nativeapptemplate · dadachi · May 24, 2026 · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -18,7 +18,7 @@ Project-wide Claude Code instructions. Keep this file short — it's loaded into
 
 - **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`)
+- **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
@@ -110,11 +110,12 @@ Each is an independent, buildable git repo.
 
 ## Packaging
 
-Ships as two surfaces today:
+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`.
 
-A Claude Code plugin (slash command + orchestration skill) is **post-v0.1 backlog**, gated on streaming progress out of `dispatch()` and a skill that chains validation + a `mobile-mcp` walkthrough — against today's single-tool MCP a plugin would be a thin wrapper. See `ROADMAP.md` → Post-v0.1 backlog.
+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)
 

diff --git a/README.md b/README.md
@@ -126,7 +126,7 @@ tree ./out/clinic-queue/
 # └── validation-report.html   ← self-contained visual report (open in a browser)
 ```
 
-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. A Claude Code plugin (a discoverable slash command plus an orchestration skill that chains validation and a `mobile-mcp` walkthrough) is planned post-v0.1 — see the [roadmap](./ROADMAP.md#post-v01-backlog).
+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/) — `claude --plugin-dir ./plugin` loads 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). See [`plugin/README.md`](./plugin/README.md).
 
 ## Requirements
 

diff --git a/ROADMAP.md b/ROADMAP.md
@@ -31,7 +31,7 @@ The strategy is two-track.
 
 ### Track 1 — Open source (this repository)
 
-`npx nativeapptemplate-agent "your spec"` — the CLI form of the agent, and the primary surface. A second surface ships alongside it: `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp`, a stdio MCP server exposing a `generate_app` tool so any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) can invoke the agent without a terminal — the distribution multiplier. Both target the free-edition substrate and require an Anthropic API key; every generation run reproduces end-to-end on the reviewer's machine. A Claude Code plugin is a planned third surface — see Post-v0.1 backlog.
+`npx nativeapptemplate-agent "your spec"` — the CLI form of the agent, and the primary surface. A second surface ships alongside it: `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp`, a stdio MCP server exposing a `generate_app` tool so any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) can invoke the agent without a terminal — the distribution multiplier. Both target the free-edition substrate and require an Anthropic API key; every generation run reproduces end-to-end on the reviewer's machine. A **Claude Code plugin** is the third surface (in [`plugin/`](plugin/)) — `claude --plugin-dir ./plugin` loads the `generate-app` and `walk-app` skills; see [Claude Code plugin](#claude-code-plugin) below.
 
 This track is permanent. It is not a free trial of a commercial product — it is how we believe a generator like this should ship by default in 2026.
 
@@ -86,15 +86,14 @@ No interactive prompts — keeps the CLI scriptable and CI-friendly, no TTY assu
 
 ### Claude Code plugin
 
-**Status: deferred.** Long named as a packaging surface, not yet built. The shipped MCP server (`nativeapptemplate-agent-mcp`) already covers in-assistant invocation across *every* MCP-capable client — strictly wider reach than a Claude-Code-only plugin. Against today's MCP, which wraps `dispatch()` as a single `generate_app` tool, a plugin would be a thin wrapper: a discoverable slash command plus a one-step install, and little else.
+**Status: shipped.** Lives in [`plugin/`](plugin/); load it locally with `claude --plugin-dir ./plugin`. Two skills, bundling two MCP servers (the generator + `mobile-mcp`):
 
-The plugin earns its place once there is depth for it to add — work that doesn't exist yet and that the bare MCP tool can't carry cleanly:
+1. **`/nativeapptemplate-agent:generate-app <spec>`** — runs the generator, parses `out/<slug>/report.json`, and explains per-platform / per-layer results, the domain mapping, and any failures with the specific evidence and the next move.
+2. **`/nativeapptemplate-agent:walk-app <slug> ios|android`** — launches a generated app on a booted simulator/emulator and drives `mobile-mcp` to capture the home screen and walk the UI conversationally, screenshots inline.
 
-1. **Streaming progress out of `dispatch()`** so a 3–5 min build-mode run isn't a frozen wait. (Flagged non-negotiable for the MCP surface in the monetization notes; the plugin inherits the same need.)
-2. **An orchestration skill** that owns the *post*-generation story — chaining a `mobile-mcp` home-screen walkthrough, running the validation layers, and surfacing the report. This is genuinely plugin-shaped (a skill plus bundled MCP wiring), and it's the piece a single `generate_app` tool can't express.
-3. **Bundling the generator MCP + `mobile-mcp` pre-wired** so "generate a clinic queue, then walk its home screen" works out of the box.
+The original plan gated this on `dispatch()` streaming + an orchestration skill. In practice the skill carries the value without streaming: `generate-app` drives the CLI and narrates around it, delivering the post-generation story (validate → explain; generate → walk) with no streaming needed. Streaming remains a nice-to-have for the single-tool MCP surface, not a blocker for the plugin.
 
-Gate building the plugin on (1) and (2) landing first; until then it adds slash-command discoverability over the MCP and not much more.
+Verified end-to-end 2026-05-24: `generate-app` (barbershop-queue, all layers green) and `walk-app` (Android launch + interactive tap-through with inline screenshots on the Pixel emulator).
 
 ## What stays out of scope
 

diff --git a/docs/SPEC.md b/docs/SPEC.md
@@ -27,14 +27,14 @@ This document was originally a **pre-hackathon specification** (v1.0). It's pres
 | §6 Layer 2 Stage 1 (boot, build, launch) | **Shipped** | Default behavior. |
 | §6 Layer 2 Stage 2 (UI-driven scenario) | **Shipped** | Behind `NATIVEAPPTEMPLATE_VISUAL=2`; see §5 Stage 2 row. The original spec mentioned an HTTP-tail watcher for 4xx/5xx; the actual implementation walks the UI directly and lets the scenario `wait_for_text`/`assert_text` catch error states. |
 | §7 Evaluation plan (3 specs × 3 platforms = 9 projects) | **Exceeded** | Validated against 12 PASS combinations (full 6-cell matrix × 2 platforms): free × 3 specs × 2 platforms (6) + paid × 3 specs × 2 platforms (6). Both new paid cells (sushi waitlist, task tracker) passed first-try with no code changes — strong evidence the parameterized scenario is genuinely edition-agnostic. |
-| §8 Packaging (CLI + Claude Code plugin) | **Changed** | The planned Claude Code plugin was **not** built. The actually-shipped second surface is the **MCP server** (`nativeapptemplate-agent-mcp`, PR #60) — stdio, wrapping `dispatch()` as a `generate_app` tool, drivable from any MCP-capable assistant (Claude Code, Cursor, Cline, Goose) without the CLI. The §8 prose below still reads "two surfaces (CLI + plugin)" as the frozen pre-hackathon plan; **today's reality is CLI + MCP**, with the plugin deferred to ROADMAP → Post-v0.1 backlog (gated on streaming progress + an orchestration skill, since against the single-tool MCP a plugin would be a thin wrapper). |
+| §8 Packaging (CLI + Claude Code plugin) | **Shipped (3 surfaces)** | Shipped surfaces are now **CLI + MCP server + Claude Code plugin**. The MCP server (`nativeapptemplate-agent-mcp`, PR #60) was added as the wide-reach surface. The Claude Code plugin (`plugin/`) was deferred mid-stream, then built post-launch on `epic/claude-code-plugin` — two skills (`generate-app`, `walk-app`) bundling the generator MCP + `mobile-mcp`, both verified end-to-end 2026-05-24. The §8 prose below ("two surfaces (CLI + plugin)") is the frozen pre-hackathon plan; today's reality is **CLI + MCP + plugin**. |
 | §8 Packaging — env bridging (new) | **Shipped** | At run time the agent mirrors `NATIVEAPPTEMPLATE_API_*` (HOST/PORT/SCHEME) into renamed-product variants (`<PRODUCT>_API_*`) so the generated Android app picks them up via `~/.gradle/gradle.properties` and the iOS sim launch picks them up via `SIMCTL_CHILD_*` (PR #64). Safety knobs: `NATIVEAPPTEMPLATE_BRIDGE=off` skips the file write; `NATIVEAPPTEMPLATE_BRIDGE_DRY_RUN=1` previews. |
 | §9 Non-goals (paid-edition features) | **Stable** | Paid-edition features (multi-tenancy URL routing, invitations, role permissions, org switching) remain out of the rename pipeline by design. The agent operates against paid substrates fine — it just doesn't generate new paid-only features into renamed projects. |
 | §11 Hackathon must-haves | **All met** | All Must-have + Stretch criteria green at v0.2.0; see release notes for the post-hackathon delta. |
 
 ### What changed structurally since v1.0 of this spec
 
-- **Distribution surfaces: planned CLI + Claude Code plugin → shipped CLI + MCP server.** The MCP server replaced the plugin as the second surface — wider reach (every MCP client, not just Claude Code) for the same `dispatch()` core. The plugin is deferred to the Post-v0.1 backlog.
+- **Distribution surfaces: planned CLI + Claude Code plugin → shipped CLI + MCP server + Claude Code plugin** (three). The MCP server was added as the wide-reach surface (every MCP client, same `dispatch()` core); the plugin (two skills, bundling the generator MCP + `mobile-mcp`) shipped post-launch on top.
 - **Substrate scope went from "free-only" to "free + paid"** without code changes; same pipeline.
 - **Validation went from "9 generated projects, target Layer 1+2 pass + Layer 3 score"** to a concrete 12-cell PASS matrix.
 - **Stage 2 went from aspirational ("stretch") to default-when-opted-in** (`NATIVEAPPTEMPLATE_VISUAL=2`).

diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json
@@ -0,0 +1,9 @@
+{
+  "name": "nativeapptemplate-agent",
+  "version": "0.2.0",
+  "description": "Generate a validated three-platform SaaS app (Rails 8.1 API + SwiftUI iOS + Jetpack Compose Android) from a one-sentence spec, explain the validation report, and walk the running app on a simulator/emulator via mobile-mcp — without leaving Claude Code.",
+  "author": { "name": "Daisuke" },
+  "homepage": "https://github.com/nativeapptemplate/nativeapptemplate-agent",
+  "repository": "https://github.com/nativeapptemplate/nativeapptemplate-agent",
+  "license": "MIT"
+}
diff --git a/plugin/.mcp.json b/plugin/.mcp.json
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "nativeapptemplate-agent": {
+      "command": "npx",
+      "args": ["-y", "-p", "nativeapptemplate-agent@latest", "nativeapptemplate-agent-mcp"]
+    },
+    "mobile-mcp": {
+      "command": "npx",
+      "args": ["-y", "@mobilenext/mobile-mcp@0.0.54"]
+    }
+  }
+}
diff --git a/plugin/README.md b/plugin/README.md
@@ -0,0 +1,82 @@
+# nativeapptemplate-agent — Claude Code plugin
+
+Drive the [`nativeapptemplate-agent`](https://github.com/nativeapptemplate/nativeapptemplate-agent)
+generator from inside Claude Code. Describe an app in one sentence; the plugin
+generates a validated three-platform implementation (Rails 8.1 API + SwiftUI iOS
++ Jetpack Compose Android), then reads the validation report back to you in plain
+language.
+
+Two skills: **generate → validate → explain**, and an interactive **walk the
+running app** layer over `mobile-mcp`.
+
+## What's in here
+
+```
+plugin/
+├── .claude-plugin/plugin.json   # manifest
+├── .mcp.json                    # bundles the generator MCP server + mobile-mcp
+├── skills/
+│   ├── generate-app/SKILL.md    # generate → validate → explain
+│   └── walk-app/SKILL.md        # launch on a device, walk the UI with mobile-mcp
+└── README.md
+```
+
+- **`/nativeapptemplate-agent:generate-app <spec>`** — runs the generator on your
+  spec, parses `out/<slug>/report.json`, and summarizes per-platform / per-layer
+  results, the domain mapping, and any failures with the specific evidence and the
+  next move.
+- **`/nativeapptemplate-agent:walk-app <slug> ios|android`** — launches a generated
+  app on a **booted simulator/emulator** and drives `mobile-mcp` to capture the
+  home screen and walk the UI conversationally, surfacing screenshots inline.
+  Needs a booted device + an installed build (easiest via a
+  `NATIVEAPPTEMPLATE_VISUAL=1` generate run — see the skill for details).
+- **Bundled MCP servers** (`/mcp` to check): the generator server
+  (`nativeapptemplate-agent`, wired as
+  `npx -y -p nativeapptemplate-agent@latest nativeapptemplate-agent-mcp`) and
+  `mobile-mcp` (`@mobilenext/mobile-mcp@0.0.54`) for device automation.
+
+  Two non-obvious bits in that generator command: the MCP entry point is a **bin**
+  of the `nativeapptemplate-agent` package, not its own package, so `-p` is
+  required; and the **`@latest`** is load-bearing — without a version spec, `npx`
+  resolves the *local* package when the server is spawned from inside the agent's
+  own repo (cwd shadowing) and fails with `command not found`. `@latest` forces
+  registry resolution regardless of cwd.
+
+  `mobile-mcp` is **pinned to 0.0.54** on purpose: 0.0.55+ closes the stdio
+  connection on startup (`Connection closed` ~6s in), so `@latest` fails. This
+  matches the agent's own pin in `src/mobile.ts`. If you have a global `mobile-mcp`
+  config on `@latest`, it'll show ✘ failed in `/mcp` — this bundled, pinned one is
+  the working copy (different command, so it won't dedup against your global).
+
+## Requirements
+
+- Node.js 22+ and an `ANTHROPIC_API_KEY` with access to `claude-opus-4-7`.
+- For the generated apps to validate, the substrate env vars
+  (`NATIVEAPPTEMPLATE_API` / `_IOS` / `_ANDROID`) must point at the substrate
+  repos, as documented in the main README. The plugin reads them from your
+  environment and does not change them.
+
+## Try it locally (no marketplace needed)
+
+```bash
+# from the agent repo root
+claude --plugin-dir ./plugin
+```
+
+Then in the session:
+
+```
+/nativeapptemplate-agent:generate-app a walk-in queue for a barbershop
+```
+
+After editing plugin files, run `/reload-plugins` to pick up changes. Confirm the
+skill is loaded via `/help` and the MCP server via `/mcp`.
+
+## Install from git
+
+```
+/plugin install github.com/nativeapptemplate/nativeapptemplate-agent
+```
+
+> Note: the plugin lives in the `plugin/` subdirectory of the repo. If installing
+> by path, point at `plugin/`, not the repo root.