@sandrinio/vbounce 1.3.2 → 1.5.0

package/skills/improve/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: improve
+description: "Use when the V-Bounce OS framework needs to evolve based on accumulated agent feedback. Activates after sprint retros, when recurring friction patterns emerge, or when the user explicitly asks to improve the framework. Reads Process Feedback from sprint reports, identifies patterns, proposes specific changes to templates, skills, brain files, scripts, and agent configs, and applies approved changes. This is the system's self-improvement loop."
+---
+
+# Framework Self-Improvement
+
+## Purpose
+
+V-Bounce OS is not static. Every sprint generates friction signals from agents who work within the framework daily. This skill closes the feedback loop: it reads what agents struggled with, identifies patterns, and proposes targeted improvements to the framework itself.
+
+**Core principle:** No framework change happens without human approval. The system suggests — the human decides.
+
+## When to Use
+
+- After every 2-3 sprints (recommended cadence)
+- When the same Process Feedback appears across multiple sprint reports
+- When the user explicitly asks to improve templates, skills, or process
+- When a sprint's Framework Self-Assessment reveals Blocker-severity findings
+- When LESSONS.md contains 3+ entries pointing to the same process gap
+
+## Trigger
+
+`/improve` OR when the Team Lead identifies recurring framework friction during Sprint Consolidation.
+
+## Announcement
+
+When using this skill, state: "Using improve skill to evaluate and propose framework changes."
+
+## Input Sources
+
+The improve skill reads from multiple signals, in priority order:
+
+### 1. Sprint Report §5 — Framework Self-Assessment (Primary)
+The structured retro tables are the richest source. Each row has:
+- Finding (what went wrong)
+- Source Agent (who experienced it)
+- Severity (Friction vs Blocker)
+- Suggested Fix (agent's proposal)
+
+### 2. LESSONS.md — Recurring Patterns
+Lessons that point to *process* problems rather than *code* problems:
+- "Always check X before Y" → the template should enforce this ordering
+- "Agent kept missing Z" → the handoff report is missing a field
+- Lessons that keep getting re-flagged sprint after sprint
+
+### 3. Sprint Execution Metrics
+Quantitative signals from Sprint Report §3:
+- High bounce ratios → story templates may need better acceptance criteria guidance
+- High correction tax → handoffs may be losing critical context
+- Escalation patterns → complexity labels may need recalibration
+
+### 4. Agent Process Feedback (Raw)
+If sprint reports aren't available, read individual agent reports from `.bounce/archive/` and extract `## Process Feedback` sections directly.
+
+## The Improvement Process
+
+### Step 1: Gather Signals
+```
+1. Read the last 2-3 Sprint Reports (§5 Framework Self-Assessment)
+2. Read LESSONS.md — filter for process-related entries
+3. Read Sprint Execution Metrics — flag anomalies
+4. If no sprint reports exist yet, read raw agent reports from .bounce/archive/
+```
+
+### Step 2: Pattern Detection
+Group findings by framework area:
+
+| Area | What to Look For | Files Affected |
+|------|-----------------|----------------|
+| **Templates** | Missing fields, unused sections, ambiguous instructions | `templates/*.md` |
+| **Agent Handoffs** | Missing report fields, redundant data, unclear formats | `brains/claude-agents/*.md` |
+| **RAG Pipeline** | Irrelevant results, missing context, stale embeddings | `scripts/vbounce_index.mjs`, `scripts/vbounce_ask.mjs`, `scripts/pre_bounce_sync.sh` |
+| **Skills** | Unclear instructions, missing steps, outdated references | `skills/*/SKILL.md`, `skills/*/references/*` |
+| **Process Flow** | Unnecessary steps, wrong ordering, missing gates | `skills/agent-team/SKILL.md`, `skills/doc-manager/SKILL.md` |
+| **Tooling** | Script failures, validation gaps, missing automation | `scripts/*`, `bin/*` |
+| **Brain Files** | Stale rules, missing rules, inconsistencies across brains | `brains/CLAUDE.md`, `brains/GEMINI.md`, `brains/AGENTS.md`, `brains/cursor-rules/*.mdc` |
+
+Deduplicate: if 3 agents report the same issue, that's 1 finding with 3 votes — not 3 findings.
+
+### Step 3: Prioritize
+Rank findings by impact:
+
+1. **Blockers reported by 2+ agents** — fix immediately
+2. **Friction reported by 2+ agents** — fix in this improvement pass
+3. **Blockers reported once** — fix if the root cause is clear
+4. **Friction reported once** — note for next improvement pass (may be a one-off)
+
+### Step 4: Propose Changes
+For each finding, write a concrete proposal:
+
+```markdown
+### Proposal {N}: {Short title}
+
+**Finding:** {What went wrong — from the retro}
+**Pattern:** {How many times / sprints this appeared}
+**Root Cause:** {Why the framework allowed this to happen}
+**Affected Files:**
+- `{file_path}` — {what changes}
+
+**Proposed Change:**
+{Describe the specific edit. Include before/after for template changes.
+For skill changes, describe the new instruction or step.
+For script changes, describe the new behavior.}
+
+**Risk:** {Low / Medium — what could break if this change is wrong}
+**Reversibility:** {Easy — revert the edit / Medium — downstream docs may need updating}
+```
+
+### Step 5: Present to Human
+Present ALL proposals as a numbered list. The human can:
+- **Approve** — apply the change
+- **Reject** — skip it (optionally explain why)
+- **Modify** — adjust the proposal before applying
+- **Defer** — save for the next improvement pass
+
+**Never apply changes without explicit approval.** The human owns the framework.
+
+### Step 6: Apply Approved Changes
+For each approved proposal:
+1. Edit the affected file(s)
+2. If brain files are affected, ensure ALL brain surfaces stay in sync (CLAUDE.md, GEMINI.md, AGENTS.md, cursor-rules/)
+3. Log the change in `brains/CHANGELOG.md`
+4. If skills were modified, update skill descriptions in all brain files that reference them
+
+### Step 7: Validate
+After all changes are applied:
+1. Run `./scripts/pre_bounce_sync.sh` to update RAG embeddings with the new framework content
+2. Verify no cross-references are broken (template paths, skill names, report field names)
+3. Confirm brain file consistency — all 4 surfaces should describe the same process
+
+## Improvement Scope
+
+### What CAN Be Improved
+
+| Target | Examples |
+|--------|---------|
+| **Templates** | Add/remove/rename sections, improve instructions, add examples, fix ambiguity |
+| **Agent Report Formats** | Add/remove YAML fields, add report sections, improve handoff clarity |
+| **Skills** | Update instructions, add/remove steps, improve reference docs, add new skills |
+| **Brain Files** | Update rules, add missing rules, improve consistency, update skill references |
+| **Scripts** | Fix bugs, add validation checks, improve error messages, add new automation |
+| **Process Flow** | Reorder steps, add/remove gates, adjust thresholds (bounce limits, complexity labels) |
+| **RAG Pipeline** | Adjust indexing scope, improve chunking, add new document types to index |
+
+### What CANNOT Be Changed Without Escalation
+- **Adding a new agent role** — requires human design decision + new brain config
+- **Changing the V-Bounce state machine** — core process change, needs explicit human approval beyond normal improvement flow
+- **Removing a gate** (QA, Architect) — safety-critical, must be a deliberate human decision
+- **Changing git branching strategy** — affects all developers and CI/CD
+
+## Output
+
+The improve skill does not produce a standalone report file. Its output is:
+1. The list of proposals presented to the human (inline during the conversation)
+2. The applied changes to framework files
+3. The `brains/CHANGELOG.md` entries documenting what changed and why
+
+## Tracking Improvement Velocity
+
+Over time, the Sprint Report §5 Framework Self-Assessment tables should shrink. If the same findings keep appearing after improvement passes, the fix didn't work — re-examine the root cause.
+
+The Team Lead should note in the Sprint Report whether the previous improvement pass resolved the issues it targeted:
+- "Improvement pass from S-03 resolved the Dev→QA handoff gap (0 handoff complaints this sprint)"
+- "Improvement pass from S-03 did NOT resolve RAG relevance — same feedback from Developer"
+
+## Critical Rules
+
+- **Never change the framework without human approval.** Propose, don't impose.
+- **Keep all brain surfaces in sync.** A change to CLAUDE.md must be reflected in GEMINI.md, AGENTS.md, and cursor-rules/.
+- **Log everything.** Every change goes in `brains/CHANGELOG.md` with the finding that motivated it.
+- **Run pre_bounce_sync.sh after changes.** Updated skills and rules must be re-indexed for RAG.
+- **Don't over-engineer.** Fix the actual problem reported by agents. Don't add speculative improvements.
+- **Respect the hierarchy.** Template changes are low-risk. Process flow changes are high-risk. Scope accordingly.
+- **Skills are living documents.** If a skill's instructions consistently confuse agents, rewrite the confusing section — don't add workarounds elsewhere.
+
+## Keywords
+
+improve, self-improvement, framework evolution, retro, retrospective, process feedback, friction, template improvement, skill improvement, brain sync, meta-process, self-aware

package/templates/charter.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-9.
 
-1. **Header**: Set Status, Ambiguity Score, Readiness based on completeness
+1. **YAML Frontmatter**: Set status, ambiguity, and readiness
 2. **§1 Project Identity**: What it is, what it's NOT, success metrics
 3. **§2 Design Principles**: 3-5 numbered rules (these guide all future decisions)
 4. **§3 Architecture**: System diagram + Tech Stack table (mark unknown as `[TBD]`)
@@ -16,7 +16,7 @@ Ambiguity Score:
 - 🟡 Medium: Tech TBD but logic clear → Ready for Roadmap
 - 🟢 Low: All filled → Ready for Epics
 
-Output location: `product_plans/{project}_charter.md`
+Output location: `product_plans/strategy/{project}_charter.md`
 
 Document Hierarchy Position: ROOT
 Charter is the source of truth for WHY. All downstream documents inherit from it:
@@ -31,13 +31,13 @@ Downstream consumers:
 Do NOT output these instructions.
 </instructions>
 
-# Project Charter: [Project Name]
-
-> **Status**: 🌱 Initial Draft / 🌿 Refining / 🌳 Approved
-> **Ambiguity Score**: 🔴 High / 🟡 Medium / 🟢 Low
-> **Readiness**: Blocked / Ready for Roadmap / Ready for Epics
-
 ---
+status: "🌱 Initial Draft / 🌿 Refining / 🌳 Approved"
+ambiguity: "🔴 High / 🟡 Medium / 🟢 Low"
+readiness: "Blocked / Ready for Roadmap / Ready for Epics"
+---
+
+# Project Charter: [Project Name]
 
 ## 1. Project Identity
 

package/templates/delivery_plan.md

@@ -1,199 +1,44 @@
 <instructions>
-FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
-
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
 1. **Header**: Set Status, link to Roadmap + Risk Registry, Sprint Cadence
 2. **§1 Project Window**: Start/End dates, total sprints, team
-3. **§2 Sprint Registry**: Table of ALL sprints with goals and status (auto-populated between markers)
-4. **§3 Active Sprint**: CURRENT sprint only — goal + assigned stories with L1-L4 labels + V-Bounce state
-5. **§4 Backlog**: Prioritized stories not yet assigned to a sprint (includes Escalated + Parking Lot)
-6. **§5 Context Pack Status**: Per-story readiness checklist (ONLY for Active Sprint stories)
-6b. **§5b Open Questions**: Operational questions that may block active sprint stories
-7. **§6 Completed Sprints**: ONE-LINE summaries of finished sprints (full detail in version history)
-8. **§7 Change Log**: Auto-appended on updates
-9. **§8 Applied Hotfixes**: Ledger of L1 Trivial fixes that bypassed Epic/Story hierarchy (auto-appended by `hotfix_manager.sh ledger`)
-
-Sprint Lifecycle:
-- When a sprint completes: update Sprint Registry row to "Completed",
-  REPLACE §3 Active Sprint with the next sprint's stories,
-  move old sprint summary to §6 Completed Sprints (one row, not full detail).
-- Full historical detail is preserved in vp_document_versions (auto-snapshots on every update).
-
-Sprint States: Planning → Active → Completed → Cancelled
-
-Story Labels (complexity_label):
-- L1: Trivial (single file, <1hr vibe time)
-- L2: Standard (2-3 files, known pattern) — DEFAULT
-- L3: Complex (cross-cutting, spike may be needed)
-- L4: Uncertain (requires Probing/Spiking before Bounce)
-
-V-Bounce States (11 total):
-Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done
-  ↳ Refinement → Probing/Spiking → Refinement (spike loop)
-  ↳ Any → Parking Lot (deferred)
-  ↳ Bouncing → Escalated (3+ failures)
-
-IMPORTANT: The §2 Sprint Registry is auto-populated by SyncEngine.
-Rows between <!-- SPRINT_REGISTRY_START --> and <!-- SPRINT_REGISTRY_END -->
-markers MUST be on their own lines (not inside table pipes).
-
-Output location: `product_plans/{delivery}/DELIVERY_PLAN.md`
-(Lives at the root of its delivery folder. One Delivery Plan per delivery/release.)
-
-Document Hierarchy Position: LEVEL 5 — EXECUTION
-Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → **Delivery Plan** (execution) → Risk Registry (risks)
+3. **§2 Epics Included**: Table of all Epics assigned to this delivery
+4. **§3 High-Level Backlog**: Unassigned stories (Epics being broken down)
 
-This is the OPERATIONAL layer. It does NOT define what to build (that's Roadmap + Epic).
-It defines WHEN and in WHAT ORDER stories execute within sprints.
-
-Upstream sources:
-- Stories come from Epics (via Epic §9 Artifact Links)
-- Sprint goals align with Roadmap §2 Release Plan milestones
-- Story complexity labels (L1-L4) are defined in the Story template
-
-Downstream consumers:
-- Team Lead Agent reads this to initialize the Bounce (via agent-team skill)
-- §5 Context Pack Status gates whether a story is Ready to Bounce
-- Sprint Reports are generated from Active Sprint data + agent reports
-- Risk Registry §2 Risk Analysis Log references sprint transitions
+Delivery Lifecycle:
+- This document tracks the *milestone* across multiple sprints.
+- Active sprint work happens inside `sprints/sprint-{XX}/sprint-{XX}.md`, not here.
+- When the delivery is fully shipped, this entire document is archived.
 
+Output location: `product_plans/strategy/{delivery}_delivery_plan.md`
 Do NOT output these instructions.
 </instructions>
-
 # Delivery Plan: {Project Name}
-
 ---
-
 > **Last Updated**: {YYYY-MM-DD}
-> **Status**: Planning / In Sprint / Delivered
+> **Status**: Planning / In Delivery / Completed
 > **Roadmap**: `product_plans/{project}_roadmap.md`
 > **Risk Registry**: `product_plans/RISK_REGISTRY.md`
 > **Delivery**: `D-{NN}_{release_name}`
-> **Sprint Cadence**: 1-week sprints within 2-week project window
-
+> **Sprint Cadence**: 1-week sprints
 ---
-
 ## 1. Project Window
-
 | Key | Value |
 |-----|-------|
 | **Start Date** | {YYYY-MM-DD} |
 | **End Date** | {YYYY-MM-DD} |
 | **Total Sprints** | {N} |
-| **Sprint Length** | 1 week |
-| **Project Window** | 2 weeks |
 | **Team** | {CE name(s) / Agent config} |
-
----
-
-## 2. Sprint Registry
-
-<!--
-AUTO-POPULATED SECTION
-Updated when sprints are created or completed.
-DO NOT manually edit the table rows - they are managed by the system.
--->
-
-| Sprint | Dates | Sprint Goal | Status | Stories | Completed |
-|--------|-------|-------------|--------|---------|-----------|
-<!-- SPRINT_REGISTRY_START -->
-| S-01 | {MM/DD - MM/DD} | {One-sentence North Star} | Planning / Active / Completed | {X} | {Y}/{X} |
-<!-- SPRINT_REGISTRY_END -->
-
 ---
-
-## 3. Active Sprint
-
-### Sprint Goal
-> {One-sentence functional "North Star" — what is shippable at the end of this sprint?}
-
-### Assigned Stories
-
-| # | Story | Epic | Label | V-Bounce State | Context Pack |
-|---|-------|------|-------|----------------|--------------|
-| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L1/L2/L3/L4 | Draft / Refinement / Ready to Bounce / Bouncing | Locked / Open |
-
-### Sprint Notes
-- {Blockers, dependencies, decisions made during the sprint}
-
----
-
-## 4. Backlog
-
-> Prioritized stories not yet assigned to a sprint.
-
-| Priority | Story | Epic | Label | V-Bounce State | Blocker |
-|----------|-------|------|-------|----------------|---------|
-| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L2 | Draft | — |
-
-### Escalated
-> Stories with 3+ bounce failures requiring PM/BA intervention.
-
-| Story | Epic | Bounce Count | Escalation Reason |
-|-------|------|--------------|-------------------|
-| — | — | — | No escalated stories |
-
-### Parking Lot
-> Stories moved out of current project window scope (V-Bounce state: Parking Lot).
-
-- STORY-XXX-YY: {name} — Reason: {why deferred}
-
----
-
-## 5. Context Pack Status
-
-> Tracks readiness of ACTIVE SPRINT stories only.
-> A story is **Ready to Bounce** only when all items are checked.
-> Context Packs for future sprints are tracked when they enter the Active Sprint.
-> L4 stories MUST pass through Probing/Spiking before reaching Ready to Bounce.
-
-### {STORY-XXX-YY}: {name} (Label: {L1/L2/L3/L4})
-- [ ] Story spec complete (§1 The Spec)
-- [ ] Acceptance criteria written (§2 The Truth)
-- [ ] Implementation guide filled (§3 Implementation Guide)
-- [ ] Ambiguity: Low
-- [ ] BA sign-off
-- [ ] Architect sign-off
-- [ ] Spike completed (L4 only — skip for L1-L3)
-- **V-Bounce State**: {current state} → Ready to Bounce
-
----
-
-## 5b. Open Questions
-
-> Operational questions that may block stories in the active sprint.
-> Strategic questions belong in the Roadmap §6.
-> The Team Lead MUST check this section before starting a sprint — do NOT bounce stories with unresolved blocking questions.
-
-| Question | Affects Story | Impact | Owner | Status |
-|----------|--------------|--------|-------|--------|
-| {e.g., "Which date format for the API?"} | STORY-001-02 | Blocks implementation | {name} | Open / Resolved |
-
----
-
-## 6. Completed Sprints
-
-> One-line summaries only. Full detail preserved in document version history.
-
-| Sprint | Goal | Delivered | Notes |
-|--------|------|-----------|-------|
-| — | — | — | No sprints completed yet |
-
----
-
-## 7. Change Log
-
-<!-- Auto-appended when Delivery Plan is updated -->
-
-| Date | Change | By |
-|------|--------|-----|
-| {YYYY-MM-DD} | Initial creation from Roadmap | Architect |
-
----
-
-## 8. Applied Hotfixes
-
-> L1 Trivial fixes that bypassed the Epic/Story hierarchy. Auto-appended by `hotfix_manager.sh ledger`.
-
-| Date | Title | Brief Description |
-|------|-------|-------------------|
-| — | — | No hotfixes applied yet |
+## 2. Epics Included
+| Epic | Name | Status | Stories | V-Bounce Phase |
+|------|------|--------|---------|----------------|
+| EPIC-XXX | {Name} | Draft / Refinement / Bouncing / Done | {Y}/{X} | {Phase Name} |
+---
+## 3. High-Level Backlog
+> Stories prioritized for this delivery but not yet assigned to an active Sprint.
+| Priority | Story | Epic | Label | Blocker |
+|----------|-------|------|-------|---------|
+| 1 | STORY-XXX-YY: {name} | EPIC-XXX | L2 | — |
+### Escalated / Parking Lot
+- STORY-XXX-YY: {name} — Reason: {escalated / deferred}

package/templates/epic.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order.
 
-1. **Metadata Table**: Status, Ambiguity, Priority, Owner, Tags, Target Date
+1. **YAML Frontmatter**: Epic ID, Status, Ambiguity, Context Source, Release, Owner, Priority, Tags, Target Date
 2. **§1 Problem & Value**: Why (problem), What (solution), Success Metrics
 3. **§2 Scope Boundaries**: IN-SCOPE checkboxes, OUT-OF-SCOPE list
 4. **§3 Context**: Personas, User Journey diagram, Constraints table
@@ -17,7 +17,7 @@ Ambiguity Score:
 - 🟡 Medium: Scope clear, tech TBD → Ready for decomposition
 - 🟢 Low: All filled → Ready for Stories
 
-Output location: `product_plans/{delivery}/EPIC-{NNN}_{epic_name}/EPIC-{NNN}.md`
+Output location: `product_plans/backlog/EPIC-{NNN}_{epic_name}/EPIC-{NNN}_{epic_name}.md`
 
 Document Hierarchy Position: LEVEL 3 (Charter → Roadmap → **Epic** → Story)
 
@@ -37,21 +37,19 @@ Downstream consumers:
 Do NOT output these instructions.
 </instructions>
 
-# EPIC-{ID}: {Epic Name}
-
-## Metadata
-| Field | Value |
-|-------|-------|
-| **Status** | Draft / Ready / In Progress / Done |
-| **Ambiguity** | 🔴 High / 🟡 Medium / 🟢 Low |
-| **Context Source** | Charter §{section} / Roadmap §{section} / User Input |
-| **Release** | {Release name from Roadmap §2} |
-| **Owner** | {PM/PO name} |
-| **Priority** | P0 - Critical / P1 - High / P2 - Medium |
-| **Tags** | #frontend, #api, #auth |
-| **Target Date** | {YYYY-MM-DD} |
-
 ---
+epic_id: "EPIC-{ID}"
+status: "Draft / Ready / In Progress / Done"
+ambiguity: "🔴 High / 🟡 Medium / 🟢 Low"
+context_source: "Charter §{section} / Roadmap §{section} / User Input"
+release: "{Release name from Roadmap §2}"
+owner: "{PM/PO name}"
+priority: "P0 - Critical / P1 - High / P2 - Medium"
+tags: ["frontend", "api", "auth"]
+target_date: "{YYYY-MM-DD}"
+---
+
+# EPIC-{ID}: {Epic Name}
 
 ## 1. Problem & Value
 > Target Audience: Stakeholders, Business Sponsors
@@ -190,9 +188,11 @@ Feature: {Epic Name}
 ## 9. Artifact Links
 > Auto-populated as Epic is decomposed.
 
-**Stories:**
-- [ ] STORY-{ID}-01: {name}
-- [ ] STORY-{ID}-02: {name}
+**Stories (Status Tracking):**
+> Keep track of where stories live contextually.
+- [ ] STORY-{ID}-01-{story_name} -> Backlog
+- [ ] STORY-{ID}-02-{story_name} -> Active (Sprint XX)
+- [x] STORY-{ID}-03-{story_name} -> Archived (Sprint YY)
 
 **References:**
 - Charter: [PROJECT CHARTER](link)

package/templates/hotfix.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. This is a lightweight alternative to the Epic/Story hierarchy for L1 (Trivial) tasks.
 
-1. **Metadata Table**: Target Release, Status, Actor
+1. **YAML Frontmatter**: Hotfix ID, Status, Target Release, Actor, Complexity Label
 2. **§1 The Fix**: What is broken/changing and why
 3. **§2 Implementation Instructions**: Which file(s) to change and what to do
 4. **§3 Verification**: Simple manual test
@@ -20,18 +20,15 @@ Constraints:
 Do NOT output these instructions.
 </instructions>
 
-# HOTFIX: {Name}
-
-## Metadata
-
-| Field | Value |
-|-------|-------|
-| **Target Release** | `D-{NN}_{release_name}` |
-| **Status** | Draft / Bouncing / Done |
-| **Actor** | {Persona Name / User} |
-| **Complexity Label** | L1 (Trivial) |
-
 ---
+hotfix_id: "HOTFIX-{Date}-{Name}"
+status: "Draft / Bouncing / Done"
+target_release: "D-{NN}_{release_name}"
+actor: "{Persona Name / User}"
+complexity_label: "L1 (Trivial)"
+---
+
+# HOTFIX: {Name}
 
 ## 1. The Fix
 > What needs to be changed and why.

package/templates/risk_registry.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
 
-1. **Header**: Set Status, link to Roadmap and Delivery Plan
+1. **YAML Frontmatter**: Set status, last updated, and roadmap ref
 2. **§1 Active Risks**: Table of open risks with phase, source, likelihood, impact, mitigation
 3. **§2 Risk Analysis Log**: Phase-stamped entries appended on state transitions
 4. **§3 Closed Risks**: Resolved/mitigated risks moved here
@@ -13,7 +13,7 @@ Risk Levels:
 
 Risk Statuses: Open → Mitigating → Mitigated → Closed / Accepted
 
-Output location: `product_plans/RISK_REGISTRY.md`
+Output location: `product_plans/strategy/RISK_REGISTRY.md`
 
 Document Hierarchy Position: LEVEL 6 — CROSS-CUTTING
 Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → **Risk Registry** (risks)
@@ -31,21 +31,19 @@ The Risk Registry is reviewed by the Team Lead at sprint boundaries and by the A
 Do NOT output these instructions.
 </instructions>
 
-# Risk Registry: {Project Name}
-
 ---
-
-> **Last Updated**: {YYYY-MM-DD}
-> **Status**: Active / Archived
-> **Roadmap**: `product_plans/{project}_roadmap.md`
-
+last_updated: "{YYYY-MM-DD}"
+status: "Active / Archived"
+roadmap_ref: "product_plans/{project}_roadmap.md"
 ---
 
+# Risk Registry: {Project Name}
+
 ## 1. Active Risks
 
 | ID | Risk | Phase | Source | Likelihood | Impact | Mitigation | Owner | Status |
 |----|------|-------|--------|------------|--------|------------|-------|--------|
-| R-001 | {Risk description} | {Verification/Bounce/Review} | {EPIC-XXX or STORY-XXX-YY} | Low/Medium/High | Low/Medium/High/Critical | {Mitigation strategy} | {Owner} | Open |
+| R-001 | {Risk description} | {Verification/Bounce/Review} | {EPIC-XXX or STORY-XXX-YY-{story_name}} | Low/Medium/High | Low/Medium/High/Critical | {Mitigation strategy} | {Owner} | Open |
 
 **Summary**: {X} Active | {Y} Mitigating | {Z} Accepted
 

package/templates/roadmap.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
 
-1. **Header**: Set Status, Last Updated, link to Charter
+1. **YAML Frontmatter**: Set status, last updated, charter ref, and risk registry ref
 2. **§1 Strategic Context**: Vision (from Charter), primary goal, target users, success metrics
 3. **§2 Release Plan**: Group epics into named releases with exit criteria — NOT sprint-level tracking
 4. **§3 Technical Architecture Decisions**: Key choices with rationale and status (this is the ADR log)
@@ -11,7 +11,7 @@ FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
 8. **§7 Delivery Log**: Release notes for completed deliveries (appended by Team Lead on delivery archive)
 9. **§8 Change Log**: Auto-appended on updates
 
-Output location: `product_plans/{project}_roadmap.md`
+Output location: `product_plans/strategy/{project}_roadmap.md`
 
 Role of this document:
 - This is the STRATEGIC layer between Charter (why) and Delivery Plan (operational execution).
@@ -26,17 +26,15 @@ Charter (why) → **Roadmap** (strategic what/when) → Epic (detailed what) →
 Do NOT output these instructions.
 </instructions>
 
-# Product Roadmap: {Project Name}
-
 ---
-
-> **Last Updated**: {YYYY-MM-DD}
-> **Status**: Planning / Active / MVP Complete / Shipped
-> **Charter**: `product_plans/{project}_charter.md`
-> **Risk Registry**: `product_plans/RISK_REGISTRY.md`
-
+last_updated: "{YYYY-MM-DD}"
+status: "Planning / Active / MVP Complete / Shipped"
+charter_ref: "product_plans/{project}_charter.md"
+risk_registry_ref: "product_plans/RISK_REGISTRY.md"
 ---
 
+# Product Roadmap: {Project Name}
+
 ## 1. Strategic Context
 
 | Key | Value |