Skip to content

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

  1. Explore — Launch 3-6 worker-explorer agents to research existing patterns, dependencies, constraints, and prior art
  2. Classify — Determine decision reversibility (Two-Way Door vs One-Way Door)
  3. Document — Create appropriate artifacts based on scope
  4. 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
  5. 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 — Requirements
  • docs/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 value
  • docs/prd/PRD-<feature>.md — Detailed requirements
  • docs/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 sequenceDiagram blocks 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 (/spec writes 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) and mkdocs.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 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 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 main on its own; a dependent unit branches from main after its prerequisite lands

Output

Every planning session MUST produce:

  1. Artifact(s) in docs/ following naming conventions (including docs/sequence/sequence-<feature>.md when the feature has a PRD)
  2. Tasks (via TaskCreate) for all implementation work, each with acceptance criteria
    • This repo: also add a ## Feature: <name> section to TASKS.md with one - [ ] **<ID>** line per task (the native list is machine-local; TASKS.md is the durable record). If TaskCreate is unavailable, TASKS.md + the plan's task table are the record.
  3. Dependency graph showing task order (via blockedBy)
  4. 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

  1. Understand — Map existing system with Grep and Glob
  2. Reason — Enumerate constraints and evaluate options
  3. Design — Create ADR with trade-off matrix
  4. Validate — Verify design fits existing patterns

swarm-coordination, writing-adrs, designing-systems, planning-artifacts

Handoff

  • To /swarm-execute: Plan artifact + task list ready
  • To /architect: Complex decisions requiring ADR review