mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-07-21 18:33:22 -07:00
jparkerweb
68542fd778
- Make plan2code-handoff an installed workflow prompt: move to src/, register in install.js SOURCE_PROMPTS, remove repo-local-only copy - Add repo-local maintainer /plan2code-publish skill (cuts GitHub Releases; excluded from install.js) - Review workflow next-step suggestion made context-aware (upstream v1.15.4) - Doc updates: list handoff in README, QUICK-REFERENCE, architecture table; add "Adding a New Workflow Prompt / Skill" checklist to dev-commands - Fix broken AGENTS.md index links: rename .agents-docs loop/metrics files to plan2code-* to match references - Bump version.json to 1.16.0 to align with package.json and CHANGELOG
113 lines
4.6 KiB
Markdown
113 lines
4.6 KiB
Markdown
# 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-quick-task | Requirements | Conversational plan |
|
|
| 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>/
|
|
├── 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
|
|
|
|
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/`
|