mvp

name	mvp
description	Autonomous MVP builder — brainstorm, scaffold, build, and track web app prototypes
compatibility	Designed for Claude Code (subagent dispatch, worktree isolation, settings-based permissions); runs on other Agent Skills harnesses in Reduced Sequential Mode with single-session setup. Requires git; the agent-managed dev server additionally requires bash background execution.
argument-hint	<start|build|status|summary>
disable-model-invocation	true
effort	high
allowed-tools	Read Write Edit Grep Glob Bash(*) Agent AskUserQuestion WebSearch WebFetch TaskCreate TaskUpdate TaskGet TaskList

MVP Builder

Autonomous skill that brainstorms an app idea with the user, scaffolds the project, and builds a working prototype using AI agents (in parallel where the harness supports it).

Effort mode: high (set by /mvp for best results)
Override with /effort medium if preferred.

Mode Routing

Detect the mode from the user's arguments and delegate to the appropriate reference file.

Arguments: $ARGUMENTS (substituted by Claude Code; on harnesses without substitution, read the arguments from the invoking message)

Route to the correct mode (paths are relative to this skill's directory, which the harness announces when the skill loads):

1. If arguments are empty, whitespace-only, or start with "start":

   • Read references/start.md and follow those instructions

2. If arguments start with "build":

   • Read references/build.md and follow those instructions

3. If arguments start with "status":

   • Read references/status.md and follow those instructions

4. If arguments start with "summary":

   • Read references/summary.md and follow those instructions

5. If no recognized mode, show usage help:

   MVP Builder — Autonomous web app prototype builder
   
   Usage:
     /mvp start     Brainstorm an idea, choose tech stack, scaffold project
     /mvp build     Build the prototype (resumes from saved state)
     /mvp status    View current progress dashboard
     /mvp summary   Generate HTML analytics page
   
   Get started:
     /mvp start
   

---

Shared Conventions

All modes inherit these conventions. Mode-specific reference files build on top of them.

Structured Questions

Where these instructions say AskUserQuestion, use the harness's structured question tool if one is available (AskUserQuestion in Claude Code); otherwise ask the same question in plain text, list the options, and wait for the user's reply.

Subagent Orchestration

Where these instructions say to dispatch, spawn, or delegate work to agents (build mode's orchestration loop), use the harness's subagent tool if one is available (the Agent tool in Claude Code). Otherwise run Reduced Sequential Mode: you are both orchestrator and worker — execute each delegatable task inline, one at a time, following the same task brief you would have given the agent. In this mode:

• Locks are trivially satisfied (you are the only actor), but lock bookkeeping in state.json is still written.
• Per-task reports are still written to .mvp/agent-logs/ as self-reports, using the same JSON shape.
• analytics.agentSpawns counts real dispatches only — it stays 0 in this mode.
• Quality review still runs: a fresh, skeptical self-review pass against the same review instructions, recording the same JSON verdict.
• Concurrency limits and worktree isolation do not apply — there is nothing to parallelize or isolate.

State Directory

All MVP state is persisted in .mvp/ in the current working directory:

File/Folder	Purpose
.mvp/brainstorm.md	Source-of-truth: vision, scope, task tracking, agent log
.mvp/state.json	Machine-readable state for orchestration and analytics
.mvp/agent-logs/	Individual agent run reports (one per agent)
.mvp/research/	Research artifacts gathered during brainstorming
.mvp/resources/	Downloaded assets (images, icons, etc.)

Supported Tech Stacks

JavaScript Stack:

• Vite (latest) + TypeScript
• React 19.x
• TailwindCSS 4.x
• SQLite via better-sqlite3 / Drizzle ORM

Elixir Stack:

• Phoenix Framework (latest)
• LiveView for page rendering
• SQLite via Ecto SQLite3 adapter

Timestamps

All timestamps use ISO 8601 format: YYYY-MM-DDTHH:MM:SS (local time). Use the current date from the conversation context — NEVER hardcode dates.

Git Conventions

• Commit messages use prefix: mvp: [description]
• Auto-commit after each quality-reviewed task completion
• Phase completion gets a summary commit
• Final completion gets a wrap-up commit

Agent Communication Format

Subagents MUST return results as structured JSON (in Reduced Sequential Mode, write the same JSON shape as your own task report):

{
  "agentId": 1,
  "status": "success|partial|failed",
  "taskCompleted": "description of what was done",
  "filesModified": ["path/to/file1"],
  "filesCreated": ["path/to/new-file"],
  "dependenciesNeeded": ["package-name"],
  "processesStarted": [{"pid": 12345, "command": "npm run dev"}],
  "issues": ["any problems encountered"],
  "notes": "additional context"
}

Lock System

state.json tracks resource locks to prevent agent conflicts:

Lock	Protects
migrations	Database schema changes — one agent at a time
design	Global CSS, theme, design system files
dependencies	package.json / mix.exs modifications (main agent only)

Main Agent Responsibilities

The main agent (not subagents) ALWAYS handles:

• Installing/removing dependencies
• Starting/stopping dev servers
• Running database migrations
• Git add, commit, push operations
• Modifying .mvp/state.json and .mvp/brainstorm.md
• Managing process PIDs
• Acquiring/releasing locks

Task Progress Tracking

Use TaskCreate and TaskUpdate (if the harness provides task-list tools — Claude Code does) to mirror real-time visual progress in the harness UI. This complements the .mvp/state.json system, which is canonical and persists across sessions; without task tools, state.json alone is sufficient.

• Create tasks at the start of each build phase
• Update task status as work progresses (in_progress, completed)
• Both systems must stay in sync — update state.json AND task status together

---

Execute Now

Route to the correct mode based on the arguments above.