@sandrinio/vbounce 1.3.2 → 1.5.0

package/templates/sprint.md

@@ -0,0 +1,48 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-2.
+
+1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status
+2. **§1 Active Scope**: Table of stories pulled into this sprint. The V-Bounce state tracks its progression.
+3. **§2 Sprint Open Questions**: Unresolved items blocking this active execution window.
+
+Output location: `product_plans/sprints/sprint-{XX}/sprint-{XX}.md`
+
+Role of this document:
+- This is the Tactical view of the active sprint execution.
+- It tracks ONLY the stories claimed for this 1-week window.
+- The Team Lead agent reads this to know what is in scope.
+
+Document Lifecycle:
+- Created by the Team Lead or PM during Sprint Setup.
+- Selected stories are physically moved from `product_plans/backlog/EPIC-*/` to `product_plans/sprints/sprint-{XX}/`.
+- When the sprint completes, this document (and the entire sprint folder) moves to `product_plans/archive/sprints/sprint-{XX}/`.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+sprint_id: "sprint-{XX}"
+sprint_goal: "{One-sentence North Star}"
+dates: "{MM/DD - MM/DD}"
+status: "Planning / Active / Completed"
+---
+
+# Sprint S-{XX} Plan
+
+## 1. Active Scope
+> Stories pulled from the backlog for execution during this sprint window.
+> The V-Bounce State tracks the live status of the story (Draft -> Ready to Bounce -> Bouncing -> QA Passed -> Architect Passed -> Sprint Review -> Done).
+
+| Priority | Story | Epic | Label | V-Bounce State | Blocker |
+|----------|-------|------|-------|----------------|---------|
+| 1 | [STORY-XXX-YY: name](./STORY-XXX-YY-name.md) | EPIC-XXX | L2 | Draft | — |
+
+### Escalated / Parking Lot
+- STORY-XXX-YY: {name} — Reason: {escalated / deferred}
+
+## 2. Sprint Open Questions
+> Unresolved items that affect this specific 1-week execution window.
+
+| Question | Options | Impact | Owner | Status |
+|----------|---------|--------|-------|--------|
+| {question} | A: {x}, B: {y} | Blocks {stories} | {name} | Open / Decided |

package/templates/sprint_report.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-6.
 
-1. **Header**: Sprint ID, Goal, Dates, Status, Delivery
+1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status, Delivery Ref, Delivery Plan Ref
 2. **§1 What Was Delivered**: User-facing summary — what's accessible/usable vs what's internal/backend
 3. **§2 Story Results**: Table of all stories with final status and per-story metrics
 4. **§3 Execution Metrics**: AI performance metrics — tokens, duration, bounces, correction tax
@@ -20,18 +20,18 @@ versus what was built under the hood. Write it from the user's perspective, not
 Do NOT output these instructions.
 </instructions>
 
-# Sprint Report: S-{XX}
-
 ---
-
-> **Sprint Goal**: {One-sentence North Star}
-> **Dates**: {MM/DD - MM/DD}
-> **Status**: Achieved / Partially Achieved / Failed
-> **Delivery**: D-{NN}_{release_name}
-> **Delivery Plan**: `product_plans/{delivery}/DELIVERY_PLAN.md`
-
+sprint_id: "S-{XX}"
+sprint_goal: "{One-sentence North Star}"
+dates: "{MM/DD - MM/DD}"
+status: "Achieved / Partially Achieved / Failed"
+total_tokens_used: {N}
+delivery_ref: "D-{NN}_{release_name}"
+delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 ---
 
+# Sprint Report: S-{XX}
+
 ## 1. What Was Delivered
 
 ### User-Facing (Accessible Now)
@@ -51,12 +51,12 @@ Do NOT output these instructions.
 ### Not Completed
 > Stories that were planned but didn't make it (escalated, deferred, or partially done).
 
-- {e.g., "STORY-001-03: Email notifications — Escalated (template integration failed 3x)"}
+- {e.g., "STORY-001-03-email_notifications — Escalated (template integration failed 3x)"}
 
 ### Product Docs Affected
 > Any product documentation files modified, created, or identified for updates. Handed off to Scribe agent.
 
-- {e.g., "product_documentation/api_reference.md — Added rate limiting details"}
+- {e.g., "vdocs/api_reference.md — Added rate limiting details"}
 
 ---
 
@@ -64,13 +64,13 @@ Do NOT output these instructions.
 
 | Story | Epic | Label | Final State | Bounces (QA) | Bounces (Arch) | Correction Tax |
 |-------|------|-------|-------------|--------------|----------------|----------------|
-| STORY-{ID}: {name} | EPIC-{ID} | L{N} | Done / Escalated / Parking Lot | {N} | {N} | {X}% |
+| STORY-{ID}-{story_name} | EPIC-{ID} | L{N} | Done / Escalated / Parking Lot | {N} | {N} | {X}% |
 
 ### Story Highlights
-- **{STORY-ID}**: {1-sentence summary of what was built and any notable decisions}
+- **STORY-{ID}-{story_name}**: {1-sentence summary of what was built and notable decisions}
 
 ### Escalated Stories (if any)
-- **{STORY-ID}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
+- **STORY-{ID}-{story_name}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
 
 ---
 
@@ -105,13 +105,13 @@ Do NOT output these instructions.
 
 | Story | Tokens | Duration | Agent Sessions | Bounces | Cost |
 |-------|--------|----------|----------------|---------|------|
-| STORY-{ID} | {N} | {Xh Ym} | {N} | {N} | ${X.XX} |
+| STORY-{ID}-{story_name} | {N} | {Xh Ym} | {N} | {N} | ${X.XX} |
 
 ### Threshold Alerts
 > Flag any metrics that crossed warning or critical thresholds. If none, write "No threshold alerts."
 
-- {e.g., "STORY-001-05: Correction Tax 10% (🟡) — root cause: test architecture rework due to ESM timer conflict"}
-- {e.g., "STORY-002-03: 2 QA bounces — spec ambiguity in edge case handling"}
+- {e.g., "STORY-001-05-test_arch: Correction Tax 10% (🟡) — root cause: test architecture rework due to ESM timer conflict"}
+- {e.g., "STORY-002-03-edge_cases: 2 QA bounces — spec ambiguity in edge case handling"}
 
 ---
 
@@ -121,7 +121,7 @@ Do NOT output these instructions.
 
 | Source | Lesson | Approved? |
 |--------|--------|-----------|
-| STORY-{ID} Dev Report | {What happened and proposed rule} | Pending / Yes / No |
+| STORY-{ID}-{story_name} Dev Report | {What happened and proposed rule} | Pending / Yes / No |
 
 ---
 
@@ -136,17 +136,55 @@ Do NOT output these instructions.
 ### What Didn't Go Well
 > Problems encountered, root causes, and impact on the sprint.
 
-- {e.g., "STORY-001-03 escalated because the spec was ambiguous — 3 QA bounces wasted"}
-- {e.g., "Merge conflict on STORY-002-01 required a fix story — cost an extra half-day"}
+- {e.g., "STORY-001-03-api_spec escalated because the spec was ambiguous — 3 QA bounces wasted"}
+- {e.g., "Merge conflict on STORY-002-01-database required a fix story — cost an extra half-day"}
+
+### Framework Self-Assessment
+> Aggregated from agent Process Feedback sections. Categorized by area of the V-Bounce framework.
+> Severity: **Friction** (slowed work) or **Blocker** (required workaround).
+> These feed the `improve` skill for framework evolution.
+
+#### Templates
+> Template sections that were confusing, incomplete, had unused fields, or were missing critical information.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Story §3 missing 'existing modules to reuse' field"} | Developer | Friction | {Add a reuse checklist to the story template} |
+
+#### Agent Handoffs
+> Information that was missing, redundant, or unclear when passed between agents via reports.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Dev report didn't specify test runner — QA had to discover it"} | QA | Friction | {Add 'test_runner' to Dev report YAML frontmatter} |
+
+#### RAG Pipeline
+> Context quality issues — irrelevant results, missing critical context, stale embeddings.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Query for 'auth constraints' returned old sprint results"} | Developer | Friction | {Add date-weighted ranking to vbounce_ask.mjs} |
+
+#### Skills
+> Skill instructions that were unclear, had gaps, or could be improved for better agent performance.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "vibe-code-review Deep Audit missing accessibility dimension"} | Architect | Friction | {Add dimension 7 to deep-audit.md} |
+
+#### Process Flow
+> Steps that were unnecessary, wrongly ordered, or missing for this type of work.
+
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "Fast Track stories still triggered Architect pass in the checklist"} | Team Lead | Blocker | {Update agent-team SKILL.md Step 4 skip logic} |
 
-### Process Improvements
-> Changes to the V-Bounce delivery process itself — not just this project, but how we work.
+#### Tooling & Scripts
+> Script failures, validation gaps, or automation opportunities.
 
-- {e.g., "Story specs for L3+ stories should require Architect pre-review before bouncing"}
-- {e.g., "QA found the same import ordering issue in 3 stories — add linting rule to Dev setup, not just LESSONS.md"}
-- {e.g., "L3 stories consumed 4x the tokens of L2s — add a complexity budget to sprint planning"}
-- {e.g., "First-pass success rate was 40% — require Ambiguity 🟢 on all stories, not just Context Pack checks"}
-- {e.g., "Sprint Integration Audit (Step 6) found no issues in 3 consecutive sprints — consider making it conditional for small sprints"}
+| Finding | Source Agent | Severity | Suggested Fix |
+|---------|-------------|----------|---------------|
+| {e.g., "validate_report.mjs doesn't check for Process Feedback section"} | Team Lead | Friction | {Add optional section validation} |
 
 ---
 

package/templates/story.md

@@ -1,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
 
-1. **Metadata Table**: Parent Epic, Status, Ambiguity, Actor, Complexity, Complexity Label
+1. **YAML Frontmatter**: Story ID, Parent Epic, Status, Ambiguity, Context Source, Actor, Complexity, Complexity Label
 2. **§1 The Spec**: User Story (As a... I want... So that...) + Detailed Requirements
 3. **§2 The Truth**: Gherkin acceptance criteria + manual verification steps
 4. **§3 Implementation Guide**: Files to modify, technical logic, API contract
@@ -12,8 +12,11 @@ Ambiguity Score:
 - 🟡 Medium: Logic clear, files TBD
 - 🟢 Low: Ready for coding
 
-Output location: `product_plans/{delivery}/EPIC-{NNN}_{epic_name}/STORY-{EpicID}-{StoryID}.md`
-(Stories live inside their parent Epic folder — a Story never exists without an Epic.)
+Output location (Draft/Refinement): `product_plans/backlog/EPIC-{NNN}_{epic_name}/STORY-{EpicID}-{StoryID}-{StoryName}.md`
+
+Sprint Lifecycle Rule:
+- When a sprint starts, this Story file is MOVED to `product_plans/sprints/sprint-{XX}/`.
+- When the sprint completes, this Story file is MOVED to `product_plans/archive/sprints/sprint-{XX}/`.
 
 Document Hierarchy Position: LEVEL 4 (Charter → Roadmap → Epic → **Story**)
 
@@ -38,19 +41,18 @@ Agent handoff sections:
 Do NOT output these instructions.
 </instructions>
 
-# STORY-{EpicID}-{StoryID}: {Story Name}
+---
+story_id: "STORY-{EpicID}-{StoryID}-{StoryName}"
+parent_epic_ref: "EPIC-{ID}"
+status: "Draft / Refinement / Probing/Spiking / Ready to Bounce / Bouncing / QA Passed / Architect Passed / Sprint Review / Done / Escalated / Parking Lot"
+ambiguity: "🔴 High / 🟡 Medium / 🟢 Low"
+context_source: "Epic §{section} / Codebase / User Input"
+actor: "{Persona Name}"
+complexity: "Small (1 file) / Medium (2-3 files) / Large (Refactor needed)"
+complexity_label: "L1 / L2 / L3 / L4 (default: L2)"
+---
 
-## Metadata
-
-| Field | Value |
-|-------|-------|
-| **Parent Epic** | [EPIC-{ID}: {Name}](link) |
-| **Status** | Draft / Refinement / Probing/Spiking / Ready to Bounce / Bouncing / QA Passed / Architect Passed / Sprint Review / Done / Escalated / Parking Lot |
-| **Ambiguity** | 🔴 High / 🟡 Medium / 🟢 Low |
-| **Context Source** | Epic §{section} / Codebase / User Input |
-| **Actor** | {Persona Name} |
-| **Complexity** | Small (1 file) / Medium (2-3 files) / Large (Refactor needed) |
-| **Complexity Label** | L1 / L2 / L3 / L4 (default: L2) |
+# STORY-{EpicID}-{StoryID}: {Story Name}
 
 ### Complexity Labels (Sprint Planning)