@sandrinio/vbounce 1.9.0 → 2.1.0

package/templates/epic.md

@@ -21,10 +21,12 @@ Output location: `product_plans/backlog/EPIC-{NNN}_{epic_name}/EPIC-{NNN}_{epic_
 
 Document Hierarchy Position: LEVEL 3 (Charter → Roadmap → **Epic** → Story)
 
+**Codebase research is mandatory when filling §4 Technical Context.** Do NOT guess at affected files, dependencies, or integration points. Read the actual codebase — explore directories, read files listed in upstream documents, understand current architecture — then fill §4 with real file paths and verified dependencies.
+
 Upstream sources:
 - §1 Problem & Value traces to Charter §1.1 (What It Is) and §5 (Key Workflows)
 - §3.3 Constraints inherits from Charter §6 and Roadmap §5 Strategic Constraints
-- §4 Technical Context references Roadmap §3 ADRs for architecture decisions
+- §4 Technical Context references Roadmap §3 ADRs for architecture decisions AND actual codebase exploration
 - Metadata.Priority aligns with Roadmap §2 Release Plan epic priorities
 
 Downstream consumers:
@@ -132,21 +134,22 @@ flowchart LR
 ---
 
 ## 5. Decomposition Guidance
-> Hints for AI story breakdown. Check all that apply.
-
-- [ ] **Schema/Migration** - Database changes, new tables/fields
-- [ ] **API Work** - New/modified endpoints
-- [ ] **UI Work** - New screens or components
-- [ ] **Integration** - External service connection
-- [ ] **Infrastructure** - Config, env vars, deployment
-- [ ] **Testing** - E2E, integration tests
-- [ ] **Documentation** - User-facing or API docs
-
-### Suggested Story Sequence
-1. {First: usually schema/data layer}
-2. {Then: API/backend layer}
-3. {Then: UI/frontend layer}
-4. {Finally: integration + E2E tests}
+> The AI agent will analyze this epic and research the codebase to create small, focused stories. Each story must deliver a tangible, verifiable result — not just a layer of work.
+
+### Affected Areas (for codebase research)
+- [ ] {Area 1: e.g., "Authentication flow in `src/auth/`"}
+- [ ] {Area 2: e.g., "User profile API in `src/api/users.ts`"}
+- [ ] {Area 3: e.g., "Dashboard component in `src/components/Dashboard/`"}
+
+### Key Constraints for Story Sizing
+- Each story should touch 1-3 files and have one clear goal
+- Prefer vertical slices (thin end-to-end) over horizontal layers
+- Stories must be independently verifiable
+
+### Suggested Sequencing Hints
+1. {What must exist first for other work to build on}
+2. {What depends on #1}
+3. {What can run in parallel}
 
 ---
 

package/templates/spike.md

@@ -0,0 +1,143 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-8.
+
+1. **YAML Frontmatter**: Spike ID, Parent Epic, Parent Story (optional), Status, Ambiguity Before, Time Box, Owner, Tags, Created
+2. **§1 Question**: The specific unknown to resolve
+3. **§2 Constraints**: Time box, scope limits, what is NOT being investigated
+4. **§3 Approach**: Investigation method
+5. **§4 Findings**: Evidence, data, observations discovered
+6. **§5 Decision**: Choice made + rationale + alternatives rejected
+7. **§6 Residual Risk**: What's still uncertain after the spike
+8. **§7 Affected Documents**: Checklist of upstream/downstream docs to update on close
+9. **§8 Change Log**: Modification history
+
+Spike Statuses: Open → Investigating → Findings Ready → Validated → Closed
+
+Output location: `product_plans/backlog/EPIC-{NNN}_{name}/SPIKE-{EpicID}-{NNN}-{topic}.md`
+
+Document Hierarchy Position: LEVEL 3.5 (Charter → Roadmap → Epic → **Spike** / Story)
+Spikes are children of Epics, siblings of Stories. They travel with their Epic folder (archiving is automatic).
+
+Upstream sources:
+- §1 Question derives from parent Epic §8 Open Questions (blocking items)
+- §3 Approach references parent Epic §4 Technical Context
+- Roadmap §3 ADRs informs existing architectural decisions
+
+Downstream consumers:
+- §4 Findings → parent Epic §4 Technical Context (update with new knowledge)
+- §5 Decision → Roadmap §3 ADRs (if architectural decision)
+- §6 Residual Risk → Risk Registry §1 Active Risks (if new risk identified)
+- §5 Decision → parent Story §3 Implementation Guide (if story-level spike)
+
+Agent handoff:
+- Team Lead creates the spike from template, links to Epic §9
+- Developer investigates (fills §4 Findings and §5 Decision)
+- Architect validates findings against Safe Zone (Findings Ready → Validated)
+- Team Lead propagates findings to affected documents (Validated → Closed)
+
+Do NOT output these instructions.
+</instructions>
+
+---
+spike_id: "SPIKE-{EpicID}-{NNN}-{topic}"
+parent_epic_ref: "EPIC-{ID}"
+parent_story_ref: "(optional — omit for epic-level spikes)"
+status: "Open / Investigating / Findings Ready / Validated / Closed"
+ambiguity_before: "🔴 High / 🟡 Medium"
+time_box: "e.g., 4 hours / 1 day"
+owner: "Developer / Architect"
+tags: []
+created: "YYYY-MM-DD"
+---
+
+# SPIKE-{EpicID}-{NNN}: {Topic}
+
+## 1. Question
+> The specific unknown to resolve. Derived from Epic §8 Open Questions.
+
+{What exactly do we need to find out? Frame as a single, concrete question.}
+
+---
+
+## 2. Constraints
+> What boundaries apply to this investigation.
+
+| Constraint | Value |
+|------------|-------|
+| **Time Box** | {e.g., 4 hours / 1 day} |
+| **Scope Limit** | {What IS being investigated} |
+| **Out of Scope** | {What is NOT being investigated — prevents scope creep} |
+
+---
+
+## 3. Approach
+> How the investigation will be conducted.
+
+**Method:** {Code exploration / Prototyping / Benchmarks / Doc research / Proof of concept}
+
+### Steps
+1. {First investigation step}
+2. {Second investigation step}
+3. {Third investigation step}
+
+---
+
+## 4. Findings
+> Evidence, data, and observations discovered during investigation.
+> Filled by the Developer during the Investigating phase.
+
+### Evidence
+- {Observation 1 — with data or code references}
+- {Observation 2}
+
+### Data
+| Metric | Value | Notes |
+|--------|-------|-------|
+| {e.g., Response time} | {value} | {context} |
+
+---
+
+## 5. Decision
+> Choice made based on findings. Becomes an ADR if architectural.
+
+### Chosen Approach
+{What we decided to do and why.}
+
+### Alternatives Rejected
+| Alternative | Why Rejected |
+|-------------|--------------|
+| {Option A} | {Reason} |
+| {Option B} | {Reason} |
+
+### ADR Required?
+- [ ] Yes — create ADR in Roadmap §3 (decision affects architecture)
+- [ ] No — decision is implementation-level only
+
+---
+
+## 6. Residual Risk
+> What's still uncertain after the spike. Feeds Risk Registry if non-trivial.
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|------------|--------|------------|
+| {Remaining unknown} | {Low/Medium/High} | {description} | {how to manage} |
+
+---
+
+## 7. Affected Documents
+> Checklist of upstream/downstream docs to update when closing this spike.
+> ALL items must be checked before spike status can move to Closed.
+
+- [ ] Epic §4 Technical Context — update with findings
+- [ ] Epic §8 Open Questions — mark resolved
+- [ ] Epic §9 Artifact Links — add spike reference
+- [ ] Roadmap §3 ADRs — if architectural decision (see §5)
+- [ ] Risk Registry §1 — if new risk identified (see §6)
+- [ ] Story §3 Implementation Guide — if story-level spike
+
+---
+
+## 8. Change Log
+| Date | Author | Change |
+|------|--------|--------|
+| {YYYY-MM-DD} | {name} | Created spike |

package/templates/sprint.md

@@ -1,11 +1,12 @@
 <instructions>
-FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 0-4.
 
-1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status, Delivery ref
-2. **§1 Active Scope**: Table of stories + Context Pack Readiness checklists
-3. **§2 Execution Strategy**: Parallel phases, dependencies, risk flags
-4. **§3 Sprint Open Questions**: Unresolved items blocking this sprint
-5. **§4 Execution Log**: Accumulated story results (populated during sprint, becomes Sprint Report §2 source)
+1. **YAML Frontmatter**: Sprint ID, Goal, Dates, Status (Planning/Confirmed/Active/Completed), Delivery ref, Confirmed by/at
+2. **§0 Sprint Readiness Gate**: Pre-sprint checklist — ALL items must be checked before human confirms
+3. **§1 Active Scope**: Table of stories + Context Pack Readiness checklists
+4. **§2 Execution Strategy**: Parallel phases, dependencies, risk flags
+5. **§3 Sprint Open Questions**: Unresolved items blocking this sprint
+6. **§4 Execution Log**: Accumulated story results (populated during sprint, becomes Sprint Report §2 source)
 
 Output location: `product_plans/sprints/sprint-{XX}/sprint-{XX}.md`
 
@@ -15,8 +16,11 @@ Role of this document:
 - The Delivery Plan is only updated at sprint boundaries (start and end).
 
 Document Lifecycle:
-- Created by the Team Lead at Sprint Setup (Step 0) via `vbounce sprint init`.
-- §1 V-Bounce States updated at every story transition.
+- Created during Sprint Planning (Phase 2) as a collaborative document between AI and human.
+- Status flow: Planning → Confirmed (human approves) → Active (execution begins) → Completed.
+- **Sprint CANNOT move to Active without human confirmation.** This is a hard gate.
+- §0 Readiness Gate must be fully checked before requesting human confirmation.
+- §1 V-Bounce States updated at every story transition during execution.
 - §4 Execution Log gets one row per completed story (via `vbounce story complete`).
 - At sprint end, §4 becomes the skeleton for Sprint Report §2 — no reconstruction needed.
 - When the sprint completes, this document moves to `product_plans/archive/sprints/sprint-{XX}/`.
@@ -28,12 +32,28 @@ Do NOT output these instructions.
 sprint_id: "sprint-{XX}"
 sprint_goal: "{One-sentence North Star}"
 dates: "{MM/DD - MM/DD}"
-status: "Planning / Active / Completed"
+status: "Planning / Confirmed / Active / Completed"
 delivery: "D-{NN}"
+confirmed_by: ""
+confirmed_at: ""
 ---
 
 # Sprint S-{XX} Plan
 
+## 0. Sprint Readiness Gate
+> This sprint CANNOT start until the human confirms this plan.
+> AI sets status to "Planning" when drafting. Human confirmation moves it to "Confirmed". Execution moves it to "Active".
+
+### Pre-Sprint Checklist
+- [ ] All stories below have been reviewed with the human
+- [ ] Open questions (§3) are resolved or non-blocking
+- [ ] No stories have 🔴 High ambiguity (spike first)
+- [ ] Dependencies identified and sequencing agreed
+- [ ] Risk flags reviewed from Risk Registry
+- [ ] **Human has confirmed this sprint plan**
+
+---
+
 ## 1. Active Scope
 > Stories pulled from the backlog for execution during this sprint window.
 > V-Bounce State is the ONLY authoritative source for story status during the sprint.
@@ -66,16 +86,30 @@ V-Bounce State: Draft / Refinement / Ready to Bounce
 - **Phase 1 (parallel)**: {Story IDs that can run simultaneously}
 - **Phase 2 (sequential)**: {Story IDs with dependencies — run in order}
 
-### Risk Flags
-- {Which stories touch shared modules — coordinate access}
-- {Sprint-specific risks pulled from Risk Registry}
+### Execution Mode
+> L1 → Fast Track (Dev → DevOps, skip QA/Arch). L2 → Fast Track only with human approval below. L3/L4 → Full Bounce always.
+
+| Story | Label | Mode | Human Approved? |
+|-------|-------|------|-----------------|
+| STORY-XXX-YY | L2 | Full Bounce / Fast Track | — / Yes |
+
+### Shared File Map
+> Stories touching the same files MUST merge sequentially (first-in wins). Flag these during planning.
+
+| File / Module | Stories Touching It | Merge Order |
+|---------------|--------------------:|-------------|
+| `{src/path/file.ts}` | STORY-A, STORY-B | A before B |
 
 ### Dependency Chain
-> Stories that MUST run sequentially (depends_on relationships).
+> Stories that MUST run sequentially (depends_on OR shared files).
 
 | Story | Depends On | Reason |
 |-------|-----------|--------|
-| STORY-XXX-YY | STORY-XXX-YY | {why sequential} |
+| STORY-XXX-YY | STORY-XXX-YY | {depends_on / shared file / data dependency} |
+
+### Risk Flags
+- {Sprint-specific risks pulled from Risk Registry}
+- {External dependency risks}
 
 ---
 
@@ -94,7 +128,7 @@ V-Bounce State: Draft / Refinement / Ready to Bounce
 > Updated by the Lead after each story completes via `vbounce story complete STORY-ID`.
 > This table becomes Sprint Report §2 at sprint end — no reconstruction needed.
 
-| Story | Final State | QA Bounces | Arch Bounces | Correction Tax | Notes |
-|-------|-------------|------------|--------------|----------------|-------|
-| STORY-XXX-YY | Done | 0 | 0 | 0% | {brief note} |
+| Story | Final State | QA Bounces | Arch Bounces | Tests Written | Correction Tax | Notes |
+|-------|-------------|------------|--------------|---------------|----------------|-------|
+| STORY-XXX-YY | Done | 0 | 0 | {N} | 0% | {brief note} |
 <!-- EXECUTION_LOG_END -->

package/templates/sprint_report.md

@@ -110,6 +110,8 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 | **Bounce Ratio** | {X}% | (total bounces / total stories) |
 | **Average Correction Tax** | {X}% | 🟢 0-5% · 🟡 6-15% · 🔴 16%+ requires process review |
 | **First-Pass Success Rate** | {X}% | stories that passed QA on first try |
+| **Total Tests Written** | {N} | across all stories (from Dev report `tests_written`) |
+| **Tests per Story (avg)** | {N} | |
 | **Merge Conflicts** | {N} simple, {N} complex | |
 
 ### Per-Story Breakdown
@@ -128,11 +130,11 @@ delivery_plan_ref: "product_plans/{delivery}/DELIVERY_PLAN.md"
 
 ## 4. Lessons Learned
 
-> Flagged by agents during the sprint. Each needs user approval before recording to LESSONS.md.
+> Lessons are recorded to LESSONS.md **immediately after each story merge** (Step 5.5), not deferred to sprint close. This table is a review of what was already captured.
 
-| Source | Lesson | Approved? |
-|--------|--------|-----------|
-| STORY-{ID}-{story_name} Dev Report | {What happened and proposed rule} | Pending / Yes / No |
+| Source | Lesson | Recorded? | When |
+|--------|--------|-----------|------|
+| STORY-{ID}-{story_name} Dev Report | {What happened and proposed rule} | Yes / No / Missed | {After story merge / Sprint close} |
 
 ---
 

package/templates/story.md

@@ -30,8 +30,8 @@ Downstream consumers:
 - Developer Agent reads §1 The Spec and §3 Implementation Guide (with react-best-practices skill)
 - QA Agent reads §2 The Truth to validate implementation (with vibe-code-review skill)
 - Architect Agent reads full story context for Safe Zone compliance audit
-- Delivery Plan §3 Active Sprint tracks story V-Bounce state
-- Delivery Plan §5 Context Pack Status tracks per-story readiness using this template's sections
+- Sprint Plan §1 Active Scope tracks story V-Bounce state during the sprint
+- Sprint Plan §1 Context Pack Readiness tracks per-story readiness using this template's sections
 
 Agent handoff sections:
 - §1 The Spec → Human contract (PM/BA writes, Dev reads)
@@ -111,10 +111,23 @@ Feature: {Story Name}
 > Instructions for the Developer Agent. The "How".
 > Target Audience: Developer Agent (with react-best-practices + lesson skills).
 
-### 3.0 Test Implementation
-- {Identify which test suites need to be created or modified to cover the Acceptance Criteria from §2.1. e.g. "Create `AuthComponent.test.tsx`"}
+### 3.0 Environment Prerequisites
+> Verify these before starting. Do NOT waste a bounce cycle on setup failures.
 
-### 3.1 Context & Files
+| Prerequisite | Value | Verified? |
+|-------------|-------|-----------|
+| **Env Vars** | {e.g., `DATABASE_URL`, `API_KEY`} | [ ] |
+| **Services Running** | {e.g., "PostgreSQL on localhost:5432"} | [ ] |
+| **Migrations** | {e.g., "Run `npx prisma migrate dev`"} | [ ] |
+| **Seed Data** | {e.g., "Run `npm run seed`" or "None"} | [ ] |
+| **Dependencies** | {e.g., "`npm install` after pulling latest"} | [ ] |
+
+### 3.1 Test Implementation
+- {Identify which test suites need to be created or modified to cover the Acceptance Criteria from §2.1}
+- {Include E2E/acceptance tests — not just unit tests. Every Gherkin scenario in §2.1 must have a corresponding test}
+- {e.g., "Create `AuthComponent.test.tsx` (unit) + `auth.e2e.test.ts` (acceptance)"}
+
+### 3.2 Context & Files
 | Item | Value |
 |------|-------|
 | **Primary File** | `{filepath/to/main/component.ts}` |
@@ -122,11 +135,11 @@ Feature: {Story Name}
 | **New Files Needed** | Yes/No — `{Name of file}` |
 | **ADR References** | ADR-{NNN} from Roadmap §3 |
 
-### 3.2 Technical Logic
+### 3.3 Technical Logic
 - {Describe the logic flow, e.g., "Use the existing useAuth hook to check permissions."}
 - {Describe state management, e.g., "Store the result in the global Zustand store."}
 
-### 3.3 API Contract (If applicable)
+### 3.4 API Contract (If applicable)
 ```json
 // Expected Request
 POST /api/resource
@@ -146,8 +159,10 @@ POST /api/resource
 ---
 
 ## 4. Definition of Done (The Gate)
+- [ ] Environment prerequisites (§3.0) verified before starting.
 - [ ] Code compiles without errors.
-- [ ] Unit/Integration Tests were written FIRST (Red), and now pass (Green).
+- [ ] Unit tests were written FIRST (Red), and now pass (Green).
+- [ ] E2E/acceptance tests cover all Gherkin scenarios from §2.1 and pass.
 - [ ] All Acceptance Criteria (§2.1) pass.
 - [ ] Linting rules passed.
 - [ ] LESSONS.md consulted before implementation.