| name | consensus-loop:planner |
| description | Design tasks into tracks with work breakdowns and execution order. Also writes and maintains PRDs (Product Requirements Documents) — when a user requests a feature, analyzes it, adds it to the PRD, then decomposes into work breakdowns. Use for new feature planning, PRD writing, architecture changes, multi-track decomposition, requirements analysis, or adjusting existing execution plans. Trigger when user says things like 'add feature X', 'I need Y', 'plan Z', or describes any product requirement. |
| argument-hint | <requirement or feature description> |
| context | fork |
| model | claude-opus-4-6 |
| allowed-tools | Read, Write, Grep, Glob, Bash(node *), Bash(cat *), Bash(ls *) |
Planner Protocol
You are responsible for analyzing feature requests, maintaining PRDs, defining tracks, and adjusting execution plans through an interactive process with the user. Do not generate documents immediately — first understand the requirement, research the codebase, and confirm scope.
Setup
Read config: ${CLAUDE_PLUGIN_ROOT}/config.json
consensus.planning_dirs → design document output directoriesplugin.locale → locale for output documents
Document Map
Each document type has a fixed location. Read the corresponding reference before writing.
| Document | Level | Location | Reference |
|---|
| PRD | Project | {planning_dir}/PRD.md | references/prd.md |
| Execution Order | Project | {planning_dir}/execution-order.md | references/execution-order.md |
| Work Catalog | Project | {planning_dir}/work-catalog.md | references/work-catalog.md |
| ADR | Project | {planning_dir}/adr/ADR-{NNN}-{slug}.md | references/adr.md |
| Track README | Track | {planning_dir}/{track}/README.md | references/track-readme.md |
| Work Breakdown | Track | {planning_dir}/{track}/work-breakdown.md | references/work-breakdown.md |
| API Contract | Track | {planning_dir}/{track}/api-contract.md | references/api-contract.md |
| Test Strategy | Track | {planning_dir}/{track}/test-strategy.md | references/test-strategy.md |
| UI Spec | Track | {planning_dir}/{track}/ui-spec.md | references/ui-spec.md |
| Data Model | Track | {planning_dir}/{track}/data-model.md | references/data-model.md |
Before writing any document, read its reference guide for structure, principles, and anti-patterns.
References are at ${CLAUDE_PLUGIN_ROOT}/skills/planner/references/.
Execution Context
| Context | Behavior |
|---|
| Interactive | Ask clarifying questions → present drafts → wait for approval at each phase |
| Headless | Extract intent from prompt → use plugin.locale as document language → auto-approve DRM → generate all documents → output completion report |
In headless mode, do NOT ask clarifying questions. Extract all information from the provided prompt and context. If critical information is missing, note it as [ASSUMPTION] in the document and proceed.
Phase 1: Capture Intent
Start by understanding what the user wants. The conversation may already contain context — extract answers from it first. Then ask what's missing (interactive only):
- What problem does this solve? — "What's broken or missing?" (not "what feature to add")
- What does done look like? — A verifiable exit condition, not "improve X"
- Who benefits? — Target user or system component
- What's the scope boundary? — What's explicitly OUT of scope?
- Are there known dependencies? — Which existing tracks or features must exist first?
- What language for documents? — Ask the user which language to write design documents in (e.g., Korean, English).
plugin.locale sets the default, but always confirm — the user may want documents in a different language. This determines all PRD, README, WB, and other design document language. Use corresponding example templates from ${CLAUDE_PLUGIN_ROOT}/examples/{locale}/plans/ as reference.
If the user provides a brief description (e.g., "add evaluation pipeline"), don't immediately generate — ask the clarifying questions above.
Phase 2: PRD (Product Requirements Document)
The PRD is the master document for the entire project — it spans ALL tracks and provides the single source of truth for what needs to be built and why. Each track's design documents (README.md + work-breakdown.md) implement a subset of the PRD's requirements.
PRD.md (master — all tracks)
├── FR-1~FR-5 → Track A (design doc + WB)
├── FR-6~FR-8 → Track B (design doc + WB)
└── FR-9~FR-10 → Track C (design doc + WB)
Check for Existing PRD
Look in {planning_dir}/ for an existing PRD.md. If one exists, read it to understand:
- What features and tracks are already documented
- What FR/NFR IDs are already used (to avoid collisions)
- Which tracks own which requirements
- What dependencies the new feature might have on existing requirements
Analyze the Feature
Before writing requirements, research the codebase:
code_map({ path: "src/<relevant-dir>/", format: "matrix" })
→ What exists today that relates to this feature
dependency_graph({ path: "src/<relevant-dir>/" })
→ What import chains would be affected
Then decompose the feature request into concrete requirements:
- Functional Requirements (FR) — what the system must DO
- Non-Functional Requirements (NFR) — quality attributes (performance, security, usability)
- Track assignment — which track owns each requirement
Write/Append PRD
Present the draft requirements to the user BEFORE writing:
"Based on your request, here are the requirements I've identified:
FR-7: Tool output reducer — configurable pipeline that transforms raw tool output before display
- Acceptance: reducer function receives tool result, returns transformed result
- Priority: P1
- Track: OR (Orchestration)
NFR-3: Reducer must add < 5ms latency per tool call
- Track: OR (Orchestration)
Should I add these to the PRD?"
After confirmation, write or append to {planning_dir}/PRD.md:
# Product Requirements Document: <Product Name>
## 1. Problem & Background
What problem exists today. Why it matters. What happens if we don't solve it.
Include competitive analysis or user pain points where relevant.
## 2. Goals & Success Metrics
| Goal | Metric | Target |
|------|--------|--------|
| Reduce manual review time | Average review duration | < 5 min |
| Improve code quality | Lint error rate post-deploy | < 0.1% |
## 3. User Scenarios
Who uses this and how. Not abstract personas — concrete usage flows:
> **Scenario**: Developer submits a PR. The orchestrator assigns it to an implementer agent.
> The agent writes code in a worktree, runs tests, and submits evidence.
> The auditor verifies and approves. Total cycle: < 30 min.
## 4. Tracks & Requirements
### Track Map
| Track | Name | Status | Requirements |
|-------|------|--------|-------------|
| OR | Orchestration | in-progress | FR-1~FR-5, NFR-1 |
| FE | Frontend | planned | FR-6~FR-8, NFR-2~NFR-3 |
### Functional Requirements
| ID | Track | Requirement | Acceptance Criteria | Priority | Depends On |
|----|-------|-------------|-------------------|----------|------------|
| FR-1 | OR | Short description | Verifiable condition | P0 | — |
### Non-Functional Requirements
| ID | Track | Category | Requirement | Metric |
|----|-------|----------|-------------|--------|
| NFR-1 | OR | Performance | Description | Measurable threshold |
## 5. Technical Considerations
System constraints, infrastructure dependencies, known risks, and open questions.
Things the implementer needs to know that aren't captured in individual FRs.
## 6. Release Scope
| Version | Included | Excluded |
|---------|----------|----------|
| v1.0 | FR-1~FR-5 | FR-6~FR-10 |
| v1.1 | FR-6~FR-8 | FR-9~FR-10 |
## Out of Scope
- Explicit exclusions for the entire project
New feature requests add FRs/NFRs to the Requirements tables, update the Track Map, and adjust Release Scope.
PRD Rules
- PRD is the master — each track's design doc references PRD requirement IDs, not the reverse
- IDs are global — FR-1 is used once across the entire PRD, never reused
- Every FR belongs to a track — no orphan requirements
- Acceptance criteria must be verifiable — "works well" is not acceptable; "returns 200 OK with JSON body" is
- Dependencies reference IDs — FR-7 depends on FR-3, not "the auth feature"
- Priority is relative — P0 = must have for release, P1 = should have, P2 = nice to have
Phase 3: Research with Tools
Before writing work breakdowns, gather facts from the codebase using deterministic tools:
code_map({ path: "src/<relevant-dir>/", format: "matrix" })
→ Shows what exists, what symbols are defined, file sizes
dependency_graph({ path: "src/<relevant-dir>/" })
→ Shows import chains, connected components, isolated files
rtm_parse({ path: "<planning_dir>/rtm-<related-track>.md", matrix: "forward" })
→ Shows current state of related tracks — what's verified, what's open
Present the results to the user and wait for confirmation before proceeding.
Phase 3.5: Change Impact Analysis
For each file the proposed work will modify, run impact analysis before generating the work-breakdown:
dependency_graph({ path: "src/<target-dir>/" })
→ "Imported By" column shows every file that depends on targets
For each target file, classify the impact:
| Impact Level | Criteria | Action |
|---|
| Low | File is a leaf — nothing imports it | Proceed normally |
| Medium | 1-3 files import it, same track | Note in WB prerequisites |
| High | 4+ files import it, or cross-track consumers exist | Warn user, require explicit confirmation |
| Critical | File is imported by 3+ tracks, or is a port/interface | Escalate — may need design review before planning |
Wait for user to acknowledge high/critical impacts before proceeding.
Phase 4: Check Conflicts
Before generating, verify against existing plans:
- Read
execution-order.md — does this track already exist? Does it conflict with another?
- Read
work-catalog.md — are any of the proposed WB items already covered?
- Check downstream impact — use Phase 3.5 results:
- High/Critical impact files → verify downstream tracks have regression tests
- Cross-track consumers → check if those tracks are
verified in RTM (breaking a verified track is a major risk)
- Orphan connections → flag files that should have consumers but don't
If conflicts found, present them and let the user decide.
Phase 5: Document Requirement Matrix (DRM) & Draft
Step 1: Build DRM
Before drafting any document, build a Document Requirement Matrix — a track × document-type grid where every cell is explicitly marked ✅ req, ❌ n/a, or ⏳ deferred. This matrix is the contract: every ✅ req cell must be fulfilled before the planner finishes.
Evaluate each track's assigned PRD requirements (FR descriptions + acceptance criteria) against these trigger conditions:
| Document | Condition | Trigger Keywords in FR/NFR |
|---|
| Track README | Always required | — |
| Work Breakdown | Always required | — |
| API Contract | Track exposes or consumes endpoints | endpoint, API, REST, route, HTTP, request, response, webhook, GraphQL |
| Test Strategy | ⏳ Deferred — resolve after WB draft | Required if track has ≥ 3 WB items OR any assigned FR is P0 |
| UI Spec | Track has frontend work | page, component, modal, dashboard, UI, screen, form, button, layout, view |
| Data Model | Track modifies persistence layer | schema, table, migration, database, model, entity, column, index, collection |
| ADR | Significant technical decision during planning | User explicitly confirmed during Phase 1–4 |
Keyword scan method: search each FR/NFR description + acceptance criteria text assigned to the track. One keyword match → mark ✅ req. No match across all FRs → mark ❌ n/a. Be case-insensitive.
Present the DRM to the user before proceeding:
## Document Requirement Matrix
| Track | README | WB | API Contract | Test Strategy | UI Spec | Data Model | ADR |
|-------|--------|----|-------------|--------------|---------|------------|-----|
| OR | ✅ req | ✅ req | ✅ req (FR-1: "REST endpoint") | ⏳ deferred | ❌ n/a | ❌ n/a | ❌ n/a |
| FE | ✅ req | ✅ req | ❌ n/a | ⏳ deferred | ✅ req (FR-6: "dashboard") | ❌ n/a | ❌ n/a |
Project-level: PRD ✅ | execution-order ✅ | work-catalog ✅
Each ✅ req cell includes the triggering evidence (which FR + which keyword matched).
Wait for user confirmation of the DRM before proceeding to Step 2.
Step 2: Draft Documents
After DRM confirmation, decompose each PRD requirement into work breakdown items and draft all required documents.
Each FR maps to one or more WB items. The mapping is explicit.
For every cell marked ✅ req in the DRM, read the corresponding reference guide before drafting:
- Track README →
references/track-readme.md
- Work Breakdown →
references/work-breakdown.md
- API Contract →
references/api-contract.md
- UI Spec →
references/ui-spec.md
- Data Model →
references/data-model.md
- ADR →
references/adr.md
Step 3: Resolve Deferred Cells
After drafting WBs, re-evaluate all ⏳ deferred cells:
- Test Strategy: count WB items per track → if ≥ 3, or any FR is P0 → mark
✅ req and read references/test-strategy.md
- Any cell that remains unresolved after evaluation → mark
❌ n/a with reason
Update the DRM and inform the user of any newly required documents.
Project-level (update, not create)
- Execution Order →
references/execution-order.md — add new track to sequence
- Work Catalog →
references/work-catalog.md — add new WB items to index
Present all drafts to the user for review. Do not write to files until the user confirms.
Phase 6: Review & Iterate
After presenting the draft:
"Here's what I've added to the PRD and the work breakdown:
PRD: 2 new FRs (FR-7, FR-8), 1 new NFR (NFR-3)
WB: 3 work items
- WB-1 covers FR-7 (3 files, prerequisite: none)
- WB-2 covers FR-8 (2 files, prerequisite: WB-1)
- WB-3 covers NFR-3 (test + benchmark, prerequisite: WB-2)
Anything to add, remove, or reorder?"
Apply feedback and present again until the user confirms.
Phase 7: Write & Register (DRM-Driven)
Only after user confirmation. Do not write from memory — iterate the DRM row by row.
For each track row in the DRM:
- For each cell marked
✅ req:
a. Read the corresponding reference guide
b. Write the document to {planning_dir}/{track}/
c. Mark the cell ✅ written in your tracking
Then update project-level documents:
- Write/update
PRD.md in {planning_dir}/
- Update
execution-order.md
- Sync
work-catalog.md
After all writes, output the final DRM with status:
## Final Document Matrix
| Track | README | WB | API Contract | Test Strategy | UI Spec | Data Model | ADR |
|-------|--------|----|-------------|--------------|---------|------------|-----|
| OR | ✅ written | ✅ written | ✅ written | ✅ written (4 WBs) | ❌ n/a | ❌ n/a | ❌ n/a |
| FE | ✅ written | ✅ written | ❌ n/a | ✅ written (3 WBs) | ✅ written | ❌ n/a | ❌ n/a |
Project: PRD ✅ written | execution-order ✅ written | work-catalog ✅ written
Phase 8: Completeness Verification
The planner does not finish until this phase passes.
Step 1: Filesystem Check
For every ✅ req cell in the DRM, verify the file exists on disk using Glob:
{planning_dir}/{track}/README.md
{planning_dir}/{track}/work-breakdown.md
{planning_dir}/{track}/api-contract.md (if ✅ req)
{planning_dir}/{track}/test-strategy.md (if ✅ req)
{planning_dir}/{track}/ui-spec.md (if ✅ req)
{planning_dir}/{track}/data-model.md (if ✅ req)
{planning_dir}/adr/ADR-*.md (if ✅ req)
{planning_dir}/PRD.md
{planning_dir}/execution-order.md
{planning_dir}/work-catalog.md
Step 2: Gap Report
Compare DRM ✅ req cells against filesystem results:
## Completeness Report
Total required: 12 | Written: 10 | ❌ Missing: 2
| Track | Document | Status | Reason Required |
|-------|----------|--------|-----------------|
| FE | test-strategy.md | ❌ MISSING | 4 WB items (≥ 3 threshold) |
| OR | api-contract.md | ❌ MISSING | FR-1: "REST endpoint" |
Step 3: Resolve Gaps
If any ✅ req documents are missing:
- Read the corresponding reference guide
- Generate the missing document
- Re-run filesystem check
- Repeat until gap count = 0
Step 4: Final Confirmation
"All documents verified. {N} documents across {M} tracks written and confirmed on disk.
[Final DRM table — all ✅ req cells now show ✅ verified]"
Only after gap count = 0 is the planner session complete.
Output Location
All documents are saved under the directories listed in consensus.planning_dirs.
Do NOT hardcode paths — always read from config.
Example templates: ${CLAUDE_PLUGIN_ROOT}/examples/${locale}/plans/
Rules
- PRD before WB — every WB item must trace back to a PRD requirement (FR or NFR)
- Cross-layer contracts — every WB item specifies BE→FE or FE→BE requirements as pairs
- Dependency chain — every
requires field references specific WB IDs
- No vague goals — "improve performance" is not a goal. "Reduce p95 latency to < 200ms" is.
- Verify prerequisites — check that required tracks/WBs are actually completed before planning dependent work
- Single locale — produce documents in the locale specified by
plugin.locale in config
- Register in execution-order — new track → add to
execution-order.md; existing track adjustment → update ordering/prerequisites
- Sync work-catalog — any WB addition/modification/removal must be reflected in
work-catalog.md
- Check for hidden dependencies — use
dependency_graph to catch import chains that cross track boundaries
- PRD IDs are global — FR/NFR numbering continues across features, never resets
- DRM is the contract — every
✅ req cell must reach ✅ written → ✅ verified before completion
- DRM before drafting — build and confirm the DRM before writing any track document
- No implicit skip — a conditional document is
❌ n/a only when zero trigger keywords matched; log the absence reason
Adjusting Existing Tracks
When modifying an existing track (not creating new):
- Read current PRD.md, README.md + work-breakdown.md for the track
- Use
rtm_parse to check current RTM status — don't plan work that's already verified
- Read execution-order.md to understand the track's position in the dependency graph
- Make targeted changes — do not rewrite documents that are already correct
- Update execution-order.md if prerequisites or ordering changed
- Update work-catalog.md if WB items were added/modified/removed
- Verify that downstream tracks are not broken by the change
Anti-Patterns
- Do NOT generate work-breakdowns without a PRD requirement to trace to
- Do NOT generate PRD requirements without user confirmation of scope
- Do NOT plan work that depends on unimplemented infra (check with tools first)
- Do NOT create WBs without exit conditions
- Do NOT mix BE and FE in the same WB without explicit contract pairs
- Do NOT plan without reading existing execution-order (may conflict or duplicate)
- Do NOT adjust execution-order without checking downstream impact
- Do NOT skip the research phase — use code_map and dependency_graph before drafting
- Do NOT reuse FR/NFR IDs — numbering is global and monotonically increasing
- Do NOT skip DRM construction — writing documents without a confirmed DRM is prohibited
- Do NOT mark a conditional document
❌ n/a without checking trigger keywords against assigned FRs
- Do NOT finish the planner session with any
✅ req cell that is not ✅ verified on disk
