vbounce-engine 2.5.1

package/templates/sprint.md

@@ -0,0 +1,134 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 0-4.
+
+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`
+
+Role of this document:
+- This is the SINGLE SOURCE OF TRUTH during active sprint execution.
+- The Team Lead updates this file at every state transition — NOT the Delivery Plan.
+- The Delivery Plan is only updated at sprint boundaries (start and end).
+
+Document Lifecycle:
+- 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}/`.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+sprint_id: "sprint-{XX}"
+sprint_goal: "{One-sentence North Star}"
+dates: "{MM/DD - MM/DD}"
+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.
+
+| Priority | Story | Epic | Label | V-Bounce State | Blocker |
+|----------|-------|------|-------|----------------|---------|
+| 1 | [STORY-XXX-YY: name](./STORY-XXX-YY-name.md) | EPIC-XXX | L2 | Draft | — |
+
+### Context Pack Readiness
+> Check before moving story to "Ready to Bounce". All items must be ✅.
+> Run `vbounce validate ready STORY-ID` to verify programmatically.
+
+**STORY-{ID}: {name}**
+- [ ] Story spec complete (§1)
+- [ ] Acceptance criteria defined (§2)
+- [ ] Implementation guide written (§3)
+- [ ] Ambiguity: Low / Medium (if High → back to Refinement)
+
+V-Bounce State: Draft / Refinement / Ready to Bounce
+
+### Escalated / Parking Lot
+- STORY-XXX-YY: {name} — Reason: {escalated / deferred}
+
+---
+
+## 2. Execution Strategy
+> Written during sprint planning. Guides the Lead's delegation order.
+
+### Phase Plan
+- **Phase 1 (parallel)**: {Story IDs that can run simultaneously}
+- **Phase 2 (sequential)**: {Story IDs with dependencies — run in order}
+
+### 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 OR shared files).
+
+| Story | Depends On | Reason |
+|-------|-----------|--------|
+| STORY-XXX-YY | STORY-XXX-YY | {depends_on / shared file / data dependency} |
+
+### Risk Flags
+- {Sprint-specific risks pulled from Risk Registry}
+- {External dependency risks}
+
+---
+
+## 3. Sprint Open Questions
+> Unresolved items that affect this specific sprint execution window.
+> Strategic questions belong in the Delivery Plan, not here.
+
+| Question | Options | Impact | Owner | Status |
+|----------|---------|--------|-------|--------|
+| {question} | A: {x}, B: {y} | Blocks {stories} | {name} | Open / Decided |
+
+---
+
+<!-- EXECUTION_LOG_START -->
+## 4. Execution Log
+> 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 | Tests Written | Correction Tax | Notes |
+|-------|-------------|------------|--------------|---------------|----------------|-------|
+| STORY-XXX-YY | Done | 0 | 0 | {N} | 0% | {brief note} |
+<!-- EXECUTION_LOG_END -->

package/templates/sprint_context.md

@@ -0,0 +1,61 @@
+<instructions>
+This template is used by the Team Lead at Sprint Setup (Step 0.7) to create a shared context file
+for all agents in the sprint. Every agent task file must reference this file.
+
+Purpose: Reduce divergence between parallel agents by giving them a single source of cross-cutting rules.
+
+Written to `.vbounce/sprint-context-S-{XX}.md`.
+Updated mid-sprint when cross-cutting decisions change.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+sprint_id: "S-{XX}"
+created: "{YYYY-MM-DD}"
+last_updated: "{YYYY-MM-DD}"
+---
+
+# Sprint Context: S-{XX}
+
+> Cross-cutting rules for ALL agents in this sprint. Read this before starting any work.
+
+## Design Tokens & UI Conventions
+> Visual rules that apply across all UI stories. Omit if sprint has no UI work.
+
+- **Color palette**: {e.g., "Primary: #1A1A2E, Accent: #E94560, Background: #F5F5F5"}
+- **Typography**: {e.g., "Headings: Inter 600, Body: Inter 400, Mono: JetBrains Mono"}
+- **Spacing rhythm**: {e.g., "4px base unit, 8/16/24/32px scale"}
+- **Component patterns**: {e.g., "Use existing Button component from src/components/ui/Button.tsx"}
+
+## Shared Patterns & Conventions
+> Technical patterns all agents must follow. Derived from ADRs, LESSONS.md, and sprint planning.
+
+- {e.g., "All API calls go through src/lib/api-client.ts — do not use fetch directly"}
+- {e.g., "Error boundaries must wrap every route-level component"}
+- {e.g., "Use Zod for all input validation — do not write manual validators"}
+
+## Locked Dependencies
+> Versions that must not be changed during this sprint.
+
+| Package | Version | Reason |
+|---------|---------|--------|
+| {e.g., "react"} | {e.g., "18.2.0"} | {e.g., "Upgrade planned for S-04"} |
+
+## Active Lessons (Broad Impact)
+> LESSONS.md entries that affect multiple stories in this sprint. Copied here for visibility.
+
+- {e.g., "[2026-03-10] Always use soft deletes with RLS — never cascade"}
+- {e.g., "[2026-03-15] Run `npm run typecheck` before committing — tsc catches what ESLint misses"}
+
+## Sprint-Specific Rules
+> Decisions made during sprint planning or mid-sprint that all agents must follow.
+
+- {e.g., "All new components must include a Storybook story"}
+- {e.g., "No new dependencies without Team Lead approval — we're near the bundle size limit"}
+
+## Change Log
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Sprint context created | Team Lead |

package/templates/sprint_report.md

@@ -0,0 +1,215 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-6.
+
+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. §2.1 Change Requests logs any mid-sprint user interventions (bugs, spec clarifications, scope/approach changes)
+4. **§3 Execution Metrics**: AI performance metrics — tokens, duration, bounces, correction tax
+5. **§4 Lessons Learned**: Flagged from agent reports, pending user approval to record
+6. **§5 Retrospective**: What went well, what didn't, and what to change — covers both project and delivery process
+
+This template is used by the Team Lead at Sprint Consolidation (Step 7).
+Written to `.vbounce/sprint-report.md`, then archived to `.vbounce/archive/S-{XX}/`.
+
+When the delivery completes, sprint reports are summarized into the Roadmap §7 Delivery Log
+as Release Notes.
+
+The §1 section is critical — the user wants to know what they can see, touch, and use NOW
+versus what was built under the hood. Write it from the user's perspective, not the developer's.
+
+Do NOT output these instructions.
+</instructions>
+
+---
+sprint_id: "S-{XX}"
+sprint_goal: "{One-sentence North Star}"
+dates: "{MM/DD - MM/DD}"
+status: "Achieved / Partially Achieved / Failed"
+total_input_tokens: {N}
+total_output_tokens: {N}
+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)
+> Features, screens, or workflows the user can see, interact with, or test right now.
+
+- {e.g., "Login page with email/password authentication — accessible at /login"}
+- {e.g., "Dashboard with project overview cards — accessible at /dashboard"}
+- {e.g., "Settings page with profile editing — accessible at /settings"}
+
+### Internal / Backend (Not Directly Visible)
+> Infrastructure, APIs, database changes, or plumbing that supports future features.
+
+- {e.g., "User roles and permissions system — API endpoints ready, no UI yet"}
+- {e.g., "Database migration for notifications table — schema deployed"}
+- {e.g., "Rate limiting middleware on all API routes"}
+
+### 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)"}
+
+### Product Docs Affected
+> Auto-populated from staleness detection (`vbounce docs check S-{XX}`). Shows which vdocs were impacted by this sprint's code changes. Scribe agent receives a targeted task from `.vbounce/scribe-task-S-{XX}.md`.
+
+| Doc | Stale Key Files | Touched By | Priority | Scribe Action |
+|-----|----------------|------------|----------|---------------|
+| {e.g., `AUTHENTICATION_DOC.md`} | {e.g., `src/auth/index.ts`} | {e.g., `STORY-001-02`} | {HIGH/MEDIUM/LOW} | {Update / Quality Fix / New} |
+
+> If no `vdocs/_manifest.json` exists, write "N/A — vdoc not installed".
+
+---
+
+## 2. Story Results
+
+| Story | Epic | Label | Final State | Bounces (QA) | Bounces (Arch) | Correction Tax | Tax Type |
+|-------|------|-------|-------------|--------------|----------------|----------------|----------|
+| STORY-{ID}-{story_name} | EPIC-{ID} | L{N} | Done / Escalated / Parking Lot | {N} | {N} | {X}% | Bug Fix / Enhancement / Mixed |
+
+### Story Highlights
+- **STORY-{ID}-{story_name}**: {1-sentence summary of what was built and notable decisions}
+
+### Escalated Stories (if any)
+- **STORY-{ID}-{story_name}**: Escalated after {N} bounces. Root cause: {why}. Recommendation: {rewrite spec / descope / kill}.
+
+### 2.1 Change Requests
+> Mid-sprint user interventions — bugs found, spec clarifications, scope or approach changes. Tracked separately from agent-driven bounces so metrics aren't skewed. Omit this section if no CRs occurred.
+
+| Story | Category | Description | Impact |
+|-------|----------|-------------|--------|
+| STORY-{ID} | Bug / Spec Clarification / Scope Change / Approach Change | {One-line description} | {e.g., No bounce reset / Dev pass reset / +1 session} |
+
+---
+
+## 3. Execution Metrics
+
+> Run `vbounce tokens --sprint S-{XX} --json` to get per-story and sprint-total token data from story documents. Use the output to populate the tables below.
+
+### AI Performance
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| **Total Tokens Used** | {N} | input + output across all agents |
+| **Output Tokens** | {N} | tokens generated by agents |
+| **Input Tokens** | {N} | context fed to agents |
+| **Total Execution Duration** | {X}h {Y}m | wall-clock time from sprint start to completion |
+| **Agent Sessions** | {N} | total subagent spawns (Dev + QA + Arch + DevOps + Scribe) |
+| **Estimated Cost** | ${X.XX} | based on model pricing at time of execution |
+
+### V-Bounce Quality
+
+| Metric | Value | Notes |
+|--------|-------|-------|
+| **Stories Planned** | {X} | |
+| **Stories Delivered** | {Y} | |
+| **Stories Escalated** | {Z} | |
+| **Total QA Bounces** | {N} | across all stories |
+| **Total Architect Bounces** | {N} | across all stories |
+| **Bounce Ratio** | {X}% | (total bounces / total stories) |
+| **Average Correction Tax** | {X}% | 🟢 0-5% · 🟡 6-15% · 🔴 16%+ requires process review |
+| **— Bug Fix Tax** | {X}% | Quality failures — bugs that should have been caught by agents |
+| **— Enhancement Tax** | {X}% | Healthy iteration — user feedback, UX tweaks, spec refinements |
+| **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
+
+| Story | Tokens | Duration | Agent Sessions | Bounces | Cost |
+|-------|--------|----------|----------------|---------|------|
+| 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."
+> **Only Bug Fix Tax triggers threshold alerts.** Enhancement Tax (user-driven iteration) is healthy and expected.
+
+- {e.g., "STORY-001-05-test_arch: Bug Fix 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"}
+
+---
+
+## 4. Lessons Learned
+
+> 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 | Recorded? | When |
+|--------|--------|-----------|------|
+| STORY-{ID}-{story_name} Dev Report | {What happened and proposed rule} | Yes / No / Missed | {After story merge / Sprint close} |
+
+---
+
+## 5. Retrospective
+
+### What Went Well
+> Practices, patterns, or decisions that worked and should be repeated.
+
+- {e.g., "Splitting EPIC-001 into small L2 stories kept bounces low — 80% first-pass success"}
+- {e.g., "Reading _manifest.json upfront saved Dev from duplicating existing API docs"}
+
+### What Didn't Go Well
+> Problems encountered, root causes, and impact on the sprint.
+
+- {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} |
+
+#### Tooling & Scripts
+> Script failures, validation gaps, or automation opportunities.
+
+| 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} |
+
+---
+
+## 6. Change Log
+
+| Date | Change | By |
+|------|--------|-----|
+| {YYYY-MM-DD} | Sprint Report generated | Team Lead |

package/templates/story.md

@@ -0,0 +1,193 @@
+<instructions>
+FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-4.
+
+1. **YAML Frontmatter**: Story ID, Parent Epic, Status, Ambiguity, Context Source, Actor, Complexity Label
+2. **§1 The Spec**: Problem Statement or User Story + Detailed Requirements + Out of Scope
+3. **§2 The Truth**: Gherkin acceptance criteria + verification steps
+4. **§3 Implementation Guide**: Files to modify, technical logic, API contract
+5. **§4 Quality Gates**: Minimum test expectations + Definition of Done checklist
+6. **Token Usage**: Table auto-populated by agents — each agent appends their row via `count_tokens.mjs --self --append`
+
+Ambiguity Score:
+- 🔴 High: Requirements unclear
+- 🟡 Medium: Logic clear, files TBD
+- 🟢 Low: Ready for coding
+
+Complexity Labels:
+- **L1**: Trivial — Single file, <1hr vibe time, known pattern
+- **L2**: Standard — 2-3 files, known pattern, ~2-4hr vibe time *(default)*
+- **L3**: Complex — Cross-cutting, spike may be needed, ~1-2 days
+- **L4**: Uncertain — Requires Probing/Spiking before Bounce, >2 days
+
+Output the complexity as a single line: **Complexity: L{N}** — {brief description from above}. Do NOT output the full legend.
+
+§1.1 Format:
+- For user-facing stories, use: "As a {Persona}, I want to {Action}, So that {Benefit}."
+- For infrastructure/framework stories, a direct problem statement is acceptable: "This story {does X} because {reason}."
+
+§3.4 API Contract: Document EXISTING API contracts the implementation must comply with (current request/response shapes, auth requirements, rate limits). If this story creates a NEW API, describe the required contract. Remove this section entirely if no API changes.
+
+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**)
+
+Upstream sources:
+- §1 The Spec inherits from parent Epic §2 Scope Boundaries
+- §3 Implementation Guide references Epic §4 Technical Context and Roadmap §3 ADRs
+- Acceptance criteria (§2) refine Epic §7 Acceptance Criteria into per-story scenarios
+- Complexity Label aligns with Delivery Plan story label definitions (L1-L4)
+
+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
+- 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)
+- §2 The Truth → QA contract (BA writes, QA Agent executes)
+- §3 Implementation Guide → AI-to-AI instructions (Architect writes, Dev Agent executes)
+
+Do NOT output these instructions.
+</instructions>
+
+---
+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_label: "L1 / L2 / L3 / L4 (default: L2)"
+---
+
+# STORY-{EpicID}-{StoryID}: {Story Name}
+
+**Complexity: {L1/L2/L3/L4}** — {brief description}
+
+---
+
+## 1. The Spec (The Contract)
+> Human-Readable Requirements. The "What".
+> Target Audience: PM, BA, Stakeholders, Developer Agent.
+
+### 1.1 User Story
+> As a **{Persona}**,
+> I want to **{Action}**,
+> So that **{Benefit}**.
+
+### 1.2 Detailed Requirements
+- **Requirement 1**: {Specific behavior}
+- **Requirement 2**: {Specific data or constraint}
+- **Requirement 3**: {Expected state or outcome}
+
+### 1.3 Out of Scope
+- {What this story explicitly does NOT do}
+- {Deferred to STORY-XXX or future work}
+
+---
+
+## 2. The Truth (Executable Tests)
+> The QA Agent uses this to verify the work. If these don't pass, the Bounce failed.
+> Target Audience: QA Agent (with vibe-code-review skill).
+
+### 2.1 Acceptance Criteria (Gherkin/Pseudocode)
+```gherkin
+Feature: {Story Name}
+
+  Scenario: {Happy Path}
+    Given {precondition}
+    When {user action}
+    Then {system response}
+    And {database state change}
+
+  Scenario: {Edge Case / Error}
+    Given {precondition}
+    When {invalid action}
+    Then {error message}
+```
+
+### 2.2 Verification Steps (Manual)
+- [ ] {Story-specific manual checks — adapt to story type}
+- [ ] {e.g., "Verify API returns 200 for valid input" or "Verify UI renders correctly on mobile"}
+
+---
+
+## 3. The Implementation Guide (AI-to-AI)
+> Instructions for the Developer Agent. The "How".
+> Target Audience: Developer Agent (with react-best-practices + lesson skills).
+
+### 3.0 Environment Prerequisites
+> Verify these before starting. Do NOT waste a bounce cycle on setup failures.
+
+| 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}` |
+| **Related Files** | `{filepath/to/api/service.ts}`, `{filepath/to/types.ts}` |
+| **New Files Needed** | Yes/No — `{Name of file}` |
+| **ADR References** | ADR-{NNN} from Roadmap §3 |
+
+### 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.4 API Contract (If applicable)
+> Document existing API contracts the implementation must comply with.
+> If this story creates a new API, describe the required contract.
+> Remove this section if no API changes.
+
+| Endpoint | Method | Auth | Request Shape | Response Shape |
+|----------|--------|------|---------------|----------------|
+| {`/api/resource`} | {GET/POST} | {Bearer/None} | {`{ id: string }`} | {`{ status: string }`} |
+
+---
+
+## 4. Quality Gates
+
+### 4.1 Minimum Test Expectations
+> Defined during sprint planning. Sets the minimum test bar for this story. QA validates against these.
+
+| Test Type | Minimum Count | Notes |
+|-----------|--------------|-------|
+| Unit tests | {N} | {e.g., "1 per exported function"} |
+| Component tests | {N} | {e.g., "render, interaction, edge case" — for UI stories} |
+| E2E / acceptance tests | {N} | {e.g., "1 per Gherkin scenario in §2.1"} |
+| Integration tests | {N} | {e.g., "1 per API endpoint" — for backend stories} |
+
+> Guidelines: L1 stories ≥2 tests. L2 stories ≥5 tests. L3/L4 stories: planner defines based on scope.
+> If "N/A" for a test type, write "0 — N/A (no {type} in scope)".
+
+### 4.2 Definition of Done (The Gate)
+- [ ] Tests written FIRST (Red → Green → Refactor). All Gherkin scenarios from §2.1 covered.
+- [ ] Minimum test expectations (§4.1) met.
+- [ ] LESSONS.md + Sprint Context consulted before implementation.
+- [ ] No violations of Roadmap ADRs.
+- [ ] Environment prerequisites (§3.0) verified before starting.
+- [ ] **Framework Integrity**: If `.claude/agents/`, `.vbounce/skills/`, `.vbounce/templates/`, or `.vbounce/scripts/` were modified, log to `.vbounce/CHANGELOG.md`.
+
+---
+
+## Token Usage
+> Auto-populated by agents. Each agent runs `node .vbounce/scripts/count_tokens.mjs --self --append <this-file> --name <Agent>` before writing their report.
+
+| Agent | Input | Output | Total |
+|-------|-------|--------|-------|