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

package/src/cli/wizard/babysit-mode-picker.js

@@ -0,0 +1,192 @@
+/**
+ * Babysit mode picker with plain labels and short hints.
+ */
+const prompts = require("@clack/prompts");
+const chalk = require("chalk");
+const { optionLabel, questionMessage } = require("../../lib/brand.js");
+
+const MODES = [
+  {
+    value: "full",
+    label: optionLabel(
+      "Full guidance",
+      "Uses the most interactive flow available for the selected IDEs.",
+    ),
+    hint: chalk.dim(
+      "Uses the most interactive flow available for the selected IDEs.",
+    ),
+  },
+  {
+    value: "light",
+    label: optionLabel(
+      "Guided mode",
+      "Keeps prompts short and only interrupts when needed.",
+    ),
+    hint: "Keeps the mentor flow on, but asks less often.",
+  },
+  {
+    value: "minimal",
+    label: optionLabel("Minimal mode", "Stays terse and avoids extra prompts."),
+    hint: "Stays terse and avoids extra prompts.",
+  },
+  {
+    value: "custom",
+    label: optionLabel(
+      "Customize",
+      "Choose exactly which mentor behaviors are enabled.",
+    ),
+    hint: "Pick the behaviors you want.",
+  },
+];
+
+const CUSTOM_FEATURES = [
+  {
+    value: "askQuestions",
+    label: "Ask questions",
+    hint: "Ask at decision points with specific options.",
+  },
+  {
+    value: "planMode",
+    label: "Plan mode",
+    hint: "Plan before non-trivial implementation.",
+  },
+  {
+    value: "delegation",
+    label: "Delegation",
+    hint: "Use subagents when work splits cleanly.",
+  },
+  {
+    value: "taskTracking",
+    label: "Task tracking",
+    hint: "Use visible task lists for multi-step work.",
+  },
+  {
+    value: "progressUpdates",
+    label: "Progress updates",
+    hint: "Send short status updates while working.",
+  },
+  {
+    value: "auditAll",
+    label: "Audit everything",
+    hint: "Run all enabled audits after every implementation, not just when relevant.",
+  },
+  {
+    value: "logicAudit",
+    label: "Logic audit",
+    hint: "Suggest after implementation.",
+  },
+  {
+    value: "flowAudit",
+    label: "Flow audit",
+    hint: "Suggest after implementation when user-facing flows changed.",
+  },
+  {
+    value: "securityAudit",
+    label: "Security audit",
+    hint: "Suggest after implementation when auth, APIs, or sensitive data involved.",
+  },
+  {
+    value: "performanceAudit",
+    label: "Performance audit",
+    hint: "Suggest after implementation when queries, rendering, or data size involved.",
+  },
+  {
+    value: "accessibilityAudit",
+    label: "Accessibility audit",
+    hint: "Suggest after implementation when UI components changed.",
+  },
+  {
+    value: "legalAudit",
+    label: "Legal audit",
+    hint: "Suggest after implementation when data handling, privacy, or compliance involved.",
+  },
+  {
+    value: "strictMode",
+    label: "Strict gates",
+    hint: "Require tests and review to pass before commit.",
+  },
+  {
+    value: "tddMode",
+    label: "TDD mode",
+    hint: "Enforce RED → GREEN → REFACTOR phases.",
+  },
+];
+
+const DEFAULT_CUSTOM_FEATURES = {
+  askQuestions: true,
+  planMode: true,
+  delegation: true,
+  taskTracking: true,
+  progressUpdates: true,
+  auditAll: false,
+  logicAudit: true,
+  flowAudit: true,
+  securityAudit: true,
+  performanceAudit: false,
+  accessibilityAudit: false,
+  legalAudit: false,
+  strictMode: false,
+  tddMode: false,
+};
+
+/**
+ * @param {string | { mode?: string, features?: Record<string, boolean> } | undefined} current
+ * @returns {Promise<{ mode: 'full' | 'light' | 'minimal' | 'custom', features?: Record<string, boolean> }>}
+ */
+async function pickBabysitMode(current = "light") {
+  const currentMode =
+    typeof current === "string" ? current : current && current.mode;
+  const option = await prompts.select({
+    message: questionMessage("How should AgileFlow guide babysit work?"),
+    options: MODES,
+    initialValue: MODES.some((m) => m.value === currentMode)
+      ? currentMode
+      : "light",
+  });
+
+  if (prompts.isCancel(option)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  if (option !== "custom") {
+    return { mode: /** @type {'full' | 'light' | 'minimal'} */ (option) };
+  }
+
+  const currentFeatures =
+    current && typeof current === "object" && current.features
+      ? current.features
+      : {};
+  const initialFeatures = { ...DEFAULT_CUSTOM_FEATURES, ...currentFeatures };
+  const picked = await prompts.multiselect({
+    message: questionMessage("Customize guidance behaviors"),
+    options: CUSTOM_FEATURES,
+    initialValues: CUSTOM_FEATURES.filter((f) => initialFeatures[f.value]).map(
+      (f) => f.value,
+    ),
+    required: false,
+  });
+
+  if (prompts.isCancel(picked)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  const selected = new Set(/** @type {string[]} */ (picked));
+  return {
+    mode: "custom",
+    features: Object.fromEntries(
+      CUSTOM_FEATURES.map((feature) => [
+        feature.value,
+        selected.has(feature.value),
+      ]),
+    ),
+  };
+}
+
+module.exports = {
+  MODES,
+  CUSTOM_FEATURES,
+  DEFAULT_CUSTOM_FEATURES,
+  pickBabysitMode,
+};

package/src/cli/wizard/behaviors-picker.js

@@ -1,14 +1,19 @@
 /**
- * Behaviors picker — curated multiselect for the 4 hook-driven presets.
+ * Behaviors picker — one prompt per behavior so each gets its own
+ * decision point, plus a sub-multiselect for damage-control tools so
+ * users can keep Bash blocking while loosening Edit/Write (or vice
+ * versa).
  *
- * Behaviors map 1:N to hooks declared in plugin manifests via the
- * `behavior: <key>` field. Disabling a behavior here excludes its hooks
- * from the generated `.agileflow/hook-manifest.yaml` at install time.
+ * Each behavior maps 1:N to hooks declared in plugin manifests via
+ * `behavior: <key>`. Disabling a behavior excludes its hooks from the
+ * generated `.agileflow/hook-manifest.yaml` at install time.
  *
  * Pure logic lives in `buildBehaviorsMap()` so it can be unit-tested
  * without spawning a TTY.
  */
 const prompts = require("@clack/prompts");
+const chalk = require("chalk");
+const { questionMessage } = require("../../lib/brand.js");
 
 /**
  * @typedef {import('../../runtime/config/defaults.js').Behaviors} Behaviors
@@ -18,91 +23,240 @@ const prompts = require("@clack/prompts");
 const BEHAVIOR_OPTIONS = [
   {
     key: "loadContext",
-    label: "Load project context at session start",
-    hint: "SessionStart hook prints stories, dirty files, and recent commits so Claude has project context immediately.",
+    label: "Load project context",
+    hint: "Show stories, dirty files, and recent commits at session start.",
   },
   {
     key: "babysitDefault",
-    label: "Activate Babysit mentor by default",
-    hint: "SessionStart hook injects the mentor pattern so Claude defaults to mentor mode without /agileflow:babysit.",
+    label: "Enable guidance on start",
+    hint: "Inject your configured guidance preferences at the start of every session.",
   },
   {
-    key: "damageControl",
-    label: "Damage control on Bash, Edit, Write",
-    hint: "PreToolUse hooks block dangerous commands (rm -rf /, fork bombs) and risky writes (.env, .ssh/) — fail-closed.",
+    key: "preCompactState",
+    label: "Preserve context on start",
+    hint: "Re-inject story, command, and git state after compaction so nothing is lost.",
   },
+];
+
+const DAMAGE_CONTROL_TOOLS = [
   {
-    key: "preCompactState",
-    label: "Save context before compaction",
-    hint: "PreCompact hook dumps active stories, current command, and dirty git state so they survive compaction.",
+    key: "damageControlBash",
+    label: "Bash",
+    hint: "Block risky shell commands.",
+  },
+  {
+    key: "damageControlEdit",
+    label: "Edit",
+    hint: "Block edits to sensitive paths.",
+  },
+  {
+    key: "damageControlWrite",
+    label: "Write",
+    hint: "Block writes to sensitive paths.",
   },
 ];
 
 /**
- * Build a complete Behaviors map from a set of selected keys, falling
- * back to current values for any key not represented in the selection
- * input. Missing keys default to `false` (the user actively saw the
- * option and chose not to enable it).
+ * Build a complete Behaviors map from a partial set of toggles. Missing
+ * keys fall back to `false` (the user actively saw the option and chose
+ * not to enable it).
  *
- * @param {Iterable<string>} selectedKeys
+ * @param {Partial<Behaviors>} input
  * @returns {Behaviors}
  */
-function buildBehaviorsMap(selectedKeys) {
-  const set = new Set(selectedKeys);
-  /** @type {Behaviors} */
-  const result = {
-    loadContext: set.has("loadContext"),
-    babysitDefault: set.has("babysitDefault"),
-    damageControl: set.has("damageControl"),
-    preCompactState: set.has("preCompactState"),
+function buildBehaviorsMap(input) {
+  return {
+    loadContext: Boolean(input.loadContext),
+    babysitDefault: Boolean(input.babysitDefault),
+    damageControlBash: Boolean(input.damageControlBash),
+    damageControlEdit: Boolean(input.damageControlEdit),
+    damageControlWrite: Boolean(input.damageControlWrite),
+    preCompactState: Boolean(input.preCompactState),
   };
-  return result;
 }
 
 /**
- * Pre-check options whose keys are currently enabled (or — when no
- * existing config — fall back to the preset's enabledByDefault). The
- * default-on shape lives in `defaults.js`; this just reads it.
+ * Initial value lookup: respect existing config, else fall back to
+ * "default-on" — every behavior is enabled out of the box.
  *
- * @param {Partial<Behaviors>} [current]
- * @returns {string[]}
+ * @param {Partial<Behaviors>|undefined} current
+ * @param {string} key
+ * @returns {boolean}
  */
-function initialSelectedKeys(current) {
-  if (!current) return BEHAVIOR_OPTIONS.map((o) => o.key);
-  return BEHAVIOR_OPTIONS.filter((o) => current[o.key] !== false).map(
-    (o) => o.key,
-  );
+function initialFor(current, key) {
+  if (!current) return true;
+  return current[key] !== false;
+}
+
+/**
+ * @param {Set<string>|string[]|undefined} supportedHookEvents
+ * @param {string} event
+ * @returns {boolean}
+ */
+function supportsEvent(supportedHookEvents, event) {
+  if (!supportedHookEvents) return true;
+  if (Array.isArray(supportedHookEvents))
+    return supportedHookEvents.includes(event);
+  return supportedHookEvents.has(event);
 }
 
 /**
- * Interactive picker. Returns a complete Behaviors object.
+ * Normalize a behaviors object against the supported hook events for the
+ * active IDE targets.
  *
- * @param {Partial<Behaviors>} [currentBehaviors]
- * @returns {Promise<Behaviors>}
+ * Unsupported behaviors are forced to false so the resulting config does
+ * not advertise hooks the selected IDEs cannot run.
+ *
+ * @param {Partial<Behaviors>} input
+ * @param {Set<string>|string[]|undefined} supportedHookEvents
+ * @returns {Behaviors}
  */
-async function pickBehaviors(currentBehaviors) {
-  const picked = await prompts.multiselect({
-    message: "Which behaviors should AgileFlow run? (Recommended: all)",
-    options: BEHAVIOR_OPTIONS.map((o) => ({
-      value: o.key,
-      label: o.label,
-      hint: o.hint,
-    })),
-    initialValues: initialSelectedKeys(currentBehaviors),
-    required: false,
+function normalizeBehaviorsForEvents(input, supportedHookEvents) {
+  return buildBehaviorsMap({
+    loadContext: supportsEvent(supportedHookEvents, "SessionStart")
+      ? input.loadContext
+      : false,
+    babysitDefault: supportsEvent(supportedHookEvents, "SessionStart")
+      ? input.babysitDefault
+      : false,
+    damageControlBash: supportsEvent(supportedHookEvents, "PreToolUse")
+      ? input.damageControlBash
+      : false,
+    damageControlEdit: supportsEvent(supportedHookEvents, "PreToolUse")
+      ? input.damageControlEdit
+      : false,
+    damageControlWrite: supportsEvent(supportedHookEvents, "PreToolUse")
+      ? input.damageControlWrite
+      : false,
+    preCompactState: supportsEvent(supportedHookEvents, "PostCompact")
+      ? input.preCompactState
+      : false,
   });
+}
 
-  if (prompts.isCancel(picked)) {
+/**
+ * Wrap each Clack prompt to handle Ctrl+C / Esc consistently.
+ *
+ * @template T
+ * @param {T | symbol} value
+ * @returns {T}
+ */
+function ensureNotCancelled(value) {
+  if (prompts.isCancel(value)) {
     prompts.cancel("Setup cancelled. No changes made.");
     process.exit(1);
   }
+  return /** @type {T} */ (value);
+}
+
+/**
+ * Interactive picker. Asks one question per behavior, with a follow-up
+ * multiselect for damage control when enabled.
+ *
+ * @param {Partial<Behaviors>} [currentBehaviors]
+ * @param {Set<string>|string[]} [supportedHookEvents]
+ * @returns {Promise<Behaviors>}
+ */
+async function pickBehaviors(currentBehaviors, supportedHookEvents) {
+  /** @type {Partial<Behaviors>} */
+  const result = {};
+
+  const supportsSessionStart = supportsEvent(
+    supportedHookEvents,
+    "SessionStart",
+  );
+  const supportsPreCompact = supportsEvent(supportedHookEvents, "PostCompact");
+  const supportsPreToolUse = supportsEvent(supportedHookEvents, "PreToolUse");
+
+  if (supportsSessionStart) {
+    for (const opt of BEHAVIOR_OPTIONS.filter(
+      (o) => o.key !== "preCompactState",
+    )) {
+      const choice = ensureNotCancelled(
+        await prompts.confirm({
+          message: questionMessage(opt.label, opt.hint),
+          initialValue: initialFor(currentBehaviors, opt.key),
+        }),
+      );
+      result[opt.key] = Boolean(choice);
+    }
+  } else {
+    result.loadContext = false;
+    result.babysitDefault = false;
+  }
+
+  if (supportsPreCompact) {
+    const opt = BEHAVIOR_OPTIONS.find((o) => o.key === "preCompactState");
+    const choice = ensureNotCancelled(
+      await prompts.confirm({
+        message: questionMessage(opt.label, opt.hint),
+        initialValue: initialFor(currentBehaviors, opt.key),
+      }),
+    );
+    result[opt.key] = Boolean(choice);
+  } else {
+    result.preCompactState = false;
+  }
+
+  if (supportsPreToolUse) {
+    // Damage control: master toggle, then per-tool sub-toggles when on.
+    const anyDamageOn =
+      initialFor(currentBehaviors, "damageControlBash") ||
+      initialFor(currentBehaviors, "damageControlEdit") ||
+      initialFor(currentBehaviors, "damageControlWrite");
+
+    const damageOn = ensureNotCancelled(
+      await prompts.confirm({
+        message: questionMessage(
+          "Enable damage control hooks",
+          "Block risky Bash, Edit, and Write actions before they run.",
+        ),
+        initialValue: anyDamageOn,
+      }),
+    );
+
+    if (!damageOn) {
+      result.damageControlBash = false;
+      result.damageControlEdit = false;
+      result.damageControlWrite = false;
+    } else {
+      const initialTools = DAMAGE_CONTROL_TOOLS.filter((t) =>
+        initialFor(currentBehaviors, t.key),
+      ).map((t) => t.key);
+
+      const picked = ensureNotCancelled(
+        await prompts.multiselect({
+          message: questionMessage("Which tools should be guarded?"),
+          options: DAMAGE_CONTROL_TOOLS.map((t) => ({
+            value: t.key,
+            label: chalk.bold(t.label),
+            hint: t.hint,
+          })),
+          initialValues: initialTools.length
+            ? initialTools
+            : DAMAGE_CONTROL_TOOLS.map((t) => t.key),
+          required: false,
+        }),
+      );
+      const set = new Set(/** @type {string[]} */ (picked));
+      for (const t of DAMAGE_CONTROL_TOOLS) {
+        result[t.key] = set.has(t.key);
+      }
+    }
+  } else {
+    result.damageControlBash = false;
+    result.damageControlEdit = false;
+    result.damageControlWrite = false;
+  }
 
-  return buildBehaviorsMap(/** @type {string[]} */ (picked));
+  return normalizeBehaviorsForEvents(result, supportedHookEvents);
 }
 
 module.exports = {
   pickBehaviors,
   buildBehaviorsMap,
-  initialSelectedKeys,
   BEHAVIOR_OPTIONS,
+  DAMAGE_CONTROL_TOOLS,
+  supportsEvent,
+  normalizeBehaviorsForEvents,
 };

package/src/cli/wizard/ide-picker.js

@@ -1,57 +1,69 @@
 /**
- * IDE / CLI picker — Clack select prompt.
+ * IDE / CLI picker — Clack multiselect prompt.
  *
- * Asks the user which agentic IDE or CLI they're targeting. Defaults to
- * Claude Code (the full-feature target). The choice is persisted to
- * `agileflow.config.json` at `ide.primary` and gates which plugin
- * content the installer writes (hooks, skills, etc. — see
- * `runtime/ide/capabilities.js`).
+ * Asks the user which agentic IDEs / CLIs to install AgileFlow into.
+ * Multiple selections are supported (space toggles); the result is
+ * persisted to `agileflow.config.json` at `ide.targets`. The installer
+ * mirrors skills into each selected IDE's dotdir and writes hooks /
+ * settings only into IDEs whose capability map declares them.
  */
-const prompts = require('@clack/prompts');
+const prompts = require("@clack/prompts");
 const {
   IDE_CAPABILITIES,
   SUPPORTED_IDES,
   capabilitiesFor,
-} = require('../../runtime/ide/capabilities.js');
+} = require("../../runtime/ide/capabilities.js");
+const { questionMessage } = require("../../lib/brand.js");
 
 /**
- * @param {string} currentIde - existing config's ide.primary
- * @returns {Promise<string>} selected ide id
+ * @param {string[]} currentTargets - existing config's ide.targets
+ * @returns {Promise<string[]>} selected ide ids (>=1)
  */
-async function pickIde(currentIde) {
-  const initialValue = SUPPORTED_IDES.includes(currentIde) ? currentIde : 'claude-code';
+async function pickIdes(currentTargets) {
+  const valid = (currentTargets || []).filter((id) =>
+    SUPPORTED_IDES.includes(id),
+  );
+  const initialValues = valid.length ? valid : ["claude-code"];
 
-  const choice = await prompts.select({
-    message: 'Which IDE / CLI are you using?',
+  const choice = await prompts.multiselect({
+    message: questionMessage(
+      "Which IDEs / CLIs should AgileFlow install into?",
+    ),
     options: SUPPORTED_IDES.map((id) => {
       const caps = IDE_CAPABILITIES[id];
-      const featureList = ['hooks', 'skills', 'commands', 'agents', 'mcp']
+      const features = ["hooks", "skills", "agents"]
         .filter((f) => caps[f])
-        .join(', ');
+        .join(", ");
       return {
         value: id,
         label: caps.description,
-        hint: featureList ? `enables: ${featureList}` : '(very limited support)',
+        hint: features || "(limited)",
       };
     }),
-    initialValue,
+    initialValues,
+    required: true,
   });
 
   if (prompts.isCancel(choice)) {
-    prompts.cancel('Setup cancelled. No changes made.');
+    prompts.cancel("Setup cancelled. No changes made.");
     process.exit(1);
   }
 
-  const caps = capabilitiesFor(/** @type {string} */ (choice));
-  const disabled = ['hooks', 'skills', 'commands', 'agents']
-    .filter((f) => !caps[f]);
-  if (disabled.length) {
-    prompts.log.warn(
-      `${choice}: ${disabled.join(', ')} won't be installed (not supported by this IDE).`,
-    );
+  const targets = /** @type {string[]} */ (choice);
+
+  // Surface what each target won't get — so a user picking only Cursor
+  // isn't surprised that hooks/agents weren't installed.
+  for (const id of targets) {
+    const caps = capabilitiesFor(id);
+    const disabled = ["hooks", "skills", "agents"].filter((f) => !caps[f]);
+    if (disabled.length) {
+      prompts.log.warn(
+        `${caps.description}: ${disabled.join(", ")} are not available here.`,
+      );
+    }
   }
 
-  return /** @type {string} */ (choice);
+  return targets;
 }
 
-module.exports = { pickIde };
+module.exports = { pickIdes };

package/src/cli/wizard/install-scope-picker.js

@@ -0,0 +1,57 @@
+/**
+ * Install scope picker — choose project-local or user-global install roots.
+ */
+const prompts = require("@clack/prompts");
+const { optionLabel, questionMessage } = require("../../lib/brand.js");
+
+const INSTALL_SCOPE_OPTIONS = [
+  {
+    value: "project",
+    label: optionLabel(
+      "Project install",
+      "Writes AgileFlow into this repository only.",
+    ),
+    hint: "Best when each repo has its own plugins, hooks, and state.",
+  },
+  {
+    value: "global",
+    label: optionLabel(
+      "Global install",
+      "Writes AgileFlow once under your home directory.",
+    ),
+    hint: "Best when you want the same commands and agents available everywhere.",
+  },
+];
+
+/**
+ * @param {string | undefined} currentScope
+ * @returns {'project' | 'global'}
+ */
+function initialInstallScope(currentScope) {
+  return currentScope === "global" ? "global" : "project";
+}
+
+/**
+ * @param {string | undefined} currentScope
+ * @returns {Promise<'project' | 'global'>}
+ */
+async function pickInstallScope(currentScope = "project") {
+  const choice = await prompts.select({
+    message: questionMessage("Where should AgileFlow install?"),
+    options: INSTALL_SCOPE_OPTIONS,
+    initialValue: initialInstallScope(currentScope),
+  });
+
+  if (prompts.isCancel(choice)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  return /** @type {'project' | 'global'} */ (choice);
+}
+
+module.exports = {
+  INSTALL_SCOPE_OPTIONS,
+  initialInstallScope,
+  pickInstallScope,
+};