swarm

name	swarm
description	Use when starting a new project or feature from an idea — orchestrates PM brainstorm, parallel planning, swarm execution, review, knowledge extraction, and PR delivery in one command
argument-hint	[your idea in one sentence]
disable-model-invocation	true

Swarm — Idea to PR Orchestrator

Takes a raw idea through 7 phases: spec, plan, build, review, learn, ship, merge. Only Phase 1 (PM) and Phase 7 (merge) need user input — everything else is automatic.

Flow

         ┌──────────────────────┐
         │  Phase 1: PM         │ ◄── interactive
         │  brainstorm → spec   │
         └──────────┬───────────┘
                    │ user confirms
                    ▼
         ┌──────────────────────┐
         │  Phase 2: Plan       │ ◄── automatic
         │  3 research agents   │
         │  → impl plan         │
         └──────────┬───────────┘
              fail? ├──► STOP
                    ▼
         ┌──────────────────────┐
         │  Phase 3: Work       │ ◄── automatic
         │  parallel workers    │
         │  worktree → merge    │
         │  test-gated batches  │
         └──────────┬───────────┘
              fail? ├──► STOP
                    ▼
         ┌──────────────────────┐
         │  Phase 4: Review     │ ◄── automatic
         │  integration check   │
         │  P1 auto-fix         │
         └──────────┬───────────┘
              fail? ├──► STOP
                    ▼
         ┌──────────────────────┐
         │  Phase 5: Compound   │ ◄── automatic
         │  abnormal data only  │
         │  extract knowledge   │
         └──────────┬───────────┘
                    ▼
         ┌──────────────────────┐
         │  Phase 6: Ship       │ ◄── automatic
         │  commit → push → PR  │
         │  test → dual review  │
         └──────────┬───────────┘
              fail? ├──► STOP
                    ▼
         ┌──────────────────────┐
         │  Phase 7: Merge      │ ◄── interactive
         │  user confirms merge │
         └──────────────────────┘

Phase 1 — PM (interactive)

Follow the /pm skill process:

1. Read $ARGUMENTS as the idea. If empty, ask: "What do you want to build?"
2. Ask clarifying questions one at a time (users, problem, MVP, out-of-scope, constraints). 3-5 questions, read the room.
3. Propose scope with tradeoffs. Let user push back.
4. Write spec to docs/specs/YYYY-MM-DD-<topic>.md using the PM spec template.
5. Show spec path + summary. Wait for explicit confirmation before proceeding.

On confirm, print: "Phase 1 complete. Starting planning..." and continue.

Phase 2 — Plan (automatic)

Follow /swarm-plan:

1. Read the spec from Phase 1.
2. Dispatch 3 agents in ONE message (all parallel, subagent_type: "Explore"):
   • Research — read ${CLAUDE_SKILL_DIR}/../../prompts/research-agent.md + append spec
   • Codebase — read ${CLAUDE_SKILL_DIR}/../../prompts/codebase-agent.md + append spec
   • Docs — read ${CLAUDE_SKILL_DIR}/../../prompts/docs-agent.md + append spec
3. Merge findings (tech stack, integration points, constraints).
4. Write plan to docs/plans/YYYY-MM-DD-<topic>.md with tasks, file paths, deps, acceptance criteria, parallelization notes.

Print: "📋 Plan ready: <plan-path>" and brief task summary. No confirmation needed — proceed.

Failure: Stop. Print which agent failed and why.

Phase 3 — Work (automatic)

Follow /swarm-work:

1. If on main/master, create feature branch: git checkout -b feat/<topic>.
2. Parse plan, build dependency graph.
3. Execute in batches (max 5 workers, each using ${CLAUDE_SKILL_DIR}/../../prompts/worker-agent.md, subagent_type: "general-purpose", isolation: "worktree", mode: "bypassPermissions").
4. After each batch:
   • Failed worker → retry once with error context. Second failure → STOP.
   • Merge worktree branches back: git merge <branch> --no-ff for each. Conflict → STOP.
   • Run tests. Fail → dispatch fix agent. Fix fails → STOP.
   • Pass → mark done, loop to next batch.
5. Print per batch: "⚡ Batch N: tasks X, Y, Z — done ✓"
6. Collect worker reports. Save any that contain Concerns (not "none") or Self-review findings (not "clean") into a list called abnormal_reports.

Failure: Stop. Report which task failed, error output, and batch state.

Phase 4 — Integration Review (automatic)

Dispatch ONE agent (subagent_type: "general-purpose") with the full git diff main...HEAD to check:

1. Naming consistency — no conflicting names for the same concept across files
2. Interface matching — functions called with correct signatures, imports resolve
3. No duplicate code — different workers didn't implement the same utility
4. No leftover TODOs — workers didn't leave unfinished markers

Triage findings:

• P1 (broken interfaces, missing imports, duplicate definitions) → auto-fix by dispatching a fix agent. Re-run tests after fix.
• P2/P3 (style inconsistencies, naming suggestions) → log as notes, continue.

Print: "🔍 Integration review: N issues found, M auto-fixed"

Failure: P1 fix agent fails → stop and report.

Phase 5 — Compound (automatic)

Only runs if abnormal_reports from Phase 3 is non-empty. If all workers completed cleanly, skip this phase.

Dispatch ONE agent (subagent_type: "general-purpose") with:

• The abnormal_reports list (concerns, retries, self-review findings)
• The integration review notes from Phase 4

Extract knowledge and write to docs/knowledge/YYYY-MM-DD-<topic>.md:

### <Pattern Name>
- **Problem:** What went wrong or was tricky
- **Solution:** What worked
- **Prevention:** How to avoid next time
- **Tags:** #tag1 #tag2

If cross-project patterns found, also write to ~/.claude/memory/patterns/.

Phase 6 — Ship (automatic)

1. Confirm on feature branch (not main). If on main somehow → STOP.
2. git add relevant files (not .env or credentials).
3. git push -u origin <branch>.
4. Check for existing PR: gh pr list --head <branch> --json number --jq '.[0].number'.
5. No PR → create: gh pr create --title "<topic>" --body "<auto-generated summary>".
6. Run tests: detect test command (package.json → npm test, Makefile → make test, etc.).
   • Tests fail → STOP. Report failures.
7. Dual review — dispatch 2 agents in parallel (subagent_type: "general-purpose"):
   • Logic reviewer — bugs, edge cases, security. Severity: CRITICAL or SUGGESTION.
   • Architecture reviewer — patterns, naming, consistency. Same severity levels.
8. Post both reviews as PR comments: gh pr comment <PR> --body "...".
9. Count CRITICALs.

Print:

🚀 PR ready: <PR URL>
🧪 Tests: all passing
🔴 CRITICALs: N

If 0 CRITICALs → proceed to Phase 7. If CRITICALs > 0 → STOP. Report critical issues. Do not proceed to merge.

Phase 7 — Merge (interactive)

Print:

✅ Swarm complete
📄 Spec: docs/specs/...
📋 Plan: docs/plans/...
📁 Files changed: N
🧪 Tests: all passing
🔍 Review: 0 criticals
🧠 Knowledge: docs/knowledge/... (or "skipped — all workers clean")
🔗 PR: <URL>

Ready to merge. Say "merge" to squash-merge and delete branch.

Wait for user to explicitly say "merge".

On merge:

gh pr merge <PR> --squash --delete-branch

Never auto-merge. Always wait for explicit user confirmation.

Error Handling

• Any phase fails → full stop. Print phase number, what failed, and why.
• Never continue to Phase N+1 if Phase N failed.
• Worker retries exhausted → stop at Phase 3. Report partial progress.
• Merge conflict → stop at Phase 3. Report conflicting files.
• Circular dependency → stop at Phase 3. Report the cycle.
• CRITICALs in review → stop at Phase 6. Report issues before merge.