diff --git a/.agents-docs/AGENTS-code-style.md b/.agents-docs/AGENTS-code-style.md index d0eb6f0..c36a527 100644 --- a/.agents-docs/AGENTS-code-style.md +++ b/.agents-docs/AGENTS-code-style.md @@ -11,7 +11,8 @@ ## Gotchas / Pitfalls -- **Version sync:** When adding a new version to `CHANGELOG.md`, also update `version.json` and `package.json` to match. The installer displays the version from `version.json` in its header. +- **Version sync:** When adding a new version to `CHANGELOG.md`, also update `version.json` and `package.json` (root) to match. Check `README.md` for any version badges or references that need updating. The installer displays the version from `version.json` in its header. All three files (`CHANGELOG.md`, `version.json`, `package.json`) must always show the same version number. +- **CHANGELOG ordering:** Entries in `CHANGELOG.md` must be in reverse-chronological order — newest version at the top, oldest at the bottom. New entries are always inserted immediately after the file header. - **Loop `.gitignore` setup:** `ensureGitignore()` runs at startup in `Controller.run()` as a pre-flight step, not just inside `createTaskCommit()`. This is critical for phase mode where the Node controller doesn't handle commits — without it, `git add -A` would stage spec files. - **Workflow file character limit:** All `src/plan2code-*.md` files must be ≤ 11,000 characters. A husky pre-commit hook enforces this. The 11,000 limit leaves buffer for platform-specific YAML headers (106-142 chars) to stay under Windsurf's 12,000 char limit. - **Metrics internal prompts have no char limit:** Files in `plan2code-metrics/src/prompts/` are NOT subject to the 11,000 char limit — only `src/plan2code-*.md` consumer-facing prompts are. diff --git a/.claude/skills/sync-repo/sync-repo.enc b/.claude/skills/sync-repo/sync-repo.enc index 8c6a1b6..05f8b10 100644 --- a/.claude/skills/sync-repo/sync-repo.enc +++ b/.claude/skills/sync-repo/sync-repo.enc @@ -1 +1 @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 2f2b034..a47b4d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,30 @@ All notable changes to Plan2Code will be documented in this file. +## v1.15.3 + +### ✨ Added + +- **Session-end summaries across workflows** — consistent closing context in implement, document, finalize, init-update, quick-task, review, and revise-plan + - Implement: work summary + upcoming-phases table (task counts, goals) after each phase approval + - Document: phase-overview table at close to help plan sessions and review gates +- **Sync & Maintain in init-update** — new unified doc-surface sync option (menu item #9) + - Covers `AGENTS.md`, `.agents-docs/`, active `specs/`, README, and human docs; tier-voice routing, never duplicates across tiers + - Adaptive to repo conventions — detects the human-docs tree, never assumes +- **Research steps in plan** — domain research (Phase 1), tech-options research (Phase 4), and an investigate-to-close-gaps rule on the 90% confidence gate + +### 🔧 Changed + +- **Spec auto-discovery hardened** — replaced Glob (silently fails on gitignored `specs/`) with explicit shell `ls` across document, implement, finalize, init-update, and revise-plan +- **Revision-mode guardrails** — `1b-revise-plan` edits restricted to `specs/` paths only; execution-shaped language removed; cleanup step added +- **Commit-message enforcement in implement** — subject ≤100 chars, exactly three `-m` flags, no body +- **Finalize documentation review expanded** — audits `AGENTS.md` + `.agents-docs/`, mandates corrections (not just additions), routes facts per tier voice +- **Quality language pass** — plan demands edge cases/failure modes and measurable criteria; document and finalize role statements sharpened + +### 🐛 Fixed + +- **Review workflow next-step guard** — Review mode no longer suggests `/plan2code-3-implement` when `overview.md` and `phase-*.md` files don't exist. If the document step hasn't been run yet, it now correctly directs users to `/plan2code-2-document` first. + ## v1.15.2 ### 🔧 Changed diff --git a/package.json b/package.json index 1c064bf..06b0664 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "plan2code", - "version": "1.15.2", + "version": "1.15.3", "private": true, "bin": { "plan2code": "./install.js" diff --git a/src/plan2code-1-plan.md b/src/plan2code-1-plan.md index 14e3cc1..82d726d 100644 --- a/src/plan2code-1-plan.md +++ b/src/plan2code-1-plan.md @@ -4,7 +4,7 @@ Start all PLANNING MODE responses with '🤔 [PLANNING PHASE X: Phase Name]' ## Role -Senior software architect and technical PM. Analyze requirements, ask questions, design solutions. Output: SOW and Implementation Plan. Do NOT write code - focus on planning and architecture. +Senior software architect and technical PM. Analyze requirements critically, ask questions, design robust, testable solutions. Output: SOW and Implementation Plan. Do NOT write code - focus on planning and architecture. ## Project Context (BLOCKING) @@ -32,7 +32,7 @@ Check if `./AGENTS.md` exists: ## Rules - Complete ONE phase at a time, then STOP and wait for input -- Reach 90% confidence before finalizing +- Reach 90% confidence before finalizing — investigate to close gaps; score honestly against evidence, never inflate - Resolve ambiguities through questions - do NOT assume - Document unavoidable assumptions clearly - Present/confirm technology decisions with user @@ -44,7 +44,7 @@ Check if `./AGENTS.md` exists: ### Check for Existing Progress -Before Phase 1, check for `specs/*/PLAN-DRAFT-*.md`: +Before Phase 1, check for existing `PLAN-DRAFT-*.md` under `specs/` (`ls specs/` via shell — never Glob; `specs/` is gitignored): - Status "Phase 3 Complete - Resume at Phase 4": Resume at Phase 4 - Status "Escalated from Quick Task - Resume at Phase 2": Acknowledge, verify requirements, skip to Phase 2 - Status "Draft" or "Complete": Ask user how to proceed @@ -88,9 +88,9 @@ Report each sub-score with overall percentage. After confirmation, proceed with analysis: -1. Read all provided information +1. Read all provided information; research the domain for standards and unstated needs 2. Extract explicit functional requirements -3. Identify implied requirements +3. Identify implied requirements, edge cases, and failure modes 4. Determine non-functional requirements: Performance, Security, Scalability, Maintenance 5. Ask clarifying questions 6. **Testing Preferences (Optional):** @@ -123,7 +123,7 @@ After confirmation, proceed with analysis: **Existing projects:** 1. Examine directory structure -2. Review key files/components +2. Review key files/components — verify behavior against actual code, not assumptions 3. Identify patterns, conventions, code style 4. Identify integration points 5. Note technical debt @@ -163,7 +163,7 @@ State assessment and ask user to confirm. ### PHASE 4: Tech Stack 1. List user-specified technologies (confirmed) -2. Recommend unspecified decisions with justification: +2. Research current options; recommend unspecified decisions with evidence-based justification: - Languages, Frameworks, Libraries, Databases, External services, Dev tools | Category | Recommendation | Alternatives | Justification | @@ -181,7 +181,7 @@ State assessment and ask user to confirm. 4. Define core components: name, responsibility, inputs/outputs, dependencies 5. Design component interfaces 6. Database schema (if applicable): entities, relationships, key fields, indexing -7. Cross-cutting concerns: Auth, Error handling, Logging, Security +7. Cross-cutting concerns: Auth, Error handling, Logging, Security, Performance, Scalability 8. Update confidence ### PHASE 6: Technical Specification @@ -193,7 +193,7 @@ State assessment and ask user to confirm. |------|------------|--------|------------| 3. Component specs: API contracts, data formats, validation, state management, error codes -4. Define success criteria +4. Define measurable success criteria 5. Update confidence 6. **If confidence >= 90%:** "Reached [X]% confidence. Proceed to PLAN-DRAFT, or any adjustments?" diff --git a/src/plan2code-1b-revise-plan.md b/src/plan2code-1b-revise-plan.md index 61efe85..eb6a2b3 100644 --- a/src/plan2code-1b-revise-plan.md +++ b/src/plan2code-1b-revise-plan.md @@ -4,7 +4,7 @@ Start all REVISION MODE responses with '🔄 [REVISION]' ## Role -Senior software architect updating implementation specs when requirements change mid-project. +Senior software architect updating implementation specs when requirements change mid-project. **Output: spec-file edits only — never implementation.** ## Rules @@ -13,14 +13,18 @@ Senior software architect updating implementation specs when requirements change - Warn if changes invalidate completed work - Keep task numbers sequential - Preserve revision history -- STOP at Step 2 for approval before making changes -- This mode modifies specs only - do NOT implement code +- STOP at Step 2 for approval before applying spec updates +- This mode modifies **`specs/` paths only** — do NOT implement code or modify any file outside `specs/` +- **Allowed file paths:** ONLY paths under `specs/`. Forbidden: `skills/`, `src/`, `.claude/`, `.agents/`, `.codeium/`, configs, source code. Creating, modifying, or deleting any file outside `specs/` is a violation. +- **Question options:** Never offer 'execute', 'implement', or any execution-shaped synonym. Implementation lives in `/plan2code-quick-task` and `/plan2code-3-implement` only. ## Required Context +⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS). + Request these files if not provided: - `specs//overview.md` -- All `specs//Phase X.md` files +- All `specs//phase-X.md` files Do not proceed without spec files. @@ -38,7 +42,7 @@ Do not proceed without spec files. |---------------|-------|----------| | [Component] | [File list] | [Section names] | -Present findings and confirm understanding before proceeding. +Present findings and confirm understanding before continuing. ### STEP 2: Impact Assessment @@ -82,14 +86,16 @@ Present findings and confirm understanding before proceeding. ╰───╯ ``` -Proceed with revision? (yes / no / discuss) +Approve the spec-update plan? (approve / refine / abort). Implementation of any new/modified tasks runs separately via /plan2code-3-implement. ``` -**Wait for approval before proceeding.** +**Wait for approval to apply spec updates.** -### STEP 3: Execute Revisions +### STEP 3: Apply Spec Updates -`🔄 [REVISION] Step 3: Execute Revisions` +`🔄 [REVISION] Step 3: Apply Spec Updates` + +**Hard guardrail (verify before every edit):** the file path must start with `specs/`. If not, STOP — document the work as a task in the spec and direct the user to `/plan2code-3-implement`. **Code references:** When writing or revising task descriptions, never use line numbers as primary references — they become stale as tasks modify files. Reference code by function/method names, class names, semantic descriptions, or code patterns. Line numbers may only appear as supplemental context (e.g., "Update `validateEmail()` (currently ~L45) to..."). @@ -130,7 +136,7 @@ Verify updated specs are consistent: - [ ] overview.md checklist matches phase files - [ ] Incomplete phases unchecked, complete phases checked -Report and resolve issues before proceeding. +Report and resolve issues before continuing. ### STEP 5: Summary @@ -188,6 +194,20 @@ Report and resolve issues before proceeding. ╚═══════════════════════════════════════════════════════════════════╝ ``` +### STEP 6: Revision Cleanup + +`🔄 [REVISION] Step 6: Revision Cleanup` + +After revision is applied, optionally clean up with user confirmation: + +1. Archive the previous PLAN-DRAFT: rename to `PLAN-DRAFT--prev.md` (preserves revision history) +2. Remove research or scratch files created during revision that are no longer needed +3. Keep the current PLAN-DRAFT as the active working version + +**Ask user before renaming or removing any files.** + +--- + ## Aborting If user says "abort" or "cancel": @@ -198,7 +218,18 @@ If user says "abort" or "cancel": ## IMPORTANT REMINDERS - Every response must start with: `🔄 [REVISION]` -- STOP and get approval at Step 2 before making changes +- STOP and get approval at Step 2 before applying spec updates - Never silently remove completed tasks - Maintain full revision history for traceability -- This mode modifies specs only - do NOT implement code \ No newline at end of file +- This mode modifies specs only - do NOT implement code +- Edits target `specs/` paths only — non-spec paths = violation regardless of context +- The question/option set offered to the user NEVER includes "execute" — implementation belongs to `/plan2code-quick-task` or `/plan2code-3-implement` +- If the revision plan would require implementation work, document it as a `🆕 ADDED` task and tell the user to run `/plan2code-3-implement` next + +## Session End + +Work summary — tell user: change type, tasks added/modified/removed, phases re-opened (if any). + +**Pending phases after revision** — read overview.md Phase Checklist, list all pending (`[ ]`) or re-opened phases with task counts so the user can plan next implementation sessions. + +Returning context: Revised specs in `specs//`. Run `/plan2code-3-implement` in a new conversation to continue implementation. \ No newline at end of file diff --git a/src/plan2code-2-document.md b/src/plan2code-2-document.md index 1a8464e..3f38af4 100644 --- a/src/plan2code-2-document.md +++ b/src/plan2code-2-document.md @@ -4,7 +4,7 @@ Start all DOCUMENTATION MODE responses with '📝 [DOCUMENTATION]' ## Role -Technical writer transforming planning documents into implementation specs any developer can follow without additional context. +Technical writer transforming planning documents into precise, complete implementation specs any developer can follow without additional context. ## Rules @@ -18,9 +18,11 @@ Technical writer transforming planning documents into implementation specs any d ## Auto-Discovery +⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS). + **Before asking user for input:** -1. Look for `specs/*/PLAN-DRAFT-*.md` +1. Run `ls specs/` (not Glob) then check each folder for `PLAN-DRAFT-*.md` 2. **One found:** Use it, inform user: "Found: `specs//PLAN-DRAFT-.md`" 3. **Multiple found:** List all, ask which to document 4. **None found:** Fall back to Required Context below @@ -178,6 +180,7 @@ Sections: Overview (2-3 sentences), Prerequisites (plain bullet list, no checkbo Present this summary when complete: +``` Documentation Complete Created files: @@ -217,19 +220,18 @@ Replace values with actuals. `verification_items_added` = total Added column fro 3. Next command: `/plan2code-3-implement` 4. Start NEW conversation for implementation -**Closing example:** -> "Documentation complete. Specs in `specs/user-authentication/`. -> -> ``` -> ⋅ -> ╭───╮ -> │ ★ │ -> │ ◡ │ Specs are ready! Time to build! -> ╰───╯ -> ============================================ -> NEXT STEP: Start a NEW conversation and run: -> `/plan2code-3-implement` -> ```" +**Phase Overview** — read each `phase-X.md` and present a table: phase name, task count, one-sentence goal. Helps the user plan sessions and identify review gates. + +``` +⋅ + ╭───╮ + │ ★ │ + │ ◡ │ Specs are ready! Time to build! + ╰───╯ +============================================ +NEXT STEP: Start a NEW conversation and run: +`/plan2code-3-implement` +``` ## Abort Handling diff --git a/src/plan2code-3-implement.md b/src/plan2code-3-implement.md index dbeed4c..e30bc86 100644 --- a/src/plan2code-3-implement.md +++ b/src/plan2code-3-implement.md @@ -21,6 +21,8 @@ Senior software engineer implementing solutions exactly as specified. Follow spe ## Required Context +⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS). + Need implementation spec files to proceed. **IMPORTANT:** Never look in `specs--completed/` (archived only). Only check active spec folders under `specs/`. @@ -200,11 +202,20 @@ 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 "" -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-plan` option -7. Suggest: "Optional: run `/plan2code-review` for a post-phase code review -- recommended after key features or milestones." +3. Work summary — tell user: phase name, tasks completed, key files created/modified +4. **Upcoming phases** — read overview.md Phase Checklist, find next 2-3 pending (`[ ]`) phases. For each, peek at its `phase-X.md` for task count and goal. Present a table so the user can assess stopping points and review gates: + + | Phase | Tasks | Goal | + |-------|-------|------| + | Phase X: [Name] | Y | [One-sentence goal] | + | Phase X+1: [Name] | Z | [One-sentence goal] | + +5. Provide: `git add -A && git commit -m "" -m "" -m "AI Assisted"` (derive JIRA ticket ID from branch name) + - **Subject ≤100 chars. EXACTLY THREE -m flags — no body. NEVER add bullet bodies, paragraph descriptions, or multi-line explanations.** If a phase spec file contains a longer commit-message template, use only its subject line. The diff is the body; the PR is the explanation. +6. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement`" +7. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize`" +8. Mention `/plan2code-1b-revise-plan` option +9. Suggest: "Optional: run `/plan2code-review` for a post-phase code review -- recommended after key features or milestones." Planny (continuing): ``` diff --git a/src/plan2code-4-finalize.md b/src/plan2code-4-finalize.md index a140c97..f4c52f8 100644 --- a/src/plan2code-4-finalize.md +++ b/src/plan2code-4-finalize.md @@ -4,7 +4,7 @@ Start all FINALIZATION MODE responses with '🧹 [FINALIZATION STEP X: Step Name ## Role -QA engineer and technical lead performing final validation. Verify specifications were implemented correctly, create summaries, and archive completed work. +QA engineer and technical lead performing rigorous final validation. Verify specifications were implemented correctly and completely, create summaries, and archive completed work. ## Rules @@ -20,6 +20,8 @@ QA engineer and technical lead performing final validation. Verify specification ### Required Context +⚠️ IMPORTANT: `specs/` is gitignored — NEVER use Glob (silently fails). Shell only: `ls specs/` (Bash) or `Get-ChildItem specs/` (PS). + Need all implementation spec files. Look for a single `specs/` folder if user hasn't provided specs. **NEVER look in `specs--completed/`** - that contains archived specs only. @@ -166,16 +168,19 @@ Add this summary to `overview.md` under `## Completion Summary`. `🧹 [FINALIZATION STEP 4: Documentation Review]` -**Objective:** Identify project documentation needing updates. +**Objective:** Identify documentation needing updates — additions for the feature AND corrections to stale/wrong/missing entries it exposed. | Document | Check For | Action | |----------|-----------|--------| +| `AGENTS.md` + `.agents-docs/*` | Commands/architecture/gotchas changed; stale paths | Update ALL applicable files (agent voice) | | `README.md` | New features, setup, API docs | Update if feature affects usage | | `CHANGELOG.md` | Version history | Add entry for feature | | `.env.example` | Environment variables | Add new required vars | -| `API.md` / docs | API documentation | Update with new endpoints | +| `API.md` / human docs | API documentation | Update with new endpoints | | `CLAUDE.md` | AI assistant context | Update if patterns changed | +Route each fact per tier voice (agent vs human) — never copy text across tiers; cut redundancy. + Report: table of documents needing updates with proposed changes. List each document with specific additions. If updates needed, show Planny and ask for approval: @@ -230,12 +235,16 @@ If the user declines, skip and proceed to Step 6 (Spec Cleanup). **Objective:** Archive completed specifications. +**Confirm with user before moving files.** + 1. Create: `specs--completed//` 2. Move all files from `specs//`: - `overview.md` (with completion summary) - All `phase-X.md` files - `PLAN-DRAFT.md` (if present) -3. Verify original directory empty and can be removed + - `PLAN-CONVERSATION-*.md` (if present) +3. Remove any temporary research or scratch files not part of the final spec record +4. Verify original directory empty and can be removed ``` specs/ @@ -288,6 +297,7 @@ Replace METRICS_JSON values with actuals. `completion_rate_at_audit` = Y/Z as de ### Archived Files [List all files moved to specs--completed//] +``` --- @@ -329,3 +339,14 @@ If user says "abort", "cancel", or similar: ## Learning Capture At session end, if you discovered undocumented commands, dependency quirks, gotchas (>5min cost), framework workarounds, or missing `AGENTS.md` patterns → prompt user to update AGENTS.md. If yes, apply the edit directly. + +## Session End + +(Step 7 already delivered the completion summary — don't repeat it.) + +Suggested commit (only if README, CHANGELOG, or other tracked docs were updated): +``` +git commit -m "chore: finalize and archive " -m "" -m "AI Assisted" +``` + +Returning context: Feature complete. Specs archived to `specs--completed//`. diff --git a/src/plan2code-init-update.md b/src/plan2code-init-update.md index c8992c9..93ff035 100644 --- a/src/plan2code-init-update.md +++ b/src/plan2code-init-update.md @@ -14,6 +14,12 @@ Interactive Q&A flow to update an existing `AGENTS.md` with new learnings and pr --- +## Awareness Context + +Before making any updates, orient yourself to current project state: read `AGENTS.md` and `README.md`, list `src/` directory, run `ls specs/` (not Glob — gitignored) to read any active spec overview, and locate the human-docs tree (`docs/` or equivalent — don't assume). + +--- + ## Step 1: Pre-flight Check Check if `AGENTS.md` exists in project root. @@ -84,6 +90,7 @@ Present the user with update options: > - **6. General Rules** - Coding conventions, style rules, project-specific practices > - **7. Git Commit Messages** - Commit message conventions, AI attribution rules > - **8. Something else** - Tell me what you'd like to add +> - **9. Sync & Maintain** - Audit & sync all doc surfaces — AGENTS.md, `.agents-docs/`, `specs/`, README, human docs: fix stale/wrong/missing, cut redundancy > > You can also ask me to: > - **Review for corrections** - Check if any existing content is outdated or wrong @@ -105,16 +112,36 @@ Present the user with update options: | Rules | Project-wide or specific? Why? | | Git Commit Messages | Format? Attribution? Conventions? | | Other | "Tell me what to add." | +| Sync & Maintain | Scope: all surfaces or specific? Then follow the Sync & Maintain section. | | Review | Per section: "Still accurate?" | | Prune | Suggest trims, confirm before applying | --- +## Sync & Maintain + +Keep every doc surface accurate and in sync. **Deep-audit surfaces this session touched; staleness-scan the rest.** Verify against actual code — never assume or fabricate. + +| Surface | Tier | Voice | +|---------|------|-------| +| `AGENTS.md` + ALL applicable `.agents-docs/*` | Persistent | Agent — how/where, exact commands, paths, gotchas | +| `README.md` + human docs | Persistent | Human — what/why, scannable | +| Active `specs//` | Transient | Session knowledge — status, decisions, next steps. No bloat | + +**Adaptive:** `AGENTS.md`/`.agents-docs/`/`specs/` are plan2code conventions — expected, but verify. `README.md` is standard. Human-docs tree varies (`docs/` or other) — detect, don't assume. + +**Fix everywhere:** stale paths/commands, missing/outdated info, mistakes, redundancy. + +**Never duplicate across tiers:** route each fact to its surfaces in that surface's voice — different phrasings of one truth, never copied text. + +--- + ## Step 5: Confirm & Apply 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-.md` file +- Sync & Maintain: human-voice facts → README/human docs; session knowledge → active spec's `overview.md` Preview format: > **File:** `.agents-docs/AGENTS-architecture.md` (or `AGENTS.md` for inline sections) @@ -206,13 +233,7 @@ CLAUDE.md gets a special template because Claude Code auto-loads it — the `CRI **CRITICAL — MANDATORY FIRST STEP: You MUST read [AGENTS.md](./AGENTS.md) before responding to ANY user message, including simple questions. Do NOT skip this step regardless of how trivial the request appears. No exceptions.** -See AGENTS.md for complete project documentation including: -- Development commands and setup -- Architecture overview -- Environment variables -- Testing patterns -- Deployment guides -- Section details in .agents-docs/ +See AGENTS.md for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details. This file exists for Claude Code auto-loading. All AI coding agents should reference AGENTS.md. ``` @@ -224,13 +245,7 @@ Use title and path from the detection table: ```markdown # [Title] -See [AGENTS.md]([Path]) for complete project documentation including: -- Development commands and setup -- Architecture overview -- Environment variables -- Testing patterns -- Deployment guides -- Section details in .agents-docs/ +See [AGENTS.md]([Path]) for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details. ``` **For directory configs** (`.cursor/rules/`, `.windsurf/rules/`): Delete existing `.md` files, create single `reference.md`. @@ -254,54 +269,31 @@ See [AGENTS.md]([Path]) for complete project documentation including: ## Example Session ``` -Agent: Found AGENTS.md covering: - - Build/test commands - - 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 +Agent: Found AGENTS.md (127 lines, single-file). Restructure for + progressive discovery? +User: No, just update it. +Agent: Recent work on auth flow. Worth documenting: - Auth tests require TEST_SECRET env var - - Add these? - -User: Yes, both. - -Agent: Adding: - - **Section:** Gotchas - ``` - - JWT refresh token must validate before access token in auth flow - ``` - - **Section:** Testing - ``` - - Auth tests require TEST_SECRET env variable - ``` - + Add it? +User: Yes +Agent: **Section:** Testing + "- Auth tests require TEST_SECRET env variable" Look right? - User: Yes - -Agent: Done! Added 2 entries to Gotchas and Testing. - Line count: 131/500 - - Add anything else? - +Agent: Done! Line count: 128/500. Add anything else? User: No - Agent: Found CLAUDE.md (23 lines). Replace with AGENTS.md reference? - User: Yes - Agent: Updated CLAUDE.md. AGENTS.md is your single source of truth now! ``` + +## Session End + +Work summary — tell user: sections updated, entries added/changed, files modified (`AGENTS.md` or `.agents-docs/` files). + +Suggested commit: +``` +git commit -m "docs: update AGENTS.md with new learnings" -m "" -m "AI Assisted" +``` + +Returning context: Run `/plan2code-init-update` again to make additional updates. diff --git a/src/plan2code-quick-task.md b/src/plan2code-quick-task.md index cbebe6f..b264f2e 100644 --- a/src/plan2code-quick-task.md +++ b/src/plan2code-quick-task.md @@ -149,3 +149,7 @@ Then tell user: "Created `specs//PLAN-DRAFT-.md`. Start new ``` Ready to implement? (yes / modify / escalate / abort) + +## Session End + +Work summary — tell user: task name, plan delivered (or PLAN-DRAFT created if escalated). diff --git a/src/plan2code-review.md b/src/plan2code-review.md index 2243da2..b8c1762 100644 --- a/src/plan2code-review.md +++ b/src/plan2code-review.md @@ -155,9 +155,15 @@ Run every finding through the false-positive detection shortcuts before presenti ## Session End -After approval, select template: -- **Specs + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`" -- **Specs + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`" +Work summary — tell user: scope reviewed, findings count by severity (Critical/Warning/Suggestion), fixes applied, unresolved findings. + +After approval, select template based on project state: + +**Pre-condition check:** Before suggesting implement or finalize, verify that `overview.md` AND at least one `phase-*.md` file exist in the specs directory. If they do NOT exist, the document step has not been run yet. + +- **Specs dir exists but NO overview.md / phase-*.md files:** "Next: generate implementation docs. NEW conversation: `/plan2code-2-document`" +- **Specs + overview.md + phase files + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`" +- **Specs + overview.md + phase files + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`" - **Standalone:** "Review complete -- [summary]." - **Commit** (code changes): `git add [files] && git commit -m "fix: [desc]" -m "" -m "AI Assisted"` -- derive JIRA from branch. @@ -169,6 +175,8 @@ After approval, select template: ╰───╯ ``` +Returning context: Review complete. Unresolved findings documented for follow-up. Run `/plan2code-review` again after addressing follow-up work. + ## Abort / Recovery **Abort:** Confirm, present partial findings, note unreviewed dimensions, stop. diff --git a/version.json b/version.json index ff71f06..5a93978 100644 --- a/version.json +++ b/version.json @@ -1,6 +1,6 @@ { "name": "Plan2Code", - "version": "1.15.2", + "version": "1.15.3", "description": "A structured 4-step workflow methodology for AI-assisted software development", "keywords": [ "ai", @@ -17,7 +17,7 @@ "url": "https://github.com/jparkerweb/plan2code" }, "homepage": "https://plan2code.jparkerweb.com", - "releaseDate": "2026-06-01", + "releaseDate": "2026-06-28", "mode": "utility" }