Plan2Code

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.0.0 · MIT · 📖 plan2code.jparkerweb.com

---

Install

Requires Node.js 14 or later. Re-run any time to update.

npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git

This fetches the installer to a temp directory, runs it, writes the slash commands for whichever tools you pick, and cleans up after itself. The installed commands work independently from then on.

Either route lands you on the same menu:

╔═════════════════════════════════════════════════════════╗
║ INSTALL PLAN2CODE                                       ║
╠═════════════════════════════════════════════════════════╣
║  I.  INSTALL    Install Plan2Code for all platforms     ║
║  A.  ALL        Install Plan2Code + dev tools           ║
║  U.  UNINSTALL  Remove Plan2Code files                  ║
║  C.  CUSTOM     Advanced options                        ║
║  Q.  QUIT       Exit                                    ║
╚═════════════════════════════════════════════════════════╝

Supported tools: Claude Code · Cursor · Windsurf · Continue · Codeium (IntelliJ) · GitHub Copilot CLI · VS Code Copilot · Crush · Pi · Amp · OpenCode · Devin · Zed

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

---

The workflow

 ┌╴╴╴╴╴╴╴╴╴╴╴╴┐
 ╎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 one per session, 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

---

The four rules that do most of the work

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.

---

What lands in your repo

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
│       ├── 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.

Progress marks

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 available

Step 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.

---

The six steps in detail

Each one travels on its own — a fresh conversation, opened and closed, with the specs on disk as the only thing carried between them.

0 · Pathfinder 🧭 — optional, new in 2.0

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.

1. Name the destination — one or two lines fixing what this effort is finding its way to. Settled first, because it fixes scope.
2. 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.
3. Clear one question per session — resolving a question burns off the fog behind it, graduating whatever just became sharp into new questions.
4. Hand off — when nothing is left to decide, it writes a PLAN-DRAFT that /plan2code-1-plan resumes 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/ → PLAN-DRAFT-<date>.md

1 · Plan 🤔

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

2 · Document 📝

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

3 · Implement ⚡

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.

Review 🔬 — optional, any time

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.

4 · Finalize 🧹

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.

---

What to bring to each step

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

---

Troubleshooting

Slash commands aren't recognised. Re-run node install.js for that platform and restart your AI tool. For a per-project install, check the directory isn't gitignored.

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.

---

Customizing

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/; re-run node install.js to push your edits out to every platform.

---

Dive deeper

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