plan2code/QUICK-REFERENCE.md

Plan2Code Quick Reference

Commands

Step	Command	Input	Output
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 + PLAN-DRAFT-.md
quick	/plan2code-quick-task	Requirements	Conversational plan (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
4	/plan2code-4-finalize	overview.md	Archived specs
handoff	/plan2code-handoff	Conversation	Self-contained handoff doc in handoffs/

File Structure

specs/
└── <feature-name>/
    ├── pathfinder/                   # From Step 0 (optional, if charted)
    │   ├── map.md                    #   the map: destination, decisions, fog
    │   └── questions/NN-<slug>.md    #   one decision question per file
    ├── 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

• Start NEW conversation for each step (and each implementation phase)
• ONE phase per conversation (but parallel phases can run in separate instances)
• Reply "approved" to complete phases
• 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

Parallel Execution

When phases have no file conflicts or dependencies, they can run simultaneously:

1. Documentation Mode auto-detects parallel-eligible phases
2. Implementation Mode shows selection UI with status for each phase
3. Run multiple /plan2code-3-implement instances on different phases
4. [/] 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 unclaer to plan? (big idea, don't yet know what the questions are)
└── /plan2code-0-pathfinder → chart it, clear one decision per session
    └── 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-loop (autonomous alternative)
         └── /plan2code-4-finalize

Need to revise mid-implementation?
└── /plan2code-1b-revise-plan

Autonomous Loop (Alternative)

The plan2code-loop CLI is an alternative to Step 3, not a replacement.

Approach	Use When
/plan2code-3-implement	You want interactive control per phase
plan2code-loop	You want hands-off autonomous execution

plan2code-loop   # Fully interactive - auto-detects specs, prompts for options

Loop Modes

Mode	Description
One task per loop (default)	One task per agent invocation. Node handles git commits.
One phase per loop	All tasks in a phase per invocation. LLM handles git commits. Best for smart models with larger context.

Session state stored per-spec in specs/<feature>/.plan2code-loop/