swarm-plan

Planning Orchestrator

Decompose features into actionable plans using parallel exploration swarms.

MCP Tools

Sequential Thinking (structured analysis):

Complex requirement decomposition
Trade-off evaluation for approach selection
Risk assessment for implementation choices

Context7 (library research):

Research existing patterns in libraries
Validate technology choices from Tech Strategy

Planning Workflow

Explore — Launch 3-6 worker-explorer agents to research existing patterns, dependencies, constraints, and prior art
Classify — Determine decision reversibility (Two-Way Door vs One-Way Door)
Document — Create appropriate artifacts based on scope
Decompose — Break into right-sized tasks: roughly 200-400 changed LOC or 15-45 minutes of focused work each — review effectiveness collapses beyond ~400 LOC (SmartBear/Cisco). Shape every unit to be independently mergeable to main (trunk-based, per core-directives): dependencies resolve by merge order, not by stacking branches
Track — Record tasks in the native task list for implementation tracking

Decision Framework

Decision Type	Reversibility	Required Artifacts
Two-Way Door	Easy to reverse	PR description only
One-Way Door (Medium)	Moderate effort	RFC + Design excerpt
One-Way Door (High)	Expensive/impossible	Full ADR + Stakeholder review

Artifact Requirements

Small Feature (1-3 days)

plan_[feature].md — Implementation steps only

Medium Feature (1-2 weeks)

prd_[feature].md — Requirements
plan_[feature].md — Implementation steps

Large Feature (2+ weeks)

pr_faq_[feature].md — Vision and customer value
prd_[feature].md — Detailed requirements
adr_[key-decision].md — Architectural decisions (format: writing-adrs skill; template bundled with designing-systems at resources/adr.template.md)
plan_[feature].md — Implementation steps

Worker Types

Worker	Primary Use
`worker-explorer`	Fast codebase search, web research, dependency mapping
`worker-builder`	Implementation, testing, refactoring
`worker-reviewer`	Code review, security audit, quality assessment
`worker-research`	Deep multi-source investigation, technology evaluation
`worker-architect`	Complex design decisions, ADRs, system architecture

Model tiers are pinned in each agent's frontmatter (.claude/agents/) — that is the single source of truth.

Swarm Patterns

Parallel Exploration

Orchestrator spawns 4-8 worker-explorer agents simultaneously
Each searches different parts of codebase
Results aggregated for next phase

Divide and Conquer

1. worker-architect designs solution
2. Orchestrator decomposes into N tasks
3. N worker-builder agents execute in parallel
4. worker-reviewer validates each output
5. Orchestrator integrates

Security Sweep

worker-reviewer (focus: security) scans all components in parallel
Findings aggregated and prioritized
worker-builder fixes critical/high issues

Parallel Exploration Pattern

# Launch exploration workers in parallel via Task tool
# Each worker focuses on one aspect:
# - Existing patterns in codebase
# - External dependencies and APIs
# - Security and performance constraints
# - Related ADRs and design specs

Task Creation

Use TaskCreate to record implementation tasks, each with clear acceptance criteria:

TaskCreate — "Implement [feature]" (epic-level task)
TaskCreate — "[Task 1: Foundation]" with acceptance criteria
TaskCreate — "[Task 2: Core Logic]" with acceptance criteria

Link dependencies with TaskUpdate (addBlockedBy): Task 2 gets Task 1 added to its blockedBy list so it can't start until Task 1 completes.

Performance Tips

Launch multiple explorers for broad searches
Use worker-architect for decisions, worker-builder for execution
Parallelize independent tasks (max 8 concurrent workers)
For large dispatch batches, declare a token/wave ceiling up front — see swarm-coordination's Budget & Waves section
Keep worker prompts under 500 tokens for fast startup

Constraints

NO skipping artifact creation for features > 3 days
NO creating tasks without clear acceptance criteria
NO assuming context — explore codebase first
ALWAYS use parallel workers for research phase
ALWAYS store artifacts in ./artifacts/
ALWAYS record implementation tasks with acceptance criteria before declaring planning complete
ALWAYS validate arguments before using in commands
NO plans that require stacked PR chains or integration branches — every planned unit merges to main on its own; a dependent unit branches from main after its prerequisite lands

Output

Every planning session MUST produce:

Artifact(s) in ./artifacts/ following naming conventions
Tasks (via TaskCreate) for all implementation work, each with acceptance criteria
Dependency graph showing task order (via blockedBy)
Handoff summary for /execute command

Product Planning

PR-FAQ

Use planning-artifacts skill for structure and template.

PRD