@sandrinio/vbounce 1.3.1 → 1.4.0

package/brains/claude-agents/developer.md

@@ -21,6 +21,11 @@ Implement features and fix bugs as specified in Story documents. You write code
 
 ## During Implementation
 
+**You MUST follow the Test-Driven Development (TDD) Red-Green-Refactor cycle:**
+1. **Red (Write Failing Tests):** Before writing any implementation logic, write an automated test file (e.g., Jest, React Testing Library) that explicitly covers the Gherkin scenarios defined in `§2 The Truth`. Run it to prove it fails.
+2. **Green (Write Implementation):** Write the minimum code required to make your tests pass.
+3. **Refactor:** Clean up the code for readability and architecture without breaking the tests.
+
 - **Follow the Safe Zone.** Do not introduce new patterns, libraries, or architectural changes.
 - **No Gold-Plating.** Implement exactly what the Story specifies. Extra features are defects, not bonuses.
 - **Track your Correction Tax.** Note every point where you needed human intervention or made a wrong turn.
@@ -41,6 +46,7 @@ You MUST include the YAML frontmatter block exactly as shown below:
 ---
 status: "implemented"
 correction_tax: {X}
+tests_written: {number of tests generated}
 files_modified:
   - "path/to/file.ts"
 lessons_flagged: {number of lessons}
@@ -66,6 +72,7 @@ lessons_flagged: {number of lessons}
 
 ## Status
 - [ ] Code compiles without errors
+- [ ] Automated tests were written FIRST (Red) and now pass (Green)
 - [ ] LESSONS.md was read before implementation
 - [ ] ADRs from Roadmap §3 were followed
 - [ ] No new patterns or libraries introduced

package/brains/claude-agents/qa.md

@@ -36,10 +36,12 @@ Analyze the specific changes from the Developer:
   5. **Test Quality** — would tests break if logic changed?
   6. **Coupling** — can you change one thing without breaking five?
 
-### Acceptance Criteria Validation
-Run Story §2.1 Gherkin scenarios against the implementation:
-- Each scenario is a binary pass/fail
-- Document exact failure conditions (input, expected, actual)
+### Test Execution & Fidelity
+Run Story §2.1 Gherkin scenarios against the Developer's automated test suite:
+- **Did the Developer actually write tests?** If `tests_written: 0` in their report, the bounce FAILS automatically. TDD is mandatory.
+- **Do the tests pass?** If the Developer's test suite fails when executed (or if there are compilation errors), the bounce FAILS.
+- Each scenario is a binary pass/fail based on test coverage.
+- Document exact failure conditions (input, expected, actual).
 
 ### Spec Fidelity Check
 After running scenarios, verify:

package/brains/claude-agents/scribe.md

@@ -98,8 +98,16 @@ The manifest is a semantic routing table — it helps agents quickly find releva
 ## Your Output
 
 Write a **Scribe Report** to `.bounce/reports/sprint-S-{XX}-scribe.md`:
+You MUST include the YAML frontmatter block exactly as shown below:
 
 ```markdown
+---
+mode: "{init / audit / create}"
+docs_created: {count}
+docs_updated: {count}
+docs_removed: {count}
+---
+
 # Scribe Report: Sprint S-{XX}
 
 ## Mode

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandrinio/vbounce",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "V-Bounce OS: Turn your AI coding assistant into a full engineering team through structured SDLC skills.",
   "type": "module",
   "bin": {

package/scripts/validate_report.mjs

@@ -14,7 +14,7 @@ import yaml from 'js-yaml';
 
 // Defined schemas for each report type
 const SCHEMAS = {
-    dev: ['status', 'correction_tax', 'files_modified', 'lessons_flagged'],
+    dev: ['status', 'correction_tax', 'tests_written', 'files_modified', 'lessons_flagged'],
     qa: {
         base: ['status', 'bounce_count', 'bugs_found', 'gold_plating_detected'],
         conditional: { 'FAIL': ['failed_scenarios'] }
@@ -26,7 +26,8 @@ const SCHEMAS = {
     devops: {
         base: ['type', 'status'],
         conditional: { 'story-merge': ['conflicts_detected'], 'sprint-release': ['version'] }
-    }
+    },
+    scribe: ['mode', 'docs_created', 'docs_updated', 'docs_removed']
 };
 
 function extractFrontmatter(content) {
@@ -89,6 +90,7 @@ function main() {
     else if (filename.endsWith('-qa.md')) agentType = 'qa';
     else if (filename.endsWith('-arch.md')) agentType = 'arch';
     else if (filename.endsWith('-devops.md')) agentType = 'devops';
+    else if (filename.endsWith('-scribe.md')) agentType = 'scribe';
 
     if (agentType === 'unknown') {
         console.error(`WARNING: Unrecognized report type for ${filename}. Ensure filename ends in -dev.md, -qa.md, -arch.md, or -devops.md.`);
@@ -108,6 +110,10 @@ function main() {
         if (agentType === 'qa') validateQA(data);
         if (agentType === 'arch') validateArch(data);
         if (agentType === 'devops') validateDevops(data);
+        if (agentType === 'scribe') {
+            const missing = SCHEMAS.scribe.filter(k => !(k in data));
+            if (missing.length > 0) throw new Error(`SCRIBE_SCHEMA_ERROR: Missing required keys: ${missing.join(', ')}`);
+        }
 
         console.log(`VALID: ${filename} matches the ${agentType.toUpperCase()} schema.`);
         process.exit(0);

package/scripts/verify_framework.mjs

@@ -41,6 +41,12 @@ const EXPECTED_PROMPT_SIGNATURES = {
         'conflicts_detected:',
         'type: "sprint-release"',
         'version:'
+    ],
+    'scribe.md': [
+        'mode:',
+        'docs_created:',
+        'docs_updated:',
+        'docs_removed:'
     ]
 };
 

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]`)
@@ -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,7 +1,7 @@
 <instructions>
 FOLLOW THIS EXACT STRUCTURE. Output sections in order 1-7.
 
-1. **Header**: Set Status, link to Roadmap + Risk Registry, Sprint Cadence
+1. **YAML Frontmatter**: Set status, last updated, roadmap ref, risk registry ref, delivery ref, and 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
@@ -59,19 +59,17 @@ Downstream consumers:
 Do NOT output these instructions.
 </instructions>
 
-# Delivery Plan: {Project Name}
-
 ---
-
-> **Last Updated**: {YYYY-MM-DD}
-> **Status**: Planning / In Sprint / Delivered
-> **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
-
+last_updated: "{YYYY-MM-DD}"
+status: "Planning / In Sprint / Delivered"
+roadmap_ref: "product_plans/{project}_roadmap.md"
+risk_registry_ref: "product_plans/RISK_REGISTRY.md"
+delivery_ref: "D-{NN}_{release_name}"
+sprint_cadence: "1-week sprints within 2-week project window"
 ---
 
+# Delivery Plan: {Project Name}
+
 ## 1. Project Window
 
 | Key | Value |

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
@@ -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

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
@@ -31,16 +31,14 @@ 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 |

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)
@@ -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 |

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,17 @@ 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"
+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)

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
@@ -38,19 +38,18 @@ Agent handoff sections:
 Do NOT output these instructions.
 </instructions>
 
-# STORY-{EpicID}-{StoryID}: {Story Name}
-
-## Metadata
+---
+story_id: "STORY-{EpicID}-{StoryID}"
+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)"
+---
 
-| 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)
 
@@ -109,6 +108,9 @@ 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.1 Context & Files
 | Item | Value |
 |------|-------|
@@ -142,7 +144,7 @@ POST /api/resource
 
 ## 4. Definition of Done (The Gate)
 - [ ] Code compiles without errors.
-- [ ] New Unit Tests are written and passing.
+- [ ] Unit/Integration Tests were written FIRST (Red), and now pass (Green).
 - [ ] All Acceptance Criteria (§2.1) pass.
 - [ ] Linting rules passed.
 - [ ] LESSONS.md consulted before implementation.