MVP Builder

Build MVPs with AI agent that verifies its own work
Claude Code instructions for Document-Driven Development

Approach • How It Works • Installation

The Problem

AI coding agents are brilliant but unreliable:

• 🎭 They hallucinate — write code that "looks right" but doesn't work
• 🦥 They cut corners — stubs, mocks, "TODO: implement later"
• 🧠 They forget — lose context between sessions
• ✅ They lie — say "done" when work is half-finished

You end up debugging AI's mistakes instead of building your product.

The Approach

If the agent performs poorly, the task description is lacking. AI models are strong reasoners but unreliable workers — they hallucinate, cut corners, and forget previous context. The fix is not just better prompts but structured specifications that require verifiable outputs.

Core Principles

Document-Driven Development
Specifications generate code, not vice versa. Every feature starts as structured documentation (PRD → spec → UX → plan) before any implementation begins.

Verification Chain
Each requirement gets a test. Each test gets an implementation. Each implementation gets reviewed. Nothing ships without passing the chain.

FR-XXX → TEST-XXX → IMPL-XXX → CHK → REV

Feedback Loop
Agents check their own work. Review finds issues → feedback.md captures them → fix agent resolves → review verifies. AICODE-* markers track what's resolved and what's still relevant. Context stays clean.

Rules + Skills + Agents
Rules (.claude/rules/) provide always-loaded standards — code style, git workflow, platform constraints. Skills provide on-demand expertise — loaded when the task requires specific domain knowledge. Agents execute specific workflows — TDD cycles, review, fixes. Add expertise by adding files, not rewriting agents.

How It Works

Pipeline

flowchart LR
    subgraph DEFINE ["Define"]
        PRD["prd"] --> DSETUP["design-setup"]
        DSETUP --> FEATURE["feature"]
        FEATURE --> CLARIFY["clarify"]
        DSETUP -.->|"to Figma"| DGEN["design-generate"]
        DGEN -.->|"from Figma"| DSETUP
    end
    
    subgraph DESIGN ["Design"]
        CLARIFY --> UX["ux"]
        UX --> UI["ui"]
        UI --> PLAN["plan"]
    end
    
    subgraph BUILD ["Build"]
        PLAN --> TASKS["tasks"]
        TASKS --> VAL["validation"]
        VAL --> SETUP["feature-setup"]
        SETUP --> TDD["feature-tdd"]
        TDD --> REVIEW["review"]
        REVIEW -->|BLOCKED| FIX["feature-fix"]
        FIX --> REVIEW
    end
    
    subgraph SHIP ["Ship"]
        REVIEW -->|PASSED| MEMORY["memory"]
    end

Phase 1: Define

Transform product idea into structured specifications.

After /docs:prd: Add supplementary materials to ai-docs/references/ — design systems, tokens, schemas, API contracts, style guides, screenshots. Run /docs:design-setup to normalize raw generator output.

Figma roundtrip (optional): design-generate pushes HTML references into Figma for designer review. After refinement in Figma, run /docs:design-setup [figma-url] to extract changes back. Repeat until design is locked.

Phase 2: Design

Convert specifications into technical architecture.

Phase 3: Build

Execute implementation through TDD cycles with self-verification.

Review Loop: If review status is BLOCKED → feature-fix → /docs:review → repeat until PASSED.

Phase 4: Ship

Finalize and document completed implementation.

Two modes: with feature path — adds the feature entry and rebuilds the graph. Without arguments — full project rescan for changes made outside feature scope (refactoring, new shared modules, deleted files). Feature list is preserved, only the dependency graph is rebuilt from scratch.

Agents

Specialized agents execute tasks across pipeline phases:

Define phase:

Build phase:

Rules & Skills

Rules (.claude/rules/) are always-loaded standards — loaded automatically like CLAUDE.md. Platform-specific rules use paths frontmatter to load only when working with matching files.

Skills (.claude/skills/) are on-demand expertise — loaded by agents when the task requires specific domain knowledge.

Each skill contains:

• Instructions for a specific domain (analysis, documentation, git workflow)
• Decision rules with explicit conditions
• Tool permissions and constraints

Add new standards: create a rule file in .claude/rules/.
Add new expertise: create a skill folder in .claude/skills/.

Document Structure

Generated by MVP Builder:

ai-docs/
├── PRD.md                      # Product vision
├── FEATURES.md                 # Feature index  
├── README.md                   # Code map (navigation for agents)
├── references/                 # Design systems, tokens, schemas, style guides, screens, API contracts
└── features/
    └── [feature-name]/
        ├── spec.md             # Requirements (FR-XXX, UX-XXX)
        ├── ux.md               # User flows and states
        ├── ui.md               # Component trees, DS mapping, layout
        ├── plan.md             # Architecture decisions
        ├── research.md         # Technical research and rationale
        ├── data-model.md       # Entities and validation
        ├── setup.md            # Environment config
        ├── contracts/          # API specifications
        ├── tasks.md            # TDD execution tasks
        ├── validation/         # Verification checklists
        └── feedback.md         # Review findings

Installation

Navigate to your project directory, then run:

macOS, Linux, WSL:

curl -fsSL https://raw.githubusercontent.com/petbrains/mvp-builder/main/scripts/install.sh | bash

Windows PowerShell:

irm https://raw.githubusercontent.com/petbrains/mvp-builder/main/scripts/install.ps1 | iex

This installs:

• .claude/ — commands, agents, skills, rules
• CLAUDE.md — agent identity and execution rules
• .mcp.json — MCP server configuration

Start with /docs:prd to define your product.