version: "1.0.1" name: mvp description: | Meta-orchestrator for going from a product idea to a demo-able MVP fast. Drives the full flow: brainstorming → PRD visual confirmation (user gate) → template lookup → MVP-flavored plan → single-subagent execution. Optimized for time-to-first-demo, not production quality — no TDD, no per-task review loops, no hardening. Use INSTEAD OF superpowers:brainstorming when the user is starting a new product from scratch — this skill calls brainstorming internally, then chains in a PRD confirmation phase, template discovery, plan writing, and execution. Triggers: "/mvp", "我要做 app", "想做產品", "想做一個 app", "做個 MVP", "build a product", "build an app from scratch", "MVP from scratch", "start a new app", "new product".

MVP Orchestrator

Codex host guard

Before any other action, check whether CODEX_THREAD_ID is set. If it is, stop before creating product artifacts, worktrees, commits, or subagent work. This release supports the MVP orchestrator only on Claude Code; tell the user its Codex engine is not shipped yet and to run the workflow there instead.

Drives the full new-app / new-product flow with one explicit charter: get to first demo fast. Tests, edge cases, accessibility, i18n, and refactor passes are deferred — if the user wants those later they invoke solopreneur:autopilot on the same plan.

This skill is orchestration only — it does NOT reimplement brainstorming or planning. It chains the right skills in the right order, inserts a template lookup between brainstorming and plan writing, and runs execution with a single implementer subagent under the MVP Charter (rather than via superpowers:executing-plans / superpowers:subagent-driven-development, which both enforce TDD discipline that kills demo velocity).

Flow

0. Verify dependencies        (superpowers + ≥1 *-app-templates)
1. superpowers:brainstorming  (clarify needs + classify platform)
2. PRD visual confirmation    (render spec via /preview, user-gated)
3. Template lookup            (find matching *-app-templates; PRD↔template decision)
4. superpowers:writing-plans  (MVP-flavored plan, demo-velocity)
5. Execute the plan (MVP)     (single implementer subagent, commit per step)

MVP Charter

The single source of truth for the demo-velocity tradeoffs. Step 4 passes the Plan-writing rules to superpowers:writing-plans; Step 5 passes the Execution rules and BLOCKED handling to the implementer subagent. Keep both copies in sync by referencing this section, not by restating.

PRD visual confirmation (Step 2) is a user gate of the same nature as

Step 1's. Both the markdown spec (source of truth) and the confirmed

PRD are handed to writing-plans (Step 4). The Execution rules

(Step 5) are unchanged — the PRD is pre-execution direction

confirmation; it does not alter the demo-velocity execution discipline.

Plan-writing rules (consumed by Step 4)

• Each task = a visible slice the user can see in the app / simulator.
• Skip these categories entirely — they're for a later hardening

pass, not MVP:

• Test tasks (no unit / integration / UI tests in the plan)
• Error-handling tasks (edge cases → TODO comments in code, not

plan tasks)

• Loading / empty / error state tasks
• Accessibility / i18n tasks
• Performance / refactor / cleanup tasks
• Acceptance criteria for the whole plan: **"user can demo the core

action end-to-end"**, not "all tests pass".

• Templates already encode baseline architecture — don't re-derive

what the template provides; reference it.

Execution rules (consumed by Step 5)

• No TDD. Don't write tests. After each step, run the app /

simulator manually and check the happy path works — that is the verification.

• Edge cases → `TODO` comments, in the language's native syntax:

// TODO: handle X for Swift / Kotlin / JS / TS; # TODO: handle X for Python / Ruby / shell / YAML. Final-report grep uses TODO: so both forms surface.

• Loading / empty / error states → stub or skip. Simplest possible

fallback; no spinners, no skeletons, no retry logic.

• No refactor passes, no cleanup commits. Ship the first working

version of each slice.

• Trust the template. Copy reference files as-is; only customize

where the plan explicitly calls for it.

• Ambiguity → simplest path forward. Don't pause to ask unless

genuinely BLOCKED (see below).

• Stay within the worktree path passed in handoff. Don't modify

files outside it (no ~/.claude/, sibling repos, global config).

First action when dispatched into a fresh worktree (created by isolation: "worktree"): the auto-created branch is worktree-agent-xxx, not the target branch. Rename it before doing anything else:

git branch -m {TARGET_BRANCH}
git branch --show-current  # confirm output equals {TARGET_BRANCH}

If the rename fails or the verification doesn't match, stop immediately and report (this is BLOCKED — see handling below). Same pattern as solopreneur:autopilot's pr-subagent-template.md.

If already in a worktree (orchestrator didn't pass isolation: "worktree"), skip the rename — assume the caller put you on the right branch.

Commit policy: one commit per plan step.

• After each step's implementation works (manual verify), commit and

push. Each step is an independently revertible slice.

• Commit message: feat(mvp): <step name>: <one-line outcome>.
• **Before the first commit, re-verify git branch --show-current

equals {TARGET_BRANCH} and is not main / master. Abort if mismatch — never push to a branch you didn't start on.**

• First push of the run: use git push -u origin {TARGET_BRANCH}

to set upstream. Path A always needs this (fresh branch, no tracking). Path B may already track origin — try plain git push first; if it fails with "has no upstream branch", fall back to git push -u origin {TARGET_BRANCH}.

• Subsequent pushes: plain git push.

BLOCKED handling

A step is BLOCKED only when an action genuinely cannot proceed: missing credential, broken toolchain, plan step incoherent against current state, external service unreachable. Ambiguity that admits a "simplest path" is not BLOCKED.

• Subagent on BLOCKED: commit any working partial slice first, then

return a structured report listing (a) last completed commit SHA, (b) the blocking step, (c) what's needed to unblock. Do not attempt workarounds that diverge from the plan.

• Orchestrator on BLOCKED return: surface the report to the user,

do not re-dispatch automatically. User decides whether to resume, amend the plan, or abort.

Stopping condition

The user can run the app / simulator and demo the core demo action captured in Step 1 end-to-end. Stop there. No polishing, no hardening, no nice-to-haves.

Step 0: Verify dependencies

Required (check via the available-skills list in the system-reminder):

• superpowers:brainstorming
• superpowers:writing-plans

Co-packaged in `solopreneur` (always present alongside this skill — no runtime check needed): solopreneur:preview (used by Step 2).

Expected (≥1): any skill matching *-app-templates (e.g. ios-dev:ios-app-templates, ai-engineer:ai-app-templates).

Missing required skill → stop and tell the user what to install. No *-app-templates → continue with a warning that the plan will be freeform (no template baseline).

Step 1: Brainstorming

Invoke superpowers:brainstorming via the Skill tool. Follow it fully — do not short-circuit.

When brainstorming exits, capture:

• One-paragraph product description
• Platforms as a list (iOS / Android / web / AI backend) —

usually one, sometimes multiple (e.g. iOS app + AI backend)

• The core demo action — the single thing the user wants to show

someone at the end ("take a photo and see what Vision detected"). This becomes the stopping condition for Step 5.

• Key features and constraints (separated from "nice-to-haves")

Confirm explicitly with the user before continuing: "This is MVP mode — demo-only, no tests, no hardening. Edge cases get TODO markers. If you want production-grade, abort here and run the standard superpowers flow or solopreneur:autopilot instead."

Proceed only on explicit confirmation.

Step 2: PRD visual confirmation

Brainstorming produced a committed markdown spec — the source of truth. This step renders it as an interactive visual PRD so the user confirms UI/UX, data shape, flow, and business logic before any template or plan work. For a single-implementer, no-review-loop MVP run, a wrong direction caught here is far cheaper than one caught after execution. This is a deliberate velocity tradeoff: the PRD round is heavier than plain brainstorming, but it de-risks the unsupervised execution that follows.

Inputs: the brainstorming markdown spec (source of truth) plus the Step 1 captures (product description, platforms, core demo action, features vs nice-to-haves).

1. Invoke solopreneur:preview via the Skill tool. Pass the markdown spec

as the source content and explicit PRD rendering instructions: do not render a markdown wall — present it the most graspable way, and it MUST cover these four (form follows content otherwise):

• UI/UX — wireframe / mockup of the core screens, especially the

core demo action flow (use /preview's mock-* / mockup recipes).

• Data structure — conceptual entity / relationship + key data

flow as a Mermaid diagram. Conceptual level only — no schema DDL, no file layout. Keeping it conceptual is what keeps the PRD template-agnostic (see Step 3's divergence handling).

• Flow diagram — user flow / business-logic flow as Mermaid.
• Business logic — the rules in skimmable form (tables / callouts).

1. Override `/preview`'s in-repo commit behavior for this run. At this

point /mvp may be on the product repo's main (Path A — no feature branch yet, Step 5 creates it) or in an existing feature-branch worktree (Path B). To keep the defer uniform across both paths — and because committing to product main is forbidden in the Path A case — instruct /preview: do not commit the proposal, do not modify .gitignore. Generate + deploy (or local fallback) only.

Where the PRD lands — follow /preview's resolved layout; do not invent one:

• Library v2 (when present): if the nearest .solopreneur.json with

a preview block resolves, content goes under <root>/active/<id>/ with a preview.json sidecar. Publish via the preview skill's Library path (deploy-library.mjs / /preview Library workflow) — not a new flat date-slug dir as the default.

• No v2 config: fall back to /preview's setup or legacy path

(e.g. a date-slug dir under the skill's resolved parent such as docs/preview/<date>-<slug>/). Follow the preview skill; do not invent a layout.

The PRD stays uncommitted in the working tree. Record that path — Step 5 commits it onto the feature branch.

1. Iterate using /preview's native comment-overlay + revision loop until

the user is satisfied. Under Library v2 the shared overlay is injected at build time — still use the skill's revision loop; do not teach copying comment-overlay.js into every item as the happy path.

1. PRD-complete gate. Explicitly ask: "PRD discussion complete?

Confirming moves to template lookup." Mirror Step 1's confirmation gate — proceed only on explicit confirmation.

1. Reconcile the markdown spec. Visual iteration almost always changes

requirements; fold those changes back into the brainstorming markdown spec so it stays the source of truth. It remains uncommitted in the working tree; Step 5 commits it alongside the PRD.

Carry-forward: the PRD dir path and the (updated, still-uncommitted) markdown spec path, both consumed by Step 5.

Step 3: Template lookup

Discovery is convention-based, not hardcoded: for each platform captured in Step 1, look for <plugin>:<platform>-app-templates in the available-skills list. Examples:

Iterate over the platform list:

1. Look up the matching *-app-templates skill in the available-skills

list. Not installed → warn user, mark this platform as no-template, continue to the next platform.

1. Invoke the template skill via the Skill tool. The template skill

browses its catalog and returns a candidate (or none).

1. Present the candidate to the user:

• Match → record template name + the baseline path the template

skill returned (don't assume a specific layout — the template skill owns its file structure).

• No match → continue without a template for this platform.
• Partial match → discuss with the user whether to adapt the

template or go freeform.

PRD ↔ template divergence (decision sub-step). When a candidate template's technical approach diverges from the confirmed PRD (e.g. the PRD specifies an external OpenAI API but the template uses an on-device Foundation Model):

• Product / UX / business logic: the PRD always wins. A template must

never silently reshape the product; if it can't conform, that part goes freeform.

• Technical approach / data structure / provider: the PRD is the

default. But if the template offers a materially faster path with a different approach, surface the divergence explicitly and ask the user: (a) adapt the PRD to the template's approach to gain template velocity, or (b) keep the PRD's approach and hand-build that part freeform. The user decides consciously. If they pick (a), fold the change back into the markdown spec and note it in the PRD.

Recovery paths: if the template skill errors, hits a tool restriction, or the user aborts mid-selection, record "no template" for that platform and proceed. Do not silently retry.

Step 4: Writing the plan (MVP-flavored, demo-velocity)

Invoke superpowers:writing-plans via the Skill tool. Pass the Step 3 records (per-platform template name + baseline path) as context in the invocation prompt — writing-plans has no formal baseline parameter, so list them inline. Also pass the confirmed PRD (its path, and that it is the visual rendering of the spec) alongside the markdown spec and the per-platform template records.

Also pass the MVP Charter's Plan-writing rules (see top section) verbatim to writing-plans so the plan it produces is demo-flavored, not production-flavored.

If templates were found:

• Open the plan with each matched template's architectural baseline.
• Reference the baseline path the template skill returned (one section

per platform when multiple templates apply).

• Layer only the MVP-specific user-visible requirements on top.

If no templates were found:

• Write a freeform MVP plan from the brainstorm output.
• State explicitly that no template was reused and that the plan is

MVP-flavored (so a future hardening pass knows what's missing).

Step 5: Execute the plan (MVP mode)

Before executing, stop and get explicit user approval of the finalized plan. Do not assume the Step 4 draft is approved.

5a. Decide target branch + isolation

This is the orchestrator's responsibility — get it wrong and the subagent self-aborts on the branch rename. Two paths:

Path A: orchestrator is on `main` (no feature branch yet)

• Derive a new, unique feature branch name from the product

(e.g. feature/mvp-photo-analyze). Confirm it doesn't exist locally or on origin — both checks matter, because a stale remote branch with the same name would block git push -u later: `` git fetch origin git rev-parse --verify <name> # must fail (no local) git ls-remote --exit-code origin refs/heads/<name> # must fail (no remote) `` If either succeeds, pick a different name (e.g. append a short suffix).

• Pass that name as {TARGET_BRANCH} and use isolation: "worktree"

so the Agent tool creates a fresh worktree on an auto-generated branch; the subagent renames it to {TARGET_BRANCH} as its first action (see Charter).

Path B: orchestrator is already on a feature-branch worktree

• Use the current branch as {TARGET_BRANCH}. The branch already

exists and may already be checked out here — that's fine because the subagent runs in the same worktree (no isolation, no rename).

• Dispatch without isolation. The Charter's "First action when

dispatched into a fresh worktree" block is skipped.

Never pass an existing branch as {TARGET_BRANCH} together with isolation: "worktree" — the rename would fail (branch already exists, possibly checked out elsewhere).

5a-bis. Bring the deferred PRD + spec into git

The PRD dir and the updated markdown spec sit uncommitted in the working tree of the checkout where Step 2 ran (Path A: main; Path B: the existing feature worktree). Step 2 deferred their commit. They must land on {TARGET_BRANCH}:

• Path A (isolation: "worktree", fresh worktree on an auto branch):

the PRD/spec files were created in the original main checkout, not the new worktree — and the worktree does not exist until the Agent tool creates it at dispatch time, so the orchestrator cannot copy into it beforehand. Instead, the orchestrator passes the absolute source paths of the PRD dir + updated markdown spec (in the original main checkout) in the handoff prompt. The subagent's first action after the branch rename — before any plan step — is to copy them into its own worktree (resolved via git rev-parse --show-toplevel) and make a dedicated docs(mvp): PRD + spec commit that includes them. Library v2: shared overlay is injected at build time — do not copy comment-overlay.js into every item or add **/comment-overlay.js to .gitignore as the happy path. Legacy / transition only: if Step 2 used /preview's legacy flat layout and would have appended **/comment-overlay.js to .gitignore (deferred from Step 2), include that line in this commit.

• Path B (same worktree, no isolation): the PRD/spec are already in

this worktree; commit them on the feature branch as the first commit. Same Library-vs-legacy rule as Path A for any deferred .gitignore line.

• Path A cleanup (mandatory). Copying into the worktree does not remove

the originals — without this the run leaves product main dirty with stale PRD/spec (and, under legacy layout only, per-item overlay) files, blocking later main-branch work. After the subagent confirms the docs(mvp): PRD + spec commit is pushed, the orchestrator restores the original main checkout to clean: delete the (untracked) PRD dir and git checkout -- <markdown-spec-path> to discard the uncommitted Step 2 reconcile edits. The authoritative reconciled copy now lives on {TARGET_BRANCH} and returns to main via the eventual PR merge. Path B needs no cleanup — the files are already in the feature worktree where they belong.

5b. Dispatch

Dispatch a single implementer subagent via the Agent tool:

• subagent_type: general-purpose by default. Single-platform MVPs MAY

use a stack-specific type (ios-dev, ai-engineer, etc.) if the user prefers that agent's tool surface — but the MVP Charter still applies and overrides the agent's normal TDD posture. Multi-platform MVPs stay on general-purpose to avoid agent-per-step churn.

• isolation: "worktree" only in Path A above. Omit in Path B.
• prompt: assemble in this order

1. The full plan text, extracted from the plan file. **Embedded text

is authoritative for this run** — if the file changes mid-flight, a new dispatch is required, not a re-read.

1. The Step 3 template records (template name + baseline path per

platform).

1. The MVP Charter Execution rules (verbatim from the top section).
2. The MVP Charter BLOCKED handling (verbatim).
3. Handoff details: {TARGET_BRANCH} (resolved in 5a) and

instructions to resolve {WORKTREE_PATH} via git rev-parse --show-toplevel from the subagent's own cwd at runtime. Pass the plan file path for cross-reference too.

1. The 5a-bis PRD/spec bootstrap (verbatim). Path A: the absolute

source paths of the PRD dir + updated markdown spec (in the original main checkout), plus the instruction that the subagent's first action after the branch rename is to copy them into its worktree and make a dedicated docs(mvp): PRD + spec commit before any plan-step commit. Include a deferred **/comment-overlay.js .gitignore line only for legacy / transition flat layouts (Library v2 injects shared overlay at build — not the happy path). Path B: the files are already in the worktree; same dedicated first commit, no copy. Without this item the PRD/spec stays uncommitted or gets folded into the first feature commit, defeating 5a-bis.

Do NOT delegate to superpowers:executing-plans or superpowers:subagent-driven-development — both enforce TDD discipline and per-task two-stage review, which is the right default for production work but kills MVP velocity.

Recovery: if the subagent returns BLOCKED (see Charter), surface its report to the user; do not re-dispatch automatically.

Final report from this skill: List each commit (SHA + step name) and append a "TODO for hardening" section — a snapshot of TODO: markers left in code at end-of-run. This becomes the input for a later solopreneur:autopilot pass if the user decides to harden. Re-grep before the hardening pass starts; the snapshot will go stale once any commits land.

Notes

• Don't skip steps. Brainstorming → PRD → template lookup → MVP plan

is the value proposition. Short-circuit to execution only if the user explicitly opts out of a phase.

• Hardening is a separate pass. When the user later wants tests,

edge cases, a11y, etc., they re-invoke against the same plan file — solopreneur:autopilot for the heavy pipeline, or the standard superpowers flow for a manual pass. MVP execute leaves the plan and the TODO: markers as the handoff surface.