A spec-driven workflow for AI coding agents. Send the plan — the build follows.
An AI agent is a fine builder and a terrible client. Plan2Code stops making it both: you approve a plan, the plan becomes a set of phase documents in your repo, and the agent builds to those documents one phase at a time. Progress lives in files instead of chat history — so the next session, the next agent, and the next engineer all start from the same specs.
Six commands, each posted separately. Two of them are optional.
Version 2.3.0 · MIT · 📖 plan2code.jparkerweb.com
Requires Node.js 18 or later and network access — installation runs through the skills CLI. Re-run any time to update.
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.gitThis fetches the installer to a temp directory, builds the workflow as Agent Skills, delegates
installation to skills add, and cleans up after itself. The installed skills work independently
from then on.
Either route lands you on the same menu:
╔═════════════════════════════════════════════════════════╗
║ INSTALL PLAN2CODE ║
╠═════════════════════════════════════════════════════════╣
║ I. INSTALL Install Plan2Code skills everywhere ║
║ A. ALL Install Plan2Code + dev tools ║
║ U. UNINSTALL Remove Plan2Code skills and dev tools ║
║ C. CUSTOM Advanced options ║
║ Q. QUIT Exit ║
╚═════════════════════════════════════════════════════════╝
Supported tools: every agent supported by the skills CLI, including Claude Code · Cursor · GitHub Copilot · Windsurf · Codex · Continue · Codeium · Zed · Amp · OpenCode · Devin · Crush · Pi · Gemini CLI · Cline · Roo · Kilo · Goose · Trae · Qwen Code.
The installer keeps one canonical copy of each skill under ~/.agents/skills/ and links it into
agents that maintain their own directory. Update later with npx skills update -g.
Use the installer rather than calling skills add against the repository root: recursive discovery
would also find maintainer-only skills under .claude/skills/. The installer targets skills/
explicitly.
Prefer to clone?
git clone https://github.com/jparkerweb/plan2code.git
cd plan2code
node install.js
# Only if you plan to modify or contribute to Plan2Code itself
npm install && npx husky ┌╴╴╴╴╴╴╴╴╴╴╴╴┐
╎0 PATHFINDER╎ optional · new in 2.0 · for an idea too big or unclear to plan
└╴╴╴╴╴╴┬╴╴╴╴╴┘
▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌╴╴╴╴╴╴╴╴╴╴╴╴┐ ┌────────────┐
│ 1 PLAN │─>│ 2 DOCUMENT │─>│3 IMPLEMENT │─>╎ REVIEW ╎─>│ 4 FINALIZE │
│decide what │ │ draw it as │ │build to the│ ╎ optional ╎ │verify, sum,│
│ to build │ │phase specs │ │ drawing │ ╎ any time ╎ │ archive │
└────────────┘ └────────────┘ └────────────┘ └╴╴╴╴╴╴╴╴╴╴╴╴┘ └────────────┘
new chat new chat new chat/phase new chat new chat
├◀─────────────── one feature, start to archive ──────────────────▶┤
Every box is its own conversation. That is not a style preference — planning context leaking into implementation is where most agent drift starts.
| Command | Use it when |
|---|---|
/plan2code-0-pathfinder |
The idea is too big and unclear to plan. Charts it as decisions, clears them one at a time, hands a hot plan draft to Step 1 |
/plan2code-1-plan |
Starting a feature. Full requirements → architecture pass |
/plan2code-2-document |
Planning is done. Turn the plan into phase specs |
/plan2code-3-implement |
Build the next phase (one per conversation) |
/plan2code-review |
Independent second opinion on local changes, then optional fixes |
/plan2code-4-finalize |
All phases done. Validate, summarize, archive |
/plan2code-init |
Generate this repo's AGENTS.md so every agent starts informed |
/plan2code-init-update |
Fold what you learned this session back into AGENTS.md |
/plan2code-quick-task |
A small change that doesn't warrant the full sequence |
/plan2code-1b-revise-plan |
Requirements moved mid-build. Revise the specs, not the code |
/plan2code-handoff |
Compact this conversation into a doc the next one resumes from |
1 · A fresh conversation for each step, and each implementation phase. Step 3 gets a new chat per phase, not one chat for all of them.
2 · No code until the plan hits 90% confidence. Step 1 will not finalize below the threshold. Under it, the agent keeps asking and keeps reading your code — and writes every assumption down where you can argue with it.
3 · Checkboxes are the state, not the chat. Progress lives in the spec files. Any agent, any session, resumes cold from them.
4 · Reply approved to close a phase.
Nothing advances on a guess about what you meant.
your-project/
├── specs/
│ └── task-api/ ← in progress
│ ├── pathfinder/ ← only if you charted it in Step 0
│ │ ├── map.md the destination, the decisions, the fog
│ │ ├── questions/NN-<slug>.md one decision per file
│ │ └── briefs/brief-<date>.md plain-English decision summaries
│ ├── PLAN-DRAFT-20260804.md ← Step 1: the verified plan
│ ├── PLAN-CONVERSATION-*.md ← Step 1: how you got there
│ ├── overview.md ← Step 2: phase list + parallel groups
│ └── Phase 1.md … Phase N.md ← Step 2: one-point tasks, self-contained
├── specs--completed/
│ └── auth-refresh/ ← Step 4 files finished work here
└── ...your code
specs/ is gitignored by default — it's your working drawing, not a deliverable. Share a folder
deliberately with git add -f when you want to.
| Mark | Status | Meaning |
|---|---|---|
[ ] |
Open | Unclaimed. Any agent picks it up cold. |
[/] |
In progress | Claimed right now — which is how two agents run parallel phases without colliding. |
[x] |
Done | Built, self-reviewed against the spec, approved by you. |
## Phases
- [x] Phase 1: Project setup
- [x] Phase 2: Data model
- [/] Phase 3: API endpoints ← an agent is on this now
- [ ] Phase 4: Authentication ← next availableStep 2 marks which phases don't share files. Open a second agent on one of those, and the [/] marks
keep the two out of each other's way.
Each one travels on its own — a fresh conversation, opened and closed, with the specs on disk as the only thing carried between them.
Some ideas are too big and unclear to plan: you can feel the shape of the work but you can't write it as requirements, so planning would just invent the answers. Pathfinder finds the way to the destination; Step 1 then walks it.
- Name the destination — one or two lines fixing what this effort is finding its way to. Settled
first, because it fixes scope. It also asks where the map should live: local files under
gitignored
specs/(private, solo — the default), or GitHub Issues (a map issue with one sub-issue per decision, native blocking, so your team can see and work the frontier in the tracker). - Chart the map — a breadth-first grilling surfaces the open decisions. Anything you can phrase sharply becomes a question file; anything you can only sense stays listed as fog.
- Clear the questions one at a time — resolving one burns off the fog behind it, graduating whatever just became sharp into new questions. After each decision it offers a menu: take the next question here, or start fresh — recommended after about three, to keep the agent sharp. Ask for a brief at any point and you get a dated, plain-English summary of what has been decided, what is still open, and what is next — meeting minutes, with no jargon in them.
- Hand off — when nothing is left to decide, it writes a
PLAN-DRAFTthat/plan2code-1-planresumes from at Phase 4, with requirements, context, and scope already answered.
Question types: grill (a decision only you can make — the default) · research (a fact gates
it; background agents resolve these, several in parallel) · sketch (you need something concrete to
react to) · legwork (manual work that has to happen before a decision is possible).
It never answers its own questions, and it plans, it never builds. When the urge to just build it arrives, the map is done. Skip Step 0 entirely when you already know what you're building.
Out: specs/<feature>/pathfinder/map.md + questions/ (or a pathfinder:map issue and its
sub-issues) → PLAN-DRAFT-<date>.md. The draft is always a local file — that is what Step 1 reads.
The agent works as a senior architect through six phases, stopping for you after each: requirements analysis · system context (reading your actual codebase) · tech stack (needs your explicit sign-off) · architecture design · technical specification · transition decision.
It won't finalize below 90% confidence, and every assumption it makes is written into the draft.
In: a description of the feature. Out: PLAN-DRAFT-<date>.md + PLAN-CONVERSATION-<date>.md
The plan becomes the drawing. One overview.md with the phase checklist, plus one file per phase of
one-story-point tasks. Each phase is self-contained — an agent opening Phase 3.md cold needs
nothing else to build it. Unit and E2E tests are excluded unless you ask for them.
The overview also identifies the parallel execution groups: phases with no shared files or dependencies, safe to run in separate agents at once.
In: the PLAN-DRAFT. Out: overview.md + Phase 1…N.md
Point it at overview.md and it does the rest: finds the next unchecked phase, implements every task
exactly as specified, ticks tasks off as they land, then reviews its own work against the spec and
writes a completion summary.
One phase per conversation. It won't run tests unless the phase says to.
In: specs/<feature>/overview.md. Out: working code, and updated checkboxes.
An independent second opinion, not a rubber stamp. It figures out its own scope (conversation context, your instruction, or the git diff as a fallback), analyses across 11 dimensions, and ranks findings Critical / Warning / Suggestion. Every finding cites a file and a line, or it gets dropped — and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards.
Spec-aware when specs/ exists, and works fine without it. Most useful right after a planning or
implementation step, but there's no wrong time to run it.
Validates every task against its phase spec, writes the summary and the list of files touched, flags
the docs that drifted (README, CHANGELOG, AGENTS.md), then archives the whole spec folder —
pathfinder/ included — to specs--completed/. That folder is the record of why the code looks
like this.
In: specs/<feature>/overview.md. Out: archived specs.
| Step | Required input |
|---|---|
| 0 · Pathfinder | Nothing to start — just describe the idea. To continue: the feature name; it finds its own map |
| 1 · Plan | Nothing — describe the feature |
| 2 · Document | specs/<feature>/PLAN-DRAFT-<date>.md, or the planning conversation |
| 3 · Implement | specs/<feature>/overview.md — it detects the phase itself |
| Review | Scope guidance, e.g. "the last two phases", "just the auth module", "the whole PR". Auto-detects if you give none |
| 4 · Finalize | specs/<feature>/overview.md |
The skills aren't recognised. Re-run the installer and restart your AI tool. Confirm the global
install with npx skills list -g. For a project install, check the generated directories aren't
gitignored.
Your tool doesn't read Agent Skills. Since v2.2.0, Plan2Code ships only as skills. If your tool
has no skill support, paste the relevant src/plan2code-*.md manually or point it at the installed
copy under ~/.agents/skills/.
The agent starts coding during planning. The prompts forbid it, but models drift. Say: "Stay in planning mode. Do not write code yet."
The agent doesn't know what to implement. Give it the path to overview.md — it reads the phase
file itself from there.
You lost track between sessions. overview.md has the phase status; the phase files have the
task status. That's the whole state.
The agent isn't following the spec. Point at the specific phase document and tell it to re-read the requirements.
Too many or too few phases. Fix it in Step 2 — a phase should be a logical grouping of work, not a fixed size.
The prompts are yours to edit. Common changes: add testing requirements in Step 2, move the 90%
confidence threshold in Step 1, restructure the specs/ layout, or add review gates to Step 3.
Source files live in src/; run npm run build:skills, then re-run node install.js to push your
edits out through the skills CLI.
Core reference:
- QUICK-REFERENCE.md — the one-page card: commands, inputs, outputs, decision tree
- .readme/walkthrough.md — one feature from a sentence to archived specs, session by session
- AGENTS.md — architecture and contributor guide for this repo
- CHANGELOG.md — what changed, and why
Optional tooling — none of it is required to use the workflow:
- .readme/autonomous-loop.md —
plan2code-loop, a hands-off alternative to Step 3 - .readme/status-line.md — three-line Claude Code status bar: model, context, quota, diff
- .readme/metrics.md —
plan2code-metrics, measuring and improving the prompts themselves - .readme/test-bot.md —
plan2code-bot, maintainer harness that runs the whole workflow unattended