2ee7206c3a
Skills: - Rename all repo skills to mosaic-<name> convention (jarvis -> mosaic-jarvis, etc.) - Update frontmatter name: fields to match directory names - New mosaic-board skill: standalone Board of Directors multi-persona review - New mosaic-forge skill: standalone Forge specialist pipeline - New mosaic-prdy skill: PRD lifecycle (init/update/validate/status) Wizard (packages/mosaic): - Add mosaic-board, mosaic-forge, mosaic-prdy, mosaic-standards, mosaic-macp to RECOMMENDED_SKILLS - Add new skills to SKILL_CATEGORIES for categorized browsing Framework scripts (~/.config/mosaic/bin): - mosaic (launcher): load skills from both skills/ and skills-local/ for Pi - mosaic-doctor: add --fix flag for auto-wiring skills into all harnesses, Pi skill dir checks, Pi settings.json validation, mosaic-* presence checks - mosaic-sync-skills: add Pi as 4th link target, fix find to follow symlinks in skills-local/, harden is_mosaic_skill_name() with -L fallback - mosaic-link-runtime-assets: add Pi settings.json skills path patching, remove duplicate extension copy (launcher --extension is single source) - mosaic-migrate-local-skills: add Pi to skill_roots, fix find for symlinks YAML fixes: - Quote description values containing colons in mosaic-deploy and mosaic-woodpecker SKILL.md frontmatter (fixes Pi parse errors)
225 lines
7.7 KiB
Markdown
225 lines
7.7 KiB
Markdown
---
|
|
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).
|