@sandrinio/vbounce 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# 🎯 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 (`product_documentation/`)**: 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.
+
+---
+
+## 🚀 Quick Start
+
+One command to install the entire methodology directly into your AI assistant.
+
+```bash
+# 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.
+- **vdoc Integration:** Fully bundled with [`@sandrinio/vdoc`](https://github.com/sandrinio/vdoc) to automatically construct the `vdocs/` semantic documentation folder.
+
+### 🧰 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. <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. |
+
+---
+
+## ⚙️ 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.**
+
+---
+
+## 🔍 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](templates/epic.md)
+- [How the Bounce Loop handles Hotfixes](docs/HOTFIX_EDGE_CASES.md)
+- [Integrating with vdoc](https://github.com/sandrinio/vdoc)
+
+## 🤝 Contributing
+Contributions, issues, and feature requests are welcome! Feel free to check the [issues page]().
+
+## 📝 License
+This project is [MIT](LICENSE) licensed.

package/bin/vbounce.mjs

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import readline from 'readline';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const pkgRoot = path.join(__dirname, '..');
+
+const args = process.argv.slice(2);
+const command = args[0];
+const targetPlatform = args[1]?.toLowerCase();
+
+if (command === '-v' || command === '--version') {
+  const pkgPath = path.join(pkgRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkgInfo = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    console.log(`v${pkgInfo.version}`);
+  } else {
+    console.log('Version information unavailable.');
+  }
+  process.exit(0);
+}
+
+// Utility for interactive prompt
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const askQuestion = (query) => new Promise(resolve => rl.question(query, resolve));
+
+function displayHelp() {
+  console.log(`
+🎯 V-Bounce OS Installer
+
+Usage:
+  npx vbounce install <platform>
+
+Supported Platforms:
+  claude  : Installs CLAUDE.md and Claude Code subagents
+  cursor  : Installs modular .cursor/rules/
+  gemini  : Installs GEMINI.md and Antigravity skills
+  codex   : Installs AGENTS.md for OpenAI Codex
+  vscode  : Installs standard system prompt for Copilot
+  copilot : Alias for vscode
+`);
+  process.exit(0);
+}
+
+if (!command || command !== 'install' || !targetPlatform) {
+  displayHelp();
+}
+
+const CWD = process.cwd();
+
+const platformMappings = {
+  claude: [
+    { src: 'brains/CLAUDE.md', dest: 'CLAUDE.md' },
+    { src: 'brains/claude-agents', dest: '.claude/agents' },
+    { src: 'templates', dest: 'templates' },
+    { src: 'skills', dest: 'skills' }
+  ],
+  cursor: [
+    { src: 'brains/cursor-rules', dest: '.cursor/rules' },
+    { src: 'templates', dest: 'templates' },
+    { src: 'skills', dest: 'skills' }
+  ],
+  gemini: [
+    { src: 'brains/GEMINI.md', dest: 'GEMINI.md' },
+    { src: 'templates', dest: 'templates' },
+    { src: 'skills', dest: 'skills' },
+    { src: 'skills', dest: '.agents/skills' }
+  ],
+  codex: [
+    { src: 'brains/AGENTS.md', dest: 'AGENTS.md' },
+    { src: 'templates', dest: 'templates' },
+    { src: 'skills', dest: 'skills' }
+  ],
+  vscode: [
+    { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
+    { src: 'templates', dest: 'templates' },
+    { src: 'skills', dest: 'skills' }
+  ],
+  copilot: [
+    { src: 'brains/CLAUDE.md', dest: '.github/copilot-instructions.md' },
+    { src: 'templates', dest: 'templates' },
+    { src: 'skills', dest: 'skills' }
+  ]
+};
+
+const mapping = platformMappings[targetPlatform];
+
+if (!mapping) {
+  console.error(`Error: Unsupported platform '${targetPlatform}'.\n`);
+  displayHelp();
+}
+
+console.log(`\n🚀 Preparing to install V-Bounce OS for \x1b[36m${targetPlatform}\x1b[0m...\n`);
+
+const toCopy = [];
+const toOverwrite = [];
+
+mapping.forEach(rule => {
+  const sourcePath = path.join(pkgRoot, rule.src);
+  const destPath = path.join(CWD, rule.dest);
+
+  if (!fs.existsSync(sourcePath)) {
+    return; // Source does not exist internally, skip
+  }
+
+  if (fs.existsSync(destPath)) {
+    toOverwrite.push(rule.dest);
+  } else {
+    toCopy.push(rule.dest);
+  }
+});
+
+if (toCopy.length > 0) {
+  console.log('The following will be \x1b[32mCREATED\x1b[0m:');
+  toCopy.forEach(f => console.log(`  + ${f}`));
+}
+
+if (toOverwrite.length > 0) {
+  console.log('\nThe following will be \x1b[33mOVERWRITTEN\x1b[0m:');
+  toOverwrite.forEach(f => console.log(`  ! ${f}`));
+}
+
+console.log('');
+
+askQuestion('Proceed with installation? [y/N] ').then(answer => {
+  rl.close();
+  const confirmation = answer.trim().toLowerCase();
+
+  if (confirmation !== 'y' && confirmation !== 'yes') {
+    console.log('\n❌ Installation cancelled.\n');
+    process.exit(0);
+  }
+
+  console.log('\n📦 Installing files...');
+
+  mapping.forEach(rule => {
+    const sourcePath = path.join(pkgRoot, rule.src);
+    const destPath = path.join(CWD, rule.dest);
+
+    if (!fs.existsSync(sourcePath)) return;
+
+    const stats = fs.statSync(sourcePath);
+    if (stats.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      fs.cpSync(sourcePath, destPath, { recursive: true, force: true });
+    } else {
+      const destDir = path.dirname(destPath);
+      if (!fs.existsSync(destDir)) {
+        fs.mkdirSync(destDir, { recursive: true });
+      }
+      fs.copyFileSync(sourcePath, destPath);
+    }
+    console.log(`  \x1b[32m✓\x1b[0m ${rule.dest}`);
+  });
+
+  console.log('\n✅ V-Bounce OS successfully installed! Welcome to the team.\n');
+});

package/brains/AGENTS.md

@@ -0,0 +1,129 @@
+# V-Bounce OS — Agent Brain (Codex CLI)
+
+> This file configures OpenAI Codex CLI to operate within the V-Bounce OS framework.
+
+## Identity
+
+You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
+
+You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
+
+## Skills
+
+Skills are in the `skills/` directory. Each skill has a `SKILL.md` with instructions. Read the relevant SKILL.md before performing any skill-related task.
+
+| Skill | Purpose | Used By |
+|-------|---------|---------|
+| `skills/agent-team/` | Subagent orchestration and delegation | Team Lead |
+| `skills/doc-manager/` | Document hierarchy navigation and lifecycle | Team Lead, all agents |
+| `skills/lesson/` | Recording project-specific mistakes and rules | All agents (read), Team Lead (write) |
+| `skills/react-best-practices/` | Frontend coding patterns and anti-patterns | Developer |
+| `skills/vibe-code-review/` | Code quality review (4 modes) | QA, Architect |
+| `skills/write-skill/` | Creating and refining agent skills | Team Lead |
+
+## The V-Bounce Process
+
+### Phase 1: Verification (Planning)
+Documents are created in strict hierarchy — no level can be skipped:
+Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
+
+### Pre-Bounce Checks
+Before starting any sprint, the Team Lead MUST:
+- **Triage the Request**: Is this an L1 Trivial change (1-2 files, cosmetic/minor)?
+  - If YES → Use the **Hotfix Path** (create a Hotfix document, bypass Epic/Story).
+  - If NO → Use the **Standard Path** (create/find Epic, Story).
+- Read RISK_REGISTRY.md — flag high-severity risks that affect planned stories.
+- Read DELIVERY_PLAN.md §5 Open Questions — do not bounce stories with unresolved blocking questions.
+- If product_documentation/_manifest.json exists, read it — understand what's documented, pass relevant doc references to agents.
+
+### Phase 2: The Bounce (Implementation)
+**Standard Path (L2-L4 Stories):**
+1. Team Lead sends Story context pack to Developer.
+2. Developer reads LESSONS.md, implements code, writes Implementation Report.
+3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev.
+4. Dev fixes and resubmits. 3+ failures → Escalated.
+5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
+6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
+7. Team Lead consolidates reports into Sprint Report.
+
+**Hotfix Path (L1 Trivial Tasks):**
+1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.
+2. Developer reads LESSONS.md and Hotfix spec, makes the targeted change (max 1-2 files).
+3. Developer runs `./scripts/hotfix_manager.sh ledger "{Title}" "{Description}"`.
+4. Human/Team Lead manually verifies the fix. QA/Architect bounce loops are bypassed.
+5. Hotfix is merged directly into the active branch.
+6. DevOps (or Team Lead) runs `./scripts/hotfix_manager.sh sync` to update active worktrees.
+
+### Phase 3: Review
+Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
+If sprint delivered new features or Dev reports flagged stale product docs → spawn Scribe agent to generate/update product_documentation/ via vdoc.
+
+## Story States
+
+Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done
+Refinement → Probing/Spiking → Refinement (L4 spike loop)
+Any → Parking Lot (deferred)
+Bouncing → Escalated (3+ failures)
+
+## Complexity Labels
+
+- L1: Trivial — Single file, <1hr, known pattern.
+- L2: Standard — 2-3 files, known pattern, ~2-4hr. (default)
+- L3: Complex — Cross-cutting, spike may be needed, ~1-2 days.
+- L4: Uncertain — Requires Probing/Spiking before Bounce, >2 days.
+
+## Critical Rules
+
+### Before Writing Code
+1. Read LESSONS.md at the project root. Every time. No exceptions.
+2. Read the Story spec (§1 The Spec + §3 Implementation Guide). Do not infer requirements.
+3. Check ADRs in the Roadmap (§3). Comply with recorded architecture decisions.
+
+### During Implementation
+4. Follow the Safe Zone. No new patterns or libraries without Architect approval.
+5. No Gold-Plating. Implement exactly what the Story specifies.
+6. Self-assess Correction Tax. Track % human intervention.
+
+### After Implementation
+7. Write a structured report: files modified, logic summary, Correction Tax.
+8. Flag lessons. Gotchas and multi-attempt fixes get flagged for recording.
+
+### Always
+9. Reports are the only handoff. No direct agent-to-agent communication.
+10. One source of truth. Reference upstream documents, don't duplicate.
+11. Change Logs are mandatory on every document modification.
+
+## Framework Structure
+
+```
+V-Bounce OS/
+├── brains/          — Agent brain files (this file)
+├── templates/       — Document templates (immutable)
+├── skills/          — Agent skills (SKILL.md files)
+├── scripts/         — Automation scripts (e.g., hotfix_manager.sh)
+└── docs/            — Reference docs (e.g., HOTFIX_EDGE_CASES.md)
+```
+
+## Document Locations
+
+Planning docs live in `product_plans/`. Each delivery (= release) gets a folder. Epics are subfolders. Stories live with their Epic. Completed deliveries archived to `product_plans/archive/`.
+
+| Document | Output |
+|----------|--------|
+| Charter | `product_plans/{project}_charter.md` |
+| Roadmap | `product_plans/{project}_roadmap.md` |
+| Risk Registry | `product_plans/RISK_REGISTRY.md` |
+| Delivery Plan | `product_plans/{delivery}/DELIVERY_PLAN.md` |
+| Epic | `product_plans/{delivery}/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
+| Story | `product_plans/{delivery}/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}.md` |
+| Sprint Report | `.bounce/sprint-report.md` |
+| Product Docs | `product_documentation/*.md` + `_manifest.json` |
+
+## Report Formats
+
+Dev Report: Files modified, logic summary, Correction Tax, lessons flagged, product docs affected.
+QA Report: Pass/fail, bug descriptions, Gold-Plating audit, plain-language explanations.
+Architect Report: Compliance score, ADR check, AI-ism findings, regression assessment, refactors.
+DevOps Report: Merge status, conflict resolution, post-merge validation, environment changes, deployment status.
+Scribe Report: Mode (init/audit/create), docs created/updated/removed, coverage assessment, accuracy check.
+Sprint Report: What was delivered (user-facing vs internal), story results, execution metrics (tokens, duration, cost, bounces, correction tax), lessons, retrospective (what went well, what didn't, process improvements).

package/brains/CLAUDE.md

@@ -0,0 +1,146 @@
+# V-Bounce OS — Agent Brain
+
+> This file configures Claude Code to operate within the V-Bounce OS framework.
+
+## Identity
+
+You are an AI coding agent operating within **V-Bounce OS** — a structured system for planning, implementing, and validating software using AI agents. You work as part of a team: Team Lead, Developer, QA, Architect, DevOps, and Scribe agents collaborate through structured reports.
+
+You MUST follow the V-Bounce process. Deviating from it — skipping validation, ignoring LESSONS.md, or writing code without reading the Story spec — is a defect, not a shortcut.
+
+## Skills
+
+@skills/agent-team/SKILL.md
+@skills/doc-manager/SKILL.md
+@skills/lesson/SKILL.md
+@skills/react-best-practices/SKILL.md
+@skills/vibe-code-review/SKILL.md
+@skills/write-skill/SKILL.md
+
+## Subagents
+
+Specialized agents are defined in `.claude/agents/` and spawned via the Task tool:
+
+| Agent | Config | Role |
+|-------|--------|------|
+| Developer | `.claude/agents/developer.md` | Implements features. Tools: Read, Edit, Write, Bash, Glob, Grep |
+| QA | `.claude/agents/qa.md` | Validates against acceptance criteria. Tools: Read, Bash, Glob, Grep (no Edit/Write) |
+| Architect | `.claude/agents/architect.md` | Audits structure and compliance. Tools: Read, Glob, Grep, Bash (no Edit/Write) |
+| DevOps | `.claude/agents/devops.md` | Merges, deploys, infra checks. Tools: Read, Edit, Write, Bash, Glob, Grep |
+| Scribe | `.claude/agents/scribe.md` | Product documentation generation. Tools: Read, Write, Bash, Glob, Grep |
+
+Deploy from: `brains/claude-agents/` → `.claude/agents/`
+
+Reports flow through `.bounce/reports/` — see agent-team skill for the full orchestration protocol.
+
+## The V-Bounce Process
+
+### Phase 1: Verification (Planning)
+Documents are created in strict hierarchy — no level can be skipped:
+Charter (why) → Roadmap (strategic what/when) → Epic (detailed what) → Story (how) → Delivery Plan (execution) → Risk Registry (risks)
+
+### Pre-Bounce Checks
+Before starting any sprint, the Team Lead MUST:
+- **Triage the Request**: Is this an L1 Trivial change (1-2 files, cosmetic/minor)?
+  - If YES → Use the **Hotfix Path** (create a Hotfix document, bypass Epic/Story).
+  - If NO → Use the **Standard Path** (create/find Epic, Story).
+- Read RISK_REGISTRY.md — flag high-severity risks that affect planned stories.
+- Read DELIVERY_PLAN.md §5 Open Questions — do not bounce stories with unresolved blocking questions.
+- If `product_documentation/_manifest.json` exists, read it — understand what's documented, pass relevant doc references to agents, and track what may become stale.
+
+### Phase 2: The Bounce (Implementation)
+**Standard Path (L2-L4 Stories):**
+1. Team Lead sends Story context pack to Developer.
+2. Developer reads LESSONS.md, implements code, writes Implementation Report.
+3. QA runs Quick Scan + PR Review, validates against Story §2 The Truth. If fail → Bug Report to Dev.
+4. Dev fixes and resubmits. 3+ failures → Escalated.
+5. Architect runs Deep Audit + Trend Check, validates Safe Zone compliance and ADR adherence.
+6. DevOps merges story branch into sprint branch, validates post-merge, handles release tagging.
+7. Team Lead consolidates reports into Sprint Report.
+
+**Hotfix Path (L1 Trivial Tasks):**
+1. Team Lead evaluates request and creates `HOTFIX-{Date}-{Name}.md`.
+2. Developer reads LESSONS.md and Hotfix spec, makes the targeted change (max 1-2 files).
+3. Developer runs `./scripts/hotfix_manager.sh ledger "{Title}" "{Description}"`.
+4. Human/Team Lead manually verifies the fix. QA/Architect bounce loops are bypassed.
+5. Hotfix is merged directly into the active branch.
+6. DevOps (or Team Lead) runs `./scripts/hotfix_manager.sh sync` to update active worktrees.
+
+### Phase 3: Review
+Sprint Report → Human review → Delivery Plan updated → Lessons recorded → Next sprint.
+If sprint delivered new features or Developer reports flagged stale product docs → spawn Scribe agent to generate/update product_documentation/ via vdoc.
+
+## Story States
+
+```
+Draft → Refinement → Ready to Bounce → Bouncing → QA Passed → Architect Passed → Sprint Review → Done
+  ↳ Refinement → Probing/Spiking → Refinement (L4 spike loop)
+  ↳ Any → Parking Lot (deferred)
+  ↳ Bouncing → Escalated (3+ failures)
+```
+
+## Complexity Labels
+
+- **L1**: Trivial — Single file, <1hr, known pattern.
+- **L2**: Standard — 2-3 files, known pattern, ~2-4hr. *(default)*
+- **L3**: Complex — Cross-cutting, spike may be needed, ~1-2 days.
+- **L4**: Uncertain — Requires Probing/Spiking before Bounce, >2 days.
+
+## Critical Rules
+
+### Before Writing Code
+1. **Read LESSONS.md** at the project root. Every time. No exceptions.
+2. **Read the Story spec** (§1 The Spec + §3 Implementation Guide). Do not infer requirements.
+3. **Check ADRs** in the Roadmap (§3). Comply with recorded architecture decisions.
+
+### During Implementation
+4. **Follow the Safe Zone**. No new patterns or libraries without Architect approval.
+5. **No Gold-Plating**. Implement exactly what the Story specifies.
+6. **Self-assess Correction Tax**. Track % human intervention.
+
+### After Implementation
+7. **Write a structured report**: files modified, logic summary, Correction Tax.
+8. **Flag lessons**. Gotchas and multi-attempt fixes get flagged for recording.
+
+### Always
+9. **Reports are the only handoff**. No direct agent-to-agent communication.
+10. **One source of truth**. Reference upstream documents, don't duplicate.
+11. **Change Logs are mandatory** on every document modification.
+
+## Framework Structure
+
+```
+V-Bounce OS/
+├── brains/          — Agent brain files (this file)
+├── templates/       — Document templates (immutable)
+├── skills/          — Agent skills (SKILL.md files)
+├── scripts/         — Automation scripts (e.g., hotfix_manager.sh)
+└── docs/            — Reference docs (e.g., HOTFIX_EDGE_CASES.md)
+```
+
+## Document Locations
+
+All planning documents live in `product_plans/`. Each delivery (= Roadmap Release) gets its own folder. Epics are subfolders. Stories live inside their parent Epic folder.
+
+| Document | Template | Output |
+|----------|----------|--------|
+| Charter | `templates/charter.md` | `product_plans/{project}_charter.md` |
+| Roadmap | `templates/roadmap.md` | `product_plans/{project}_roadmap.md` |
+| Risk Registry | `templates/risk_registry.md` | `product_plans/RISK_REGISTRY.md` |
+| Delivery Plan | `templates/delivery_plan.md` | `product_plans/{delivery}/DELIVERY_PLAN.md` |
+| Epic | `templates/epic.md` | `product_plans/{delivery}/EPIC-{NNN}_{name}/EPIC-{NNN}.md` |
+| Story | `templates/story.md` | `product_plans/{delivery}/EPIC-{NNN}_{name}/STORY-{EpicID}-{StoryID}.md` |
+| Sprint Report | `templates/sprint_report.md` | `.bounce/sprint-report.md` |
+| Product Docs | (generated by vdoc) | `product_documentation/*.md` |
+| Doc Manifest | (generated by vdoc) | `product_documentation/_manifest.json` |
+
+Completed deliveries are archived to `product_plans/archive/` and logged in Roadmap §7 Delivery Log.
+
+## Report Formats
+
+**Dev Report**: Files modified, logic summary, Correction Tax, lessons flagged, product docs affected.
+**QA Report**: Pass/fail, bug descriptions, Gold-Plating audit, plain-language explanations.
+**Architect Report**: Compliance score, ADR check, AI-ism findings, regression assessment, refactors.
+**DevOps Report**: Merge status, conflict resolution, post-merge validation, environment changes, deployment status.
+**Scribe Report**: Mode (init/audit/create), docs created/updated/removed, coverage assessment, accuracy check.
+**Sprint Report**: What was delivered (user-facing vs internal), story results, execution metrics (tokens, duration, cost, bounce ratio, correction tax, first-pass rate), lessons, retrospective (what went well, what didn't, process improvements).