write-plan

Write Plan: Spec Into Implementation Plan

Turn a beagle-analysis:brainstorm-beagle spec into a comprehensive implementation plan that an engineer (or a downstream agent) can execute task-by-task without re-deriving intent.

The output is a single markdown plan document at .beagle/concepts/<slug>/plan.md, sitting beside the spec in the same concept folder. The plan captures HOW — file structure, task decomposition, exact code, exact commands — while the spec already owns WHAT and WHY.

<hard_gate> Do NOT start writing the plan until a brainstorm-beagle spec exists at .beagle/concepts/<slug>/spec.md. If one is missing, stop and route the user to beagle-analysis:brainstorm-beagle first. Skipping the spec produces plans that bake in unexamined assumptions — the spec is the contract this skill plans against. </hard_gate>

Workflow

Complete these steps in order:

1. Locate the spec — find .beagle/concepts/<slug>/spec.md; if absent, stop and route to beagle-analysis:brainstorm-beagle
2. Read the spec — ingest every section; do not paraphrase, do not summarize away requirements
3. Read project conventions — scan CLAUDE.md (root and nested) for testing, commenting, and architecture rules the plan must respect
4. Explore relevant code — read existing files the plan will touch or pattern-match against; do not guess at structure
5. Design file structure — map which files will be created or modified before any task is written
6. Decompose into tasks — each task is bite-sized (2-5 minute steps), TDD-driven, with exact paths and code
7. Self-review — check against the spec, scan for placeholders, verify type consistency (see Self-Review below)
8. Optionally dispatch a reviewer subagent — only for plans that are long or cover unfamiliar territory (see references/plan-reviewer.md)
9. Present draft to user — show the draft in chat for review; iterate if needed
10. Write to disk — save to .beagle/concepts/<slug>/plan.md only after explicit user approval

Spec at .beagle/concepts/<slug>/spec.md? ── No  → STOP, route to beagle-analysis:brainstorm-beagle
                                          ── Yes → Read spec + CLAUDE.md + relevant code
                                                   ↓
                                                   Design file structure
                                                   ↓
                                                   Decompose into TDD tasks
                                                   ↓
                                                   Self-review → fix inline
                                                   ↓
                                                   (optional) Dispatch reviewer subagent
                                                   ↓
                                                   Present draft → User review
                                                                  ├─ Changes? → Revise
                                                                  └─ Approved? → Write to plan.md

The terminal state is a written plan. This skill does not execute the plan, run tests, or modify production code. After writing, offer execution handoff via beagle-core:subagent-prompt if the user wants to run the plan in a fresh session; otherwise tell the user the plan is ready.

Locating the Spec

The default input path is .beagle/concepts/<slug>/spec.md.

Slug resolution priorities (in order):

1. User-supplied path or slug (/write-plan auth-rewrite, "plan the spec at .beagle/concepts/foo/spec.md")
2. Recently-edited spec under .beagle/concepts/
3. Ask the user to disambiguate when multiple specs are plausible

If no spec exists:

"I can't find a brainstorm-beagle spec at .beagle/concepts/<slug>/spec.md. Run beagle-analysis:brainstorm-beagle first to produce the spec, then come back to plan it."

Do not proceed. The spec is the contract; planning without one re-invents the spec under a different name and skips the review gates brainstorm-beagle enforces.

Scope Check

If the spec covers multiple independent subsystems, it should have been decomposed during brainstorming. If it wasn't, stop and suggest splitting it — the brainstorm-beagle workflow has a Scope Assessment step for this. Each plan should produce working, testable software for one cohesive subsystem.

Signs the spec is too broad to plan in one document:

• More than ~15 must-have requirements with no shared core loop
• Requirements span independent subsystems (auth, billing, analytics — each is its own plan)
• The core loop can't be explained in 30 seconds

Action: push back to the user with: "This spec covers more than one cohesive system. I'd suggest splitting it during brainstorm-beagle and planning each sub-spec independently. Want to do that, or proceed with one big plan?"

Reading Project Conventions

Before designing tasks, scan for project rules that shape the plan:

• CLAUDE.md at repo root and any subdirectory you'll touch — testing tiers, commenting policy, commit conventions, forbidden patterns
• Test framework and runner — Cargo, pytest, npm test, mix test, etc. Tasks must use the correct command.
• Existing patterns — if the codebase uses a particular file layout, follow it. The spec's Constraints and Reference Points often pin these.

When CLAUDE.md mandates something specific (e.g., "every user-visible feature needs a tier-3 test driven through the compiled binary"), the plan must include tasks that satisfy that rule. Do not silently produce a plan that violates project policy — call it out and adapt.

Spike Before Plan-Lock

Plans written from documentation alone bake in toolchain assumptions that fail on first contact with the codebase. Before locking the plan, identify every claim of the form "tool X supports behavior Y" or "command Z produces output W" where neither this repo nor the team has a working example. Each such claim is a spike candidate.

For every spike candidate, the plan must include a Task 0: Spike <claim> whose body is:

1. Run the canonical command(s) the rest of the plan depends on, against this repo, as a documented step.
2. Capture the actual output (success path AND failure modes).
3. Either: confirm the spec's Key Decision survives intact, OR route the finding back to the user with a concrete revision proposal before any other task runs.

Task 0 is non-optional when the spec's Key Decisions rest on tool behavior the team has not verified in this repo. Examples of spike-required claims:

• "Tool X's --workspace flag handles this repo's multi-backend layout in one invocation."
• "Library Y's default test attribute uses the same pool config production uses."
• "CLI Z's introspection covers every query shape we'll write."
• "Migration framework W handles concurrent migrators against a fresh DB idempotently."

If the spike fails or surfaces caveats, stop and revise the spec — do not paper over the discovery with extra plan tasks. A spec that locks a Key Decision on a tool that does not behave as assumed is a spec that needs another brainstorm pass, not a plan that needs more workarounds.

This rule is stricter than the existing Assumption Audit. An assumption is "I'm guessing about behavior I haven't verified." A spike candidate is "the spec made a load-bearing decision about behavior nobody verified." The first is documented; the second is run.

Parallel-Implementation Gate

When the plan adds a parallel implementation of an existing capability (a second database backend behind the same trait, a second platform target for the same UI, a second protocol adapter for the same service), the plan must end with a final task whose body is:

1. Identify the canonical contract/conformance test suite that pins the existing implementation's observable behavior.
2. Run that suite against both implementations in the same invocation.
3. Assert byte-i