spec-plan

name	spec-plan
description	Turn an approved spec into plan.md and tasks.md. Use when asked to "plan a spec", "create an implementation plan", "break down a spec into tasks", "how should we build this", or when a spec.md exists and needs a plan. Produces architecture, files, alternatives considered, risks, and an ordered task list.

Plan an implementation

Read specs/NNN-name/spec.md and produce plan.md and tasks.md alongside it. Write those two files and nothing else — no source, no tests.

Portable equivalent of the /spec-plan prompt file. Prompt files work only in the VS Code Chat view; this skill works there and in the Copilot CLI and the coding agent.

Before planning

• Open every file you intend to change. Do not plan against a memory of the codebase.
• Check current library APIs with the context7 MCP server. SQLAlchemy 2.0, Pydantic v2, FastAPI, React 19, and Tailwind v4 all changed idioms recently. A plan built on a stale API wastes the implementer's day.
• Check Azure guidance with microsoft-docs if this touches infra.

plan.md

# Plan — NNN <Title>

## Approach
Two or three paragraphs. What is the shape of the change?

## Architecture
Where it sits. A Mermaid diagram if the data flow is not obvious.

## Files
| File | Change | Why |
|---|---|---|

## Alternatives considered
| Option | Why not |
|---|---|

The section readers return to in six months. Be specific about what you
rejected and what would change your mind.

## Risks
What could break. **Call out anything that could affect the golden tests.**

## Verification
Exactly which gate proves each acceptance criterion.

tasks.md

Each task independently completable and verifiable, stating what "done" means in terms a command can check.

- [ ] **T1 — <short title>**
      Files: `path/one.py`, `path/two.py`
      Done when: <a condition a command can verify>
      Verify: `cd apps/api && uv run pytest tests/test_x.py -v`

Sequence tasks that touch the same file. Two "parallel" tasks editing one module is a merge conflict you scheduled deliberately.

Leave the build green after every task. A task that ends red is two tasks.

Planning rules for this repository

Analytics first, then presentation. A feature that needs a new number needs a new function in analytics/ with its own unit test before anything in routers/, agent/, or apps/web/ touches it. The agent must never compute.

A new agent capability is a new tool, not a longer prompt. Plan a deterministic function plus a tool schema in agent/tools.py. Do not plan prompt changes as the mechanism.

Golden tests are load-bearing. If the plan changes a threshold, the generator, or a ranking rule, say so under Risks and add a task to re-verify pytest -m golden.

Money stays integer cents. Any task introducing a new monetary field specifies BigInteger and where the single conversion to dollars happens.

Next

Then implement one task at a time — see the spec-implement skill.