novaforge-appkit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NovaForge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# AppKit — Lean Mobile App Launch Kit
+
+An opinionated, **lean** AI development kit that takes a small mobile app from a vague idea to a
+store-ready release on **Google Play** and the **Apple App Store**. Works with **Claude Code**
+and **OpenAI Codex** — you pick the tool at install time, like a spec kit.
+
+> The AI gets broad freedom to make normal product and technical decisions. The workflow
+> automatically enforces privacy, quality, advertising, and store-readiness — and only asks you
+> when a decision is sensitive, expensive, legal, or hard to reverse.
+
+## Install
+
+The recommended way is `npx` — no global install, always the latest:
+
+```bash
+# inside your app project directory (interactive: asks which AI tool)
+npx novaforge-appkit init
+
+# or explicitly
+npx novaforge-appkit init --ai claude
+npx novaforge-appkit init --ai codex
+npx novaforge-appkit init --ai both
+
+# target a different directory
+npx novaforge-appkit init --ai claude --path ./my-app
+```
+
+Before it's published to npm, you can run it straight from GitHub:
+
+```bash
+npx github:NovaForgeOrg/appkit init --ai claude
+```
+
+Or install globally:
+
+```bash
+npm install -g novaforge-appkit
+appkit init --ai codex
+```
+
+Prefer no Node? A pure-bash installer is included:
+
+```bash
+git clone git@github.com:NovaForgeOrg/appkit.git
+./appkit/install.sh --ai claude --path ./my-app
+```
+
+Then open the project in your chosen tool and run the commands below. Re-running the installer
+is safe and refreshes the kit.
+
+## The workflow
+
+```
+/appkit.init      initialize the project + .appkit workflow
+/appkit.idea      generate or evaluate a small app idea         -> idea.md
+/appkit.shape     lean spec + vertical-slice task plan          -> app-spec.md, tasks.md
+/appkit.build     implement slices with tests                   -> source + tests
+/appkit.verify    full quality + policy gate                    -> verification-report.md
+/appkit.release   prepare the store package                     -> .appkit/release/
+```
+
+Repair loop:
+
+```
+/appkit.fix       minimal fix for a defect / finding / rejection
+/appkit.verify    re-run the gate
+```
+
+The commands are stateful: a gentle state machine (`UNINITIALIZED → … → RELEASE_PREPARED`)
+prevents skipping phases and routes blockers back to `/appkit.fix`.
+
+## What's opinionated
+
+- **Small & local-first** by default: one outcome, few screens, no login, no backend, no
+  personal data unless truly required.
+- **Privacy by default**: declarations (Google Data Safety, Apple App Privacy, iOS privacy
+  manifest) are built from real implementation evidence, not guesses.
+- **Monetization by design**: AdMob placements are decided during Shape, never bolted on.
+- **Policy by design**: Google Play, Apple, and AdMob rules are checked every phase.
+- **Evidence-based completion**: "done" requires passing scripts and captured screenshots —
+  AI for judgment, deterministic scripts for certainty.
+
+## What's inside
+
+```
+appkit/
+├── install.sh            # picks Claude Code or Codex, renders the adapter
+├── kit/                  # tool-independent source of truth
+│   ├── constitution.md       # non-negotiable principles
+│   ├── orchestrator.md       # state machine, gates, agent routing
+│   ├── agents/               # product · builder · reviewer · release
+│   ├── commands/             # init · idea · shape · build · verify · release · fix
+│   ├── skills/               # 6 skills (product, dev, testing/visual-QA, privacy, admob, store)
+│   ├── templates/            # idea, app-spec, tasks, report, privacy, listing, manifest
+│   ├── policy-rules/         # google-play · apple-app-store · admob · privacy checklists
+│   ├── profiles/             # flutter (default) · android · ios
+│   └── scripts/              # format, analyze, test, build, screenshots, validators…
+└── adapters/{claude-code,codex}/   # how the kit maps onto each tool
+```
+
+In an installed project the kit lives at `.appkit/kit/`, runtime artifacts at `.appkit/`
+(`status.yaml`, `idea.md`, `app-spec.md`, `tasks.md`, `verification-report.md`, `screenshots/`,
+`release/`).
+
+## Agents & skills (how the AI is organized)
+
+Four agents, each owning a phase and never chosen manually by you:
+
+| Agent     | Commands                         | Owns |
+|-----------|----------------------------------|------|
+| Product   | idea, shape                      | ideation, scope, spec |
+| Builder   | init, build, fix                 | architecture, implementation, tests |
+| Reviewer  | verify                           | independent quality + policy gate |
+| Release   | release                          | store package preparation |
+
+Six reusable skills carry the domain knowledge: `small-app-product-design`,
+`mobile-app-development`, `mobile-testing-and-visual-qa`, `mobile-privacy-and-permissions`,
+`admob-best-practices`, `mobile-store-release`.
+
+## Defaults & scope
+
+Default profile is **Flutter** (Android API 35 / iOS 15), local-first, portrait, AdMob planned
+but optional, no personal data. Native Android (Compose) / iOS (SwiftUI), IAP, subscriptions,
+analytics, and automated submission are intentionally **out of scope** for this lean version but
+the architecture leaves room for them.
+
+## Safety
+
+The kit **prepares** releases; **you** submit. It never exposes signing secrets, never invents
+legal/privacy text (placeholders are marked for your review), and requires your confirmation
+before anything sensitive or irreversible.

package/adapters/claude-code/README.md

@@ -0,0 +1,25 @@
+# Claude Code adapter
+
+Maps the tool-independent kit (`kit/`) onto Claude Code conventions.
+
+The installer (`install.sh --ai claude`) renders into the target project:
+
+| Kit source              | Installed as                         | Why |
+|-------------------------|---------------------------------------|-----|
+| `kit/commands/*.md`     | `.claude/commands/appkit.<name>.md`   | Filename → slash command `/appkit.<name>` |
+| `kit/agents/*.md`       | `.claude/agents/appkit-*.md`          | Native sub-agents (frontmatter: name/description/tools/model) |
+| `kit/skills/*/SKILL.md` | `.claude/skills/<name>/SKILL.md`      | Native skills, auto-activated by their `description` |
+| whole `kit/`            | `.appkit/kit/`                        | Shared brain; path references rewritten to `.appkit/kit/` |
+
+How it uses Claude Code best practices:
+- **Slash commands** are the orchestration entry points. Each runs the orchestrator preamble,
+  enforces the phase gate, adopts the owning agent role, and updates `.appkit/status.yaml`.
+- **Skills** carry reusable domain knowledge (product design, dev, testing/visual-QA, privacy,
+  AdMob, store release). Claude auto-loads them based on their `description`; commands also name
+  the ones they need.
+- **Sub-agents** (`appkit-product/builder/reviewer/release`) are available for delegation — e.g.
+  the Reviewer can run independently during `/appkit.verify`. Because the workflow is stateful
+  (reads/writes `.appkit/`), commands normally adopt the role inline and reserve sub-agent
+  delegation for heavy independent work like visual review.
+
+Re-running the installer refreshes these files in place.

package/adapters/codex/AGENTS.section.md

@@ -0,0 +1,53 @@
+<!-- BEGIN APPKIT -->
+# AppKit — Lean Mobile App Launch Kit (Codex operating guide)
+
+This project uses **AppKit** to take a small mobile app from idea to a store-ready release.
+You are the orchestrator. When the user runs an `/appkit.*` command (from `.codex/prompts/`) or
+asks to start/continue an app, follow the workflow below.
+
+## Golden path
+`/appkit.init` → `/appkit.idea` → `/appkit.shape` → `/appkit.build` → `/appkit.verify` →
+`/appkit.release`  ·  repair with `/appkit.fix` then re-verify.
+
+## On every command (orchestrator preamble)
+1. Read `kit/constitution.md` (non-negotiable rules) and `.appkit/status.yaml` (current state).
+2. Read the relevant artifacts (`.appkit/idea.md`, `app-spec.md`, `tasks.md`,
+   `verification-report.md`) when present.
+3. Check the gate for the phase; if unmet, tell the user the prerequisite command. Never skip phases.
+4. Adopt the owning agent role (below) and load its skills from `kit/skills/<name>/SKILL.md`.
+5. Prefer deterministic `kit/scripts/*.sh` for anything that must be certain.
+6. Update `.appkit/status.yaml` and report the new state + the single best next command.
+
+## State machine & gates
+`UNINITIALIZED → INITIALIZED → IDEA_SELECTED → SHAPED → BUILDING → BUILT → VERIFYING →
+(NOT_READY|READY) → RELEASING → RELEASE_PREPARED`
+- idea⇒INITIALIZED · shape⇒IDEA_SELECTED · build⇒SHAPED · verify⇒usable build · release⇒READY ·
+  fix⇒after build/verify/release/rejection.
+
+## Agent roles (personas — adopt the right one per command)
+- **Product** (`/appkit.idea`, `/appkit.shape`): generate/evaluate small ideas, reduce scope,
+  define users/screens/flows/acceptance, plan monetization & privacy, screen policy risk.
+  Skills: `small-app-product-design`, `mobile-privacy-and-permissions`, `admob-best-practices`,
+  `mobile-store-release`. Details: `kit/agents/product-agent.md`.
+- **Builder** (`/appkit.init`, `/appkit.build`, `/appkit.fix`): proportional architecture,
+  implement vertical slices with tests, AdMob adapter, storage, build config, minimal fixes.
+  Skills: `mobile-app-development`, `mobile-testing-and-visual-qa` (+ privacy/admob).
+  Details: `kit/agents/builder-agent.md`.
+- **Reviewer** (`/appkit.verify`): independent, evidence-based; run scripts, visual review,
+  accessibility, privacy, AdMob, Google Play & Apple policy, release smoke; write
+  `verification-report.md`. Skills: testing/privacy/admob/store. Details:
+  `kit/agents/reviewer-agent.md` + `policy-rules/`.
+- **Release** (`/appkit.release`): builds, signing checklists (no secrets), metadata,
+  declarations, screenshots, manifest. Requires READY verification + human approval to submit.
+  Details: `kit/agents/release-agent.md`.
+
+## Hard rules (see kit/constitution.md)
+Small & local-first by default · privacy by default · monetization decided in Shape · policy
+checked every phase · completion needs evidence (not assertions) · scripts for certainty ·
+ask the human only for the §8 triggers (children, sensitive data, high-risk permissions,
+payments, legal/medical claims, signing ownership, final submission, automatic submission) ·
+never change product objective/permissions/data/monetization silently.
+
+The full per-command instructions live in `.codex/prompts/appkit.*.md`. The shared brain is in
+`kit/`. The kit prepares releases; the human submits.
+<!-- END APPKIT -->

package/adapters/codex/README.md

@@ -0,0 +1,20 @@
+# Codex adapter
+
+Maps the tool-independent kit (`kit/`) onto OpenAI Codex CLI conventions.
+
+The installer (`install.sh --ai codex`) renders into the target project:
+
+| Kit source            | Installed as                          | Why |
+|-----------------------|----------------------------------------|-----|
+| `kit/commands/*.md`   | `.codex/prompts/appkit.<name>.md`      | Codex discovers prompt files; filename → `/appkit.<name>` |
+| `kit/skills/*/SKILL.md` | `.codex/skills/<name>/SKILL.md`      | Reusable skills (also readable at `.appkit/kit/skills/`) |
+| `kit/agents/*` + orchestrator | `AGENTS.md` (APPKIT block)      | Codex auto-reads `AGENTS.md`; agents become personas |
+| whole `kit/`          | `.appkit/kit/`                         | Shared brain; path references rewritten to `.appkit/kit/` |
+
+Codex has no isolated sub-agents, so the four agents are expressed as **personas** the single
+Codex agent adopts per command, driven by `AGENTS.md`. The `AGENTS.md` block is delimited by
+`<!-- BEGIN APPKIT -->` / `<!-- END APPKIT -->` and is replaced (not duplicated) on re-install.
+
+Note: Codex also supports user-level prompts in `~/.codex/prompts/`. This adapter installs
+**project-level** files so the kit travels with the repo; `AGENTS.md` makes the workflow work
+even on Codex versions that only read home-dir prompts.

package/bin/appkit.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * AppKit installer (Node) — same behavior as install.sh, cross-platform for npm/npx.
+ *
+ *   npx novaforge-appkit init --ai claude
+ *   npx github:NovaForgeOrg/appkit init --ai codex --path ./my-app
+ */
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const KIT_SRC = path.join(PKG_ROOT, 'kit');
+const CODEX_SECTION = path.join(PKG_ROOT, 'adapters', 'codex', 'AGENTS.section.md');
+
+function parseArgs(argv) {
+  const a = { ai: '', target: process.cwd() };
+  const args = argv.slice(2).filter((x) => x !== 'init'); // `init` is an optional verb
+  for (let i = 0; i < args.length; i++) {
+    const v = args[i];
+    if (v === '--ai') a.ai = args[++i];
+    else if (v === '--path') a.target = path.resolve(args[++i]);
+    else if (v === '--here') a.target = process.cwd();
+    else if (v === '-h' || v === '--help') a.help = true;
+    else { console.error(`Unknown arg: ${v}`); process.exit(1); }
+  }
+  return a;
+}
+
+const HELP = `AppKit — Lean Mobile App Launch Kit
+
+Usage:
+  npx novaforge-appkit init               interactive (asks which AI tool)
+  npx novaforge-appkit init --ai claude   Claude Code adapter
+  npx novaforge-appkit init --ai codex    OpenAI Codex adapter
+  npx novaforge-appkit init --ai both
+  Options: --path <dir> (default: current dir), --here
+
+Then run /appkit.init  ->  /appkit.idea -> /appkit.shape -> /appkit.build
+        /appkit.verify -> /appkit.release   (repair with /appkit.fix)`;
+
+// Rewrite bare kit refs to .appkit/kit/, protecting existing .appkit/ runtime paths.
+function rewrite(text) {
+  const SENT = "\u0000";
+  return text
+    .split('.appkit/').join(SENT)
+    .split('kit/').join('.appkit/kit/')
+    .split('templates/').join('.appkit/kit/templates/')
+    .split('profiles/').join('.appkit/kit/profiles/')
+    .split('policy-rules/').join('.appkit/kit/policy-rules/')
+    .split(SENT).join('.appkit/');
+}
+
+function copyDir(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name);
+    const d = path.join(dst, e.name);
+    if (e.isDirectory()) copyDir(s, d);
+    else { fs.copyFileSync(s, d); if (s.endsWith('.sh')) fs.chmodSync(d, 0o755); }
+  }
+}
+
+function ensureDirs(dirs) { for (const d of dirs) fs.mkdirSync(d, { recursive: true }); }
+function cmdNames() {
+  return fs.readdirSync(path.join(KIT_SRC, 'commands')).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3));
+}
+function readKit(rel) { return fs.readFileSync(path.join(KIT_SRC, rel), 'utf8'); }
+
+function installClaude(target, say) {
+  const C = path.join(target, '.claude');
+  ensureDirs([path.join(C, 'commands'), path.join(C, 'agents'), path.join(C, 'skills')]);
+  for (const n of cmdNames())
+    fs.writeFileSync(path.join(C, 'commands', `appkit.${n}.md`), rewrite(readKit(`commands/${n}.md`)));
+  for (const f of fs.readdirSync(path.join(KIT_SRC, 'agents')))
+    fs.writeFileSync(path.join(C, 'agents', f), rewrite(readKit(`agents/${f}`)));
+  copyDir(path.join(KIT_SRC, 'skills'), path.join(C, 'skills'));
+  say('claude -> .claude/{commands/appkit.*, agents/, skills/}');
+}
+
+function installCodex(target, say) {
+  const P = path.join(target, '.codex', 'prompts');
+  const S = path.join(target, '.codex', 'skills');
+  ensureDirs([P, S]);
+  for (const n of cmdNames())
+    fs.writeFileSync(path.join(P, `appkit.${n}.md`), rewrite(readKit(`commands/${n}.md`)));
+  copyDir(path.join(KIT_SRC, 'skills'), S);
+  const A = path.join(target, 'AGENTS.md');
+  const block = rewrite(fs.readFileSync(CODEX_SECTION, 'utf8')).replace(/\n+$/, '');
+  let existing = fs.existsSync(A) ? fs.readFileSync(A, 'utf8') : '';
+  if (existing.includes('<!-- BEGIN APPKIT -->')) {
+    existing = existing.replace(/<!-- BEGIN APPKIT -->[\s\S]*?<!-- END APPKIT -->\n?/g, '').replace(/\n{3,}$/, '\n');
+  }
+  const out = existing.trim() ? `${existing.replace(/\n+$/, '')}\n\n${block}\n` : `${block}\n`;
+  fs.writeFileSync(A, out);
+  say('codex -> AGENTS.md + .codex/{prompts/appkit.*, skills/}');
+}
+
+function writeStatus(target, ai) {
+  const status = path.join(target, '.appkit', 'status.yaml');
+  if (fs.existsSync(status)) return;
+  const today = new Date().toISOString().slice(0, 10);
+  fs.writeFileSync(status,
+`project_name: ${path.basename(target)}
+profile: flutter
+ai_tool: ${ai}
+targets: [android, ios]
+stores: [google_play, apple_app_store]
+monetization: { admob: true }
+state: UNINITIALIZED
+current_phase: init
+verification_status: not_run
+release_status: not_started
+open_blockers: []
+open_warnings: []
+last_updated: ${today}
+`);
+}
+
+function ensureGitignore(target) {
+  const gi = path.join(target, '.gitignore');
+  const lines = ['**/key.properties', '**/*.keystore', '**/*.jks', '.appkit/release/builds/', 'build/'];
+  let cur = fs.existsSync(gi) ? fs.readFileSync(gi, 'utf8') : '';
+  const have = new Set(cur.split('\n'));
+  const add = lines.filter((l) => !have.has(l));
+  if (add.length) fs.writeFileSync(gi, (cur && !cur.endsWith('\n') ? cur + '\n' : cur) + add.join('\n') + '\n');
+}
+
+async function chooseAi() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const q = (s) => new Promise((res) => rl.question(s, res));
+  console.log('Which AI coding tool should AppKit target?\n  1) claude   (Claude Code)\n  2) codex    (OpenAI Codex CLI)\n  3) both');
+  const c = (await q('Select [1]: ')).trim();
+  rl.close();
+  return c === '2' ? 'codex' : c === '3' ? 'both' : 'claude';
+}
+
+async function main() {
+  const a = parseArgs(process.argv);
+  if (a.help) { console.log(HELP); return; }
+  if (!fs.existsSync(KIT_SRC)) { console.error(`Cannot find kit/ at ${KIT_SRC}`); process.exit(1); }
+  if (!a.ai) a.ai = await chooseAi();
+  if (!['claude', 'codex', 'both'].includes(a.ai)) { console.error(`--ai must be claude|codex|both`); process.exit(1); }
+
+  fs.mkdirSync(a.target, { recursive: true });
+  console.log(`==> AppKit install: ai=${a.ai}  target=${a.target}`);
+  const say = (s) => console.log(`  ${s}`);
+
+  const appkit = path.join(a.target, '.appkit');
+  ensureDirs([
+    path.join(appkit, 'kit'),
+    path.join(appkit, 'screenshots', 'qa'),
+    path.join(appkit, 'screenshots', 'baselines'),
+    path.join(appkit, 'screenshots', 'findings'),
+    path.join(appkit, 'release'),
+  ]);
+  copyDir(KIT_SRC, path.join(appkit, 'kit'));
+  say('core -> .appkit/kit/');
+  writeStatus(a.target, a.ai);
+  say('status -> .appkit/status.yaml');
+
+  if (a.ai === 'claude' || a.ai === 'both') installClaude(a.target, say);
+  if (a.ai === 'codex' || a.ai === 'both') installCodex(a.target, say);
+  ensureGitignore(a.target);
+
+  const tool = a.ai === 'codex' ? 'Codex' : 'Claude Code';
+  console.log(`\n==> Done. AppKit installed for: ${a.ai}\n\nNext:\n  1) Open this folder in ${tool}.\n  2) Run /appkit.init  then  /appkit.idea -> /appkit.shape -> /appkit.build\n     /appkit.verify -> /appkit.release   (repair with /appkit.fix)\n\nShared brain: .appkit/kit/   |   Status: .appkit/status.yaml`);
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

package/install.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# AppKit installer — sets up the Lean Mobile App Launch Kit for Claude Code or Codex.
+#
+# Usage:
+#   ./install.sh                      # interactive: asks which AI tool, installs in CWD
+#   ./install.sh --ai claude          # install Claude Code adapter into the current dir
+#   ./install.sh --ai codex --path ./my-app
+#   ./install.sh --ai both            # install both adapters (they share .appkit/kit)
+#
+# Re-running is safe: it refreshes .appkit/kit and the chosen adapter's files.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+KIT_SRC="$SCRIPT_DIR/kit"
+AI=""; TARGET="$(pwd)"
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ai) AI="${2:-}"; shift 2;;
+    --path|--here) if [ "$1" = "--here" ]; then shift; else TARGET="${2:-}"; shift 2; fi;;
+    -h|--help) grep '^#' "$0" | sed 's/^# \{0,1\}//'; exit 0;;
+    *) echo "Unknown arg: $1"; exit 1;;
+  esac
+done
+
+[ -d "$KIT_SRC" ] || { echo "Cannot find kit/ next to installer ($KIT_SRC)"; exit 1; }
+mkdir -p "$TARGET"; TARGET="$(cd "$TARGET" && pwd)"
+
+if [ -z "$AI" ]; then
+  echo "Which AI coding tool should AppKit target?"
+  echo "  1) claude   (Claude Code)"
+  echo "  2) codex    (OpenAI Codex CLI)"
+  echo "  3) both"
+  printf "Select [1]: "; read -r choice || true
+  case "${choice:-1}" in 1|"") AI=claude;; 2) AI=codex;; 3) AI=both;; *) AI=claude;; esac
+fi
+
+say() { printf '  %s\n' "$*"; }
+echo "==> AppKit install: ai=$AI  target=$TARGET"
+
+# --- 1. Shared tool-independent core -> .appkit/kit ------------------------------------------
+APPKIT="$TARGET/.appkit"
+mkdir -p "$APPKIT/kit" "$APPKIT/screenshots/qa" "$APPKIT/screenshots/baselines" \
+         "$APPKIT/screenshots/findings" "$APPKIT/release"
+cp -R "$KIT_SRC/." "$APPKIT/kit/"
+chmod +x "$APPKIT/kit/scripts/"*.sh 2>/dev/null || true
+say "core -> .appkit/kit/"
+
+if [ ! -f "$APPKIT/status.yaml" ]; then
+  cat > "$APPKIT/status.yaml" <<EOF
+project_name: $(basename "$TARGET")
+profile: flutter
+ai_tool: $AI
+targets: [android, ios]
+stores: [google_play, apple_app_store]
+monetization: { admob: true }
+state: UNINITIALIZED
+current_phase: init
+verification_status: not_run
+release_status: not_started
+open_blockers: []
+open_warnings: []
+last_updated: $(date +%Y-%m-%d)
+EOF
+  say "status -> .appkit/status.yaml (UNINITIALIZED)"
+fi
+
+# Rewrite bare kit references (kit/ templates/ profiles/ policy-rules/) to .appkit/kit/ paths,
+# while protecting existing .appkit/ runtime paths. BSD/GNU-portable (no word boundaries).
+rewrite() {
+  sed -e 's#\.appkit/#__AK__#g' \
+      -e 's#kit/#.appkit/kit/#g' \
+      -e 's#templates/#.appkit/kit/templates/#g' \
+      -e 's#profiles/#.appkit/kit/profiles/#g' \
+      -e 's#policy-rules/#.appkit/kit/policy-rules/#g' \
+      -e 's#__AK__#.appkit/#g' "$1"
+}
+
+# Command name mapping: kit/commands/<name>.md -> appkit.<name>
+cmd_names() { for f in "$KIT_SRC"/commands/*.md; do basename "$f" .md; done; }
+
+install_claude() {
+  local C="$TARGET/.claude"
+  mkdir -p "$C/commands" "$C/agents" "$C/skills"
+  for n in $(cmd_names); do rewrite "$KIT_SRC/commands/$n.md" > "$C/commands/appkit.$n.md"; done
+  for f in "$KIT_SRC"/agents/*.md; do rewrite "$f" > "$C/agents/$(basename "$f")"; done
+  cp -R "$KIT_SRC/skills/." "$C/skills/"
+  say "claude -> .claude/{commands/appkit.*, agents/, skills/}"
+}
+
+install_codex() {
+  local P="$TARGET/.codex/prompts" S="$TARGET/.codex/skills"
+  mkdir -p "$P" "$S"
+  for n in $(cmd_names); do rewrite "$KIT_SRC/commands/$n.md" > "$P/appkit.$n.md"; done
+  cp -R "$KIT_SRC/skills/." "$S/"
+  # AGENTS.md: orchestrator + agent personas, pointing at the shared core. Idempotent block.
+  local A="$TARGET/AGENTS.md"
+  local block; block="$(rewrite "$SCRIPT_DIR/adapters/codex/AGENTS.section.md")"
+  if [ -f "$A" ] && grep -q "<!-- BEGIN APPKIT -->" "$A"; then
+    # Strip the old AppKit block, then re-append the fresh one.
+    awk '/<!-- BEGIN APPKIT -->/{skip=1} !skip{print} /<!-- END APPKIT -->/{skip=0}' "$A" > "$A.tmp"
+    mv "$A.tmp" "$A"
+  fi
+  { [ -f "$A" ] && [ -s "$A" ] && printf '\n'; printf '%s\n' "$block"; } >> "$A"
+  say "codex -> AGENTS.md + .codex/{prompts/appkit.*, skills/}"
+}
+
+case "$AI" in
+  claude) install_claude;;
+  codex)  install_codex;;
+  both)   install_claude; install_codex;;
+  *) echo "Unknown --ai '$AI' (use claude|codex|both)"; exit 1;;
+esac
+
+# .gitignore guard for secrets / build output
+GI="$TARGET/.gitignore"
+for line in "**/key.properties" "**/*.keystore" "**/*.jks" ".appkit/release/builds/" "build/"; do
+  grep -qxF "$line" "$GI" 2>/dev/null || echo "$line" >> "$GI"
+done
+
+cat <<EOF
+
+==> Done. AppKit installed for: $AI
+
+Next steps:
+  1) Open this folder in $( [ "$AI" = codex ] && echo "Codex" || echo "Claude Code" ).
+  2) Run:  /appkit.init   then  /appkit.idea  ->  /appkit.shape  ->  /appkit.build
+           /appkit.verify ->  /appkit.release   (repair with /appkit.fix)
+
+Shared brain: .appkit/kit/   |   Status: .appkit/status.yaml
+EOF

package/kit/agents/builder-agent.md

@@ -0,0 +1,49 @@
+---
+name: appkit-builder
+description: Owns architecture, codebase initialization, task implementation, tests, AdMob and storage wiring, build configuration and technical fixes for small Flutter apps. Invoked by /appkit.init, /appkit.build and /appkit.fix.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: inherit
+---
+
+# Builder Agent
+
+You own **Init**, **Build**, and technical **Fix** work. Ship a working MVP with tests — not a
+framework.
+
+## Operating rules
+- Obey `kit/constitution.md`. Keep architecture proportional to a small app; avoid
+  overengineering, unnecessary abstraction, and unnecessary dependencies.
+- Load `mobile-app-development` and `mobile-testing-and-visual-qa` skills; load
+  `mobile-privacy-and-permissions` and `admob-best-practices` when touching permissions, data,
+  or ads.
+- Follow `app-spec.md` and the selected profile (`profiles/flutter.md` + android/ios). Add only
+  what is in scope.
+- Write tests **with** the implementation. Preserve deterministic UI states.
+- Isolate advertising behind the ad adapter. Keep release config separate. Never use production
+  ad ids in development. Never silently add permissions or data collection.
+- Add a regression test for every fix. Preserve local-first behavior.
+
+## Init → project + `.appkit/` structure
+Scaffold the Flutter app per profile, set application id / bundle id, create the `.appkit/`
+tree and `status.yaml`, configure environments (`APP_ENV`), lints, and initial tests. Default:
+Flutter, Android+iOS, local-first, no login, no backend, portrait, AdMob planned-not-mandatory,
+no personal data. State → INITIALIZED.
+
+## Build → implement slices
+For each task: read spec → implement the slice → add/update tests → run format, analyze, unit,
+widget, and targeted integration tests (`kit/scripts/`) → update task status. Report remaining
+work. State → BUILDING, then BUILT when all slices/tests pass.
+
+## Change control
+Do not silently change product objective, target user, monetization, data collection,
+permissions, backend usage, store target, or acceptance criteria. If implementation forces a
+change, update `app-spec.md` and record why.
+
+## Fix
+Classify the issue, locate the affected requirement + code, make the **minimal** correction,
+add a regression test, rerun the affected gates, and update task status + the verification
+report. Do not add unrelated features.
+
+## Done when
+Code compiles, the relevant scripts pass (with output, not assertion), tasks/status are
+updated, and changes stay within the spec (or the spec was updated with a recorded reason).

package/kit/agents/product-agent.md

@@ -0,0 +1,48 @@
+---
+name: appkit-product
+description: Owns product ideation and shaping for small mobile apps. Use to generate/evaluate app ideas, reduce scope to an MVP, define users, screens, flows and acceptance criteria, plan monetization and privacy, screen policy risk, and produce idea.md, app-spec.md and tasks.md. Invoked by /appkit.idea and /appkit.shape.
+tools: Read, Write, Edit, Grep, Glob, WebSearch, WebFetch
+model: inherit
+---
+
+# Product Agent
+
+You own the **Idea** and **Shape** phases. Your job is to turn a vague request into a small,
+coherent, launchable product — and to keep it small.
+
+## Operating rules
+- Obey `kit/constitution.md`. Prefer a small coherent app over a broad one.
+- Load and apply the `small-app-product-design` skill always; load
+  `mobile-privacy-and-permissions`, `admob-best-practices`, and `mobile-store-release` when
+  shaping monetization, privacy, or store risk.
+- Make safe assumptions and record them. Ask only high-value questions. Reject weak ideas
+  honestly and propose a smaller adjacent idea.
+- Never recommend unnecessary accounts, servers, or high-risk permissions.
+- Treat monetization as part of UX, decided now, not later.
+- Use WebSearch/WebFetch to check current store/AdMob policy or validate that an idea is not
+  in a restricted category when unsure.
+
+## Idea phase → `.appkit/idea.md`
+Understand the category, generate one or a few ideas, score them (see the skill's dimensions),
+estimate size/screens/backend/data/permissions, evaluate monetization and store-policy risk,
+recommend platforms, and give a decision: GO / GO WITH REDUCED SCOPE / REVISE / HOLD / REJECT.
+Use `templates/idea.template.md`.
+
+## Shape phase → `.appkit/app-spec.md` + `.appkit/tasks.md`
+Produce a lean spec (not an enterprise PRD): summary, objective, users, primary outcome, core
+features, out-of-scope, main flow, screen inventory + per-screen specs (with every state), data
+model, local storage, permissions (each justified), third-party SDKs, AdMob plan (per-placement
+yaml), privacy plan, technical approach, testing strategy, accessibility, acceptance criteria,
+store risks, release targets, assumptions. Use `templates/app-spec.template.md`.
+
+Break work into vertical slices in `tasks.md` (`templates/tasks.template.md`); each task
+references feature, screen, acceptance criteria, test expectation, and policy consideration.
+
+## Human-confirmation triggers (ask before shaping further)
+children · sensitive/medical/financial · gambling · UGC · social comms · location tracking ·
+high-risk permissions · subscriptions/IAP · backend · content licensing · legal/regulated
+claims · irreversible integration. Ask one concise question stating the risk + safe default.
+
+## Done when
+The artifact(s) exist, are internally consistent, the decision/recommendation is explicit, and
+`.appkit/status.yaml` is updated (IDEA_SELECTED after idea is accepted; SHAPED after shape).