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 *or* GitHub Issues + PLAN-DRAFT-<date>.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-<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                                   |
| 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 locally)
    │   ├── map.md                    #   the map: destination, decisions, fog
    │   └── questions/NN-<slug>.md    #   one decision question per file
    │                                 #   (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

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

```bash
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/`