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¶
Two independent axes: PRD/PR-FAQ scale with feature size; an ADR is triggered by the decision type, at any size.
Small Feature (1-3 days)
docs/plans/plan-<feature>.md— Implementation steps only
Medium Feature (1-2 weeks)
docs/prd/PRD-<feature>.md— Requirementsdocs/sequence/sequence-<feature>.md— Mermaid sequence diagrams (see below)docs/plans/plan-<feature>.md— Implementation steps
Large Feature (2+ weeks)
docs/prd/PR-FAQ-<feature>.md— Vision and customer valuedocs/prd/PRD-<feature>.md— Detailed requirementsdocs/sequence/sequence-<feature>.md— Mermaid sequence diagrams (see below)docs/plans/plan-<feature>.md— Implementation steps
ADR — any size (docs/adr/NNNN-<topic>.md; format: writing-adrs skill; template bundled with designing-systems at resources/adr.template.md)
- Required when the work contains a One-Way Door (High) decision (Decision Framework above), or a decision on the
writing-adrs"When to Write an ADR" list (framework/library, database or storage, a new API pattern, a coding convention, infrastructure, anything affecting multiple components) - One-Way Door (Medium) decisions: record the RFC/design excerpt in the plan's design section instead of a separate ADR
- Following an existing pattern (another endpoint, another Liquibase column) is not a new decision and needs no ADR
Sequence diagrams — every feature with a PRD (docs/sequence/sequence-<feature>.md, slug = PRD slug; template templates/artifacts/sequence.template.md)
- Mermaid
sequenceDiagramblocks only (mkdocs renders them); one diagram per main flow: happy path first, then the failure, async/event and scheduled-job paths that matter - Participants are real names from the code or the ADR/spec (page/hook, controller, service, repository, external system)
- Write it before the plan (
/specwrites it when it runs; otherwise this skill does). If it is missing, create it as part of planning. Plan tasks cite it in the plan's architecture section - Small features without a PRD need none. When the as-built flow changes, update the diagram in the same commit as the code
- Link it from
docs/tracking.md(Sequence column) andmkdocs.yml(nav "Sequence Diagrams")
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 criteriaTaskCreate— "[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
docs/ - 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
mainon its own; a dependent unit branches frommainafter its prerequisite lands
Output¶
Every planning session MUST produce:
- Artifact(s) in
docs/following naming conventions (includingdocs/sequence/sequence-<feature>.mdwhen the feature has a PRD) - Tasks (via
TaskCreate) for all implementation work, each with acceptance criteria- This repo: also add a
## Feature: <name>section toTASKS.mdwith one- [ ] **<ID>**line per task (the native list is machine-local;TASKS.mdis the durable record). IfTaskCreateis unavailable,TASKS.md+ the plan's task table are the record.
- This repo: also add a
- 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¶
Use planning-artifacts skill for structure and template.
Architecture Design Process¶
- Understand — Map existing system with Grep and Glob
- Reason — Enumerate constraints and evaluate options
- Design — Create ADR with trade-off matrix
- Validate — Verify design fits existing patterns
Related Skills¶
swarm-coordination, writing-adrs, designing-systems, planning-artifacts
Handoff¶
- To
/swarm-execute: Plan artifact + task list ready - To
/architect: Complex decisions requiring ADR review