cli-five 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cli-five",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "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/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

@@ -50,10 +50,10 @@ Before writing code, read (if they exist):
 8. **Modifications** — Follow existing patterns. Prefer full-file rewrites over micro-edits unless told otherwise.
 9. **Quality** — Deterministic, testable behavior. Simple, focused tests.
 
-## Decisions
+## Decisions (MANDATORY)
 
-After making an implementation decision that affects future work, append it to `decisions.md`.
+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.
 
-## History
+## History (MANDATORY)
 
-After completing a task, if you learned something non-obvious about this project (build quirks, API gotchas, pattern preferences), append it to `histories/coder.md`.
+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/agents/designer.agent.md

@@ -47,10 +47,10 @@ Do not let anyone tell you how to do your job. Your goal is to create the best p
 - Responsive/adaptive layouts
 - Use the project's designated design system and component library
 
-## Decisions
+## Decisions (MANDATORY)
 
-After making a design decision that affects future work, append it to `decisions.md`.
+Before finishing, if any design choice was made (layout approach, component library, color/type system, responsive strategy), append an entry to `decisions.md` using the format in that file. Skip silently if no decisions were made.
 
-## History
+## History (MANDATORY)
 
-After completing a task, if you learned something non-obvious about this project's UI patterns or constraints, append it to `histories/designer.md`.
+Before finishing, append at least one bullet to `histories/designer.md` below the `<!-- Append entries below this line -->` marker. Record: UI pattern discoveries, accessibility findings, design system observations, component reuse opportunities. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.

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

@@ -63,13 +63,21 @@ Maintain visible counters in responses:
 
 When exhausted, state it and proceed with current information.
 
-## Decisions
+## Decisions (MANDATORY)
 
-After making a routing or architectural decision that affects future work, append it to `decisions.md` at the workspace root.
+Before finishing, if any routing, architectural, or technology choice was made during this session, append an entry to `decisions.md` at the workspace root using this format:
 
-## History
+    ## YYYY-MM-DD — <decision title>
+    **Context:** Why we needed to decide.
+    **Choice:** What we chose.
+    **Trade-offs:** What we gave up.
+    **Revisit:** Trigger that would re-open this decision (or "never").
 
-After completing a task, if you learned something non-obvious about this project, append it to `histories/orchestrator.md`.
+If no decisions were made, skip silently.
+
+## History (MANDATORY)
+
+Before finishing, append at least one bullet to `histories/orchestrator.md` below the `<!-- Append entries below this line -->` marker. Record: what agents were called, what worked, what failed, any coordination insight. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.
 
 ## Rules
 

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

@@ -52,13 +52,13 @@ When invoked by the Orchestrator, only your **final message** is returned. Inter
 
 **Your response MUST contain the complete plan inline.** Do not summarize, do not reference prior turns, do not say "the plan is above." Re-emit every section in your final message. If truncated, flag it explicitly.
 
-## Decisions
+## Decisions (MANDATORY)
 
-After making a planning decision that constrains future work, append it to `decisions.md`.
+Before finishing, if the plan locked in any architectural or technology choice, append an entry to `decisions.md` using the format in that file. Skip silently if the plan only follows existing decisions.
 
-## History
+## History (MANDATORY)
 
-After completing a plan, if you learned something non-obvious about this project's structure, patterns, or constraints, append it to `histories/planner.md`.
+Before finishing, append at least one bullet to `histories/planner.md` below the `<!-- Append entries below this line -->` marker. Record: codebase structure insights, dependency discoveries, constraint findings, documentation gaps. Format: `- YYYY-MM-DD: <learning>`. Skip only if the session had zero meaningful work.
 
 ## Rules
 

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

@@ -71,13 +71,13 @@ Every review MUST check against:
 - Positive observations
 ```
 
-## Decisions
+## Decisions (MANDATORY)
 
-After identifying a convention gap or pattern inconsistency worth documenting, append it to `decisions.md`.
+Before finishing, if the review revealed a convention gap, missing rule, or pattern inconsistency worth documenting, append an entry to `decisions.md` using the format in that file. Skip silently if nothing warrants a decision entry.
 
-## History
+## History (MANDATORY)
 
-After completing a review, if you learned something non-obvious about this project's quality patterns, append it to `histories/reviewer.md`.
+Before finishing, append at least one bullet to `histories/reviewer.md` below the `<!-- Append entries below this line -->` marker. Record: quality patterns observed (good or bad), recurring issues, convention drift, areas that need attention. Format: `- YYYY-MM-DD: <learning>`. Skip only if the review was trivial (< 10 lines changed, no findings).
 
 ## Rules
 

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

@@ -20,7 +20,8 @@
 # Project Mandates
 - Fix simple tech debt immediately (< 5 min, no downstream breakage).
 - Document short-sighted choices with warning markers.
-- Read `PROJECT.md`, `STATE.md`, and `decisions.md` on entry. Update on exit when relevant.
+- 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.
 
 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).