2026-05-23 06:58:20 -07:00
# Plan2Code Quick Reference
2025-12-23 15:42:35 -08:00
2026-10-08 17:02:40 -07:00
## Before you start
- **Node.js 18 or newer.** Check with `node --version` . No Node? Get it from [nodejs.org ](https://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.
- **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.
2026-10-02 20:51:34 -07:00
## 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 |
| ------------------------- | ------------------------------------ | -------------------------------------------------------------------------------------- |
2026-10-08 17:02:40 -07:00
| 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 |
2026-10-03 09:38:55 -07:00
| Install / update | `npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git` | Installs the skills and the `plan2code` command; re-run it to update |
2026-10-02 20:51:34 -07:00
| Straight into a skill | `/plan2code-1-plan --web` (any step) | Skips the "web console or terminal?" question and opens the page |
Pick a skill on the dashboard and the same page becomes that session. Details: [.readme/web-console.md ](.readme/web-console.md ) · worked example: [.readme/walkthrough.md ](.readme/walkthrough.md ).
2025-12-23 15:42:35 -08:00
## Commands
2026-10-02 20:51:34 -07:00
Every command below is what a dashboard card runs. Typed on its own, each one asks "web console or terminal?" first.
2026-10-07 23:18:40 -07:00
| 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-<date>.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-<date>.md + PLAN-DRAFT-<date>.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/` ) |
2026-10-08 07:22:26 -07:00
| changelog | /plan2code-changelog | Your branch | `CHANGELOG.md` entries and the `package.json` version, from the default branch's latest version |
2026-10-07 23:18:40 -07:00
| git-commit | /plan2code-git-commit | Your changes | A commit (`<subject>` / `AI Assisted` ): suggested splits, a branch offer on the default branch, optional push |
2026-09-28 19:37:41 -07:00
2026-10-02 20:51:34 -07:00
**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.
2025-12-23 15:42:35 -08:00
## File Structure
```
specs/
└── <feature-name>/
2026-08-08 19:00:26 -07:00
├── pathfinder/ # From Step 0 (optional, if charted locally)
2026-08-08 12:39:29 -07:00
│ ├── map.md # the map: destination, decisions, fog
2026-09-03 07:18:34 -07:00
│ ├── questions/NN-<slug>.md # one decision question per file
2026-09-28 19:37:41 -07:00
│ └── briefs/brief-<date>.md # on-demand plain-English decision briefs
2026-08-08 19:00:26 -07:00
│ # (GitHub Issues backend: map issue + sub-issues instead)
2026-02-17 09:13:23 -08:00
├── 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
2025-12-23 15:42:35 -08:00
2026-02-17 09:13:23 -08:00
specs--completed/ # After Step 4
└── <feature-name>/ # Archived specs
2025-12-23 15:42:35 -08:00
```
2026-02-17 09:13:23 -08:00
Note: `<date>` uses YYYYMMDD format (e.g., `20250204` )
2025-12-23 15:42:35 -08:00
## Key Rules
2026-10-02 20:51:34 -07:00
- Keep sessions short: fresh console session when the meter turns red, and before a big plan or build step
2026-01-27 12:11:00 -08:00
- ONE phase per conversation (but parallel phases can run in separate instances)
2026-10-02 20:51:34 -07:00
- Approve phases on the sign-off card (or reply "approved" in the terminal)
2025-12-23 15:42:35 -08:00
- 90% confidence required before planning completes
- Never look in `specs--completed/` (it's archived specs)
2026-01-27 12:11:00 -08:00
## Phase Status
2026-02-03 20:32:18 -08:00
2026-01-27 12:11:00 -08:00
| Checkbox | Status | Meaning |
|----------|--------|---------|
| `[ ]` | Pending | Not started |
| `[/]` | In Progress | Agent working (or paused) |
| `[x]` | Complete | Approved |
2026-10-03 09:38:55 -07:00
| `[!]` | Blocked | Couldn't be done; the line says why and what you need to do |
| `[?]` | Assumed | Couldn't be verified, assumed complete; check it |
2026-02-03 20:32:18 -08:00
2026-01-27 12:11:00 -08:00
## Parallel Execution
2026-02-03 20:32:18 -08:00
2026-01-27 12:11:00 -08:00
When phases have no file conflicts or dependencies, they can run simultaneously:
2026-02-03 20:32:18 -08:00
2026-01-27 12:11:00 -08:00
1. Documentation Mode auto-detects parallel-eligible phases
2026-10-02 20:51:34 -07:00
2. Implementation Mode asks which phase to take (a card on the web console), with the status of each
2026-05-23 06:58:20 -07:00
3. Run multiple `/plan2code-3-implement` instances on different phases
2026-01-27 12:11:00 -08:00
4. `[/]` status shows which phases are actively being worked on
2026-02-03 20:32:18 -08:00
2025-12-23 15:42:35 -08:00
## Quick Troubleshooting
2026-09-28 19:37:41 -07:00
| Issue | Solution |
| ---------------------- | ------------------------------------------------ |
| Lost context mid-phase | Attach spec files, say "resume from Task X.Y" |
| Wrong phase started | Say "abort", start correct phase |
2026-05-23 06:58:20 -07:00
| Need to change plan | Use `/plan2code-1b-revise-plan` |
2026-09-28 19:37:41 -07:00
| 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 |
2025-12-23 15:42:35 -08:00
## Workflow Decision
```
New to a project?
2026-05-23 06:58:20 -07:00
└── /plan2code-init → Generate AGENTS.md for project-specific guidance
2025-12-23 15:42:35 -08:00
Learned something during a session?
2026-05-23 06:58:20 -07:00
└── /plan2code-init-update → Add learnings to AGENTS.md
2025-12-23 15:42:35 -08:00
2026-09-28 19:37:41 -07:00
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
2026-08-08 12:39:29 -07:00
└── then → /plan2code-1-plan (resumes at Phase 4)
2025-12-23 15:42:35 -08:00
Is it a quick, small task?
2026-05-23 06:58:20 -07:00
├── Yes → /plan2code-quick-task (standalone)
└── No → /plan2code-1-plan (full workflow)
├── /plan2code-2-document
├── /plan2code-3-implement (repeat per phase)
2026-09-28 19:37:41 -07:00
│ ├── OR: /plan2code-3-implement-review (review gate before approval)
2026-01-27 12:11:00 -08:00
│ └── OR: plan2code-loop (autonomous alternative)
2026-05-23 06:58:20 -07:00
└── /plan2code-4-finalize
2025-12-23 15:42:35 -08:00
Need to revise mid-implementation?
2026-05-23 06:58:20 -07:00
└── /plan2code-1b-revise-plan
2025-12-23 15:42:35 -08:00
```
2026-02-03 20:32:18 -08:00
2026-01-27 12:11:00 -08:00
## Autonomous Loop (Alternative)
2026-02-03 20:32:18 -08:00
2026-10-03 09:38:55 -07:00
`plan2code-loop` is a hands-off alternative to Step 3. See [.readme/autonomous-loop.md ](.readme/autonomous-loop.md ).