# 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.
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)
#### No Clone Required
Run the interactive installer directly using `npx` with your preferred GitHub authentication method:
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.
**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
---
### Step 3b: 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
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
**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
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 |
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.
---
## File Structure After Complete Implementation
```
your-project/
├── specs/
│ └── another-feature/ # In-progress feature
│ ├── overview.md
│ └── Phase 1.md
├── 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
```
---
## Customization
Feel free to modify these prompts to fit your workflow:
