11 KiB
Plan2Code Quick Reference
Before you start
- Node.js 18 or newer. Check with
node --version. No Node? Get it from nodejs.org (the LTS download), or runwinget install OpenJS.NodeJS.LTSon Windows,brew install nodeon macOS, or usenvmon Linux. Then open a new terminal. - Start from your project. Open your terminal in the project you want to work on (
cdinto it) before you run anything. Plan2Code works on the folder you start it in. - Ways in.
plan2code(Claude Code, Devin or Codex), or type/plan2codein your agent ($plan2codein Codex). - No agent yet? Install Claude Code, Codex or Devin first, or let the
plan2codecommand's setup page walk you through it.
Launch
The web console is the main way in: a local page where questions, documents, build progress and sign-offs live.
| How | Command | What happens |
|---|---|---|
| From your project (shell) | plan2code |
Opens Claude Code, Devin or Codex on the dashboard (--cli claude / devin / codex to choose) |
| Inside any agent | /plan2code ($plan2code in Codex) |
Opens the dashboard: a card for every skill, launched on the same page |
| Install | npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git |
Installs the skills and the plan2code command (re-run it to update without the plan2code command) |
| Update | plan2code update |
Updates the skills, command, app and status line, with no menu (metrics and the bot only from a git checkout: node install.js); never uninstalls anything |
| Uninstall | plan2code uninstall |
Removes the skills, command, app and dev tools after a Y/N; then asks whether ~/.plan2code/ (your notebooks, handoffs, settings) goes too. --yes skips the questions and keeps your data, --purge deletes it |
| Straight into a skill | /plan2code-1-plan --web (any step) |
Skips the "web console or terminal?" question and opens the page |
The install command always opens a menu. Back at your prompt with no output at all? npm could not reach the repository and hid the reason: run git ls-remote https://github.com/jparkerweb/plan2code.git to see it (usually the network, a proxy or the VPN).
Pick a skill on the dashboard and the same page becomes that session. Details: .readme/web-console.md · worked example: .readme/walkthrough.md.
The Notebook icon in the top bar opens a private scratch pad for the folder you are in (Markdown and pictures, kept in ~/.plan2code/notepads/). Private: the agent never reads your Notebook. A tab reaches it only when you start a workflow with it.
Commands
Every command below is what a dashboard card runs. Typed on its own, each one asks "web console or terminal?" first.
| Step | Command | Input | Output |
|---|---|---|---|
| — | /plan2code | None | Web console dashboard — a menu of every skill below, launched on the page |
| Init | /plan2code-init | None | AGENTS.md file |
| Update | /plan2code-init-update | AGENTS.md | Updated AGENTS.md |
| 0 | /plan2code-0-pathfinder | A foggy idea | pathfinder/map.md or GitHub Issues + PLAN-DRAFT-.md |
| quick | /plan2code-quick-task | Requirements | A short plan, then the change built (standalone, not a pipeline step) |
| review | /plan2code-review | Scope guidance | Review findings + fixes |
| 1 | /plan2code-1-plan | Requirements | PLAN-CONVERSATION-.md + PLAN-DRAFT-.md |
| 1b | /plan2code-1b-revise-plan | Specs + changes | Updated specs |
| 2 | /plan2code-2-document | PLAN-DRAFT.md | overview.md + Phase files |
| 3 | /plan2code-3-implement | overview.md | Implemented code |
| 3+review | /plan2code-3-implement-review | overview.md | Reviewed implementation ready for approval (alternative to /plan2code-3-implement) |
| 4 | /plan2code-4-finalize | overview.md | Archived specs |
| handoff | /plan2code-handoff | Conversation | Self-contained handoff doc (OS temp dir by default, or a folder you pick such as handoffs/) |
| xray | /plan2code-xray | An area, or none | An explanation citing files and commits, or ARCHITECTURE-BRIEF-<date>.md with the rough spots you picked |
| diagnose | /plan2code-diagnose | A bug, or none | DIAGNOSIS-<date>.md with the cause and its evidence, then Quick Task (or Plan for a big fix) to fix it |
| pr-prep | /plan2code-pr-prep | Your branch | A readiness verdict (Ready, Ready with notes, Not ready) and a PR description to copy; no commits, no push |
| test | /plan2code-test | An area, or none | New unit and integration tests in the project's style, run; a bug handed to Diagnose; no source changes |
| changelog | /plan2code-changelog | Your branch | CHANGELOG.md entries and the package.json version, from the default branch's latest version |
| git | /plan2code-git | Your repo | Commits (<subject> / AI Assisted), branches, pull with conflict help, push, publish |
Terminal instead: run any command without --web and answer the interface question with terminal. Nothing is lost: same questions, same gates, same files under specs/. You can switch between the two mid-feature.
File Structure
specs/
└── <feature-name>/
├── pathfinder/ # From Step 0 (optional, if charted locally)
│ ├── map.md # the map: destination, decisions, fog
│ ├── questions/NN-<slug>.md # one decision question per file
│ └── briefs/brief-<date>.md # on-demand plain-English decision briefs
│ # (GitHub Issues backend: map issue + sub-issues instead)
├── PLAN-DRAFT-<date>.md # From Step 1 (verified plan)
├── PLAN-CONVERSATION-<date>.md # From Step 1 (conversation log)
├── overview.md # From Step 2
└── phase-X.md # From Step 2
specs--completed/ # After Step 4
└── <feature-name>/ # Archived specs
Note: <date> uses YYYYMMDD format (e.g., 20250204)
Key Rules
- Keep sessions short: fresh console session when the meter turns red, and before a big plan or build step
- ONE phase per conversation (but parallel phases can run in separate instances)
- Approve phases on the sign-off card (or reply "approved" in the terminal)
- 90% confidence required before planning completes
- Never look in
specs--completed/(it's archived specs)
Phase Status
| Checkbox | Status | Meaning |
|---|---|---|
[ ] |
Pending | Not started |
[/] |
In Progress | Agent working (or paused) |
[x] |
Complete | Approved |
[!] |
Blocked | Couldn't be done; the line says why and what you need to do |
[?] |
Assumed | Couldn't be verified, assumed complete; check it |
Parallel Execution
When phases have no file conflicts or dependencies, they can run simultaneously:
- Documentation Mode auto-detects parallel-eligible phases
- Implementation Mode asks which phase to take (a card on the web console), with the status of each
- Run multiple
/plan2code-3-implementinstances on different phases [/]status shows which phases are actively being worked on
Quick Troubleshooting
| Issue | Solution |
|---|---|
| Lost context mid-phase | Attach spec files, say "resume from Task X.Y" |
| Wrong phase started | Say "abort", start correct phase |
| Need to change plan | Use /plan2code-1b-revise-plan |
| Multiple spec folders | Specify which: "Continue with specs/user-auth/" |
| Need AGENTS.md file | Use /plan2code-init to generate one |
| Update AGENTS.md | Use /plan2code-init-update after sessions |
| Run phases in parallel | Check Parallel Execution Groups in overview.md |
Workflow Decision
New to a project?
└── /plan2code-init → Generate AGENTS.md for project-specific guidance
Learned something during a session?
└── /plan2code-init-update → Add learnings to AGENTS.md
Too foggy to plan? (big idea, don't yet know what the questions are)
└── /plan2code-0-pathfinder → chart it, clear one decision at a time
├── continue-or-stop menu between decisions; fresh session recommended after ~3
└── then → /plan2code-1-plan (resumes at Phase 4)
Is it a quick, small task?
├── Yes → /plan2code-quick-task (standalone)
└── No → /plan2code-1-plan (full workflow)
├── /plan2code-2-document
├── /plan2code-3-implement (repeat per phase)
│ └── OR: /plan2code-3-implement-review (review gate before approval)
└── /plan2code-4-finalize
Need to revise mid-implementation?
└── /plan2code-1b-revise-plan