{"id":42264033,"url":"https://github.com/petbrains/mvp-builder","last_synced_at":"2026-04-15T07:07:48.758Z","repository":{"id":333472922,"uuid":"1034839115","full_name":"petbrains/mvp-builder","owner":"petbrains","description":"Document-Driven Development framework for Claude Code — structured specs, TDD cycles, feedback loops, and skills system","archived":false,"fork":false,"pushed_at":"2026-04-10T10:09:49.000Z","size":2051,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-10T12:18:16.095Z","etag":null,"topics":["ai-agents","automation","claude-code","code-generator","developer-tools","document-driven-development","llm","mvp","prompt-engineering","spec-driven","tdd"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/petbrains.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-09T04:52:13.000Z","updated_at":"2026-03-11T17:55:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/petbrains/mvp-builder","commit_stats":null,"previous_names":["petbrains/mvp-builder"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/petbrains/mvp-builder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petbrains%2Fmvp-builder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petbrains%2Fmvp-builder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petbrains%2Fmvp-builder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petbrains%2Fmvp-builder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/petbrains","download_url":"https://codeload.github.com/petbrains/mvp-builder/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/petbrains%2Fmvp-builder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31830232,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T18:05:02.291Z","status":"online","status_checked_at":"2026-04-15T02:00:06.175Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","automation","claude-code","code-generator","developer-tools","document-driven-development","llm","mvp","prompt-engineering","spec-driven","tdd"],"created_at":"2026-01-27T06:12:12.941Z","updated_at":"2026-04-15T07:07:48.743Z","avatar_url":"https://github.com/petbrains.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" width=\"180\" alt=\"MVP Builder\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eMVP Builder\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBuild MVPs with AI agent that verifies its own work\u003c/strong\u003e\u003cbr\u003e\n  Claude Code instructions for Document-Driven Development\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#the-approach\"\u003eApproach\u003c/a\u003e •\n  \u003ca href=\"#how-it-works\"\u003eHow It Works\u003c/a\u003e •\n  \u003ca href=\"#installation\"\u003eInstallation\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## The Problem\n\nAI coding agents are brilliant but unreliable:\n\n- 🎭 **They hallucinate** — write code that \"looks right\" but doesn't work\n- 🦥 **They cut corners** — stubs, mocks, \"TODO: implement later\"\n- 🧠 **They forget** — lose context between sessions\n- ✅ **They lie** — say \"done\" when work is half-finished\n\nYou end up debugging AI's mistakes instead of building your product.\n\n---\n\n## The Approach\n\nIf 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.\n\n### Core Principles\n\n**Document-Driven Development**  \nSpecifications generate code, not vice versa. Every feature starts as structured documentation (PRD → spec → UX → plan) before any implementation begins.\n\n**Verification Chain**  \nEach requirement gets a test. Each test gets an implementation. Each implementation gets reviewed. Nothing ships without passing the chain.\n\n```\nFR-XXX → TEST-XXX → IMPL-XXX → CHK → REV\n```\n\n**Feedback Loop**  \nAgents 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.\n\n**Rules + Skills + Agents**  \nRules (`.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.\n\n---\n\n## How It Works\n\n### Pipeline\n\n```mermaid\nflowchart LR\n    subgraph DEFINE [\"Define\"]\n        PRD[\"prd\"] --\u003e DSETUP[\"design-setup\"]\n        DSETUP --\u003e FEATURE[\"feature\"]\n        FEATURE --\u003e CLARIFY[\"clarify\"]\n        DSETUP -.-\u003e|\"Figma roundtrip\"| DSETUP\n    end\n    \n    subgraph DESIGN [\"Design\"]\n        CLARIFY --\u003e UX[\"ux\"]\n        UX --\u003e UI[\"ui\"]\n        UI --\u003e PLAN[\"plan\"]\n    end\n    \n    subgraph BUILD [\"Build\"]\n        PLAN --\u003e TASKS[\"tasks\"]\n        TASKS --\u003e VAL[\"validation\"]\n        VAL --\u003e SETUP[\"feature-setup\"]\n        SETUP --\u003e TDD[\"feature-tdd\"]\n        TDD --\u003e REVIEW[\"review\"]\n        REVIEW --\u003e|BLOCKED| FIX[\"feature-fix\"]\n        FIX --\u003e REVIEW\n    end\n    \n    subgraph SHIP [\"Ship\"]\n        REVIEW --\u003e|PASSED| MEMORY[\"memory\"]\n    end\n```\n\n### Phase 1: Define\n\nTransform product idea into structured specifications.\n\n| Command / Agent | Output | Purpose |\n|---------|--------|---------|\n| `/docs:prd` | `PRD.md`, `references/` dir | Product vision, audience, core problem |\n| `design-setup` | `references/design-system.md`, `tokens/`, `style-guide.md` | Normalize design references, extract from Figma |\n| `/docs:feature` | `spec.md`, `FEATURES.md` | Feature specs with requirements (FR-XXX, UX-XXX) |\n| `/docs:clarify` | Updated `spec.md` | Resolve ambiguities through targeted questions |\n\n**After `/docs:prd`**: Add supplementary materials to `ai-docs/references/` — design systems, tokens, schemas, API contracts, style guides, screenshots. Run `design-setup` agent to normalize raw generator output.\n\n**Figma roundtrip** (optional): Run `design-setup [figma-url]` to extract tokens and screens from Figma. Refine in Figma, then re-run `design-setup [figma-url]` to pull changes back. Repeat until design is locked.\n\n### Phase 2: Design\n\nConvert specifications into technical architecture.\n\n| Command | Output | Purpose |\n|---------|--------|---------|\n| `/docs:ux` | `ux.md` | User flows, states, error handling, accessibility |\n| `/docs:ui` | `ui.md` | Component trees, DS mapping, layout structure |\n| `/docs:plan` | `plan.md`, `data-model.md`, `contracts/`, `setup.md` | Architecture, entities, API specs, environment |\n\n### Phase 3: Build\n\nExecute implementation through TDD cycles with self-verification.\n\n| Command / Agent | Output | Purpose |\n|-----------------|--------|---------|\n| `/docs:tasks` | `tasks.md` | INIT tasks + TDD cycles (TEST-XXX → IMPL-XXX) |\n| `/docs:validation` | `validation/*.md` | Checklists with traceable checkpoints (CHK) |\n| `feature-setup` | Infrastructure code | Execute INIT tasks, scaffold project |\n| `feature-tdd` | Feature code + tests | RED-GREEN cycles, atomic commits |\n| `/docs:review` | `feedback.md` | Verify implementation, generate findings (REV-XXX) |\n| `feature-fix` | Fixed code | Apply fixes one error at a time |\n\n**Review Loop**: If review status is BLOCKED → `feature-fix` → `/docs:review` → repeat until PASSED.\n\n### Phase 4: Ship\n\nFinalize and document completed implementation.\n\n| Command | Output | Purpose |\n|---------|--------|---------|\n| `/docs:memory [feature-path]` | `ai-docs/README.md` | Add feature to code map, rebuild dependency graph |\n| `/docs:memory` | `ai-docs/README.md` | Rescan entire project, capture all changes |\n\n**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.\n\n### Agents\n\nSpecialized agents execute tasks across pipeline phases:\n\n**Define phase:**\n\n| Agent | Role | When to use |\n|-------|------|-------------|\n| `design-setup` | Normalize design references, extract Figma | When user adds design references to `ai-docs/references/` or provides a Figma URL |\n\n**Build phase:**\n\n| Agent | Role | When to use |\n|-------|------|-------------|\n| `feature-setup` | Scaffold infrastructure | After `/docs:validation`, executes INIT-XXX tasks |\n| `feature-tdd` | TDD implementation | After setup, runs RED-GREEN cycles |\n| `feature-fix` | Apply review fixes | When review status = BLOCKED, fixes one error at a time |\n\n### Rules \u0026 Skills\n\n**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.\n\n| Rule | Scope | Paths |\n|------|-------|-------|\n| `git.md` | Branch naming, commits, secret protection | Always |\n| `authentication.md` | Auth library decisions per platform | Always |\n| `backend.md` | ORM, validation, API design, logging | `**/prisma/**`, `**/api/**`, `**/*.py` |\n| `frontend.md` | Next.js, Tailwind, testing, SSR | `**/*.tsx`, `**/*.jsx`, `**/*.css` |\n| `design.md` | Color, typography, animation, accessibility | Always |\n| `docker.md` | Multi-stage builds, dev compose | Always |\n| `code-quality.md` | Error handling, type design, simplification | Always |\n| `ios.md` | Swift style, concurrency, SwiftUI, SwiftData | `**/*.swift`, `**/*.xcodeproj/**` |\n\n**Skills** (`.claude/skills/`) are on-demand expertise — loaded by agents when the task requires specific domain knowledge.\n\nEach skill contains:\n- Instructions for a specific domain (analysis, documentation, git workflow)\n- Decision rules with explicit conditions\n- Tool permissions and constraints\n\nAdd new standards: create a rule file in `.claude/rules/`.  \nAdd new expertise: create a skill folder in `.claude/skills/`.\n\n---\n\n## Document Structure\n\nGenerated by MVP Builder:\n\n```\nai-docs/\n├── PRD.md                      # Product vision\n├── FEATURES.md                 # Feature index  \n├── README.md                   # Code map (navigation for agents)\n├── references/                 # Design systems, tokens, schemas, style guides, screens, API contracts\n└── features/\n    └── [feature-name]/\n        ├── spec.md             # Requirements (FR-XXX, UX-XXX)\n        ├── ux.md               # User flows and states\n        ├── ui.md               # Component trees, DS mapping, layout\n        ├── plan.md             # Architecture decisions\n        ├── research.md         # Technical research and rationale\n        ├── data-model.md       # Entities and validation\n        ├── setup.md            # Environment config\n        ├── contracts/          # API specifications\n        ├── tasks.md            # TDD execution tasks\n        ├── validation/         # Verification checklists\n        └── feedback.md         # Review findings\n```\n\n---\n\n## Installation\n\nNavigate to your project directory, then run:\n\n**macOS, Linux, WSL:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/petbrains/mvp-builder/main/scripts/install.sh | bash\n```\n\n**Windows PowerShell:**\n\n```powershell\nirm https://raw.githubusercontent.com/petbrains/mvp-builder/main/scripts/install.ps1 | iex\n```\n\nThis installs:\n- `.claude/` — commands, agents, skills, rules\n- `CLAUDE.md` — agent identity and execution rules\n- `.mcp.json` — MCP server configuration\n\nStart with `/docs:prd` to define your product.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetbrains%2Fmvp-builder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpetbrains%2Fmvp-builder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpetbrains%2Fmvp-builder/lists"}