hanamizuki/solopreneur/mvp

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: