@sandrinio/vbounce 1.8.0 → 2.0.0

package/README.md

@@ -1,246 +1,526 @@
-# 🎯 V-Bounce OS
+# V-Bounce Engine
 
-**Turn your AI coding assistant into a full engineering team.**
+**A structured SDLC framework for AI coding agents.**
 
-*Stop letting your AI code in a vacuum. V-Bounce OS is a structured, agentic framework that enforces a strict Software Development Lifecycle (SDLC) on AI agents like Claude Code, Cursor, Copilot, Gemini, and Codex.*
+V-Bounce Engine turns AI assistants — Claude Code, Cursor, Gemini, Copilot, Codex — into disciplined engineering teams. Instead of letting agents code in a vacuum, it enforces a planning-first workflow with automated quality gates, structured handoffs, and a persistent learning loop.
 
-> *Inspired by the work of Cory Hymel*
+> Inspired by the work of Cory Hymel
 
 ---
 
-## 💡 The Hook: Why V-Bounce OS?
+## The Problem
 
-Multi-agent frameworks are everywhere. But simply putting three agents in a chatroom doesn't write scalable software. When left unchecked, AI coding teams still hallucinate requirements, introduce architectural drift, and break existing patterns because they are disconnected from the truth of what they actually built.
+AI coding agents are powerful — but without structure, they create expensive chaos:
 
-**The core differentiator of V-Bounce OS is the Context Loop: Requirements → Bounce Reports → Product Documentation.**
+- **No accountability.** The agent writes code, but nobody reviews it against requirements before it ships. Bugs that a junior engineer would catch survive to production.
+- **Invisible progress.** You ask "how's the feature going?" and the only answer is "the agent is still running." No milestones, no intermediate artifacts, no way to course-correct mid-sprint.
+- **No institutional memory.** Every session starts from zero. The agent makes the same architectural mistake it made last week because nothing captures what went wrong.
+- **Rework cycles.** Without quality gates, bad code compounds. A missed requirement discovered late costs 10x more to fix than one caught early.
+- **Risk blindness.** There's no structured way to assess what could go wrong before the agent starts building.
 
-Instead of treating your AI as a solo developer, V-Bounce OS forces distinct, specialized roles (Team Lead, Developer, QA, Architect, Scribe) to communicate exclusively through structured artifacts.
+V-Bounce Engine solves this by wrapping AI agents in the same discipline that makes human engineering teams reliable: planning documents, role-based reviews, automated gates, and a learning loop that compounds knowledge across sprints.
 
-1. **Requirements (`product_plans/`)**: The Team Lead defines standard, immutable templates (Charter, Epic, Story) before a single line of code is written.
-2. **Bounce Reports (`.bounce/`)**: During implementation, the QA and Architect agents do not edit code. They run deep codebase audits and emit structured "Bounce Reports" summarizing anti-patterns and regressions. The Developer must fix the issues and run the loop again until the code passes validation. 
-3. **Product Documentation (`vdocs/`)**: The Scribe agent explores the *actual* codebase post-merge and uses our integrated `vdoc` tool to update feature-centric documentation and the semantic `_manifest.json` map. 
+---
+
+## Built-in Guardrails
 
-The next time an agent writes code, it reads the `_manifest.json` and the `LESSONS.md` file from previous sprints. The context loop closes. Your AI writes better code because it finally understands the reality of your evolving system.
+Every risk that keeps you up at night has a specific mechanism that catches it:
+
+| Risk | What catches it |
+|------|----------------|
+| Agent ships code that doesn't match requirements | **QA gate** — validates every story against acceptance criteria before merge |
+| Architectural drift over time | **Architect gate** — audits against your ADRs and safe-zone rules on every story |
+| One bad story breaks everything | **Git worktrees** — every story is isolated; failures can't contaminate other work |
+| Agent gets stuck in a loop | **3-bounce escalation** — after 3 failed attempts, the story surfaces to a human |
+| Scope creep on "quick fixes" | **Hotfix hard-stop** — Developer must stop if a fix touches more than 2 files |
+| Same mistakes keep happening | **LESSONS.md** — agents read accumulated mistakes before writing future code |
+| Silent regressions | **Root cause tagging** — every failure is tagged and tracked across sprints |
+| Framework itself becomes stale | **Self-improvement skill** — analyzes friction patterns and proposes changes (with your approval) |
 
 ---
 
-## 📂 State-Based Folder Structure
+## Planning With V-Bounce
+
+V-Bounce separates planning into two layers: **what to build** and **how to ship it**. The AI is your planning partner — not a tool you invoke with commands.
+
+### Product Planning — What to Build
+
+Just talk to the AI. Say "plan a feature for X" or "create an epic for payments" and it handles the rest — reading upstream documents, researching your codebase, and drafting planning documents.
+
+A document hierarchy that mirrors how product teams already think:
+
+```
+Charter  (WHY — vision, principles, constraints)
+  → Roadmap  (WHAT/WHEN — releases, milestones, architecture decisions)
+    → Epic  (scoped WHAT — a feature with clear boundaries)
+      → Story  (HOW — implementation spec with acceptance criteria)
+```
+
+**You write the top levels. The AI builds the bottom — informed by your actual codebase.**
+
+When creating Epics, the AI researches your codebase to fill Technical Context with real file paths and verified dependencies — not guesses. When decomposing Epics into Stories, the AI reads affected files, explores architecture patterns, and creates small, focused stories by deliverable (vertical slices), not by layer.
+
+Every document includes an **ambiguity score**:
+- 🔴 High — requirements unclear, blocked from development
+- 🟡 Medium — tech TBD but logic is clear, safe to plan
+- 🟢 Low — fully specified, ready to build
+
+No level can be skipped. This prevents the most common AI failure mode: building the wrong thing because requirements were vague.
+
+### Execution Planning — How to Ship It
 
-V-Bounce OS organizes planning documents (`product_plans/`) through a strict state machine based on folder location:
+Once you know *what* to build, three documents govern *how* it gets delivered:
 
-- **`strategy/`**: High-level context (Charter, Roadmap, Risk Registry, Release Plans). Frozen during active sprints.
-- **`backlog/`**: Where unassigned work lives. Epics and their child Stories are refined here until selected for a sprint.
-- **`sprints/`**: The active execution workspace. A physical `sprint-XX/` boundary is created and Stories are moved in. Only one sprint is "Active" at a time.
-- **`hotfixes/`**: Trivial, emergency tasks that bypass sprint cycles.
-- **`archive/`**: Immutable history. Finished sprint folders and fully completed Epics are permanently moved here.
+| Document | Scope | Who uses it | What it tracks |
+|----------|-------|-------------|----------------|
+| **Delivery Plan** | A full release (multiple sprints) | PM | Which Epics are included, project window (start/end dates), high-level backlog prioritization, escalated/parked stories |
+| **Sprint Plan** | One sprint (typically 1 week) | Team Lead + PM | Active story scope, context pack readiness checklists, execution strategy (parallel vs sequential phases), dependency chains, risk flags, and a live execution log |
+| **Risk Registry** | Cross-cutting (all levels) | PM + Architect | Active risks with likelihood/impact scoring, phase-stamped analysis log, mitigations, and resolution history |
+
+**How they connect:**
+
+```
+Delivery Plan  (the milestone — "we're shipping auth + payments by March 30")
+  → Sprint Plan  (this week — "stories 01-03 in parallel, 04 depends on 01")
+       ↑
+  Risk Registry  (cross-cutting — reviewed at every sprint boundary)
+```
+
+The **Delivery Plan** is updated only at sprint boundaries. The **Sprint Plan** is the single source of truth during active execution — every story state transition is recorded there. At sprint end, the Sprint Plan's execution log becomes the skeleton for the Sprint Report automatically.
+
+The **Sprint Plan** also includes a **Context Pack Readiness** checklist for each story — a preflight check ensuring the spec is complete, acceptance criteria are defined, and ambiguity is low before any code is written. If a story isn't ready, it stays in Refinement.
 
 ---
 
-## 🛠️ The Tech Stack
+## Reports and Visibility
+
+V-Bounce generates structured reports at every stage — designed to answer stakeholder questions without requiring anyone to read code:
 
-V-Bounce OS is built to be **local-first, privacy-conscious, and dependency-light**.
+| Report | When it's generated | What it answers |
+|--------|-------------------|-----------------|
+| **Implementation Report** | After each story is built | What was built? What decisions were made? What tests were added? |
+| **QA Report** | After validation | Does the implementation match the acceptance criteria? What failed? |
+| **Architect Report** | After audit | Does this align with our architecture? Any ADR violations? |
+| **Sprint Report** | End of sprint | What shipped? What bounced? What's the correction tax? Lessons learned? |
+| **Release Report** | After merge | What went to production? Environment changes? Post-merge validations? |
+| **Scribe Report** | After documentation pass | What product docs were created, updated, or flagged as stale? |
 
-- **Runtime**: Node.js — Powering the validation pipeline, context preparation, and CLI.
-- **Data Contract**: YAML Frontmatter + Markdown — Human-readable agent handoffs that are also strictly machine-parsable.
-- **State Management**: `.bounce/state.json` — Machine-readable sprint state for instant crash recovery without re-reading documents.
-- **Context Budget**: On-demand prep scripts (`vbounce prep sprint/qa/arch`) generate capped context packs — no embedding or vector DB required.
+**You don't need to read code to manage the sprint.** The reports surface exactly what a PM or PO needs to make decisions.
 
 ---
 
-## 🚀 Quick Start
+## What You Can Measure
 
-One command to install the entire methodology directly into your AI assistant.
+V-Bounce tracks metrics that map directly to product and delivery health:
 
-```bash
-# For Claude Code
-npx @sandrinio/vbounce install claude
+| Metric | What it tells you | Action when it's bad |
+|--------|------------------|---------------------|
+| **Bounce Rate (QA)** | How often code fails acceptance criteria | Stories may have vague requirements — tighten acceptance criteria |
+| **Bounce Rate (Architect)** | How often code violates architecture rules | ADRs may be unclear, or the agent needs better context |
+| **Correction Tax** | 0% = agent delivered autonomously, 100% = human rewrote everything | High tax means the agent needs better guidance (Charter, Roadmap, or Skills) |
+| **Root Cause Distribution** | Why things fail — `missing_tests`, `adr_violation`, `spec_ambiguity`, etc. | Invest in the category that fails most often |
+| **Escalation Rate** | How often stories hit the 3-bounce limit | Chronic escalation signals structural issues in planning docs |
+| **Sprint Velocity** | Stories completed per sprint | Track trend over time — should improve as LESSONS.md grows |
+
+Run `vbounce trends` to see cross-sprint analysis. Run `vbounce suggest` for AI-generated improvement recommendations.
 
-# For Cursor
-npx @sandrinio/vbounce install cursor
+---
 
-# For Gemini / Antigravity
-npx @sandrinio/vbounce install gemini
+## How a Sprint Flows
 
-# For Copilot / VS Code
-npx @sandrinio/vbounce install vscode
+Here's what a sprint looks like from the product side — no terminal commands, no code:
 
-# For OpenAI Codex
-npx @sandrinio/vbounce install codex
-```
+**Phase 1 — Planning**
+You talk to the AI about what to build. The AI creates Epics and Stories by reading upstream documents and researching your codebase. Ambiguity, risks, and open questions are surfaced and discussed collaboratively.
+
+**Phase 2 — Sprint Planning**
+You and the AI decide what goes into the sprint together. The AI reads the backlog, proposes scope, and surfaces blockers — open questions, unresolved ambiguity, dependency risks, edge cases. You discuss, adjust, and confirm. **No sprint starts without your explicit confirmation.** The Sprint Plan is mandatory.
+
+**Phase 3 — The Bounce**
+The AI team works autonomously. For each Story:
+1. The **Developer** builds the feature in isolation (with E2E tests, not just unit tests)
+2. The **QA agent** checks: does the code meet the acceptance criteria?
+3. The **Architect agent** checks: does the code follow our architecture rules?
+4. If either check fails, the work "bounces" back to the Developer with a tagged reason
+5. After 3 bounces, the story escalates — the AI presents root causes and options (re-scope, split, spike, or remove), and you decide
+
+Lessons are recorded **immediately** after each story merges, not deferred to sprint close.
 
-### What gets installed?
-- **Agent Instructions:** The "Brain" file (e.g., `CLAUDE.md`, `.cursor/rules/`) that teaches your AI how to follow the V-Bounce process.
-- **Templates:** Markdown templates for your Charter, Roadmap, Epics, Stories, Sprint Plans, and Delivery Plans.
-- **Bundled Scripts:** 16+ automation scripts — validation pipeline, context preparation, state management, sprint lifecycle, and the self-improvement loop.
-- **Lightweight Dependencies:** The installer runs `npm install` for `js-yaml`, `marked`, and `commander` — nothing else. No vector DBs, no embedding models.
-- **vdoc Integration:** The installer offers to install [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) for your platform — enabling automatic semantic product documentation generation via the Scribe agent.
+**Phase 4 — Review**
+The Sprint Report lands. It tells you:
+- What shipped and what didn't
+- How many bounces each story took (and why)
+- The correction tax (how much human intervention was needed)
+- Test counts per story
+- Lessons already captured during the sprint
+- Recommendations for process improvements
 
-After installing, run `vbounce doctor` to verify your setup is complete.
+You review, approve the release, and the sprint archives itself. The next sprint starts smarter because the agents now carry forward everything they learned.
 
 ---
 
-## 🛠️ The `vbounce` CLI
+## Continuous Improvement
 
-All V-Bounce OS operations route through a unified CLI. Every command is designed to be run by the Team Lead agent — not just humans.
+Most AI coding setups are stateless — every session starts from scratch. V-Bounce is the opposite.
 
-```bash
-# Sprint lifecycle
-vbounce sprint init S-01 D-01   # Initialize sprint state.json + plan dir
-vbounce sprint close S-01        # Validate terminal states, archive, close
+The **Context Loop** is a closed feedback system that makes your AI team measurably better over time:
 
-# Story lifecycle
-vbounce story complete STORY-001-01-login   # Update state.json + sprint plan §4
+```
+Plan  ──>  Build  ──>  Bounce  ──>  Document  ──>  Learn
+ │                        │             │              │
+ │                    QA + Arch         │          LESSONS.md
+ │                    gate code     Scribe maps        │
+ │                                  the codebase       │
+ └─────────────────────────────────────────────────────┘
+                  Next sprint reads it all
+```
 
-# State management (crash recovery)
-vbounce state show                               # Print current state.json
-vbounce state update STORY-001-01-login "QA Passed"  # Update story state
-vbounce state update STORY-001-01-login "Bouncing" --qa-bounce  # Increment QA bounce
+After each sprint:
+- **LESSONS.md** captures every mistake — agents read this before writing future code
+- **Trend analysis** spots recurring patterns (e.g., "auth-related stories bounce 3x more than average")
+- **Self-improvement pipeline** analyzes friction and proposes concrete framework changes
+- **Scribe** keeps product documentation in sync with actual code
 
-# Context preparation (context budget management)
-vbounce prep sprint S-01          # Generate sprint-context-S-01.md (≤200 lines)
-vbounce prep qa STORY-001-01-login    # Generate qa-context-STORY-ID.md (≤300 lines)
-vbounce prep arch STORY-001-01-login  # Generate arch-context with truncated diff
+Sprint 1 might have a 40% bounce rate. By Sprint 5, that number drops — because the agents have accumulated context about your codebase, your architecture decisions, and your team's standards.
 
-# Validation gates
-vbounce validate report .bounce/reports/STORY-001-01-login-qa.md
-vbounce validate state            # Validate state.json schema
-vbounce validate sprint S-01      # Validate sprint plan structure + cross-refs
-vbounce validate ready STORY-001-01-login  # Pre-bounce readiness gate
+### The Self-Improvement Pipeline
 
-# Self-improvement loop
-vbounce trends                    # Compute sprint metrics → .bounce/trends.md
-vbounce suggest S-01              # Generate improvement suggestions
+When a sprint closes (`vbounce sprint close`), an automated pipeline analyzes what went wrong and proposes how to fix the framework itself:
 
-# Framework health
-vbounce doctor                    # Check all required files, scripts, templates
 ```
+Sprint Close
+  │
+  ├── Trend Analysis         → Cross-sprint bounce patterns
+  │
+  ├── Retro Parser           → Reads §5 Framework Self-Assessment tables
+  │                            from the Sprint Report
+  │
+  ├── Lesson Analyzer        → Classifies LESSONS.md rules by what they
+  │                            can become: gate checks, scripts, template
+  │                            fields, or permanent agent rules
+  │
+  ├── Recurrence Detector    → Cross-references archived sprint reports
+  │                            to find findings that keep coming back
+  │
+  ├── Effectiveness Checker  → Did last sprint's improvements actually
+  │                            resolve their target findings?
+  │
+  └── Improvement Suggestions → Human-readable proposals with impact levels
+```
+
+Every proposal gets an **impact level** so you know what to fix first:
+
+| Level | Label | Meaning | When to fix |
+|-------|-------|---------|-------------|
+| **P0** | Critical | Blocks agent work or causes incorrect output | Before next sprint |
+| **P1** | High | Causes rework — bounces, wasted tokens, repeated manual steps | This improvement cycle |
+| **P2** | Medium | Friction that slows agents but doesn't block | Within 2 sprints |
+| **P3** | Low | Polish — nice-to-have | Batch when convenient |
+
+### Lessons Become Automation
+
+The pipeline doesn't just track lessons — it classifies each one by what it can become:
+
+| Lesson pattern | Becomes | Example |
+|---------------|---------|---------|
+| "Always check X", "Never use Y" | **Gate check** — automated grep/lint rule | "Never import from internal modules" → pre-gate grep pattern |
+| "Run X before Y" | **Script** — validation step | "Run type-check before QA" → added to pre_gate_runner.sh |
+| "Include X in the story" | **Template field** — required section | "Include rollback plan" → new field in story template |
+| General behavioral rules (3+ sprints old) | **Agent config** — permanent brain rule | "Always check for N+1 queries" → graduated to Architect config |
+
+This means your framework evolves organically: agents report friction, the pipeline classifies it, you approve the fix, and the next sprint runs smoother. No manual analysis required.
+
+Run `vbounce improve S-XX` anytime to trigger the pipeline on demand.
 
 ---
 
-## 🔄 State Management & Crash Recovery
+## Is V-Bounce Right For You?
 
-V-Bounce OS tracks sprint state in `.bounce/state.json` — a machine-readable snapshot that survives context resets and session interruptions.
+**Best fit:**
+- Teams using AI agents for production code (not just prototypes)
+- Projects with clear requirements that can be expressed as acceptance criteria
+- Codebases where architectural consistency matters
+- Teams that want to scale AI usage without losing quality control
 
-```json
-{
-  "sprint_id": "S-01",
-  "delivery_id": "D-01",
-  "current_phase": "bouncing",
-  "last_action": "QA failed STORY-001-01-login — bounce 1",
-  "stories": {
-    "STORY-001-01-login": {
-      "state": "Bouncing",
-      "qa_bounces": 1,
-      "arch_bounces": 0,
-      "worktree": ".worktrees/STORY-001-01-login",
-      "updated_at": "2026-03-12T10:00:00Z"
-    }
-  }
-}
-```
+**Less ideal for:**
+- One-off scripts or throwaway prototypes (overkill)
+- Exploratory research with no defined requirements
+- Projects where the entire team is deeply embedded in every code change anyway
 
-When a new session starts, the Team Lead reads `state.json` in under 5 seconds to know exactly where the sprint left off — no re-reading 10 markdown files.
+**Minimum setup:** One person who can run `npx` commands + one person who can write a Charter and Epics. That's it.
 
 ---
 
-## 📊 Self-Improvement Loop
+## Roles and Responsibilities
+
+### Human
+
+You own the planning and the final say. The agents never ship without your approval.
 
-V-Bounce OS tracks its own performance and suggests improvements automatically.
+| Responsibility | What it involves |
+|---------------|-----------------|
+| **Set vision and constraints** | Write the Charter and Roadmap — define what to build and what's off-limits |
+| **Define requirements** | Break Roadmap into Epics and Stories with acceptance criteria |
+| **Review and approve** | Read sprint reports, approve releases, intervene on escalations |
+| **Tune agent performance** | Adjust brain files, skills, and ADRs based on trend data and bounce patterns |
+| **Install and configure** | Run the installer, verify setup with `vbounce doctor` |
 
-1. **Root Cause Tagging**: Every QA and Architect FAIL report includes a `root_cause:` field (e.g., `missing_tests`, `adr_violation`, `spec_ambiguity`) that feeds into trend analysis.
-2. **Sprint Trends**: `vbounce trends` scans all archived reports to compute first-pass rate, average bounce count, correction tax, and root cause breakdown per sprint.
-3. **Improvement Suggestions**: `vbounce suggest S-{XX}` reads trends, LESSONS.md, and the improvement log to flag stale lessons, recurring failure patterns, and graduation candidates.
-4. **Improvement Log**: `.bounce/improvement-log.md` tracks every suggestion with Applied/Rejected/Deferred status — so nothing falls through the cracks.
+### Agent — Team Lead (Orchestrator)
+
+The Team Lead reads your planning documents and coordinates the entire sprint. It never writes code — it delegates, tracks state, and generates reports.
+
+| Responsibility | What it involves |
+|---------------|-----------------|
+| **Sprint orchestration** | Assigns stories, manages state transitions, enforces the bounce loop |
+| **Agent delegation** | Spawns Developer, QA, Architect, DevOps, and Scribe agents as needed |
+| **Report routing** | Reads each agent's output and decides the next step (pass, bounce, escalate) |
+| **Escalation** | Surfaces stories to the human after 3 failed bounces |
+| **Sprint reporting** | Consolidates execution data into Sprint Reports and Release Reports |
+
+### Agent — Specialists (Developer, QA, Architect, DevOps, Scribe)
+
+Five specialist agents, each with a single job and strict boundaries:
+
+| Agent | What it does | Constraints |
+|-------|-------------|-------------|
+| **Developer** | Implements stories in isolated worktrees, submits implementation reports | Works only in its assigned worktree |
+| **QA** | Validates code against acceptance criteria | Read-only — cannot modify code |
+| **Architect** | Audits against ADRs, architecture rules, and safe-zone boundaries | Read-only — cannot modify code |
+| **DevOps** | Merges passing stories into the sprint branch | Only acts after both gates pass |
+| **Scribe** | Generates and maintains product documentation from the actual codebase | Only runs after merge |
+
+One person can fill the entire human side. The framework scales to the team you have.
 
 ---
 
-## 🔧 Tool Tier Model
+## Quick Start
 
-V-Bounce OS supports four tiers of AI tools with dedicated brain files for each.
+```bash
+npx @sandrinio/vbounce install claude    # Claude Code
+npx @sandrinio/vbounce install cursor    # Cursor
+npx @sandrinio/vbounce install gemini    # Gemini CLI
+npx @sandrinio/vbounce install codex     # OpenAI Codex
+npx @sandrinio/vbounce install vscode    # GitHub Copilot
+```
 
-| Tier | Tools | Brain File | Capabilities |
-|------|-------|------------|--------------|
-| **Tier 1** | Claude Code | `brains/CLAUDE.md` | Full orchestration — spawns subagents, manages state, runs all CLI commands |
-| **Tier 2** | Gemini CLI, OpenAI Codex | `brains/GEMINI.md`, `brains/codex/` | Single-agent — follows bounce loop, reads state.json, all CLI commands |
-| **Tier 3** | Cursor | `brains/cursor-rules/` | Role-specific context injection via `.cursor/rules/` MDC files |
-| **Tier 4** | GitHub Copilot, Windsurf | `brains/copilot/`, `brains/windsurf/` | Awareness mode — checklist-driven, reads state.json, CLI commands for safe operations |
+Then verify your setup:
 
-Install the appropriate brain for your tool:
 ```bash
-npx @sandrinio/vbounce install claude   # Tier 1
-npx @sandrinio/vbounce install gemini   # Tier 2
-npx @sandrinio/vbounce install cursor   # Tier 3
-npx @sandrinio/vbounce install vscode   # Tier 4
+npx vbounce doctor
+```
+
+### What gets installed
+
+Here's what lands in your repo (example: Claude Code):
+
+```
+your-project/
+├── CLAUDE.md                    # Brain file — teaches the agent the V-Bounce process
+├── .claude/agents/              # Subagent instructions (Claude Code only)
+│   ├── developer.md
+│   ├── qa.md
+│   ├── architect.md
+│   ├── devops.md
+│   └── scribe.md
+├── templates/                   # 9 Markdown + YAML frontmatter templates
+│   ├── charter.md
+│   ├── roadmap.md
+│   ├── epic.md
+│   ├── story.md
+│   ├── sprint.md
+│   ├── delivery_plan.md
+│   ├── sprint_report.md
+│   ├── hotfix.md
+│   └── risk_registry.md
+├── skills/                      # 7 modular skill files (see Skills below)
+│   ├── agent-team/
+│   ├── doc-manager/
+│   ├── lesson/
+│   ├── vibe-code-review/
+│   ├── write-skill/
+│   ├── improve/
+│   └── react-best-practices/   # Example — customize for your stack
+├── scripts/                     # 23 automation scripts (validation, context prep, state)
+└── package.json                 # 3 deps: js-yaml, marked, commander. Nothing else.
+```
+
+Other platforms install the same `templates/`, `skills/`, and `scripts/` — only the brain file differs (`.cursor/rules/`, `GEMINI.md`, `AGENTS.md`, or `.github/copilot-instructions.md`).
+
+Everything is plain Markdown and Node.js. No vector DBs, no embedding models, no background services.
+
+---
+
+## Supported Tools
+
+V-Bounce Engine adapts to each tool's capabilities:
+
+| Tier | Tool | How it works |
+|------|------|-------------|
+| 1 | Claude Code | Full orchestration — spawns subagents for each role, manages state, runs all CLI commands |
+| 2 | Gemini CLI, Codex | Single-agent mode — follows the bounce loop sequentially, full CLI access |
+| 3 | Cursor | Role-specific context injection via `.cursor/rules/` MDC files |
+| 4 | Copilot, Windsurf | Awareness mode — checklist-driven, reads state, safe CLI operations |
+
+---
+
+## The Bounce Loop
+
+This is the core execution cycle for every Story:
+
+```
+         Developer                QA                 Architect            DevOps
+            │                     │                      │                  │
+  Writes code in worktree         │                      │                  │
+  Submits Implementation  ──────> │                      │                  │
+  Report                   Validates against       (waits for QA)          │
+                           acceptance criteria           │                  │
+                                  │                      │                  │
+                           PASS ──────────────────────>  │                  │
+                           FAIL ──> bounces back    Audits against          │
+                                    to Developer    ADRs + safe zone        │
+                                                         │                  │
+                                                  PASS ──────────────────>  │
+                                                  FAIL ──> bounces back  Merges worktree
+                                                           to Developer  into main branch
 ```
 
+After 3 failed bounces on either gate, the Story escalates to you for intervention.
+
+Each FAIL report includes a `root_cause` tag that feeds into cross-sprint trend analysis via `vbounce trends`.
+
 ---
 
-### 🧰 The Bundled Skills
-V-Bounce OS installs a powerful suite of specialized markdown `skills/` directly into your workspace. These act as modular capabilities you can invoke dynamically or that the Team Lead agent will invoke automatically during the SDLC process:
+## Skills
+
+Skills are modular markdown instructions the Team Lead invokes automatically during the SDLC:
 
-| Skill | Role | Purpose |
-|-------|------|---------|
-| `agent-team` | Lead | Spawns temporary sub-agents (Dev, QA, DevOps) to parallelize complex tasks without losing context. |
-| `doc-manager` | All | Enforces the strict hierarchy for managing Epic and Story documents *(Charter is optional, used only for new projects or brainstorming)*. |
-| `lesson` | Lead | Extracts mistakes made during Sprints and updates `LESSONS.md` to prevent future regressions. |
-| `react-best-practices` | Developer | A strict set of frontend execution rules the Developer must follow during implementation. <mark>*(Note: This skill serves as a template and must be customized by the human according to the specific tech stack being used.)*</mark> |
-| `vibe-code-review` | QA/Architect | Runs distinct review modes (Quick Scan, Deep Audit) to validate code against Acceptance Criteria and Architecture rules. |
-| `write-skill` | Lead | Allows the Team Lead to autonomously write and deploy entirely *new* skills if the team repeatedly encounters a novel problem. |
-| `improve` | Lead | The framework's self-improvement loop. Reads agent friction signals from sprint retros and proposes targeted changes to templates, skills, brain files, and scripts — with human approval. |
+| Skill | Purpose |
+|-------|---------|
+| `agent-team` | Spawns temporary sub-agents (Dev, QA, Architect, DevOps, Scribe) to parallelize work |
+| `doc-manager` | Enforces the document hierarchy for Epics and Stories |
+| `lesson` | Extracts mistakes from sprints into `LESSONS.md` |
+| `vibe-code-review` | Runs Quick Scan or Deep Audit against acceptance criteria and architecture rules |
+| `write-skill` | Allows the Team Lead to author new skills when the team encounters a recurring problem |
+| `improve` | Self-improvement loop — reads agent friction signals across sprints and proposes framework changes (with your approval) |
+| `react-best-practices` | Example tech-stack skill — customize this for your own stack |
 
 ---
 
-## ⚙️ A Skill-Driven Methodology
+## State Management
+
+Sprint state lives in `.bounce/state.json` — a machine-readable snapshot that survives context resets and session interruptions:
+
+```json
+{
+  "sprint_id": "S-01",
+  "current_phase": "bouncing",
+  "stories": {
+    "STORY-001-01-login": {
+      "state": "Bouncing",
+      "qa_bounces": 1,
+      "arch_bounces": 0,
+      "worktree": ".worktrees/STORY-001-01-login"
+    }
+  }
+}
+```
 
-V-Bounce OS enforces a strict hierarchy. No code is written without a plan, and no task is executed without invoking the proper skills.
+When a session starts, the Team Lead reads `state.json` to resume exactly where the sprint left off.
 
-### 1. Planning Layer
-You use the bundled templates to define the work.
-`Charter ➔ Roadmap ➔ Epic ➔ Story`
+---
 
-### 2. The Bounce Loop (Implementation)
-Once a Story is ready, you kick off the AI sprint.
-1. The **Developer** AI writes the code and submits an Implementation Report.
-2. The **QA** AI reads the report and tests it against the Story's requirements. If it fails, it bounces back. (Max 3 attempts before escalating to you).
-3. The **Architect** AI audits the successful QA build against your Safe Zone and Architecture Decision Records (ADRs).
-4. Only when both gates pass does the **DevOps** AI merge the isolated worktree into your main branch.
+## CLI Reference
 
-### 3. End of Sprint Reports
-When a sprint concludes, V-Bounce OS generates structured reports so human reviewers can audit the work without reading every line of code:
-- **Sprint Report**: A comprehensive summary by the Team Lead detailing what was delivered, execution metrics, story results, and a retro of what went wrong.
-- **Sprint Release Report**: The DevOps agent's log of the merge process to the main branch, environment changes, and post-merge test validations.
-- **Scribe Report**: The Scribe agent's complete audit of which product documentation files were generated, updated, or removed (using `vdoc`) to map the new codebase reality.
+```bash
+# Sprint lifecycle
+vbounce sprint init S-01 D-01         # Initialize sprint
+vbounce sprint close S-01             # Validate, archive, close
 
-### 4. Progressive Learning (`LESSONS.md`)
-Every time the AI makes a mistake during the Bounce Loop, it flags the issue. During the sprint retrospective, these mistakes are recorded in `LESSONS.md`—a permanent project memory that all agents read *before* writing any future code. **Your AI gets smarter about your specific codebase with every single sprint.**
+# Story lifecycle
+vbounce story complete STORY-ID       # Mark story done, update state
+
+# State management
+vbounce state show                    # Print current state
+vbounce state update STORY-ID STATE   # Update story state
+
+# Context preparation
+vbounce prep sprint S-01              # Sprint context pack
+vbounce prep qa STORY-ID              # QA context pack
+vbounce prep arch STORY-ID            # Architect context pack
+
+# Validation
+vbounce validate report <file>        # Validate report YAML
+vbounce validate state                # Validate state.json schema
+vbounce validate sprint S-01          # Validate sprint plan
+vbounce validate ready STORY-ID       # Pre-bounce readiness gate
+
+# Self-improvement
+vbounce trends                        # Cross-sprint trend analysis
+vbounce suggest S-01                  # Generate improvement suggestions
+vbounce improve S-01                  # Full self-improvement pipeline
+
+# Health check
+vbounce doctor                        # Verify setup
+```
 
-### 5. Self-Improving Framework (`improve` skill)
-V-Bounce OS doesn't just improve your code — it improves *itself*. Every agent report includes a **Process Feedback** section where agents flag friction with the framework: a template missing a critical field, a handoff that lost context, a RAG query that returned irrelevant results, or a skill instruction that was unclear.
+---
 
-These signals are aggregated into the Sprint Report's **Framework Self-Assessment** — categorized by area (Templates, Handoffs, RAG Pipeline, Skills, Process Flow, Tooling) with severity ratings and suggested fixes.
+## Runtime Structure
 
-After every 2-3 sprints, the Team Lead runs the `improve` skill which:
-1. Reads accumulated friction signals across sprints
-2. Identifies recurring patterns (same complaint from multiple agents = real problem)
-3. Proposes specific, targeted changes to templates, skills, brain files, or scripts
-4. **Applies nothing without your approval** — you review every proposed change
+As you use V-Bounce Engine, the framework creates these directories to manage your sprints:
 
-The result: templates get sharper, handoffs get cleaner, skills get more precise, and the bounce loop gets tighter — all driven by the agents who actually use the framework every day.
+```
+product_plans/                   # Created when you start planning
+  strategy/                      #   Charter, Roadmap, Risk Registry (frozen during sprints)
+  backlog/                       #   Epics and Stories awaiting sprint assignment
+  sprints/                       #   Active sprint workspace (one active at a time)
+  hotfixes/                      #   Emergency fixes that bypass sprint cycles
+  archive/                       #   Completed sprints and Epics (immutable history)
+
+.bounce/                         # Created on first sprint init
+  state.json                     #   Machine-readable sprint state (crash recovery)
+  reports/                       #   QA and Architect bounce reports
+  improvement-manifest.json      #   Machine-readable improvement proposals (auto-generated)
+  improvement-suggestions.md     #   Human-readable suggestions with impact levels (auto-generated)
+  improvement-log.md             #   Applied/rejected/deferred improvement tracking
+
+.worktrees/                      # Git worktrees for isolated story branches
+
+LESSONS.md                       # Accumulated mistakes — agents read this before coding
+```
 
 ---
 
-## 🔍 Keywords for Searchability
-`ai coding agent` `claude code` `cursor` `github copilot` `gemini` `openai codex` `software development lifecycle` `sdlc` `ai software engineer` `autonomous coding` `agentic framework` `software architecture` `ai team` `vdoc` `ai documentation` `prompt engineering`
+## Glossary
+
+| Term | Definition |
+|------|-----------|
+| **Bounce** | When a story fails a quality gate (QA or Architect) and gets sent back to the Developer for fixes |
+| **Bounce Rate** | Percentage of stories that fail a gate on the first attempt |
+| **Context Loop** | The closed feedback cycle: Plan → Build → Bounce → Document → Learn → next sprint |
+| **Correction Tax** | How much human intervention a story needed — 0% is fully autonomous, 100% means a human rewrote it |
+| **Escalation** | When a story hits the 3-bounce limit and surfaces to a human for intervention |
+| **Gate** | An automated quality checkpoint — QA validates requirements, Architect validates structure |
+| **Hotfix Path** | A fast track for trivial (L1) changes: 1-2 files, no QA/Architect gates, human verifies directly |
+| **L1–L4** | Complexity labels: L1 Trivial, L2 Standard, L3 Complex, L4 Strategic |
+| **Root Cause Tag** | A label on every bounce failure (e.g., `missing_tests`, `adr_violation`) used for trend analysis |
+| **Scribe** | The documentation agent that maps code into semantic product docs |
+| **Sprint Report** | End-of-sprint summary: what shipped, metrics, bounce analysis, lessons, retrospective |
+| **Worktree** | An isolated git checkout where a single story is implemented — prevents cross-story interference |
 
 ---
 
-## 📖 Documentation
-- [How to structure an Epic](templates/epic.md)
-- [How the Bounce Loop handles Hotfixes](docs/HOTFIX_EDGE_CASES.md)
-- [Integrating with vdoc](https://github.com/sandrinio/vdoc)
+## Documentation
+
+- [System Overview with diagrams](OVERVIEW.md)
+- [Epic template and structure](templates/epic.md)
+- [Hotfix edge cases](docs/HOTFIX_EDGE_CASES.md)
+- [vdoc integration](https://github.com/sandrinio/vdoc)
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome. Check the [issues page](https://github.com/sandrinio/v-bounce-engine/issues).
 
-## 🤝 Contributing
-Contributions, issues, and feature requests are welcome! Feel free to check the [issues page]().
+## License
 
-## 📝 License
-This project is [MIT](LICENSE) licensed.
+[MIT](LICENSE)