v1.3.3: Learning Capture Protocol and improved session instructions

CHANGELOG.md

@@ -2,6 +2,39 @@
 
 All notable changes to Plan2Code will be documented in this file.
 
+## v1.3.3 - 2025-12-30
+
+### ✨ Added
+
+- **Learning Capture Protocol** - Replaced simple "Session Hint" with structured learning capture
+  - Auto-capture triggers checklist (undocumented commands, gotchas, patterns, workarounds)
+  - Formatted capture template with category, learning, and context
+  - Inline `AGENTS.md` updates without requiring init-update mode switch
+  - Applied to Implementation (Step 3) and Finalize (Step 4) modes
+
+### 🔧 Changed
+
+- **Archive path includes timestamp** - Specs now archived to `specs--completed/<feature-name>-<timestamp>/`
+  - Prevents overwriting when re-implementing same feature
+  - Preserves history of multiple implementation attempts
+- **Clearer session end instructions** - Planning mode (Step 1) now explicitly says "ALWAYS tell the user"
+- **Simplified next command reference** - Removed "or equivalent" from next step instructions
+
+## v1.3.2 - 2025-12-25
+
+### 🔧 Changed
+
+- **Phase file naming convention** - Changed from `Phase X.md` to `phase-X.md` (lowercase, hyphen instead of space)
+  - Affects generated spec files in `specs/<feature-name>/`
+  - Updated references in documentation, implementation, and finalization modes
+- **PLAN-DRAFT auto-archiving** - Planning documents are now automatically archived without prompting
+  - Moves `specs/PLAN-DRAFT-<timestamp>.md` to `specs/<feature-name>/PLAN-DRAFT.md` after documentation step
+  - Removed user prompt asking to delete/archive/keep
+
+### 📦 Updated
+
+- Improved uniformity of Prompt files
+
 ## v1.3.1 - 2025-12-19
 
 ### ✨ Added

src/plan2code-1--plan.md

@@ -387,7 +387,7 @@ Structure every response in this order:
 
 ## Session End
 
-When planning is complete (PLAN-DRAFT created), tell the user:
+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`

src/plan2code-3--implement.md

@@ -396,6 +396,26 @@ If the user says "abort", "cancel", "start over", or similar:
 - Flag blockers and spec issues clearly - do not silently skip or assume
 - Your job is to BUILD according to spec, not to redesign
 
-## Session Hint
+## Learning Capture Protocol
 
-If you discovered any project-specific insights, gotchas, or conventions during implementation that future AI agents should know, suggest running `/plan2code---init-update` to capture them in `AGENTS.md`.
+At the END of each Implementation session, check:
+
+### Auto-Capture Triggers
+Proactively suggest updating `AGENTS.md` if ANY of these occurred:
+- [ ] You discovered an undocumented build/test command
+- [ ] You found a non-obvious dependency relationship
+- [ ] You encountered a "gotcha" that cost > 5 minutes
+- [ ] You made a workaround for a framework quirk
+- [ ] You found existing patterns not mentioned in `AGENTS.md`
+
+### Capture Format
+📚 LEARNING DETECTED
+
+I noticed something future agents should know:
+- Category: [Commands / Architecture / Gotchas / Testing / Config]
+- Learning: [concise description]
+- Context: [why this matters]
+
+Would you like me to update `AGENTS.md` with this? (yes/no)
+
+If user says yes, generate the specific edit and apply it (don't require switching to init-update mode).

src/plan2code-4--finalize.md

@@ -436,6 +436,26 @@ If the user says "abort", "cancel", "start over", or similar:
 - Archive specs to `specs--completed/<feature-name>/` - preserve folder name exactly
 - This is validation and cleanup only - do NOT write implementation code
 
-## Session Hint
+## Learning Capture Protocol
 
-If you discovered any project-specific insights, gotchas, or conventions during finalization that future AI agents should know, suggest running `/plan2code---init-update` to capture them in `AGENTS.md`.
+At the END of Finalize session, check:
+
+### Auto-Capture Triggers
+Proactively suggest updating `AGENTS.md` if ANY of these occurred:
+- [ ] You discovered an undocumented build/test command
+- [ ] You found a non-obvious dependency relationship
+- [ ] You encountered a "gotcha" that cost > 5 minutes
+- [ ] You made a workaround for a framework quirk
+- [ ] You found existing patterns not mentioned in `AGENTS.md`
+
+### Capture Format
+📚 LEARNING DETECTED
+
+I noticed something future agents should know:
+- Category: [Commands / Architecture / Gotchas / Testing / Config]
+- Learning: [concise description]
+- Context: [why this matters]
+
+Would you like me to update `AGENTS.md` with this? (yes/no)
+
+If user says yes, generate the specific edit and apply it (don't require switching to init-update mode).