jparkerweb/plan2code
1
0
Fork 0
mirror of https://github.com/jparkerweb/plan2code.git synced 2026-09-17 16:22:23 -07:00
Code Issues Packages Projects Releases Wiki Activity

Redesign docs site and README around an airmail postcard theme

Browse Source 
Adds a postage-stamp favicon set and banner, removes three orphaned images,
and records the site and README as protected divergences so an upstream sync
can't revert them.

AI Assisted
This commit is contained in:
Justin Parker
2026-08-08 12:32:17 -07:00
parent fda0146969
commit 30860a7654
11 changed files with 630 additions and 1681 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/sync-repo/sync-repo.enc
+1 -1
View File
File diff suppressed because one or more lines are too long
README.md
+237 -483
View File
@@ -1,542 +1,296 @@
# Plan2Code: AI-Assisted Software Development Workflow
A structured 4-step workflow for developing features and projects with AI assistance. This methodology emphasizes thorough planning before implementation, ensuring well-documented, maintainable code.
# Plan2Code
<img src="docs/desk.jpg" alt="Plan2Code Workflow" height="275">
<img src="docs/banner.png" alt="Plan2Code — send the plan, the build follows" style="max-width:1024px;">
## Overview
**A spec-driven workflow for AI coding agents. Send the plan — the build follows.**
```
🤔 📝 ⚡ 🧹
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Step 1 │ │ Step 2 │ │ Step 3 │ │ Step 4 │
│ PLAN │ --> │ DOCUMENT │ --> │ IMPLEMENT │ --> │ FINALIZE │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
New Chat New Chat New Chat (per phase) New Chat
```
An AI agent is a fine builder and a terrible client. Plan2Code stops making it both: you approve a
plan, the plan becomes a set of phase documents in your repo, and the agent builds to those documents
one phase at a time. Progress lives in files instead of chat history — so the next session, the next
agent, and the next engineer all start from the same specs.
| Command | When to Use |
|----------------------------------|----------------------------------------------------------|
| `/plan2code-init` | Generate AGENTS.md file for new/existing projects |
| `/plan2code-init-update` | Update AGENTS.md with new learnings from coding sessions |
| `/plan2code-quick-task` | Small, quick tasks that don't need full workflow |
| `/plan2code-review` | Post-phase code review (after key features or milestones)|
| `/plan2code-1-plan` | Starting a new feature (full planning) |
| `/plan2code-1b-revise-plan` | Requirements change mid-implementation |
| `/plan2code-2-document` | After planning, create implementation specs |
| `/plan2code-3-implement` | Execute implementation (one phase per conversation) |
| `/plan2code-4-finalize` | All phases complete, ready to archive |
| `/plan2code-handoff` | Compact the conversation into a handoff doc for a fresh session |
Six commands, each posted separately. Two of them are optional.
**Key Rules:**
- Start NEW conversation for each step (and each implementation phase)
- ONE phase per conversation
- Reply "approved" to complete phases
- 90% confidence required before planning completes
See [QUICK-REFERENCE.md](QUICK-REFERENCE.md) for full reference card.
Version 2.0.0 · MIT · 📖 [plan2code.jparkerweb.com](https://plan2code.jparkerweb.com)
---
## Installation
## Install
Plan2Code includes an interactive installer that generates and installs workflow files for all major AI coding assistants.
<img src="docs/install-script.jpg" width="600">
### Prerequisites
The install script requires **Node.js** (v14 or later). If you don't have Node.js installed:
1. Download from [nodejs.org](https://nodejs.org/) (recommended)
2. Or use a package manager:
- **macOS:** `brew install node`
- **Windows:** `winget install OpenJS.NodeJS` or `choco install nodejs`
- **Linux:** `sudo apt install nodejs` (Debian/Ubuntu) or `sudo dnf install nodejs` (Fedora)
### Supported Platforms
- Claude Code
- Cursor
- Windsurf
- Continue
- Codeium (IntelliJ)
- GitHub Copilot CLI
- VS Code GitHub Copilot
- Gemini CLI
- Crush
- Pi (pi.dev)
- Amp
- OpenCode
- Devin
- Zed
### Install via npx (Recommended — No Clone Required)
Run the interactive installer directly using `npx` with your preferred GitHub authentication method:
Requires [Node.js](https://nodejs.org/) 14 or later. Re-run any time to update.
```bash
npx git+https://code.jparkerweb.com/jparkerweb/plan2code.git
npx --allow-git=all git+https://github.com/jparkerweb/plan2code.git
```
This downloads the installer to a temporary location, runs it, installs the workflow files to your machine, and cleans up automatically. The installed workflows remain on your system and work independently. To update or reinstall, simply run the command again.
This fetches the installer to a temp directory, runs it, writes the slash commands for whichever
tools you pick, and cleans up after itself. The installed commands work independently from then on.
### Standard Installation (Clone Method)
#### No Clone Required
Run the interactive installer directly using `npx` with your preferred GitHub authentication method:
```bash
npx git+https://code.jparkerweb.com/jparkerweb/plan2code.git
```
This downloads the installer to a temporary location, runs it, installs the workflow files to your machine, and cleans up automatically. The installed workflows remain on your system and work independently. To update or reinstall, simply run the command again.
#### Standard Installation (Clone Method)
```bash
# Clone the repository
git clone https://code.jparkerweb.com/jparkerweb/plan2code.git
cd plan2code
# Run the interactive installer
node install.js
# OPTIONAL: Install dev dependencies (ONLY if you plan to modify/contribute to Plan2Code)
npm install
```
The installer displays an interactive menu:
Either route lands you on the same menu:
```
╔════════════════════════════════════════════════════════════════╗
╔═════════════════════════════════════════════════════════╗
║ INSTALL PLAN2CODE ║
╠════════════════════════════════════════════════════════════════╣
╠═════════════════════════════════════════════════════════╣
║ I. INSTALL Install Plan2Code for all platforms ║
║ A. ALL Install Plan2Code + dev tools ║
║ U. UNINSTALL Remove Plan2Code files ║
║ C. CUSTOM Advanced options ║
║ Q. QUIT Exit ║
╚════════════════════════════════════════════════════════════════╝
SELECT OPTION (I, U, C, Q) [I]:
╚═════════════════════════════════════════════════════════╝
```
---
**Supported tools:** Claude Code · Cursor · Windsurf · Continue · Codeium (IntelliJ) ·
GitHub Copilot CLI · VS Code Copilot · Crush · Pi · Amp · OpenCode · Devin · Zed
## Status Line — Claude CLI (Optional)
A persistent three-line status bar for Claude Code showing model, project, git branch, uncommitted diff stats, context usage, and plan quota. Included in `node install.js` → `A` (Install All + dev tools), or available individually via Custom → Status Line. See [src/statusline-claude/README.md](src/statusline-claude/README.md) for details.
---
## Important: Start Fresh Conversations
**Start a new conversation/chat session before each step.** This includes:
- Step 1: New conversation
- Step 2: New conversation
- Step 3: New conversation **for each phase** (Phase 1, Phase 2, etc.)
- Step 4: New conversation
Fresh conversations prevent context pollution and ensure the AI focuses on the current task with the relevant specifications.
---
## The Workflow Steps
### Step 1: Planning Mode 🤔
**Purpose:** Thoroughly analyze requirements and design the solution architecture before writing any code.
**AI Role:** Senior software architect and technical product manager
**Phases (completed one at a time):**
1. **Requirements Analysis** - Extract functional/non-functional requirements, identify ambiguities
2. **System Context Examination** - Review existing codebase, identify integration points
3. **Tech Stack** - Recommend and confirm all technologies (requires user sign-off)
4. **Architecture Design** - Propose patterns, define components, design interfaces/schemas
5. **Technical Specification** - Break down implementation phases, identify risks
6. **Transition Decision** - Finalize plan when confidence reaches 90%+
**Output:** `specs/<feature-name>/PLAN-DRAFT-<date>.md` and `specs/<feature-name>/PLAN-CONVERSATION-<date>.md` (date format: YYYYMMDD)
**Key Behaviors:**
- AI stops after each phase for clarification
- Must reach 90% confidence before finalizing
- All assumptions are documented
- User must approve tech stack decisions
---
### Step 2: Documentation Mode 📝
**Purpose:** Transform the planning output into structured, actionable implementation documents.
**Required Context:** Attach or reference the `specs/<feature-name>/PLAN-DRAFT-<date>.md` from Step 1 (or provide the planning conversation).
**Output Structure:**
```
specs/
└── <feature-name>/
├── overview.md # High-level overview with phase checkboxes and parallel groups
├── Phase 1.md # Detailed tasks for Phase 1
├── Phase 2.md # Detailed tasks for Phase 2
└── Phase N.md # ...additional phases
```
The `overview.md` includes a "Parallel Execution Groups" section that identifies which phases can be run simultaneously in separate agent instances.
**Document Format:**
- Each phase file contains detailed one-story-point tasks
- All tasks have checkboxes `[ ]` for progress tracking
- Each phase is self-contained (developer needs no prior context)
- Unit/E2E testing excluded unless explicitly requested
---
### Step 3: Implementation Mode ⚡
**Purpose:** Execute the implementation following the documented specifications.
**AI Role:** Senior software engineer
**Required Context:** Provide the path to `specs/<feature-name>/overview.md`. The command will auto-detect the next uncompleted phase and read the corresponding `Phase X.md` file automatically.
**Workflow:**
1. Identify the next uncompleted phase (unchecked in `overview.md`)
2. Check for parallel execution options (if phases can run simultaneously)
3. Implement ALL tasks in that phase exactly as specified
4. Update `Phase X.md` checkboxes as tasks complete `[x]`
5. Update `overview.md` phase checkbox when phase completes
6. Perform code review to ensure nothing was missed
7. Add completion summary to the phase document
**Parallel Execution:** If the next phase is part of a parallel-eligible group, you'll be prompted to choose which phase to implement. This allows running multiple agent instances simultaneously on different phases that don't conflict with each other.
**Key Rules:**
- **Start a new conversation for EACH phase**
- Work on ONE phase per conversation (unless told otherwise)
- Follow specifications EXACTLY as documented
- Keep checkboxes updated (enables progress tracking across sessions)
- Do NOT run tests unless specified in phase tasks
---
### Review Mode 🔬 (Optional)
**Purpose:** Comprehensive post-implementation code review with adaptive scope and spec compliance checking.
**AI Role:** Critical review specialist -- independent second opinion
**When to use:** After completing implementation phases, especially key features or milestones. Can be run after any phase, not just before finalization.
**What it does:**
1. Determines review scope — detects conversation context, user-specified scope, or gathers git changes as fallback
2. Understands context and determines review strategy
3. Analyzes across 11 dimensions (correctness, security, performance, spec compliance, etc.)
4. Generates findings ranked by severity (Critical, Warning, Suggestion)
5. Offers to fix issues, then provides commit guidance
**Key Behaviors:**
- Uses companion reference files for deep verification, detailed dimension checklists, and false-positive detection (loaded automatically during review)
- Reviews all changed files across 11 dimensions; prioritizes by risk when batches exceed 50 files
- Spec-aware when `specs/` exists; works standalone without specs
- Review phase is read-only; fixes only on user request with verification
---
### Step 4: Finalization Mode 🧹
**Purpose:** Validate implementation, create summaries, and archive documentation.
**Required Context:** Attach or reference the `specs/<feature-name>/` directory contents.
**Steps:**
1. **Validation** - Verify all tasks implemented correctly, check for issues
2. **Summary** - Document what was built and list all modified/created files
3. **Documentation Review** - Identify any needed README/CHANGELOG updates
4. **Spec Cleanup** - Move completed specs to `specs--completed/<implementation-name>/`
5. **Final Confirmation** - Confirm completion
---
## How to Use
After running `node install.js`, use the slash commands directly in your AI tool:
```
/plan2code-1-plan # Start planning a new feature
/plan2code-2-document # Create implementation docs from plan
/plan2code-3-implement # Begin/continue implementation
/plan2code-review # Post-phase code review (optional)
/plan2code-4-finalize # Wrap up after all phases complete
```
---
## Complete Workflow Example
### Starting a New Project
**Session 1 - Planning (New Chat):**
```
User: [Paste or invoke Step 1 prompt]
I want to build a REST API for a task management application.
AI: 🤔 [REQUIREMENTS ANALYSIS]
... asks clarifying questions, works through phases ...
AI: 🤔 [TRANSITION DECISION]
Confidence: 92%. Creating specs/task-api/PLAN-DRAFT-20250204.md...
```
**Session 2 - Documentation (New Chat):**
```
User: [Paste or invoke Step 2 prompt]
[Attach: specs/task-api/PLAN-DRAFT-20250204.md]
AI: 📝 [DOCUMENTATION]
Creating specs/task-api/overview.md...
Creating specs/task-api/Phase 1.md...
Creating specs/task-api/Phase 2.md...
...
```
**Session 3 - Implementation Phase 1 (New Chat):**
```
User: [Paste or invoke Step 3 prompt]
[Provide: specs/task-api/overview.md]
AI: ⚡ [PHASE 1: Project Setup]
(Auto-detected Phase 1 as next uncompleted phase)
Implementing tasks...
✓ Phase 1 complete. Updated checkboxes in Phase 1.md and overview.md.
```
**Session 4 - Implementation Phase 2 (New Chat):**
```
User: [Paste or invoke Step 3 prompt]
[Provide: specs/task-api/overview.md]
AI: ⚡ [PHASE 2: Database Models]
(Auto-detected Phase 2 as next uncompleted phase)
Implementing tasks...
✓ Phase 2 complete. Updated checkboxes in Phase 2.md and overview.md.
```
**Sessions 5-N - Continue Implementation (New Chat for each phase):**
```
... repeat for each remaining phase ...
```
**Final Session - Finalization (New Chat):**
```
User: [Paste or invoke Step 4 prompt]
[Provide: specs/task-api/overview.md]
AI: 🧹 [VALIDATION]
Verifying implementation...
AI: 🧹 [SPEC CLEANUP]
Moving to specs--completed/task-api/
Implementation complete!
```
---
## Progress Tracking
The checkbox system enables seamless progress tracking across multiple sessions:
**Phase Status (overview.md):**
| Checkbox | Status | Meaning |
|----------|--------|---------|
| `[ ]` | Pending | Not yet started |
| `[/]` | In Progress | Agent actively working (or paused/aborted) |
| `[x]` | Complete | Finished and approved |
```markdown
## Phases
- [x] Phase 1: Project Setup
- [x] Phase 2: Database Models
- [/] Phase 3: API Endpoints <- In progress (agent working)
- [ ] Phase 4: Authentication <- Next available
```
**Task Status (phase-X.md):**
```markdown
## Tasks
- [x] Create routes file
- [x] Implement GET /tasks
- [ ] Implement POST /tasks <- Current task
- [ ] Implement PUT /tasks/:id
- [ ] Implement DELETE /tasks/:id
```
The `[/]` status enables parallel execution - multiple agents can work on different phases simultaneously, and you can see which phases are actively being worked on.
---
## Best Practices
1. **Start fresh conversations** - New chat for each step and each implementation phase
2. **Always attach specs** - The AI needs the spec files to understand the current state
3. **Don't skip planning** - The upfront investment prevents costly rework later
4. **Confirm tech stack** - Ensure AI gets explicit approval before architecture design
5. **One phase at a time** - Keeps conversations focused and manageable
6. **Update checkboxes immediately** - Maintains accurate progress state
7. **Review phase output** - Verify each phase before moving to the next
8. **Keep spec files** - The completed folder serves as project documentation
---
## What to Attach at Each Step
| Step | Required Input |
| ------------------ | ---------------------------------------------------- |
| Step 1 (Plan) | None (describe your feature/project) |
| Step 2 (Document) | `specs/<feature>/PLAN-DRAFT-<date>.md` or planning conversation |
| Step 3 (Implement) | `specs/<feature>/overview.md` (auto-detects phase) |
| Review (Optional) | Scope guidance (e.g., "review last 2 phases", "just the auth module", "whole PR"). Auto-detects changes and specs if no scope given. |
| Step 4 (Finalize) | `specs/<feature>/overview.md` |
---
## Autonomous Loop (Alternative to Step 3)
For hands-off implementation, Plan2Code includes an optional autonomous loop CLI that iterates through your spec tasks automatically.
> **Note:** The loop is an **alternative** to `/plan2code-3-implement`, not a replacement. Use the manual Step 3 workflow when you want direct control over each phase, or use the loop when you prefer autonomous execution.
### When to Use Each
| Approach | Best For |
|----------|----------|
| `/plan2code-3-implement` | Interactive control, reviewing each phase, complex logic requiring human judgment |
| `plan2code-loop` | Straightforward implementations, batch processing, overnight runs |
### Installing the Loop
<details>
<summary>Prefer to clone?</summary>
```bash
# From the plan2code root directory:
git clone https://github.com/jparkerweb/plan2code.git
cd plan2code
node install.js
# Option 1: Install everything (recommended)
node install.js # Select I at the menu
# Option 2: Install loop only
node install.js # Select C, then O at the menu
# Only if you plan to modify or contribute to Plan2Code itself
npm install && npx husky
```
### Using the Loop
```bash
# Run the loop - fully interactive
plan2code-loop
```
The CLI will:
1. Auto-detect specs in `./specs/` directory
2. Let you select a spec if multiple are found
3. Prompt to continue if an existing session is found
4. Ask for JIRA ticket ID, agent selection, loop mode, and max iterations
### Loop Modes
| Mode | Behavior | Git Commits | Best For |
|------|----------|-------------|----------|
| **One task per loop** (default) | Each agent call implements one task | Node controller commits after each task | Smaller models, cautious execution |
| **One phase per loop** | Each agent call implements all tasks in a phase | LLM commits after each task (with JIRA ID) | Smart models with larger context windows, related tasks |
Session state is stored per-spec in `specs/<feature>/.plan2code-loop/`, keeping each feature's progress isolated.
The loop will:
1. Read your `overview.md` and phase files
2. Find the first unchecked task (or phase, in phase mode)
3. Implement it and mark the checkbox complete
4. Repeat until all tasks are done or max iterations reached
See [plan2code-loop/](plan2code-loop/) for full documentation.
</details>
---
## File Structure After Complete Implementation
## The workflow
```
┌╴╴╴╴╴╴╴╴╴╴╴╴┐
╎0 PATHFINDER╎ optional · new in 2.0 · for an idea too big or unclear to plan
└╴╴╴╴╴╴┬╴╴╴╴╴┘
▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌╴╴╴╴╴╴╴╴╴╴╴╴┐ ┌────────────┐
│ 1 PLAN │─>│ 2 DOCUMENT │─>│3 IMPLEMENT │─>╎ REVIEW ╎─>│ 4 FINALIZE │
│decide what │ │ draw it as │ │build to the│ ╎ optional ╎ │verify, sum,│
│ to build │ │phase specs │ │ drawing │ ╎ any time ╎ │ archive │
└────────────┘ └────────────┘ └────────────┘ └╴╴╴╴╴╴╴╴╴╴╴╴┘ └────────────┘
new chat new chat new chat/phase new chat new chat
├◀─────────────── one feature, start to archive ──────────────────▶┤
```
Every box is its own conversation. That is not a style preference — planning context leaking into
implementation is where most agent drift starts.
| Command | Use it when |
|---------|-------------|
| `/plan2code-0-pathfinder` | The idea is too big and unclear to plan. Charts it as decisions, clears one per session, hands a hot plan draft to Step 1 |
| `/plan2code-1-plan` | Starting a feature. Full requirements → architecture pass |
| `/plan2code-2-document` | Planning is done. Turn the plan into phase specs |
| `/plan2code-3-implement` | Build the next phase (one per conversation) |
| `/plan2code-review` | Independent second opinion on local changes, then optional fixes |
| `/plan2code-4-finalize` | All phases done. Validate, summarize, archive |
| `/plan2code-init` | Generate this repo's `AGENTS.md` so every agent starts informed |
| `/plan2code-init-update` | Fold what you learned this session back into `AGENTS.md` |
| `/plan2code-quick-task` | A small change that doesn't warrant the full sequence |
| `/plan2code-1b-revise-plan` | Requirements moved mid-build. Revise the specs, not the code |
| `/plan2code-handoff` | Compact this conversation into a doc the next one resumes from |
---
## The four rules that do most of the work
**1 · A fresh conversation for each step, and each implementation phase.**
Step 3 gets a new chat per phase, not one chat for all of them.
**2 · No code until the plan hits 90% confidence.**
Step 1 will not finalize below the threshold. Under it, the agent keeps asking and keeps reading your
code — and writes every assumption down where you can argue with it.
**3 · Checkboxes are the state, not the chat.**
Progress lives in the spec files. Any agent, any session, resumes cold from them.
**4 · Reply `approved` to close a phase.**
Nothing advances on a guess about what you meant.
---
## What lands in your repo
```
your-project/
├── specs/
│ └── another-feature/ # In-progress feature
│ ├── overview.md
│ └── Phase 1.md
│ └── task-api/ ← in progress
│ ├── pathfinder/ ← only if you charted it in Step 0
│ │ ├── map.md the destination, the decisions, the fog
│ │ └── questions/NN-<slug>.md one decision per file
│ ├── PLAN-DRAFT-20260804.md ← Step 1: the verified plan
│ ├── PLAN-CONVERSATION-*.md ← Step 1: how you got there
│ ├── overview.md ← Step 2: phase list + parallel groups
│ └── Phase 1.md … Phase N.md ← Step 2: one-point tasks, self-contained
├── specs--completed/
│ └── feature-name/
│ ├── overview.md # Archived with completion summary
│ ├── Phase 1.md # All checkboxes marked [x]
│ ├── Phase 2.md
│ └── ...
├── your project files...
└── README.md
│ └── auth-refresh/ ← Step 4 files finished work here
└── ...your code
```
`specs/` is gitignored by default — it's your working drawing, not a deliverable. Share a folder
deliberately with `git add -f` when you want to.
### Progress marks
| Mark | Status | Meaning |
|------|--------|---------|
| `[ ]` | Open | Unclaimed. Any agent picks it up cold. |
| `[/]` | In progress | Claimed right now — which is how two agents run parallel phases without colliding. |
| `[x]` | Done | Built, self-reviewed against the spec, approved by you. |
```markdown
## Phases
- [x] Phase 1: Project setup
- [x] Phase 2: Data model
- [/] Phase 3: API endpoints ← an agent is on this now
- [ ] Phase 4: Authentication ← next available
```
Step 2 marks which phases don't share files. Open a second agent on one of those, and the `[/]` marks
keep the two out of each other's way.
---
## Customization
## The six steps in detail
Feel free to modify these prompts to fit your workflow:
Each one travels on its own — a fresh conversation, opened and closed, with the specs on disk as the
only thing carried between them.
- **Add testing phases** - Uncomment/add testing requirements in Step 2
- **Adjust confidence threshold** - Change the 90% threshold in Step 1
- **Modify output structure** - Customize the specs folder organization
- **Add code review steps** - Enhance Step 3 with additional review gates
### 0 · Pathfinder 🧭 — optional, new in 2.0
Some ideas are too big and unclear to plan: you can feel the shape of the work but you can't write
it as requirements, so planning would just invent the answers. Pathfinder finds the *way* to the
destination; Step 1 then walks it.
1. **Name the destination** — one or two lines fixing what this effort is finding its way to. Settled
first, because it fixes scope.
2. **Chart the map** — a breadth-first grilling surfaces the open decisions. Anything you can phrase
*sharply* becomes a question file; anything you can only sense stays listed as fog.
3. **Clear one question per session** — resolving a question burns off the fog behind it, graduating
whatever just became sharp into new questions.
4. **Hand off** — when nothing is left to decide, it writes a `PLAN-DRAFT` that
`/plan2code-1-plan` resumes from at Phase 4, with requirements, context, and scope already
answered.
**Question types:** `grill` (a decision only you can make — the default) · `research` (a fact gates
it; background agents resolve these, several in parallel) · `sketch` (you need something concrete to
react to) · `legwork` (manual work that has to happen before a decision is possible).
It never answers its own questions, and it **plans, it never builds.** When the urge to just build it
arrives, the map is done. Skip Step 0 entirely when you already know what you're building.
**Out:** `specs/<feature>/pathfinder/map.md` + `questions/` → `PLAN-DRAFT-<date>.md`
### 1 · Plan 🤔
The agent works as a senior architect through six phases, stopping for you after each: requirements
analysis · system context (reading your actual codebase) · tech stack (needs your explicit sign-off) ·
architecture design · technical specification · transition decision.
It won't finalize below **90% confidence**, and every assumption it makes is written into the draft.
**In:** a description of the feature. **Out:** `PLAN-DRAFT-<date>.md` + `PLAN-CONVERSATION-<date>.md`
### 2 · Document 📝
The plan becomes the drawing. One `overview.md` with the phase checklist, plus one file per phase of
one-story-point tasks. Each phase is **self-contained** — an agent opening `Phase 3.md` cold needs
nothing else to build it. Unit and E2E tests are excluded unless you ask for them.
The overview also identifies the **parallel execution groups**: phases with no shared files or
dependencies, safe to run in separate agents at once.
**In:** the `PLAN-DRAFT`. **Out:** `overview.md` + `Phase 1…N.md`
### 3 · Implement ⚡
Point it at `overview.md` and it does the rest: finds the next unchecked phase, implements every task
exactly as specified, ticks tasks off as they land, then reviews its own work against the spec and
writes a completion summary.
One phase per conversation. It won't run tests unless the phase says to.
**In:** `specs/<feature>/overview.md`. **Out:** working code, and updated checkboxes.
### Review 🔬 — optional, any time
An independent second opinion, not a rubber stamp. It figures out its own scope (conversation
context, your instruction, or the git diff as a fallback), analyses across 11 dimensions, and ranks
findings Critical / Warning / Suggestion. Every finding cites a file and a line, or it gets dropped —
and the review pass is read-only. It fixes things only if you ask, and verifies each fix afterwards.
Spec-aware when `specs/` exists, and works fine without it. Most useful right after a planning or
implementation step, but there's no wrong time to run it.
### 4 · Finalize 🧹
Validates every task against its phase spec, writes the summary and the list of files touched, flags
the docs that drifted (`README`, `CHANGELOG`, `AGENTS.md`), then archives the whole spec folder —
`pathfinder/` included — to `specs--completed/`. That folder is the record of *why* the code looks
like this.
**In:** `specs/<feature>/overview.md`. **Out:** archived specs.
---
## What to bring to each step
| Step | Required input |
|------|----------------|
| 0 · Pathfinder | Nothing to start — just describe the idea. To continue: the feature name; it finds its own map |
| 1 · Plan | Nothing — describe the feature |
| 2 · Document | `specs/<feature>/PLAN-DRAFT-<date>.md`, or the planning conversation |
| 3 · Implement | `specs/<feature>/overview.md` — it detects the phase itself |
| Review | Scope guidance, e.g. "the last two phases", "just the auth module", "the whole PR". Auto-detects if you give none |
| 4 · Finalize | `specs/<feature>/overview.md` |
---
## Troubleshooting
**Slash commands/workflows not recognized:**
**Slash commands aren't recognised.** Re-run `node install.js` for that platform and restart your AI
tool. For a per-project install, check the directory isn't gitignored.
- Ensure you ran `node install.js` and selected the appropriate platform
- Restart your AI tool after installation
- For per-project installation, ensure the directory isn't in `.gitignore`
**The agent starts coding during planning.** The prompts forbid it, but models drift. Say: "Stay in
planning mode. Do not write code yet."
**AI jumps ahead to implementation during planning:**
**The agent doesn't know what to implement.** Give it the path to `overview.md` — it reads the phase
file itself from there.
- The prompts explicitly forbid this, but if it happens, remind the AI: "Stay in planning mode. Do not write code yet."
**You lost track between sessions.** `overview.md` has the phase status; the phase files have the
task status. That's the whole state.
**AI doesn't know what to implement:**
**The agent isn't following the spec.** Point at the specific phase document and tell it to re-read
the requirements.
- Make sure you provided the path to `overview.md`
- The AI will auto-detect the next phase and read the corresponding `Phase X.md` file
**Too many or too few phases.** Fix it in Step 2 — a phase should be a logical grouping of work, not
a fixed size.
**Lost progress between sessions:**
---
- Check `overview.md` for phase status
- Review individual phase files for task completion status
## Customizing
**AI not following spec exactly:**
The prompts are yours to edit. Common changes: add testing requirements in Step 2, move the 90%
confidence threshold in Step 1, restructure the `specs/` layout, or add review gates to Step 3.
Source files live in `src/`; re-run `node install.js` to push your edits out to every platform.
- Reference the specific phase document and ask it to re-read the requirements
---
**Too many/few phases:**
## Dive deeper
- Adjust during Step 2 (Documentation) - phases should represent logical groupings of work
Core reference:
- **[QUICK-REFERENCE.md](QUICK-REFERENCE.md)** — the one-page card: commands, inputs, outputs, decision tree
- **[.readme/walkthrough.md](.readme/walkthrough.md)** — one feature from a sentence to archived specs, session by session
- **[AGENTS.md](AGENTS.md)** — architecture and contributor guide for this repo
- **[CHANGELOG.md](CHANGELOG.md)** — what changed, and why
Optional tooling — none of it is required to use the workflow:
- **[.readme/autonomous-loop.md](.readme/autonomous-loop.md)** — `plan2code-loop`, a hands-off alternative to Step 3
- **[.readme/status-line.md](.readme/status-line.md)** — three-line Claude Code status bar: model, context, quota, diff
- **[.readme/metrics.md](.readme/metrics.md)** — `plan2code-metrics`, measuring and improving the prompts themselves
- **[.readme/test-bot.md](.readme/test-bot.md)** — `plan2code-bot`, maintainer harness that runs the whole workflow unattended
docs/apple-touch-icon.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.1 KiB

docs/banner.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

docs/desk.jpg
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 185 KiB

docs/favicon.ico
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 1.9 KiB

docs/favicon.png
BIN
View File
Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.4 KiB

After

Width:  |  Height:  |  Size: 584 B

docs/favicon.svg
+33
View File
@@ -0,0 +1,33 @@
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Plan2Code postage stamp">
<defs>
<!-- Perforated stamp silhouette: white keeps, black bites out.
Few, deep notches so the scalloped edge still reads at 16px. -->
<mask id="perf">
<rect width="64" height="64" fill="#000"/>
<rect x="2" y="2" width="60" height="60" fill="#fff"/>
<g fill="#000">
<circle cx="2" cy="2" r="5"/><circle cx="14" cy="2" r="5"/><circle cx="26" cy="2" r="5"/>
<circle cx="38" cy="2" r="5"/><circle cx="50" cy="2" r="5"/><circle cx="62" cy="2" r="5"/>
<circle cx="2" cy="62" r="5"/><circle cx="14" cy="62" r="5"/><circle cx="26" cy="62" r="5"/>
<circle cx="38" cy="62" r="5"/><circle cx="50" cy="62" r="5"/><circle cx="62" cy="62" r="5"/>
<circle cx="2" cy="14" r="5"/><circle cx="2" cy="26" r="5"/>
<circle cx="2" cy="38" r="5"/><circle cx="2" cy="50" r="5"/>
<circle cx="62" cy="14" r="5"/><circle cx="62" cy="26" r="5"/>
<circle cx="62" cy="38" r="5"/><circle cx="62" cy="50" r="5"/>
</g>
</mask>
</defs>
<g mask="url(#perf)">
<!-- printed stamp -->
<rect x="2" y="2" width="60" height="60" fill="#D33A38"/>
<!-- the 2, set as a franking-machine numeral -->
<g fill="#FBFAF6">
<rect x="16" y="13" width="32" height="8"/>
<rect x="40" y="13" width="8" height="22"/>
<rect x="16" y="27" width="32" height="8"/>
<rect x="16" y="27" width="8" height="24"/>
<rect x="16" y="43" width="32" height="8"/>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 1.6 KiB

docs/index.html
+369 -1207
View File
File diff suppressed because it is too large Load Diff
docs/install-script.jpg
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 147 KiB

docs/plan2code.jpg
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 95 KiB