Files
plan2code/.readme/walkthrough.md
T

9.4 KiB

Walkthrough: one feature, start to finish

A REST API for task management goes from a sentence to archived specs, all on the web console. Each session stays short, and the specs on disk carry everything from one session to the next.

← Back to README


Before you start

  • Node.js 18 or newer. Check with node --version. No Node? Get it from nodejs.org (the LTS download), or run winget install OpenJS.NodeJS.LTS on Windows, brew install node on macOS, or use nvm on Linux. Then open a new terminal.
  • Git. Check with git --version. The installer is fetched from GitHub with Git, and without it npm stops with spawn git ENOENT. No Git? Get it from git-scm.com, or run winget install Git.Git on Windows, brew install git on macOS, or use your package manager on Linux. Then open a new terminal.
  • Start from your project. Open your terminal in the project you want to work on (cd into it) before you run anything. Plan2Code works on the folder you start it in.
  • Ways in. plan2code (Claude Code, Devin or Codex), or type /plan2code in your agent ($plan2code in Codex).
  • No agent yet? Install Claude Code, Codex or Devin first, or let the plan2code command's setup page walk you through it.

Not installed yet? The install steps are in the README.

Running plan2code with no agent installed opens a setup page instead of a dashboard: it lists each built-in as found, found outside PATH or not found, with its install commands for your system and an Install page link. Install one, press Check again, then Start with this agent and the run carries on in the same tab. On a machine with no browser (over SSH, a server) it prints the install steps instead and exits with code 127. The rest of this walkthrough assumes an agent is already in place.


Session 1: Plan

Run plan2code in the project (or /plan2code inside your agent). The dashboard opens in your browser with every step laid out as a card.

The Plan2Code dashboard: a Set up card, then the steps in order as cards, one of them marked Suggested.

Pick Plan and describe the idea in the box: I want to build a REST API for a task management application. The same page turns into the Plan session.

The questions arrive in batches of up to three, each option with its trade-off written underneath. Answer what is there and press Send to Plan2Code; the next batch follows.

A Plan question card, How tasks are paged, with three options, the first marked Suggested, each with its trade-off underneath.

The phase breakdown comes back as a list you can reorder and edit. Documents a skill writes on the page open as tabs like this one, where settled parts read as decisions and anything still a guess is marked as assumed and still open.

The What we've agreed tab for the task API: a settled summary, an assumed section on paging with a dashed edge, and a dimmed draft list of what is still to work out.

Plan proposes a tech stack, Fastify + Postgres + Zod, and does not pick it alone: a sign-off card asks you to approve it. Plan then designs the architecture. At 92% confidence (the gate is 90%) it asks whether to write the draft, and with 3 assumptions written down, it writes:

specs/task-api/PLAN-DRAFT-20260804.md

Two files land: the draft, and a PLAN-CONVERSATION-*.md log of how you got there. The finish card names the next step.

Started foggy instead? Run /plan2code-0-pathfinder first. When its map clears it writes a PLAN-DRAFT that Plan picks up at Phase 4, with requirements and scope already answered.


Session 2: Document

On Plan's finish card, press Back to the dashboard (or start a fresh console session if the session meter says so; see Session 3 below). Pick Document, with specs/task-api selected in the picker at the top. It reads specs/task-api/PLAN-DRAFT-20260804.md.

The overview and each phase file appear as tabs as they are written, so you watch the spec take shape:

specs/task-api/overview.md
specs/task-api/phase-1.md   Project setup           (6 tasks)
specs/task-api/phase-2.md   Data model              (8 tasks)
specs/task-api/phase-3.md   API endpoints          (11 tasks)
specs/task-api/phase-4.md   Authentication          (7 tasks)

Parallel execution groups: Phase 3 and Phase 4 don't share files.


Sessions 3 to N: Implement, one phase each

Look at the session meter in the top bar first. Plan and Document add 2 points each, so after those two the meter is at 4: Session: getting long, in yellow. That is the cue to close this console session and start a fresh one for the build (run plan2code again). This is the first of the four rules:

1 · Keep each session short. Chaining a couple of small skills on the dashboard is fine. Start a fresh console session when the session meter turns red, and always before a big planning or build step. The specs on disk carry everything between sessions.

On the fresh dashboard, pick Implement for specs/task-api. Phase 1 (Project setup) is the next unchecked phase, so it starts there. The page shows the build as it goes: a progress bar counting tasks, the phase's task list ticking as each task lands on disk, and a line beside Planny saying what it is doing now. Use the Ask tab for a quick question without interrupting the build.

A phase of a task API being built: 5 of 11 done on the progress bar, and the phase's task list with the first five ticked.

When all 6 of 6 tasks are ticked in phase-1.md, a Completion report tab opens with the sign-off card: Review the code first, Approve this phase, or I want changes.

The Approve this phase card, with a button to read the completion report and three choices: Review the code first, Approve this phase, and I want changes.

After you approve, overview.md marks Phase 1 done, and the finish card gives the next command: Phase 2, Data model (8 tasks), in a new session.

The finished screen after a phase sign-off: the phase is built, the next implement command with a Copy button, and a Back to the dashboard button.

Repeat. A fresh session each time. It always finds the next open phase itself.

When you reach a parallel group, it offers you the choice: open a second agent, take the other phase, and the [/] marks keep them from colliding.

Pick Implement + review instead when review should run automatically before phase approval. Review remains available on the dashboard for an independent second opinion at any other time.


Final session: Finalize

With every phase approved, the dashboard suggests Finalize for specs/task-api. Pick it in a fresh session. Each check lands on the page as a report tab, and anything that needs your say is a card:

  • Validation. All 32 tasks verified against the phase specs. 2 gaps found and fixed.
  • Documentation review. README needs the new /tasks endpoints; AGENTS.md is current. A card lists the proposed doc updates, and you tick the ones to make.
  • Spec cleanup. A confirm card, then specs/task-api/ moves to specs--completed/task-api/.

The finish card says the implementation is complete, and gives the commit command when doc updates landed.


If requirements move mid-build

Don't patch the code and hope the specs catch up. Pick Revise the plan on the dashboard: it edits the specs (and only the specs), so the drawing and the build stay in agreement.


Prefer the terminal?

The same journey is four commands, each in a new conversation:

  1. /plan2code-1-plan with the idea in a sentence. Writes specs/task-api/PLAN-DRAFT-20260804.md.
  2. /plan2code-2-document specs/task-api/PLAN-DRAFT-20260804.md. Writes the overview and phase files.
  3. /plan2code-3-implement specs/task-api/overview.md, once per phase. It finds the next open phase itself.
  4. /plan2code-4-finalize specs/task-api/overview.md. Verifies, updates docs, and archives the spec.

Add --web to any of them (for example /plan2code-1-plan --web) to open that step straight on the web console without being asked. Every command and argument is in the README's Prefer the terminal? section. You can switch between terminal and console at any point, because the files under specs/ are the only state.

More