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