cli-five 0.2.15 → 0.2.17

package/README.md

@@ -10,7 +10,14 @@
 npx cli-five init
 ```
 
-Interviews you, lets you pick a target platform and model provider, scaffolds agents + memory files + stack-specific instructions, discovers skills, and tells you what to do next.
+By default `init` is **minimal**: it scaffolds the 5-agent team and the tooling they need, asking only for the target platform and (when it can't find them) your project name and one-liner. Name and description are auto-pulled from `package.json` and `README.md`. Optional integrations — including CodeGraph, skills, and instruction files — are **not** installed unless you ask.
+
+```bash
+npx cli-five init --full-interview   # legacy: docs, goals, persona, model picker, CodeGraph, skills, instructions
+npx cli-five init --codegraph        # minimal, but add the CodeGraph MCP + AGENTS.md block
+```
+
+`--full-interview` (or passing `--doc`) restores the complete guided setup: stack presets, goals, constraints, persona toggle, per-agent model overrides, Copilot cost modes, CodeGraph, skill discovery, and stack-specific instruction generation. Individual pieces can also be toggled with `--codegraph`, `--skills`, `--instructions`, and `--persona`.
 
 ### Quick plugin install (personal use, Copilot only)
 
@@ -44,9 +51,9 @@ your-repo/
 │   │   ├── coder.agent.md
 │   │   ├── designer.agent.md
 │   │   └── reviewer.agent.md
-│   ├── copilot-instructions.md  # Persona + project mandates from interview
-│   ├── instructions/            # Stack-specific coding guidelines
-│   └── skills/                  # Installed skills from awesome-copilot + skills.sh
+│   ├── copilot-instructions.md  # Project mandates (persona is opt-in)
+│   ├── instructions/            # Container; stack guidelines via --instructions
+│   └── skills/                  # Container; skills via --skills
 ├── .vscode/mcp.json             # CodeGraph MCP server (optional)
 ├── AGENTS.md                    # Tool-agnostic project context (agents.md standard)
 ├── PROJECT.md                   # Long-form vision (rarely changes)
@@ -68,8 +75,8 @@ your-repo/
 │       ├── designer.md
 │       └── reviewer.md
 ├── opencode.json                # Project config, model defaults, CodeGraph MCP (optional)
-├── .github/instructions/        # Stack-specific coding guidelines
-├── .github/skills/              # Installed skills
+├── .github/instructions/        # Container; stack guidelines via --instructions
+├── .github/skills/              # Container; skills via --skills
 ├── AGENTS.md                    # Project rules + optional CodeGraph block
 ├── PROJECT.md
 ├── STATE.md
@@ -94,7 +101,10 @@ The plugin agents and scaffolded `.github/agents/*.agent.md` templates are inten
 ## Commands
 
 ```bash
-npx cli-five init              # interview + scaffold + skill discovery
+npx cli-five init              # minimal scaffold (5 agents + required tooling)
+npx cli-five init --full-interview  # full guided setup (interview, models, skills, instructions)
+npx cli-five add <name>        # install an optional add-on (dispatcher; targets land later)
+npx cli-five list-addons       # show installed vs. available add-ons
 npx cli-five doctor            # validate an existing cli-five setup
 npx cli-five list-stacks       # show detectable tech stacks
 npx cli-five help
@@ -104,33 +114,97 @@ npx cli-five help
 
 | Flag | Effect |
 |---|---|
-| `--yes`, `-y` | Accept interview defaults (overwrite gate still active) |
+| `--yes`, `-y` | Accept defaults (overwrite gate still active) |
 | `--force` | Overwrite without confirmation (use with `--yes`) |
 | `--dry-run` | Print actions, write nothing |
-| `--no-skills` | Skip skills.sh discovery step |
-| `--no-codegraph` | Skip CodeGraph MCP + instructions |
+| `--full-interview`, `--full` | Run the full legacy interview (docs, goals/constraints/persona, model picker). Also enables CodeGraph, skills + instructions |
+| `--skills` / `--no-skills` | Force skill discovery on/off |
+| `--instructions` / `--no-instructions` | Force stack-specific instruction generation on/off |
+| `--persona` / `--no-persona` | Include / omit the snarky persona block |
+| `--codegraph` / `--no-codegraph` | Force CodeGraph MCP + instructions on/off (default: on with `--full-interview`, off otherwise) |
 | `--target <t>` | Target platform: `copilot` or `opencode` (default: `copilot`) |
 | `--provider <p>` | Model provider: `copilot`, `opencode`, `opencode-go` (default: platform default) |
 | `--cost-mode <m>` | Set cost mode for Copilot: `premium`, `cheap`, or `mixed` |
-| `--doc <file>` | Read project docs to pre-fill interview (repeatable) |
+| `--doc <file>` | Read project docs to pre-fill interview (repeatable; implies `--full-interview`) |
 | `--cwd <path>` | Run against a different directory |
 
 ## What `init` does
 
+Default (`npx cli-five init`):
+
 1. **Detect** — fingerprints stack (Node/TS, Python, .NET, Kotlin, Rust, Go, etc.). Brownfield-aware.
-2. **Choose platform** — GitHub Copilot or OpenCode, with optional CodeGraph pairing.
+2. **Choose platform** — explicit `--target`, auto-detected from an existing scaffold, or prompted.
 3. **git init** — if needed. Asks first.
 4. **Overwrite gate** — double-confirms ("Proceed?" then "R U Sure?"). Only `--force --yes` bypasses.
-5. **Project info** — name, one-liner, stack, frameworks, goals, constraints, persona toggle.
-6. **Model configuration** — pick a provider and optionally override each agent's model.
-7. **Scaffold** — writes platform-specific files. Swaps `model:` per provider/selection.
-8. **Skill discovery** — multi-source discovery from **awesome-copilot** and **skills.sh**.
-9. **Custom instructions** — generates stack-specific `.instructions.md` files for detected languages.
-10. **Next steps** — platform-specific instructions. No button-clicking required.
+5. **Project info** — name and one-liner auto-pulled from `package.json` / `README.md`; asks only when missing or ambiguous.
+6. **Model configuration** — platform/provider defaults, no prompt.
+7. **Scaffold** — writes the 5 agents + required project memory/tooling files. Swaps `model:` per provider defaults.
+8. **Done** — prints platform-specific next steps.
+
+`--full-interview` additionally runs:
+
+- **Docs / manual interview** — project docs, stack preset, goals, constraints.
+- **Model customization** — provider picker + per-agent model overrides.
+- **Persona toggle** — snarky persona block.
+- **CodeGraph** — MCP registration + `AGENTS.md` block (also available standalone via `--codegraph`).
+- **Skill discovery** — multi-source discovery from **awesome-copilot** and **skills.sh**.
+- **Custom instructions** — stack-specific `.instructions.md` files for detected languages.
+
+## Add-ons
+
+Optional integrations live outside the default scaffold and are installed with `cli-five add <name>`.
+
+```bash
+npx cli-five add            # list known targets
+npx cli-five add codegraph  # CodeGraph MCP registration + AGENTS.md instructions
+npx cli-five add jev        # tier-routing tool for the Planner (OpenCode only)
+npx cli-five list-addons    # installed vs. available status
+```
+
+Add-ons use `mergeBlock(file, markerFence, content)` to layer a fenced block into an existing JSON or Markdown file without touching the rest of it (distinct from init's blunt overwrite gate). Markdown gets `<!-- NAME_START -->` / `<!-- NAME_END -->` fences; JSON is deep-merged with existing keys preserved. Re-running an add-on is idempotent — no duplicate MCP entries or AGENTS.md sections.
+
+### CodeGraph (`add codegraph`)
+
+`add codegraph` registers the CodeGraph MCP server and adds the CodeGraph section to `AGENTS.md`. It works on **both platforms**:
+
+| Target | MCP registration | Instructions |
+|---|---|---|
+| Copilot | `.vscode/mcp.json` → `servers.codegraph` | `AGENTS.md` block |
+| OpenCode | `opencode.json` → `mcp.codegraph` | `AGENTS.md` block |
+
+**The `init` flags are now thin wrappers.** `init --codegraph` and `init --no-codegraph` still behave exactly as before, but they call the *same* underlying `add codegraph` logic — one implementation, two entry points. CodeGraph remains off by default in minimal `init` and on with `--full-interview`; pass `--codegraph` to force it on, `--no-codegraph` to force it off.
+
+cli-five still does **not** run `codegraph init` itself — it only registers the server and reminds you to index the project:
+
+```bash
+npm i -g @colbymchenry/codegraph
+codegraph init
+```
+
+### Jev (`add jev`) — tier-routing only, OpenCode only
+
+`add jev` scaffolds an OpenCode plugin that adds a `local_tier_heuristic` tool. The Planner calls it once per task to classify the work as `trivial` / `minor` / `major`, then scales planning depth accordingly.
+
+**Two things it deliberately does *not* do, stated plainly:**
+
+1. **It does not call Jev.** `jev-harness` 0.2.0's `route` subcommand exposes no custom-criteria interface — it emits its own fixed tier vocabulary (`deterministic` / `lightweight_system2` / `heavy_system2`) and returns a constant confidence (`0.88`) under its offline/mock engine, so it cannot be thresholded on. The shipped tool is therefore a **local heuristic**, truthfully named `local_tier_heuristic`. The swap point for real Jev wiring is marked in `templates/opencode/plugin/jev-tier-router/index.js` (`JEVR_SWAP_POINT`).
+2. **The test-gate is parked.** Gating Reviewer spawns via plugin interception (`tool.execute.before` / `permission.ask`) does not work: OpenCode plugin hooks do not fire under OpenChamber's embedded-server routing. Do not expect `add jev` to gate anything.
+
+`list-addons` reports each add-on's honest capability rather than a bare "installed":
+
+```
+codegraph   installed (MCP registration + AGENTS.md instructions)   available   MCP registration + AGENTS.md instructions
+jev         installed (tier-routing only)                           available   local heuristic — …; test-gate parked — <issue link>
+```
+
+**Fail-open is non-negotiable.** If the classifier is unavailable, errors, or returns malformed output, the tool returns `available: false` with tier `major` (the expensive tier) and never throws. The Planner falls back to its own judgment. cli-five and the scaffolded agents behave identically whether the plugin works, is missing, or is broken.
+
+**Copilot has no equivalent.** `add jev` refuses cleanly on a Copilot target (exit 1, no files written) — there is no `tools.add`-style surface there.
+
 
 ## Model providers
 
-During `init` you can choose the model provider and optionally customize each agent's model.
+During `init --full-interview` you can choose the model provider and optionally customize each agent's model. The minimal `init` path uses provider defaults (honouring `--provider` and `--cost-mode`).
 
 | Provider | Platform | Example model |
 |---|---|---|
@@ -155,7 +229,7 @@ Change anytime by editing the `model:` line in the agent files.
 
 ## CodeGraph
 
-CodeGraph adds a local, graph-backed codebase context server. When enabled, cli-five:
+CodeGraph adds a local, graph-backed codebase context server. It is **off by default** in the minimal scaffold; enable it with `--codegraph` or `--full-interview`. When enabled, cli-five:
 
 - Registers the CodeGraph MCP server in `opencode.json` (OpenCode) or `.vscode/mcp.json` (Copilot).
 - Adds a marker-fenced CodeGraph section to `AGENTS.md`.
@@ -184,7 +258,7 @@ No extra settings required. Project agents live in `.opencode/agents/` and the p
 
 ## Skill discovery
 
-cli-five searches **two sources** for skills matching your detected stack:
+Skill discovery runs during `init --full-interview` (or when you pass `--skills`). cli-five searches **two sources** for skills matching your detected stack:
 
 | Source | What it has | Stars |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-five",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Code Like I'm Five — scaffold a 5-agent AI team (GitHub Copilot or OpenCode) into any repo.",
   "type": "module",
   "repository": {

package/src/addons/codegraph-command.mjs

@@ -0,0 +1,47 @@
+import kleur from 'kleur';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { log } from '../util/log.mjs';
+import { PLATFORM_COPILOT, PLATFORM_OPENCODE, platformLabel } from '../util/platforms.mjs';
+import { addCodegraphTo, CODEGRAPH_INIT_REMINDER, mcpTargetFor } from './codegraph.mjs';
+
+/**
+ * `add codegraph` — register the CodeGraph MCP server + AGENTS.md section.
+ *
+ * Works on both platforms. Same content and behavior as the previous inline
+ * init implementation; only the invocation path and write mechanism changed
+ * (mergeBlock instead of blunt overwrite).
+ */
+export async function runCodegraph({ cwd, args = {} }) {
+  const platform = detectPlatform(cwd);
+
+  if (platform === 'unknown') {
+    log.err('No cli-five scaffold detected (neither .opencode/agents nor .github/agents).');
+    log.dim('Run `npx cli-five init` first, then `npx cli-five add codegraph`.');
+    process.exitCode = 1;
+    return [];
+  }
+
+  const dryRun = Boolean(args.dryRun);
+  const touched = addCodegraphTo({ cwd, platform, dryRun, track: true });
+
+  for (const t of touched) {
+    const rel = t.path.replace(cwd + '/', '');
+    const symbol = t.action === 'created' || t.action === 'updated' ? '+' : '~';
+    log.raw(`  ${symbol} ${rel} ${kleur.dim(`(${t.action})`)}`);
+  }
+
+  log.ok(`CodeGraph registered for ${platformLabel(platform)}`);
+  log.dim(`MCP: ${mcpTargetFor(platform)} · instructions: AGENTS.md`);
+  log.dim(CODEGRAPH_INIT_REMINDER.replace('CodeGraph is configured. ', ''));
+
+  return touched;
+}
+
+function detectPlatform(cwd) {
+  if (existsSync(join(cwd, '.opencode', 'agents'))) return PLATFORM_OPENCODE;
+  if (existsSync(join(cwd, '.github', 'agents', 'orchestrator.agent.md'))) return PLATFORM_COPILOT;
+  return 'unknown';
+}
+
+export const __testables = { detectPlatform };

package/src/addons/codegraph.mjs

@@ -0,0 +1,124 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { mergeBlock } from '../util/merge.mjs';
+import { PLATFORM_COPILOT, PLATFORM_OPENCODE } from '../util/platforms.mjs';
+
+export const CODEGRAPH_STATUS = 'MCP registration + AGENTS.md instructions';
+export const CODEGRAPH_BLOCK_NAME = 'codegraph';
+export const CODEGRAPH_INIT_REMINDER =
+  'CodeGraph is configured. Remember to run `codegraph init` before asking agents to explore the codebase.';
+
+// The AGENTS.md section is byte-identical to the pre-migration inline constant
+// in scaffold.mjs. Do not change its content — only the write path changed.
+export const CODEGRAPH_BLOCK = `## CodeGraph
+
+This project is configured to use [CodeGraph](https://codegraph.ru) for graph-backed codebase context.
+When you need to understand relationships, call paths, or impacts, use:
+
+\`\`\`
+codegraph explore "<your question>"
+\`\`\`
+
+The CodeGraph MCP server is registered in the project config. Run \`codegraph init\` in this directory
+if the project has not been indexed yet.`;
+
+/**
+ * The CodeGraph MCP server entries, per platform. Unchanged from the previous
+ * inline implementation — same server, same command, same shape.
+ */
+export function codegraphOpencodeConfig() {
+  return {
+    codegraph: {
+      type: 'local',
+      command: ['codegraph', 'serve', '--mcp'],
+      enabled: true,
+    },
+  };
+}
+
+export function codegraphCopilotMcpJson() {
+  return {
+    inputs: [],
+    servers: {
+      codegraph: {
+        command: 'codegraph',
+        args: ['serve', '--mcp'],
+      },
+    },
+  };
+}
+
+/** Which MCP file a given platform owns. Preserves the old per-platform split. */
+export function mcpTargetFor(platform) {
+  return platform === PLATFORM_OPENCODE ? 'opencode.json' : join('.vscode', 'mcp.json');
+}
+
+/**
+ * Register CodeGraph in a workspace, using mergeBlock() for every write.
+ *
+ * Shared by `add codegraph` and init's legacy --codegraph flag — one
+ * implementation, two entry points.
+ *
+ * @returns {Array<{path:string, action:string}>} the files touched.
+ */
+export function addCodegraphTo({ cwd, platform, dryRun = false, track = false }) {
+  const touched = [];
+  const isOpenCode = platform === PLATFORM_OPENCODE;
+
+  // 1. MCP registration.
+  if (isOpenCode) {
+    const opencodePath = join(cwd, 'opencode.json');
+    // Preserve a pre-existing `plugins[]` (e.g. jev): deepMerge replaces arrays,
+    // so carry the existing value through untouched at the root.
+    const existing = readJson(opencodePath) || {};
+    const patch = { mcp: codegraphOpencodeConfig() };
+    if (Array.isArray(existing.plugins)) patch.plugins = existing.plugins;
+    touched.push(mergeBlock(opencodePath, 'codegraph', patch, { dryRun, track }));
+  } else {
+    const mcpPath = join(cwd, '.vscode', 'mcp.json');
+    const existing = readJson(mcpPath) || {};
+    // Preserve the old key order (`inputs` first) so output matches the
+    // pre-migration inline implementation byte-for-byte. `inputs` is an array;
+    // carry it through so deepMerge's array-replace is a no-op.
+    const patch = { inputs: Array.isArray(existing.inputs) ? existing.inputs : [] };
+    patch.servers = { codegraph: codegraphCopilotMcpJson().servers.codegraph };
+    touched.push(mergeBlock(mcpPath, 'codegraph', patch, { dryRun, track }));
+  }
+
+  // 2. AGENTS.md section (fenced block; same marker name as the old template).
+  const agentsPath = join(cwd, 'AGENTS.md');
+  touched.push(mergeBlock(agentsPath, CODEGRAPH_BLOCK_NAME, CODEGRAPH_BLOCK, { dryRun }));
+
+  return touched;
+}
+
+/**
+ * Idempotent remove-of-duplicates is intentionally NOT implemented: mergeBlock
+ * already replaces an existing fenced block in place and deep-merges JSON, so
+ * re-running add codegraph does not duplicate anything.
+ */
+export function isCodegraphPresent(cwd, platform) {
+  const mcpPath = join(cwd, mcpTargetFor(platform));
+  const cfg = readJson(mcpPath);
+  if (platform === PLATFORM_OPENCODE) return Boolean(cfg?.mcp?.codegraph);
+  return Boolean(cfg?.servers?.codegraph);
+}
+
+function readJson(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Ensure a file exists with given content (used for a created-not-merged file). */
+export function ensureFile(filePath, contents) {
+  if (existsSync(filePath)) return false;
+  mkdirSync(dirname(filePath), { recursive: true });
+  writeFileSync(filePath, contents);
+  return true;
+}
+
+export const __testables = { readJson, mcpTargetFor };

package/src/addons/jev.mjs

@@ -0,0 +1,98 @@
+import kleur from 'kleur';
+import { existsSync, readFileSync, cpSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { log } from '../util/log.mjs';
+import { mergeBlock } from '../util/merge.mjs';
+import { templatePath } from '../util/fs.mjs';
+
+export const JEVR_STATUS =
+  'local heuristic — jev-harness lacks a custom-criteria interface as of 2026-09-26';
+export const JEVR_TOOL = 'local_tier_heuristic';
+export const TEST_GATE_ISSUE = 'https://github.com/idusortus/cli-five/issues';
+
+const PLUGIN_REL = join('.opencode', 'plugin', 'jev-tier-router');
+
+/**
+ * `add jev` — tier-routing only.
+ *
+ * Ships a local tier-classification tool for the Planner. Does NOT wire the
+ * test-gate (parked: OpenCode plugin hooks don't fire under OpenChamber's
+ * embedded-server routing) and does NOT call Jev (no custom-criteria
+ * interface in jev-harness as of this release).
+ */
+export async function runJev({ cwd, args }) {
+  const platform = detectPlatform(cwd);
+
+  if (platform !== 'opencode') {
+    log.err('jev is OpenCode-only. No tools.add-equivalent surface exists for Copilot.');
+    log.dim('Re-run init with --target opencode, then `npx cli-five add jev`.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const written = [];
+
+  // 1. Plugin directory (package.json + index.js), confirmed convention.
+  const pluginDir = join(cwd, PLUGIN_REL);
+  mkdirSync(pluginDir, { recursive: true });
+  for (const file of ['package.json', 'index.js']) {
+    const src = templatePath('opencode', 'plugin', 'jev-tier-router', file);
+    const dest = join(pluginDir, file);
+    cpSync(src, dest);
+    written.push({ path: dest, written: true });
+  }
+
+  // 2. Register the plugin path in opencode.json's `plugins` array.
+  //    mergeBlock deep-merges JSON but replaces arrays, so read the existing
+  //    array, union it, and hand the unioned value to mergeBlock (single
+  //    write path — no second merge approach).
+  const opencodePath = join(cwd, 'opencode.json');
+  const plugins = readPlugins(opencodePath);
+  const pluginRef = toPosix(PLUGIN_REL);
+  if (!plugins.includes(pluginRef)) plugins.push(pluginRef);
+  mergeBlock(opencodePath, 'jev', { plugins }, { track: true, metaKey: '$cliFive' });
+
+  // 3. Planner instruction in AGENTS.md (fenced block, idempotent).
+  const agentsPath = join(cwd, 'AGENTS.md');
+  mergeBlock(agentsPath, 'jev-tier-routing', plannerInstruction());
+
+  log.ok(`Plugin written to ${kleur.bold(toPosix(PLUGIN_REL))}`);
+  log.ok(`Registered in opencode.json (plugins[])`);
+  log.ok('Planner instruction added to AGENTS.md');
+  log.raw('');
+  log.info(`Tool: ${kleur.bold(JEVR_TOOL)} (tier-routing only)`);
+  log.warn('Status: ' + JEVR_STATUS);
+  log.dim(`Test-gate is parked — see ${TEST_GATE_ISSUE}`);
+}
+
+function plannerInstruction() {
+  return `## Tier routing (local heuristic)
+
+Before planning, call the \`${JEVR_TOOL}\` tool once with the task description.
+
+- If it returns \`confidence\` >= 0.6, use its \`tier\` (trivial | minor | major) as your planning depth.
+- If \`confidence\` < 0.6, or the tool is unavailable, use your own judgment and default to \`major\`.
+- This is a local heuristic, not a Jev call. Never block or fail a turn because the tool is unavailable.`;
+}
+
+function readPlugins(opencodePath) {
+  if (!existsSync(opencodePath)) return [];
+  try {
+    const cfg = JSON.parse(readFileSync(opencodePath, 'utf8'));
+    return Array.isArray(cfg.plugins) ? [...cfg.plugins] : [];
+  } catch {
+    return [];
+  }
+}
+
+function detectPlatform(cwd) {
+  if (existsSync(join(cwd, '.opencode', 'agents'))) return 'opencode';
+  if (existsSync(join(cwd, '.github', 'agents', 'orchestrator.agent.md'))) return 'copilot';
+  return 'unknown';
+}
+
+function toPosix(p) {
+  return p.split('\\').join('/');
+}
+
+export const __testables = { plannerInstruction, readPlugins, detectPlatform };

package/src/addons/registry.mjs

@@ -0,0 +1,126 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runJev, JEVR_STATUS, TEST_GATE_ISSUE } from './jev.mjs';
+import { runCodegraph } from './codegraph-command.mjs';
+import { CODEGRAPH_STATUS } from './codegraph.mjs';
+
+/**
+ * Add-on registry for `cli-five add <name>`.
+ *
+ * An add-on describes an optional integration that can be layered onto an
+ * already-scaffolded repo. Entries without a `run` function are reserved
+ * (dispatcher/stub) targets — the mechanism is live, the integration is not.
+ *
+ * To wire a real target later: give it a `run({ cwd, args })` function (the
+ * `add` command will invoke it) and update `available`/`note` accordingly.
+ */
+export const ADDONS = {
+  codegraph: {
+    name: 'codegraph',
+    label: 'CodeGraph',
+    description: 'Graph-backed codebase context MCP server and agent instructions.',
+    // Matches jev's status-object pattern: explicit capability + status string,
+    // not a bare boolean.
+    available: true,
+    capability: 'MCP registration + AGENTS.md instructions',
+    status: CODEGRAPH_STATUS,
+    platforms: ['copilot', 'opencode'],
+    detect: detectCodeGraph,
+    run: runCodegraph,
+  },
+  jev: {
+    name: 'jev',
+    label: 'Jev',
+    description: 'Tier-routing tool for the Planner (local heuristic; test-gate parked).',
+    // Not a bare boolean: jev ships tier-routing ONLY. The test-gate half is
+    // parked because OpenCode plugin hooks don't fire under OpenChamber routing.
+    available: true,
+    capability: 'tier-routing only',
+    status: `${JEVR_STATUS}; test-gate parked — ${TEST_GATE_ISSUE}`,
+    platforms: ['opencode'],
+    detect: detectJev,
+    run: runJev,
+  },
+};
+
+export const ADDON_NAMES = Object.keys(ADDONS);
+
+export function listAddons() {
+  return Object.values(ADDONS);
+}
+
+export function getAddon(name) {
+  if (!name) return undefined;
+  return ADDONS[String(name).toLowerCase()];
+}
+
+/**
+ * Inspect a workspace for evidence that an add-on is already present.
+ * Returns a list of human-readable signals (empty when not detected).
+ */
+export function detectAddon(addon, cwd) {
+  if (!addon || typeof addon.detect !== 'function') return [];
+  try {
+    return addon.detect(cwd) || [];
+  } catch {
+    return [];
+  }
+}
+
+// ── Detectors ─────────────────────────────────────────────────────────
+
+/**
+ * Detect CodeGraph artifacts written by init today. Read-only: this inspects
+ * existing registration without modifying it.
+ */
+export function detectCodeGraph(cwd) {
+  const signals = [];
+
+  const opencodePath = join(cwd, 'opencode.json');
+  const opencodeCfg = readJson(opencodePath);
+  if (opencodeCfg?.mcp?.codegraph) signals.push('opencode.json mcp.codegraph');
+
+  const mcpPath = join(cwd, '.vscode', 'mcp.json');
+  const mcpCfg = readJson(mcpPath);
+  if (mcpCfg?.servers?.codegraph) signals.push('.vscode/mcp.json servers.codegraph');
+
+  const agentsPath = join(cwd, 'AGENTS.md');
+  if (existsSync(agentsPath)) {
+    try {
+      const body = readFileSync(agentsPath, 'utf8');
+      if (body.includes('<!-- CODEGRAPH_START -->')) signals.push('AGENTS.md CodeGraph section');
+    } catch {
+      /* ignore */
+    }
+  }
+
+  return signals;
+}
+
+function readJson(filePath) {
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Detect the jev tier-router plugin: its directory on disk and/or its entry in
+ * opencode.json's `plugins` array. Read-only.
+ */
+export function detectJev(cwd) {
+  const signals = [];
+
+  if (existsSync(join(cwd, '.opencode', 'plugin', 'jev-tier-router', 'index.js'))) {
+    signals.push('.opencode/plugin/jev-tier-router');
+  }
+
+  const cfg = readJson(join(cwd, 'opencode.json'));
+  if (Array.isArray(cfg?.plugins) && cfg.plugins.some((p) => String(p).includes('jev-tier-router'))) {
+    signals.push('opencode.json plugins[]');
+  }
+
+  return signals;
+}

package/src/cli.mjs

@@ -5,6 +5,8 @@ import { join } from 'node:path';
 import { init } from './commands/init.mjs';
 import { doctor } from './commands/doctor.mjs';
 import { listStacks } from './commands/list-stacks.mjs';
+import { add } from './commands/add.mjs';
+import { listAddonsCommand } from './commands/list-addons.mjs';
 import { STACK_SIGNATURES } from './steps/detect.mjs';
 
 const HELP = `${kleur.bold('cli-five')} ${kleur.gray('— Code Like I\'m Five')}
@@ -14,7 +16,9 @@ ${kleur.bold('Usage')}
   npx cli-five <command> [options]
 
 ${kleur.bold('Commands')}
-  init            Interview + scaffold agents + project memory files
+  init            Scaffold the 5 agents + required tooling (minimal by default)
+  add <name>      Install an optional add-on (dispatcher; targets land later)
+  list-addons     Show installed vs. available add-ons
   doctor          Validate an existing cli-five setup
   list-stacks     Show detectable tech stacks
   help            Show this message
@@ -23,12 +27,19 @@ ${kleur.bold('Flags')}
   --yes, -y       Accept defaults and skip confirmations (still gated on overwrite)
   --force         Overwrite without confirmation. Dangerous. Use with --yes.
   --dry-run       Print actions without writing files
+  --full-interview Run the full legacy interview (docs, goals, persona, models). Enables CodeGraph by default
+  --skills        Force skill discovery (default: full interview only)
   --no-skills     Skip the skills.sh discovery step
-  --doc <file>    Read project docs to pre-fill interview (repeatable)
+  --instructions  Force stack-specific instruction generation
+  --no-instructions Skip instruction generation
+  --persona       Include the snarky persona block
+  --no-persona    Omit the snarky persona block
+  --codegraph     Add CodeGraph MCP + instructions (default: only with --full-interview)
+  --no-codegraph  Skip CodeGraph MCP + instructions
+  --doc <file>    Read project docs to pre-fill interview (repeatable; implies --full-interview)
   --cost-mode <m> Override cost mode (premium, cheap, mixed) — skips interview question
   --target <t>    Target platform: copilot or opencode (default: copilot)
   --provider <p>  Model provider: copilot, opencode, opencode-go (default: platform default)
-  --no-codegraph  Skip CodeGraph MCP + instructions
   --cwd <path>    Run against a directory other than the current one
   --version, -v   Print version and exit
 `;
@@ -40,6 +51,10 @@ export async function run(argv) {
   switch (cmd) {
     case 'init':
       return init(args);
+    case 'add':
+      return add(args);
+    case 'list-addons':
+      return listAddonsCommand(args);
     case 'doctor':
       return doctor(args);
     case 'list-stacks':
@@ -68,8 +83,11 @@ function parse(argv) {
     yes: false,
     force: false,
     dryRun: false,
-    skills: true,
-    codegraph: true,
+    fullInterview: false,
+    skills: null,
+    instructions: null,
+    persona: null,
+    codegraph: null,
     docs: [],
     costMode: null,
     target: null,
@@ -81,7 +99,14 @@ function parse(argv) {
     if (a === '--yes' || a === '-y') out.yes = true;
     else if (a === '--force') out.force = true;
     else if (a === '--dry-run') out.dryRun = true;
+    else if (a === '--full-interview' || a === '--full') out.fullInterview = true;
+    else if (a === '--skills') out.skills = true;
     else if (a === '--no-skills') out.skills = false;
+    else if (a === '--instructions') out.instructions = true;
+    else if (a === '--no-instructions') out.instructions = false;
+    else if (a === '--persona') out.persona = true;
+    else if (a === '--no-persona') out.persona = false;
+    else if (a === '--codegraph') out.codegraph = true;
     else if (a === '--no-codegraph') out.codegraph = false;
     else if (a === '--doc') out.docs.push(argv[++i]);
     else if (a === '--cost-mode') out.costMode = argv[++i];