write-plan

What this skill does

# Write Plan: Spec Into Implementation Plan

Turn a [brainstorm-beagle](../brainstorm-beagle/SKILL.md) 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 [brainstorm-beagle](../brainstorm-beagle/SKILL.md) 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 [brainstorm-beagle](../brainstorm-beagle/SKILL.md)
2. **Read the spec** — ingest every section; do not paraphrase, do not summarize away requirements
3. **Read project conventions** — scan project conventions (e.g. AGENTS.md or 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 run a reviewer pass** — only for plans that are long or cover unfamiliar territory. **If the agent supports subagents**, dispatch a reviewer subagent; **otherwise** run the same review inline — identical output (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

```text
Spec at .beagle/concepts/<slug>/spec.md? ── No  → STOP, route to brainstorm-beagle
                                          ── Yes → Read spec + project conventions + 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, it asks whether to generate an execution handoff prompt and, on yes, loads the **subagent-prompt** skill ([../../../beagle-core/skills/subagent-prompt/SKILL.md](../../../beagle-core/skills/subagent-prompt/SKILL.md)) to produce one in this session; otherwise it tells 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 [brainstorm-beagle](../brainstorm-beagle/SKILL.md) 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:

- **Project conventions (e.g. `AGENTS.md` or `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 the project conventions doc 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 capabili