/write-plan

name: write-plan
description: "Use when you have a finalized brainstorm-beagle spec at `.beagle/concepts/<slug>/spec.md` and need a bite-sized, TDD-driven implementation plan before any code is written. Triggers on: \"write a plan\", \"plan this spec\", \"turn the spec into a plan\", \"now plan the implementation\", \"write-plan\". Reads the spec, designs the file structure, decomposes work into 2-5 minute TDD steps with exact paths and commands, self-reviews against the spec, gets user approval, then writes to `.beagle/concepts/<slug>/plan.md` and offers to generate an execution handoff prompt via the subagent-prompt skill. Does NOT brainstorm specs, write code, or execute the plan — produces the plan document (and an optional handoff prompt) only."

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

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 on