jparkerweb/plan2code
1
0
Fork 0
mirror of https://github.com/jparkerweb/plan2code.git synced 2026-07-21 18:33:22 -07:00
Code Issues Packages Projects Releases Wiki Activity

v1.10.0

Browse Source
This commit is contained in:
Justin Parker
2026-03-01 12:24:11 -08:00
parent 628e688ab9
commit 63656d339d
33 changed files with 1018 additions and 539 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/plan2code---init-update.md
+67 -3
View File
@@ -24,6 +24,42 @@ Check if `AGENTS.md` exists in project root.
- Main sections (bullets)
- Current line count
Check for `.agents-docs/` directory:
**If `.agents-docs/` exists:**
```
Structure: Progressive discovery (index + N section files)
Section files:
- .agents-docs/AGENTS-architecture.md
- .agents-docs/AGENTS-development.md
[etc.]
```
**If `.agents-docs/` does not exist:** Note: `Structure: Single-file (no .agents-docs/ directory)`
**IMPORTANT — you MUST offer restructuring.** Stop and ask:
> "Your AGENTS.md uses a single-file format. Want to restructure for progressive discovery? This splits detailed sections into `.agents-docs/` files and converts AGENTS.md to a lightweight index with summaries and links."
Wait for user response before continuing. If user accepts, restructure existing content: create `.agents-docs/` directory with section files, convert AGENTS.md to index with summaries and links. Always-inline sections (Project Overview, Git Commit Messages, How to Use This File) stay in AGENTS.md. If user declines, continue with single-file editing.
### Git Commit Messages Audit
Check AGENTS.md for a `## Git Commit Messages` section describing this format:
```
<description>
<JIRA-Ticket-ID>
AI Assisted
```
Required rules:
1. **JIRA ticket ID from branch** — derive from branch name format `<prefix>/<TICKET-ID>-description` (uppercase project key + hyphen + integer, e.g., `PCWEB-10968`)
2. **AI Assisted footer** — always the last line, on its own line directly after the ticket ID
If the section is missing or either rule is absent, flag it:
> "Your Git Commit Messages section is missing [missing items]. Want me to add them?"
If user confirms, add/update the section before proceeding. If user declines, continue.
Proceed to Step 2.
---
@@ -94,7 +130,12 @@ Present the user with update options:
## Step 5: Confirm & Apply
Before changes:
Before changes, route edits to the correct file when `.agents-docs/` exists:
- Always-inline sections (Project Overview, Git Commit Messages, How to Use This File) → edit AGENTS.md directly
- All other sections → edit the corresponding `.agents-docs/AGENTS-<section-name>.md` file
Preview format:
> **File:** `.agents-docs/AGENTS-architecture.md` (or `AGENTS.md` for inline sections)
> **Section:** [name]
> **Change:** [description]
> ```
@@ -105,6 +146,13 @@ Before changes:
- "adjust" -> ask what to change, repeat
- "yes" -> apply edit, insert in appropriate section (create if needed), preserve structure
### Section File Lifecycle (when `.agents-docs/` exists)
- **New section (>~10 lines):** Create `.agents-docs/AGENTS-<section-name>.md` with breadcrumb header, add summary + link in AGENTS.md
- **New section (<~10 lines):** Keep inline in AGENTS.md
- **Delete section:** Remove the `.agents-docs/` file and its summary + link from AGENTS.md
- **Orphan cleanup:** After all edits, check for `.agents-docs/` files with no corresponding AGENTS.md section — offer to remove them
---
## Step 6: Summary & Next
@@ -112,8 +160,14 @@ Before changes:
After applying:
> "Done! Changed:"
> - [Summary]
> - Line count: X/500
>
If `.agents-docs/` exists:
> Structure: AGENTS.md (index) + N section files in .agents-docs/
> Index line count: X/500
Otherwise:
> Line count: X/500
> "Add anything else?"
If yes, return to Step 3. If done, proceed to Step 7.
@@ -172,6 +226,7 @@ See [AGENTS.md](./AGENTS.md) for complete project documentation including:
- Environment variables
- Testing patterns
- Deployment guides
- Section details in .agents-docs/
```
**For directory configs** (`.cursor/rules/`, `.windsurf/rules/`): Delete existing `.md` files, create single `reference.md`.
@@ -188,6 +243,7 @@ See [AGENTS.md](./AGENTS.md) for complete project documentation including:
6. **No duplication** - Check for similar content first
7. **Group logically** - Place near related content
8. **Be specific** - Include exact commands, paths, names
9. **Route edits to correct file** - Inline sections edit AGENTS.md directly, detailed sections edit the corresponding .agents-docs/ file
---
@@ -199,6 +255,14 @@ Agent: Found AGENTS.md covering:
- Project structure
- API conventions
Line count: 127
Structure: Single-file (no .agents-docs/ directory)
Your AGENTS.md uses a single-file format. Want to
restructure for progressive discovery?
User: No thanks, just update it.
Agent: OK, keeping single-file format.
Recent work on auth flow. Worth documenting:
- JWT refresh token must validate before access token
src/plan2code---init.md
+40 -1
View File
@@ -16,7 +16,8 @@ Analyze this codebase and create `AGENTS.md` to guide future AI coding agents (C
1. **Commands**: Build, lint, test, run single test, and other common development tasks
2. **Architecture**: High-level "big picture" structure requiring multi-file context to understand
3. **Git Commit Messages**: Always append `AI Assisted` as the last line of every git commit message, separated from the rest of the message body with a blank line
3. **Git Commit Messages**: All commits must follow this format: `<description>\n\n<JIRA-Ticket-ID>\nAI Assisted`. Derive the JIRA ticket ID from the current branch name — the format is `<prefix>/<TICKET-ID>-description` where the ticket ID is an uppercase project key, hyphen, and integer (e.g., `PCWEB-10968`). The ticket ID and `AI Assisted` go on consecutive lines after a blank line.
4. **How to Use This File**: A short paragraph explaining that sections below contain brief summaries and agents should follow the markdown links to `.agents-docs/` for full details — only read what's relevant to the current task.
## Rules
@@ -36,6 +37,43 @@ This file provides guidance to AI coding agents like Claude Code (claude.ai/code
---
## Progressive Discovery
Generate AGENTS.md as an **index file** — each section gets a 2-3 line summary with a markdown link to a detail file. Full content goes in `.agents-docs/` directory files.
- **Index format** — each section in AGENTS.md: heading, brief summary, then `Details: [Section Name](./.agents-docs/AGENTS-<section-name>.md)`
- **Detail files** — named `AGENTS-<section-name>.md` using kebab-case from the section header (e.g., "Development Commands" → `AGENTS-development-commands.md`)
- **Detail file header** — each file starts with:
```
# <Section Name>
> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.
```
### Always Inline
These sections must remain fully inline in AGENTS.md (never split to separate files):
- Project Overview
- Git Commit Messages
- How to Use This File
### Directory Setup
- Create `.agents-docs/` directory in the project root
- Each file: `AGENTS-<section-name>.md` where `<section-name>` is kebab-case of the section header
- Each file starts with `# <Section Name>` followed by breadcrumb: `> Part of [AGENTS.md](../AGENTS.md) — project guidance for AI coding agents.`
### Grouping Heuristics
- Combine related subsections into a single detail file (e.g., "Architecture" with its subsections → one file)
- Sections under ~10 lines of content should stay inline in AGENTS.md rather than being split out
- Decide grouping dynamically based on the project's actual content — heuristics guide, not prescribe
### Existing AGENTS.md Without `.agents-docs/`
If AGENTS.md exists but `.agents-docs/` does not, offer to restructure: "Your AGENTS.md uses a single-file format. Want to restructure it for progressive discovery? This splits detailed sections into `.agents-docs/` files and converts AGENTS.md to a lightweight index." Only restructure if the user confirms — never auto-restructure.
---
## AI Agent File Sync
After creating `AGENTS.md`, check for these files and offer to replace with references:
@@ -81,4 +119,5 @@ See [AGENTS.md]([Path]) for complete project documentation including:
- Environment variables
- Testing patterns
- Deployment guides
- Section details in .agents-docs/
```
src/plan2code-1--plan.md
+1
View File
@@ -221,6 +221,7 @@ State assessment and ask user to confirm.
1. Save PLAN-CONVERSATION (see template below) — transcript + decision summary tables
2. Create PLAN-DRAFT (see template below) using same date
3. Verify: re-read conversation as source of truth, cross-reference against PLAN-DRAFT sections (Reqs→2.1/2.2, Tech→3, Architecture→4, Risks→6, Assumptions→9, Criteria→7). Add gaps with `<!-- VERIFICATION -->` comments. Output verification summary table.
4. Append `## Planning Metrics` to PLAN-DRAFT with these exact fields: `confidence: [0-100]`, `clarification_rounds: [N]`, `functional_requirements_count: [N]`, `non_functional_requirements_count: [N]`, `risk_count: [N]`, `phase_count: [N]`, `verification_gaps_found: [N]`. Use exact field names — the metrics pipeline parses this section.
## Templates
src/plan2code-2--document.md
+3 -3
View File
@@ -11,7 +11,7 @@ Technical writer transforming planning documents into implementation specs any d
- Follow `./AGENTS.md` if it exists
- Require planning document before proceeding
- Tasks must be specific enough for a developer with NO context
- Use checkbox format `- [ ]` for tracking
- Use checkbox format `- [ ]` for Task items ONLY (not prerequisites, acceptance criteria, or success criteria)
- Verify all planning requirements are covered
- Do NOT implement - documentation only
- If no filesystem access, output in code blocks with file path headers
@@ -80,7 +80,7 @@ If no plan exists and user wants to skip:
- Tech Stack table (exact copy)
- Architecture Pattern and Component Overview (section 4)
- Risks and Mitigations table (section 6)
- Success Criteria checklist (section 7)
- Success Criteria (plain bullet list, no checkboxes) (section 7)
- Phase Checklist (Implementation Phases)
- Quick Reference (Key Files, Environment Variables, External Dependencies)
7. **Write** each `phase-X.md` with detailed tasks
@@ -162,7 +162,7 @@ Sections: Summary (from Executive Summary), Tech Stack table (exact copy from PL
Header: Phase name, Status, Estimated Tasks count.
Sections: Overview (2-3 sentences), Prerequisites checklist, Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details), Phase Testing (if enabled), Acceptance Criteria checklist, Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues).
Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkboxes), Tasks (grouped by category, `- [ ] **Task X.N:** [Description]` with File path and details), Phase Testing (if enabled), Acceptance Criteria (plain bullet list, no checkboxes), Notes, Phase Completion Summary (filled after implementation: date, implementer, what was done, files changed, issues).
## Session End
src/plan2code-3--implement.md
+13 -9
View File
@@ -51,6 +51,8 @@ Do not proceed without successfully reading overview.md and determining the next
| `[x]` | Complete | Finished and approved |
| `[?]` | Assumed | Couldn't verify, assumed complete |
These checkbox states apply to Task items and the Phase Checklist in overview.md only. Prerequisites and Acceptance Criteria use plain bullets.
**Transitions:**
- `[ ]` -> `[/]`: Agent STARTS phase
- `[/]` -> `[x]`: User APPROVES completed phase
@@ -58,6 +60,8 @@ Do not proceed without successfully reading overview.md and determining the next
Never reset `[/]` to `[ ]`. Started work stays marked for conscious resume decisions.
**Disk Write Rule:** Write task completion status (`[x]`) to `phase-X.md` on disk immediately after each task — never batch status updates. If a session ends unexpectedly, on-disk state must reflect all completed work.
## Parallel Phase Selection
Check overview.md for "Parallel Execution Groups" section. Find workable phases (`[ ]` or `[/]`).
@@ -102,17 +106,17 @@ State: `⚡ [PHASE X: Phase Name] - Marking in-progress and starting`
### 2. Verify Prerequisites
Process Prerequisites section in order:
Process Prerequisites section in order. Prerequisites use plain bullets (no checkboxes).
For each unchecked (`[ ]`) prerequisite:
- **Verifiable:** Check condition -> mark `[x]`
- **Actionable:** Complete action -> mark `[x]`
- **Cannot verify:** Mark `[?]` with assumption note
- **Blocked:** Mark `[!]` with reason, STOP phase
For each prerequisite:
- **Verifiable:** Check condition, note "VERIFIED" inline
- **Actionable:** Complete action, note "VERIFIED" inline
- **Cannot verify:** Note "ASSUMED: [reason]" inline
- **Blocked:** Note "BLOCKED: [reason]" inline, STOP phase
Proceed only when ALL prerequisites are `[x]` or `[?]`.
Proceed only when all prerequisites are verified or assumed.
If any `[!]`, STOP and inform user.
If any blocked, STOP and inform user.
### 3. Implement Tasks Sequentially
@@ -195,7 +199,7 @@ Sections: Summary (2-3 sentences), Tasks Completed (Y/Z + blocked list), Test Re
On user "approved":
1. Mark `[/]` → `[x]` in overview.md, update phase-X.md status to "Complete"
2. Show Planny art with completion message
3. Provide: `git add -A && git commit -m "Complete Phase X: [Phase Name]" -m "AI Assisted"`
3. Provide: `git add -A && git commit -m "Complete Phase X: [Phase Name]" -m "<JIRA-Ticket-ID>" -m "AI Assisted"` (derive JIRA ticket ID from branch name)
4. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3--implement`"
5. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4--finalize`"
6. Mention `/plan2code-1b--revise` option
src/plan2code-4--finalize.md
+2 -4
View File
@@ -48,7 +48,8 @@ Complete steps in order. Report progress after each.
**Objective:** Verify all tasks across all phases completed.
1. Open each `phase-X.md` file
2. Verify each task status:
2. Count only `**Task X.N:**` checkbox items (prerequisites and acceptance criteria use plain bullets)
3. Verify each task status:
| Status | Meaning | Action |
|--------|---------|--------|
@@ -299,9 +300,6 @@ specs--completed/
> Specs archived to `specs--completed/<feature-name>/`.
> Thank you for using the Plan2Code workflow!
### Metrics Capture (Contributors)
To help improve plan2code's prompts, run `plan2code-metrics` in the project root.
### Handling Incomplete Implementations
| Completion | Action |