cli-five 0.2.13 → 0.2.16

package/README.md

@@ -1,6 +1,6 @@
 # cli-five
 
-> **Code Like I'm Five** — scaffold a 5-agent VS Code Copilot team into any repo.
+> **Code Like I'm Five** — scaffold a 5-agent AI team into any repo.
 
 ## Two ways to install
 
@@ -10,9 +10,16 @@
 npx cli-five init
 ```
 
-Interviews you, scaffolds agents + memory files + stack-specific instructions, discovers skills from **awesome-copilot** and **skills.sh**, 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.
 
-### Quick plugin install (personal use)
+```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)
 
 ```
 copilot plugin install idusortus/cli-five
@@ -20,20 +27,34 @@ copilot plugin install idusortus/cli-five
 
 Installs the 5 agents to your Copilot profile. No project config, no interview — just the agents with the same autonomous contracts shipped by the scaffolded templates.
 
+## Supported platforms
+
+cli-five can scaffold for:
+
+- **GitHub Copilot** — `.github/agents/*.agent.md` + `copilot-instructions.md`
+- **OpenCode** — `.opencode/agents/*.md` + `opencode.json`
+
+Both platforms can optionally include a **CodeGraph** MCP server and instructions.
+
+Run `npx cli-five init` and choose your platform. If you want both, run it again in the same repo.
+
 ## What you get
 
+### GitHub Copilot layout
+
 ```
 your-repo/
 ├── .github/
 │   ├── agents/                  # 5 agents — Orchestrator delegates autonomously
-│   │   ├── orchestrator.agent.md  # Routes tasks: Planner → Coder/Designer → Reviewer
-│   │   ├── planner.agent.md       # Researches codebase, produces implementation plans
-│   │   ├── coder.agent.md         # Writes production code, runs tests
-│   │   ├── designer.agent.md      # UI/UX design, layouts, theming
-│   │   └── reviewer.agent.md      # Code review, convention compliance
-│   ├── copilot-instructions.md  # Persona + project mandates from interview
-│   ├── instructions/            # Stack-specific coding guidelines
-│   └── skills/                  # Installed skills from awesome-copilot + skills.sh
+│   │   ├── orchestrator.agent.md
+│   │   ├── planner.agent.md
+│   │   ├── coder.agent.md
+│   │   ├── designer.agent.md
+│   │   └── reviewer.agent.md
+│   ├── 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)
 ├── STATE.md                     # Cross-session status (changes constantly)
@@ -42,9 +63,31 @@ your-repo/
 └── histories/                   # Per-agent accumulated learnings
 ```
 
+### OpenCode layout
+
+```
+your-repo/
+├── .opencode/
+│   └── agents/                  # 5 agents — Orchestrator delegates autonomously
+│       ├── orchestrator.md
+│       ├── planner.md
+│       ├── coder.md
+│       ├── designer.md
+│       └── reviewer.md
+├── opencode.json                # Project config, model defaults, CodeGraph MCP (optional)
+├── .github/instructions/        # Container; stack guidelines via --instructions
+├── .github/skills/              # Container; skills via --skills
+├── AGENTS.md                    # Project rules + optional CodeGraph block
+├── PROJECT.md
+├── STATE.md
+├── decisions.md
+├── agent-diary.md
+└── histories/
+```
+
 ## How it works
 
-Select the **Orchestrator** agent in Copilot Chat and describe what you want. The Orchestrator autonomously calls Planner → Coder/Designer → Reviewer without any manual handoff clicks.
+Select the **Orchestrator** agent and describe what you want. The Orchestrator autonomously calls Planner → Coder/Designer → Reviewer without any manual handoff clicks.
 
 ```
 User: implement from plan.md
@@ -53,13 +96,16 @@ Orchestrator → [calls Planner] → [calls Coder] → [calls Reviewer] → done
 
 No buttons. No "click here to continue". Just results.
 
-The plugin agents and scaffolded `.github/agents/*.agent.md` templates are intentionally kept in sync. The repository test suite now checks that parity so the quick-install path does not quietly degrade.
+The plugin agents and scaffolded `.github/agents/*.agent.md` templates are intentionally kept in sync. The repository test suite checks that parity so the quick-install path does not quietly degrade.
 
 ## Commands
 
 ```bash
-npx cli-five init              # interview + scaffold + skill discovery
-npx cli-five doctor            # validate an existing setup
+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
 ```
@@ -68,38 +114,99 @@ 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 |
-| `--cost-mode <m>` | Set cost mode: `premium`, `cheap`, or `mixed` |
+| `--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; 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. **git init** — if needed. Asks first.
-3. **Overwrite gate** — double-confirms ("Proceed?" then "R U Sure?"). Only `--force --yes` bypasses.
-4. **Interview** — name, one-liner, stack, frameworks, goals, constraints, cost mode, persona toggle.
-5. **Scaffold** — writes 18 files. Substitutes answers into templates. Swaps `model:` per cost mode.
-6. **Skill discovery** — the hero feature. Multi-source discovery from **awesome-copilot** (30k+ ★ community marketplace) and **skills.sh**. Color-coded recommendations, source attribution, multiselect install, and post-install breadcrumbs with copy-paste commands for the awesome-copilot suggestion skill and MCP server.
-7. **Custom instructions** — generates stack-specific `.instructions.md` files for detected languages.
-8. **Next steps** — tells you to open Copilot Chat, select Orchestrator, and start building. No button-clicking required.
+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 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>`.
 
-## Cost modes
+```bash
+npx cli-five add            # list known targets
+npx cli-five add codegraph  # stub in this release
+npx cli-five list-addons    # installed vs. available status
+```
+
+This release ships the **dispatcher and merge utility** only — no integration is wired in yet. Jev and the CodeGraph migration are future commits.
+
+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.
+
+## Model providers
+
+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 |
+|---|---|---|
+| GitHub Copilot | Copilot | `Claude Sonnet 4.6 (copilot)` |
+| OpenCode Zen | OpenCode | `opencode/gpt-5.3-codex` |
+| OpenCode Go | OpenCode | `opencode-go/qwen3.8-max` |
+
+`--yes` uses the provider's defaults. `--provider opencode-go --yes` skips the provider prompt.
+
+### Copilot cost modes
 
 | Agent | `premium` (1x–3x) | `cheap` (0x) | `mixed` |
 |---|---|---|---|
 | Orchestrator | Claude Sonnet 4.6 | GPT-4.1 | GPT-4.1 |
 | Planner | Claude Opus 4.6 | GPT-4o | GPT-4o |
 | Coder | GPT-5.3-Codex | GPT-4.1 | GPT-5.3-Codex |
-| Designer | Claude Opus 4.6 | GPT-4o | GPT-4o |
-| Reviewer | Claude Opus 4.6 | GPT-5 mini | Claude Opus 4.6 |
+| Designer | Gemini 3.1 Pro (Preview) | GPT-4o | GPT-4o |
+| Reviewer | Claude Sonnet 4.6 | GPT-5 mini | Claude Sonnet 4.6 |
 
 Override from CLI: `npx cli-five init --cost-mode cheap`
-Change anytime by editing the `model:` line in `.github/agents/*.agent.md`.
+Change anytime by editing the `model:` line in the agent files.
 
-## Required VS Code settings
+## CodeGraph
+
+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`.
+- Tells you to run `codegraph init` to index the project.
+
+cli-five does **not** install or run the CodeGraph CLI automatically. After scaffolding:
+
+```bash
+npm i -g @colbymchenry/codegraph
+codegraph init
+```
+
+## Required settings
+
+### GitHub Copilot
 
 ```jsonc
 {
@@ -107,9 +214,13 @@ Change anytime by editing the `model:` line in `.github/agents/*.agent.md`.
 }
 ```
 
+### OpenCode
+
+No extra settings required. Project agents live in `.opencode/agents/` and the project config in `opencode.json`.
+
 ## 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 |
 |---|---|---|
@@ -127,7 +238,7 @@ Take time to read each installed skill so you understand what it does and can ca
 ## What this is not
 
 - **Not a runtime.** Once scaffolded, your repo doesn't depend on `cli-five`. You can uninstall the package and the agents still work.
-- **Not a workflow engine.** No `/plan-phase`, no `/ship`, no 50 slash commands. Use `/agent-customization` in Copilot Chat to extend.
+- **Not a workflow engine.** No `/plan-phase`, no `/ship`, no 50 slash commands. Use `/agent-customization` in Copilot Chat or OpenCode commands to extend.
 - **Not Ralph.** No issue-polling daemons, no autonomous loops, no crypto tokens.
 
 ## Why the name
@@ -144,6 +255,7 @@ ELI5 → CLI5. Code Like I'm Five. Five agents. Get it? Yeah, it's a stretch. Bu
 
 - The plugin install path and the scaffolded project path are both supported and now validated against each other.
 - `npm test` includes agent integrity checks in addition to the existing skill-step tests.
+- Google Antigravity AGY CLI support is planned but not implemented yet.
 
 ## Local development
 

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "cli-five",
-  "version": "0.2.13",
-  "description": "Code Like I'm Five — scaffold a 5-agent VS Code Copilot team into any repo.",
+  "version": "0.2.16",
+  "description": "Code Like I'm Five — scaffold a 5-agent AI team (GitHub Copilot or OpenCode) into any repo.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/idusortus/cli-five.git"
+  },
+  "homepage": "https://github.com/idusortus/cli-five#readme",
+  "bugs": {
+    "url": "https://github.com/idusortus/cli-five/issues"
+  },
   "bin": {
     "cli-five": "bin/cli-five.mjs"
   },
@@ -24,6 +32,8 @@
   },
   "keywords": [
     "copilot",
+    "opencode",
+    "codegraph",
     "vscode",
     "agents",
     "scaffold",
@@ -33,6 +43,7 @@
   "dependencies": {
     "kleur": "^4.1.5",
     "prompts": "^2.4.2",
-    "skills": "^1.5.0"
+    "skills": "^1.5.0",
+    "yaml": "^2.8.3"
   }
 }

package/plugin-agents/designer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: Designer
 description: "Handles all UI/UX design tasks. Use when: creating screens, layouts, theming, navigation flows, design systems."
-model: Claude Opus 4.6 (copilot)
+model: Gemini 3.1 Pro (Preview) (copilot)
 tools: ['read', 'edit', 'search', 'web', 'io.github.upstash/context7/*', 'vscode/memory']
 agents: []
 ---
@@ -10,7 +10,7 @@ agents: []
 
 | Mode | Model | Premium Cost |
 |---|---|---|
-| **Default** | Claude Opus 4.6 | 3x |
+| **Default** | Gemini 3.1 Pro (Preview) (copilot) | 1x |
 | **Cheap** | GPT-4o | 0x (free) |
 
 To switch: change the `model` key in frontmatter above.

package/plugin-agents/planner.agent.md

@@ -13,7 +13,7 @@ You create plans. You do NOT write code.
 
 | Mode | Model | Premium Cost |
 |---|---|---|
-| **Default** | Claude Sonnet 4.6 | 1x |
+| **Default** | Claude Opus 4.6 | 3x |
 | **Cheap** | GPT-4o | 0x (free) |
 
 To switch: change the `model` key in frontmatter above.

package/src/addons/registry.mjs

@@ -0,0 +1,96 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * 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.',
+    available: false,
+    note: 'Currently installed by init (on by default). `add` migration is a future commit.',
+    detect: detectCodeGraph,
+    run: null,
+  },
+  jev: {
+    name: 'jev',
+    label: 'Jev',
+    description: 'Optional Jev integration (purpose to be defined in a future commit).',
+    available: false,
+    note: 'Reserved target. No integration wired in this release.',
+    detect: () => [],
+    run: null,
+  },
+};
+
+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;
+  }
+}

package/src/cli.mjs

@@ -5,16 +5,20 @@ 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')}
-Scaffold a 5-agent Copilot team into any repo.
+Scaffold a 5-agent AI team into any repo.
 
 ${kleur.bold('Usage')}
   npx cli-five <command> [options]
 
 ${kleur.bold('Commands')}
-  init            Interview + scaffold .github/* and 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,9 +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)
   --cwd <path>    Run against a directory other than the current one
   --version, -v   Print version and exit
 `;
@@ -37,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':
@@ -60,15 +78,40 @@ export async function run(argv) {
 }
 
 function parse(argv) {
-  const out = { _: [], yes: false, force: false, dryRun: false, skills: true, docs: [], costMode: null, cwd: process.cwd() };
+  const out = {
+    _: [],
+    yes: false,
+    force: false,
+    dryRun: false,
+    fullInterview: false,
+    skills: null,
+    instructions: null,
+    persona: null,
+    codegraph: null,
+    docs: [],
+    costMode: null,
+    target: null,
+    provider: null,
+    cwd: process.cwd(),
+  };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     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];
+    else if (a === '--target') out.target = argv[++i];
+    else if (a === '--provider') out.provider = argv[++i];
     else if (a === '--cwd') out.cwd = argv[++i];
     else if (a === '--help' || a === '-h') out._.push('help');
     else if (a === '--version' || a === '-v') out._.push('--version');

package/src/commands/add.mjs

@@ -0,0 +1,55 @@
+import kleur from 'kleur';
+import { log } from '../util/log.mjs';
+import { ADDON_NAMES, getAddon, listAddons } from '../addons/registry.mjs';
+
+/**
+ * `cli-five add <name>` — dispatch to a registered add-on.
+ *
+ * This pass ships the dispatcher only. Registered targets without a `run`
+ * function respond with a clear stub so the mechanism can be exercised
+ * end-to-end without pretending an integration exists.
+ */
+export async function add(args) {
+  const name = args._[1];
+
+  if (!name || name === '--help' || name === '-h' || name === 'help') {
+    printAddHelp();
+    return;
+  }
+
+  const addon = getAddon(name);
+  if (!addon) {
+    log.err(`Unknown add-on: ${name}`);
+    printAvailable(addon => addon.name);
+    process.exitCode = 2;
+    return;
+  }
+
+  if (typeof addon.run !== 'function') {
+    log.warn(`${addon.label} is registered but not implemented yet.`);
+    log.info('The add dispatcher works — this target is reserved for a future release.');
+    if (addon.note) log.dim(addon.note);
+    log.dim('Nothing was written to your project.');
+    return;
+  }
+
+  log.step(`add ${addon.name}`);
+  await addon.run({ cwd: args.cwd, args });
+}
+
+function printAddHelp() {
+  process.stdout.write(`${kleur.bold('cli-five add')} — install an optional add-on\n\n`);
+  process.stdout.write(`${kleur.bold('Usage')}\n  npx cli-five add <name>\n\n`);
+  printAvailable();
+}
+
+function printAvailable() {
+  process.stdout.write(`${kleur.bold('Available add-ons')}\n`);
+  for (const addon of listAddons()) {
+    const addable = typeof addon.run === 'function';
+    const statusText = (addable ? 'available' : 'planned').padEnd(10);
+    const status = addable ? kleur.green(statusText) : kleur.yellow(statusText);
+    process.stdout.write(`  ${addon.name.padEnd(12)} ${status} ${kleur.dim(addon.description)}\n`);
+  }
+  process.stdout.write(`\n${kleur.dim(`Known names: ${ADDON_NAMES.join(', ')}`)}\n`);
+}