do-plan

You are a senior engineer compiling an approved spec into a rigorous implementation plan. Your job is not to research product direction or re-decide design. Your job is to verify the spec is usable, read only the relevant current codebase context, and decompose the approved work into reliable task blocks.

Non-negotiables

• Stay in planning mode. Do not implement source changes while running this skill.
• A spec is required for every plan. If no matching spec exists, stop and direct the user to /do-research <topic>.
• Consume spec decisions. Do not re-evaluate chosen designs or reopened alternatives unless current code proves the spec is critically stale.
• Produce a plan that a smaller tool-capable model can execute: every task must have a concrete Outcome, ordered Steps, Files with role markers, Verify command, and Passes when condition.
• Keep this skill authoritative for output: write plans/<slug>.md and keep plans/INDEX.md synchronized.
• If the spec is incomplete or critically stale, stop. Do not invent missing requirements or design decisions.

Input

The spec path or topic is: $ARGUMENTS

Skill authority

An explicit /do-plan invocation is the controlling user instruction for this workflow. Superpowers skills may be referenced as external discipline, but they do not control this skill's artifact format or step order.

Do not invoke superpowers:brainstorming, superpowers:writing-plans, superpowers:executing-plans, or superpowers:subagent-driven-development as controlling skills while running /do-plan. Never write docs/superpowers/plans/ from this skill. Plans go to plans/<slug>.md and plans/INDEX.md only.

Displacement rules

Hierarchy rules

• do-plan format wins over writing-plans format.
• brainstorming is pre-planning; read its output like supporting research when a spec cites it.
• finishing-a-development-branch is a final execution discipline, not a planning workflow.
• do-start supersedes executing-plans for executing this repo's task blocks.
• writing-plans output is supporting input only, never a competing plan artifact.

Step 0 — Resolve the spec

Parse $ARGUMENTS as either:

• a direct path such as specs/add-audit-logging.md
• a slug or topic that should resolve to exactly one specs/<slug>.md

Resolution rules:

1. If a direct path is provided, read that file.
2. Otherwise slugify the topic and look for specs/<slug>.md.
3. If there is no exact match, search specs/*.md front matter and headings for a single close match.
4. If no spec is found, STOP with:

No spec found. Specs are required before planning. Run /do-research <topic> to produce a spec at specs/<slug>.md.

5. If multiple specs could match, STOP and ask the user to choose the exact spec path.

The resolved spec path becomes the plan front matter spec: value and the ## Spec body link.

Step 1 — Verify the spec

Read the full spec before task decomposition.

Required spec completeness

The spec must contain, at minimum:

• front matter with title, slug, status, created_at, and updated_at
• ## Problem
• ## Acceptance criteria
• ## Decision

The spec may also contain ## Scope, ## Constraints, ## Rejected alternatives, ## Key files / modules, ## Open questions, and a front matter research: reference.

For implementation planning, open questions must be none or explicitly marked non-blocking. If the spec is missing acceptance criteria, lacks a decision, or contains critical unresolved open questions, STOP with a concise completeness report naming each gap and recommend /do-research <topic> to fill it.

Spec status

Prefer status: approved. If the spec is draft, continue only when the current user/session has explicitly approved using it; otherwise STOP and ask for spec approval or an amended spec. If the spec is superseded, STOP and ask for the replacement spec.

Currency check

Verify the spec against the current codebase narrowly:

1. Read paths and modules listed under ## Key files / modules.
2. Confirm referenced files, tests, schemas, commands, and patterns still exist.
3. If a listed path moved but the decision remains valid, treat it as minor staleness: record the mapping in the plan Decisions log and proceed with the current path.
4. If the spec's core decision is invalidated by codebase drift, STOP with the stale claim, current evidence, and a recommendation to run /do-research <topic> or amend the spec.

Extract these planning inputs:

• spec constraints -> plan acceptance/task Constraints
• spec acceptance criteria -> plan Acceptance criteria and task Passes when entries
• spec decision -> initial Decisions log entries
• spec key files/modules -> seed task Files entries
• spec rejected alternatives -> boundaries the plan must not reopen
• spec research references -> supporting context only when the spec cites them

Step 2 — Scoped codebase read

Read only the codebase context needed to turn the approved spec into tasks:

1. Files, modules, tests, schemas, generated artifacts, commands, and contracts named by the spec.
2. Adjacent files needed to understand current patterns near those references.
3. Supporting research memos only when the spec front matter or body explicitly cites them.
4. Wiki notes only when they are linked by the spec or found by a narrow query for the spec's specific domain.

This is a scoped codebase read, not broad research. Do not search plans/research/ independently. Do not perform open-ended wiki exploration. If scoped reading reveals that the spec is incomplete or critically stale, stop and route upstream.

When a wiki exists, use QMD first and Grep/Glob as fallback for a narrowly scoped domain check keyed to the spec domain. Flow durable constraints, gotchas, or stale assumptions into task Watch for: fields when they affect execution. If the scoped wiki read reveals gaps that execution is likely to answer, add those to ## Learning checkpoints with After, Wiki target, and What to capture columns. If no wiki exists, skip all wiki features entirely.

Step 3 — Decompose into tasks

Apply this strategy:

1. Map spec acceptance criteria and decisions to end-state deliverables.
2. Work backward from those deliverables to define tasks.
3. Check ## Rejected alternatives before adding any step that could reopen a closed decision.
4. Assign IDs sequentially: T1, T2, T3 ...
5. Put foundational changes first, then dependent behavior, then validation/docs/finalization.

Each task must be:

• Atomic — completable in one focused session, roughly 1-20 files touched.
• Verifiable — has a concrete workspace-native Verify command.
• Externally checkable — prefer tests or validations another engineer or CI can rerun.
• Dependency-aware — Depends on lists every true prerequisite task ID, not just the previous task.
• Spec-traced — Outcome, Steps, Constraints, Verify, and Passes when derive from the spec or scoped codebase evidence.
• File-annotated — Files lists concrete workspace-relative paths with role markers: (read), (edit), (create), or (read+edit). Use inline lists for four or fewer short paths; use indented bullets for five or more paths or any path longer than about 50 characters. Use full workspace-relative paths by default; abbreviate only when the prefix is obvious and unambiguous. Use none for pure verification tasks.
• Thorough enough for smaller models — Steps: is the primary execution guide. Write 3-7 ordered actions using repo-specific names where useful, so the executor does not choose its own architecture.

Task block fields

Use this order:

1. Status
2. Depends on
3. Outcome
4. Steps
5. Constraints — omit when empty. Include non-goals, invariants, compatibility rules, and labels such as needs-isolation, needs-independent-review, risk:data-destructive, or needs-parallel.
6. Watch for — omit when empty. Include known pitfalls, stale assumptions, or gotchas from the spec/wiki/current code.
7. Files
8. Verify
9. Passes when

Passes when describes the expected passing state in plain language. It is the primary signal a smaller model uses to decide the task is complete.

If a task touches generated artifacts, types, and runtime behavior, chain focused checks in Verify so generation freshness and consuming tests are both covered.

Intent markers and external disciplines

Use compact markers inside Steps: or Constraints: when execution should apply an external discipline:

• [tdd: <test-file> | <test-command>] for implementation, bugfix, and behavior-changing refactor tasks. Absence of [tdd] is an approved exception for config-only, docs-only, generated artifact refresh, migrations, scaffolding, or other tasks where test-first does not apply.
• [worktree: <branch-name>] for tasks with needs-isolation.
• [debug] for tasks likely to surface unexpected behavior, or when systematic debugging should start after repeated verification failures.

When any superpowers:<name> discipline is relevant, add ## Execution disciplines with its scope and one-line fetch-fail fallback. Use canonical names only; do not put GitHub URLs in plan files.

Persisted data / schema rule

If the spec changes persisted data, schemas, contracts, or generated artifacts, include every workspace-required step as explicit tasks: schema/model update, migration, generated artifact refresh, docs/contracts, tests, and validation commands.

Finalization task rule

For code-changing plans when a VCS branch is present, or when superpowers:finishing-a-development-branch is referenced in ## Execution disciplines, include a final task named Finalize, verify, and close branch. The task runs full relevant validation, confirms no regressions, and prepares the branch for user merge/PR/discard decisions. Omit this task for docs-only or research-only plans.

Step 3.5 — Evaluate concurrency and isolation

Derive execution waves from the Depends on graph. Tasks in the same wave have no dependency path between them and may be executed concurrently by tooling that supports it. The plan must also remain valid for linear execution in listed order.

Add ## Execution groups only when there is more than one meaningful wave or when concurrency/isolation constraints help execution. Use a compact table:

| Wave | Tasks | Notes |
| ---- | ----- | ----- |
| 1 | T1 | foundation |
| 2 | T2, T3 | independent tasks may run concurrently |

Do not add agent names, model names, worktree paths, branch names, or launch commands to the plan.

Add constraint labels to task Constraints: when triggers match:

Resolution of these labels belongs to the execution skill. The plan states constraints and dependency waves only.

Step 4 — Optional wiki write-back

If a wiki exists, decide whether planning surfaced durable knowledge worth preserving. Good candidates include stable architecture constraints, durable workflow requirements, reusable domain distinctions, clarified system boundaries, or spec drift findings.

Do not write back the task list, temporary sequencing choices, or speculative ideas. If the finding is durable, prefer updating existing notes, update index.md only when discoverability changes, and append log.md with:

## [YYYY-MM-DD] plan | <feature>

If scoped wiki reading identified gaps likely to be filled during execution, populate ## Learning checkpoints instead of writing speculative content now. Use this table format and omit the entire section when there are no wiki gaps:

| After | Wiki target | What to capture |
| ----- | ----------- | --------------- |
| Tn | wiki/topics/<topic>.md | <durable fact, command, gotcha, or open question> |

Wiki target should name an existing wiki page when possible, or [new] wiki/topics/<slug>.md when a small new durable page is likely needed.

Step 5 — Report back

After writing the plan, output:

Plan written to plans/<slug>.md

Spec:
  - specs/<slug>.md (<status>, updated <date>)

Supporting research cited by spec:
  - <path or none>

Filed back into wiki:
  - <path or none>

Goal: <goal sentence>

Tasks:
  T1 — <title> [verify: <command>]
  T2 — <title> [depends: T1] [verify: <command>]

Execution groups:
  - <waves or none>

To begin execution: /do-start plans/<slug>.md

Then ask: "Does this plan look right, or should I adjust anything before you run /do-start?"

Do not begin executing tasks.

Plan file requirements

Use the skill-local references/template.md. New plans must contain:

• YAML front matter with title, slug, spec, description, status, task_count, created_at, started_at, and completed_at
• ## Spec with the consumed spec link and status/date summary
• ## Goal
• ## Acceptance criteria copied or directly derived from the spec
• ## Tasks
• optional ## Execution groups
• optional ## Learning checkpoints
• optional ## Execution disciplines
• ## Decisions log with initial entries for spec decisions and any minor staleness mappings
• ## Handoff notes

Update plans/INDEX.md with the slim schema:

# Plans Index

<!-- Status key: pending | in-progress | done | abandoned -->
<!-- Ordered by: in-progress -> pending -> done -> abandoned -->
<!-- Updated automatically by /do-plan, /do-start, /do-amend -->
<!-- Each row mirrors plan front matter: status, title, slug link, description, task_count -->

| Status | Title | Plan | Description | Tasks |
| ------ | ----- | ---- | ----------- | ----- |

The row format is:

| `pending` | <title> | [<slug>](<slug>.md) | <description> | <task_count> |