cli-five 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-five",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Code Like I'm Five — scaffold a 5-agent VS Code Copilot team into any repo.",
   "type": "module",
   "bin": {
@@ -30,6 +30,7 @@
   "license": "MIT",
   "dependencies": {
     "kleur": "^4.1.5",
-    "prompts": "^2.4.2"
+    "prompts": "^2.4.2",
+    "skills": "^1.5.0"
   }
 }

package/src/commands/init.mjs

@@ -49,6 +49,11 @@ export async function init(args) {
     answers.costMode = args.costMode;
   }
 
+  if (answers.presetId && answers.presetId !== 'custom') {
+    log.info(`Preset: ${answers.presetId}`);
+  }
+  if (answers.frameworks.length) log.info(`Stack:  ${answers.stack.join(', ')} + ${answers.frameworks.join(', ')}`);
+
   // 5. Scaffold
   log.step('4/6 Scaffold');
   const written = scaffold({ cwd, answers, args });

package/src/steps/interview.mjs

@@ -1,5 +1,69 @@
 import prompts from 'prompts';
 
+// ── Preset stacks ─────────────────────────────────────────────────────
+// Chosen for: LLM familiarity, low setup friction, minimal config,
+// copy-paste quickstart, broad hosting support.
+// Research via Context7: Next.js, Vite+React, Express, Hono all score
+// 80+ benchmark with high snippet counts and well-indexed docs.
+const STACK_PRESETS = [
+  {
+    title: 'Next.js (TypeScript)',
+    value: 'nextjs',
+    description: 'Full-stack React. App Router, TypeScript, Tailwind. `npx create-next-app`',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Next.js', 'React', 'Tailwind CSS'],
+    quickstart: 'npx create-next-app@latest . --yes && npm run dev',
+  },
+  {
+    title: 'Vite + React (TypeScript)',
+    value: 'vite-react',
+    description: 'SPA frontend. Lightning-fast HMR. `npm create vite`',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Vite', 'React', 'TypeScript'],
+    quickstart: 'npm create vite@latest . -- --template react-ts && npm i && npm run dev',
+  },
+  {
+    title: 'Express API (TypeScript)',
+    value: 'express',
+    description: 'REST API server. Minimal, well-known, huge ecosystem.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Express', 'TypeScript'],
+    quickstart: 'npm init -y && npm i express typescript tsx @types/express && npx tsx src/index.ts',
+  },
+  {
+    title: 'Hono API (TypeScript)',
+    value: 'hono',
+    description: 'Ultrafast, Web Standards. Works on Node, Bun, Deno, Cloudflare.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Hono', 'TypeScript'],
+    quickstart: 'npm create hono@latest . && npm i && npm run dev',
+  },
+  {
+    title: 'Vite + Vue (TypeScript)',
+    value: 'vite-vue',
+    description: 'SPA frontend with Vue 3 + Composition API.',
+    stack: ['Node + TypeScript'],
+    frameworks: ['Vite', 'Vue', 'TypeScript'],
+    quickstart: 'npm create vite@latest . -- --template vue-ts && npm i && npm run dev',
+  },
+  {
+    title: 'Python + FastAPI',
+    value: 'fastapi',
+    description: 'Modern Python API with type hints and auto-docs.',
+    stack: ['Python'],
+    frameworks: ['FastAPI', 'Pydantic', 'Uvicorn'],
+    quickstart: 'pip install fastapi uvicorn && uvicorn main:app --reload',
+  },
+  {
+    title: 'Custom (freeform)',
+    value: 'custom',
+    description: 'Enter your own stack and frameworks manually.',
+    stack: [],
+    frameworks: [],
+    quickstart: '',
+  },
+];
+
 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.' },
@@ -13,7 +77,8 @@ export async function interview(detected, args) {
     throw new Error('Interview cancelled. Nothing was written.');
   };
 
-  const answers = await prompts(
+  // ── Basic info ────────────────────────────────────────────────────
+  const basic = await prompts(
     [
       {
         type: 'text',
@@ -27,20 +92,61 @@ export async function interview(detected, args) {
         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: ',',
-      },
+    ],
+    { onCancel },
+  );
+
+  // ── Stack preset or freeform ──────────────────────────────────────
+  // If detection already found a stack, show it as initial hint
+  const detectedLabel = detected.stacks.map((s) => s.label).join(', ');
+
+  const { preset } = await prompts(
+    {
+      type: 'select',
+      name: 'preset',
+      message: detectedLabel
+        ? `Stack preset (detected: ${detectedLabel})`
+        : 'Stack preset — pick one or go freeform',
+      choices: STACK_PRESETS,
+      initial: 0,
+    },
+    { onCancel },
+  );
+
+  let stackAnswers;
+  const chosenPreset = STACK_PRESETS.find((p) => p.value === preset);
+
+  if (preset === 'custom') {
+    // Freeform: user types whatever they want
+    stackAnswers = await prompts(
+      [
+        {
+          type: 'list',
+          name: 'stack',
+          message: 'Tech stack (comma separated)',
+          initial: detectedLabel,
+          separator: ',',
+        },
+        {
+          type: 'list',
+          name: 'frameworks',
+          message: 'Frameworks / key libraries (comma separated)',
+          initial: '',
+          separator: ',',
+        },
+      ],
+      { onCancel },
+    );
+  } else {
+    stackAnswers = {
+      stack: chosenPreset.stack,
+      frameworks: chosenPreset.frameworks,
+    };
+  }
+
+  // ── Remaining questions ───────────────────────────────────────────
+  const rest = await prompts(
+    [
       {
         type: 'text',
         name: 'goals',
@@ -68,19 +174,31 @@ export async function interview(detected, args) {
     { onCancel },
   );
 
-  return normalize({ ...defaults(detected), ...answers });
+  return normalize({
+    ...defaults(detected),
+    ...basic,
+    ...stackAnswers,
+    ...rest,
+    presetId: preset,
+    quickstart: chosenPreset?.quickstart || '',
+  });
 }
 
+/** Default stack is Next.js + TypeScript when nothing detected and --yes. */
 function defaults(detected) {
+  const hasDetected = detected.stacks.length > 0;
+  const fallback = STACK_PRESETS[0]; // Next.js (TypeScript)
   return {
     projectName: detected.projectName,
     oneLiner: '',
-    stack: detected.stacks.map((s) => s.label),
-    frameworks: [],
+    stack: hasDetected ? detected.stacks.map((s) => s.label) : fallback.stack,
+    frameworks: hasDetected ? [] : fallback.frameworks,
     goals: '',
     constraints: '',
     costMode: 'premium',
     snark: true,
+    presetId: hasDetected ? 'custom' : fallback.value,
+    quickstart: hasDetected ? '' : fallback.quickstart,
   };
 }
 

package/src/steps/scaffold.mjs

@@ -94,6 +94,7 @@ function buildVars(a) {
     FRAMEWORKS: a.frameworks.length ? a.frameworks.join(', ') : 'None declared.',
     GOALS: a.goals || 'TODO — declare the primary goal.',
     CONSTRAINTS: a.constraints || 'None declared.',
+    QUICKSTART: a.quickstart || 'TODO — add install + run commands here.',
     COST_MODE: a.costMode,
     DATE: new Date().toISOString().slice(0, 10),
     PERSONA_BLOCK: a.snark ? PERSONA_BLOCK : '',

package/src/steps/skills.mjs

@@ -1,5 +1,8 @@
 import prompts from 'prompts';
 import { spawn, execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, renameSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { createRequire } from 'node:module';
 import { log } from '../util/log.mjs';
 
 // Well-known skill repos matched by stack term → repo + suggested skill names
@@ -13,6 +16,83 @@ const SKILL_CATALOG = [
   { terms: ['rust'], repo: 'anthropics/skills', skills: ['code-review'] },
 ];
 
+// ── Environment detection ─────────────────────────────────────────────
+
+function resolveSkillsBin() {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkgPath = require.resolve('skills/package.json');
+    const bin = join(dirname(pkgPath), 'bin', 'cli.mjs');
+    return existsSync(bin) ? bin : null;
+  } catch {
+    return null;
+  }
+}
+
+function whichVersion(cmd) {
+  try {
+    return execFileSync(cmd, ['--version'], { stdio: ['ignore', 'pipe', 'ignore'] })
+      .toString()
+      .trim()
+      .split('\n')[0];
+  } catch {
+    return null;
+  }
+}
+
+/** Detect whether the target workspace itself uses pnpm. */
+function projectUsesPnpm(cwd) {
+  return existsSync(join(cwd, 'pnpm-lock.yaml')) || existsSync(join(cwd, 'pnpm-workspace.yaml'));
+}
+
+/**
+ * Detect the runtime environment.
+ * Returns { runner, label } where runner is a function (skillsArgs, cwd) → {cmd, args}.
+ */
+function detectEnv(cwd) {
+  const bundledBin = resolveSkillsBin();
+  const pnpmVer = whichVersion('pnpm');
+  const npxVer = whichVersion('npx');
+  const projectPnpm = projectUsesPnpm(cwd);
+
+  // ── Terse status lines ────────────────────────────────────────────
+  log.info(`skills CLI (bundled) ${bundledBin ? '✓' : '✗ not resolved'}`);
+  log.info(`pnpm                 ${pnpmVer ? `✓ ${pnpmVer}` : '✗ not found'}${projectPnpm ? '  (project uses pnpm)' : ''}`);
+  log.info(`npx                  ${npxVer ? `✓ ${npxVer}` : '✗ not found'}`);
+
+  // ── Priority: bundled > pnpm (if project or system) > npx ─────────
+  if (bundledBin) {
+    return {
+      label: 'bundled skills CLI',
+      runner: (skillsArgs) => ({ cmd: process.execPath, args: [bundledBin, ...skillsArgs] }),
+      pnpmVer,
+      npxVer,
+      projectPnpm,
+    };
+  }
+  if (pnpmVer) {
+    return {
+      label: 'pnpm dlx',
+      runner: (skillsArgs) => ({ cmd: 'pnpm', args: ['dlx', 'skills', ...skillsArgs] }),
+      pnpmVer,
+      npxVer,
+      projectPnpm,
+    };
+  }
+  if (npxVer) {
+    return {
+      label: 'npx',
+      runner: (skillsArgs) => ({ cmd: 'npx', args: ['-y', 'skills', ...skillsArgs] }),
+      pnpmVer,
+      npxVer,
+      projectPnpm,
+    };
+  }
+  return null;
+}
+
+// ── Main entry ────────────────────────────────────────────────────────
+
 export async function skillDiscovery({ cwd, answers, args }) {
   if (!args.skills) {
     log.dim('Skipping skills discovery (--no-skills).');
@@ -23,15 +103,43 @@ export async function skillDiscovery({ cwd, answers, args }) {
     return;
   }
 
+  // ── Environment checks ──────────────────────────────────────────────
+  const env = detectEnv(cwd);
+
+  if (!env) {
+    log.warn('Cannot run skills CLI: no bundled binary, pnpm, or npx found.');
+    log.warn('Install Node.js (includes npx) or pnpm, then re-run.');
+    return;
+  }
+
+  // Offer pnpm if the user doesn't have it
+  if (!env.pnpmVer) {
+    const { wantPnpm } = await prompts({
+      type: 'confirm',
+      name: 'wantPnpm',
+      message: 'pnpm not found. Install it? (faster, stricter deps, saves disk)',
+      initial: false,
+    });
+    if (wantPnpm) {
+      try {
+        execFileSync('npm', ['install', '-g', 'pnpm'], { stdio: 'inherit' });
+        log.ok('pnpm installed.');
+      } catch (err) {
+        log.warn(`pnpm install failed: ${err.message}`);
+      }
+    }
+  }
+
+  log.ok(`Running skills via ${env.label}`);
   log.raw('');
-  log.raw('Skill discovery powered by skills.sh (Vercel)');
+
+  // ── Skill discovery ─────────────────────────────────────────────────
 
   // 1. Build recommendations from catalog based on stack
   const recs = buildRecommendations(answers);
   if (recs.length === 0) {
     log.dim('No stack-specific recommendations found.');
   } else {
-    log.raw('');
     log.raw(`  ${pad('Skill', 36)} ${pad('Repo', 36)}`);
     log.raw(`  ${'─'.repeat(36)} ${'─'.repeat(36)}`);
     for (const r of recs) {
@@ -47,7 +155,6 @@ export async function skillDiscovery({ cwd, answers, args }) {
     log.raw('');
   }
 
-  // 3. Offer to launch interactive find for each term
   for (const term of terms) {
     const { go } = await prompts({
       type: 'confirm',
@@ -56,11 +163,11 @@ export async function skillDiscovery({ cwd, answers, args }) {
       initial: true,
     });
     if (go) {
-      await runInteractive('npx', ['-y', 'skills', 'find', term], cwd);
+      await runSkills(env, ['find', term], cwd);
     }
   }
 
-  // 4. Offer to install from well-known repos
+  // 3. Offer to install from well-known repos
   if (recs.length > 0) {
     const { install } = await prompts({
       type: 'multiselect',
@@ -75,7 +182,6 @@ export async function skillDiscovery({ cwd, answers, args }) {
     });
 
     if (install && install.length > 0) {
-      // Group by repo
       const byRepo = new Map();
       for (const r of install) {
         if (!byRepo.has(r.repo)) byRepo.set(r.repo, []);
@@ -84,16 +190,14 @@ export async function skillDiscovery({ cwd, answers, args }) {
       for (const [repo, skills] of byRepo) {
         const skillArgs = skills.flatMap((s) => ['--skill', s]);
         log.info(`Installing from ${repo}: ${skills.join(', ')}`);
-        await runInteractive(
-          'npx',
-          ['-y', 'skills', 'add', repo, ...skillArgs, '-a', 'github-copilot'],
-          cwd,
-        );
+        await runSkills(env, ['add', repo, ...skillArgs, '-a', 'github-copilot'], cwd);
       }
+
+      await relocateSkills(cwd);
     }
   }
 
-  // 5. Offer freeform catch-all
+  // 4. Offer freeform catch-all
   const { freeform } = await prompts({
     type: 'confirm',
     name: 'freeform',
@@ -101,12 +205,78 @@ export async function skillDiscovery({ cwd, answers, args }) {
     initial: false,
   });
   if (freeform) {
-    await runInteractive('npx', ['-y', 'skills', 'find'], cwd);
+    await runSkills(env, ['find'], cwd);
+    await relocateSkills(cwd);
   }
 
   log.dim('Done. Run `npx skills find` anytime to discover more.');
 }
 
+// ── Relocation ─────────────────────────────────────────────────────────
+
+async function relocateSkills(cwd) {
+  const src = join(cwd, '.agents', 'skills');
+  const dest = join(cwd, '.github', 'skills');
+
+  if (!existsSync(src)) return;
+
+  const candidates = [];
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    if (!existsSync(join(src, entry.name, 'SKILL.md'))) continue;
+    if (existsSync(join(dest, entry.name))) continue;
+    candidates.push(entry.name);
+  }
+
+  if (candidates.length === 0) return;
+
+  log.raw('');
+  log.info(`${candidates.length} skill${candidates.length > 1 ? 's' : ''} in .agents/skills/: ${candidates.join(', ')}`);
+  log.info('cli-five prefers .github/skills/ (co-located with agents & instructions).');
+  log.info('Both locations work — Copilot discovers either.');
+
+  const { move } = await prompts({
+    type: 'confirm',
+    name: 'move',
+    message: 'Move to .github/skills/?',
+    initial: true,
+  });
+
+  if (!move) {
+    log.dim('Keeping skills in .agents/skills/.');
+    return;
+  }
+
+  let moved = 0;
+  for (const name of candidates) {
+    mkdirSync(dest, { recursive: true });
+    renameSync(join(src, name), join(dest, name));
+    moved++;
+  }
+
+  log.ok(`Moved ${moved} skill${moved > 1 ? 's' : ''} → .github/skills/`);
+
+  // Clean up empty dirs
+  try {
+    if (readdirSync(src).length === 0) {
+      rmSync(src, { recursive: true });
+      const agentsDir = join(cwd, '.agents');
+      if (existsSync(agentsDir) && readdirSync(agentsDir).length === 0) {
+        rmSync(agentsDir, { recursive: true });
+      }
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+// ── Runner ─────────────────────────────────────────────────────────────
+
+function runSkills(env, skillsArgs, cwd) {
+  const { cmd, args } = env.runner(skillsArgs);
+  return runInteractive(cmd, args, cwd);
+}
+
 function buildRecommendations(a) {
   const stackLower = (a.stack || []).map((s) => s.toLowerCase());
   const fwLower = (a.frameworks || []).map((f) => f.toLowerCase());

package/templates/.github/agents/coder.agent.md

@@ -54,6 +54,10 @@ Before writing code, read (if they exist):
 
 Before finishing, if any implementation choice was made (library selection, pattern choice, API approach), append an entry to `decisions.md` using the format in that file. Skip silently if no decisions were made.
 
+## README.md (MANDATORY)
+
+After any session that adds, changes, or removes user-facing functionality, update `README.md` at the project root. The README must contain at minimum: project name & one-liner, **copy-paste quickstart commands** (install deps + run), usage notes, and tech stack. If `README.md` does not exist, create it as the FIRST file before any other work. A new developer must go from clone → running app in < 2 minutes.
+
 ## History (MANDATORY)
 
 Before finishing, append at least one bullet to `histories/coder.md` below the `<!-- Append entries below this line -->` marker. Record: build quirks, API gotchas, pattern preferences, file structure observations, test insights. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.

package/templates/.github/copilot-instructions.md.tmpl

@@ -23,6 +23,18 @@
 - Read `PROJECT.md`, `STATE.md`, and `decisions.md` on entry.
 - Before finishing: update `decisions.md` if any choice was made, update your `histories/<agent>.md` with at least one learning.
 
+# README.md (MANDATORY)
+- The project MUST have a `README.md` at the root at all times.
+- After any session that adds, changes, or removes user-facing functionality, update `README.md`.
+- The README must always contain at minimum:
+  1. **Project name & one-liner** — what this is.
+  2. **Quickstart** — exact commands to install dependencies and run the project locally (copy-paste ready, no placeholders).
+  3. **Usage** — how to use the main features.
+  4. **Tech stack** — languages, frameworks, key libraries.
+- Keep it concise and user-friendly. A new developer should go from clone → running app in under 2 minutes.
+- If the README does not exist yet, create it as the FIRST file before any other work.
+- If unsure about run commands, inspect `package.json` scripts, `Makefile`, `Dockerfile`, or equivalent.
+
 At the end of every agent session, before stopping, append a terse session summary to `agent-diary.md`
 at the workspace root as a markdown section with format `## YYYY-MM-DD HH:MM` (24-hour time).
 Include: 2-5 sentence summary of what was accomplished, include model used.

package/templates/PROJECT.md.tmpl

@@ -12,6 +12,11 @@
 ## Frameworks / Key Libraries
 - {{FRAMEWORKS}}
 
+## Quickstart
+```bash
+{{QUICKSTART}}
+```
+
 ## Hard Constraints
 {{CONSTRAINTS}}