Quick Start

Get your new AI team up and running in seconds. No complex setup, no vector databases. Just plain Markdown and Node.

# 1. Install the framework for your platform of choice
npx vbounce-engine install claude    # Claude Code (Full Orchestration)
# Or: npx vbounce-engine install cursor|gemini|codex|vscode

# 2. Verify your installation
npx vbounce-engine doctor

# 3. Initialize your first sprint!
npx vbounce-engine sprint init S-01 --stories STORY-001-01

Requirements: Node.js and a project directory. That's it. One person to set the vision, the AI handles the execution.

The Problem: AI Chaos

AI coding tools are incredibly fast, but without guardrails, they create expensive chaos:

• No accountability: Code ships with bugs a junior dev would catch.
• Invisible progress: "The agent is still running." No milestones, no checks.
• Goldfish memory: Every session is Day 1. It makes the same architectural mistake twice.
• Infinite loops: The agent gets stuck trying to fix its own broken code.

Why V-Bounce Engine?

V-Bounce wraps your AI agents in the same discipline that makes human engineering teams reliable:

| Guardrail | What It Solves | |-------------|-------------------| | Isolated Worktrees | Contamination. Every story is a sandbox. One bad story won't break your app. | | QA Quality Gates | Missed Requirements. Code is validated against Acceptance Criteria before merge. | | Architect Audits | Drift. Blocks the AI from hallucinating new dependencies or breaking patterns. | | 3-Bounce Escalation | Infinite Loops. After 3 failed attempts, the AI surfaces the root cause to you. | | Persistent Lessons | Goldfish Memory. The AI logs mistakes in FLASHCARDS.md and reads them next sprint. |

The Planning Phase

V-Bounce doesn't just protect execution — it structures planning so your AI never starts coding from a vague prompt.

You and the AI collaborate through a strict document hierarchy. Each level inherits context from the one above, so nothing is lost or hallucinated.

Charter  →  Roadmap  →  Epic  →  Story  →  Sprint Plan  →  Bounce
  WHY         WHAT       WHAT      HOW       WHEN           DO

How It Works

1. You set the vision. Write a Charter (the why) and Roadmap (the what). The AI reads these before touching anything else.
2. AI researches, then plans. Before creating Stories, the AI explores your actual codebase — reading affected files, discovering patterns, and identifying real dependencies. No guessing.
3. Ambiguity is surfaced, not hidden. Every Epic and Story gets an Ambiguity Score (🟢 Low / 🟡 Medium / 🔴 High). If critical unknowns exist, the AI creates Spikes — focused investigations that must complete before coding begins.
4. Sprint Planning is collaborative. The AI proposes scope, surfaces risks, flags open questions, and identifies dependency chains. You discuss, adjust, and confirm. No sprint starts without your explicit sign-off.
5. Stories are sized for success. Each story has one clear goal, touches 1–3 files, and produces a verifiable result. Vertical slices over horizontal layers — always.

The Sprint Planning Gate

| Step | What Happens | |------|--------------| | Read | AI scans backlog, archive, and risk registry to build full context | | Propose | AI selects stories by priority and dependency, flags blockers | | Discuss | You and the AI resolve open questions, adjust scope, agree on execution mode | | Confirm | You approve the Sprint Plan → stories move into execution → Bounce begins |

Hard rule: The Bounce Loop cannot start without a finalized, human-confirmed Sprint Plan.

The "Bounce" Loop

Instead of letting an AI hallucinate straight to production, V-Bounce coordinates specialized roles working in isolation.

1. Developer: Implements features in isolated git worktrees.
2. QA: Validates code strictly against acceptance criteria. (Read-only)
3. Architect: Audits code against ADRs (Architecture Decision Records). (Read-only)
4. DevOps: Merges passing code cleanly to the sprint branch.
5. Scribe: Keeps product documentation in sync with actual code.

Measure What Matters (Metrics)

For the first time, manage your AI work like a true Product Manager. Run vbounce trends to track:

• Bounce Rate (QA / Architect): How often does the AI fail to meet spec?
• Correction Tax: How much manual human intervention was required? (0% = AI shipped autonomously).
• Escalation Rate: How often did stories hit the 3-bounce limit?

Supported Platforms

V-Bounce adapts to your current workflow effortlessly.

• Claude Code (Tier 1): Full orchestration. Spawns specific subagents for each role seamlessly.
• Gemini CLI / Codex (Tier 2): Single-agent mode, following the strict sequential bounce loop.
• Cursor (Tier 3): Deep integration via modular .cursor/rules/ MDC mapping.
• Copilot / Windsurf (Tier 4): Embedded awareness through checklists and state reading.

Deep Dive & Docs

Ready to see how deep the rabbit hole goes?

• System Overview & Architecture
• Epic and Story Templates
• Self-Improvement Pipeline (vbounce improve) (Your AI optimizes its own framework)