Skip to content

plan-work

Spine position: Step 3 — scope-work → slice-tasks → plan-work.

Produce a detailed, verifiable implementation plan in the active epic capsule directory (specs/epics/eNN-slug/). Output: a story spec .md file (countable-story-format) and a decoupled eNNsYY-tasks.yaml with runnable verify commands. “I think it works” is not a step.

HARD GATE — Do NOT proceed with a plan until the task’s success criteria are clear. If success is ambiguous, run define-success first to convert the task into “step → verify: <cmd>” pairs.

RECURSIVE DISCIPLINE — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is “meta” or “just documentation.”

Read: release-plan.yaml, product/SCOPE_LATEST.yaml, active epics/&lt;capsule>/epic.yaml, tech-architecture/tech-stack.md, product/GLOSSARY_LATEST.yaml.

ZOOM-OUT MANDATE (v1.17.0) — If modifying an existing module: (1) State the module’s purpose. (2) Name its callers. (3) List its contracts. Cannot answer all three? Stop — scope is misunderstood.

If this plan touches an existing module, run assess-impact first to understand blast radius.

DISCOVERY MANDATE (v1.18.0) — For external API integration, verify the API signature via local docs or search and quote at least one technical detail in the step’s context.

MULTIPLE INTERPRETATIONS (HARD GATE) — If the task admits ≥2 valid interpretations, list them and get a user decision before drafting any steps.

COMPLEXITY PUSHBACK (HARD GATE) — Every new abstraction MUST include a one-sentence “Reason for Depth.” If it can’t be filled non-trivially, the abstraction is premature — use inline code instead.

SLOPCHECK (HARD GATE) — For every external package, tag it [OK], [SUS], or [SLOP]. [SUS]/[SLOP] require human approval before execution.

  • Default: full plan with zoom-out mandate, impact assessment, slopcheck
  • --fast: Skip zoom-out and impact assessment. Use for tasks under 3 BCPs with no module interface changes.

Timing: bash scripts/bp-timing.sh start plan-work at invocation; bash scripts/bp-timing.sh end plan-work before handoff.

  1. Explore — Use Explore subagent to understand affected modules, existing test patterns, similar prior art, and dependencies.

  2. Draft steps — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3.

  3. Write capsule story spec + tasks — Output two files inside the active epic capsule. See REFERENCE.md for file formats and the plan-template. Each task MUST include a risk: field (P0 | P1 | P2 | P3) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (specs/tech-architecture/eNN-TEST_PLAN_LATEST.md) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (SC-eNNsYY-P0-NN). Each task optionally includes a security: field (none / low / medium / high) sourced from the epic’s specs/security/epics/&lt;id>/THREAT_MODEL.md. Tasks with security: medium or security: high MUST include “no new security findings in affected paths” in their verify steps.

    Requirement delta tags (e45s29): When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content:

    Tag When Required content
    ADDED New requirement Full requirement text
    MODIFIED Changed behavior Before: prior behavior · After: new behavior
    REMOVED Retired requirement Before: what existed · After: (removed) + rationale
    RENAMED ID or title change only Before: old ID/title · After: new ID/title

    Net-new stories (greenfield) use ADDED only. MODIFIED/REMOVED/RENAMED without before/after blocks fail the plan-work gate.

  4. Verify step format — Every step MUST follow: N. &lt;What to do> → verify: &lt;runnable command>. See REFERENCE.md for good/bad examples.

4a. Cross-artifact consistency pass (HARD GATE — e45s04) — Before handoff, run:

Terminal window
bash scripts/lib/plan-consistency-check.sh specs/epics/<capsule>/

Print CRITICAL / HIGH / MED findings. CRITICAL or HIGH blocks code generation — fix capsule artifacts first. MED requires explicit user acknowledgment.

4b. tasks.yaml failing ledger (e45s06) — Every new task entry starts with status: failing. Only flip to status: passing after its verify: command exits 0 during develop-tdd or verify-work. Never pre-mark passing at plan time.

  1. Review with user — Confirm step order, granularity, and that verify commands are runnable in this project.
Gate When Pass condition
Pre-Implementation Before kickoff-branch / first RED commit Root-cause stated for bugs; assess-impact done for module changes; plan-consistency-check PASS
Validation Story marked done All tasks status: passing; verify evidence in specs/verifications/
Reopen-don’t-refile Regression on shipped story Reopen existing story/bug — do not create duplicate capsule entries

After writing capsule tasks, suggest kickoff-branch (if not already on a feature branch) then build-epic, execute-plan, or develop-tdd.

→ verify: test -f scripts/lib/plan-consistency-check.sh && bash scripts/lib/plan-consistency-check.sh specs/epics/e45-quality-core/ 2>&1 | head -5

Gate: READY -> next: kickoff-branch Writes: state.yaml handoff.next_skill = kickoff-branch

<!– story: e01s01 –> <!– story: e02s02 –> <!– story: e06s01 –> <!– story: e06s02 –>