cli-five 0.2.15 → 0.2.16

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,59 @@ 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  # 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` 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 +191,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 +220,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.16",
   "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/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,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];

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`);
+}

package/src/commands/init.mjs

@@ -5,18 +5,30 @@ import { resolve, basename, join, extname } from 'node:path';
 import { log } from '../util/log.mjs';
 import { detect } from '../steps/detect.mjs';
 import { confirmOverwriteIfNeeded } from '../steps/confirm.mjs';
-import { interview } from '../steps/interview.mjs';
+import { interview, minimalInterview } from '../steps/interview.mjs';
 import { scaffold, summarize } from '../steps/scaffold.mjs';
 import { skillDiscovery } from '../steps/skills.mjs';
 import { instructionGeneration } from '../steps/instructions.mjs';
-import { choosePlatform, chooseModels } from '../steps/platform.mjs';
+import { choosePlatform, chooseModels, resolveCodegraphDefault } from '../steps/platform.mjs';
 import { isGitRepo, gitInit } from '../util/git.mjs';
 import { platformLabel } from '../util/platforms.mjs';
+import { autoProjectInfo } from '../util/project.mjs';
 
 export async function init(args) {
   const cwd = args.cwd;
   log.raw(kleur.bold().magenta('\ncli-five init') + kleur.gray(`  ${cwd}`));
 
+  // ── Mode ───────────────────────────────────────────────────────────
+  // Default init is minimal: the 5 agents + required tooling, asking only for
+  // platform and (when needed) name/one-liner. The legacy interview — docs,
+  // goals/constraints/persona, model customization, skills, instructions — is
+  // opt-in via --full-interview (or --doc). Per-feature flags can also force
+  // skills/instructions/persona without the whole interview.
+  const docs = Array.isArray(args.docs) ? args.docs : [];
+  const fullInterview = Boolean(args.fullInterview) || docs.length > 0;
+  const runSkills = args.skills !== null ? Boolean(args.skills) : fullInterview;
+  const runInstructions = args.instructions !== null ? Boolean(args.instructions) : fullInterview;
+
   // 1. Detect
   log.step('1/8 Detect workspace');
   const detected = detect(cwd);
@@ -27,10 +39,17 @@ export async function init(args) {
 
   // 2. Platform + CodeGraph
   log.step('2/8 Choose platform');
-  const { platform, codegraph } = await choosePlatform(args);
+  const codegraphDefault = resolveCodegraphDefault(args, fullInterview);
+  const { platform, codegraph } = await choosePlatform(args, {
+    autoDetect: !fullInterview,
+    askCodegraph: fullInterview && args.codegraph === null,
+    codegraphDefault,
+  });
   log.info(`Target:  ${kleur.bold(platformLabel(platform))}`);
   if (codegraph) log.info(`CodeGraph: ${kleur.green('enabled')}`);
-  else log.info('CodeGraph: disabled');
+  else if (fullInterview || args.codegraph === false) log.info('CodeGraph: disabled');
+  else log.info(`CodeGraph: ${kleur.gray('disabled')} ${kleur.dim('(enable with --codegraph or --full-interview)')}`);
+  if (!fullInterview) log.dim('Minimal init. Full interview: npx cli-five init --full-interview');
 
   // 3. git init if needed
   if (!detected.hasGit) {
@@ -51,43 +70,57 @@ export async function init(args) {
   }
   if (!detected.hasAgents && !detected.hasCopilotInstructions) log.dim('No collisions.');
 
-  // 5. Input mode — docs or manual interview
-  log.step('4/8 Project info');
+  // 5. Project info + model configuration
+  args.__platform = platform;
   let docHints;
+  let modelConfig;
+
+  if (fullInterview) {
+    log.step('4/8 Project info');
+    if (docs.length > 0) {
+      // --doc was passed on the CLI — validate with retry
+      docHints = loadDocs(docs, cwd);
+      if (docHints.files.length === 0) {
+        log.warn('None of the --doc files could be loaded.');
+      }
+    } else if (args.yes) {
+      docHints = loadDocs([], cwd);
+    } else {
+      docHints = await collectDocFiles(cwd);
+    }
 
-  if (args.docs.length > 0) {
-    // --doc was passed on the CLI — validate with retry
-    docHints = loadDocs(args.docs, cwd);
-    if (docHints.files.length === 0) {
-      log.warn('None of the --doc files could be loaded.');
+    if (docHints.files.length > 0 && docs.length > 0) {
+      log.info(`Loaded ${docHints.files.length} doc${docHints.files.length > 1 ? 's' : ''}: ${docHints.files.join(', ')}`);
+      if (docHints.projectName) log.dim(`  → project name: ${docHints.projectName}`);
+      if (docHints.oneLiner) log.dim(`  → description: ${docHints.oneLiner}`);
     }
-  } else if (args.yes) {
-    docHints = loadDocs([], cwd);
+
+    log.step('5/8 Model configuration');
+    modelConfig = await chooseModels(platform, args);
   } else {
-    docHints = await collectDocFiles(cwd);
-  }
+    log.step('4/8 Project info');
+    docHints = autoProjectInfo(cwd);
+    logAutoProjectInfo(docHints);
 
-  if (docHints.files.length > 0 && args.docs.length > 0) {
-    log.info(`Loaded ${docHints.files.length} doc${docHints.files.length > 1 ? 's' : ''}: ${docHints.files.join(', ')}`);
-    if (docHints.projectName) log.dim(`  → project name: ${docHints.projectName}`);
-    if (docHints.oneLiner) log.dim(`  → description: ${docHints.oneLiner}`);
+    log.step('5/8 Model configuration');
+    // Minimal path uses provider defaults without prompting (still honours --provider).
+    modelConfig = await chooseModels(platform, { ...args, yes: true });
   }
 
-  // 6. Model configuration
-  log.step('5/8 Model configuration');
-  const modelConfig = await chooseModels(platform, args);
   log.info(`Provider: ${kleur.bold(modelConfig.provider)}`);
   if (modelConfig.customized) log.info('Models:  customized');
   else log.info('Models:  defaults');
 
-  // 7. Interview (pre-filled from docs if available, otherwise manual)
-  args.__platform = platform;
-  const answers = await interview(detected, args, docHints);
+  // 6. Interview (minimal by default, full behind --full-interview)
+  const answers = fullInterview
+    ? await interview(detected, args, docHints)
+    : await minimalInterview(detected, args, docHints);
 
-  // CLI --cost-mode override
+  // CLI overrides — apply to both paths.
   if (args.costMode && ['premium', 'cheap', 'mixed'].includes(args.costMode)) {
     answers.costMode = args.costMode;
   }
+  if (args.persona !== null) answers.snark = Boolean(args.persona);
 
   // Attach platform/model choices to answers so scaffold can use them.
   answers.platform = platform;
@@ -101,30 +134,56 @@ export async function init(args) {
   }
   if (answers.frameworks.length) log.info(`Stack:  ${answers.stack.join(', ')} + ${answers.frameworks.join(', ')}`);
 
-  // 8. Scaffold
+  // 7. Scaffold
   log.step('6/8 Scaffold');
   const written = scaffold({ cwd, answers, args });
   if (args.dryRun) log.warn('--dry-run: no files written. Plan:');
   log.raw(summarize(written, cwd));
   if (!args.dryRun) log.ok(`Wrote ${written.length} files.`);
 
-  // 9. Skill discovery
+  // 8. Skill discovery
   log.step('7/8 Skill discovery');
-  await skillDiscovery({ cwd, answers, args });
+  if (runSkills) {
+    await skillDiscovery({ cwd, answers, args: { ...args, skills: true } });
+  } else {
+    log.dim('Skipped (minimal init). Enable with --skills or --full-interview.');
+  }
 
-  // 10. Custom instructions
+  // 9. Custom instructions
   log.step('8/8 Custom instructions');
-  const instrWritten = await instructionGeneration({ cwd, answers, args });
-  if (instrWritten && instrWritten.length > 0) {
-    if (args.dryRun) log.warn('--dry-run: instruction plan:');
-    for (const w of instrWritten) {
-      log.raw(`  ${w.written ? '+' : '~'} ${w.path.replace(cwd + '/', '')}`);
+  if (runInstructions) {
+    const instrWritten = await instructionGeneration({ cwd, answers, args });
+    if (instrWritten && instrWritten.length > 0) {
+      if (args.dryRun) log.warn('--dry-run: instruction plan:');
+      for (const w of instrWritten) {
+        log.raw(`  ${w.written ? '+' : '~'} ${w.path.replace(cwd + '/', '')}`);
+      }
+      if (!args.dryRun) log.ok(`Wrote ${instrWritten.length} instruction file${instrWritten.length > 1 ? 's' : ''}.`);
     }
-    if (!args.dryRun) log.ok(`Wrote ${instrWritten.length} instruction file${instrWritten.length > 1 ? 's' : ''}.`);
+  } else {
+    log.dim('Skipped (minimal init). Enable with --instructions or --full-interview.');
   }
 
-  // 11. Next steps
-  printNextSteps(answers);
+  // 10. Next steps
+  printNextSteps(answers, { generatedInstructions: runInstructions });
+}
+
+/** Log which project fields were auto-pulled from the workspace. */
+function logAutoProjectInfo(info) {
+  const name = info?.name || {};
+  const oneLiner = info?.oneLiner || {};
+
+  if (name.value && !name.ambiguous) {
+    log.info(`Name:    ${kleur.bold(name.value)} ${kleur.gray(`(${name.sources[0].source})`)}`);
+  } else if (name.ambiguous) {
+    log.warn(`Multiple project names found (${name.sources.map((s) => s.source).join(', ')}) — asking.`);
+  }
+
+  if (oneLiner.value && !oneLiner.ambiguous) {
+    log.info(`Tagline: ${oneLiner.value} ${kleur.gray(`(${oneLiner.sources[0].source})`)}`);
+  } else if (oneLiner.ambiguous) {
+    log.warn(`Multiple descriptions found (${oneLiner.sources.map((s) => s.source).join(', ')}) — asking.`);
+  }
 }
 
 async function ask(message, initial = false) {
@@ -132,7 +191,7 @@ async function ask(message, initial = false) {
   return Boolean(v);
 }
 
-function printNextSteps(answers) {
+function printNextSteps(answers, { generatedInstructions = false } = {}) {
   const hasDocs = answers.docFiles?.length > 0;
   const platform = answers.platform || 'copilot';
   const codegraph = answers.codegraph;
@@ -165,8 +224,10 @@ function printNextSteps(answers) {
   } else {
     log.raw(kleur.gray(`        read PROJECT.md and implement Phase 1.`));
   }
-  log.raw(`  6. Review generated instruction files in .github/instructions/.`);
-  log.raw(kleur.gray(`        Edit applyTo globs and guidelines to fit your project.`));
+  if (generatedInstructions) {
+    log.raw(`  6. Review generated instruction files in .github/instructions/.`);
+    log.raw(kleur.gray(`        Edit applyTo globs and guidelines to fit your project.`));
+  }
 
   if (codegraph) {
     log.raw('');
@@ -183,6 +244,9 @@ function printNextSteps(answers) {
     log.raw('');
     log.raw(kleur.dim('Edit agent models anytime by changing `model:` in .opencode/agents/*.md.'));
   }
+
+  log.raw('');
+  log.raw(kleur.dim('Optional integrations: npx cli-five list-addons'));
   log.raw('');
 }
 

package/src/commands/list-addons.mjs

@@ -0,0 +1,40 @@
+import kleur from 'kleur';
+import { log } from '../util/log.mjs';
+import { detectAddon, listAddons } from '../addons/registry.mjs';
+
+/**
+ * `cli-five list-addons` — show what is installed vs. available.
+ *
+ * "Installed" is detected read-only from workspace artifacts. CodeGraph is
+ * listed honestly even though its `add` plumbing has not moved yet.
+ */
+export function listAddonsCommand(args) {
+  const cwd = args.cwd;
+  log.raw(kleur.bold().magenta('\ncli-five list-addons') + kleur.gray(`  ${cwd}`));
+  log.raw('');
+
+  log.raw(`  ${kleur.gray(pad('ADD-ON', 12))} ${kleur.gray(pad('STATUS', 12))} ${kleur.gray(pad('ADD', 10))} ${kleur.gray('DETAIL')}`);
+  log.raw(`  ${'─'.repeat(12)} ${'─'.repeat(12)} ${'─'.repeat(10)} ${'─'.repeat(30)}`);
+
+  for (const addon of listAddons()) {
+    const signals = detectAddon(addon, cwd);
+    const installed = signals.length > 0;
+    const addable = typeof addon.run === 'function';
+    const detail = installed ? signals.join(', ') : addon.note || '';
+
+    const statusText = pad(installed ? 'installed' : 'not found', 12);
+    const status = installed ? kleur.green(statusText) : kleur.gray(statusText);
+    const addableText = pad(addable ? 'available' : 'planned', 10);
+    const addableColored = addable ? kleur.green(addableText) : kleur.yellow(addableText);
+
+    log.raw(`  ${pad(addon.name, 12)} ${status} ${addableColored} ${kleur.dim(detail)}`);
+  }
+
+  log.raw('');
+  log.dim('Install with `npx cli-five add <name>` once a target is available.');
+  log.raw('');
+}
+
+function pad(value, width) {
+  return String(value).padEnd(width);
+}

package/src/steps/interview.mjs

@@ -195,6 +195,65 @@ export async function interview(detected, args, docHints = {}) {
   });
 }
 
+/**
+ * Minimal interview — the default `init` path.
+ *
+ * Asks for the project name and one-liner only, and only when `projectInfo`
+ * could not confidently supply them. Everything else (stack, goals,
+ * constraints, persona, cost mode) falls back to `defaults`.
+ *
+ * `projectInfo` is the shape returned by `autoProjectInfo(cwd)`.
+ */
+export async function minimalInterview(detected, args, projectInfo = {}) {
+  const platform = args.__platform || 'copilot';
+  const nameInfo = projectInfo.name || {};
+  const oneLinerInfo = projectInfo.oneLiner || {};
+
+  let projectName = nameInfo.value || '';
+  let oneLiner = oneLinerInfo.value || '';
+
+  if (!args.yes) {
+    const questions = [];
+
+    if (!projectName || nameInfo.ambiguous) {
+      questions.push({
+        type: 'text',
+        name: 'projectName',
+        message: 'Project name',
+        initial: projectName || detected.projectName,
+      });
+    }
+
+    if (!oneLiner || oneLinerInfo.ambiguous) {
+      questions.push({
+        type: 'text',
+        name: 'oneLiner',
+        message: 'One-line description (becomes PROJECT.md vision)',
+        initial: oneLiner || '',
+      });
+    }
+
+    if (questions.length > 0) {
+      const answers = await prompts(questions, {
+        onCancel: () => {
+          throw new Error('Interview cancelled. Nothing was written.');
+        },
+      });
+      if (answers.projectName !== undefined) projectName = answers.projectName;
+      if (answers.oneLiner !== undefined) oneLiner = answers.oneLiner;
+    }
+  }
+
+  const base = defaults(detected, { projectName, oneLiner }, platform);
+  return normalize({
+    ...base,
+    projectName: (projectName || detected.projectName || '').trim(),
+    oneLiner: (oneLiner || '').trim(),
+    // Persona is opt-in on the minimal path (--persona / --full-interview).
+    snark: args.persona === true,
+  });
+}
+
 /** Default stack is first preset when nothing is detected and --yes is used. */
 function defaults(detected, docHints = {}, platform = 'copilot') {
   const hasDetected = detected.stacks.length > 0;

package/src/steps/platform.mjs

@@ -1,5 +1,7 @@
 import kleur from 'kleur';
 import prompts from 'prompts';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import {
   PLATFORM_COPILOT,
   PLATFORM_OPENCODE,
@@ -21,20 +23,50 @@ import {
 
 const CUSTOM_SENTINEL = '__custom__';
 
+/**
+ * Resolve whether CodeGraph should be enabled when no explicit `--codegraph`
+ * / `--no-codegraph` value was passed.
+ *
+ * The registration/opt-out mechanism is unchanged — this only decides the
+ * default: on for the full interview, off for minimal init.
+ */
+export function resolveCodegraphDefault(args, fullInterview) {
+  if (args.codegraph === true || args.codegraph === false) return args.codegraph;
+  return Boolean(fullInterview);
+}
+
 /**
  * Ask the user to choose a target platform.
  * If args.target is a valid platform, skip the prompt.
+ *
+ * Options:
+ *   autoDetect   — infer the platform from an existing scaffold before prompting
+ *   askCodegraph — whether to ask the CodeGraph opt-out question (full interview)
+ *   codegraphDefault — resolved default when no explicit flag was passed
+ *
+ * Note: CodeGraph registration and the `--no-codegraph` opt-out are unchanged;
+ * this only controls whether the question is asked / what the default is.
  */
-export async function choosePlatform(args) {
+export async function choosePlatform(args, { autoDetect = false, askCodegraph = true, codegraphDefault } = {}) {
+  if (codegraphDefault === undefined) codegraphDefault = args.codegraph !== false;
+
   if (args.target) {
     const t = String(args.target).toLowerCase();
     if (PLATFORMS.includes(t)) {
-      return { platform: t, codegraph: args.codegraph !== false };
+      return { platform: t, codegraph: codegraphDefault };
+    }
+  }
+
+  if (autoDetect) {
+    const existing = detectExistingPlatform(args.cwd);
+    if (existing) {
+      log.dim(`Detected existing ${platformLabel(existing)} scaffold.`);
+      return { platform: existing, codegraph: codegraphDefault };
     }
   }
 
   if (args.yes) {
-    return { platform: PLATFORM_COPILOT, codegraph: args.codegraph !== false };
+    return { platform: PLATFORM_COPILOT, codegraph: codegraphDefault };
   }
 
   const { platform } = await prompts({
@@ -60,6 +92,10 @@ export async function choosePlatform(args) {
     throw new Error('Platform selection cancelled. Nothing was written.');
   }
 
+  if (!askCodegraph) {
+    return { platform, codegraph: codegraphDefault };
+  }
+
   const { codegraph } = await prompts({
     type: 'confirm',
     name: 'codegraph',
@@ -70,6 +106,13 @@ export async function choosePlatform(args) {
   return { platform, codegraph: codegraph !== false };
 }
 
+/** Infer an existing scaffold's platform, or null when there is no scaffold. */
+export function detectExistingPlatform(cwd) {
+  if (existsSync(join(cwd, '.opencode', 'agents'))) return PLATFORM_OPENCODE;
+  if (existsSync(join(cwd, '.github', 'agents', 'orchestrator.agent.md'))) return PLATFORM_COPILOT;
+  return null;
+}
+
 /**
  * Ask the user whether to customize models, pick a provider, and optionally
  * override per-agent models.

package/src/util/merge.mjs

@@ -0,0 +1,170 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, extname } from 'node:path';
+
+const JSON_EXTENSIONS = new Set(['.json']);
+
+/**
+ * Surgically merge a named block into an existing file **without touching the
+ * rest of it**. Unlike init's blunt overwrite gate (which replaces whole files),
+ * `mergeBlock` is designed for `cli-five add` against repos that are already
+ * scaffolded.
+ *
+ * Two strategies, chosen by file extension:
+ *
+ *   JSON (.json)
+ *     `content` (a plain object or a JSON string) is deep-merged into the file.
+ *     Existing keys are preserved; overlapping scalar/array keys are replaced.
+ *     Passing `fenceKey` nests the patch under that top-level key instead of
+ *     merging at the root (e.g. `{ fenceKey: 'mcp' }` for `opencode.json`).
+ *
+ *   Markdown / other text
+ *     `content` is wrapped in HTML-comment fences derived from `markerFence`:
+ *       <!-- NAME_START -->
+ *       ...content...
+ *       <!-- NAME_END -->
+ *     If the fences already exist the body between them is replaced in place;
+ *     otherwise the block is appended. Re-running is idempotent.
+ *
+ * @param {string} filePath              Absolute path to the target file.
+ * @param {string|{name?:string,start?:string,end?:string}} markerFence
+ *        Block name (e.g. "codegraph"), or explicit `{ start, end }` markers.
+ * @param {string|object} content        Markdown body, or object / JSON string.
+ * @param {object} [options]
+ * @param {boolean} [options.dryRun]     Compute but do not write.
+ * @param {string|null} [options.fenceKey] JSON only — nest the merge under this key.
+ * @param {boolean} [options.track]      JSON only — record the block name under `$cliFive`.
+ * @param {string} [options.metaKey]     JSON only — metadata key (default `$cliFive`).
+ * @returns {{path:string, block:string, action:'created'|'updated'|'unchanged', dryRun:boolean}}
+ */
+export function mergeBlock(filePath, markerFence, content, options = {}) {
+  const { dryRun = false, fenceKey = null, track = false, metaKey = '$cliFive' } = options;
+  const block = fenceName(markerFence);
+
+  const ext = extname(filePath).toLowerCase();
+  const result = JSON_EXTENSIONS.has(ext)
+    ? mergeJson(filePath, block, content, { fenceKey, track, metaKey })
+    : mergeText(filePath, markerFence, content);
+
+  if (!dryRun && (result.action === 'created' || result.action === 'updated')) {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, result.contents);
+  }
+
+  return { path: filePath, block, action: result.action, dryRun };
+}
+
+// ── Markdown / text ───────────────────────────────────────────────────
+
+function mergeText(filePath, markerFence, content) {
+  const { start, end } = fenceMarkers(markerFence);
+  const body = String(content ?? '').replace(/\s+$/, '');
+  const core = `${start}\n${body}\n${end}`;
+
+  if (!existsSync(filePath)) {
+    return { contents: `${core}\n`, action: 'created' };
+  }
+
+  const existing = readFileSync(filePath, 'utf8');
+  if (existing.trim() === '') {
+    return { contents: `${core}\n`, action: 'created' };
+  }
+
+  const pattern = new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`);
+  if (pattern.test(existing)) {
+    const next = existing.replace(pattern, core);
+    return { contents: next, action: next === existing ? 'unchanged' : 'updated' };
+  }
+
+  const next = `${existing.replace(/\s+$/, '')}\n\n${core}\n`;
+  return { contents: next, action: 'updated' };
+}
+
+function fenceMarkers(markerFence) {
+  if (isPlainObject(markerFence) && markerFence.start && markerFence.end) {
+    return { start: markerFence.start, end: markerFence.end };
+  }
+  const name = fenceName(markerFence).toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return { start: `<!-- ${name}_START -->`, end: `<!-- ${name}_END -->` };
+}
+
+// ── JSON ──────────────────────────────────────────────────────────────
+
+function mergeJson(filePath, block, content, { fenceKey, track, metaKey }) {
+  let existing = {};
+  if (existsSync(filePath)) {
+    const raw = readFileSync(filePath, 'utf8').trim();
+    if (raw) {
+      try {
+        existing = JSON.parse(raw);
+      } catch (err) {
+        throw new Error(`mergeBlock: ${filePath} is not valid JSON: ${err.message}`);
+      }
+    }
+  }
+
+  if (!isPlainObject(existing)) {
+    throw new Error(`mergeBlock: ${filePath} must contain a JSON object at the root`);
+  }
+
+  let patch = content;
+  if (typeof patch === 'string') {
+    try {
+      patch = JSON.parse(patch);
+    } catch (err) {
+      throw new Error(`mergeBlock: content for ${filePath} is not valid JSON: ${err.message}`);
+    }
+  }
+  if (!isPlainObject(patch)) {
+    throw new Error(`mergeBlock: content for ${filePath} must be a JSON object`);
+  }
+
+  const before = JSON.stringify(existing);
+
+  const target = fenceKey
+    ? (isPlainObject(existing[fenceKey]) ? existing[fenceKey] : (existing[fenceKey] = {}))
+    : existing;
+  deepMerge(target, patch);
+
+  if (track) {
+    const meta = isPlainObject(existing[metaKey]) ? existing[metaKey] : (existing[metaKey] = {});
+    const blocks = Array.isArray(meta.blocks) ? meta.blocks : (meta.blocks = []);
+    if (!blocks.includes(block)) blocks.push(block);
+  }
+
+  const contents = `${JSON.stringify(existing, null, 2)}\n`;
+  const action = before === JSON.stringify(existing) && existsSync(filePath) ? 'unchanged' : (existsSync(filePath) ? 'updated' : 'created');
+  return { contents, action };
+}
+
+function deepMerge(target, patch) {
+  for (const [key, value] of Object.entries(patch)) {
+    if (isPlainObject(value) && isPlainObject(target[key])) {
+      deepMerge(target[key], value);
+    } else if (isPlainObject(value)) {
+      target[key] = deepMerge({}, value);
+    } else if (Array.isArray(value)) {
+      target[key] = [...value];
+    } else {
+      target[key] = value;
+    }
+  }
+  return target;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────
+
+function fenceName(markerFence) {
+  if (typeof markerFence === 'string' && markerFence.trim()) return markerFence.trim();
+  if (isPlainObject(markerFence) && typeof markerFence.name === 'string' && markerFence.name.trim()) {
+    return markerFence.name.trim();
+  }
+  throw new Error('mergeBlock: markerFence must be a non-empty string or { name }');
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/util/project.mjs

@@ -0,0 +1,140 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// README variants checked in order. First match wins.
+const README_CANDIDATES = [
+  'README.md',
+  'readme.md',
+  'Readme.md',
+  'README.MD',
+  'README.markdown',
+  'README.txt',
+  'README',
+];
+
+/**
+ * Best-effort auto-extraction of a project name and one-liner from the
+ * workspace itself (package.json and/or README), used by the minimal init
+ * interview so it only has to ask when the answer is genuinely missing or
+ * ambiguous.
+ *
+ * Returns:
+ *   {
+ *     name:     { value, ambiguous, sources: [{ source, value }] },
+ *     oneLiner: { value, ambiguous, sources: [{ source, value }] },
+ *   }
+ *
+ * `value` is the first candidate (a safe fallback), `ambiguous` is true when
+ * two or more distinct candidates were found. Callers should ask the user
+ * whenever `ambiguous` is true or `value` is empty.
+ */
+export function autoProjectInfo(cwd) {
+  const nameSources = [];
+  const oneLinerSources = [];
+
+  const pkgPath = join(cwd, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+      if (isNonEmptyString(pkg?.name)) {
+        nameSources.push({ source: 'package.json', value: pkg.name.trim() });
+      }
+      if (isNonEmptyString(pkg?.description)) {
+        oneLinerSources.push({ source: 'package.json', value: pkg.description.trim() });
+      }
+    } catch {
+      /* malformed package.json — ignore */
+    }
+  }
+
+  for (const file of README_CANDIDATES) {
+    const filePath = join(cwd, file);
+    if (!existsSync(filePath)) continue;
+
+    let content;
+    try {
+      content = readFileSync(filePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    const hints = extractReadmeHints(content);
+    if (hints.name) nameSources.push({ source: file, value: hints.name });
+    if (hints.oneLiner) oneLinerSources.push({ source: file, value: hints.oneLiner });
+
+    break; // first README found wins — don't blend multiple README variants
+  }
+
+  return {
+    name: summarize(nameSources),
+    oneLiner: summarize(oneLinerSources),
+  };
+}
+
+/** Pull a name (first H1) and one-liner (first prose line) out of a README. */
+export function extractReadmeHints(content) {
+  const lines = String(content || '').split('\n');
+  let name = '';
+  let oneLiner = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+
+    if (!name) {
+      const h1 = /^#\s+(.+?)\s*$/.exec(line);
+      if (h1) {
+        name = stripInlineMarkdown(h1[1]);
+        continue;
+      }
+    }
+
+    // Wait for the first H1 before reading prose — otherwise the README may
+    // start with a logo/badge that is not a name.
+    if (!name || oneLiner) continue;
+
+    if (isProseLine(line)) {
+      oneLiner = line.length > 120 ? `${line.slice(0, 117)}...` : line;
+    }
+  }
+
+  return { name, oneLiner };
+}
+
+function summarize(sources) {
+  if (sources.length === 0) {
+    return { value: '', ambiguous: false, sources: [] };
+  }
+
+  const distinct = [];
+  for (const entry of sources) {
+    if (!distinct.includes(entry.value)) distinct.push(entry.value);
+  }
+
+  return {
+    value: sources[0].value,
+    ambiguous: distinct.length > 1,
+    sources,
+  };
+}
+
+function isProseLine(line) {
+  // Skip headings, badges/images, code fences, lists, tables, blockquotes, HTML.
+  if (/^[#>|`*\-_]/.test(line)) return false;
+  if (/^\[!\[/.test(line)) return false;
+  if (/^!\[/.test(line)) return false;
+  if (/^<[a-zA-Z!/]/.test(line)) return false;
+  if (/^\|/.test(line)) return false;
+  return true;
+}
+
+function stripInlineMarkdown(value) {
+  return String(value)
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1') // [text](url) → text
+    .replace(/[*_`]/g, '')
+    .trim();
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}