Spec Plan — Turn a Spec into a Plan

You are turning a spec into a concrete plan file that /implement can consume. No implementation code is written.

Specs Folder Discovery

Run bun ~/.claude/tools/spec-edit/index.ts conf-get <cwd> where <cwd> is the current working directory. If it returns a path, use that as <specs-dir>. If it exits with no output, tell the user: "This project hasn't been set up yet — run /spec first to configure the specs folder."

No Arguments?

If invoked without arguments, run bun ~/.claude/tools/spec-edit/index.ts status <specs-dir> and present the output. Then ask: "Which spec do you want to plan?"

Using spec-edit

bun ~/.claude/tools/spec-edit/index.ts status <specs-dir>              # All specs + plans summary
bun ~/.claude/tools/spec-edit/index.ts list <file>                     # Sections with line numbers + content line count
bun ~/.claude/tools/spec-edit/index.ts read <file> <heading>           # One section's content
bun ~/.claude/tools/spec-edit/index.ts init-plan <file> <title>        # New plan
echo "content" | bun ~/.claude/tools/spec-edit/index.ts replace <file> "Heading"
bun ~/.claude/tools/spec-edit/index.ts set-meta <file> <key> <value>   # Header metadata

Steps

1. Find the spec.
   • No args → run status, ask which spec.
   • <spec-name> → use that spec.
   • <spec-name> <hint> → use that spec; the hint scopes which part to plan. If the spec can't be found, run status and ask the user to pick.
2. Read the spec by section, not in full. Use read <file> <heading> for each section you need — at minimum Context and Key Decisions if present. Only read detail files if the spec references them as relevant to this chunk. Never dump the entire file.
3. Propose chunks. Identify task-oriented buildable chunks — each chunk is a coherent unit of work that results in a reviewable change. Think in tasks, not files. Present the list with brief descriptions.
4. User picks a chunk. Do NOT pick for them. If the hint from step 1 clearly points to one chunk, confirm it rather than assuming.
5. Draft the plan. For the chosen chunk, draft — in chat, not yet on disk:
   • Scope: what part of the spec this plan covers, and what's explicitly out of scope.
   • Checklist: files to create/modify, key decisions to follow (lifted from the spec), acceptance criteria. Include sub-parts as checklist items if the chunk has internal steps.
   • Todo: leave empty. /implement populates this as it works.
   • Open Questions: anything ambiguous that blocks implementation.
6. Get approval. Show the draft to the user. Iterate until they're satisfied. Do NOT write the file until they approve.
7. Write the plan file.
   • Path: <specs-dir>/<spec-name>/plans/<plan-slug>.md. Pick a short kebab-case slug from the chunk name (e.g. token-rotation-backend.md). Confirm the slug with the user if ambiguous.
   • Create with spec-edit init-plan <path> "<Plan Title>".
   • Fill each section with spec-edit replace <path> "<Heading>" (content via stdin).
   • Set the linked ticket with spec-edit set-meta <path> Jira <ticket> if applicable.
8. Done. Tell the user the plan is saved and ready to run via /implement <hint>. Do not start implementing.

Rules

• No code written. At all.
• Stay faithful to the spec — if the chunk requires a decision the spec doesn't cover, add it to Open Questions and ask the user before writing the plan.
• One plan file = one chunk. If the user wants to plan multiple chunks, repeat the flow per chunk.
• Keep plans self-contained enough that /implement can execute them without re-reading the full spec, but always link back to ../spec.md.

Token efficiency

Known sections — go straight to replace, no reads:

• Plan: Scope, Checklist, Todo, Open Questions

1. Fresh file (just init-plan) → replace directly, no reads ever
2. Need to set Jira or other header metadata → set-meta, not replace

$ARGUMENTS