stack/skills/mosaic-forge/SKILL.md

name, description

name	description
mosaic-forge	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 @mosaicstack/forge package is available, Forge uses MACP task execution:

# 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:

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).