npm package: @guydor/bvr
Description: BVR — AI-powered development platform with browser automation, orchestrated workflows, and intelligent code review
Latest version: 0.3.1

# BVR

**AI-powered development platform for Claude Code with structured workflows, browser automation, and intelligent code review.**

BVR adds 44 slash commands to Claude Code — giving you a structured 7-phase workflow, code review, QA, design audit, browser automation, and more.

## Install

```bash
npm install -g @guydor/bvr
```

This automatically registers all 42 slash commands in Claude Code. Restart Claude Code after install.

## Uninstall

```bash
node ~/.claude/bvr-uninstall.cjs
```

Removes the npm package, all `/bvr-*` slash commands, and cleans up after itself. Restart Claude Code after.

## Update

```bash
npm install -g @guydor/bvr@latest
```

Automatically refreshes all slash commands. Restart Claude Code after.

## Getting Started

After install, set your experience level:

```
/bvr-level
```

This personalizes your recommended workflow. You can change it anytime. All 44 commands are always available regardless of level.

Need a refresher? Run `/bvr-guide` to see your recommended commands.

## Choose Your Level

Pick the workflow that matches your experience. Each level is complete — you can build and ship software at any level.

---

### Beginner — "I describe what I want, AI builds it"

No coding knowledge needed. You describe features in plain English, BVR handles everything.

**Your workflow:**

```
1. /bvr-new-project     "I want to build a task manager app"
2. /bvr-auto             AI builds the entire thing autonomously
3. Done.
```

**Or step by step:**

```
Start of day:    /bvr-resume          Pick up where you left off
New feature:     /bvr-auto            "Add user authentication"
Small change:    /bvr-do              "Make the header blue"
Medium task:     /bvr-quick           "Add a contact form"
Lost?            /bvr-next            AI tells you what to do next
Check status:    /bvr-progress        See where you are
Remember idea:   /bvr-todo            "Add dark mode later"
End of day:      /bvr-pause           Save everything for tomorrow
Safety:          /bvr-guard           Prevent accidental damage
```

| Command | What it does |
|---------|-------------|
| `/bvr-new-project` | Set up a new project from scratch |
| `/bvr-auto` | Full autopilot — discusses, plans, builds, reviews, ships |
| `/bvr-do` | Just do it — "make the button bigger" |
| `/bvr-quick` | Small task with light guardrails |
| `/bvr-next` | "What should I do next?" |
| `/bvr-progress` | "Where are we?" |
| `/bvr-todo` | Remember something for later |
| `/bvr-pause` | Save work, come back later |
| `/bvr-resume` | Pick up where you left off |
| `/bvr-guard` | Maximum safety — prevents destructive actions |
| `/bvr-version` | Check installed version |
| `/bvr-level` | Change your experience level |
| `/bvr-guide` | Show recommended commands for your level |

---

### Technical — "I understand code, AI accelerates me"

You know software development. You want structured workflows, quality gates, and AI assistance at each step.

**Your workflow — building a feature:**

```
1. /bvr-discuss          Agree on what to build and how
2. /bvr-research         Investigate unknowns (skip if familiar)
3. /bvr-plan             Generate execution plan with dependency waves
4. /bvr-execute          Implement wave-by-wave
5. /bvr-review           Staff-engineer code review
6. /bvr-qa               Find bugs, fix them, write tests
7. /bvr-verify           User acceptance testing
8. /bvr-ship             Create PR, deploy
```

**Your workflow — fixing a bug:**

```
1. /bvr-debug            Root-cause analysis with evidence trail
2. /bvr-review           Verify the fix is solid
3. /bvr-ship             Ship the fix
```

**Your workflow — joining an existing project:**

```
1. /bvr-map-codebase     Understand the codebase
2. /bvr-new-project      Initialize BVR tracking
3. /bvr-discuss          Start your first feature
```

**Your workflow — daily routine:**

```
Start of day:    /bvr-resume           Continue from yesterday
During work:     /bvr-discuss → /bvr-plan → /bvr-execute → /bvr-review → /bvr-ship
End of day:      /bvr-report           Generate standup summary
End of sprint:   /bvr-stats            View project metrics
Milestone done:  /bvr-complete-milestone   Archive and tag
Next milestone:  /bvr-new-milestone    Begin next cycle
```

| Command | What it does | When to use |
|---------|-------------|-------------|
| `/bvr-discuss` | Capture decisions & requirements | Before any feature |
| `/bvr-research` | Investigate approaches & risks | Unfamiliar tech |
| `/bvr-plan` | Execution plan with dependency waves | After requirements clear |
| `/bvr-execute` | Implement wave-by-wave | After plan approved |
| `/bvr-review` | Staff-engineer code review | Before merging |
| `/bvr-verify` | User acceptance testing | After review passes |
| `/bvr-ship` | Create PR, deploy | Ready to merge |
| `/bvr-qa` | Find bugs, fix, write tests | After implementation |
| `/bvr-qa-only` | Bug report (read-only) | Audit without changes |
| `/bvr-debug` | Root-cause analysis | Something broke |
| `/bvr-browse` | Headless browser automation | Test UI, screenshots |
| `/bvr-new-milestone` | Start next version cycle | After shipping |
| `/bvr-complete-milestone` | Audit and archive | Milestone done |
| `/bvr-map-codebase` | Analyze existing codebase | Joining a project |
| `/bvr-report` | Session summary | Standups, handoffs |
| `/bvr-stats` | Project metrics | Sprint review |
| `/bvr-careful` | Warn before destructive commands | Near production |
| `/bvr-freeze` | Lock edits to one directory | Focused refactoring |
| `/bvr-unfreeze` | Remove edit restrictions | Done with focus |
| `/bvr-health` | Diagnostics + auto-repair | Something feels off |

---

### Expert — "I architect systems and own the full lifecycle"

You design architecture, run teams, and ship to production. These commands add cross-model review, design systems, engineering metrics, and strategic planning.

**Your workflow — new product:**

```
1. /bvr-office-hours         Pressure-test the product idea
2. /bvr-design-consultation  Create design system (tokens, components)
3. /bvr-new-project          Initialize with research + roadmap
4. /bvr-plan-ceo-review      Strategic scope review
5. /bvr-plan-eng-review      Architecture validation
6. /bvr-auto                 Build it
7. /bvr-design-review        Visual audit of implementation
8. /bvr-codex                Cross-model code review (Claude + OpenAI)
9. /bvr-ship                 Deploy
10. /bvr-document-release    Sync all documentation
```

**Your workflow — weekly cadence:**

```
Monday:     /bvr-resume → /bvr-progress      See where things stand
Daily:      /bvr-discuss → ... → /bvr-ship    Feature work
Friday:     /bvr-retro                         Engineering retrospective
Release:    /bvr-ship → /bvr-document-release  Ship + update docs
```

**Your workflow — production debugging:**

```
1. /bvr-guard                Enable safety mode
2. /bvr-setup-browser-cookies Import auth session
3. /bvr-browse               Reproduce in headless browser
4. /bvr-debug                Root-cause with evidence trail
5. /bvr-codex                Get OpenAI second opinion on fix
6. /bvr-review               Final review
7. /bvr-ship                 Hotfix PR
```

| Command | What it does | When to use |
|---------|-------------|-------------|
| `/bvr-plan-eng-review` | Architecture validation | Before approving designs |
| `/bvr-plan-ceo-review` | Strategic product review (4 modes) | Scope decisions |
| `/bvr-codex` | OpenAI second-opinion review | Cross-model validation |
| `/bvr-retro` | Engineering metrics + bottleneck analysis | Weekly retrospective |
| `/bvr-design-review` | Visual audit with dimensional scoring | After UI implementation |
| `/bvr-design-consultation` | Create design system from scratch | New project or rebrand |
| `/bvr-office-hours` | YC-style product reframing | Validating product direction |
| `/bvr-document-release` | Sync docs with shipped code | After merge |
| `/bvr-setup-browser-cookies` | Import auth cookies | Testing authenticated flows |
| `/bvr-profile` | Personalize BVR to your style | First-time setup |
| `/bvr-upgrade` | Update BVR preserving customizations | New version available |

## Features

- **7-Phase Pipeline** — Discuss, Research, Plan, Execute, Review, Verify, Ship with quality gates between each phase.
- **Wave-Based Parallelism** — Plans grouped into dependency-aware waves that execute in parallel.
- **Browser Automation** — 50+ headless browser commands with accessibility-tree refs. CSP-safe.
- **16 Specialized Agents** — Purpose-built agents for research, planning, execution, and verification.
- **44 Slash Commands** — Code review, QA, design audit, debugging, release automation, and more.
- **Context Management** — Thin orchestrator prevents context rot. Heavy work delegates to fresh subagent windows.
- **State via Markdown** — All state in human-readable Markdown with YAML frontmatter. Git-friendly, no database.

## Architecture

```
BVR/
├── core/          # Orchestration engine, state, config, phases
├── browse/        # Headless browser (50+ commands, ref system)
├── agents/        # 16 specialized agent definitions
├── skills/        # 44 slash command definitions
├── workflows/     # 20 orchestration workflows
├── templates/     # Document templates
├── hooks/         # Integration hooks (pre/post phase, pre-commit)
└── tests/         # Unit, e2e, and eval tests
```

See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical design.

## Development

```bash
git clone https://github.com/gd007/bvr.git
cd bvr
npm install
npm test
npm run build
```

## License

[MIT](./LICENSE)