@grvmithas/create-aies-kit 1.3.0 → 2.3.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Changelog — @grvmithas/create-aies-kit
+
+Format: one `## [version] — date` heading per release (the release workflow refuses to publish without it).
+
+## [2.3.0] — 2026-11-06
+
+### Added
+- **Definition-of-done gate** (`hooks/aies-done.mjs` + `hooks/aies-done.json`). It is wired to Claude Code `Stop`, Codex `Stop`, Devin `Stop`, Gemini CLI `AfterAgent`, and Cursor `stop` (`followup_message`).
+  - When the working tree changed, it runs the detected lint, typecheck, and test commands, and refuses completion with the last 40 lines of failing output.
+  - It skips unchanged trees, caches the fingerprint of the last green run, releases after 3 consecutive blocks, and fails open on internal errors.
+  - Copilot, Kiro, and opencode have no blocking completion event; the CI gate covers them.
+- **Egress self-test** (`hooks/aies-egress-check.mjs` + `hooks/aies-egress.json`) for control AC-06.
+  - DNS and TCP probes to non-allowlisted hosts and a raw IP.
+  - Wired at session start for `--data-class confidential`. `--require-closed` exits 1 when anything is reachable, and `--json` gives machine-readable output.
+- `audit` check `done-gate`. `fix` fills an empty command list from the detected verify commands.
+- Guard protects `aies-done.*` and `aies-egress*` files from agent edits and deletion (14 self-test cases).
+
+### Changed
+- **`plugin` emits an Agent Plugins 1.0 bundle.** It contains a root `plugin.json` (spec schema), `skills/` (including the commands rendered as skills), and `mcp.json`, which Cursor and Kiro load natively.
+  - `.claude-plugin/` carries the Claude manifest, marketplace entry, and hooks (guard plus done gate) at `hooks/claude-hooks.json`.
+  - `.codex-plugin/plugin.json` is the Codex manifest.
+  - The bundle no longer emits `commands/`.
+
+## [2.2.0] — 2026-11-06
+
+### Fixed
+- **`enhance` no longer overwrites your edits.** It previously forced every generated file, silently discarding customized `AGENTS.md`, skills, and agents. Re-running install previously skipped every existing file, so there was no safe upgrade path at all.
+- `audit` no longer scores 100 on an unconfigured harness. It now fails on placeholder verify commands, a guard that fails its self-test, a missing eval suite, unwired `hooks/*.hook.sh`, and unmerged `*.aies-new` files.
+
+### Added
+- `.aies-kit.json` manifest of SHA-256 hashes for every kit-written file (CRLF-normalized). Upgrades update untouched files, keep edited ones (writing `<file>.aies-new` only when the kit version changed), delete retired files only when untouched, and record the profile so `enhance` no longer parses `AIES.md`.
+- Verify-command detection: `package.json` scripts with the right runner (npm/pnpm/yarn/bun), `pyproject.toml`/requirements with uv/poetry/pdm (ruff, flake8, mypy, pyright, pytest), Maven/Gradle wrappers, `.sln`/`.csproj`, `go.mod`, and `Makefile` targets. Detected commands are written into `AGENTS.md`, `AIES_REPO_SCAN.md`, and the CI gate.
+- `evals/`: promptfoo harness evals (7 cases: weaken lint, `--no-verify`, push to main, print `.env`, skip the plan, deploy, invent verify commands) with `AGENTS.md` injected as the system prompt and a pinned provider per `--model`; `evals/cases/` for product evals.
+- `templates/ci/aies-gates.yml`: merge-blocking jobs for guard self-test + `audit --min-score 100`, the repo's verify commands, and evals when behavior-defining files change.
+- `node hooks/aies-guard.mjs --self-test`: 12 fixed deny/allow cases; exits 1 on any mismatch or an invalid rules file.
+- `upgrade` alias for `enhance`; `fix` fills detectable verify commands in place.
+- Install uses the repo scan for MCP recommendations (previously only `enhance` did).
+
+### Changed
+- `mcps/` ships specs only for recommended servers (4–6 instead of 24; ~225 KB → ~40 KB). The full catalog stays online.
+- `hooks/*.hook.sh` and `hooks/CONTRACT.md` are no longer installed — no runtime executed them and they depended on `OAIES_*` evidence files nothing produced. Their role moves to the CI gate.
+- `AIES.md` and `AIES_REPO_SCAN.md` drop timestamps so re-runs do not churn diffs.
+
+## [2.1.0] — 2026-11-06
+
+### Security
+- `aies-guard.mjs` enforces three policies instead of one: shell commands, **writes to the agent's own guardrails** (hook, permission, MCP, editor auto-approve, CI, CODEOWNERS files — the CVE-2025-53773 / MCPoison class), and **reads of secrets** (`.env*`, keys, cloud credentials, registry tokens).
+- Fail closed: any guard error denies. Claude Code hooks set `onFailure: "block"`; Cursor hooks set `failClosed: true`.
+- Codex `apply_patch` bodies are parsed so every patched file is checked.
+- Custom rules gain `"protect"` path patterns alongside `"deny"` command patterns.
+
+### Added
+- Hook wiring for Codex (`.codex/hooks.json`), Gemini CLI (`hooks.BeforeTool` in `.gemini/settings.json`), Devin Desktop (`.devin/hooks.v1.json`), and opencode (`.opencode/plugins/aies-guard.js`). All 9 targets except Continue now have native enforcement.
+- Claude Code guard covers `Edit|Write|MultiEdit|NotebookEdit` and `Read`; Cursor adds `preToolUse` and `beforeReadFile`; Kiro adds `write` and `read` matchers.
+- Kiro skill mirror at `.kiro/skills/` (Kiro does not read `.agents/skills`).
+- Devin Desktop MCP config `.devin/mcp_config.json` (empty by default).
+- Codex `.codex/config.toml` sets project `sandbox_mode = "workspace-write"` and `approval_policy = "on-request"`.
+
+### Changed
+- Devin Desktop commands are emitted as skills (`.devin/skills/<name>/SKILL.md`); workflows are deprecated upstream. The `.devin/skills` skill mirror is dropped because Devin reads `.agents/skills`.
+- Codex agent TOML no longer emits `sandbox_mode` (agent files cannot override it; it was silently ignored). Read-only roles carry an explicit read-only instruction; enforcement comes from the parent session's sandbox.
+
+## [2.0.0] — 2026-11-06
+
+### Breaking
+- `AGENTS.md` is canonical. Root `copilot-instructions.md` and `aies-hooks.json` are no longer written; `CLAUDE.md` imports `@AGENTS.md`.
+- Skills move to `.agents/skills/<name>/SKILL.md` (open Agent Skills standard), mirrored to `.claude/skills` / `.devin/skills` only where required.
+- Commands move to native folders (`.cursor/commands`, `.claude/commands`, `.github/prompts`, `.gemini/commands`, `.opencode/commands`, `.devin/workflows`, `.kiro/steering`). `.cursor/prompts` and `.claude/prompts` are gone — runtimes never loaded them.
+- `windsurf` now targets Devin Desktop paths (`.devin/rules`, `.devin/workflows`, `.devin/skills`).
+- Node ≥ 20.
+
+### Added
+- Targets: `codex`, `gemini-cli`, `kiro`, `opencode` (plus aliases `vscode`, `claude`, `gemini`, `devin`).
+- Native subagents with enforced privileges: `readonly` (Cursor), tool lists (Claude, Copilot, Gemini), `sandbox_mode` (Codex), `permission` maps (opencode). Ships planner, coder, reviewer, security, testing, prompt-engineer, parallel-implementer.
+- `hooks/aies-guard.mjs` wired into Claude Code `PreToolUse`, Cursor `beforeShellExecution`, Copilot `preToolUse`, and Kiro `PreToolUse`; hashed audit log; fail-closed custom rules.
+- `scripts/aies-worktree.mjs` + `plans/_TASK_CONTRACT.md` for parallel agents.
+- Remote MCP catalog (GitHub, GitLab, Sentry, Linear, Notion, Atlassian, Asana, Supabase) rendered per runtime; empty config by default.
+- `plugin` command (Claude Code plugin + marketplace manifest).
+- Cloud agent setup: `copilot-setup-steps.yml`, `.cursor/environment.json`.
+- `audit --min-score` and `--format json`; audit checks skills, native hooks, task contracts, MCP hygiene; `fix` never overwrites.
+- `MODEL_POLICY.md` routes by task class.
+
+### Verification
+- Conformance suite (`npm run kit:check`): 9 runtimes × 4 stacks, frontmatter/TOML/JSON validity, guard behavior per hook protocol, layout snapshot.
+
+## [1.3.0]
+- Ephemeral `plans/{STORY_ID}-plan.md` + `reviews/{STORY_ID}-code-review.md`; agent hooks shipped; enhance-repo v2.
+
+## [1.2.0]
+- Layout fix: cookbook/guides/mcps/templates at repo root.
+
+## [1.1.0]
+- Self-contained package (embedded corpus + generator).
+
+## [1.0.0]
+- Initial publish (incomplete; do not use).

package/README.md

@@ -1,55 +1,108 @@
 # @grvmithas/create-aies-kit
 
-Scaffold a **complete AIES harness** into your repo using **IDE-native paths** (no `.aies/` folder).
+Scaffold the AIES harness into your repository in the **native formats each agent runtime actually loads** — `AGENTS.md`, open-standard skills, subagents, commands, enforcing hooks, MCP config, and a parallel-worktree helper. No `.aies/` folder.
 
 ```bash
 npx @grvmithas/create-aies-kit@latest \
-  --stack nextjs --ide cursor --role fullstack \
+  --stack nextjs --ide claude-code --role fullstack \
   --maturity intermediate --goal new-product \
   --model claude --data-class internal --yes
 ```
 
-Then enhance for *this* repository:
+Install reads your repository first: `AGENTS.md` gets your real lint / typecheck / test / build commands (from `package.json` scripts with the right package manager, `pyproject.toml` with uv/poetry/pdm, Maven/Gradle wrappers, `.sln`/`.csproj`, `go.mod`, or `Makefile` targets), and `mcps/` gets specs only for the servers your stack needs.
+
+Later, upgrade and rescan:
 
 ```bash
-npx @grvmithas/create-aies-kit@latest enhance
+npx @grvmithas/create-aies-kit@latest enhance     # alias: upgrade — refreshes the harness, keeps your edits
 ```
 
-Then open `*/prompts/enhance-repo.prompt.md` in your IDE agent so it adapts artifacts to your conventions.
+…and run the `enhance-repo` command in your agent for conventions a scan cannot infer (`/enhance-repo` in Cursor, Claude Code, Copilot, opencode; `/aies:enhance-repo` in Gemini CLI).
+
+## Your edits are safe
+
+`.aies-kit.json` records a hash of every file the kit wrote. Re-running install or `enhance`:
 
-## Layout contract
+| Your file is… | The kit… |
+|---|---|
+| Untouched | Updates it to the new kit version |
+| Edited, kit version unchanged | Leaves it alone |
+| Edited, kit version changed | Leaves it alone; writes the new version to `<file>.aies-new` for you to merge |
+| Retired by the new kit version, untouched | Deletes it |
+| Retired, edited | Leaves it in place and tells you |
 
-| Location | Contents |
-|----------|----------|
-| IDE folder (`.cursor` / `.github` / `.claude` / …) | **prompts**, **skills**, **agents** only (+ IDE rules / MCP config) |
-| Repo root | `cookbook/{stack}/`, `guides/`, `mcps/`, `templates/`, `MODEL_POLICY.md`, root instruction files |
+`--force` replaces edited files with the kit version. Commit `.aies-kit.json`; add `*.aies-new` and `hooks/logs/` to `.gitignore`.
 
-**Anti-pattern:** Nesting cookbook (or guides/MCP specs) under `.github/`. That folder is for Copilot discovery and GitHub metadata only.
+## Runtimes
 
-## What you get
+| `--ide` | Instructions | Skills | Subagents | Commands | Native hook | MCP config |
+|---|---|---|---|---|---|---|
+| `cursor` | `AGENTS.md` + `.cursor/rules/aies.mdc` | `.agents/skills` | `.cursor/agents/*.md` | `.cursor/commands` | `.cursor/hooks.json` | `.cursor/mcp.json` |
+| `claude-code` | `CLAUDE.md` → `@AGENTS.md` | `.agents/skills` + `.claude/skills` | `.claude/agents/*.md` | `.claude/commands` | `.claude/settings.json` | `.mcp.json` |
+| `copilot` | `AGENTS.md` + `.github/copilot-instructions.md` | `.agents/skills` | `.github/agents/*.agent.md` | `.github/prompts` | `.github/hooks/aies-guard.json` | `.mcp.json` |
+| `codex` | `AGENTS.md` | `.agents/skills` | `.codex/agents/*.toml` | `prompts/` | `.codex/hooks.json` (trust via `/hooks`) | `.codex/config.toml` |
+| `gemini-cli` | `AGENTS.md` via `.gemini/settings.json` | `.agents/skills` | `.gemini/agents/*.md` | `.gemini/commands/aies/*.toml` | `hooks.BeforeTool` in `.gemini/settings.json` | `.gemini/settings.json` |
+| `kiro` | `AGENTS.md` + `.kiro/steering` | `.agents/skills` + `.kiro/skills` | — | `.kiro/steering/aies-*.md` (manual) | `.kiro/hooks/aies-guard.json` | `.kiro/settings/mcp.json` |
+| `windsurf` (Devin Desktop) | `AGENTS.md` + `.devin/rules` | `.agents/skills` | — | `.devin/skills/<name>/SKILL.md` | `.devin/hooks.v1.json` | `.devin/mcp_config.json` |
+| `opencode` | `AGENTS.md` | `.agents/skills` | `.opencode/agents/*.md` | `.opencode/commands` | `.opencode/plugins/aies-guard.js` | `opencode.json` |
+| `continue` | `AGENTS.md` + `.continue/rules` | `.agents/skills` | — | `.continue/prompts` | — | `.continue/mcpServers/aies.json` |
+
+Aliases: `vscode`→`copilot`, `claude`→`claude-code`, `gemini`→`gemini-cli`, `devin`→`windsurf`.
+
+## What every install gets
 
 | Path | Purpose |
 |------|---------|
-| `AIES.md` | Operator guide — plans, prompts, skills, MCP, enhance |
-| `implementation_plan.md` | Plan of record |
-| `AGENTS.md` | Multi-agent / IDE agent contract |
-| `CLAUDE.md` | Root Claude / multi-IDE contract |
-| `copilot-instructions.md` | Root Copilot instructions |
-| `.github/copilot-instructions.md` | Copilot discovery copy |
-| IDE `prompts/` `skills/` `agents/` | Lifecycle + create/enhance artifacts |
-| `cookbook/{stack}/` | Full stack cookbook at **repo root** |
+| `AGENTS.md` | Canonical instructions (every runtime reads it or imports it) |
+| `AIES.md` | Operator guide: profile, plans, commands, skills, hooks, MCP, worktrees |
+| `MODEL_POLICY.md` | Model routing by task class + data-class rules |
+| `.agents/skills/<name>/SKILL.md` | Open Agent Skills standard (`name` = folder, trigger-style `description`) |
+| `hooks/aies-guard.mjs` | Dependency-free guard: denies force pushes, pushes to protected branches, `reset --hard`, pipe-to-shell, destructive SQL, publishes/deploys, edits to its own guardrails, secret reads. Fails closed. `--self-test` proves it in CI. Extend via `hooks/aies-guard.rules.json` |
+| `hooks/aies-done.mjs` · `hooks/aies-done.json` | Definition-of-done gate on the runtime's completion event (Claude Code, Codex, Devin `Stop`; Gemini `AfterAgent`; Cursor `stop`): when the working tree changed, runs your verify commands and sends the agent back with the failing output. Skips Q&A turns, caches green results, releases after 3 consecutive blocks, fails open. `AIES_DONE_SKIP=1` bypasses it |
+| `hooks/aies-egress-check.mjs` · `hooks/aies-egress.json` | Network-isolation self-test (control AC-06): DNS and TCP probes to non-allowlisted hosts and a raw IP. Wired at session start for `--data-class confidential`; `--require-closed` exits 1 when anything is reachable |
+| `evals/` | promptfoo harness evals: seven cases that check the `AGENTS.md` non-negotiables hold under pressure (weaken lint, `--no-verify`, push to main, print `.env`, skip the plan, deploy, invent verify commands). Add product evals under `evals/cases/` |
+| `templates/ci/aies-gates.yml` | Merge-blocking CI: guard self-test + `audit --min-score 100`, your repo's verify commands, and evals when behavior-defining files change. Copy to `.github/workflows/` |
+| `scripts/aies-worktree.mjs` | `new` / `list` / `check` / `overlap` / `remove` for one-task-one-worktree parallel agents (max 4), with per-slot ports and DB schema |
+| `plans/_TEMPLATE.md` · `plans/_TASK_CONTRACT.md` | Ephemeral per-story plans and per-task contracts (allowed/prohibited paths, acceptance, stop conditions) |
+| `reviews/` | `{STORY_ID}-code-review.md` reports |
+| `mcps/recommended.json` · `mcps/<spec>.mcp.md` | Vendor-hosted remote MCP servers (OAuth, read-only first) rendered for your runtime, plus specs for the recommended servers only — **nothing is enabled by default** |
+| `cookbook/{stack}/` · `guides/` · `templates/` | Reference material at repo root |
+| Cloud setup | `.github/workflows/copilot-setup-steps.yml` (Copilot) or `.cursor/environment.json` (Cursor) |
+
+## Commands
+
+```bash
+npx @grvmithas/create-aies-kit@latest audit                    # score the harness (0–100)
+npx @grvmithas/create-aies-kit@latest audit --min-score 100    # CI gate: exit 1 below threshold
+npx @grvmithas/create-aies-kit@latest audit --format json
+npx @grvmithas/create-aies-kit@latest fix                      # create missing files, fill detectable verify commands; never overwrites
+node hooks/aies-guard.mjs --self-test                          # prove the guard denies and allows what it should
+node hooks/aies-done.mjs                                       # run the definition-of-done gate by hand
+node hooks/aies-egress-check.mjs --require-closed              # CI/sandbox: exit 1 if egress is open
+npx @grvmithas/create-aies-kit@latest plugin --out ./aies-plugin   # Agent Plugins 1.0 bundle
+```
+
+The plugin bundle follows [Agent Plugins 1.0](https://agent-plugins.org/specification): root `plugin.json`, `skills/`, and `mcp.json`, which Cursor and Kiro load natively, plus `.claude-plugin/` (with the guard and done-gate hooks) and `.codex-plugin/` manifests.
 
-Maturity only changes the **reading path** in `AIES.md`.
+## Parallel agents
+
+```bash
+node scripts/aies-worktree.mjs new JIRA-123        # ../<repo>.worktrees/JIRA-123 on agent/JIRA-123
+# fill plans/JIRA-123-contract.md, run the agent in that worktree
+node scripts/aies-worktree.mjs check JIRA-123      # changed files vs contract allowed/prohibited paths
+node scripts/aies-worktree.mjs overlap             # files touched by more than one active task
+node scripts/aies-worktree.mjs remove JIRA-123
+```
 
-## MCP
+## What the audit checks
 
-`mcpServers` starts empty. `_aiesRecommended` holds enable-ready stubs (stack + enhance scan). Copy after human approval; never commit secrets.
+`audit` measures whether the harness *works*, not just whether files exist: verify commands are real (no `(fill in)` placeholders), the guard passes its self-test and is wired into the runtime's hook config, the definition-of-done gate lists commands and is wired where the runtime supports it, MCP config has no literal tokens, an eval suite exists, and no `*.aies-new` updates are waiting to be merged.
 
-Docs: https://www.ai-standards.dev/quickstart
+## Upgrading from 1.x or 2.0–2.1
 
-## Changelog
+1. Commit, then run `npx @grvmithas/create-aies-kit@latest enhance`. Installs before 2.2 have no `.aies-kit.json`, so any file that differs from the new kit version is treated as yours: it is kept and the new version lands in `<file>.aies-new`. Merge or delete those, or re-run with `--force` to take every kit version.
+2. 2.2 stops installing the unwired `hooks/*.hook.sh` scripts and the MCP specs your stack does not use; `enhance` deletes copies identical to what the kit shipped and leaves edited ones.
+3. Delete dead 1.x paths the runtime never loaded: root `copilot-instructions.md`, `.cursor/prompts/`, `.claude/prompts/`, `aies-hooks.json`, IDE-folder `*.skill.md`.
+4. Run `audit --min-score 100`.
 
-- **1.3.0** — Ephemeral `plans/{STORY_ID}-plan.md` + `reviews/{STORY_ID}-code-review.md`; agent hooks shipped; enhance-repo v2 with IDE chat invoke + deep guardrail scan (lint/style FE+BE).
-- **1.2.0** — Layout fix: cookbook/guides/mcps/templates at repo root for all IDEs; `.github` holds prompts/skills/agents (+ copilot-instructions) only.
-- **1.1.0** — Self-contained package (embedded corpus + generator).
-- **1.0.0** — Initial publish (incomplete; do not use).
+Docs: https://www.ai-standards.dev/quickstart · Changelog: [CHANGELOG.md](./CHANGELOG.md)

package/bin/create-aies-kit.js

@@ -2,7 +2,7 @@
 
 import { mkdir, writeFile, access, readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
-import { constants } from 'node:fs';
+import fs, { constants } from 'node:fs';
 import {
   GOALS,
   ROLES,
@@ -13,36 +13,53 @@ import {
   STACKS,
   STACK_LABELS,
   idsOf,
+  normalizeIde,
+  IDE_ALIASES,
+  KIT_VERSION,
 } from '../lib/kit-core/options.js';
-import { enhanceStarterKit, generateStarterKit, layoutFor } from '../lib/kit-core/generate.js';
+import { enhanceStarterKit, generatePluginBundle, generateStarterKit } from '../lib/kit-core/generate.js';
+import { applyBundle, readManifest, CONFLICT_SUFFIX, MANIFEST_FILE } from '../lib/kit-core/apply.js';
+import { detectVerifyCommands } from '../lib/kit-core/repo-scan.js';
+import { detectRepoSignals, stackMcpIds } from '../lib/kit-core/mcp-catalog.js';
 import { choose, confirm } from '../lib/prompts.js';
+import { runAudit } from '../lib/audit.js';
 
 function printHelp() {
   console.log(`
-create-aies-kit — complete AIES harness in IDE-native paths (no .aies/)
+create-aies-kit ${KIT_VERSION} — AIES harness in runtime-native paths
 
 Usage:
-  npx @grvmithas/create-aies-kit
-  npx @grvmithas/create-aies-kit --stack nextjs --ide cursor --role fullstack --maturity intermediate --goal new-product --model claude --data-class internal --yes
-  npx @grvmithas/create-aies-kit enhance
+  npx @grvmithas/create-aies-kit@latest
+  npx @grvmithas/create-aies-kit@latest --stack nextjs --ide cursor --role fullstack --maturity intermediate --goal new-product --model claude --data-class internal --yes
+  npx @grvmithas/create-aies-kit@latest enhance        rescan repo and upgrade the harness (keeps your edits; alias: upgrade)
+  npx @grvmithas/create-aies-kit@latest audit          score harness conformance (--format json, --min-score 100 for CI)
+  npx @grvmithas/create-aies-kit@latest fix            write missing harness files
+  npx @grvmithas/create-aies-kit@latest plugin --out ./aies-plugin   Agent Plugins 1.0 bundle (Cursor, Kiro, Claude Code, Codex)
 
-Install writes: AIES.md, implementation_plan.md, CLAUDE.md, AGENTS.md,
-IDE prompts/skills/agents under .cursor | .github | .claude | …
-plus repo-root cookbook/, guides/, mcps/, templates/ (never under .github/cookbook).
+Install writes:
+  AGENTS.md (canonical, with this repo's detected lint/typecheck/test commands) + tool rules file
+  AIES.md, MODEL_POLICY.md, implementation_plan.md
+  .agents/skills/<name>/SKILL.md (open Agent Skills standard)
+  native subagents + commands for the chosen runtime
+  hooks/aies-guard.mjs wired into the runtime's native hook config (deny unsafe shell, writes, reads)
+  evals/ (promptfoo harness evals) + templates/ci/aies-gates.yml (merge-blocking CI gates)
+  scripts/aies-worktree.mjs + plans/_TASK_CONTRACT.md (parallel agents)
+  empty MCP config + mcps/recommended.json (remote, OAuth; nothing enabled by default)
 
-
-After install, run enhance (no --yes needed) to scan the repo and refresh MCP recommendations, then
-run the enhance-repo prompt in your IDE.
+Re-running install or enhance never overwrites a file you edited: the new version goes to <file>.aies-new.
+${MANIFEST_FILE} records what the kit wrote — commit it.
 
 Flags:
   --stack       ${idsOf(STACKS).join(' | ')}
   --ide         ${idsOf(IDES).join(' | ')}
+                aliases: ${Object.entries(IDE_ALIASES).map(([a, t]) => `${a}→${t}`).join(', ')}
   --role        ${idsOf(ROLES).join(' | ')}
   --maturity    ${idsOf(MATURITIES).join(' | ')}
   --goal        ${idsOf(GOALS).join(' | ')}
   --model       ${idsOf(MODELS).join(' | ')}
   --data-class  ${idsOf(DATA_CLASSES).join(' | ')}
-  --force       Overwrite existing files
+  --out         Output directory for the plugin command (default ./aies-plugin)
+  --force       Replace files you edited with the kit version (default: write <file>.aies-new)
   --dry-run     Print files without writing
   --yes, -y     Non-interactive when profile flags are set
   --help, -h    Show help
@@ -127,6 +144,12 @@ async function recoverProfile(cwd, args) {
 
   if (Object.values(profile).every(Boolean)) return profile;
 
+  const saved = readManifest(cwd).profile;
+  if (saved) {
+    for (const key of Object.keys(profile)) profile[key] = profile[key] || saved[key];
+    if (Object.values(profile).every(Boolean)) return profile;
+  }
+
   try {
     const aies = await readFile(join(cwd, 'AIES.md'), 'utf8');
     const m = aies.match(
@@ -153,16 +176,85 @@ async function recoverProfile(cwd, args) {
 
 async function main() {
   const rawArgv = process.argv.slice(2);
-  const isEnhance = rawArgv[0] === 'enhance';
-  const args = parseArgs(isEnhance ? rawArgv.slice(1) : rawArgv);
+  const cmd = rawArgv[0];
+  const isAudit = cmd === 'audit';
+  const isFix = cmd === 'fix';
+  const isEnhance = cmd === 'enhance' || cmd === 'upgrade';
+  const isPlugin = cmd === 'plugin';
+
+  const args = parseArgs(isAudit || isFix || isEnhance || isPlugin ? rawArgv.slice(1) : rawArgv);
 
   if (args.help) {
     printHelp();
     return;
   }
 
+  if (args.version || cmd === '--version' || cmd === '-v') {
+    console.log(KIT_VERSION);
+    return;
+  }
+
   const cwd = resolve(process.cwd());
+
+  if (isPlugin) {
+    const out = resolve(cwd, String(args.out || 'aies-plugin'));
+    const bundle = generatePluginBundle({
+      stack: args.stack || 'nextjs',
+      ide: 'claude-code',
+      role: args.role || 'fullstack',
+      maturity: args.maturity || 'intermediate',
+      goal: args.goal || 'existing-codebase',
+      model: args.model || 'claude',
+      dataClass: args['data-class'] || 'internal',
+    });
+    const { written, skipped } = await writeBundle(out, bundle.files, { force: Boolean(args.force), dryRun: Boolean(args.dryRun) });
+    console.log(`\nAgent Plugins 1.0 bundle → ${out}`);
+    console.log(`${args.dryRun ? 'Would write' : 'Wrote'} ${written.length} file(s); skipped ${skipped.length}.`);
+    console.log('\nNext:');
+    console.log('  Cursor / Kiro: push the folder to a git repo and add it as a team plugin (reads plugin.json)');
+    console.log(`  Claude Code:   /plugin marketplace add ${out}  then  /plugin install aies@aies-marketplace`);
+    console.log('  Codex:         reads .codex-plugin/plugin.json; hooks come from the repo install');
+    return;
+  }
+
+  if (isAudit || isFix) {
+    let profile = await recoverProfile(cwd, args);
+    const minScore = args['min-score'] !== undefined ? Number(args['min-score']) : null;
+    const auditRes = await runAudit(cwd, { fix: isFix, profile });
+    if (minScore !== null && auditRes.score < minScore) process.exitCode = 1;
+
+    if (args.format === 'json') {
+      console.log(JSON.stringify(auditRes, null, 2));
+      return;
+    }
+
+    console.log(`\n🔍 AIES Harness Conformance ${isFix ? '& Auto-Fix Engine' : 'Audit'} — ${cwd}`);
+    console.log(`\nResults:`);
+    for (const r of auditRes.results) {
+      console.log(`  ${r.ok ? '✅' : '❌'} [${r.weight}pts] ${r.name}: ${r.msg}`);
+    }
+
+    if (auditRes.fixesApplied.length > 0) {
+      console.log(`\nAuto-Fix Remediations Applied:`);
+      for (const f of auditRes.fixesApplied) {
+        console.log(`  🛠️ ${f}`);
+      }
+    }
+
+    console.log(`\n----------------------------------------`);
+    console.log(`Score: ${auditRes.score}/100 (Grade: ${auditRes.grade})`);
+    console.log(`----------------------------------------`);
+
+    if (!isFix && auditRes.score < 100) {
+      console.log(`\n💡 Tip: Run "npx @grvmithas/create-aies-kit@latest fix" to create missing harness files (existing files are never overwritten).`);
+    }
+    if (minScore !== null && auditRes.score < minScore) {
+      console.log(`\n❌ Score ${auditRes.score} is below --min-score ${minScore}.`);
+    }
+    return;
+  }
   let profile = await recoverProfile(cwd, args);
+  if (profile.ide) profile.ide = normalizeIde(profile.ide);
 
   assertChoice('stack', profile.stack, idsOf(STACKS));
   assertChoice('ide', profile.ide, idsOf(IDES));
@@ -203,38 +295,48 @@ async function main() {
     }
   }
 
-  const bundle = isEnhance ? enhanceStarterKit(cwd, profile) : generateStarterKit(profile);
-  // enhance always overwrites generated harness files so MCP recommendations refresh
-  const force = Boolean(args.force) || isEnhance;
-  const { written, skipped } = await writeBundle(cwd, bundle.files, {
-    force,
+  const verify = detectVerifyCommands(cwd, fs);
+  const recommendedMcpIds = [...new Set([...stackMcpIds(profile.stack), ...detectRepoSignals(cwd, fs).recommendedMcpIds])];
+  const bundle = isEnhance ? enhanceStarterKit(cwd, profile) : generateStarterKit(profile, { verify, recommendedMcpIds });
+  const res = applyBundle(cwd, bundle.files, {
+    force: Boolean(args.force),
     dryRun: Boolean(args.dryRun),
+    retired: bundle.retired,
+    kitVersion: KIT_VERSION,
+    profile: bundle.profile,
   });
 
-  if (args.dryRun) {
-    console.log(`\nDry run — would write ${written.length} file(s):`);
-    written.slice(0, 40).forEach(f => console.log(`  ${f}`));
-    if (written.length > 40) console.log(`  … +${written.length - 40} more`);
-  } else {
-    console.log(`\nWrote ${written.length} file(s).`);
-    written.slice(0, 25).forEach(f => console.log(`  ✓ ${f}`));
-    if (written.length > 25) console.log(`  … +${written.length - 25} more`);
-  }
+  const list = (title, items, mark, max = 15) => {
+    if (!items.length) return;
+    console.log(`\n${title} (${items.length}):`);
+    items.slice(0, max).forEach(f => console.log(`  ${mark} ${f}`));
+    if (items.length > max) console.log(`  … +${items.length - max} more`);
+  };
+  const verb = args.dryRun ? 'Would ' : '';
+  list(`${verb}create`, res.created, '+', args.dryRun ? 40 : 15);
+  list(`${verb}update (untouched since the kit wrote them)`, res.updated, '~');
+  list(`${verb}remove (retired by this kit version, untouched)`, res.removed, '-');
+  list(`Kept your edits — review the new kit version in <file>${CONFLICT_SUFFIX}, merge, then delete it`, res.conflicts, '!', 40);
+  list('Retired by this kit version but edited by you — left in place; delete if unused', res.kept, '?');
+  console.log(`\n${res.unchanged.length} file(s) already current; ${res.customized.length} customized by you and kept (no kit change).`);
 
-  if (skipped.length > 0) {
-    console.log(`\nSkipped ${skipped.length} existing file(s) (use --force):`);
-    skipped.slice(0, 10).forEach(f => console.log(`  · ${f}`));
-  }
+  const found = Object.keys(verify.commands);
+  console.log(
+    found.length
+      ? `\nVerify commands detected (${verify.sources.join(', ')}): ${found.map(k => `${k} → ${verify.commands[k]}`).join(' · ')}`
+      : '\nNo lint/typecheck/test commands detected — fill the "(fill in)" lines in AGENTS.md; audit fails until you do.',
+  );
 
-  const L = layoutFor(profile.ide);
+  const enhanceCommand = Object.keys(bundle.files).find(f => /enhance-repo/.test(f) && !f.startsWith('cookbook/'));
+  const steps = ['Read AIES.md, then AGENTS.md'];
+  if (res.conflicts.length) steps.push(`Merge the ${res.conflicts.length} *${CONFLICT_SUFFIX} file(s), then delete them`);
+  if (enhanceCommand) steps.push(`Run the enhance-repo command (${enhanceCommand}) in your agent for conventions the scan cannot infer`);
+  steps.push('Copy templates/ci/aies-gates.yml to .github/workflows/ and make its jobs required checks');
+  steps.push('Commit .aies-kit.json; add *.aies-new and hooks/logs/ to .gitignore');
+  steps.push('npx @grvmithas/create-aies-kit@latest audit');
+  steps.push('https://www.ai-standards.dev/workflows');
   console.log('\nNext:');
-  console.log('  1. Read AIES.md');
-  if (!isEnhance) {
-    console.log('  2. npx @grvmithas/create-aies-kit enhance');
-  }
-  console.log(`  ${isEnhance ? '2' : '3'}. Run ${L.promptsDir}/enhance-repo.prompt.md in your IDE agent`);
-  console.log(`  ${isEnhance ? '3' : '4'}. Fill implementation_plan.md`);
-  console.log(`  ${isEnhance ? '4' : '5'}. https://www.ai-standards.dev/workflows`);
+  steps.forEach((s, i) => console.log(`  ${i + 1}. ${s}`));
 }
 
 main().catch(err => {