wheee

Wheee Protocol

From Vibe Coding to Vibe Engineering.

Vibe Coding builds fast. It also breaks fast — scope creep, no quality gates, architecture that collapses at scale. Wheee gives AI-assisted development the structure it needs without killing the speed.

This is a Claude Code plugin that turns "just build it" into a repeatable, quality-gated engineering process. You still move fast. But now you know where you're going before you start, what you're allowed to touch, and when it's actually done.

The Problem

AI can write code faster than ever. But faster code isn't better code:

• Features get built without understanding blast radius
• Nobody asks "what does done look like?" before starting
• Quick fixes bypass review and break unrelated features
• Planning documents exist once, then drift from reality
• There's no quality gate between "it works on my machine" and "it's shipped"

What Wheee Does

Think first. Then build. Then verify. Every time. Enforced by tooling, not willpower.

B.L.A.S.T. — The 5-Phase Cycle

Every piece of work follows the same structured cycle:

Phase	What Happens
Blueprint	Discovery questions define scope, constraints, and success criteria. What are we building? For whom? What does done look like?
Link	Dependency mapping and connectivity checks. The FIP (Functionality Isolation Protocol) maps your blast radius before you touch code.
Architect	System design, technical planning, execution plan with tasks and acceptance criteria.
Stabilize	Implementation + verification. Tests, linting, smoke tests on protected areas.
Trigger	Quality gate, planning doc sync, deployment. Nothing ships without passing.

The Blueprint Phase Is the Secret Weapon

Before a single line of code is written, Wheee asks the questions that matter:

/wheee:new-project

• What problem does this project solve?
• Who is the target user?
• What is the core feature set (MVP)?
• What technology stack and constraints exist?
• What are the success criteria?

For existing projects, /wheee:discuss-phase gathers context through adaptive questioning — drilling into exactly what a phase needs to achieve, what the inputs are, what the risks are, and what "done" means.

This is where scope gets defined. Where features get shaped before they get built. Where a vague "add authentication" becomes a concrete plan with boundaries.

Three Execution Modes

The plan is always the same. Only execution differs.

Guided Mode — You Drive

You approve each step. See what's happening. Learn the codebase.

/wheee:init                    # Set up planning structure
/wheee:new-project             # Blueprint: discovery questions
/wheee:plan-phase 1            # Create execution plan
/wheee:execute-phase 1         # Build step by step
/wheee:quality-gate            # Verify before shipping

Good for: new projects, sensitive changes, learning a codebase, onboarding.

Autonomous Mode — Agent Teams Execute

After planning, an Agent Team of 6 specialists handles the phase independently.

/wheee:init                    # Same planning
/wheee:new-project             # Same discovery
/wheee:plan-phase 1            # Same plan
/wheee:orchestrate 1           # Agent Team takes over

The team self-coordinates:

• Researcher gathers context and maps dependencies
• Architect designs the solution (plan mode, can't write code)
• Developer implements in an isolated worktree
• Reviewer runs quality gates and security scans
• Tester validates acceptance criteria
• Orchestrator coordinates and reports results

Good for: well-understood domains, parallelizable work, scaling output.

Design Mode — UX Before Code

Start with the user experience, not the architecture. Mode D lets you explore UI/UX concepts, wireframes, and interaction flows before any technical planning begins.

/wheee:design                  # Start a UX/UI design round
/wheee:convert                 # Turn design findings into S/M/L phases

Design Mode produces UX artifacts — screens, flows, component inventories. When the design is solid, /wheee:convert transforms those findings into concrete technical phases with tasks and acceptance criteria. The design drives the engineering, not the other way around.

The Design Critic

In autonomous mode, the Critic agent evaluates every design output against strict criteria — visual hierarchy, consistency, accessibility, spacing, typography, contrast ratios. It uses browser tools (Playwright, Chrome Extension, Preview Server) to take screenshots and inspect actual rendered CSS.

The Critic scores each criterion 0-10 and gives a verdict: PASS, ITERATE, or RETHINK. No design moves to implementation without passing.

Custom criteria? Drop a .planning/DESIGN-CRITERIA.md and the Critic uses your rules instead of the defaults.