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

package/src/runtime/skills/learnings.js

@@ -0,0 +1,308 @@
+/**
+ * Skill learnings — persistent self-improvement signals per skill.
+ *
+ * Learnings live inside the installed skill directory so they are
+ * co-located with the skill that owns them:
+ *   <skillsDir>/<skillName>/_learnings/<skill>.yaml
+ *
+ * File format:
+ *   # Auto-generated by AgileFlow. Edit carefully — these shape skill behavior.
+ *   version: 1
+ *   skill: agileflow-research
+ *   updated: "2026-05-06"
+ *   entries:
+ *     - id: "abc123"
+ *       confidence: high     # high / medium / low
+ *       created: "2026-05-06"
+ *       observation: "User prefers concise research prompts..."
+ *       source: correction   # correction | confirmation | observation
+ *
+ * Confidence levels:
+ *   - high:   explicit user correction
+ *   - medium: pattern accepted without correction
+ *   - low:    observation; not yet confirmed
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const yaml = require("js-yaml");
+
+const VALID_CONFIDENCE = new Set(["high", "medium", "low"]);
+const VALID_SOURCE = new Set(["correction", "confirmation", "observation"]);
+const CONFIDENCE_ORDER = { high: 0, medium: 1, low: 2 };
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the skillsDir for the primary IDE target from agileflow.config.json.
+ * Falls back to `.claude/skills` if config is absent or unreadable.
+ *
+ * @param {string} projectDir
+ * @returns {string} absolute path to the skills directory
+ */
+function resolveSkillsDir(projectDir) {
+  let IDE_CAPABILITIES = null;
+  try {
+    ({ IDE_CAPABILITIES } = require("../ide/capabilities.js"));
+  } catch {
+    // unavailable — use default
+  }
+
+  let cfg = {};
+  try {
+    const raw = fs.readFileSync(
+      path.join(projectDir, "agileflow.config.json"),
+      "utf8",
+    );
+    cfg = JSON.parse(raw);
+  } catch {
+    // config absent — use default
+  }
+
+  const primaryIde =
+    Array.isArray(cfg?.ide?.targets) && cfg.ide.targets.length > 0
+      ? cfg.ide.targets[0]
+      : "claude-code";
+
+  const skillsDir =
+    IDE_CAPABILITIES?.[primaryIde]?.skillsDir ?? ".claude/skills";
+  return path.join(projectDir, skillsDir);
+}
+
+/**
+ * Resolve the absolute path of a learnings file for a given skill.
+ * The `learns.file` field from frontmatter (e.g. `_learnings/research.yaml`)
+ * is resolved relative to the skill's installed directory.
+ *
+ * @param {string} skillsDir - absolute path to the IDE skills dir
+ * @param {string} skillName - e.g. "agileflow-research"
+ * @param {string} [learnFile] - relative path from frontmatter, e.g. "_learnings/research.yaml"
+ * @returns {string}
+ */
+function resolveLearnFile(skillsDir, skillName, learnFile) {
+  const file = learnFile || `_learnings/${skillName}.yaml`;
+  // Prevent path traversal: discard any leading ../ segments.
+  const safeParts = file.split("/").filter((p) => p && p !== ".." && p !== ".");
+  return path.join(skillsDir, skillName, ...safeParts);
+}
+
+// ---------------------------------------------------------------------------
+// Public API (new spec)
+// ---------------------------------------------------------------------------
+
+/**
+ * Read learnings for a skill.
+ *
+ * @param {string} skillName
+ * @param {string} [projectDir]
+ * @returns {Promise<{ entries: Array, version: number, skill: string }>}
+ */
+async function readLearnings(skillName, projectDir) {
+  const dir = projectDir || process.env.AGILEFLOW_PROJECT_DIR || process.cwd();
+  const skillsDir = resolveSkillsDir(dir);
+  // Look for the standard learnings file path.
+  const p = resolveLearnFile(skillsDir, skillName);
+
+  let text;
+  try {
+    text = await fs.promises.readFile(p, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return { entries: [], version: 1, skill: skillName };
+    throw err;
+  }
+  if (!text.trim()) return { entries: [], version: 1, skill: skillName };
+
+  let doc;
+  try {
+    doc = yaml.load(text);
+  } catch (err) {
+    throw new Error(`learnings file ${p} is not valid YAML: ${err.message}`);
+  }
+  if (!doc || typeof doc !== "object" || !Array.isArray(doc.entries)) {
+    return { entries: [], version: 1, skill: skillName };
+  }
+  return {
+    entries: doc.entries,
+    version: doc.version ?? 1,
+    skill: doc.skill ?? skillName,
+  };
+}
+
+/**
+ * Append a new learning entry.
+ *
+ * @param {string} skillName
+ * @param {string} projectDir
+ * @param {{ observation: string, confidence?: string, source?: string }} entry
+ * @param {{ maxEntries?: number, learnFile?: string }} [opts]
+ * @returns {Promise<void>}
+ */
+async function appendLearning(skillName, projectDir, entry, opts = {}) {
+  const { observation, confidence = "medium", source = "observation" } = entry;
+  const { maxEntries = 30, learnFile } = opts;
+
+  if (typeof observation !== "string" || !observation.trim()) {
+    throw new Error("observation must be a non-empty string");
+  }
+  if (!VALID_CONFIDENCE.has(confidence)) {
+    throw new Error(
+      `confidence must be one of ${[...VALID_CONFIDENCE].join(", ")}`,
+    );
+  }
+  if (!VALID_SOURCE.has(source)) {
+    throw new Error(`source must be one of ${[...VALID_SOURCE].join(", ")}`);
+  }
+  if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+    throw new Error("maxEntries must be a positive integer");
+  }
+
+  const dir = projectDir || process.env.AGILEFLOW_PROJECT_DIR || process.cwd();
+  const skillsDir = resolveSkillsDir(dir);
+  const p = resolveLearnFile(skillsDir, skillName, learnFile);
+
+  // Ensure directory exists.
+  await fs.promises.mkdir(path.dirname(p), { recursive: true });
+
+  // Read existing entries (tolerate missing file).
+  let existing = { entries: [], version: 1, skill: skillName };
+  try {
+    const text = await fs.promises.readFile(p, "utf8");
+    if (text.trim()) {
+      const doc = yaml.load(text);
+      if (doc && Array.isArray(doc.entries)) {
+        existing = {
+          entries: doc.entries,
+          version: doc.version ?? 1,
+          skill: doc.skill ?? skillName,
+        };
+      }
+    }
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+
+  const id = crypto.randomBytes(3).toString("hex");
+  const created = new Date().toISOString().slice(0, 10);
+
+  existing.entries.push({
+    id,
+    confidence,
+    created,
+    observation: observation.trim(),
+    source,
+  });
+
+  // Trim oldest entries if over cap.
+  if (existing.entries.length > maxEntries) {
+    existing.entries.splice(0, existing.entries.length - maxEntries);
+  }
+
+  const header = `# Auto-generated by AgileFlow. Edit carefully — these shape skill behavior.\n`;
+  const doc = {
+    version: existing.version,
+    skill: skillName,
+    updated: created,
+    entries: existing.entries,
+  };
+  const body = yaml.dump(doc, { lineWidth: 120 });
+
+  // Atomic write via temp file + rename.
+  const tmp = `${p}.tmp-${process.pid}`;
+  await fs.promises.writeFile(tmp, header + body, "utf8");
+  await fs.promises.rename(tmp, p);
+}
+
+/**
+ * Format learnings as a markdown block for injection into context.
+ * Returns null if there are no entries.
+ * Sorts entries by confidence: high first, then medium, then low.
+ *
+ * @param {{ entries: Array<{confidence: string, observation: string}>, skill?: string }} learnings
+ * @returns {string|null}
+ */
+function formatLearningsBlock(learnings) {
+  if (
+    !learnings ||
+    !Array.isArray(learnings.entries) ||
+    learnings.entries.length === 0
+  ) {
+    return null;
+  }
+
+  const sorted = [...learnings.entries].sort(
+    (a, b) =>
+      (CONFIDENCE_ORDER[a.confidence] ?? 99) -
+      (CONFIDENCE_ORDER[b.confidence] ?? 99),
+  );
+
+  const skillLabel = learnings.skill || "skill";
+  const lines = [
+    `## Learned preferences (${skillLabel})`,
+    "",
+    "From past sessions in this project:",
+  ];
+
+  for (const e of sorted) {
+    lines.push(`- [${e.confidence} confidence] ${e.observation}`);
+  }
+
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Legacy API (kept for install.js compat)
+// ---------------------------------------------------------------------------
+
+const LEARNINGS_DIR_REL = path.join(".agileflow", "skills", "_learnings");
+
+/**
+ * Resolve path for legacy scaffold usage.
+ * @param {string} projectRoot
+ * @param {string} file
+ */
+function learningsPath(projectRoot, file) {
+  const flat = path.basename(file || "").trim();
+  if (!flat || flat.startsWith(".")) {
+    throw new Error(`invalid learnings filename: ${JSON.stringify(file)}`);
+  }
+  return path.join(projectRoot, LEARNINGS_DIR_REL, flat);
+}
+
+/**
+ * Create an empty learnings file in the legacy location if it does not exist.
+ * Used by install.js to scaffold at install time.
+ *
+ * @param {string} projectRoot
+ * @param {string} skillId
+ * @param {string} file
+ * @returns {Promise<{ path: string, created: boolean }>}
+ */
+async function scaffoldLearnings(projectRoot, skillId, file) {
+  const p = learningsPath(projectRoot, file);
+  await fs.promises.mkdir(path.dirname(p), { recursive: true });
+  try {
+    await fs.promises.access(p);
+    return { path: p, created: false };
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+  const header = `# AgileFlow skill learnings — ${skillId}\n# Append-only signals; oldest trimmed when count exceeds maxEntries.\nentries: []\n`;
+  await fs.promises.writeFile(p, header, "utf8");
+  return { path: p, created: true };
+}
+
+module.exports = {
+  // New spec API
+  readLearnings,
+  appendLearning,
+  formatLearningsBlock,
+  resolveSkillsDir,
+  resolveLearnFile,
+  // Legacy (install.js compat)
+  scaffoldLearnings,
+  learningsPath,
+  LEARNINGS_DIR_REL,
+};

package/content/plugins/core/hooks/babysit-mentor-injector.js

@@ -1,55 +0,0 @@
-#!/usr/bin/env node
-/**
- * Core hook: babysit-mentor-injector (SessionStart, HARD mode).
- *
- * Pre-loads the babysit mentor pattern into the session by printing
- * its operating rules to stdout. Claude Code includes this in the
- * session context, so Claude defaults to mentor behavior (smart
- * AskUserQuestion at every decision point, plan mode for non-trivial
- * tasks, expert delegation, task tracking, audits) without the user
- * needing to type "walk me through".
- *
- * Disable this hook in agileflow.config.json if you want quick-edit
- * mode by default — the agileflow-babysit-mentor skill still
- * activates on its keyword triggers when needed.
- *
- * Always exits 0.
- */
-process.stdout.write(`## AgileFlow Mentor Mode (default-on)
-
-This session has the babysit-mentor pattern enabled. Apply these
-rules unless the user explicitly opts out for a specific request:
-
-1. **Smart AskUserQuestion at every decision point.** When the work
-   reaches a meaningful choice (which task, which approach, whether
-   to commit), end the response with the AskUserQuestion tool —
-   specific options with one marked (Recommended). Never generic
-   "Continue?" / "What next?".
-
-2. **Plan mode for non-trivial implementation.** Call EnterPlanMode
-   for anything more than a typo/one-liner. Explore 3–5 files,
-   write the plan, ExitPlanMode. Skip for trivial fixes.
-
-3. **Delegate complex work to domain experts.** Use the Task tool
-   with appropriate subagent_type (database / api / ui / testing /
-   security / etc.) for complex single-domain work. Use the
-   orchestrator for multi-domain features. Use multi-expert for
-   review/analysis questions.
-
-4. **Track progress.** TaskCreate for any task with 3+ steps.
-   TaskUpdate as each completes. Don't batch.
-
-5. **Suggest a logic audit after every implementation.** After tests
-   pass, present "🔍 Run logic audit on modified files" as
-   (Recommended). 5 analyzers catch edge cases tests miss.
-
-6. **Suggest a flow audit when user-flows changed.** Plans for
-   non-trivial features must include a "Verify flow integrity"
-   step. After tests pass on flow-touching code, suggest
-   "🔄 Run flow audit" before commit.
-
-To disable mentor mode entirely: edit agileflow.config.json,
-set hooks.babysit-mentor-injector.enabled to false, run
-\`agileflow update\`.
-`);
-process.exit(0);

package/src/cli/wizard/personalization.js

@@ -1,64 +0,0 @@
-/**
- * Personalization prompts — three Clack selects for tone, ask-level, verbosity.
- *
- * v4.0-alpha scope: three enum flags that render into a short
- * `{{PERSONALIZATION_BLOCK}}` in each installed SKILL.md (the renderer lands
- * in Phase 5). ADR-0015 covers the future XML-tag matrix.
- */
-const prompts = require('@clack/prompts');
-
-/**
- * @param {import('../../runtime/config/defaults.js').Personalization} current
- * @returns {Promise<import('../../runtime/config/defaults.js').Personalization>}
- */
-async function personalizationPrompts(current) {
-  const tone = await prompts.select({
-    message: 'How should AgileFlow respond?',
-    options: [
-      { value: 'concise', label: 'Concise', hint: 'Tight answers, low ceremony' },
-      { value: 'detailed', label: 'Detailed', hint: 'More context and explanation' },
-      { value: 'teaching', label: 'Teaching', hint: 'Walk through the why' },
-    ],
-    initialValue: current.tone,
-  });
-  if (prompts.isCancel(tone)) {
-    prompts.cancel('Setup cancelled. No changes made.');
-    process.exit(1);
-  }
-
-  const askLevel = await prompts.select({
-    message: 'When should AgileFlow ask for confirmation?',
-    options: [
-      { value: 'none', label: 'Never', hint: 'Fully autonomous' },
-      { value: 'decision_points', label: 'At decision points', hint: 'Standard' },
-      { value: 'always', label: 'Always', hint: 'Confirm before each step' },
-    ],
-    initialValue: current.ask_level,
-  });
-  if (prompts.isCancel(askLevel)) {
-    prompts.cancel('Setup cancelled. No changes made.');
-    process.exit(1);
-  }
-
-  const verbosity = await prompts.select({
-    message: 'Output length preference?',
-    options: [
-      { value: 'low', label: 'Low', hint: 'Short responses' },
-      { value: 'medium', label: 'Medium', hint: 'Balanced' },
-      { value: 'high', label: 'High', hint: 'Full context' },
-    ],
-    initialValue: current.verbosity,
-  });
-  if (prompts.isCancel(verbosity)) {
-    prompts.cancel('Setup cancelled. No changes made.');
-    process.exit(1);
-  }
-
-  return {
-    tone: /** @type {any} */ (tone),
-    ask_level: /** @type {any} */ (askLevel),
-    verbosity: /** @type {any} */ (verbosity),
-  };
-}
-
-module.exports = { personalizationPrompts };