diff --git a/packages/mosaic/src/constants.ts b/packages/mosaic/src/constants.ts index 22502cc..d4c00e1 100644 --- a/packages/mosaic/src/constants.ts +++ b/packages/mosaic/src/constants.ts @@ -35,4 +35,9 @@ export const RECOMMENDED_SKILLS = new Set([ 'writing-plans', 'executing-plans', 'architecture-patterns', + 'mosaic-board', + 'mosaic-forge', + 'mosaic-prdy', + 'mosaic-standards', + 'mosaic-macp', ]); diff --git a/packages/mosaic/src/skills/categories.ts b/packages/mosaic/src/skills/categories.ts index 4d10546..a549537 100644 --- a/packages/mosaic/src/skills/categories.ts +++ b/packages/mosaic/src/skills/categories.ts @@ -47,6 +47,11 @@ export const SKILL_CATEGORIES: Record = { 'using-superpowers', 'kickstart', 'executing-plans', + 'mosaic-forge', + 'mosaic-macp', + 'mosaic-setup-cicd', + 'mosaic-jarvis', + 'mosaic-standards', ], 'Testing & Quality': [ 'code-review-excellence', @@ -95,6 +100,9 @@ export const SKILL_CATEGORIES: Record = { 'skill-creator', 'writing-skills', 'prd', + 'mosaic-prd', + 'mosaic-prdy', + 'mosaic-board', ], 'Developer Practices': ['finishing-a-development-branch', 'using-git-worktrees'], 'Auth & Security': [ diff --git a/skills/mosaic-board/SKILL.md b/skills/mosaic-board/SKILL.md new file mode 100644 index 0000000..8749b16 --- /dev/null +++ b/skills/mosaic-board/SKILL.md @@ -0,0 +1,155 @@ +--- +name: mosaic-board +description: 'Run a Board of Directors review on a brief or proposal. CEO, CTO, CFO, and COO personas evaluate strategic, technical, financial, and operational viability. Use when you need a go/no-go decision, strategic review, or multi-perspective evaluation of a plan. Triggers on: board review, evaluate this brief, strategic review, go/no-go, board of directors.' +--- + +# Mosaic Board of Directors + +Run a multi-persona strategic review of a brief, proposal, or plan. Four executive personas independently evaluate, then a synthesis merges their verdicts into a single recommendation. + +--- + +## When to Use + +- Evaluating a new feature, product, or architectural decision +- Go/no-go decisions before committing resources +- Strategic review of a PRD or project brief +- Any time you want structured multi-perspective feedback + +--- + +## The Board + +| Role | Perspective | Key Question | +| ------- | ------------------------------- | ------------------------------------------ | +| **CEO** | Vision & mission alignment | "Does this serve the mission?" | +| **CTO** | Technical feasibility & risk | "Can we actually build this?" | +| **CFO** | Cost, ROI, budget impact | "What does this cost vs return?" | +| **COO** | Operations, timeline, resources | "What's the timeline and resource impact?" | + +--- + +## How It Works + +### Step 1: Identify the Brief + +The user provides a brief, PRD, proposal, or describes what they want reviewed. If no written document exists, help them articulate the key points: + +- What is being proposed? +- What problem does it solve? +- What are the success criteria? +- What are the known constraints? + +### Step 2: Run Individual Reviews + +For **each board member**, adopt their persona and evaluate the brief independently. Each review must output: + +```json +{ + "persona": "CEO|CTO|CFO|COO", + "verdict": "approve|reject|conditional", + "confidence": 0.0-1.0, + "concerns": ["specific concern 1", "specific concern 2"], + "recommendations": ["actionable recommendation 1"], + "key_risks": ["identified risk 1"] +} +``` + +**Rules for each persona:** + +- **CEO**: Focus on strategic alignment, market positioning, user value, mission fit. Ask "why should we do this?" not just "can we?" +- **CTO**: Focus on architecture implications, technical debt, integration complexity, security surface. Be realistic about build effort. +- **CFO**: Focus on cost (compute, human time, opportunity cost), ROI timeline, budget impact. Demand numbers or reasonable estimates. +- **COO**: Focus on timeline, team capacity, operational overhead, maintenance burden, deployment complexity. + +### Step 3: Synthesize + +Merge all four reviews into a board synthesis: + +- **Verdict**: `reject` if ANY member rejects. `conditional` if any member is conditional. `approve` only if all approve. +- **Confidence**: Average of all member confidence scores. +- **Concerns**: Deduplicated union of all concerns. +- **Recommendations**: Deduplicated union of all recommendations. +- **Key Risks**: Deduplicated union of all risks. + +### Step 4: Present Results + +Format the output as a readable Board Decision document: + +```markdown +# Board Decision: [Brief Title] + +## Verdict: APPROVED / CONDITIONAL / REJECTED + +**Confidence: X.XX** + +## Individual Reviews + +### CEO — [verdict] + +- Concerns: ... +- Recommendations: ... + +### CTO — [verdict] + +- Concerns: ... +- Recommendations: ... + +### CFO — [verdict] + +- Concerns: ... +- Recommendations: ... + +### COO — [verdict] + +- Concerns: ... +- Recommendations: ... + +## Synthesis + +- Combined concerns: ... +- Combined recommendations: ... +- Key risks: ... + +## Next Steps + +[Based on verdict — what should happen next] +``` + +--- + +## Standalone vs Full Pipeline + +This skill works **standalone** — you don't need the full Mosaic Stack or Forge pipeline. Just invoke `/skill:mosaic-board` with any brief or proposal. + +When used within the **Forge pipeline** (`@mosaic/forge`), the board stage is automated with parallel persona tasks and mechanical synthesis via `board-tasks.ts`. + +--- + +## Board Persona Files + +If detailed persona definitions exist at `~/.config/mosaic/forge/agents/board/`, load them for richer persona context. The personas work without these files — the role descriptions above are sufficient for standalone use. + +--- + +## Classification Shortcut + +Not every proposal needs a full board review: + +- **Strategic** (new features, architecture, integrations, security): Full board review +- **Technical** (refactors, bugfixes, UI tweaks): Skip board — go straight to implementation +- **Hotfix** (urgent patches): Skip board and analysis — just fix it + +If the user's request is clearly technical or a hotfix, suggest skipping the board review and proceeding directly. + +--- + +## Save Results + +Save the board decision to `docs/board-reviews/` or the project's `.forge/` directory: + +``` +docs/board-reviews/YYYY-MM-DD-brief-name.md +``` + +This creates an audit trail of strategic decisions. diff --git a/skills/mosaic-forge/SKILL.md b/skills/mosaic-forge/SKILL.md new file mode 100644 index 0000000..83323f6 --- /dev/null +++ b/skills/mosaic-forge/SKILL.md @@ -0,0 +1,224 @@ +--- +name: mosaic-forge +description: 'Run the Mosaic Forge specialist pipeline — teams of specialized agents that plan, build, review, and deploy software through railed stages. Use when starting a project from a brief or PRD, running a multi-stage build pipeline, or orchestrating specialist agent teams. Triggers on: forge run, forge pipeline, specialist pipeline, run the forge, build this project, forge status.' +--- + +# Mosaic Forge + +Mosaic Forge is a railed specialist pipeline that replaces ad-hoc coding with structured stages: intake → board review → planning → coding → review → test → deploy. Each stage uses purpose-built agent personas. + +--- + +## When to Use + +- Building a feature or project from a brief/PRD +- Multi-stage work that needs architecture → implementation → review +- Any task complex enough to benefit from structured planning before coding +- When you want specialist perspectives (security, data, UX) before implementation + +--- + +## Quick Start + +### From an Existing Brief + +``` +/skill:mosaic-forge run path/to/brief.md +``` + +### From a Description + +If no brief exists, the Forge intake stage will help create one: + +``` +/skill:mosaic-forge run "Build a user notification system with email and in-app channels" +``` + +### Check Status of a Run + +``` +/skill:mosaic-forge status +``` + +### Resume an Interrupted Run + +``` +/skill:mosaic-forge resume +``` + +--- + +## The Pipeline + +``` +INTAKE → DISCOVERY → BOARD → BRIEF ANALYSIS → PLANNING 1 → PLANNING 2 → PLANNING 3 → CODING → REVIEW → REMEDIATE → TEST → DEPLOY +``` + +### Stage Details + +| # | Stage | Purpose | Who | +| --- | ------------------ | ---------------------------- | ---------------------------------- | +| 00 | **Intake** | Parse and validate the brief | Mechanical | +| 00b | **Discovery** | Scan codebase for context | Codebase Scout | +| 01 | **Board** | Strategic go/no-go | CEO, CTO, CFO, COO | +| 01b | **Brief Analyzer** | Select specialist team | Sonnet agent | +| 02 | **Planning 1** | Architecture decisions | Software Architect + generalists | +| 03 | **Planning 2** | Implementation design | Language + domain specialists | +| 04 | **Planning 3** | Task decomposition | Context Manager + Task Distributor | +| 05 | **Coding** | Write the code | Codex/Claude workers | +| 06 | **Review** | Evidence-driven review | Code reviewer + Security auditor | +| 07 | **Remediate** | Fix review findings | Workers | +| 08 | **Test** | Acceptance validation | QA Strategist | +| 09 | **Deploy** | Ship it | Infrastructure Lead | + +### Brief Classification (Skip Stages) + +Not every brief needs every stage: + +| Class | Skips | Use When | +| ----------- | ----------------------- | ---------------------------------------- | +| `strategic` | Nothing — full pipeline | New features, architecture, integrations | +| `technical` | Board review | Refactors, bugfixes, UI tweaks | +| `hotfix` | Board + Brief Analyzer | Urgent patches | + +Classification is automatic (keyword analysis) but can be overridden: + +- YAML frontmatter in the brief: `class: technical` +- CLI flag: `--class hotfix` +- Force board: `--force-board` on any class + +--- + +## Standalone Mode + +Forge works **without the full Mosaic Stack**. In standalone mode: + +1. **You are the orchestrator** — advance through stages manually +2. **Each stage is a conversation turn** — the agent adopts the stage's specialist persona(s) +3. **Gates are checkpoints** — you decide when a stage passes + +### Running Standalone + +When invoked via `/skill:mosaic-forge`, run stages sequentially in the current session: + +1. **Read the brief** — understand what's being built +2. **Discovery** — scan the codebase (`find`, `grep`, read key files) to build context +3. **Board Review** (if strategic) — run `/skill:mosaic-board` or do inline board evaluation +4. **Planning 1** — propose architecture, debate trade-offs, produce an ADR +5. **Planning 2** — detail implementation specs per component +6. **Planning 3** — break into tasks with dependencies, estimates, acceptance criteria +7. **Coding** — implement each task +8. **Review** — self-review with evidence (grep for issues, check patterns) +9. **Remediate** — fix anything found in review +10. **Test** — run tests, verify acceptance criteria +11. **Deploy** — if applicable + +### Gate Checks Per Stage + +After each stage, verify before advancing: + +- **Board → Planning**: Brief approved, concerns addressed +- **Planning 1 → 2**: ADR exists, covers all components +- **Planning 2 → 3**: Impl specs per component, no conflicts +- **Planning 3 → Coding**: Tasks have owners, criteria, estimates +- **Coding → Review**: Compiles, lints, unit tests pass +- **Review → Test**: All findings addressed +- **Test → Deploy**: Acceptance criteria pass + +--- + +## Full Pipeline Mode (Mosaic Stack) + +When the full `@mosaic/forge` package is available, Forge uses MACP task execution: + +```bash +# Run from CLI +mosaic forge run path/to/brief.md + +# Resume interrupted run +mosaic forge resume .forge/runs/20260401-143022/ + +# Check status +mosaic forge status .forge/runs/20260401-143022/ +``` + +Pipeline runs are tracked in `.forge/runs/{runId}/manifest.json`. + +--- + +## Agent Roster + +### Board (Static) + +CEO, CTO, CFO, COO — see `/skill:mosaic-board` + +### Generalists (Dynamic per brief) + +- **Software Architect** — system design, boundaries, API contracts +- **Security Architect** — threat modeling, auth, OWASP (always included) +- **Infrastructure Lead** — deploy, networking, scaling +- **Data Architect** — schema, migrations, query strategy +- **QA Strategist** — test strategy, coverage +- **UX Strategist** — user flows, accessibility + +### Language Specialists (Dynamic) + +TypeScript, JavaScript, Go, Rust, Solidity, Python, SQL + +### Domain Specialists (Dynamic) + +NestJS, React, Docker, CI/CD, Web Design, UX/UI, Kubernetes, AWS, Cloudflare, Proxmox, Portainer, DevOps, Ceph + +--- + +## Debate Protocol + +Planning stages use structured debate, not rubber-stamping: + +1. **Independent positions** — each specialist states their position with reasoning +2. **Responses** — specialists challenge each other's positions +3. **Synthesis** — resolve disagreements, record dissents + +Agents must argue, not agree. Premature consensus produces bad architecture. + +--- + +## Artifacts + +Each Forge run produces: + +``` +.forge/runs/{runId}/ +├── manifest.json # Run state and stage statuses +├── 00-intake/brief.md # Validated brief +├── 00b-discovery/ # Codebase context +├── 01-board/ # Board reviews + synthesis +├── 02-planning-1/ # Architecture Decision Record +├── 03-planning-2/ # Implementation specs +├── 04-planning-3/ # Task breakdown +├── 05-coding/ # Implementation output +├── 06-review/ # Review findings +├── 07-remediate/ # Fix log +├── 08-test/ # Test results +└── 09-deploy/ # Deploy log +``` + +--- + +## Project Configuration + +Optional `.forge/config.yaml` in the project root: + +```yaml +board: + skipMembers: + - cfo # Skip CFO for internal tools + additionalMembers: + - legal # Add legal review for compliance projects + +specialists: + alwaysInclude: + - security-architect +``` + +Optional `.forge/personas/` for project-specific persona overrides (appended to base personas). diff --git a/skills/jarvis/SKILL.md b/skills/mosaic-jarvis/SKILL.md similarity index 99% rename from skills/jarvis/SKILL.md rename to skills/mosaic-jarvis/SKILL.md index 3911772..5e7e223 100644 --- a/skills/jarvis/SKILL.md +++ b/skills/mosaic-jarvis/SKILL.md @@ -1,5 +1,5 @@ --- -name: jarvis +name: mosaic-jarvis description: 'Jarvis Platform development context. Use when working on the jetrich/jarvis repository. Provides architecture knowledge, coding patterns, and component locations.' --- diff --git a/skills/macp/SKILL.md b/skills/mosaic-macp/SKILL.md similarity index 98% rename from skills/macp/SKILL.md rename to skills/mosaic-macp/SKILL.md index 6cfecbc..8b2f085 100644 --- a/skills/macp/SKILL.md +++ b/skills/mosaic-macp/SKILL.md @@ -1,5 +1,5 @@ --- -name: macp +name: mosaic-macp description: Manage MACP tasks — submit, check status, view history, and drain queues. Use when orchestrating coding tasks via the Mosaic Agent Coordination Protocol. --- diff --git a/skills/prd/SKILL.md b/skills/mosaic-prd/SKILL.md similarity index 99% rename from skills/prd/SKILL.md rename to skills/mosaic-prd/SKILL.md index bba4f3d..818b99a 100644 --- a/skills/prd/SKILL.md +++ b/skills/mosaic-prd/SKILL.md @@ -1,5 +1,5 @@ --- -name: prd +name: mosaic-prd description: 'Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out.' --- diff --git a/skills/mosaic-prdy/SKILL.md b/skills/mosaic-prdy/SKILL.md new file mode 100644 index 0000000..f93e00b --- /dev/null +++ b/skills/mosaic-prdy/SKILL.md @@ -0,0 +1,275 @@ +--- +name: mosaic-prdy +description: 'Create, update, validate, and manage Product Requirements Documents (PRDs) using the Mosaic PRDy system. Use when planning features, writing requirements, validating PRDs against standards, or checking PRD status. Triggers on: create a prd, write prd, prdy init, prdy validate, plan this feature, requirements document, spec out.' +--- + +# Mosaic PRDy + +PRDy is Mosaic's PRD (Product Requirements Document) lifecycle manager. Create structured PRDs from templates, validate them against quality standards, and track their status through draft → review → approved → archived. + +--- + +## Commands + +### Initialize a New PRD + +``` +/skill:mosaic-prdy init --name "Feature Name" +``` + +Or describe what you want to build and PRDy will guide you through it: + +``` +/skill:mosaic-prdy init "Build a notification system with email and in-app channels" +``` + +### Update an Existing PRD + +``` +/skill:mosaic-prdy update +``` + +Scans the project for existing PRDs and offers to update sections. + +### Validate a PRD + +``` +/skill:mosaic-prdy validate +``` + +Checks all PRDs against Mosaic quality standards: + +- Required sections present +- Acceptance criteria are specific and verifiable +- Non-goals defined +- Success metrics measurable + +### Check Status + +``` +/skill:mosaic-prdy status +``` + +Lists all PRDs in the project with their current status. + +--- + +## The Job + +### Step 1: Clarifying Questions + +Ask 3-5 essential questions with lettered options (user responds "1A, 2C, 3B"): + +``` +1. What is the primary goal? + A. Improve user experience + B. Increase retention + C. Reduce support burden + D. Other: [specify] + +2. Who is the target user? + A. New users only + B. All users + C. Admin users + D. Other: [specify] + +3. What is the scope? + A. Minimal viable version + B. Full-featured + C. Backend/API only + D. UI only +``` + +### Step 2: Generate PRD + +Using the Mosaic PRD template with these required sections: + +1. **Introduction/Overview** — problem statement and what this solves +2. **Goals** — specific, measurable objectives +3. **User Stories** — with acceptance criteria (see format below) +4. **Functional Requirements** — numbered (FR-1, FR-2, ...) +5. **Non-Functional Requirements** — security, performance, reliability, observability +6. **Non-Goals (Out of Scope)** — explicit boundaries +7. **Design Considerations** — UI/UX, mockups, reusable components +8. **Technical Considerations** — constraints, dependencies, integrations +9. **Success Metrics** — measurable outcomes +10. **Open Questions** — unresolved items + +### Step 3: Save + +Save to `tasks/prd-[feature-name].md` (kebab-case). + +--- + +## User Story Format + +Each story must be small enough to implement in one focused session: + +```markdown +### US-001: [Title] + +**Description:** As a [user], I want [feature] so that [benefit]. + +**Acceptance Criteria:** + +- [ ] Specific verifiable criterion (not "works correctly") +- [ ] Another criterion with measurable outcome +- [ ] Typecheck/lint passes +- [ ] **[UI stories]** Verify in browser using dev-browser skill +``` + +**Rules:** + +- Acceptance criteria must be verifiable, not vague +- "Button shows confirmation dialog before deleting" ✅ +- "Works correctly" ❌ +- UI stories always include browser verification +- Each story gets a unique ID (US-001, US-002, ...) + +--- + +## PRD Lifecycle + +``` +draft → review → approved → archived +``` + +| Status | Meaning | +| ---------- | ---------------------------------------------- | +| `draft` | Work in progress, not ready for implementation | +| `review` | Ready for stakeholder review | +| `approved` | Approved for implementation — the contract | +| `archived` | Completed or abandoned | + +**Key rule:** Implementation that diverges from an approved PRD without updating the PRD first is a blocker. Change control: update PRD → update plan → then implement. + +--- + +## Templates + +PRDy ships with built-in templates: + +| Template | Use When | +| ---------------- | ----------------------------------- | +| `feature` | New feature or capability (default) | +| `integration` | Third-party integration or API | +| `infrastructure` | DevOps, deployment, scaling | +| `refactor` | Technical debt, architecture change | + +Specify a template: + +``` +/skill:mosaic-prdy init --name "Auth Integration" --template integration +``` + +--- + +## Validation Rules + +`/skill:mosaic-prdy validate` checks: + +- [ ] Has introduction/overview +- [ ] Has at least one goal +- [ ] Has at least one user story with acceptance criteria +- [ ] Functional requirements are numbered +- [ ] Non-goals section exists and is non-empty +- [ ] Acceptance criteria are specific (flags vague terms: "works correctly", "handles properly", "is fast") +- [ ] Success metrics are measurable +- [ ] No TODO/TBD markers in approved PRDs + +--- + +## Integration with Forge + +When used with Mosaic Forge (`/skill:mosaic-forge`): + +1. PRDy creates the PRD (this skill) +2. Forge decomposes the PRD into briefs +3. Board reviews each brief +4. Pipeline builds each brief through specialist stages + +PRDy is the **input** to the Forge pipeline. A well-written PRD means less rework in planning stages. + +--- + +## Standalone CLI + +If the `mosaic` CLI is available: + +```bash +mosaic prdy init --name "Feature Name" +mosaic prdy update +mosaic prdy validate +mosaic prdy status + +# With runtime selection +mosaic prdy --pi init --name "Feature Name" +mosaic prdy --claude init --name "Feature Name" +``` + +--- + +## Writing for Junior Developers + +PRDs may be read by junior developers or AI agents. Therefore: + +- Be explicit and unambiguous +- Avoid jargon or explain it +- Provide enough detail to understand purpose and core logic +- Number requirements for easy reference +- Use concrete examples where helpful + +--- + +## Example + +```markdown +# PRD: Task Priority System + +## Introduction + +Add priority levels to tasks so users can focus on what matters most. + +## Goals + +- Allow assigning priority (high/medium/low) to any task +- Provide clear visual differentiation between priority levels +- Enable filtering and sorting by priority + +## User Stories + +### US-001: Add priority field to database + +**Description:** As a developer, I need to store task priority persistently. +**Acceptance Criteria:** + +- [ ] Add priority column: 'high' | 'medium' | 'low' (default 'medium') +- [ ] Migration runs successfully +- [ ] Typecheck passes + +### US-002: Display priority indicator + +**Description:** As a user, I want to see task priority at a glance. +**Acceptance Criteria:** + +- [ ] Colored badge: red=high, yellow=medium, gray=low +- [ ] Priority visible without hovering +- [ ] Verify in browser + +## Functional Requirements + +- FR-1: Add `priority` field ('high'|'medium'|'low', default 'medium') +- FR-2: Display colored priority badge on each task card +- FR-3: Priority filter dropdown in task list header + +## Non-Goals + +- No priority-based notifications +- No automatic priority assignment +- No priority inheritance for subtasks + +## Success Metrics + +- Users can change priority in under 2 clicks +- High-priority tasks visible at top of lists +``` diff --git a/skills/setup-cicd/SKILL.md b/skills/mosaic-setup-cicd/SKILL.md similarity index 99% rename from skills/setup-cicd/SKILL.md rename to skills/mosaic-setup-cicd/SKILL.md index 268e035..1de15e1 100644 --- a/skills/setup-cicd/SKILL.md +++ b/skills/mosaic-setup-cicd/SKILL.md @@ -1,5 +1,5 @@ --- -name: setup-cicd +name: mosaic-setup-cicd description: 'Configure CI/CD Docker build, push, and package linking for a project. Use when adding Docker builds to a Woodpecker pipeline, setting up Gitea container registry, or implementing CI/CD for deployment. Triggers on: setup cicd, add docker builds, configure pipeline, add ci/cd, setup ci.' ---