agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/src/cli/commands/skills.js

@@ -0,0 +1,324 @@
+/**
+ * `agileflow skills <action>` — inspect and manage installed skill packs.
+ *
+ * Actions:
+ *   list              Print a table of every skill installed for the configured IDE,
+ *                     including name, version, learns status, and accumulated learning count.
+ *   enable  <plugin>  Enable a plugin (skill pack) and re-sync the install.
+ *   disable <plugin>  Disable a plugin (skill pack) and remove its skills.
+ *
+ * Usage:
+ *   agileflow skills list
+ *   agileflow skills list --json
+ *   agileflow skills enable  ads
+ *   agileflow skills disable council
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const pkg = require("../../../package.json");
+const yaml = require("js-yaml");
+const { loadConfig } = require("../../runtime/config/loader.js");
+const { writeConfig } = require("../../runtime/config/writer.js");
+const {
+  IDE_CAPABILITIES,
+  capabilitiesFor,
+  hookEventsForIdes,
+} = require("../../runtime/ide/capabilities.js");
+const { readLearnings } = require("../../runtime/skills/learnings.js");
+const { discoverPlugins } = require("../../runtime/plugins/registry.js");
+const { installPlugins } = require("../../runtime/installer/install.js");
+const {
+  normalizeBehaviorsForEvents,
+} = require("../wizard/behaviors-picker.js");
+const {
+  InvalidArgumentError,
+  MissingFileError,
+  OperationFailedError,
+  fail,
+} = require("../../lib/errors.js");
+
+/**
+ * Read and parse SKILL.md frontmatter from an installed skill directory.
+ * Returns null when SKILL.md is absent or unparseable.
+ *
+ * @param {string} skillDir
+ * @returns {{ name: string, version: string, description: string, learns: object } | null}
+ */
+function readSkillMeta(skillDir) {
+  const mdPath = path.join(skillDir, "SKILL.md");
+  let text;
+  try {
+    text = fs.readFileSync(mdPath, "utf8");
+  } catch {
+    return null;
+  }
+  const match = text.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+  try {
+    const fm = yaml.load(match[1]) || {};
+    return {
+      name: fm.name || path.basename(skillDir),
+      version: fm.version || "?",
+      description: (typeof fm.description === "string" ? fm.description : "")
+        .replace(/\n/g, " ")
+        .trim()
+        .slice(0, 80),
+      learns: fm.learns || { enabled: false },
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {{ json?: boolean }} options
+ */
+async function skillsList(options = {}) {
+  const cwd = process.cwd();
+  const { config } = await loadConfig(cwd);
+
+  const primaryIde =
+    Array.isArray(config?.ide?.targets) && config.ide.targets.length > 0
+      ? config.ide.targets[0]
+      : "claude-code";
+
+  const caps = IDE_CAPABILITIES[primaryIde];
+  if (!caps || !caps.skills) {
+    if (options.json) {
+      // eslint-disable-next-line no-console
+      console.log(
+        JSON.stringify({
+          ide: primaryIde,
+          skills: [],
+          note: "IDE does not support skills",
+        }),
+      );
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(`(${primaryIde} does not support skills)`);
+    }
+    return;
+  }
+
+  const skillsDir = path.join(cwd, caps.skillsDir);
+  if (!fs.existsSync(skillsDir)) {
+    if (options.json) {
+      // eslint-disable-next-line no-console
+      console.log(
+        JSON.stringify({
+          ide: primaryIde,
+          skillsDir: caps.skillsDir,
+          skills: [],
+          note: "Skills directory not found — run `agileflow setup`",
+        }),
+      );
+    } else {
+      // eslint-disable-next-line no-console
+      console.log(
+        `Skills not installed — run \`agileflow setup\` to install to ${caps.skillsDir}/`,
+      );
+    }
+    return;
+  }
+
+  const entries = fs
+    .readdirSync(skillsDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .filter((name) => fs.existsSync(path.join(skillsDir, name, "SKILL.md")));
+
+  if (entries.length === 0) {
+    // eslint-disable-next-line no-console
+    console.log(`(no skills installed in ${caps.skillsDir}/)`);
+    return;
+  }
+
+  const rows = [];
+  for (const skillId of entries.sort()) {
+    const meta = readSkillMeta(path.join(skillsDir, skillId));
+    if (!meta) continue;
+
+    let learningCount = 0;
+    if (meta.learns && meta.learns.enabled) {
+      try {
+        const { entries: le } = await readLearnings(skillId, cwd);
+        learningCount = le.length;
+      } catch {
+        // learnings file absent or unreadable — treat as 0
+      }
+    }
+
+    rows.push({
+      id: skillId,
+      version: meta.version,
+      learns:
+        meta.learns && meta.learns.enabled ? `yes (${learningCount})` : "no",
+      description: meta.description,
+    });
+  }
+
+  if (options.json) {
+    // eslint-disable-next-line no-console
+    console.log(
+      JSON.stringify(
+        { ide: primaryIde, skillsDir: caps.skillsDir, skills: rows },
+        null,
+        2,
+      ),
+    );
+    return;
+  }
+
+  // Plain-text table
+  const idW = Math.max(4, ...rows.map((r) => r.id.length));
+  const verW = Math.max(3, ...rows.map((r) => r.version.length));
+  const learnW = Math.max(7, ...rows.map((r) => r.learns.length));
+  const header = `${"Skill".padEnd(idW)}  ${"Ver".padEnd(verW)}  ${"Learns".padEnd(learnW)}  Description`;
+  const sep = `${"-".repeat(idW)}  ${"-".repeat(verW)}  ${"-".repeat(learnW)}  ${"-".repeat(40)}`;
+  // eslint-disable-next-line no-console
+  console.log(`\nInstalled skills (${primaryIde} — ${caps.skillsDir}/):\n`);
+  // eslint-disable-next-line no-console
+  console.log(header);
+  // eslint-disable-next-line no-console
+  console.log(sep);
+  for (const r of rows) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `${r.id.padEnd(idW)}  ${r.version.padEnd(verW)}  ${r.learns.padEnd(learnW)}  ${r.description}`,
+    );
+  }
+  // eslint-disable-next-line no-console
+  console.log(`\n${rows.length} skill(s) installed.`);
+}
+
+// ---------------------------------------------------------------------------
+// enable / disable helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Toggle a plugin on or off, write config, then re-run the installer.
+ *
+ * @param {'enable'|'disable'} action
+ * @param {string} pluginId
+ * @param {object} options
+ */
+async function togglePlugin(action, pluginId, options) {
+  const enable = action === "enable";
+  const cwd = process.cwd();
+
+  // Validate plugin exists in the registry
+  const all = discoverPlugins();
+  const plugin = all.find((p) => p.id === pluginId);
+  if (!plugin) {
+    const ids = all.map((p) => p.id).join(", ");
+    fail(
+      new InvalidArgumentError(`unknown plugin "${pluginId}"`, {
+        suggestion: `available: ${ids}`,
+      }),
+      { command: `skills ${action}` },
+    );
+  }
+  if (plugin.cannotDisable && !enable) {
+    fail(
+      new InvalidArgumentError(
+        `"${pluginId}" cannot be disabled (it is always active)`,
+      ),
+      { command: "skills disable" },
+    );
+  }
+
+  // Load current config
+  const { config, source } = await loadConfig(cwd);
+  if (source === "defaults") {
+    fail(
+      new MissingFileError("no agileflow.config.json found", {
+        suggestion: "run `npx agileflow setup` first",
+      }),
+      { command: "skills" },
+    );
+  }
+
+  // Patch the plugin entry
+  if (!config.plugins) config.plugins = {};
+  if (!config.plugins[pluginId]) config.plugins[pluginId] = {};
+  config.plugins[pluginId].enabled = enable;
+
+  // Write config atomically
+  await writeConfig(cwd, config);
+  // eslint-disable-next-line no-console
+  console.log(
+    `✓ ${enable ? "Enabled" : "Disabled"} plugin "${pluginId}" in agileflow.config.json`,
+  );
+
+  // Re-run installer to materialize / remove the skill files
+  const agileflowDir = path.join(cwd, ".agileflow");
+  const userSelected = Object.entries(config.plugins || {})
+    .filter(([id, v]) => v && v.enabled && id !== "core")
+    .map(([id]) => id);
+
+  const supportedHookEvents = hookEventsForIdes(config.ide.targets || []);
+  const normalizedBehaviors = normalizeBehaviorsForEvents(
+    config.behaviors,
+    supportedHookEvents,
+  );
+
+  let result;
+  try {
+    result = await installPlugins({
+      discovered: all,
+      userSelected,
+      agileflowDir,
+      cliVersion: pkg.version,
+      ides: config.ide.targets || ["claude-code"],
+      behaviors: normalizedBehaviors,
+      learningsEnabled: Boolean(config.learnings && config.learnings.enabled),
+      force: Boolean(options.force),
+      config,
+    });
+  } catch (err) {
+    fail(
+      new OperationFailedError(`install sync failed: ${err.message}`, {
+        suggestion:
+          "config was saved but install failed — re-run `agileflow update` or fix the underlying error",
+        cause: err,
+      }),
+      { command: `skills ${action}` },
+    );
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(
+    `  created=${result.ops.created} updated=${result.ops.updated} unchanged=${result.ops.unchanged} removed=${result.ops.removed}`,
+  );
+}
+
+/**
+ * @param {string} action - 'list' | 'enable' | 'disable'
+ * @param {string} [pluginOrSkillId] - required for enable/disable
+ * @param {{ json?: boolean, force?: boolean }} options
+ */
+async function skills(action, pluginOrSkillId, options = {}) {
+  if (action === "list") {
+    return skillsList(options);
+  }
+  if (action === "enable" || action === "disable") {
+    if (!pluginOrSkillId) {
+      fail(
+        new InvalidArgumentError("plugin name required", {
+          suggestion: `agileflow skills ${action} <plugin-id>  (e.g. \`agileflow skills ${action} ads\`)`,
+        }),
+        { command: `skills ${action}` },
+      );
+    }
+    return togglePlugin(action, pluginOrSkillId, options);
+  }
+  fail(
+    new InvalidArgumentError(`unknown action "${action}"`, {
+      suggestion: "use `list`, `enable`, or `disable`",
+    }),
+    { command: "skills" },
+  );
+}
+
+module.exports = skills;

package/src/cli/commands/status.js

@@ -4,9 +4,9 @@
  * Phase 1 stub: prints version + config summary if present. Hook health,
  * plugin state beyond `enabled` flag, and integrity counts land in Phase 5.
  */
-const path = require('path');
-const pkg = require('../../../package.json');
-const { loadConfig } = require('../../runtime/config/loader.js');
+const path = require("path");
+const pkg = require("../../../package.json");
+const { loadConfig } = require("../../runtime/config/loader.js");
 
 /** @param {{ json?: boolean }} options */
 async function status(options = {}) {
@@ -21,8 +21,8 @@ async function status(options = {}) {
     plugins: Object.entries(result.config.plugins || {})
       .filter(([, v]) => v && v.enabled)
       .map(([id]) => id),
-    personalization: result.config.personalization,
-    phase: 'Phase 2a — wizard ready; installer sync engine + hooks + content pending (Phase 2b+)',
+    phase:
+      "Phase 2a — wizard ready; installer sync engine + hooks + content pending (Phase 2b+)",
   };
 
   if (options.json) {
@@ -34,14 +34,12 @@ async function status(options = {}) {
   const lines = [
     `agileflow v${summary.version}`,
     `cwd:      ${summary.cwd}`,
-    `config:   ${summary.configPath ? path.relative(cwd, summary.configPath) : '(defaults — no agileflow.config.json found)'}`,
-    `plugins:  ${summary.plugins.length ? summary.plugins.join(', ') : '(none enabled — core is default)'}`,
-    `tone:     ${summary.personalization.tone}`,
-    `ask:      ${summary.personalization.ask_level}`,
+    `config:   ${summary.configPath ? path.relative(cwd, summary.configPath) : "(defaults — no agileflow.config.json found)"}`,
+    `plugins:  ${summary.plugins.length ? summary.plugins.join(", ") : "(none enabled — core is default)"}`,
     `phase:    ${summary.phase}`,
   ];
   // eslint-disable-next-line no-console
-  console.log(lines.join('\n'));
+  console.log(lines.join("\n"));
 }
 
 module.exports = status;

package/src/cli/commands/update.js

@@ -14,32 +14,57 @@
  * failure.
  */
 const path = require("path");
+const os = require("os");
 const pkg = require("../../../package.json");
 const { loadConfig } = require("../../runtime/config/loader.js");
 const { discoverPlugins } = require("../../runtime/plugins/registry.js");
 const { installPlugins } = require("../../runtime/installer/install.js");
+const {
+  capabilitiesFor,
+  hookEventsForIdes,
+} = require("../../runtime/ide/capabilities.js");
+const {
+  normalizeBehaviorsForEvents,
+} = require("../wizard/behaviors-picker.js");
+const {
+  MissingFileError,
+  OperationFailedError,
+  fail,
+} = require("../../lib/errors.js");
 
 /**
  * @param {{ force?: boolean }} options
  */
 async function update(options = {}) {
   const cwd = process.cwd();
+  const scope = options.scope === "global" ? "global" : "project";
+  const agileflowDir =
+    scope === "global"
+      ? path.join(os.homedir(), ".agileflow")
+      : path.join(cwd, ".agileflow");
+  const configRoot = scope === "global" ? agileflowDir : cwd;
 
   let existing;
   try {
-    existing = await loadConfig(cwd);
+    existing = await loadConfig(configRoot);
   } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error(`agileflow update: ${err.message}`);
-    process.exit(1);
+    fail(
+      new OperationFailedError(err.message, {
+        suggestion:
+          "fix or delete agileflow.config.json and re-run `agileflow setup`",
+        cause: err,
+      }),
+      { command: "update" },
+    );
   }
 
   if (existing.source === "defaults") {
-    // eslint-disable-next-line no-console
-    console.error(
-      "agileflow update: no agileflow.config.json found. Run `agileflow setup` first.",
+    fail(
+      new MissingFileError("no agileflow.config.json found", {
+        suggestion: "run `npx agileflow setup` first",
+      }),
+      { command: "update" },
     );
-    process.exit(1);
   }
 
   const enabled = Object.entries(existing.config.plugins || {})
@@ -51,23 +76,59 @@ async function update(options = {}) {
 
   let result;
   try {
+    const supportedHookEvents = hookEventsForIdes(existing.config.ide.targets);
+    const normalizedBehaviors = normalizeBehaviorsForEvents(
+      existing.config.behaviors,
+      supportedHookEvents,
+    );
     result = await installPlugins({
       discovered: discoverPlugins(),
       userSelected,
-      agileflowDir: path.join(cwd, ".agileflow"),
+      agileflowDir,
       cliVersion: pkg.version,
-      ide: existing.config.ide.primary,
-      behaviors: existing.config.behaviors,
+      ides: existing.config.ide.targets,
+      behaviors: normalizedBehaviors,
+      learningsEnabled: Boolean(
+        existing.config.learnings && existing.config.learnings.enabled,
+      ),
       force: Boolean(options.force),
+      config: existing.config,
     });
   } catch (err) {
-    // eslint-disable-next-line no-console
-    console.error(`agileflow update: install failed: ${err.message}`);
-    process.exit(1);
+    fail(
+      new OperationFailedError(`install failed: ${err.message}`, {
+        suggestion:
+          "check the error above; re-run with DEBUG=1 for a full stack trace",
+        cause: err,
+      }),
+      { command: "update" },
+    );
   }
 
   // eslint-disable-next-line no-console
-  console.log(`✓ Updated ${enabled.length} plugin(s): ${enabled.join(", ")}`);
+  console.log(
+    `✓ Updated ${enabled.length} skill pack(s): ${enabled.join(", ")}`,
+  );
+  // eslint-disable-next-line no-console
+  console.log(`  scope: ${scope}`);
+
+  const targets = existing.config.ide.targets || [];
+  const anyHooks = targets.some((id) => capabilitiesFor(id).hooks);
+  if (anyHooks) {
+    const activeBehaviors = Object.entries(
+      normalizeBehaviorsForEvents(
+        existing.config.behaviors,
+        hookEventsForIdes(targets),
+      ),
+    )
+      .filter(([, v]) => v)
+      .map(([k]) => k);
+    // eslint-disable-next-line no-console
+    console.log(
+      `  behaviors enabled: ${activeBehaviors.length ? activeBehaviors.join(", ") : "(none — no hooks will run)"}`,
+    );
+  }
+
   // eslint-disable-next-line no-console
   console.log(
     `  created=${result.ops.created} updated=${result.ops.updated} unchanged=${result.ops.unchanged} preserved=${result.ops.preserved} removed=${result.ops.removed}`,

package/src/cli/index.js

@@ -4,14 +4,19 @@
  * Phase 1 ships `status`, `setup` (stub), and `doctor` (stub). Phase 2 adds
  * `enable`, `disable`, and a real `setup`. Phase 5 adds `uninstall`.
  */
-const { Command } = require('commander');
-const pkg = require('../../package.json');
+const { Command } = require("commander");
+const pkg = require("../../package.json");
+const { SUPPORTED_IDES } = require("../runtime/ide/capabilities.js");
 
-const status = require('./commands/status.js');
-const setup = require('./commands/setup.js');
-const update = require('./commands/update.js');
-const doctor = require('./commands/doctor.js');
-const hook = require('./commands/hook.js');
+const status = require("./commands/status.js");
+const setup = require("./commands/setup.js");
+const update = require("./commands/update.js");
+const doctor = require("./commands/doctor.js");
+const hook = require("./commands/hook.js");
+const learn = require("./commands/learn.js");
+const skills = require("./commands/skills.js");
+const plugins = require("./commands/plugins.js");
+const launch = require("./commands/launch.js");
 
 /**
  * Build the commander program. Exported so tests can construct it without
@@ -22,39 +27,98 @@ function buildProgram() {
   const program = new Command();
 
   program
-    .name('agileflow')
-    .description('AgileFlow v4 — skills-first agile toolkit for Claude Code')
-    .version(pkg.version, '-v, --version', 'print version');
+    .name("agileflow")
+    .description("AgileFlow v4 — skills-first agile toolkit for Claude Code")
+    .version(pkg.version, "-v, --version", "print version");
 
   program
-    .command('status')
-    .description('print install state, enabled plugins, and hook health')
-    .option('--json', 'output machine-readable JSON')
+    .command("status")
+    .description("print install state, enabled plugins, and hook health")
+    .option("--json", "output machine-readable JSON")
     .action(status);
 
   program
-    .command('setup')
-    .description('run interactive install wizard')
-    .option('--yes', 'skip prompts, install with defaults')
-    .option('--plugins <ids>', 'comma-separated plugin list to enable')
-    .option('--ide <id>', 'target IDE / CLI: claude-code | cursor | windsurf | codex', 'claude-code')
+    .command("setup")
+    .description("run interactive install wizard")
+    .option("--yes", "skip prompts, install with defaults")
+    .option("--plugins <ids>", "comma-separated plugin list to enable")
+    .option(
+      "--ide <id>",
+      `target IDE / CLI(s): ${SUPPORTED_IDES.join(" | ")} | all`,
+      "claude-code",
+    )
+    .option("--scope <scope>", "install scope: project | global", "project")
     .action(setup);
 
   program
-    .command('update')
-    .description('re-install plugins from the current agileflow.config.json (no prompts)')
-    .option('--force', 'overwrite local modifications instead of preserving them')
+    .command("update")
+    .description(
+      "re-install plugins from the current agileflow.config.json (no prompts)",
+    )
+    .option(
+      "--force",
+      "overwrite local modifications instead of preserving them",
+    )
+    .option("--scope <scope>", "install scope: project | global", "project")
     .action(update);
 
   program
-    .command('doctor')
-    .description('validate config, plugins, skills, and hook manifest (Phase 5)')
+    .command("doctor")
+    .description(
+      "validate config, plugins, skills, and hook manifest (Phase 5)",
+    )
+    .option(
+      "--fix",
+      "preview removal of detected stale artifacts (dry-run unless --yes)",
+    )
+    .option("--yes", "with --fix, actually apply removals without confirmation")
     .action(doctor);
 
   program
-    .command('hook <event>')
-    .description('internal: dispatch a Claude Code hook event (used by settings.json)')
-    .option('--matcher <name>', 'tool name for tool-related events (Bash / Edit / Write / etc.)')
+    .command("learn <action> <skillId> [observation]")
+    .description("append or list skill learnings (action: append | list)")
+    .option("--confidence <level>", "high | medium | low", "medium")
+    .option(
+      "--source <type>",
+      "correction | confirmation | observation",
+      "correction",
+    )
+    .action(learn);
+
+  program
+    .command("skills <action> [pluginId]")
+    .description(
+      "manage skill packs (actions: list, enable <plugin>, disable <plugin>)",
+    )
+    .option("--json", "output as JSON")
+    .option(
+      "--force",
+      "overwrite local modifications when syncing after enable/disable",
+    )
+    .action(skills);
+
+  program
+    .command("plugins <action>")
+    .description("inspect the plugin registry (action: list)")
+    .option("--json", "output as JSON")
+    .action(plugins);
+
+  program
+    .command("launch [sub] [name]")
+    .description(
+      "multi-CLI tmux wrapper: sub=setup to (re)configure, sub=new [name] to spawn a parallel session (same-dir or worktree-backed)",
+    )
+    .action(launch);
+
+  program
+    .command("hook <event>")
+    .description(
+      "internal: dispatch a Claude Code hook event (used by settings.json)",
+    )
+    .option(
+      "--matcher <name>",
+      "tool name for tool-related events (Bash / Edit / Write / etc.)",
+    )
     .action(hook);
 
   return program;