🎯 V-Bounce OS

Turn your AI coding assistant into a full engineering team.

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.

Inspired by the work of Cory Hymel

💡 The Hook: Why V-Bounce OS?

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.

The core differentiator of V-Bounce OS is the Context Loop: Requirements → Bounce Reports → Product Documentation.

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.

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.

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.

📂 State-Based Folder Structure

V-Bounce OS organizes planning documents (product_plans/) through a strict state machine based on folder location:

• 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.

🛠️ The Tech Stack

V-Bounce OS is built to be local-first, privacy-conscious, and blazing fast.

• Vector Database: LanceDB — A serverless, local vector DB used to store and query project context.
• Embeddings: Xenova Transformers — Local execution of all-MiniLM-L6-v2. No private code is ever sent to external embedding APIs for RAG.
• Runtime: Node.js — Powering the validation pipeline and semantic search engine.
• Data Contract: YAML Frontmatter + Markdown — Ensures human-readable agent handoffs that are also strictly machine-parsable.

🧠 Semantic Context (Local RAG)

V-Bounce OS doesn't just dump your entire codebase into a prompt. It uses Retrieval-Augmented Generation (RAG) to find only the rules that matter right now.

1. Indexing: The pre_bounce_sync.sh script crawls your product_plans/, LESSONS.md, and Roadmap ADRs, converting them into searchable vectors.
2. Querying: Agents use the built-in ./scripts/vbounce_ask.mjs tool to ask questions like "What are the architectural constraints for auth?" or "What mistakes did we make with the last React component?".
3. Targeted Context: The agent receives only the most relevant 3-5 snippets of project history, preventing context-window bloat and improving instruction following.

🚀 Quick Start

One command to install the entire methodology directly into your AI assistant.

# For Claude Code
npx @sandrinio/vbounce install claude

# For Cursor
npx @sandrinio/vbounce install cursor

# For Gemini / Antigravity
npx @sandrinio/vbounce install gemini

# For Copilot / VS Code
npx @sandrinio/vbounce install vscode

# For OpenAI Codex
npx @sandrinio/vbounce install codex

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, and Stories.
• Bundled Scripts: Our validation pipeline (validate_report.mjs) and RAG synchronization engine (pre_bounce_sync.sh).
• Autonomous RAG Setup: The installer automatically runs npm install for required libraries and initializes your local LanceDB knowledge base (.bounce/.lancedb/).
• vdoc Integration: The installer offers to install @sandrinio/vdoc for your platform — enabling automatic semantic product documentation generation via the Scribe agent.

🧰 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:

| 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. (Note: This skill serves as a template and must be customized by the human according to the specific tech stack being used.) | | 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. |

⚙️ A Skill-Driven Methodology

V-Bounce OS enforces a strict hierarchy. No code is written without a plan, and no task is executed without invoking the proper skills.

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.

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.

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.

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.

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

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.

🔍 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

📖 Documentation

• How to structure an Epic
• How the Bounce Loop handles Hotfixes
• Integrating with vdoc

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

📝 License

This project is MIT licensed.