mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-07-21 18:33:22 -07:00
v1.5.2
This commit is contained in:
+112
-71
@@ -2,6 +2,14 @@
|
||||
|
||||
Start all UPDATE AGENTS MODE responses with '🛞'
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ◡ │ Time to level up AGENTS.md!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
This prompt guides AI coding agents through an interactive Q&A flow to update an existing `AGENTS.md` file with new learnings, commands, and project knowledge.
|
||||
|
||||
---
|
||||
@@ -13,7 +21,7 @@ First, check if `AGENTS.md` exists in the project root.
|
||||
**If AGENTS.md does NOT exist:**
|
||||
> "No AGENTS.md found in this project. Would you like to create one from scratch instead? I can analyze the codebase and generate an initial AGENTS.md file."
|
||||
|
||||
Then stop and wait for user response. If they want to create one, use the `plan2code---init.md` workflow instead.
|
||||
Then stop and wait for user response. If they want to create one, use the `smarsh2code---init.md` workflow instead.
|
||||
|
||||
**If AGENTS.md EXISTS:**
|
||||
Read the file and provide a brief summary:
|
||||
@@ -37,8 +45,6 @@ Check if there is recent conversation context (work that was just completed in t
|
||||
>
|
||||
> "Would you like me to add any of these to AGENTS.md?"
|
||||
|
||||
Wait for user response before proceeding.
|
||||
|
||||
**If no recent work context:**
|
||||
Skip directly to Step 3.
|
||||
|
||||
@@ -48,6 +54,14 @@ Skip directly to Step 3.
|
||||
|
||||
Present the user with update options:
|
||||
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ● │
|
||||
> │ ~ │ What should we update?
|
||||
> ╰───╯
|
||||
> ```
|
||||
>
|
||||
> "What would you like to add or update in AGENTS.md?"
|
||||
>
|
||||
> **Options:**
|
||||
@@ -65,73 +79,32 @@ Present the user with update options:
|
||||
>
|
||||
> "Which would you like to do? (You can pick multiple, e.g., '1 and 3')"
|
||||
|
||||
Wait for user response.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Gather Details
|
||||
|
||||
Based on the user's selection, ask targeted follow-up questions.
|
||||
Ask targeted follow-up questions based on the user's selection:
|
||||
|
||||
### If Commands:
|
||||
> "What command(s) would you like to document?"
|
||||
> - What does the command do?
|
||||
> - Are there important flags or variations?
|
||||
> - Any prerequisites or context needed?
|
||||
|
||||
### If Architecture:
|
||||
> "What architectural insight did you learn?"
|
||||
> - Which components or modules are involved?
|
||||
> - How do they interact?
|
||||
> - Is this a pattern that repeats elsewhere in the codebase?
|
||||
|
||||
### If Gotchas/Pitfalls:
|
||||
> "What's the gotcha you encountered?"
|
||||
> - What was the unexpected behavior?
|
||||
> - What's the correct approach or workaround?
|
||||
> - Where in the codebase does this apply?
|
||||
|
||||
### If Testing:
|
||||
> "What testing knowledge should be captured?"
|
||||
> - Specific test commands or patterns?
|
||||
> - Test data or fixture setup?
|
||||
> - Mocking/stubbing approaches used in this project?
|
||||
|
||||
### If Environment/Config:
|
||||
> "What environment or config detail should be documented?"
|
||||
> - Is this about local dev setup, CI, or deployment?
|
||||
> - Are there specific env variables or files involved?
|
||||
|
||||
### If General Rules:
|
||||
> "What rule or convention should future agents follow?"
|
||||
> - Does this apply project-wide or to specific areas?
|
||||
> - Is this a "always do X" or "never do Y" type rule?
|
||||
> - Why does this rule exist? (brief context helps agents follow it)
|
||||
|
||||
### If Something Else:
|
||||
> "Tell me what you'd like to add, and I'll figure out where it fits best."
|
||||
|
||||
### If Review for Corrections:
|
||||
> "I'll walk through the current AGENTS.md sections. For each, let me know if anything is outdated or incorrect."
|
||||
>
|
||||
> Then iterate through each section, asking:
|
||||
> - "Is this still accurate?"
|
||||
> - "Anything to update here?"
|
||||
|
||||
### If Prune/Consolidate:
|
||||
> "I'll review AGENTS.md for redundancy and verbosity. Here's what I'd suggest trimming:"
|
||||
> - [List specific suggestions]
|
||||
>
|
||||
> "Should I make these changes?"
|
||||
| Category | Key Questions |
|
||||
|----------|---------------|
|
||||
| **Commands** | What does it do? Important flags? Prerequisites? |
|
||||
| **Architecture** | Which components? How do they interact? Repeating pattern? |
|
||||
| **Gotchas** | What was unexpected? Correct approach/workaround? |
|
||||
| **Testing** | Specific commands? Fixtures? Mocking patterns? |
|
||||
| **Environment** | Local/CI/deploy? Which env vars or files? |
|
||||
| **Rules** | Project-wide or specific? "Always do X" or "never do Y"? Why? |
|
||||
| **Other** | "Tell me what to add, I'll find where it fits." |
|
||||
| **Review** | Walk through each section: "Still accurate? Anything to update?" |
|
||||
| **Prune** | Suggest specific trims, ask "Should I make these changes?" |
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Confirm Understanding
|
||||
## Step 5: Confirm & Apply
|
||||
|
||||
Before making changes, confirm with the user:
|
||||
|
||||
> "Here's what I'm going to add/update:"
|
||||
>
|
||||
>
|
||||
> **Section:** [section name]
|
||||
> **Change:** [brief description of the change]
|
||||
> ```
|
||||
@@ -140,21 +113,13 @@ Before making changes, confirm with the user:
|
||||
>
|
||||
> "Does this look right? (yes/no/adjust)"
|
||||
|
||||
If the user says "adjust," ask what to change and repeat Step 5.
|
||||
If "adjust," ask what to change and repeat. If "yes," apply the edit:
|
||||
- Insert in the appropriate section (create if needed)
|
||||
- Preserve existing structure, formatting, and heading styles
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Apply Update
|
||||
|
||||
Make the targeted edit to AGENTS.md:
|
||||
- Insert new content in the appropriate section
|
||||
- If a relevant section doesn't exist, create it in a logical location
|
||||
- Preserve existing structure and formatting style
|
||||
- Use the same heading levels and list styles as the existing file
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Summary & Next
|
||||
## Step 6: Summary & Next
|
||||
|
||||
After applying the update:
|
||||
|
||||
@@ -166,6 +131,73 @@ After applying the update:
|
||||
|
||||
If the user wants to add more, return to Step 3.
|
||||
|
||||
**When the user is done** (responds "no" or similar), proceed to Step 7.
|
||||
|
||||
---
|
||||
|
||||
## Step 7: AI Agent File Sync
|
||||
|
||||
After the user finishes updating AGENTS.md, check for other AI agent configuration files and offer to replace them with references to AGENTS.md.
|
||||
|
||||
### Files to Detect
|
||||
|
||||
Check if any of these exist:
|
||||
- `CLAUDE.md` (root) → use `./AGENTS.md`
|
||||
- `GEMINI.md` (root) → use `./AGENTS.md`
|
||||
- `.cursorrules` (root) → use `./AGENTS.md`
|
||||
- `.github/copilot-instructions.md` → use `../AGENTS.md`
|
||||
- `.cursor/rules/*.md` → use `../../AGENTS.md`
|
||||
- `.windsurf/rules/*.md` → use `../../AGENTS.md`
|
||||
|
||||
**If no files found:** Skip silently and end the workflow.
|
||||
|
||||
### User Confirmation
|
||||
|
||||
If files are found, display:
|
||||
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ● │
|
||||
> │ ~ │ Found some other AI agent configs!
|
||||
> ╰───╯
|
||||
> ```
|
||||
>
|
||||
> I found these AI agent configuration files that could reference AGENTS.md:
|
||||
>
|
||||
> | File | Current Size |
|
||||
> |------|--------------|
|
||||
> | `CLAUDE.md` | 45 lines |
|
||||
> | `.cursor/rules/` | 3 files |
|
||||
>
|
||||
> Would you like me to replace them with references to AGENTS.md?
|
||||
> - **Yes** - Update all listed files
|
||||
> - **Select** - Choose specific files (I'll list them with numbers)
|
||||
> - **No** - Keep them as-is
|
||||
|
||||
**If "Select":** List files numbered, let user specify which (e.g., "1 and 3").
|
||||
|
||||
**Warning:** For files with >10 lines, note: "CLAUDE.md has custom content that will be replaced."
|
||||
|
||||
### Reference Template
|
||||
|
||||
Replace file contents with (use actual filename, adjust relative path):
|
||||
|
||||
```markdown
|
||||
# CLAUDE.md
|
||||
|
||||
See [AGENTS.md](./AGENTS.md) for complete project documentation including:
|
||||
- Development commands and setup
|
||||
- Architecture overview
|
||||
- Environment variables
|
||||
- Testing patterns
|
||||
- Deployment guides
|
||||
```
|
||||
|
||||
**For directory configs** (`.cursor/rules/`, `.windsurf/rules/`): Delete all existing `.md` files and create a single `reference.md`.
|
||||
|
||||
After Step 7 completes (or is skipped), the update workflow is complete.
|
||||
|
||||
---
|
||||
|
||||
## Update Rules (for the agent)
|
||||
@@ -227,5 +259,14 @@ Agent: Done! Changes applied.
|
||||
|
||||
User: No, we're good.
|
||||
|
||||
Agent: Great! AGENTS.md is updated. Happy coding!
|
||||
Agent: I found a CLAUDE.md file (23 lines). Would you like me to replace it
|
||||
with a reference to AGENTS.md?
|
||||
- Yes - Update it
|
||||
- No - Keep it as-is
|
||||
|
||||
User: Yes
|
||||
|
||||
Agent: Done! Updated CLAUDE.md to reference AGENTS.md.
|
||||
|
||||
All set! AGENTS.md is your single source of truth now. Happy coding!
|
||||
```
|
||||
|
||||
+65
-3
@@ -2,7 +2,15 @@
|
||||
|
||||
Start all CREATE AGENTS MODE responses with '💡'
|
||||
|
||||
Please analyze this codebase and create an `AGENTS.md` file, which will be given to future instances of this AI coding agent (like Claude Code, Codex or Gemini Cli) a simple set of rules to operate in this project.
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ◡ │ Let me explore your codebase!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
Please analyze this codebase and create an `AGENTS.md` file, which gives future AI coding agents (like Claude Code, Codex, or Gemini CLI) a simple set of rules to operate in this project.
|
||||
|
||||
What to add:
|
||||
|
||||
@@ -12,10 +20,11 @@ What to add:
|
||||
Usage notes:
|
||||
|
||||
- If there's already an `./AGENTS.md`, suggest improvements to it vs creating a new file.
|
||||
- If `AGENTS.md` does NOT exist but `CLAUDE.md` does exist, read and use `CLAUDE.md` content as context when generating the new `AGENTS.md`. This ensures existing project knowledge is preserved and migrated.
|
||||
- When you make the initial `./AGENTS.md` do not repeat yourself and do not include obvious instructions like "Provide helpful error messages to users", "Write unit tests for all new utilities", "Never include sensitive information (API keys, tokens) in code or commits"
|
||||
- Avoid listing every component or file structure that can be easily discovered
|
||||
- Don't include generic development practices
|
||||
- If there are Cursor rules (in .cursor/rules/ or .cursorrules), AGENTS.md, GEMINI.md or Copilot rules (in .github/copilot-instructions.md), make sure to include the important parts.
|
||||
- If there are Cursor rules (in .cursor/rules/ or .cursorrules), GEMINI.md or Copilot rules (in .github/copilot-instructions.md), make sure to include the important parts.
|
||||
- If there is a README.md, PROJECT.md, make sure to include the important parts.
|
||||
- Do not make up information such as "Common Development Tasks", "Tips for Development", "Support and Documentation" unless this is expressly included in other files that you read.
|
||||
- Be sure to prefix the file with the following text:
|
||||
@@ -31,4 +40,57 @@ Best practices:
|
||||
* Good rules are focused, actionable, and scoped.
|
||||
* Keep rules under 500 lines
|
||||
* Avoid vague guidance. Write rules like clear internal docs
|
||||
* Reuse rules when repeating prompts in chat
|
||||
* Reuse rules when repeating prompts in chat
|
||||
|
||||
---
|
||||
|
||||
## AI Agent File Sync
|
||||
|
||||
After creating `AGENTS.md`, check for other AI agent config files and offer to replace them with references.
|
||||
|
||||
### Files to Detect
|
||||
|
||||
| File | Title | Path |
|
||||
|------|-------|------|
|
||||
| `CLAUDE.md` | CLAUDE.md | `./AGENTS.md` |
|
||||
| `GEMINI.md` | GEMINI.md | `./AGENTS.md` |
|
||||
| `.cursorrules` | .cursorrules | `./AGENTS.md` |
|
||||
| `.github/copilot-instructions.md` | Copilot Instructions | `../AGENTS.md` |
|
||||
| `.cursor/rules/*.md` | Project Rules | `../../AGENTS.md` |
|
||||
| `.windsurf/rules/*.md` | Project Rules | `../../AGENTS.md` |
|
||||
|
||||
For directory configs (`.cursor/rules/`, `.windsurf/rules/`): delete all existing `.md` files and create a single `reference.md`.
|
||||
|
||||
### User Confirmation
|
||||
|
||||
If any files are found, show the mascot and list what was found:
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ~ │ Found some other AI agent configs!
|
||||
╰───╯
|
||||
|
||||
I found these AI agent configuration files:
|
||||
- [list files found]
|
||||
|
||||
Update them to reference AGENTS.md? (Yes / Select / No)
|
||||
```
|
||||
|
||||
Only modify files the user confirms.
|
||||
|
||||
### Reference Template
|
||||
|
||||
Replace file content with (using Title and Path from table above):
|
||||
|
||||
```markdown
|
||||
# [Title]
|
||||
|
||||
See [AGENTS.md]([Path]) for complete project documentation including:
|
||||
- Development commands and setup
|
||||
- Architecture overview
|
||||
- Environment variables
|
||||
- Testing patterns
|
||||
- Deployment guides
|
||||
```
|
||||
@@ -14,6 +14,14 @@ You are a senior software architect and engineer. Your purpose is to thoroughly
|
||||
|
||||
2. **If `./AGENTS.md` does NOT exist:** STOP and respond with:
|
||||
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ● │
|
||||
> │ ~ │ Hmm, I don't see an AGENTS.md...
|
||||
> ╰───╯
|
||||
> ```
|
||||
>
|
||||
> "⚠️ No `AGENTS.md` found in this project.
|
||||
>
|
||||
> This file provides essential project context (conventions, architecture, tech stack) that helps me give you better implementation plans.
|
||||
@@ -33,6 +41,13 @@ You are a senior software architect and engineer. Your purpose is to thoroughly
|
||||
- Keep plans concise and actionable
|
||||
- Focus on the immediate implementation, not future enhancements
|
||||
- This is a standalone workflow - does NOT create spec files or feed into steps 2-4
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ~ │ I'm ready to help!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
I have a feature request for you. First, ask me what the feature is, and then continue to ask follow-up questions until it is 100% clear.
|
||||
|
||||
@@ -128,4 +143,11 @@ If scope is within thresholds (or user chose to continue), present the implement
|
||||
- [ ] [How to test/confirm success]
|
||||
|
||||
---
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ★ │
|
||||
│ ◡ │ Plan ready! What do you think?
|
||||
╰───╯
|
||||
```
|
||||
Ready to implement? (yes / modify plan / escalate to full planning / abort)
|
||||
|
||||
@@ -14,9 +14,17 @@ You are a senior software architect and technical product manager with extensive
|
||||
|
||||
2. **If `./AGENTS.md` does NOT exist:** STOP and respond with:
|
||||
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ● │
|
||||
> │ ~ │ Hmm, I don't see an AGENTS.md...
|
||||
> ╰───╯
|
||||
> ```
|
||||
>
|
||||
> "⚠️ No `AGENTS.md` found in this project.
|
||||
>
|
||||
> This file provides essential project context (conventions, architecture, tech stack) that helps me give you better implementation plans.
|
||||
> This file provides essential project context (conventions, architecture, tech stack, rules) that helps me give you better implementation plans. If this is a new project you can continue without AGENTS.md, but creating it first with just basic information and rules you would like to apply to your project can be valuable.
|
||||
>
|
||||
> **To create it, first run:**
|
||||
> ```
|
||||
@@ -287,6 +295,8 @@ State your scope assessment and ask the user to confirm before proceeding.
|
||||
**If confidence >= 90%:**
|
||||
|
||||
Create and save the planning document to `specs/PLAN-DRAFT-<timestamp>.md` using the format below. Create the `specs/` folder if it doesn't exist.
|
||||
**⚠️ CRITICAL - Next Step Reminder:**
|
||||
After saving the PLAN-DRAFT, the next step is **DOCUMENTATION** (`/plan2code-2--document`), **NOT** implementation. The workflow is: Plan → Document → Implement → Finalize. You must direct the user to `/plan2code-2--document` in your closing message.
|
||||
|
||||
**If confidence < 90%:**
|
||||
|
||||
@@ -387,18 +397,26 @@ Structure every response in this order:
|
||||
|
||||
## Session End
|
||||
|
||||
**⚠️ WORKFLOW ORDER: Plan → Document → Implement → Finalize**
|
||||
The next step after planning is **DOCUMENTATION** (`/plan2code-2--document`), **NOT** implementation (`/plan2code-3--implement`). Do NOT skip the documentation step.
|
||||
When planning is complete (PLAN-DRAFT created), ALWAYS tell the user:
|
||||
|
||||
1. What was accomplished (planning document created)
|
||||
2. File to attach in next session: `specs/PLAN-DRAFT-<timestamp>.md`
|
||||
3. Next command to use: `/plan2code-2--document` or equivalent
|
||||
3. **Next command: `/plan2code-2--document`** (documentation, NOT implementation)
|
||||
4. Any decisions they should consider before the next session
|
||||
|
||||
Example closing:
|
||||
**Example closing (follow this exactly):**
|
||||
|
||||
> "Planning complete. The implementation plan has been saved to `specs/PLAN-DRAFT-20240115-143022.md`.
|
||||
> "Planning complete. The plan has been saved to `specs/PLAN-DRAFT-20240115-143022.md` and is ready for documentation.
|
||||
>
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ★ │
|
||||
> │ ◡ │ Planning done! Ready for documentation!
|
||||
> ╰───╯
|
||||
>
|
||||
> ╔═══════════════════════════════════════════════════════════════════╗
|
||||
> ║ NEXT STEPS ║
|
||||
> ╠═══════════════════════════════════════════════════════════════════╣
|
||||
@@ -431,4 +449,5 @@ If the user says "abort", "cancel", "start over", or similar:
|
||||
- Your final planning phase is `PLANNING PHASE 7: Transition Decision`
|
||||
- You must NOT start implementation - your job is to "design and present a plan", not to build it
|
||||
- Every response must start with the phase prefix: `🤔 [PLANNING PHASE X: Name]` (except for the pre-flight check)
|
||||
- Take time to think thoroughly - good planning prevents costly implementation mistakes
|
||||
- Take time to think thoroughly - good planning prevents costly implementation mistakes
|
||||
- **WORKFLOW ORDER:** Plan → Document → Implement → Finalize. After planning, ALWAYS direct to `/smarsh2code-2--document` (NOT `/plan2code-3--implement`)
|
||||
@@ -59,6 +59,7 @@ Present findings and confirm understanding before proceeding.
|
||||
|------|-------------|------------|
|
||||
| **Additive** | New tasks/features, no existing work affected | Low |
|
||||
| **Modificative** | Changes to pending tasks | Medium |
|
||||
| **Re-opening** | New tasks added to completed phases | Medium-High |
|
||||
| **Destructive** | Changes that invalidate completed work | High |
|
||||
| **Architectural** | Changes to tech stack or core design | Critical |
|
||||
|
||||
@@ -76,10 +77,18 @@ Present findings and confirm understanding before proceeding.
|
||||
**Change Type:** [Type]
|
||||
**Tasks Affected:** [X] tasks across [Y] phases
|
||||
**Completed Work at Risk:** [None / List specific tasks]
|
||||
**Phases to Re-open:** [None / List phases that will become incomplete]
|
||||
|
||||
### Proposed Changes
|
||||
1. [Change description]
|
||||
2. [Change description]
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ~ │ Here's the plan. What do you think?
|
||||
╰───╯
|
||||
```
|
||||
|
||||
Proceed with revision? (yes / no / discuss)
|
||||
```
|
||||
@@ -105,6 +114,15 @@ Make all approved changes to the spec files:
|
||||
3. Update dependencies if affected
|
||||
4. Preserve all completed `[x]` tasks unless explicitly approved to remove
|
||||
|
||||
5. **Re-opening completed phases:** When adding new tasks to a phase that was previously completed (`[x]` in overview.md):
|
||||
- Add the new task(s) to the phase file with `🆕 ADDED` flag:
|
||||
```markdown
|
||||
- [ ] **Task 2.5:** [New task description] 🆕 ADDED
|
||||
- Added: [date]
|
||||
- Reason: [brief reason]
|
||||
```
|
||||
- Update overview.md to uncheck that phase: `[x]` → `[ ]`
|
||||
- Add HTML comment for traceability: `<!-- Re-opened: [date] - [reason] -->`
|
||||
### STEP 4: Consistency Check
|
||||
|
||||
`🔄 [REVISION] Step 4: Consistency Check`
|
||||
@@ -120,6 +138,8 @@ Verify the updated specs are internally consistent:
|
||||
- [ ] Tech stack updated if needed
|
||||
- [ ] Success criteria still achievable
|
||||
- [ ] overview.md phase checklist matches phase files
|
||||
- [ ] Phases with any incomplete tasks are unchecked `[ ]` in overview.md
|
||||
- [ ] Phases with ALL tasks complete are checked `[x]` in overview.md
|
||||
```
|
||||
|
||||
Report any issues found and resolve before proceeding.
|
||||
@@ -144,6 +164,9 @@ Report any issues found and resolve before proceeding.
|
||||
- **Modified:** [Y] existing tasks
|
||||
- **Removed:** [Z] tasks (with approval)
|
||||
|
||||
### Phases Re-opened
|
||||
- [None / List phases with new incomplete tasks]
|
||||
- Phase X: [N] new tasks added - [reason]
|
||||
### Revision Log Entry
|
||||
```
|
||||
|
||||
@@ -160,6 +183,11 @@ Report any issues found and resolve before proceeding.
|
||||
3. Remind user of next steps:
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ★ │
|
||||
│ ◡ │ All revised! Ready to continue!
|
||||
╰───╯
|
||||
╔═══════════════════════════════════════════════════════════════════╗
|
||||
║ REVISION COMPLETE ║
|
||||
╠═══════════════════════════════════════════════════════════════════╣
|
||||
|
||||
@@ -90,8 +90,39 @@ Each task should be:
|
||||
- Phase Checklist (from Implementation Phases)
|
||||
- Quick Reference (Key Files, Environment Variables, External Dependencies)
|
||||
5. **Write** each `phase-X.md` file with detailed tasks
|
||||
6. **Verify** all requirements from planning document are covered
|
||||
7. **Present** summary to user and ask about the planning document
|
||||
6. **Analyze** phases for parallel execution eligibility (see Parallel Eligibility Analysis below)
|
||||
7. **Verify** all requirements from planning document are covered
|
||||
8. **Present** summary to user and ask about the planning document
|
||||
### Parallel Eligibility Analysis
|
||||
After creating all phase files, analyze which phases can be executed in parallel. This enables users to run multiple agent instances simultaneously for faster implementation.
|
||||
**Analysis Process:**
|
||||
1. For each pair of adjacent phases (Phase N and Phase N+1), check for conflicts:
|
||||
| Conflict Type | How to Detect | Result if Found |
|
||||
|---------------|---------------|-----------------|
|
||||
| **File Overlap** | Any task in Phase N modifies a file also modified in Phase N+1 | NOT parallel-eligible |
|
||||
| **Prerequisite Dependency** | Phase N+1's Prerequisites section references Phase N | NOT parallel-eligible |
|
||||
| **Data/Output Dependency** | Phase N+1 tasks require artifacts, exports, or state created by Phase N | NOT parallel-eligible |
|
||||
| **Shared State** | Both phases modify the same database tables, config, or global state | NOT parallel-eligible |
|
||||
2. Group consecutive phases with NO conflicts into Parallel Execution Groups:
|
||||
- If Phases 2 and 3 have no conflicts → Group A: 2, 3
|
||||
- If Phase 4 depends on Phase 3 → Phase 4 starts a new sequence
|
||||
- If Phases 5 and 6 have no conflicts → Group B: 5, 6
|
||||
3. Populate the "Parallel Execution Groups" table in `overview.md`:
|
||||
**Example with parallel groups:**
|
||||
```markdown
|
||||
| Group | Phases | Reason |
|
||||
|-------|--------|--------|
|
||||
| A | 2, 3 | Phase 2 (data models) and Phase 3 (API routes) touch separate files |
|
||||
| B | 5, 6 | Phase 5 (frontend) and Phase 6 (tests) have no shared dependencies |
|
||||
```
|
||||
**Example with no parallel phases:**
|
||||
```markdown
|
||||
| Group | Phases | Reason |
|
||||
|-------|--------|--------|
|
||||
| None | - | All phases must run sequentially due to dependencies |
|
||||
```
|
||||
4. Inform the user about parallel eligibility in the completion summary:
|
||||
> **Parallel Execution:** Phases [X, Y] can be run simultaneously in separate agent instances. Phases [Z] must be run sequentially due to dependencies.
|
||||
|
||||
### Output Structure
|
||||
|
||||
@@ -169,6 +200,13 @@ Check the Testing Strategy from the PLAN-DRAFT (section 2.4):
|
||||
## Phase Checklist
|
||||
- [ ] Phase 1: [Name] - [Description]
|
||||
...
|
||||
## Parallel Execution Groups
|
||||
<!-- This section enables running multiple phases simultaneously in separate agent instances -->
|
||||
<!-- Phases in the same group have no file conflicts or dependencies between them -->
|
||||
| Group | Phases | Reason |
|
||||
|-------|--------|--------|
|
||||
| [A/B/etc or "None"] | [phase numbers] | [Why these can run in parallel] |
|
||||
_If no phases can run in parallel, this table will show "None - all phases must run sequentially"_
|
||||
|
||||
## Quick Reference
|
||||
### Key Files
|
||||
@@ -257,6 +295,9 @@ Total phases: X
|
||||
Total tasks: Y
|
||||
|
||||
Requirements coverage: [Confirm all planning requirements are addressed]
|
||||
Parallel Execution Groups:
|
||||
- Group A: Phases X, Y (can run simultaneously)
|
||||
- [Or: "None - all phases must run sequentially"]
|
||||
```
|
||||
|
||||
Then automatically archive the planning document:
|
||||
@@ -276,6 +317,12 @@ Example closing:
|
||||
> "Documentation complete. Implementation specs are in `specs/user-authentication/`.
|
||||
>
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ★ │
|
||||
> │ ◡ │ Specs are ready! Time to build!
|
||||
> ╰───╯
|
||||
>
|
||||
> ╔═══════════════════════════════════════════════════════════════════╗
|
||||
> ║ NEXT STEPS ║
|
||||
> ╠═══════════════════════════════════════════════════════════════════╣
|
||||
|
||||
+163
-15
@@ -31,9 +31,11 @@ If the user provides a path to an `overview.md` file (e.g., `specs/high-severity
|
||||
|
||||
1. Read the overview.md file
|
||||
2. Find the "Phase Checklist" section
|
||||
3. Identify the first unchecked `[ ]` phase - this is the next phase to implement
|
||||
4. Automatically read the corresponding `phase-X.md` file from the same directory
|
||||
5. Proceed with implementation
|
||||
3. Identify workable phases — any phase marked `[ ]` (pending) or `[/]` (in-progress)
|
||||
4. **Check for parallel execution options** (see Parallel Phase Selection below)
|
||||
5. Apply phase selection logic based on status and parallelism
|
||||
6. Automatically read the corresponding `phase-X.md` file from the same directory
|
||||
7. Proceed with implementation
|
||||
|
||||
**Option 2: Auto-detect from specs folder**
|
||||
|
||||
@@ -49,6 +51,109 @@ If there are multiple active spec folders or nothing was found, ask the user to
|
||||
|
||||
**Do not proceed until you have successfully read the overview.md and determined the next phase.**
|
||||
|
||||
### Phase Status Tracking
|
||||
|
||||
Phases in overview.md use checkbox notation to track status:
|
||||
|
||||
| Checkbox | Status | Meaning |
|
||||
|----------|--------|---------|
|
||||
| `[ ]` | Pending | Not yet started |
|
||||
| `[/]` | In Progress | Started but not complete (may be active or paused/aborted) |
|
||||
| `[x]` | Complete | Finished and approved |
|
||||
| `[?]` | Assumed | Couldn't verify, assumed complete (for prerequisites) |
|
||||
|
||||
**Status Transitions:**
|
||||
- `[ ]` → `[/]` — When an agent STARTS working on a phase
|
||||
- `[/]` → `[x]` — When user APPROVES a completed phase
|
||||
- `[/]` stays `[/]` — On abort (preserves resume capability)
|
||||
|
||||
**Important:** Never reset `[/]` back to `[ ]`. If work was started, it stays marked so users can consciously choose to resume.
|
||||
|
||||
### Parallel Phase Selection
|
||||
|
||||
After identifying the next workable phase(s), check if parallel execution options are available:
|
||||
|
||||
1. **Look for "Parallel Execution Groups" section** in overview.md
|
||||
2. **Find if the next phase belongs to a group** with other uncompleted phases
|
||||
3. **Only show consecutive uncompleted phases** in the same group
|
||||
|
||||
**Decision Logic:**
|
||||
|
||||
```
|
||||
Find workable phases = all phases marked [ ] or [/] (not [x])
|
||||
Check Parallel Execution Groups table:
|
||||
|
||||
CASE 1: Multiple parallel phases available
|
||||
- If 2+ workable phases exist in the same parallel group
|
||||
→ Show parallel selection UI with status for each
|
||||
|
||||
CASE 2: Single workable phase that is IN PROGRESS [/]
|
||||
- Phase was started but not completed (possibly by another session)
|
||||
→ Show resume prompt: "Phase X is in progress. Resume? (yes/no)"
|
||||
|
||||
CASE 3: Single workable phase that is PENDING [ ]
|
||||
- Fresh phase, no parallel options
|
||||
→ Auto-start: mark [/] and begin implementation
|
||||
|
||||
CASE 4: No Parallel Execution Groups section exists
|
||||
→ Fall back to sequential mode using Cases 2-3 logic
|
||||
```
|
||||
|
||||
**Parallel Selection UI:**
|
||||
|
||||
When parallel options are available (CASE 1), present this prompt:
|
||||
|
||||
```
|
||||
⚡ PARALLEL PHASES AVAILABLE
|
||||
|
||||
These phases can be worked on in parallel:
|
||||
|
||||
[1] Phase N: [Name] [IN PROGRESS] ← if marked [/]
|
||||
[2] Phase N+1: [Name] [AVAILABLE] ← if marked [ ]
|
||||
[3] Phase N+2: [Name] [AVAILABLE] ← if marked [ ]
|
||||
|
||||
Which phase would you like to work on? (1/2/3)
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ TIP: Run another agent instance with /plan2code-3--implement to work │
|
||||
│ on a different phase simultaneously. │
|
||||
│ │
|
||||
│ IN PROGRESS phases may be running in another session - selecting one │
|
||||
│ will resume work on it. │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Single Phase Resume UI:**
|
||||
|
||||
When there's only one workable phase and it's in-progress (CASE 2):
|
||||
|
||||
```
|
||||
⚡ PHASE RESUME CHECK
|
||||
|
||||
Phase N: [Name] is marked as IN PROGRESS.
|
||||
|
||||
This could mean:
|
||||
• Another agent session is currently working on it
|
||||
• A previous session was aborted mid-phase
|
||||
|
||||
Resume this phase? (yes / no - I'll wait)
|
||||
```
|
||||
|
||||
If user says "yes", proceed with implementation.
|
||||
If user says "no", end session gracefully.
|
||||
|
||||
**Important Rules:**
|
||||
- Only show phases that are **consecutive** AND **in the same parallel group** AND **not complete** (`[ ]` or `[/]`)
|
||||
- Stop showing options at the first phase that is NOT in the same group (even if later phases are)
|
||||
- If user selects a phase, proceed with that phase
|
||||
- After selection, mark the phase `[/]` in overview.md (if not already), then read `phase-X.md` and begin
|
||||
|
||||
**Edge Cases:**
|
||||
- If Parallel Execution Groups section is missing → fall back to sequential (Cases 2-3)
|
||||
- If table shows "None" → fall back to sequential (Cases 2-3)
|
||||
- If only one workable phase remains in the group → apply Cases 2-3 (resume or auto-start)
|
||||
- If ALL parallel phases are `[/]` (all in progress) → show selection UI with all marked IN PROGRESS, warn user that work may be duplicated
|
||||
|
||||
### Code Consistency Rules
|
||||
|
||||
When implementing:
|
||||
@@ -85,18 +190,40 @@ Proceeding to Task 2.4 (no Stripe dependency).
|
||||
|
||||
## Process
|
||||
|
||||
### 1. Identify the Current Phase
|
||||
### 1. Identify and Claim the Phase
|
||||
|
||||
Review `overview.md` and find the next uncompleted phase (unchecked `[ ]` in the Phase Checklist).
|
||||
Review `overview.md` and find workable phases (`[ ]` or `[/]` in the Phase Checklist).
|
||||
|
||||
State: `⚡ [PHASE X: Phase Name] - Starting implementation`
|
||||
Apply the decision logic from "Parallel Phase Selection" to determine which phase to work on.
|
||||
|
||||
**Once a phase is selected:**
|
||||
1. If the phase is `[ ]` (pending), immediately update it to `[/]` in overview.md
|
||||
2. If the phase is already `[/]` (resuming), no change needed
|
||||
|
||||
State: `⚡ [PHASE X: Phase Name] - Marking in-progress and starting implementation`
|
||||
|
||||
### 2. Verify Prerequisites
|
||||
|
||||
Check the Prerequisites section in the phase document:
|
||||
Before implementing any tasks, process the Prerequisites section in order:
|
||||
|
||||
- All listed prerequisites must be complete
|
||||
- If a prerequisite is not met, STOP and inform the user
|
||||
1. Read each prerequisite
|
||||
2. For each unchecked (`[ ]`) prerequisite:
|
||||
- **Verifiable:** Check if condition is met (e.g., check overview.md for phase completion) → mark `[x]`
|
||||
- **Actionable:** Complete the action (e.g., install dependencies) → mark `[x]`
|
||||
- **Cannot verify:** Mark `[?]` with note explaining assumption
|
||||
- **Blocked:** Mark `[!]` with blocker reason, STOP the phase
|
||||
|
||||
3. Only proceed to tasks when ALL prerequisites are `[x]` or `[?]`
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
## Prerequisites
|
||||
- [x] Phase 1: Core Setup is complete ← verified via overview.md
|
||||
- [?] Design approved by stakeholder ← cannot verify, assuming complete
|
||||
- [!] API credentials configured ← BLOCKED: .env missing STRIPE_KEY
|
||||
```
|
||||
|
||||
If any prerequisite is marked `[!]`, STOP and inform the user before proceeding
|
||||
|
||||
### 3. Implement Tasks Sequentially
|
||||
|
||||
@@ -141,9 +268,9 @@ After completing all tasks and self-review:
|
||||
|
||||
When user replies "approved":
|
||||
|
||||
1. Update `overview.md` - mark the phase checkbox `[x]`
|
||||
2. Update `Phase X.md` - change Status to "Complete"
|
||||
3. Confirm completion and provide next steps
|
||||
1. Update `overview.md` - change the phase checkbox from `[/]` to `[x]`
|
||||
2. Update `phase-X.md` - change Status to "Complete"
|
||||
3. Confirm completion and provide next steps (see Session End section)
|
||||
|
||||
### Handling Blockers
|
||||
|
||||
@@ -272,6 +399,14 @@ Before approving, confirm this phase is working:
|
||||
- **App runs** (if applicable): Start command runs without crashing
|
||||
- **Quick check**: [Describe 1-2 specific things to verify based on what was built]
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ● │
|
||||
│ ~ │ Ready for your review!
|
||||
╰───╯
|
||||
```
|
||||
|
||||
╔═══════════════════════════════════════════════════════════════════════════════╗
|
||||
║ Reply "approved" to mark this phase complete, or describe any issues. ║
|
||||
╚═══════════════════════════════════════════════════════════════════════════════╝
|
||||
@@ -300,7 +435,7 @@ This creates a checkpoint you can return to if needed.
|
||||
The next uncompleted phase is Phase Y: [Name].
|
||||
To continue, start a NEW conversation with:
|
||||
|
||||
> /plan2code-3--implement specs/<feature-name>/overview.md
|
||||
> /smarsh2code-3--implement specs/<feature-name>/overview.md
|
||||
|
||||
The command will auto-detect Phase Y as the next phase to implement.
|
||||
```
|
||||
@@ -322,6 +457,12 @@ Example for continuing:
|
||||
> Phase marked complete in overview.md.
|
||||
>
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ★ │
|
||||
> │ ◡ │ Phase done! Great progress!
|
||||
> ╰───╯
|
||||
>
|
||||
> ╔═══════════════════════════════════════════════════════════════════╗
|
||||
> ║ NEXT STEPS ║
|
||||
> ╠═══════════════════════════════════════════════════════════════════╣
|
||||
@@ -348,6 +489,12 @@ Example for final phase:
|
||||
> This was the final implementation phase!
|
||||
>
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ★ │
|
||||
> │ ◡ │ All phases complete! Amazing work!
|
||||
> ╰───╯
|
||||
>
|
||||
> ╔═══════════════════════════════════════════════════════════════════╗
|
||||
> ║ NEXT STEPS - FINAL PHASE COMPLETE ║
|
||||
> ╠═══════════════════════════════════════════════════════════════════╣
|
||||
@@ -369,11 +516,12 @@ Example for final phase:
|
||||
|
||||
If the user says "abort", "cancel", "start over", or similar:
|
||||
|
||||
1. Confirm: "Are you sure you want to abort Phase X? Partial progress will remain in the spec files."
|
||||
1. Confirm: "Are you sure you want to abort Phase X? The phase will remain marked as in-progress `[/]` for resuming later."
|
||||
2. If confirmed:
|
||||
- List which tasks were completed vs. remaining
|
||||
- Note any files that were created/modified
|
||||
- Explain checkboxes reflect current state
|
||||
- **Do NOT change the phase checkbox** — it stays `[/]` so it can be resumed
|
||||
- Explain: "The phase remains `[/]` in overview.md. Run `/plan2code-3--implement` again to resume."
|
||||
3. Do not continue with implementation
|
||||
|
||||
## Recovery
|
||||
|
||||
@@ -14,7 +14,7 @@ You are a QA engineer and technical lead performing final validation before a fe
|
||||
- Incomplete tasks are found (Step 1)
|
||||
- Documentation updates are proposed (Step 4)
|
||||
- Do NOT make documentation changes without explicit user approval
|
||||
- Archive specs to `specs--completed/<feature-name>/` - preserve folder name exactly
|
||||
- Archive specs to `specs--completed/<feature-name>-<timestamp>/` - preserve feature name exactly and append timestamp
|
||||
- This is validation and cleanup only - do NOT write implementation code
|
||||
- If you cannot perform file operations, output file contents in code blocks with the intended file path as the header
|
||||
- If you cannot access the filesystem, ask the user to paste relevant file contents
|
||||
@@ -251,6 +251,14 @@ Add this summary to `overview.md` under `## Completion Summary`.
|
||||
|
||||
**If ANY documentation needs updates:**
|
||||
|
||||
> ```
|
||||
> ⋅
|
||||
> ╭───╮
|
||||
> │ ● │
|
||||
> │ ~ │ Found some docs that need updating!
|
||||
> ╰───╯
|
||||
> ```
|
||||
>
|
||||
> "The following documentation updates are recommended. Please review and approve before I make these changes:
|
||||
>
|
||||
> [List proposed changes]
|
||||
@@ -334,6 +342,13 @@ specs--completed/
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
⋅
|
||||
╭───╮
|
||||
│ ★ │
|
||||
│ ◡ │ You did it! Feature complete!
|
||||
╰───╯
|
||||
```
|
||||
╔═══════════════════════════════════════════════════════════════════╗
|
||||
║ IMPLEMENTATION COMPLETE ║
|
||||
╠═══════════════════════════════════════════════════════════════════╣
|
||||
|
||||
Reference in New Issue
Block a user