Plan Work

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: " pairs. > > RECURSIVE DISCIPLINE — This lifecycle applies to EVERY task, including updating these skills. Never skip planning because a task is "meta" or "just documentation."

Pre-flight

Read: release-plan.yaml, product/SCOPE_LATEST.yaml, active epics//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.

Invocation modes

• 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.

Process

> 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.

1. 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.

1. Write capsule story spec + tasks — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task optionally includes a security: field (none / low / medium / high) sourced from the epic's specs/security/epics//THREAT_MODEL.md. Tasks with security: medium or security: high MUST include "no new security findings in affected paths" in their verify steps.

1. Verify step format — Every step MUST follow: N. → verify: . See [REFERENCE.md](REFERENCE.md) for good/bad examples.

1. Review with user — Confirm step order, granularity, and that verify commands are runnable in this project.

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

Handoff

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

---

Plan Work — Reference

Output file formats

Story spec: specs/epics//eNNsYY-.md

Populated countable-story-format with all 20 sections. Minimum maturity: 3 (Countable). Acceptance criteria in §17.

Task checklist: specs/epics//eNNsYY-tasks.yaml

story_id: e01s01
title: Login
status: todo
bcps: 3
tasks:
  - id: 1
    description: "Add login form component tests"
    verify: "npm test -- login-form.test.tsx"
    status: todo

Update specs/epics//epic.yaml manifest to list the story and its BCPs. Run bash scripts/sync-status-from-epics.sh after structural changes.

Plan template

### Story [X.Y]: [title] — Implementation Steps

**type:** feat | fix | refactor
**context:** domain | infra
**Context**: [One paragraph: what this story implements and why]

## Steps

1. [Step description] (ref: ADR-NNNN or commit SHA) → verify: ``
2. [Step description] (ref: ADR-NNNN or commit SHA) → verify: ``
...

## Verification Script (Step-by-Step)

[A human-readable, step-by-step script for the user to verify the story's outcome.]

1. [Action 1: e.g. Start the server]
2. [Action 2: e.g. Open browser to http://localhost:3000]
3. [Observation: e.g. Verify that the login modal appears]

## Out of scope

- [Explicit exclusions]

## Risks

- [Anything that could go wrong and how to detect it early]

Verify step format rules

Every step MUST follow this exact format:

N.  → verify: 

Good examples:

1. Add User model with email and name fields → verify: npm test -- user.test.ts
2. Add POST /users endpoint → verify: curl -s -X POST http://localhost:3000/users -d '{"email":"a@b.com"}' | jq .id
3. Add email uniqueness constraint → verify: npm test -- user-uniqueness.test.ts

Bad examples (no verify command):

1. Implement the user creation flow
2. Write tests for the API

Sub-operations

Define Success

Before planning, convert task statements into observable "step → verify: " pairs:

• Break the task into observable outcomes (behaviors) rather than implementation steps
• Write pairs in the format: [What must be true] → verify:
• Challenge completeness: are all required behaviors covered?
• Get user confirmation: "Does this capture everything the task requires?"
• Once confirmed, these pairs become the skeleton for plan-work steps

Zoom-Out Check

When modifying an existing module, confirm scope is understood:

• State the module's purpose — what is it responsible for?
• Name the callers — who depends on it?
• List the contracts — what invariants or interfaces must be preserved?

If you cannot answer all three without deep code archaeology, scope is misunderstood. Clarify with the user before writing steps.

Slopcheck

For every external package proposed in the plan, tag each with one of:

• [OK] — package is mature, actively maintained, appropriate scope
• [SUS] — suspiciously broad, has maintenance concerns, or unclear fit
• [SLOP] — unmaintained, known security issues, or out of scope

[SUS] and [SLOP] require explicit human approval before the step may execute. Document tags inline next to the package name.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: danielvm-git
• Source: danielvm-git/bigpowers
• License: MIT
• Homepage: https://github.com/danielvm-git/bigpowers

Install and usage instructions live in the source repository linked above.