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

package/src/lib/errors.js

@@ -0,0 +1,120 @@
+/**
+ * Typed user-facing errors for the AgileFlow CLI.
+ *
+ * Every error a user is likely to hit (bad argument, missing config,
+ * failed install) should be one of these classes so the formatter can
+ * print a consistent two-line message:
+ *
+ *   ✗ agileflow <cmd>: <message>
+ *     Try: <suggestion>
+ *
+ * Internal/programmer errors should stay as plain `Error` — `fail()`
+ * wraps them with a generic "Try: re-run with --debug" suggestion so
+ * the CLI never prints a bare stack trace at users.
+ */
+const chalk = require("chalk");
+
+/**
+ * @typedef {object} AgileflowErrorOptions
+ * @property {string} [suggestion] Actionable fix the user should try next.
+ * @property {string} [code]       Stable machine-readable code (defaults per subclass).
+ * @property {Error}  [cause]      Underlying error, if wrapping.
+ */
+
+class AgileflowError extends Error {
+  /**
+   * @param {string} message
+   * @param {AgileflowErrorOptions} [options]
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "AgileflowError";
+    this.suggestion = options.suggestion;
+    this.code = options.code || "ERR_AGILEFLOW";
+    if (options.cause) this.cause = options.cause;
+  }
+}
+
+class MissingFileError extends AgileflowError {
+  constructor(message, options = {}) {
+    super(message, { code: "ERR_MISSING_FILE", ...options });
+    this.name = "MissingFileError";
+  }
+}
+
+class InvalidArgumentError extends AgileflowError {
+  constructor(message, options = {}) {
+    super(message, { code: "ERR_INVALID_ARGUMENT", ...options });
+    this.name = "InvalidArgumentError";
+  }
+}
+
+class OperationFailedError extends AgileflowError {
+  constructor(message, options = {}) {
+    super(message, { code: "ERR_OPERATION_FAILED", ...options });
+    this.name = "OperationFailedError";
+  }
+}
+
+/**
+ * Format an error as a two-line stderr string. Does not write — caller decides.
+ *
+ * @param {Error} err
+ * @param {{ command?: string }} [opts]
+ * @returns {string}
+ */
+function formatError(err, opts = {}) {
+  const cmd = opts.command ? `agileflow ${opts.command}` : "agileflow";
+  const head = `${chalk.red("✗")} ${cmd}: ${err.message}`;
+  const isAgileflowError = err instanceof AgileflowError;
+  const hasStringSuggestion =
+    isAgileflowError && typeof err.suggestion === "string" && err.suggestion;
+  const suggestion = hasStringSuggestion
+    ? err.suggestion
+    : isAgileflowError
+      ? null
+      : "Re-run with DEBUG=1 for a stack trace, or report at https://github.com/anthropics/agileflow/issues";
+  if (!suggestion) return head;
+  return `${head}\n  ${chalk.dim(`Try: ${suggestion}`)}`;
+}
+
+/**
+ * Print an error to stderr and exit with code 1. Use this at the leaf of
+ * a command handler instead of `console.error(...); process.exit(1)`.
+ *
+ * Internal errors (non-AgileflowError) are still printed clearly; their
+ * stack trace is emitted only when `DEBUG=1` is set, so users don't see
+ * Node internals by default.
+ *
+ * @param {Error} err
+ * @param {{ command?: string }} [opts]
+ * @returns {never}
+ */
+function fail(err, opts = {}) {
+  console.error(formatError(err, opts));
+  if (isDebugEnabled() && err.stack) {
+    console.error(chalk.dim(err.stack));
+  }
+  process.exit(1);
+}
+
+/**
+ * Treat DEBUG as set unless it's an explicit falsy string. Mirrors the
+ * convention used by most Node libraries (`debug`, `npm`), where
+ * DEBUG=0 / DEBUG=false / DEBUG="" all mean off.
+ */
+function isDebugEnabled() {
+  const v = process.env.DEBUG;
+  if (!v) return false;
+  const lowered = String(v).toLowerCase();
+  return lowered !== "0" && lowered !== "false" && lowered !== "no";
+}
+
+module.exports = {
+  AgileflowError,
+  MissingFileError,
+  InvalidArgumentError,
+  OperationFailedError,
+  formatError,
+  fail,
+};

package/src/lib/path-check.js

@@ -0,0 +1,39 @@
+/**
+ * Check whether a command is resolvable on the user's PATH.
+ *
+ * Used by `agileflow launch` to detect which AI CLIs (claude, codex,
+ * cursor-agent, aider) are installed so the onboarding picker only
+ * offers real choices.
+ *
+ * Implementation: shell out to `command -v` (POSIX) or `where` (Windows).
+ * Both are built-ins, present on every supported platform, and exit
+ * non-zero when the name is not found.
+ *
+ * Safety: the name argument is constrained to a conservative character
+ * class before being interpolated into the shell command. These are CLI
+ * binary names — not free-form user input — so the restriction is
+ * intentional rather than limiting.
+ */
+const { execSync } = require("child_process");
+
+const SAFE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function commandExists(name) {
+  if (typeof name !== "string" || !SAFE_NAME.test(name)) return false;
+
+  const probe =
+    process.platform === "win32" ? `where ${name}` : `command -v ${name}`;
+
+  try {
+    execSync(probe, { stdio: "ignore", shell: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { commandExists, SAFE_NAME };

package/src/runtime/config/defaults.js

@@ -4,28 +4,26 @@
  * Returned when `agileflow.config.json` is absent. Also merged into
  * user-supplied config so missing sections get sensible defaults.
  *
- * @typedef {Object} Personalization
- * @property {'concise'|'detailed'|'teaching'} tone
- * @property {'none'|'decision_points'|'always'} ask_level
- * @property {'low'|'medium'|'high'} verbosity
- *
  * @typedef {Object} PluginEntry
  * @property {boolean} enabled
  * @property {Record<string, unknown>} [settings]
  *
  * @typedef {Object} Behaviors
- * @property {boolean} loadContext       - SessionStart context dump
- * @property {boolean} babysitDefault    - HARD mentor mode at SessionStart
- * @property {boolean} damageControl     - PreToolUse guards on Bash/Edit/Write
- * @property {boolean} preCompactState   - PreCompact state preservation
+ * @property {boolean} loadContext         - SessionStart context dump
+ * @property {boolean} babysitDefault      - HARD mentor mode at SessionStart
+ * @property {boolean} damageControlBash   - PreToolUse guard on Bash
+ * @property {boolean} damageControlEdit   - PreToolUse guard on Edit
+ * @property {boolean} damageControlWrite  - PreToolUse guard on Write
+ * @property {boolean} preCompactState     - PreCompact state preservation
  *
  * @typedef {Object} AgileflowConfig
  * @property {1} version
  * @property {Record<string, PluginEntry>} plugins
  * @property {Record<string, { enabled?: boolean, timeout?: number, skipOnError?: boolean }>} hooks
+ * @property {{ scope: 'project' | 'global' }} install
  * @property {Behaviors} behaviors
- * @property {Personalization} personalization
- * @property {{ primary: 'claude-code'|'cursor'|'windsurf'|'codex' }} ide
+ * @property {{ enabled: boolean }} learnings
+ * @property {{ primary?: string, targets: Array<'claude-code'|'cursor'|'windsurf'|'codex'|'antigravity'> }} ide
  * @property {string} language
  */
 
@@ -37,22 +35,29 @@ function defaultConfig() {
       core: { enabled: true },
     },
     hooks: {},
+    install: {
+      scope: "project",
+    },
     behaviors: {
       // Behaviors are presets that map to one or more hooks. The
       // wizard surfaces these as a curated multiselect; advanced
       // users can override individual hooks via the `hooks:` map.
       loadContext: true,
       babysitDefault: true,
-      damageControl: true,
+      damageControlBash: true,
+      damageControlEdit: true,
+      damageControlWrite: true,
       preCompactState: true,
     },
-    personalization: {
-      tone: "concise",
-      ask_level: "decision_points",
-      verbosity: "medium",
+    learnings: {
+      // Global on/off for the skill self-improvement system. When false,
+      // install-time scaffolding is skipped and no learnings hint is
+      // injected into the session prompt — the `agileflow learn` CLI
+      // still works for users who want to manually append signals.
+      enabled: true,
     },
     ide: {
-      primary: "claude-code",
+      targets: ["claude-code"],
     },
     language: "en",
   };

package/src/runtime/config/loader.js

@@ -21,9 +21,57 @@ const ajv = new Ajv({ allErrors: true, useDefaults: false, strict: false });
 const validate = ajv.compile(schema);
 
 /**
- * Shallow-merge user config on top of defaults. `plugins`, `hooks`, and
- * `personalization` sub-objects are deep-merged at one level so that
- * partial user configs don't wipe defaults.
+ * Migrate older config shapes into the current schema before validation.
+ * This keeps `agileflow setup` usable across alpha bumps even when a
+ * project already has an older config checked in.
+ *
+ * @param {any} parsed
+ * @returns {any}
+ */
+function migrateLegacyConfig(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return parsed;
+  }
+
+  const migrated = { ...parsed };
+
+  if (
+    migrated.behaviors &&
+    typeof migrated.behaviors === "object" &&
+    !Array.isArray(migrated.behaviors)
+  ) {
+    const behaviors = { ...migrated.behaviors };
+    if (Object.prototype.hasOwnProperty.call(behaviors, "damageControl")) {
+      const damageControl = Boolean(behaviors.damageControl);
+      delete behaviors.damageControl;
+      behaviors.damageControlBash = damageControl;
+      behaviors.damageControlEdit = damageControl;
+      behaviors.damageControlWrite = damageControl;
+    }
+    migrated.behaviors = behaviors;
+  }
+
+  if (
+    migrated.ide &&
+    typeof migrated.ide === "object" &&
+    !Array.isArray(migrated.ide)
+  ) {
+    const ide = { ...migrated.ide };
+    if (!Array.isArray(ide.targets) || ide.targets.length === 0) {
+      if (typeof ide.primary === "string") {
+        ide.targets = [ide.primary];
+      }
+    }
+    migrated.ide = ide;
+  }
+
+  return migrated;
+}
+
+/**
+ * Shallow-merge user config on top of defaults. `plugins` and `hooks`
+ * sub-objects are deep-merged at one level so that partial user configs
+ * don't wipe defaults.
  *
  * @param {import('./defaults.js').AgileflowConfig} defaults
  * @param {Partial<import('./defaults.js').AgileflowConfig>} user
@@ -34,16 +82,35 @@ function mergeConfig(defaults, user) {
     version: user.version ?? defaults.version,
     plugins: { ...defaults.plugins, ...(user.plugins || {}) },
     hooks: { ...defaults.hooks, ...(user.hooks || {}) },
+    install: { ...defaults.install, ...(user.install || {}) },
     behaviors: { ...defaults.behaviors, ...(user.behaviors || {}) },
-    personalization: {
-      ...defaults.personalization,
-      ...(user.personalization || {}),
-    },
-    ide: { ...defaults.ide, ...(user.ide || {}) },
+    learnings: { ...defaults.learnings, ...(user.learnings || {}) },
+    ide: mergeIde(defaults.ide, user.ide),
     language: user.language ?? defaults.language,
   };
 }
 
+/**
+ * Merge user `ide` block onto defaults, normalizing legacy `primary` into
+ * `targets`. Old configs (alpha.1 / alpha.2) shipped only `primary`; we
+ * migrate them in-memory so a single re-install moves them onto the new
+ * shape without forcing the user to hand-edit JSON.
+ *
+ * @param {{ targets: string[], primary?: string }} defaultsIde
+ * @param {{ targets?: string[], primary?: string } | undefined} userIde
+ * @returns {{ targets: string[], primary?: string }}
+ */
+function mergeIde(defaultsIde, userIde) {
+  const merged = { ...defaultsIde, ...(userIde || {}) };
+  if (!Array.isArray(merged.targets) || merged.targets.length === 0) {
+    merged.targets =
+      typeof merged.primary === "string"
+        ? [merged.primary]
+        : [...defaultsIde.targets];
+  }
+  return merged;
+}
+
 /**
  * Format Ajv errors as a single human-readable message with JSON Pointers.
  * @param {import('ajv').ErrorObject[]} errors
@@ -93,6 +160,8 @@ async function loadConfig(cwd) {
     throw new Error(`Invalid JSON in ${configPath}: ${err.message}`);
   }
 
+  parsed = migrateLegacyConfig(parsed);
+
   if (!validate(parsed)) {
     const details = formatSchemaErrors(validate.errors || []);
     throw new Error(`Config validation failed for ${configPath}:\n${details}`);

package/src/runtime/config/schema.json

@@ -39,6 +39,18 @@
         }
       }
     },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where AgileFlow is installed. Project installs write into the current repository; global installs write under the user's home directory.",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["project", "global"],
+          "description": "Install scope for config, AgileFlow state, and IDE mirrors."
+        }
+      }
+    },
     "behaviors": {
       "type": "object",
       "description": "Curated behavior presets. Each maps to one or more hooks the installer wires up. Disabling a behavior excludes its hooks from the generated hook-manifest.yaml.",
@@ -52,9 +64,17 @@
           "type": "boolean",
           "description": "SessionStart: inject the babysit-mentor pattern so Claude defaults to mentor mode without explicit invocation."
         },
-        "damageControl": {
+        "damageControlBash": {
+          "type": "boolean",
+          "description": "PreToolUse: block dangerous Bash commands (rm -rf /, fork bombs, etc.)."
+        },
+        "damageControlEdit": {
           "type": "boolean",
-          "description": "PreToolUse: block dangerous Bash commands and risky Edit/Write paths via the patterns library."
+          "description": "PreToolUse: block risky Edit operations on sensitive paths (.env, .ssh/, etc.)."
+        },
+        "damageControlWrite": {
+          "type": "boolean",
+          "description": "PreToolUse: block risky Write operations on sensitive paths (.env, .ssh/, etc.)."
         },
         "preCompactState": {
           "type": "boolean",
@@ -62,22 +82,12 @@
         }
       }
     },
-    "personalization": {
+    "learnings": {
       "type": "object",
       "additionalProperties": false,
+      "description": "Global on/off for the skill self-improvement system. When false, install-time scaffolding is skipped and no learnings hint is injected into the session prompt.",
       "properties": {
-        "tone": {
-          "type": "string",
-          "enum": ["concise", "detailed", "teaching"]
-        },
-        "ask_level": {
-          "type": "string",
-          "enum": ["none", "decision_points", "always"]
-        },
-        "verbosity": {
-          "type": "string",
-          "enum": ["low", "medium", "high"]
-        }
+        "enabled": { "type": "boolean" }
       }
     },
     "ide": {
@@ -86,7 +96,24 @@
       "properties": {
         "primary": {
           "type": "string",
-          "enum": ["claude-code", "cursor", "windsurf", "codex"]
+          "enum": ["claude-code", "cursor", "windsurf", "codex", "antigravity"],
+          "description": "Deprecated alias for targets[0]; kept for back-compat with prior alphas."
+        },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "claude-code",
+              "cursor",
+              "windsurf",
+              "codex",
+              "antigravity"
+            ]
+          },
+          "description": "IDEs / CLIs to install AgileFlow surface into (skills, hooks, settings)."
         }
       }
     },

package/src/runtime/config/writer.js

@@ -30,14 +30,16 @@ async function writeConfig(cwd, config) {
     version: 1,
     plugins: config.plugins,
     hooks: config.hooks,
+    install: config.install,
     behaviors: config.behaviors,
-    personalization: config.personalization,
+    learnings: config.learnings,
     ide: config.ide,
     language: config.language,
   };
   const content = JSON.stringify(payload, null, 2) + "\n";
 
   try {
+    await fs.promises.mkdir(cwd, { recursive: true });
     await fs.promises.writeFile(tmp, content, "utf8");
     await fs.promises.rename(tmp, file);
   } catch (err) {

package/src/runtime/ide/babysit-skill.js

@@ -0,0 +1,202 @@
+/**
+ * Babysit mentor skill renderer.
+ *
+ * The bundled babysit skill stays as the shared baseline. At install
+ * time we append IDE-specific guidance so the mirrored SKILL.md only
+ * names primitives the target can actually use.
+ */
+const { capabilitiesFor } = require("./capabilities.js");
+
+const VALID_MODES = new Set(["full", "light", "minimal", "custom"]);
+
+const DEFAULT_CUSTOM_FEATURES = {
+  planMode: true,
+  askQuestions: true,
+  taskTracking: true,
+  delegation: true,
+  progressUpdates: true,
+};
+
+/**
+ * @param {any} config
+ * @returns {{ mode: 'full' | 'light' | 'minimal' | 'custom' | null, features: Record<string, boolean> }}
+ */
+function resolveBabysitSettings(config) {
+  const raw =
+    config &&
+    config.plugins &&
+    config.plugins.core &&
+    config.plugins.core.settings &&
+    config.plugins.core.settings.babysit;
+  const mode = raw && VALID_MODES.has(raw.mode) ? raw.mode : null;
+  const features =
+    raw && raw.features && typeof raw.features === "object"
+      ? { ...DEFAULT_CUSTOM_FEATURES, ...raw.features }
+      : { ...DEFAULT_CUSTOM_FEATURES };
+  return { mode, features };
+}
+
+/**
+ * @param {string} targetIde
+ * @param {any} config
+ * @returns {'full' | 'light' | 'minimal' | 'custom'}
+ */
+function resolveBabysitMode(targetIde, config) {
+  const { mode } = resolveBabysitSettings(config);
+  if (mode) return mode;
+  return targetIde === "claude-code" ? "full" : "light";
+}
+
+/**
+ * @param {'full' | 'light' | 'minimal' | 'custom'} mode
+ * @param {Record<string, boolean>} customFeatures
+ * @returns {Record<string, boolean>}
+ */
+function featuresForMode(mode, customFeatures) {
+  if (mode === "custom")
+    return { ...DEFAULT_CUSTOM_FEATURES, ...customFeatures };
+  if (mode === "minimal") {
+    return {
+      planMode: false,
+      askQuestions: false,
+      taskTracking: false,
+      delegation: false,
+      progressUpdates: false,
+    };
+  }
+  if (mode === "light") {
+    return {
+      planMode: true,
+      askQuestions: true,
+      taskTracking: true,
+      delegation: false,
+      progressUpdates: true,
+    };
+  }
+  return { ...DEFAULT_CUSTOM_FEATURES };
+}
+
+/**
+ * Build the IDE-specific appendix for the babysit skill.
+ *
+ * @param {string} targetIde
+ * @param {any} config
+ * @returns {string}
+ */
+function renderBabysitAppendix(targetIde, config) {
+  const caps = capabilitiesFor(targetIde);
+  const mode = resolveBabysitMode(targetIde, config);
+  const settings = resolveBabysitSettings(config);
+  const features = featuresForMode(mode, settings.features);
+
+  const lines = [];
+  lines.push("## IDE-specific guidance");
+  lines.push("");
+  lines.push(`- Installed babysit mode: \`${mode}\``);
+  if (mode === "custom") {
+    const enabled = Object.entries(features)
+      .filter(([, value]) => value)
+      .map(([key]) => key);
+    lines.push(
+      `- Custom behaviors enabled: ${enabled.length ? enabled.join(", ") : "none"}`,
+    );
+  }
+
+  if (targetIde === "claude-code") {
+    if (features.askQuestions) {
+      lines.push(
+        "- Use `AskUserQuestion` at decision points when a choice would benefit from user control.",
+      );
+    }
+    if (features.planMode) {
+      lines.push(
+        "- Use `EnterPlanMode` for non-trivial implementation, then `ExitPlanMode` when the plan is ready.",
+      );
+    }
+    if (features.taskTracking) {
+      lines.push(
+        "- Use `TaskCreate` / `TaskUpdate` for 3+ step work and update as each step lands.",
+      );
+    }
+    if (features.delegation) {
+      lines.push(
+        "- Use subagents for bounded parallel exploration or delegation when the work splits cleanly.",
+      );
+    }
+    if (features.progressUpdates) {
+      lines.push("- Send short progress updates while working for a while.");
+    }
+    if (mode === "light") {
+      lines.push(
+        "- Keep the prompt surface lighter: ask only when blocked or when the next move is genuinely ambiguous.",
+      );
+    }
+    if (mode === "minimal") {
+      lines.push(
+        "- Keep the interaction terse: make one recommendation, explain the next action, and avoid repeated confirmation loops.",
+      );
+    }
+    return `${lines.join("\n")}\n`;
+  }
+
+  if (targetIde === "codex" && features.taskTracking) {
+    lines.push(
+      "- Use Codex tasks for multi-step work and keep the task scoped to a single clear outcome.",
+    );
+  }
+  if (features.askQuestions) {
+    lines.push(
+      "- Use `request_user_input` for small sets of clarifying questions when collaboration mode is enabled; otherwise fall back to a concise numbered choice list with one recommended option first.",
+    );
+  }
+  if (features.planMode) {
+    lines.push(
+      "- Write a short plan in plain text before non-trivial implementation.",
+    );
+  }
+  if (features.delegation) {
+    if (caps.agents) {
+      lines.push(
+        "- Use subagents for bounded parallel exploration or delegation when the work splits cleanly.",
+      );
+    } else {
+      lines.push(
+        "- If subagents are unavailable, keep delegation in plain text and split the work into explicit named steps.",
+      );
+    }
+  }
+  if (features.taskTracking) {
+    lines.push(
+      "- Track progress visibly with a checklist or step list and mark each item complete as soon as it lands.",
+    );
+  }
+  if (features.progressUpdates) {
+    lines.push("- Keep the user updated as each step lands.");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Append IDE-specific babysit guidance to a SKILL.md payload.
+ *
+ * @param {string} skillId
+ * @param {string} sourceText
+ * @param {{ targetIde?: string, config?: any }} [context]
+ * @returns {string}
+ */
+function renderSkillForTarget(skillId, sourceText, context = {}) {
+  if (skillId !== "agileflow-babysit-mentor") {
+    return sourceText;
+  }
+  const targetIde = context.targetIde || "claude-code";
+  const appendix = renderBabysitAppendix(targetIde, context.config);
+  return `${sourceText.replace(/\s+$/u, "")}\n\n${appendix}`;
+}
+
+module.exports = {
+  resolveBabysitSettings,
+  resolveBabysitMode,
+  featuresForMode,
+  renderBabysitAppendix,
+  renderSkillForTarget,
+};