nativeapptemplate-agent 0.2.0 → 0.2.2

package/AGENTS.md

@@ -0,0 +1,142 @@
+# AGENTS.md
+
+Project-wide instructions for AI coding agents (Claude Code, Codex, etc.). Keep this file short — it's loaded into context every session. For deep context, read the linked docs on demand.
+
+## What this project is
+
+`nativeapptemplate-agent` — a Claude Code agent that turns a natural-language SaaS spec (e.g. "a walk-in queue for a barbershop") into a working three-platform implementation: Rails 8.1 API + native SwiftUI iOS + native Jetpack Compose Android. Built during the Built with Opus 4.7 Claude Code Hackathon, April 21–27, 2026.
+
+**Read `docs/SPEC.md` before making non-trivial changes.** It's the source of truth for architecture, three-layer validation, operation paths (adapt vs. replace), and hackathon success criteria.
+
+## Model
+
+- Use `claude-opus-4-7` for all agent invocations.
+- Requires Claude Agent SDK `>= 0.2.111`.
+- Do not set `thinking.type.enabled` — use `thinking: {type: "adaptive"}` instead (Opus 4.7 uses adaptive thinking).
+
+## Stack
+
+- **Host language:** TypeScript (Claude Agent SDK `@anthropic-ai/claude-agent-sdk`)
+- **Ruby subprocesses** for Rails AST / ERB / migration work (called from TypeScript)
+- **External MCP:** [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) for iOS Simulator + Android Emulator UI automation. **Pin `npx -y @mobilenext/mobile-mcp@0.0.54`** — 0.0.55+ closes the stdio connection on startup (the pin lives in `src/mobile.ts` and the plugin's `.mcp.json`).
+- **Node 22+ required.**
+
+## Coding conventions
+
+- TypeScript `strict: true`; no implicit `any`.
+- Prefer functions over classes — introduce a class only when state + lifecycle justify it (e.g. a long-lived MCP client wrapper). Stateless transforms are functions.
+- Ruby subprocesses: shell out via `execFile("ruby", ["scripts/ruby/<script>.rb", ...])` from a thin wrapper in `src/ruby.ts`. Pass structured data as JSON on stdin/stdout, not positional CLI args. Each script must be self-contained and re-entrant.
+- No comments explaining *what* the code does — name things well instead. Reserve comments for non-obvious *why*.
+
+## Substrate (what the agent operates on)
+
+The agent targets BOTH the paid and free (MIT-licensed) editions — the same code path handles both, validated end-to-end. **Test the paid edition first**: the free edition is a strict subset of paid (paid = free + multi-tenancy + invitations + role permissions + org switching), so anything that works on paid works on free, but not vice-versa. Catching paid-only regressions first avoids "free passes, paid breaks" surprises.
+
+Env vars point at the paid edition by default. Pick which substrate to use by pointing them at the corresponding repos:
+
+- `$NATIVEAPPTEMPLATE_API` — Rails 8.1 API repo (`nativeapptemplateapi`, single repo serves both editions; multi-tenancy + invitations are conditional features)
+- `$NATIVEAPPTEMPLATE_IOS` — SwiftUI iOS repo. Paid: `NativeAppTemplate` (Swift 23,003 LOC, adds org switching, invitations, role permissions). Free: `NativeAppTemplate-Free-iOS` (Swift 15,311 LOC).
+- `$NATIVEAPPTEMPLATE_ANDROID` — Jetpack Compose Android repo. Paid: `NativeAppTemplate` (Kotlin 28,401 LOC). Free: `NativeAppTemplate-Free-Android` (Kotlin 19,521 LOC).
+
+The renamer's substitution rules (Shop / Shopkeeper / ItemTag / NativeAppTemplate) apply identically to both editions. Paid-only concepts (Account, Member, Invitation) aren't in the rename plan, so paid features survive the generation intact. Both editions hit the same Rails OpenAPI server, so the reviewer's three-way diff works against either.
+
+**Substrate repos are read-only from the agent's perspective.** The agent never commits, pushes, edits, or runs destructive commands inside the substrate directories. To customize, the agent copies the substrate into `./out/<spec-slug>/{rails,ios,android}/` as fresh git-initialized project directories, and works exclusively inside `./out/` thereafter. Treat the substrate paths the same way you'd treat a read-only mount.
+
+## Domain model (do not misread)
+
+- `Shop` → per-tenant primary resource (not "store", not "shop" in e-commerce sense — a physical location with a walk-in queue)
+- `Shopkeeper` → the authenticated user/owner of a Shop
+- `ItemTag` (aka Number Tag) → a queue entry, attached to a Shop
+- **ItemTag has TWO states: `Idled` ↔ `Completed`.** It's a toggle, not a three-state machine. If a user's spec wants three states (e.g. "in-service"), extend the machine rather than assume it.
+- Free edition is single-organization (personal account is transparent). Paid edition adds multi-tenancy, invitations, roles, org switching — all out of scope for the rename pipeline (paid-only concepts aren't in the rename plan), but the agent still operates against paid substrates by default since paid is a superset of free.
+
+## Repository state
+
+Pre-implementation as of this writing: `src/` and `scripts/ruby/` are empty, and there is no `package.json`. The npm commands below are the target interface — don't try to run them until the scaffolding lands. Check `src/` before assuming.
+
+## Commands
+
+```bash
+# Build & test the agent (run from this repo root — once package.json exists)
+npm run build
+npm run test
+npm run dev -- "your spec here"
+
+# Substrate commands — run from the matching generated project dir in ./out/<slug>/
+bin/dev                                        # Rails API
+xcodebuild -scheme NativeAppTemplate -destination 'platform=iOS Simulator,name=iPhone 17 Pro,OS=26.2' build   # iOS
+./gradlew assembleDebug && ./gradlew installDebug                                                          # Android
+
+# Validation (run from this repo root)
+rg -n "Shop|Shopkeeper|ItemTag" ./out/<slug>/    # Layer 1 rename completeness check
+cloc --vcs=git "$NATIVEAPPTEMPLATE_API"                  # LOC measurement for a specific substrate repo
+
+# mobile-mcp — invoked via natural language through Claude Code
+# "Take a screenshot", "Tap on Sign Up", "List elements on screen", etc.
+```
+
+## Operations the agent performs
+
+Three clean operations on the substrate (details in `docs/SPEC.md` section 4):
+
+1. **Rename the skeleton** — Shop → Clinic, Shopkeeper → Staff, propagated coherently across Rails + Swift + Kotlin.
+2. **Adapt or replace the domain module** — keep ItemTag for queue variants; strip and insert a new resource for non-queue SaaS.
+3. **Drive the build green** — Rails tests + xcodebuild + gradlew must all pass.
+
+## Validation (three layers, gated)
+
+1. **Structural** — ripgrep for leftover domain tokens + OpenAPI contract parity (Rails ↔ iOS ↔ Android).
+2. **Runtime** — Rails boots, iOS builds & launches, Android builds & launches (Stage 1); UI-driven CRUD scenario via mobile-mcp (Stage 2).
+3. **Semantic** — Opus 4.7 as judge (text + vision) scoring against a structured rubric. Three runs per screenshot, take the median.
+
+## Guardrails
+
+- **Self-repair loop hard-capped at 5 iterations** per generated project, opt-in via `NATIVEAPPTEMPLATE_REPAIR` (targets Layer 1/2 only; Layer 3 + reviewer are surfaced, not auto-repaired). On exceed, surface residuals and exit. Code: `src/repair-loop.ts` + `src/agents/repair.ts`.
+- Known-cryptic failure modes: Jetpack Compose compilation, Hilt DI. Slow down and verify rather than pattern-match on those.
+- **Do not invent tests for the generated code.** The substrate already has tests; use them.
+- **Never modify the substrate repos** — clone them fresh into `./out/<slug>/{rails,ios,android}` before editing.
+- Token budget: keep per-sub-agent context under 500k tokens to leave headroom for self-repair loops.
+
+## Output layout
+
+```
+./out/<spec-slug>/
+├── rails/           # customized Rails API (git-initialized)
+├── ios/             # customized iOS project (git-initialized)
+└── android/         # customized Android project (git-initialized)
+```
+
+Each is an independent, buildable git repo.
+
+## Packaging
+
+Ships as three surfaces today:
+- `npx nativeapptemplate-agent "your spec"` — standalone CLI (primary)
+- `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp` — stdio MCP server wrapping `dispatch()` as a `generate_app` tool, for any MCP-capable assistant (Claude Code, Cursor, Cline, Goose). The distribution multiplier. (The `-mcp` entry point is a *bin* of the `nativeapptemplate-agent` package, not its own package — hence `-p`; `npx -y nativeapptemplate-agent-mcp` 404s.)
+- **Claude Code plugin** in `plugin/` — `claude --plugin-dir ./plugin` loads two skills: `/nativeapptemplate-agent:generate-app` (generate → validate → explain) and `/nativeapptemplate-agent:walk-app` (drive the running app via `mobile-mcp`). Bundles the generator MCP server + mobile-mcp. See `plugin/README.md`.
+
+Plugin `.mcp.json` pins are load-bearing: `nativeapptemplate-agent@latest` (MCP servers spawn with cwd = repo root; without `@latest`, `npx -p` resolves the *local* package and fails) and `@mobilenext/mobile-mcp@0.0.54` (0.0.55+ closes stdio).
+
+## Hackathon success criteria (quick reminder — details in docs/SPEC.md section 11)
+
+**Must-have for the demo video:**
+- Clinic queue spec produces 3 projects passing Layer 1 + Layer 2 Stage 1
+- Layer 3 rubric scores above threshold for captured home-screen shots
+- 90s demo video of end-to-end run with validation report
+
+**Stretch:** restaurant waitlist + task tracker also pass; self-repair loop fixes at least one real failure in the video.
+
+## Sibling docs
+
+- `docs/SPEC.md` — full technical specification (read first for any non-trivial change)
+- `ROADMAP.md` — post-hackathon direction, OSS vs hosted tracks, durable scope boundaries
+- `docs-private/GTM.md` — business strategy (relevant when discussing product surface, pricing, or Phase A/B transitions). Gitignored, not for publication.
+- `docs-private/PREP-CHECKLIST.md` — pre-hackathon setup (should already be all-green by the time development starts). Gitignored.
+
+## Anti-patterns to avoid
+
+- **Don't reimplement mobile UI automation.** Use mobile-mcp. The hackathon is not about inventing device automation.
+- **Don't extend scope beyond the queue / simple-CRUD-SaaS family** during the hackathon week. See `docs/SPEC.md` section 9 for the full non-goals list.
+- **Test the paid edition first.** Free is a strict subset of paid, so running paid first catches regressions that wouldn't surface against free alone. The OSS reproducibility story (judges/contributors with no paid license) lives in the free edition — once paid is green, point env vars at the free repos and re-run for the public demo.
+- **Don't skip the validation layers to save time.** They are the demo story. A run that green-builds without passing Layer 3 is a failed run.
+- **Don't edit, commit, push, or run `git clean` / `rm` inside `$NATIVEAPPTEMPLATE_API`, `$NATIVEAPPTEMPLATE_IOS`, or `$NATIVEAPPTEMPLATE_ANDROID`.** Those are the developer's working copies of the substrate (paid by default; possibly free), shared with other projects on the same machine. Copy them into `./out/<slug>/` first; change nothing in place. If unsure whether a command is safe, ask.

package/CLAUDE.md

@@ -1,139 +1 @@
-# CLAUDE.md
-
-Project-wide Claude Code instructions. Keep this file short — it's loaded into context every session. For deep context, read the linked docs on demand.
-
-## What this project is
-
-`nativeapptemplate-agent` — a Claude Code agent that turns a natural-language SaaS spec (e.g. "a walk-in queue for a barbershop") into a working three-platform implementation: Rails 8.1 API + native SwiftUI iOS + native Jetpack Compose Android. Built during the Built with Opus 4.7 Claude Code Hackathon, April 21–27, 2026.
-
-**Read `docs/SPEC.md` before making non-trivial changes.** It's the source of truth for architecture, three-layer validation, operation paths (adapt vs. replace), and hackathon success criteria.
-
-## Model
-
-- Use `claude-opus-4-7` for all agent invocations.
-- Requires Claude Agent SDK `>= 0.2.111`.
-- Do not set `thinking.type.enabled` — use `thinking: {type: "adaptive"}` instead (Opus 4.7 uses adaptive thinking).
-
-## Stack
-
-- **Host language:** TypeScript (Claude Agent SDK `@anthropic-ai/claude-agent-sdk`)
-- **Ruby subprocesses** for Rails AST / ERB / migration work (called from TypeScript)
-- **External MCP:** [`mobile-next/mobile-mcp`](https://github.com/mobile-next/mobile-mcp) for iOS Simulator + Android Emulator UI automation (`npx -y @mobilenext/mobile-mcp@latest`)
-- **Node 22+ required.**
-
-## Coding conventions
-
-- TypeScript `strict: true`; no implicit `any`.
-- Prefer functions over classes — introduce a class only when state + lifecycle justify it (e.g. a long-lived MCP client wrapper). Stateless transforms are functions.
-- Ruby subprocesses: shell out via `execFile("ruby", ["scripts/ruby/<script>.rb", ...])` from a thin wrapper in `src/ruby.ts`. Pass structured data as JSON on stdin/stdout, not positional CLI args. Each script must be self-contained and re-entrant.
-- No comments explaining *what* the code does — name things well instead. Reserve comments for non-obvious *why*.
-
-## Substrate (what the agent operates on)
-
-The agent targets BOTH the paid and free (MIT-licensed) editions — the same code path handles both, validated end-to-end. **Test the paid edition first**: the free edition is a strict subset of paid (paid = free + multi-tenancy + invitations + role permissions + org switching), so anything that works on paid works on free, but not vice-versa. Catching paid-only regressions first avoids "free passes, paid breaks" surprises.
-
-Env vars point at the paid edition by default. Pick which substrate to use by pointing them at the corresponding repos:
-
-- `$NATIVEAPPTEMPLATE_API` — Rails 8.1 API repo (`nativeapptemplateapi`, single repo serves both editions; multi-tenancy + invitations are conditional features)
-- `$NATIVEAPPTEMPLATE_IOS` — SwiftUI iOS repo. Paid: `NativeAppTemplate` (Swift 23,003 LOC, adds org switching, invitations, role permissions). Free: `NativeAppTemplate-Free-iOS` (Swift 15,311 LOC).
-- `$NATIVEAPPTEMPLATE_ANDROID` — Jetpack Compose Android repo. Paid: `NativeAppTemplate` (Kotlin 28,401 LOC). Free: `NativeAppTemplate-Free-Android` (Kotlin 19,521 LOC).
-
-The renamer's substitution rules (Shop / Shopkeeper / ItemTag / NativeAppTemplate) apply identically to both editions. Paid-only concepts (Account, Member, Invitation) aren't in the rename plan, so paid features survive the generation intact. Both editions hit the same Rails OpenAPI server, so the reviewer's three-way diff works against either.
-
-**Substrate repos are read-only from the agent's perspective.** The agent never commits, pushes, edits, or runs destructive commands inside the substrate directories. To customize, the agent copies the substrate into `./out/<spec-slug>/{rails,ios,android}/` as fresh git-initialized project directories, and works exclusively inside `./out/` thereafter. Treat the substrate paths the same way you'd treat a read-only mount.
-
-## Domain model (do not misread)
-
-- `Shop` → per-tenant primary resource (not "store", not "shop" in e-commerce sense — a physical location with a walk-in queue)
-- `Shopkeeper` → the authenticated user/owner of a Shop
-- `ItemTag` (aka Number Tag) → a queue entry, attached to a Shop
-- **ItemTag has TWO states: `Idled` ↔ `Completed`.** It's a toggle, not a three-state machine. If a user's spec wants three states (e.g. "in-service"), extend the machine rather than assume it.
-- Free edition is single-organization (personal account is transparent). Paid edition adds multi-tenancy, invitations, roles, org switching — all out of scope for the rename pipeline (paid-only concepts aren't in the rename plan), but the agent still operates against paid substrates by default since paid is a superset of free.
-
-## Repository state
-
-Pre-implementation as of this writing: `src/` and `scripts/ruby/` are empty, and there is no `package.json`. The npm commands below are the target interface — don't try to run them until the scaffolding lands. Check `src/` before assuming.
-
-## Commands
-
-```bash
-# Build & test the agent (run from this repo root — once package.json exists)
-npm run build
-npm run test
-npm run dev -- "your spec here"
-
-# Substrate commands — run from the matching generated project dir in ./out/<slug>/
-bin/dev                                        # Rails API
-xcodebuild -scheme NativeAppTemplate -destination 'platform=iOS Simulator,name=iPhone 17,OS=26.2' build   # iOS
-./gradlew assembleDebug && ./gradlew installDebug                                                          # Android
-
-# Validation (run from this repo root)
-rg -n "Shop|Shopkeeper|ItemTag" ./out/<slug>/    # Layer 1 rename completeness check
-cloc --vcs=git "$NATIVEAPPTEMPLATE_API"                  # LOC measurement for a specific substrate repo
-
-# mobile-mcp — invoked via natural language through Claude Code
-# "Take a screenshot", "Tap on Sign Up", "List elements on screen", etc.
-```
-
-## Operations the agent performs
-
-Three clean operations on the substrate (details in `docs/SPEC.md` section 4):
-
-1. **Rename the skeleton** — Shop → Clinic, Shopkeeper → Staff, propagated coherently across Rails + Swift + Kotlin.
-2. **Adapt or replace the domain module** — keep ItemTag for queue variants; strip and insert a new resource for non-queue SaaS.
-3. **Drive the build green** — Rails tests + xcodebuild + gradlew must all pass.
-
-## Validation (three layers, gated)
-
-1. **Structural** — ripgrep for leftover domain tokens + OpenAPI contract parity (Rails ↔ iOS ↔ Android).
-2. **Runtime** — Rails boots, iOS builds & launches, Android builds & launches (Stage 1); UI-driven CRUD scenario via mobile-mcp (Stage 2).
-3. **Semantic** — Opus 4.7 as judge (text + vision) scoring against a structured rubric. Three runs per screenshot, take the median.
-
-## Guardrails
-
-- **Self-repair loop hard-capped at 5 iterations** per generated project, opt-in via `NATIVEAPPTEMPLATE_REPAIR` (targets Layer 1/2 only; Layer 3 + reviewer are surfaced, not auto-repaired). On exceed, surface residuals and exit. Code: `src/repair-loop.ts` + `src/agents/repair.ts`.
-- Known-cryptic failure modes: Jetpack Compose compilation, Hilt DI. Slow down and verify rather than pattern-match on those.
-- **Do not invent tests for the generated code.** The substrate already has tests; use them.
-- **Never modify the substrate repos** — clone them fresh into `./out/<slug>/{rails,ios,android}` before editing.
-- Token budget: keep per-sub-agent context under 500k tokens to leave headroom for self-repair loops.
-
-## Output layout
-
-```
-./out/<spec-slug>/
-├── rails/           # customized Rails API (git-initialized)
-├── ios/             # customized iOS project (git-initialized)
-└── android/         # customized Android project (git-initialized)
-```
-
-Each is an independent, buildable git repo.
-
-## Packaging
-
-Ships as:
-- `npx nativeapptemplate-agent "your spec"` — standalone CLI
-- A Claude Code plugin (slash commands + skills)
-
-## Hackathon success criteria (quick reminder — details in docs/SPEC.md section 11)
-
-**Must-have for the demo video:**
-- Clinic queue spec produces 3 projects passing Layer 1 + Layer 2 Stage 1
-- Layer 3 rubric scores above threshold for captured home-screen shots
-- 90s demo video of end-to-end run with validation report
-
-**Stretch:** restaurant waitlist + task tracker also pass; self-repair loop fixes at least one real failure in the video.
-
-## Sibling docs
-
-- `docs/SPEC.md` — full technical specification (read first for any non-trivial change)
-- `ROADMAP.md` — post-hackathon direction, OSS vs hosted tracks, durable scope boundaries
-- `docs-private/GTM.md` — business strategy (relevant when discussing product surface, pricing, or Phase A/B transitions). Gitignored, not for publication.
-- `docs-private/PREP-CHECKLIST.md` — pre-hackathon setup (should already be all-green by the time development starts). Gitignored.
-
-## Anti-patterns to avoid
-
-- **Don't reimplement mobile UI automation.** Use mobile-mcp. The hackathon is not about inventing device automation.
-- **Don't extend scope beyond the queue / simple-CRUD-SaaS family** during the hackathon week. See `docs/SPEC.md` section 9 for the full non-goals list.
-- **Test the paid edition first.** Free is a strict subset of paid, so running paid first catches regressions that wouldn't surface against free alone. The OSS reproducibility story (judges/contributors with no paid license) lives in the free edition — once paid is green, point env vars at the free repos and re-run for the public demo.
-- **Don't skip the validation layers to save time.** They are the demo story. A run that green-builds without passing Layer 3 is a failed run.
-- **Don't edit, commit, push, or run `git clean` / `rm` inside `$NATIVEAPPTEMPLATE_API`, `$NATIVEAPPTEMPLATE_IOS`, or `$NATIVEAPPTEMPLATE_ANDROID`.** Those are the developer's working copies of the substrate (paid by default; possibly free), shared with other projects on the same machine. Copy them into `./out/<slug>/` first; change nothing in place. If unsure whether a command is safe, ask.
+@AGENTS.md

package/README.md

@@ -14,10 +14,45 @@ Coherent across all three, in under an hour.
 [![node: >=22](https://img.shields.io/node/v/nativeapptemplate-agent.svg)](https://nodejs.org/)
 
 ```bash
-npx nativeapptemplate-agent "a walk-in clinic queue for small veterinary practices"
+npx nativeapptemplate-agent "a walk-in clinic queue for small veterinary practices" --project-name="VetClinic"
 ```
 
-> **Status: v0.1.2 stable.** First built during [Built with Opus 4.7: a Claude Code Hackathon](https://cerebralvalley.ai/e/built-with-4-7-hackathon) (April 21–27, 2026); shipped to npm post-hackathon. Verified end-to-end on the three demo specs below from a fresh `/tmp/` cwd. Stage 2 (scripted-CRUD walk-through via `mobile-mcp` against a live Rails server) and paid-edition parity validation landed post-launch. Active development continues — see the [roadmap](./ROADMAP.md) for what's next.
+> **Status: 0.2.2 stable.** First built during [Built with Opus 4.7: a Claude Code Hackathon](https://cerebralvalley.ai/e/built-with-4-7-hackathon) (April 21–27, 2026); shipped to npm post-hackathon. Verified end-to-end on the three demo specs below from a fresh `/tmp/` cwd — the full 3-spec × 2-edition × 2-platform matrix is green at `NATIVEAPPTEMPLATE_VISUAL=2` (see the [matrix](#demo)). Stage 2 (scripted-CRUD walk-through via `mobile-mcp` against a live Rails server) and paid-edition parity validation landed post-launch. Active development continues — see the [roadmap](./ROADMAP.md) for what's next.
+
+---
+
+## Quick Start
+
+### Option 1: Claude Code plugin (recommended)
+
+Install the plugin once, then drive the agent with two slash commands — `/nativeapptemplate-agent:generate-app` (generate → validate → explain) and `/nativeapptemplate-agent:walk-app` (launch the app on a simulator/emulator and walk its UI via `mobile-mcp`, screenshots inline).
+
+```bash
+/plugin marketplace add nativeapptemplate/nativeapptemplate-agent
+/plugin install nativeapptemplate-agent@nativeapptemplate
+```
+
+Then in Claude Code:
+
+```
+/nativeapptemplate-agent:generate-app a walk-in clinic queue for small veterinary practices. project name is VetClinic.
+```
+
+Or load it locally without the marketplace: `claude --plugin-dir ./plugin`. See [`plugin/README.md`](./plugin/README.md) for the reference card, and the [A-to-Z plugin guide](./docs/PLUGIN-GUIDE.md) for a full walkthrough.
+
+### Option 2: Standalone CLI
+
+No editor required — runs anywhere Node 22+ is installed.
+
+```bash
+npx nativeapptemplate-agent "a walk-in clinic queue for small veterinary practices" --project-name="VetClinic"
+```
+
+Generated output appears under `./out/<slug>/`. See [Usage](#usage) for rename overrides and report flags.
+
+> **Pass a project name.** `--project-name` (or "project name is …" in the plugin) pins the Pascal project name, output slug (`out/vet-clinic/`), Xcode scheme, and display name across all three platforms. Omit it and the planner picks one — fine for one-off exploration, but it'll differ across re-runs.
+
+> Using Cursor, Cline, Goose, or another MCP-capable editor? The generator also ships as an MCP server: `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp` exposes a `generate_app` tool you can wire into your editor's MCP config.
 
 ---
 
@@ -29,6 +64,8 @@ Classic mobile boilerplates sell "save 12–16 weeks of setup." AI coding tools
 
 This agent is an answer to that: turn a boilerplate into a generator that produces coherent three-platform implementations on demand, with structural and semantic validation built in.
 
+> 📝 **Background:** [*One sentence becomes a native iOS app, a native Android app, and a Rails API*](https://medium.com/@dadachix/one-sentence-becomes-a-native-ios-app-a-native-android-app-and-a-rails-api-0000aaf9010c) — the long-form version of this argument: why cross-platform coherence, not code volume, is the problem AI didn't make easier.
+
 ## What it does
 
 Point the agent at a natural-language spec:
@@ -43,14 +80,18 @@ It will:
 2. **Copy the free-edition substrate** (three MIT-licensed repos covering Rails + iOS + Android) into `./out/<spec-slug>/{rails,ios,android}/`.
 3. **Rename the skeleton** — `Shop → Clinic`, `Shopkeeper → Vet`, etc. — consistently across Ruby migrations, Swift models, Kotlin data classes, policies, tests, and localized copy.
 4. **Adapt or replace the domain module** — keep `ItemTag` for walk-in queue variants; strip and insert a new resource for non-queue SaaS.
-5. **Drive the build green** — `bin/rails test`, `xcodebuild test`, `./gradlew test` must all pass before the agent exits.
+5. **Drive the build green** — every platform must pass before the agent exits. By default this is a fast gate: Rails routes load (`bin/rails routes`) and the iOS/Android projects resolve (`xcodebuild -list`, `./gradlew --version`). With `NATIVEAPPTEMPLATE_VISUAL=1`+ it escalates to full builds — Rails boots (`bin/rails db:prepare` + `bin/rails runner`), iOS builds (`xcodebuild build`), Android builds (`./gradlew assembleDebug`).
 6. **Validate the output** across three layers (structural, runtime, semantic) and write a self-contained HTML + JSON [validation report](#validation-report). Details in [`docs/SPEC.md`](./docs/SPEC.md) section 6.
 
 ## Demo
 
+**Quick look (40s)** — what the agent does, the three distribution surfaces, and a live walk of the generated app: **▸ [Watch on YouTube](https://youtu.be/fsjfskPWecQ)**
+
+**Full end-to-end run (90s)** — spec → renamed Rails API + iOS app + Android app, all three platforms validated:
+
 https://github.com/user-attachments/assets/bd1ed091-93d8-45d7-b502-c21720218484
 
-90-second end-to-end run: spec → renamed Rails API + iOS app + Android app, all three platforms validated. Also on [YouTube](https://youtu.be/z08ueZX-02I) for full-screen viewing.
+Also on [YouTube](https://youtu.be/z08ueZX-02I) for full-screen viewing.
 
 Three demo specs, both adapt and replace paths, all four validation layers green end-to-end:
 
@@ -60,12 +101,38 @@ Three demo specs, both adapt and replace paths, all four validation layers green
 | `"a restaurant waitlist for casual dining"` | `Shop → Restaurant`, `Shopkeeper → Host` | adapt | Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 · Reviewer PASS |
 | `"a personal task tracker with due dates"` | `ItemTag → Todo` (replaces queue entry entirely) | replace | Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 · Reviewer PASS |
 
-Layer 2 ran in build mode — real `xcodebuild build` and `./gradlew assembleDebug`, full app builds installed on iPhone 17 simulator and Android emulator. Layer 3 captured the home-screen via `xcrun simctl io booted screenshot` / `adb exec-out screencap` and judged against the rubric using Opus 4.7 vision (median of 3 samples per criterion). With `NATIVEAPPTEMPLATE_VISUAL=2`, Layer 2 additionally drives a scripted-CRUD walk-through via `mobile-mcp` against a live Rails server — Welcome → Sign Up → email-confirm via `bin/rails runner` → Sign In → drill into the auto-seeded sample — and Layer 3 then judges the post-walk screenshot against a domain-content rubric.
+Layer 2 ran in build mode — real `xcodebuild build` and `./gradlew assembleDebug`, full app builds installed on iPhone 17 Pro simulator and Android emulator. Layer 3 captured the home-screen via `xcrun simctl io booted screenshot` / `adb exec-out screencap` and judged against the rubric using Opus 4.7 vision (median of 3 samples per criterion). With `NATIVEAPPTEMPLATE_VISUAL=2`, Layer 2 additionally drives a scripted-CRUD walk-through via `mobile-mcp` against a live Rails server — Welcome → Sign Up → email-confirm via `bin/rails runner` → Sign In → drill into the auto-seeded sample — and Layer 3 then judges the post-walk screenshot against a domain-content rubric.
 
 The agent works on either the **free (MIT) edition** or the **paid edition** without code changes — the same pipeline handles both substrates; multi-tenant features (org switching, invitations, role permissions) survive the rename pipeline when targeting paid. The agent tests paid first because free is a strict subset of paid; running paid first catches regressions that wouldn't surface against free alone.
 
+### Validation matrix — 12/12 green at `VISUAL=2`
+
+All three specs pass a full end-to-end `NATIVEAPPTEMPLATE_VISUAL=2` run (build → rename → boot → scripted-CRUD walk → vision judge) on **both editions and both platforms** — 12 cells (3 specs × 2 editions × 2 platforms), each **Layer 1 3/3 · Layer 2 3/3 · Layer 3 2/2 · reviewer PASS** on a real iPhone 17 Pro simulator + Android emulator:
+
+| Spec | Free (iOS · Android) | Paid (iOS · Android) |
+|---|---|---|
+| Walk-in queue | ✅ · ✅ | ✅ · ✅ |
+| Restaurant / sushi waitlist | ✅ · ✅ | ✅ · ✅ |
+| Personal task tracker | ✅ · ✅ | ✅ · ✅ |
+
+After the queue cell's Stage-2 hardening landed, sushi and the task tracker passed first-try on both editions with no further changes — the scripted scenario is genuinely spec- and edition-agnostic (the task tracker is a non-queue spec running the same walk).
+
 Both screenshots are real captures from the booted iOS Simulator and Android emulator post-`./gradlew assembleDebug` / `xcodebuild build`, after the agent installed and launched the generated app.
 
+## Runtime
+
+End-to-end wall-clock per run, measured from `report.json`'s `meta.durationMs` on a 2021 M1 Max with both simulators pre-booted:
+
+| `NATIVEAPPTEMPLATE_VISUAL` | What runs | Observed time | Approx cost |
+|---|---|---|---|
+| `0` (default) | Layer 1 (ripgrep) + Layer 2 *fast* (Rails boot probe, iOS/Android type-check) + reviewer | ~2–3 min | ~$0.05 |
+| `1` | + full `xcodebuild build` + `./gradlew assembleDebug` + home-screen capture + Stage 1 vision judge | ~2.5 min (barbershop-queue · 2026-05-24) | — |
+| `2` | + Rails server boot + scripted-CRUD walk via `mobile-mcp` + Stage 2 vision judge | ~7–8 min (sentova / sushi / task-tracker · 2026-05-23) | — |
+
+Cold builds, first-run cocoapods/gradle dependency resolution, or unbooted simulators add a one-time minute or two. The self-repair loop (opt-in, hard-capped at 5 iterations) can extend a failing run substantially — budget for it if you set `NATIVEAPPTEMPLATE_REPAIR=on`.
+
+**Cost** scales with model usage, not wall-clock. The agent makes real `claude-opus-4-7` API calls (planner, workers, reviewer, judge) and a single VISUAL=2 run consumes tens of thousands of tokens across multiple sub-agents. Set a workspace spend cap (see [Security](#security)) as a backstop — the agent exits non-zero on validation failure, but doesn't gate on spend itself.
+
 ## Architecture
 
 ```mermaid
@@ -105,6 +172,12 @@ npx nativeapptemplate-agent "a walk-in clinic queue for small veterinary practic
 npx nativeapptemplate-agent "a restaurant waitlist for casual dining"
 npx nativeapptemplate-agent "a personal task tracker with due dates"
 
+# Name the project explicitly (sets display name + output slug, independent of the
+# domain rename). The plugin/MCP path accepts the same intent in plain language —
+# "…detection. project name is Sentova." — mapped to the projectName argument.
+npx nativeapptemplate-agent "a two-device home monitor for household pest detection" --project-name="Sentova"
+# → out/sentova/ · Sentova.xcodeproj · "Sentova API"; adapts ItemTag (e.g. Shop→Household, ItemTag→Sighting)
+
 # Generated output appears under ./out/<slug>/
 tree ./out/clinic-queue/
 # ├── rails/                   ← Rails 8.1 API, git-initialized, buildable
@@ -114,7 +187,14 @@ tree ./out/clinic-queue/
 # └── validation-report.html   ← self-contained visual report (open in a browser)
 ```
 
-The agent will also be available as a Claude Code plugin.
+The same generator also ships as an MCP server — `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp` exposes a `generate_app` tool, so any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) can invoke it without leaving the editor. And a **Claude Code plugin** ships in [`plugin/`](./plugin/) with two skills: `/nativeapptemplate-agent:generate-app` (generate → validate → explain) and `/nativeapptemplate-agent:walk-app` (launch the app on a simulator/emulator and walk its UI via `mobile-mcp`, screenshots inline). Install it via the bundled marketplace:
+
+```bash
+/plugin marketplace add nativeapptemplate/nativeapptemplate-agent
+/plugin install nativeapptemplate-agent@nativeapptemplate
+```
+
+…or load it locally with `claude --plugin-dir ./plugin`. See [`plugin/README.md`](./plugin/README.md) for the reference card, or the **[A-to-Z plugin guide](./docs/PLUGIN-GUIDE.md)** for a full follow-along walkthrough.
 
 ## Requirements
 
@@ -206,17 +286,17 @@ Report flags:
 
 **Don't** paste a real key into shell history (`HISTFILE` captures it), commit a `.env`, or echo the key into a non-private channel.
 
-The agent strips `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, and `NATIVEAPPTEMPLATE_AGENT_ANTHROPIC_KEY` from the environment of every subprocess it spawns — Ruby scripts, `git`, `psql`, `xcodebuild`, `gradlew`, the future mobile-mcp client. Keys are only seen by the Anthropic SDK in the Node process. Set spend limits on your API workspace as a backstop, and rotate the key if you suspect leak.
+The agent strips `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, and `NATIVEAPPTEMPLATE_AGENT_ANTHROPIC_KEY` from the environment of every subprocess it spawns — Ruby scripts, `git`, `psql`, `xcodebuild`, `gradlew`, the mobile-mcp client. Keys are only seen by the Anthropic SDK in the Node process. Set spend limits on your API workspace as a backstop, and rotate the key if you suspect leak.
 
 ## Project docs
 
 - [`docs/SPEC.md`](./docs/SPEC.md) — full technical specification
 - [`ROADMAP.md`](./ROADMAP.md) — where this project is headed, OSS vs hosted, what stays out of scope
-- [`CLAUDE.md`](./CLAUDE.md) — Claude Code project instructions (read if you're running Claude Code against this repo)
+- [`AGENTS.md`](./AGENTS.md) — AI coding agent instructions (read if you're running Claude Code, Codex, etc. against this repo; `CLAUDE.md` imports it)
 
 ## Contributing
 
-Issues and PRs welcome. The repository is stable now (v0.1.x) — no more hackathon-pace rewrites. A `CONTRIBUTING.md` with detailed guidelines will land alongside v0.2.
+Issues and PRs welcome. The repository is stable now (v0.2.x) — no more hackathon-pace rewrites. A `CONTRIBUTING.md` with detailed guidelines is still to come.
 
 For now, the simplest path is: open an issue describing what you're trying to do, and we'll figure out the right shape together before code lands. Bug reports with reproducible commands (and the `/tmp/<dir>/tmp/trace/` log) are especially welcome.
 

package/dist/agents/judge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/agents/judge.ts"],"names":[],"mappings":"AAIA,OAAO,EAAa,KAAK,UAAU,EAAqB,MAAM,yBAAyB,CAAC;AAIxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EAGX,cAAc,EAGd,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,YAAY,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAWF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QACP,mBAAmB,EAAE,MAAM,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACrC,CAAC;CACH,CAAC;AAQF,wBAAsB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAkEtE"}
+{"version":3,"file":"judge.d.ts","sourceRoot":"","sources":["../../src/agents/judge.ts"],"names":[],"mappings":"AAMA,OAAO,EAAa,KAAK,UAAU,EAAqB,MAAM,yBAAyB,CAAC;AAMxF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE/D,OAAO,KAAK,EACV,UAAU,EACV,WAAW,EAGX,cAAc,EAGd,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,YAAY,CAAC;IACpB,GAAG,EAAE,YAAY,CAAC;IAClB,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,MAAM,CAAC,EAAE,iBAAiB,CAAC;CAC5B,CAAC;AAWF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACpC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE;QACP,mBAAmB,EAAE,MAAM,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;KACrC,CAAC;CACH,CAAC;AAQF,wBAAsB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,CAAC,CAkEtE"}

package/dist/agents/judge.js

@@ -1,10 +1,14 @@
 import { resolve } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
 import { trace } from "../trace.js";
 import { isStub } from "../stub.js";
+import { createMobileClient } from "../mobile.js";
 import { runLayer1 } from "../validation/layer1.js";
 import { runLayer2 } from "../validation/layer2.js";
 import { runStage1Visual } from "../validation/stage1.js";
-import { runStage2Visual } from "../validation/stage2-judge.js";
+import { runStage2Visual, selectDevice } from "../validation/stage2-judge.js";
+import { recoverFromErrorScreen } from "../validation/stage2.js";
+import { discoverIosArtifact, discoverAndroidArtifact } from "../validation/discover.js";
 import { buildQueueScenario } from "../validation/scenarios/queue.js";
 export async function runJudge(input) {
     if (isStub("judge"))
@@ -76,23 +80,64 @@ async function runVisualPhase(config, domain) {
         platforms.push("android");
     const rubric = config.rubric;
     trace("judge", `Layer 3 (semantic) — judging ${platforms.join(" + ")} home screen against rubric`);
-    const stage1 = await runStage1Visual({
-        ...(config.iosDir !== undefined ? { iosDir: config.iosDir } : {}),
-        ...(config.androidDir !== undefined ? { androidDir: config.androidDir } : {}),
-        spec: config.spec ?? domain.displayName,
-        ...(rubric !== undefined ? { rubric } : {}),
-        ...(config.screenshotDir !== undefined ? { screenshotDir: config.screenshotDir } : {}),
-    });
-    const report = {};
-    if (stage1.ios) {
-        report.ios = toPlatformReport(stage1.ios);
-        trace("judge", `Layer 3 ios: ${stage1.ios.ok ? "PASS" : "FAIL"}` + (stage1.ios.error ? ` — ${stage1.ios.error}` : ""));
+    // iOS recovery for Stage 1: the paid app intermittently lands on a "Something
+    // went wrong" error screen at launch. On a renders-cleanly retry, tap its
+    // "Back to Start Screen" button (logs out + returns to welcome) so the
+    // re-capture sees a clean screen. Only when WDA is available (VISUAL=2, i.e.
+    // stage2 configured) and not in stub mode; the mobile client is created
+    // lazily on first retry and closed in the finally below.
+    let recoverClient;
+    let recoverUnavailable = false;
+    const canRecover = config.stage2 !== undefined && config.iosDir !== undefined && !isStub("judge");
+    const iosRecover = canRecover
+        ? async () => {
+            if (recoverUnavailable)
+                return;
+            if (!recoverClient) {
+                try {
+                    recoverClient = await createMobileClient();
+                    const err = await selectDevice(recoverClient, "ios");
+                    if (err) {
+                        recoverUnavailable = true;
+                        return;
+                    }
+                }
+                catch {
+                    recoverUnavailable = true;
+                    return;
+                }
+            }
+            const tapped = await recoverFromErrorScreen(recoverClient);
+            if (tapped) {
+                trace("judge", "Layer 3 ios: tapped 'Back to Start Screen' to clear error screen, re-capturing");
+                await sleep(2_000); // let the welcome screen render before re-capture
+            }
+        }
+        : undefined;
+    try {
+        const stage1 = await runStage1Visual({
+            ...(config.iosDir !== undefined ? { iosDir: config.iosDir } : {}),
+            ...(config.androidDir !== undefined ? { androidDir: config.androidDir } : {}),
+            spec: config.spec ?? domain.displayName,
+            ...(rubric !== undefined ? { rubric } : {}),
+            ...(config.screenshotDir !== undefined ? { screenshotDir: config.screenshotDir } : {}),
+            ...(iosRecover ? { iosRecover } : {}),
+        });
+        const report = {};
+        if (stage1.ios) {
+            report.ios = toPlatformReport(stage1.ios);
+            trace("judge", `Layer 3 ios: ${stage1.ios.ok ? "PASS" : "FAIL"}` + (stage1.ios.error ? ` — ${stage1.ios.error}` : ""));
+        }
+        if (stage1.android) {
+            report.android = toPlatformReport(stage1.android);
+            trace("judge", `Layer 3 android: ${stage1.android.ok ? "PASS" : "FAIL"}` + (stage1.android.error ? ` — ${stage1.android.error}` : ""));
+        }
+        return report;
     }
-    if (stage1.android) {
-        report.android = toPlatformReport(stage1.android);
-        trace("judge", `Layer 3 android: ${stage1.android.ok ? "PASS" : "FAIL"}` + (stage1.android.error ? ` — ${stage1.android.error}` : ""));
+    finally {
+        if (recoverClient)
+            await recoverClient.close().catch(() => { });
     }
-    return report;
 }
 async function runStage2Phase(base, config, domain) {
     if (!config.stage2)
@@ -121,6 +166,11 @@ async function runStage2Phase(base, config, domain) {
     }
     const platforms = [wantIos && "ios", wantAndroid && "android"].filter(Boolean).join(" + ");
     trace("judge", `Stage 2 — scripted-CRUD walk via mobile-mcp on ${platforms}`);
+    // Resolve the app ids so Stage 2 can foreground the app before walking (it
+    // can drop to springboard between stages). Best-effort: a discovery miss
+    // just skips the foreground step.
+    const iosArtifact = wantIos && config.iosDir !== undefined ? await discoverIosArtifact(config.iosDir) : null;
+    const androidArtifact = wantAndroid && config.androidDir !== undefined ? await discoverAndroidArtifact(config.androidDir) : null;
     const merged = { ...base };
     // Guard the whole Stage 2 walk: mobile-mcp runs in a child process, and if
     // it exits mid-walk the SDK rejects with `McpError: Connection closed`. That
@@ -131,6 +181,8 @@ async function runStage2Phase(base, config, domain) {
             spec: config.spec ?? domain.displayName,
             ...(wantIos ? { iosScenario } : {}),
             ...(wantAndroid ? { androidScenario } : {}),
+            ...(iosArtifact ? { iosAppId: iosArtifact.bundleId } : {}),
+            ...(androidArtifact ? { androidAppId: androidArtifact.packageName } : {}),
             ...(config.stage2.rubric !== undefined ? { rubric: config.stage2.rubric } : {}),
             ...(config.screenshotDir !== undefined ? { screenshotDir: config.screenshotDir } : {}),
         });