epic-planner

Epic Planner

Plan and scaffold a complete epic hierarchy: from idea to beads-tracked, dependency-wired tasks ready for multi-agent execution.

Spec → Bead Mapping

Every spec artifact maps to a bead hierarchy level. Use the project's beads prefix (e.g. adj- for adjutant) — shown here as bd- generically.

Spec Artifact	Section	Bead Level	Bead ID	Bead Type
spec.md	User Story N (Priority: PN)	Sub-Epic	bd-xxx.N	epic
plan.md	Phase N heading	Sub-Epic	bd-xxx.N	epic
tasks.md	T001 task line under Phase N	Task	bd-xxx.N.M	task
beads-import.md	Task table row	Task	bd-xxx.N.M	task
(created during impl)	Bug fix / refactor / extra tests	Improvement	bd-xxx.N.M.P	task|bug

T-IDs vs Bead IDs: T001, T002 etc. are authoring-time identifiers used in tasks.md for readability. Bead IDs (bd-xxx.N.M) are the runtime tracking identifiers that replace them once beads are created. The beads-import.md table maps between them.

Phase-to-sub-epic numbering: Phases in tasks.md and sub-epics in beads share the same sequential numbering. Phase 1 = .1, Phase 2 = .2, etc. If you skip a phase (e.g. no Setup needed), skip that sub-epic number too — keep them in sync.

Workflow

Phase 0: Discover & Clarify

Before generating anything, ask 3-5 targeted questions using AskUserQuestion. Good areas to probe:

1. Scope - What's in, what's explicitly out?
2. Tracks - Are there natural parallel streams (backend/frontend, infra/feature, data/UI)?
3. MVP - Which user story is the minimum viable delivery?
4. Constraints - Performance targets, platform requirements, dependencies on external systems?
5. Priority - P0 (critical) through P4 (backlog)?

Skip questions whose answers are obvious from the user's description.

Phase 1: Setup Feature Directory

Determine the next feature number by scanning specs/ for existing directories:

ls specs/ | sort -n | tail -1   # e.g., 007-push-notifications
# Next number: 008

Create directory: specs/###-feature-name/

Phase 2: Generate Artifacts

Generate four files in order. Use the templates in references/templates.md as the structural guide — fill them with content derived from the user's description and your clarification answers.

1. spec.md - What to build (user stories with acceptance criteria, requirements, success criteria)
2. plan.md - How to build (architecture decisions, file paths, phases, parallel opportunities)
3. tasks.md - Executable task checklist (T001 format with [P] and [US] markers, exact file paths). Every non-exempt task MUST use one of the two TDD-shaped forms — see "TDD Task Shape (MANDATORY)" below.
4. beads-import.md - Bead hierarchy mapping (root epic, sub-epics per phase, task tables)

Write all four files to specs/###-feature-name/.

Small features (< 5 tasks): Skip sub-epics entirely. Use the simplified template variant in templates.md. Tasks go directly under the root epic (bd-xxx.1, bd-xxx.2 as tasks, not sub-epics).

Phase 3: Create Beads

Use bd CLI to create real beads matching the hierarchy in beads-import.md. See references/beads-workflow.md for the exact commands and conventions.

Hierarchy pattern (using project prefix, e.g. adj-):

bd-xxx           (root epic, type=epic)
  bd-xxx.1       (sub-epic: Setup, type=epic)
  bd-xxx.2       (sub-epic: Foundational, type=epic)
  bd-xxx.3       (sub-epic: US1, type=epic)
    bd-xxx.3.1   (task under US1, type=task)
    bd-xxx.3.2   (task under US1, type=task)
  bd-xxx.4       (sub-epic: US2, type=epic)
  ...

Steps:

1. Find next available root ID: bd list --status=all and pick next sequential root
2. Create root epic: bd create --id=bd-xxx --title="..." --description="..." --type=epic --priority=N
3. Create sub-epics for each phase (Setup, Foundational, US1, US2..., Polish)
4. Create tasks under each sub-epic
5. Wire dependencies immediately (MANDATORY — see beads-workflow.md)

Phase 4: Update Artifacts with Bead IDs

After creating beads, update beads-import.md and plan.md with the actual bead IDs. Add a bead map block to plan.md:

## Bead Map

- `bd-xxx` - Root epic: [Title]
  - `bd-xxx.1` - Setup
    - `bd-xxx.1.1` - [Task title]
  - `bd-xxx.2` - Foundational
  - `bd-xxx.3` - US1: [Title]
    - `bd-xxx.3.1` - [Task title]

Phase 5: Summary

Report to the user:

• Feature directory path
• Root epic ID and total bead count
• Bead hierarchy overview (the bead map)
• Suggested next step: "Run bd ready to see unblocked tasks, or assign work to team agents"

Improvements (Post-Planning)

Improvements are Level 4 beads (bd-xxx.N.M.P) created during implementation, not during planning. They cover:

• Bug fixes discovered while building a task
• Refactors needed after initial implementation
• Extra tests identified during code review

Create them as children of the affected task. Example: while implementing bd-012.3.1, you discover a bug → create bd-012.3.1.1 as type=bug. Wire it: bd dep add bd-012.3.1 bd-012.3.1.1.

Do NOT pre-plan improvements in the spec artifacts — they emerge organically.

TDD Task Shape (MANDATORY)

Every implementation task in specs/<###-feature>/tasks.md MUST be authored in a test-first shape. A task that says "Create file X with tests" expresses the same step twice and erases the RED → GREEN cadence — that is not TDD. Use one of the two shapes below for every non-exempt task. The audit script scripts/audit-tasks-md.ts walks specs/*/tasks.md and flags any line that violates this rule.

Shape A — Split task (preferred for non-trivial work)

The Ta-tests / Tb-impl pair share a base number and a clear ordering: Ta must be RED before Tb begins.

- [ ] T010a [P] [US1] Write failing tests for foo-service.ts in
      backend/tests/unit/foo-service.test.ts. Cover happy path, error path,
      edge case. Confirm RED.
- [ ] T010b [US1] Implement foo-service.ts in backend/src/services/foo-service.ts.
      Run tests until GREEN. No new code paths beyond what tests require.

Shape B — Single task with explicit phases (for small atomic tasks)

The verbiage MUST include BOTH a write-failing-tests-first phrase (e.g. "failing tests first", "write tests first", "RED first", "tests before impl", "confirm RED") AND a confirm-GREEN phrase (e.g. "until GREEN", "confirm GREEN", "make tests pass"). A single-line task that only mentions "with tests" or "+ tests" does NOT satisfy this rule.

- [ ] T010 [P] [US1] Build foo-service.ts in backend/src/services/foo-service.ts.
      Phases: write failing tests first in backend/tests/unit/foo-service.test.ts
      → confirm RED → implement → confirm GREEN → refactor.

Exemptions

The following inline markers exempt a task from the TDD-shape rule. Use sparingly:

• [setup] — Scaffolding tasks with no behavior (npm install, mkdir, config init).
• [docs] — Documentation-only tasks (CHANGELOG, README, ADR).
• [scaffold] — Empty file or directory creation that another task will fill.

Bug-fix tasks are NOT exempt — the regression test IS the test-first phase. The task wording must still include "regression test first" or equivalent.

Audit

Run the warn-only auditor locally before considering tasks.md complete:

npx tsx scripts/audit-tasks-md.ts            # full report
npx tsx scripts/audit-tasks-md.ts --quiet    # exit code only
npx tsx scripts/audit-tasks-md.ts --json     # machine-readable

The script exits 0 always (warn-only — does NOT fail CI). It exists so reviewers can spot non-TDD task shapes quickly. New tasks.md files authored after this rule landed MUST pass the audit clean. See .claude/rules/03-testing.md → "Task Structure in tasks.md (TDD-shaped)" for the canonical rule and reference examples.

Question Routing (MANDATORY)

Anything you need from the General MUST be filed via file_question — both questions/decisions AND user-blocking actions (key/secret, access, approval). This is non-negotiable.

// Question or decision
file_question({
  body: "Question about epic '<title>': <your question>",
  context: "<what you're doing, what you tried, what you need>",
  urgency: "normal",
  suggestedOptions: ["option A", "option B"]   // optional
})

// Blocking action (General must DO something, not just answer)
file_question({
  body: "Need <resource> to proceed with epic '<title>'",
  context: "<what you're building, why you need it, what's blocked>",
  urgency: "blocking",
  category: "action_required"
})

Rules:

• Do NOT use AskUserQuestion — it blocks execution and the user may not be at the terminal
• Do NOT print questions to stdout — the user monitors agents via the Adjutant dashboard, not terminal output
• Do NOT bury questions in send_message — they miss the triage queue and the General cannot act on them
• Do NOT block waiting for answers — file via file_question, state your assumption, and continue
• If ambiguous on multiple points, file ONE file_question with all questions in the body, then proceed with reasonable defaults

When spawning team agents to work on the epic, include this same instruction in their spawn prompts — they must also use file_question for questions and blocking actions, not send_message or stdout.

Key Rules

• One root epic per feature — never create multiple roots
• Wire deps immediately after creating beads — not as an afterthought
• Exact file paths in every task description
• [P] marker only when tasks touch different files with no dependencies
• Sequential IDs within each level (.1, .2, .3, not random)
• Phase numbers = sub-epic numbers — keep them in sync
• Skip sub-epics for tiny features (< 5 tasks) — put tasks directly under root
• TDD-shaped tasks — every non-exempt task uses Shape A (Ta/Tb split) or Shape B (single task with explicit RED → GREEN phasing). Exemptions: [setup], [docs], [scaffold].

References

• templates.md - Speckit-compatible templates for all four artifacts
• beads-workflow.md - bd CLI commands, dependency wiring, and ID conventions
• .claude/rules/03-testing.md - Canonical testing rules, including the TDD-shaped tasks.md rule
• scripts/audit-tasks-md.ts - Warn-only auditor that flags non-TDD task shapes