cli-five 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,106 @@
+# cli-five
+
+> **Code Like I'm Five** — scaffold a 5-agent VS Code Copilot team into any repo.
+
+```bash
+npx cli-five init
+```
+
+That's it. Run it in any folder. It interviews you, scaffolds `.github/agents/` + project memory files, searches skills.sh for relevant skills, and tells you what to do next.
+
+## What you get
+
+```
+your-repo/
+├── .github/
+│   ├── agents/                  # 5 agents: Orchestrator, Planner, Coder, Designer, Reviewer
+│   ├── copilot-instructions.md  # Persona + project mandates from interview
+│   ├── instructions/            # Empty — populate via /agent-customization in chat
+│   └── skills/                  # Empty — populate via skills.sh
+├── AGENTS.md                    # Tool-agnostic project context (agents.md standard)
+├── PROJECT.md                   # Long-form vision (rarely changes)
+├── STATE.md                     # Cross-session status (changes constantly)
+├── decisions.md                 # Architectural decision log
+├── agent-diary.md               # Append-only session log
+└── histories/                   # Per-agent accumulated learnings
+```
+
+## Commands
+
+```bash
+npx cli-five init              # interview + scaffold + skill discovery
+npx cli-five doctor            # validate an existing setup
+npx cli-five list-stacks       # show detectable tech stacks
+npx cli-five help
+```
+
+### Flags
+
+| Flag | Effect |
+|---|---|
+| `--yes`, `-y` | Accept interview 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` |
+| `--cwd <path>` | Run against a different directory |
+
+## What `init` does
+
+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** — queries skills.sh via `npx skills find <term>` per detected stack. Recommends known-good skills, offers multiselect install, and launches interactive browser.
+7. **Next steps** — tells you to run `/agent-customization` for stack-specific instructions.
+
+## 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 |
+
+Override from CLI: `npx cli-five init --cost-mode cheap`
+Change anytime by editing the `model:` line in `.github/agents/*.agent.md`.
+
+## Required VS Code settings
+
+```jsonc
+{
+  "chat.subagents.allowInvocationsFromSubagents": true
+}
+```
+
+## 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 Ralph.** No issue-polling daemons, no autonomous loops, no crypto tokens.
+
+## Why the name
+
+ELI5 → CLI5. Code Like I'm Five. Five agents. Get it? Yeah, it's a stretch. But the npm name was available.
+
+## Influences
+
+- [bradygaster/squad](https://github.com/bradygaster/squad) — see [docs/squad-review.md](docs/squad-review.md)
+- [burkeholland/ultralight](https://github.com/burkeholland/ultralight) — see [docs/ultralight-review.md](docs/ultralight-review.md)
+- [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done) — see [docs/gsd-review.md](docs/gsd-review.md)
+
+## Local development
+
+```bash
+git clone https://github.com/idusortus/squad-mine
+cd squad-mine
+npm install
+node bin/cli-five.mjs init --cwd /tmp/test-target
+```
+
+## License
+
+MIT.

package/bin/cli-five.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// cli-five — Code Like I'm Five
+import { run } from '../src/cli.mjs';
+
+run(process.argv.slice(2)).catch((err) => {
+  console.error(err?.stack || err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "cli-five",
+  "version": "0.1.0",
+  "description": "Code Like I'm Five — scaffold a 5-agent VS Code Copilot team into any repo.",
+  "type": "module",
+  "bin": {
+    "cli-five": "bin/cli-five.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test tests/",
+    "smoke": "node bin/cli-five.mjs --help"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "copilot",
+    "vscode",
+    "agents",
+    "scaffold",
+    "ai"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "kleur": "^4.1.5",
+    "prompts": "^2.4.2"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,65 @@
+import kleur from 'kleur';
+import { init } from './commands/init.mjs';
+import { doctor } from './commands/doctor.mjs';
+import { listStacks } from './commands/list-stacks.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.
+
+${kleur.bold('Usage')}
+  npx cli-five <command> [options]
+
+${kleur.bold('Commands')}
+  init            Interview + scaffold .github/* and project memory files
+  doctor          Validate an existing cli-five setup
+  list-stacks     Show detectable tech stacks
+  help            Show this message
+
+${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
+  --no-skills     Skip the skills.sh discovery step
+  --cost-mode <m> Override cost mode (premium, cheap, mixed) — skips interview question
+  --cwd <path>    Run against a directory other than the current one
+`;
+
+export async function run(argv) {
+  const args = parse(argv);
+  const cmd = args._[0] || 'help';
+
+  switch (cmd) {
+    case 'init':
+      return init(args);
+    case 'doctor':
+      return doctor(args);
+    case 'list-stacks':
+      return listStacks();
+    case 'help':
+    case '--help':
+    case '-h':
+      process.stdout.write(HELP);
+      return;
+    default:
+      process.stderr.write(kleur.red(`Unknown command: ${cmd}\n\n`));
+      process.stdout.write(HELP);
+      process.exit(2);
+  }
+}
+
+function parse(argv) {
+  const out = { _: [], yes: false, force: false, dryRun: false, skills: true, costMode: 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 === '--no-skills') out.skills = false;
+    else if (a === '--cost-mode') out.costMode = argv[++i];
+    else if (a === '--cwd') out.cwd = argv[++i];
+    else if (a === '--help' || a === '-h') out._.push('help');
+    else out._.push(a);
+  }
+  return out;
+}

package/src/commands/doctor.mjs

@@ -0,0 +1,54 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import kleur from 'kleur';
+import { log } from '../util/log.mjs';
+
+const REQUIRED = [
+  '.github/copilot-instructions.md',
+  '.github/agents/orchestrator.agent.md',
+  '.github/agents/planner.agent.md',
+  '.github/agents/coder.agent.md',
+  '.github/agents/designer.agent.md',
+  '.github/agents/reviewer.agent.md',
+  'PROJECT.md',
+  'STATE.md',
+  'decisions.md',
+  'agent-diary.md',
+];
+
+const OPTIONAL = [
+  '.github/instructions',
+  '.github/skills',
+  'AGENTS.md',
+  'histories/orchestrator.md',
+];
+
+export async function doctor(args) {
+  const cwd = args.cwd;
+  log.raw(kleur.bold().magenta('\ncli-five doctor') + kleur.gray(`  ${cwd}`));
+  let fail = 0;
+
+  log.step('Required');
+  for (const p of REQUIRED) {
+    const ok = existsSync(join(cwd, p));
+    if (ok) log.ok(p);
+    else {
+      log.err(p);
+      fail++;
+    }
+  }
+
+  log.step('Optional');
+  for (const p of OPTIONAL) {
+    if (existsSync(join(cwd, p))) log.ok(p);
+    else log.warn(`missing (ok): ${p}`);
+  }
+
+  log.raw('');
+  if (fail === 0) {
+    log.ok('All required files present.');
+  } else {
+    log.err(`${fail} required file(s) missing. Run \`npx cli-five init\`.`);
+    process.exit(1);
+  }
+}

package/src/commands/init.mjs

@@ -0,0 +1,87 @@
+import kleur from 'kleur';
+import prompts from 'prompts';
+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 { scaffold, summarize } from '../steps/scaffold.mjs';
+import { skillDiscovery } from '../steps/skills.mjs';
+import { isGitRepo, gitInit } from '../util/git.mjs';
+
+export async function init(args) {
+  const cwd = args.cwd;
+  log.raw(kleur.bold().magenta('\ncli-five init') + kleur.gray(`  ${cwd}`));
+
+  // 1. Detect
+  log.step('1/5 Detect workspace');
+  const detected = detect(cwd);
+  log.info(`Project: ${kleur.bold(detected.projectName)}`);
+  log.info(`Mode:    ${detected.isBrownfield ? kleur.yellow('brownfield') : kleur.green('greenfield')}`);
+  if (detected.stacks.length) log.info(`Stack:   ${detected.stacks.map((s) => s.label).join(', ')}`);
+  if (!detected.hasGit) log.warn('Not a git repository.');
+
+  // 2. git init if needed
+  if (!detected.hasGit) {
+    if (args.yes || (await ask('Run `git init`?', true))) {
+      gitInit(cwd);
+      log.ok('Initialised git repo.');
+    } else {
+      log.warn('Continuing without git. You will regret this.');
+    }
+  }
+
+  // 3. Overwrite gate
+  log.step('2/5 Confirm overwrites');
+  const ok = await confirmOverwriteIfNeeded(detected, args);
+  if (!ok) {
+    log.warn('Aborted. Nothing written.');
+    return;
+  }
+  if (!detected.hasAgents && !detected.hasCopilotInstructions) log.dim('No collisions.');
+
+  // 4. Interview
+  log.step('3/5 Interview');
+  const answers = await interview(detected, args);
+
+  // CLI --cost-mode override
+  if (args.costMode && ['premium', 'cheap', 'mixed'].includes(args.costMode)) {
+    answers.costMode = args.costMode;
+  }
+
+  // 5. Scaffold
+  log.step('4/5 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.`);
+
+  // 6. Skill discovery
+  log.step('5/5 Skill discovery');
+  await skillDiscovery({ cwd, answers, args });
+
+  // 7. Next steps
+  printNextSteps(answers);
+}
+
+async function ask(message, initial = false) {
+  const { v } = await prompts({ type: 'confirm', name: 'v', message, initial });
+  return Boolean(v);
+}
+
+function printNextSteps(answers) {
+  log.raw('');
+  log.raw(kleur.bold().green('Done. Next steps:'));
+  log.raw('');
+  log.raw(`  1. Open this folder in VS Code Insiders.`);
+  log.raw(`  2. Enable Copilot subagents (settings.json):`);
+  log.raw(kleur.gray(`        "chat.subagents.allowInvocationsFromSubagents": true`));
+  log.raw(`  3. Open Copilot Chat and verify the 5 agents appear (@ menu).`);
+  log.raw(`  4. Ask the Orchestrator to do something:`);
+  log.raw(kleur.gray(`        @Orchestrator read PROJECT.md and propose Phase 1.`));
+  log.raw(`  5. Generate stack-specific instructions:`);
+  log.raw(kleur.gray(`        Run /agent-customization in chat — it will read PROJECT.md`));
+  log.raw(kleur.gray(`        and produce .github/instructions/*.instructions.md files.`));
+  log.raw('');
+  log.raw(kleur.dim('Edit cost mode anytime by changing `model:` in .github/agents/*.agent.md.'));
+  log.raw('');
+}

package/src/commands/list-stacks.mjs

@@ -0,0 +1,13 @@
+import kleur from 'kleur';
+import { STACK_SIGNATURES } from '../steps/detect.mjs';
+
+export function listStacks() {
+  process.stdout.write(kleur.bold('\nDetectable stacks\n\n'));
+  process.stdout.write(`  ${kleur.gray('ID'.padEnd(18))} ${kleur.gray('Label'.padEnd(22))} ${kleur.gray('Detected by')}\n`);
+  process.stdout.write(`  ${'─'.repeat(18)} ${'─'.repeat(22)} ${'─'.repeat(40)}\n`);
+  for (const s of STACK_SIGNATURES) {
+    const trigger = s.files ? s.files.join(', ') : `glob: ${s.glob}`;
+    process.stdout.write(`  ${s.id.padEnd(18)} ${s.label.padEnd(22)} ${trigger}\n`);
+  }
+  process.stdout.write('\n');
+}

package/src/steps/confirm.mjs

@@ -0,0 +1,38 @@
+import prompts from 'prompts';
+import { log } from '../util/log.mjs';
+
+export async function confirmOverwriteIfNeeded(detected, args) {
+  const collisions = collideList(detected);
+  if (collisions.length === 0) return true;
+
+  log.warn('Existing cli-five artifacts detected:');
+  for (const c of collisions) log.dim(`    - ${c}`);
+
+  if (args.force && args.yes) {
+    log.warn('--force --yes set. Overwriting without prompts. Hope you have git.');
+    return true;
+  }
+
+  const first = await prompts({
+    type: 'confirm',
+    name: 'ok',
+    message: 'This will OVERWRITE the files above. Proceed?',
+    initial: false,
+  });
+  if (!first.ok) return false;
+
+  const second = await prompts({
+    type: 'confirm',
+    name: 'sure',
+    message: 'R U Sure? Last chance.',
+    initial: false,
+  });
+  return Boolean(second.sure);
+}
+
+function collideList(detected) {
+  const out = [];
+  if (detected.hasAgents) out.push('.github/agents/');
+  if (detected.hasCopilotInstructions) out.push('.github/copilot-instructions.md');
+  return out;
+}

package/src/steps/detect.mjs

@@ -0,0 +1,64 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+
+export const STACK_SIGNATURES = [
+  { id: 'node-ts', label: 'Node + TypeScript', files: ['tsconfig.json', 'package.json'] },
+  { id: 'node', label: 'Node', files: ['package.json'] },
+  { id: 'python', label: 'Python', files: ['pyproject.toml', 'requirements.txt', 'setup.py'] },
+  { id: 'dotnet', label: '.NET', glob: /\.(csproj|fsproj|sln)$/i },
+  { id: 'rust', label: 'Rust', files: ['Cargo.toml'] },
+  { id: 'go', label: 'Go', files: ['go.mod'] },
+  { id: 'kotlin-android', label: 'Kotlin / Android', files: ['build.gradle.kts', 'settings.gradle.kts'] },
+  { id: 'gradle', label: 'Gradle (JVM)', files: ['build.gradle', 'settings.gradle'] },
+  { id: 'maven', label: 'Maven (JVM)', files: ['pom.xml'] },
+  { id: 'ruby', label: 'Ruby', files: ['Gemfile'] },
+  { id: 'php', label: 'PHP', files: ['composer.json'] },
+];
+
+export function detect(cwd) {
+  const entries = safeRead(cwd);
+  const names = new Set(entries);
+  const stacks = [];
+
+  for (const sig of STACK_SIGNATURES) {
+    if (sig.files && sig.files.some((f) => names.has(f))) stacks.push(sig);
+    else if (sig.glob && entries.some((n) => sig.glob.test(n))) stacks.push(sig);
+  }
+
+  const hasGit = names.has('.git');
+  const hasGithub = names.has('.github');
+  const hasAgents = existsSync(join(cwd, '.github', 'agents'));
+  const hasCopilotInstructions = existsSync(join(cwd, '.github', 'copilot-instructions.md'));
+  const projectName = guessName(cwd, names);
+
+  return {
+    cwd,
+    projectName,
+    hasGit,
+    hasGithub,
+    hasAgents,
+    hasCopilotInstructions,
+    isBrownfield: stacks.length > 0,
+    stacks,
+  };
+}
+
+function safeRead(cwd) {
+  try {
+    return readdirSync(cwd);
+  } catch {
+    return [];
+  }
+}
+
+function guessName(cwd, names) {
+  if (names.has('package.json')) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8'));
+      if (pkg?.name) return pkg.name;
+    } catch {
+      /* ignore */
+    }
+  }
+  return basename(cwd);
+}

package/src/steps/interview.mjs

@@ -0,0 +1,98 @@
+import prompts from 'prompts';
+
+const COST_MODES = [
+  { title: 'Premium (default)', value: 'premium', description: 'Sonnet/Opus/Codex. Best quality, real cost.' },
+  { title: 'Cheap (0x)', value: 'cheap', description: 'GPT-4.1 / GPT-4o / GPT-5 mini. Free tier-friendly.' },
+  { title: 'Mixed', value: 'mixed', description: 'Premium Coder + Reviewer, cheap everything else.' },
+];
+
+export async function interview(detected, args) {
+  if (args.yes) return defaults(detected);
+
+  const onCancel = () => {
+    throw new Error('Interview cancelled. Nothing was written.');
+  };
+
+  const answers = await prompts(
+    [
+      {
+        type: 'text',
+        name: 'projectName',
+        message: 'Project name',
+        initial: detected.projectName,
+      },
+      {
+        type: 'text',
+        name: 'oneLiner',
+        message: 'One-line description (becomes PROJECT.md vision)',
+        initial: '',
+      },
+      {
+        type: 'list',
+        name: 'stack',
+        message: 'Tech stack (comma separated)',
+        initial: detected.stacks.map((s) => s.label).join(', '),
+        separator: ',',
+      },
+      {
+        type: 'list',
+        name: 'frameworks',
+        message: 'Frameworks / key libraries (comma separated, optional)',
+        initial: '',
+        separator: ',',
+      },
+      {
+        type: 'text',
+        name: 'goals',
+        message: 'Primary goal of this project (one sentence)',
+      },
+      {
+        type: 'text',
+        name: 'constraints',
+        message: 'Hard constraints (perf, deps, deploy, compliance — one sentence, optional)',
+      },
+      {
+        type: 'select',
+        name: 'costMode',
+        message: 'Agent cost mode',
+        choices: COST_MODES,
+        initial: 0,
+      },
+      {
+        type: 'confirm',
+        name: 'snark',
+        message: 'Include the snarky persona block in copilot-instructions.md?',
+        initial: true,
+      },
+    ],
+    { onCancel },
+  );
+
+  return normalize({ ...defaults(detected), ...answers });
+}
+
+function defaults(detected) {
+  return {
+    projectName: detected.projectName,
+    oneLiner: '',
+    stack: detected.stacks.map((s) => s.label),
+    frameworks: [],
+    goals: '',
+    constraints: '',
+    costMode: 'premium',
+    snark: true,
+  };
+}
+
+function normalize(a) {
+  const trim = (s) => (typeof s === 'string' ? s.trim() : s);
+  return {
+    ...a,
+    projectName: trim(a.projectName),
+    oneLiner: trim(a.oneLiner),
+    goals: trim(a.goals),
+    constraints: trim(a.constraints),
+    stack: (a.stack || []).map(trim).filter(Boolean),
+    frameworks: (a.frameworks || []).map(trim).filter(Boolean),
+  };
+}