Sync upstream workflow improvements (v1.15.3): session-end summaries, Sync & Maintain in init-update, plan research steps, ls-based spec discovery, revision/commit guardrails; bump version to v1.15.3

AI Assisted

.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.

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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "plan2code",
-  "version": "1.15.2",
+  "version": "1.15.3",
   "private": true,
   "bin": {
     "plan2code": "./install.js"

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?"
 

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
+- STOP at Step 2 for approval before applying spec updates
-- This mode modifies specs only - do NOT implement code
+- 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/<feature-name>/overview.md`
-- All `specs/<feature-name>/Phase X.md` files
+- All `specs/<feature-name>/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-<date>-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
+- 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/<feature-name>/`. Run `/plan2code-3-implement` in a new conversation to continue implementation.

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/<feature>/PLAN-DRAFT-<date>.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:**
+**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.
-> "Documentation complete. Specs in `specs/user-authentication/`.
+
->
+```
-> ```
+⋅
-> ⋅
+    ╭───╮
->     ╭───╮
+    │ ★ │
->     │ ★ │
+    │ ◡ │   Specs are ready! Time to build!
->     │ ◡ │   Specs are ready! Time to build!
+    ╰───╯
->     ╰───╯
+============================================
-> ============================================
+NEXT STEP: Start a NEW conversation and run:
-> NEXT STEP: Start a NEW conversation and run:
+`/plan2code-3-implement`
-> `/plan2code-3-implement`
+```
-> ```"
 
 ## Abort Handling
 

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 "<JIRA-Ticket-ID>" -m "AI Assisted"` (derive JIRA ticket ID from branch name)
+3. Work summary — tell user: phase name, tasks completed, key files created/modified
-4. **If more phases:** "NEXT STEP: Start NEW conversation and run: `/plan2code-3-implement`"
+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:
-5. **If final phase:** "NEXT STEP: Start NEW conversation and run: `/plan2code-4-finalize`"
+
-6. Mention `/plan2code-1b-revise-plan` option
+   | Phase | Tasks | Goal |
-7. Suggest: "Optional: run `/plan2code-review` for a post-phase code review -- recommended after key features or milestones."
+   |-------|-------|------|
+   | Phase X: [Name] | Y | [One-sentence goal] |
+   | Phase X+1: [Name] | Z | [One-sentence goal] |
+
+5. Provide: `git add -A && git commit -m "<subject>" -m "<JIRA-Ticket-ID>" -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):
 ```

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/<feature-name>` 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/<feature-name>/`
 2. Move all files from `specs/<feature-name>/`:
    - `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/<feature-name>/]
+```
 
 ---
 
@@ -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 <feature-name>" -m "<JIRA-Ticket-ID>" -m "AI Assisted"
+```
+
+Returning context: Feature complete. Specs archived to `specs--completed/<feature-name>/`.

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/<feature>/` | 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-<section-name>.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:
+See AGENTS.md for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details.
-- Development commands and setup
-- Architecture overview
-- Environment variables
-- Testing patterns
-- Deployment guides
-- Section details in .agents-docs/
 
 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:
+See [AGENTS.md]([Path]) for full project documentation: commands, architecture, environment, testing, deployment, and .agents-docs/ section details.
-- Development commands and setup
-- Architecture overview
-- 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`.
@@ -254,54 +269,31 @@ See [AGENTS.md]([Path]) for complete project documentation including:
 ## Example Session
 
 ```
-Agent: Found AGENTS.md covering:
+Agent: Found AGENTS.md (127 lines, single-file). Restructure for
-       - Build/test commands
+       progressive discovery?
-       - Project structure
+User:  No, just update it.
-       - API conventions
+Agent: Recent work on auth flow. Worth documenting:
-       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
        - Auth tests require TEST_SECRET env var
-
+       Add it?
-       Add these?
+User:  Yes
-
+Agent: **Section:** Testing
-User:  Yes, both.
+       "- Auth tests require TEST_SECRET env variable"
-
-Agent: Adding:
-
-       **Section:** Gotchas
-       ```
-       - JWT refresh token must validate before access token in auth flow
-       ```
-
-       **Section:** Testing
-       ```
-       - Auth tests require TEST_SECRET env variable
-       ```
-
        Look right?
-
 User:  Yes
-
+Agent: Done! Line count: 128/500. Add anything else?
-Agent: Done! Added 2 entries to Gotchas and Testing.
-       Line count: 131/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 "<JIRA-Ticket-ID>" -m "AI Assisted"
+```
+
+Returning context: Run `/plan2code-init-update` again to make additional updates.

src/plan2code-quick-task.md

@@ -149,3 +149,7 @@ Then tell user: "Created `specs/<feature-name>/PLAN-DRAFT-<date>.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).

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:
+Work summary — tell user: scope reviewed, findings count by severity (Critical/Warning/Suggestion), fixes applied, unresolved findings.
-- **Specs + more phases:** "Next: Phase X. NEW conversation: `/plan2code-3-implement`"
+
-- **Specs + all complete:** "All complete! NEW conversation: `/plan2code-4-finalize`"
+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 "<JIRA>" -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.

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"
 }