From acb256308ff2428a9c616d7e2c23f626f3ca66d2 Mon Sep 17 00:00:00 2001 From: dadachi Date: Sun, 24 May 2026 15:37:05 +0900 Subject: [PATCH] =?UTF-8?q?feat(plugin):=20Claude=20Code=20plugin=20skelet?= =?UTF-8?q?on=20=E2=80=94=20generate-app=20orchestration=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First cut of the Claude Code plugin (ROADMAP Post-v0.1 backlog → in progress on epic/claude-code-plugin). Minimal end-to-end: generate → validate → explain. - plugin/.claude-plugin/plugin.json — manifest (name nativeapptemplate-agent). - plugin/skills/generate-app/SKILL.md — orchestration skill: resolve spec, run the CLI (local dist or npx) with --report-format=both --exit-zero, parse out//report.json, and summarize per-platform layer1/2(/3) + reviewer parity + domain mapping; on failure surface the specific findings and the next move (--rename, NATIVEAPPTEMPLATE_REPAIR, NATIVEAPPTEMPLATE_VISUAL). The mobile-mcp home-screen walk-through is explicitly deferred to phase 2. - plugin/.mcp.json — bundles the generator MCP server. - plugin/README.md — local install (claude --plugin-dir ./plugin) + usage. Fix a propagated invocation bug: there is no npm package `nativeapptemplate-agent-mcp` (it's a *bin* of `nativeapptemplate-agent`), so `npx -y nativeapptemplate-agent-mcp` 404s. Correct form, verified against the published 0.2.1 with a real MCP initialize handshake from a clean dir: `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp`. Co-Authored-By: Claude Opus 4.7 (1M context) --- plugin/.claude-plugin/plugin.json | 9 ++ plugin/.mcp.json | 8 ++ plugin/README.md | 65 ++++++++++++++ plugin/skills/generate-app/SKILL.md | 126 ++++++++++++++++++++++++++++ 4 files changed, 208 insertions(+) create mode 100644 plugin/.claude-plugin/plugin.json create mode 100644 plugin/.mcp.json create mode 100644 plugin/README.md create mode 100644 plugin/skills/generate-app/SKILL.md diff --git a/plugin/.claude-plugin/plugin.json b/plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..191ea53 --- /dev/null +++ b/plugin/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "nativeapptemplate-agent", + "version": "0.1.0", + "description": "Generate a validated three-platform SaaS app (Rails 8.1 API + SwiftUI iOS + Jetpack Compose Android) from a one-sentence spec, then read the validation report and explain what passed and failed — 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 new file mode 100644 index 0000000..93f16aa --- /dev/null +++ b/plugin/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "nativeapptemplate-agent": { + "command": "npx", + "args": ["-y", "-p", "nativeapptemplate-agent", "nativeapptemplate-agent-mcp"] + } + } +} diff --git a/plugin/README.md b/plugin/README.md new file mode 100644 index 0000000..a6fdda8 --- /dev/null +++ b/plugin/README.md @@ -0,0 +1,65 @@ +# 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. + +This is the **first cut** — generate → validate → explain. A live home-screen +walk-through via `mobile-mcp` is planned as a second phase (see the repo +[roadmap](../ROADMAP.md#post-v01-backlog)). + +## What's in here + +``` +plugin/ +├── .claude-plugin/plugin.json # manifest +├── .mcp.json # bundles the nativeapptemplate-agent MCP server +├── skills/ +│ └── generate-app/SKILL.md # the orchestration skill +└── README.md +``` + +- **`/nativeapptemplate-agent:generate-app `** — the skill. Runs the + generator on your spec, parses `out//report.json`, and summarizes + per-platform / per-layer results, the domain mapping, and any failures with + the specific evidence and the next move. +- **Bundled MCP server** (`nativeapptemplate-agent`) — exposes `generate_app` as + a tool for direct/tool-call use; check it with `/mcp`. Wired as + `npx -y -p nativeapptemplate-agent nativeapptemplate-agent-mcp` (the MCP entry + point is a **bin** of the `nativeapptemplate-agent` package, not its own + package — hence `-p`). + +## 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. diff --git a/plugin/skills/generate-app/SKILL.md b/plugin/skills/generate-app/SKILL.md new file mode 100644 index 0000000..609d605 --- /dev/null +++ b/plugin/skills/generate-app/SKILL.md @@ -0,0 +1,126 @@ +--- +name: generate-app +description: >- + Generate a validated three-platform SaaS app — Rails 8.1 API + SwiftUI iOS + + Jetpack Compose Android — from a one-sentence natural-language spec, then read + the validation report and explain in plain language what passed and what + failed. Use when the user wants to scaffold, generate, bootstrap, or create a + new mobile or SaaS app from a description (e.g. "a walk-in queue for a + barbershop", "a restaurant waitlist", "a task tracker"). +--- + +# Generate a three-platform app and explain the result + +You orchestrate the `nativeapptemplate-agent` generator end-to-end: run it on the +user's spec, then turn its machine-readable validation report into a clear +summary. You are the conversational layer over a one-shot CLI — narrate each +step, never just dump raw output. + +## 1. Resolve the spec + +The user's spec (and any flags) arrive in `$ARGUMENTS`. If empty, ask for a +one-sentence description of the app before doing anything else. Examples that +work well: "a walk-in queue for a barbershop", "a restaurant waitlist for casual +dining", "a personal task tracker with due dates". The generator is scoped to +the queue / booking / simple-CRUD SaaS family — if the spec is far outside that +(e.g. a multiplayer game, a video app), say so and offer the closest in-scope +shape rather than generating something that will fail validation. + +Optional overrides the user may include, passed straight through to the CLI: +- `--project-name="Vet Clinic"` — fixes the display name + output slug. +- `--rename Shopkeeper=Vet` (repeatable) — overrides one of the planner's chosen + renames. Only renames the planner *already planned* are overridable; an + override that matches nothing is reported and dropped. + +## 2. Set expectations before running + +Tell the user, briefly, before you start: +- This makes real Anthropic API calls and takes ~3–5 minutes (longer with visual + validation). It needs `ANTHROPIC_API_KEY` in the environment. +- Output lands in `./out//{rails,ios,android}/` in the current directory, + each an independent git-initialized project. +- Substrate selection comes from the environment (`NATIVEAPPTEMPLATE_API` / + `_IOS` / `_ANDROID`); the defaults target the paid edition. Don't change these + unless the user asks. + +## 3. Run the generator + +Prefer a local build when present, otherwise the published CLI: +- If you are inside the agent's own repo and `dist/index.js` exists (or + `$NATIVEAPPTEMPLATE_AGENT_HOME` is set), run `node dist/index.js …`. +- Otherwise run `npx -y nativeapptemplate-agent …`. + +Always pass `--report-format=both` (so `report.json` is written for parsing) and +`--exit-zero` (so a validation FAIL doesn't abort the command before you can +read and explain the report — you decide pass/fail from the report yourself). + +Pass the spec as a **single quoted argument**, then append any flags. Example: + +```bash +node dist/index.js "a walk-in queue for a barbershop" --report-format=both --exit-zero +# or, outside this repo: +npx -y nativeapptemplate-agent "a restaurant waitlist" --report-format=both --exit-zero +``` + +The run prints a `report: file://…/out//validation-report.html` line on +completion. Note the `` — `report.json` sits next to that HTML file at +`out//report.json`. + +## 4. Read and interpret the report + +Read `out//report.json`. Its shape: + +```jsonc +{ + "meta": { "spec", "slug", "displayName", "visualLevel" /* 0|1|2 */, "durationMs", ... }, + "overallPass": true, + "summary": "one-line human summary", + "platforms": [ + { "platform": "rails"|"ios"|"android", + "layer1": { "pass": bool, "findings": [ /* leftover-token findings */ ] }, + "layer2": { "pass": bool, "command", "mode": "fast"|"build", "exitCode", "stderrTail"? }, + "layer3": { /* present only when visualLevel > 0 — vision-judge scores */ } } + ], + "reviewer": { "contractParity": "pass"|"fail", "diffs": [ /* OpenAPI mismatches */ ] }, + "domain": { + "renamePlan": [ { "from": "Shop", "to": "…" }, … ], + "entities": [ { "name", "replaces", "fields", "states"? }, … ] + }, + "repairAttempts": [ /* present only if the self-repair loop ran */ ] +} +``` + +Layers: **Layer 1** = structural (leftover domain tokens + OpenAPI parity), +**Layer 2** = runtime (Rails boots / iOS builds / Android builds; `mode: "build"` +means a full build was run), **Layer 3** = semantic vision judge (only when +`visualLevel > 0`). + +## 5. Summarize for the user + +Lead with the headline (`overallPass` + `summary` + total time from +`meta.durationMs`). Then a compact per-platform table — Layer 1 / Layer 2 (/ +Layer 3 if present) as ✅/❌ for rails, ios, android — plus reviewer contract +parity. Then the domain mapping the planner chose (`domain.renamePlan`, e.g. +`Shop → Clinic`, `Shopkeeper → Vet`) and the entities. Finish with the path to +`validation-report.html` and offer to open it (`open ` on macOS). + +## 6. On failure, be specific and offer the next move + +Don't just say "it failed." Pull the exact evidence and propose a fix: +- **Layer 1 fail** → list `layer1.findings` (leftover substrate tokens). Often a + rename the planner missed; suggest a targeted re-run with `--rename From=To`. +- **Layer 2 fail** → show `layer2.stderrTail` for the failing platform and name + the likely cause (Jetpack Compose compile + Hilt DI are the known-cryptic ones + — slow down there). Offer to opt into the self-repair loop by re-running with + `NATIVEAPPTEMPLATE_REPAIR=on` (targets Layer 1/2, hard-capped at 5 iterations). +- **reviewer parity fail** → list `reviewer.diffs` (Rails ↔ iOS ↔ Android + contract drift). +- For semantic checks, mention `NATIVEAPPTEMPLATE_VISUAL=1` (build + home-screen + judge) or `=2` (full mobile-mcp walk-through) as opt-in deeper validation. + +## 7. Hand off to the rest of the session + +The generated projects are real, git-initialized, and buildable. Offer concrete +follow-ups: open the report, tweak generated code, commit a project, or re-run +with overrides. (A live home-screen walk-through via `mobile-mcp` is planned as a +second phase of this skill — not wired yet.)