agileflow 3.4.3 → 4.0.0-alpha.10

package/content/plugins/core/hooks/preferences-injector.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * Core hook: preferences-injector (SessionStart).
+ *
+ * Reads agileflow.config.json and emits a concise user-preferences block
+ * so every skill and interaction in the session automatically respects
+ * the user's configured settings — without each skill needing its own
+ * config-reading logic.
+ *
+ * Always exits 0.
+ */
+const path = require("path");
+const fs = require("fs");
+
+const projectDir =
+  process.env.AGILEFLOW_PROJECT_DIR ||
+  process.env.CLAUDE_PROJECT_DIR ||
+  process.cwd();
+
+// Resolve capabilities.js from the installed runtime or the source tree.
+let IDE_CAPABILITIES = null;
+try {
+  ({ IDE_CAPABILITIES } = require("../../../src/runtime/ide/capabilities.js"));
+} catch {
+  try {
+    // Installed path: node_modules/agileflow/src/runtime/ide/capabilities.js
+    ({
+      IDE_CAPABILITIES,
+    } = require("agileflow/src/runtime/ide/capabilities.js"));
+  } catch {
+    // capabilities unavailable — skip capability block
+  }
+}
+
+// Resolve learnings helpers from the installed runtime or the source tree.
+let _readLearnings = null;
+let _formatLearningsBlock = null;
+try {
+  const learnings = require("../../../src/runtime/skills/learnings.js");
+  _readLearnings = learnings.readLearnings;
+  _formatLearningsBlock = learnings.formatLearningsBlock;
+} catch {
+  try {
+    const learnings = require("agileflow/src/runtime/skills/learnings.js");
+    _readLearnings = learnings.readLearnings;
+    _formatLearningsBlock = learnings.formatLearningsBlock;
+  } catch {
+    // learnings unavailable — skip learnings block
+  }
+}
+
+module.exports = { buildPreferencesBlock, buildLearningsBlock };
+
+function buildCapabilitiesBlock(cfg) {
+  if (!IDE_CAPABILITIES) return null;
+
+  const targets = cfg?.ide?.targets;
+  if (!Array.isArray(targets) || targets.length === 0) return null;
+
+  // Use the first target as the primary IDE for capability detection.
+  const primaryIde = targets[0];
+  const caps = IDE_CAPABILITIES[primaryIde];
+  if (!caps) return null;
+
+  const tick = (v) => (v ? "✓" : "✗");
+
+  const lines = [
+    `## Runtime Capabilities (${caps.description})`,
+    "",
+    "Skills and workflows adapt their behavior based on what this IDE supports:",
+    "",
+    `| Capability | Available | Behavior when unavailable |`,
+    `|------------|-----------|--------------------------|`,
+    `| **Interactive prompts** (AskUserQuestion) | ${tick(caps.interactivePrompts)} | Present options as a numbered list instead |`,
+    `| **Agent spawning** (Task / multi-agent) | ${tick(caps.multiAgent)} | Work through each analysis inline, sequentially |`,
+    `| **Session restore** (PostCompact hook) | ${tick(caps.sessionRestore)} | Re-state context manually if conversation compacts |`,
+    `| **Lifecycle hooks** | ${tick(caps.hooks)} | Guidance and state injection unavailable between sessions |`,
+    "",
+  ];
+
+  if (!caps.interactivePrompts) {
+    lines.push(
+      "**Note:** This IDE does not support interactive prompts. When a workflow says to present options, write a numbered list and ask the user to reply with a number.",
+    );
+  }
+  if (!caps.multiAgent) {
+    lines.push(
+      "**Note:** This IDE does not support agent spawning. When a workflow calls for running multiple expert agents in parallel, perform each analysis inline and sequentially instead.",
+    );
+  }
+
+  // Filter trailing empty string if no notes added
+  return lines.join("\n").trimEnd();
+}
+
+function buildPreferencesBlock() {
+  let cfg = {};
+  try {
+    const raw = fs.readFileSync(
+      path.join(projectDir, "agileflow.config.json"),
+      "utf8",
+    );
+    cfg = JSON.parse(raw);
+  } catch {
+    // config missing — emit nothing
+    return null;
+  }
+
+  const babysit = cfg?.plugins?.core?.settings?.babysit;
+  if (!babysit) return null;
+
+  const mode = babysit.mode || "full";
+  const f = babysit.features || {};
+
+  const on = (key) => {
+    if (mode === "full") return true;
+    if (mode === "light")
+      return ["askQuestions", "planMode", "taskTracking"].includes(key);
+    if (mode === "minimal") return key === "askQuestions";
+    // custom — default true for core features unless explicitly false
+    const defaults = {
+      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,
+    };
+    return key in f ? f[key] : (defaults[key] ?? false);
+  };
+
+  const prefs = [];
+
+  if (on("askQuestions")) {
+    prefs.push(
+      '- **Ask at decision points** — end responses with AskUserQuestion (specific options, one marked Recommended). Never generic "Continue?".',
+    );
+  }
+  if (on("planMode")) {
+    prefs.push(
+      "- **Plan mode for non-trivial work** — EnterPlanMode before implementing anything beyond a one-liner.",
+    );
+  }
+  if (on("delegation")) {
+    prefs.push(
+      "- **Delegate to domain experts** — use Task tool with appropriate subagent_type for complex single-domain work; orchestrator for multi-domain.",
+    );
+  }
+  if (on("taskTracking")) {
+    prefs.push(
+      "- **Track progress** — TaskCreate for 3+ step tasks, TaskUpdate as each completes.",
+    );
+  }
+  if (on("progressUpdates")) {
+    prefs.push(
+      "- **Short status updates** — brief progress notes while working.",
+    );
+  }
+  const always = mode === "full" || on("auditAll");
+
+  if (on("logicAudit")) {
+    prefs.push(
+      always
+        ? "- **Logic audit after every implementation** — suggest 🔍 Run logic audit as (Recommended) after every implementation."
+        : "- **Logic audit after implementation** — suggest 🔍 Run logic audit as (Recommended) after implementation.",
+    );
+  }
+  if (on("flowAudit")) {
+    prefs.push(
+      always
+        ? "- **Flow audit after every implementation** — suggest 🔄 Run flow audit after every implementation. Include a Verify flow integrity step in plans."
+        : "- **Flow audit after implementation** — when user-facing flows were touched (forms, navigation, auth, CRUD), suggest 🔄 Run flow audit after implementation. Include a Verify flow integrity step in plans.",
+    );
+  }
+  if (on("securityAudit")) {
+    prefs.push(
+      always
+        ? "- **Security audit after every implementation** — suggest 🔒 Run security audit after every implementation."
+        : "- **Security audit after implementation** — when auth, APIs, user input, file handling, or sensitive data were touched, suggest 🔒 Run security audit after implementation.",
+    );
+  }
+  if (on("performanceAudit")) {
+    prefs.push(
+      always
+        ? "- **Performance audit after every implementation** — suggest ⚡ Run performance audit after every implementation."
+        : "- **Performance audit after implementation** — when database queries, rendering, large data, or caching were touched, suggest ⚡ Run performance audit after implementation.",
+    );
+  }
+  if (on("accessibilityAudit")) {
+    prefs.push(
+      always
+        ? "- **Accessibility audit after every implementation** — suggest ♿ Run accessibility audit after every implementation."
+        : "- **Accessibility audit after implementation** — when UI components, forms, or interactive elements were changed, suggest ♿ Run accessibility audit after implementation.",
+    );
+  }
+  if (on("legalAudit")) {
+    prefs.push(
+      always
+        ? "- **Legal audit after every implementation** — suggest ⚖️ Run legal audit after every implementation."
+        : "- **Legal audit after implementation** — when data collection, privacy, user consent, or compliance-sensitive code was touched, suggest ⚖️ Run legal audit after implementation.",
+    );
+  }
+  if (on("strictMode")) {
+    prefs.push(
+      "- **Strict gates** — hide commit option until tests pass; auto-trigger code review at 5+ files changed; remove skip options.",
+    );
+  }
+  if (on("tddMode")) {
+    prefs.push(
+      "- **TDD phases** — RED (failing tests first) → GREEN (minimum code) → REFACTOR. Gate each phase.",
+    );
+  }
+
+  if (prefs.length === 0) return null;
+
+  const modeLabel =
+    mode === "custom"
+      ? `custom (${Object.entries(f)
+          .filter(([, v]) => v)
+          .map(([k]) => k)
+          .join(", ")})`
+      : mode;
+
+  const prefsBlock = [
+    `## User Preferences (agileflow ${modeLabel} mode)`,
+    "",
+    "Apply these preferences throughout this session across all skills and tasks:",
+    "",
+    ...prefs,
+    "",
+    "To change: run `agileflow setup`.",
+  ].join("\n");
+
+  const capsBlock = buildCapabilitiesBlock(cfg);
+
+  return capsBlock ? `${capsBlock}\n\n${prefsBlock}` : prefsBlock;
+}
+
+/**
+ * Build a learnings block by scanning the installed skills directory for
+ * skills that have `learns.enabled: true` and have at least one learning entry.
+ *
+ * @param {object} cfg - parsed agileflow.config.json
+ * @returns {string|null}
+ */
+function buildLearningsBlock(cfg) {
+  if (!_readLearnings || !_formatLearningsBlock) return null;
+  if (!cfg?.learnings?.enabled) return null;
+
+  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";
+  const absoluteSkillsDir = path.join(projectDir, skillsDir);
+
+  let skillNames;
+  try {
+    skillNames = fs.readdirSync(absoluteSkillsDir);
+  } catch {
+    return null; // skills dir not yet installed
+  }
+
+  const yaml = (() => {
+    try {
+      return require("js-yaml");
+    } catch {
+      return null;
+    }
+  })();
+  if (!yaml) return null;
+
+  const blocks = [];
+
+  for (const skillName of skillNames) {
+    const skillMdPath = path.join(absoluteSkillsDir, skillName, "SKILL.md");
+    let skillMdText;
+    try {
+      skillMdText = fs.readFileSync(skillMdPath, "utf8");
+    } catch {
+      continue;
+    }
+
+    // Parse frontmatter between first two `---` fences.
+    const fmMatch = skillMdText.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!fmMatch) continue;
+
+    let fm;
+    try {
+      fm = yaml.load(fmMatch[1]);
+    } catch {
+      continue;
+    }
+
+    if (!fm?.learns?.enabled) continue;
+
+    // readLearnings is async — run synchronously via the already-read skills dir.
+    // We resolve the learnings file path directly.
+    const learnFile = fm.learns.file || `_learnings/${skillName}.yaml`;
+    const safeParts = learnFile
+      .split("/")
+      .filter((p) => p && p !== ".." && p !== ".");
+    const learnFilePath = path.join(absoluteSkillsDir, skillName, ...safeParts);
+
+    let learningsData;
+    try {
+      const text = fs.readFileSync(learnFilePath, "utf8");
+      if (!text.trim()) continue;
+      const doc = yaml.load(text);
+      if (!doc || !Array.isArray(doc.entries) || doc.entries.length === 0)
+        continue;
+      learningsData = { entries: doc.entries, skill: skillName };
+    } catch {
+      continue; // file absent or invalid — skip silently
+    }
+
+    const block = _formatLearningsBlock(learningsData);
+    if (block) blocks.push(block);
+  }
+
+  return blocks.length > 0 ? blocks.join("\n\n") : null;
+}
+
+if (require.main === module) {
+  let cfg = {};
+  try {
+    cfg = JSON.parse(
+      fs.readFileSync(path.join(projectDir, "agileflow.config.json"), "utf8"),
+    );
+  } catch {
+    /* ignore */
+  }
+
+  const prefsBlock = buildPreferencesBlock();
+  const learnBlock = buildLearningsBlock(cfg);
+
+  const parts = [prefsBlock, learnBlock].filter(Boolean);
+  if (parts.length > 0) {
+    process.stdout.write(parts.join("\n\n") + "\n");
+  }
+  process.exit(0);
+}

package/content/plugins/core/hooks/session-welcome.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Core plugin hook: session-welcome.
+ *
+ * Phase 3 stub. The real welcome banner (similar to v3's
+ * agileflow-welcome.js but ~200 lines instead of 79KB) lands in
+ * Phase 4 alongside the rest of Core plugin content.
+ *
+ * Reads stdin (Claude Code's payload) and exits 0 — non-blocking.
+ */
+let stdin = '';
+process.stdin.on('data', (chunk) => {
+  stdin += chunk;
+});
+process.stdin.on('end', () => {
+  // eslint-disable-next-line no-console
+  console.log('agileflow: session welcome (Phase 3 stub)');
+  process.exit(0);
+});

package/content/plugins/core/plugin.yaml

@@ -0,0 +1,78 @@
+id: core
+name: Core
+description: Essential AgileFlow skills.
+version: 1.0.0
+enabledByDefault: true
+cannotDisable: true
+
+depends: []
+
+provides:
+  skills:
+    - id: agileflow-adr
+      dir: skills/agileflow-adr
+    - id: agileflow-epic-planner
+      dir: skills/agileflow-epic-planner
+    - id: agileflow-story-writer
+      dir: skills/agileflow-story-writer
+    - id: agileflow-status-updater
+      dir: skills/agileflow-status-updater
+    - id: agileflow-babysit-mentor
+      dir: skills/agileflow-babysit-mentor
+  agents:
+    - id: adr-writer
+      path: agents/adr-writer.md
+    - id: epic-planner
+      path: agents/epic-planner.md
+    - id: mentor
+      path: agents/mentor.md
+    - id: orchestrator
+      path: agents/orchestrator.md
+    - id: team-coordinator
+      path: agents/team-coordinator.md
+    - id: team-lead
+      path: agents/team-lead.md
+    - id: workspace-orchestrator
+      path: agents/workspace-orchestrator.md
+  hooks:
+    - id: context-loader
+      event: SessionStart
+      script: hooks/context-loader.js
+      timeout: 5000
+      skipOnError: true
+      behavior: loadContext
+    - id: preferences-injector
+      event: SessionStart
+      script: hooks/preferences-injector.js
+      timeout: 2000
+      skipOnError: true
+      runAfter: [context-loader]
+      behavior: babysitDefault
+    - id: damage-control-bash
+      event: PreToolUse
+      matcher: Bash
+      script: hooks/damage-control-bash.js
+      timeout: 3000
+      skipOnError: false
+      behavior: damageControlBash
+    - id: damage-control-edit
+      event: PreToolUse
+      matcher: Edit
+      script: hooks/damage-control-edit.js
+      timeout: 3000
+      skipOnError: false
+      behavior: damageControlEdit
+    - id: damage-control-write
+      event: PreToolUse
+      matcher: Write
+      script: hooks/damage-control-write.js
+      timeout: 3000
+      skipOnError: false
+      behavior: damageControlWrite
+    - id: post-compact-state
+      event: PostCompact
+      script: hooks/post-compact-state.js
+      timeout: 5000
+      skipOnError: true
+      behavior: preCompactState
+  templates: []

package/content/plugins/core/skills/agileflow-adr/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: agileflow-adr
+version: 2.0.0
+category: agileflow/core
+description: |
+  Use when the user is debating a technology / architecture / trade-off
+  decision (database choice, framework, API style, infra) or wants to
+  formalize one as an Architecture Decision Record. Writes the ADR to
+  docs/03-decisions/ in MADR format.
+triggers:
+  keywords:
+    - architecture decision
+    - architectural decision
+    - which should we use
+    - record this decision
+    - trade-off between
+    - which framework
+    - which database
+    - rest vs graphql
+    - sql vs nosql
+    - adr for
+  priority: 50
+  exclude:
+    - decision tree (algorithmic)
+    - decisive moment
+provides:
+  agents: []
+learns:
+  enabled: true
+  file: _learnings/adr.yaml
+  maxEntries: 50
+depends:
+  skills: []
+  plugins: [core]
+---
+
+# AgileFlow ADR Writer
+
+Captures architectural / technical decisions as formal Architecture
+Decision Records in `docs/03-decisions/` (MADR format). Decisions stay
+immutable once accepted; if context changes, supersede with a new ADR
+and link the chain.
+
+## When this skill activates
+
+- User is comparing options ("PostgreSQL vs MongoDB", "REST vs GraphQL")
+- User asks "which X should we use?" with at least two real candidates
+- User wants to record a decision they've already made
+- Discussion of trade-offs, drivers, or constraints
+- Should NOT activate on unrelated mentions of "decision" — `exclude`
+  keywords damp casual / algorithmic uses.
+
+## What this skill does
+
+1. Detect that a decision is being made (or asked about).
+2. Extract the four MADR elements: context/problem, decision drivers,
+   considered options, chosen option + justification.
+3. Ask clarifying questions if any are missing or ambiguous.
+4. Read `docs/03-decisions/` to find the next ADR number and any
+   related ADRs to cross-link.
+5. Show the proposed ADR and wait for explicit approval.
+6. Write `docs/03-decisions/ADR-####-<slug>.md` in MADR format.
+
+## Self-improving learnings
+
+`.agileflow/skills/_learnings/adr.yaml` records preferences:
+
+- Default `Status:` value (Proposed vs Accepted)
+- Whether to require all four MADR sections or allow brief mode
+- Preferred date format
+- Whether to include Deciders names by default
+
+## ADR format (MADR)
+
+```markdown
+# [ADR-0001] Title
+
+**Date**: YYYY-MM-DD
+**Status**: Proposed | Accepted | Deprecated | Superseded
+**Deciders**: Names of people involved
+**Tags**: architecture, database, api, …
+
+## Context and Problem Statement
+
+[Describe the context and problem. What are we trying to solve? Why now?]
+
+## Decision Drivers
+
+- [e.g., Performance requirements]
+- [e.g., Team expertise]
+- [e.g., Cost constraints]
+
+## Considered Options
+
+- [Option 1]
+- [Option 2]
+- [Option 3]
+
+## Decision Outcome
+
+**Chosen option**: [Option X]
+
+**Justification**: [Why this option best satisfies the drivers]
+
+### Positive Consequences
+
+- [Good outcome 1]
+- [Good outcome 2]
+
+### Negative Consequences
+
+- [Bad outcome 1] — Mitigation: [plan, if any]
+- [Bad outcome 2]
+
+## Pros and Cons of the Options
+
+### [Option 1]
+
+**Pros**: …
+**Cons**: …
+
+### [Option 2]
+
+**Pros**: …
+**Cons**: …
+
+## Links
+
+- [Related ADRs]
+- [Relevant documentation]
+- [External resources]
+```
+
+## Statuses
+
+- **Proposed** — Under discussion, not yet decided
+- **Accepted** — Decision made and ratified
+- **Deprecated** — No longer relevant; kept for history
+- **Superseded** — Replaced by a newer ADR (link forward to it)
+
+## When to write the ADR vs ask first
+
+Write it now (with `Status: Accepted`):
+
+- The user has already made a clear decision and wants to record it
+- The user explicitly asks for the ADR
+
+Ask first (then write with `Status: Proposed` or `Accepted`):
+
+- Multiple options are still in play
+- Drivers / constraints aren't clear yet
+- The chosen option's justification is one-line ("we like it more")
+
+## Quality checklist
+
+- [ ] Problem statement is concrete (not "improve performance")
+- [ ] At least 2 real options considered (single-option ADRs are a
+      smell — note that the alternative was "do nothing" or "status
+      quo")
+- [ ] Each option has explicit pros AND cons
+- [ ] Decision drivers explicitly stated
+- [ ] Chosen option's justification ties back to drivers
+- [ ] Negative consequences acknowledged with mitigations where possible
+- [ ] File path: `docs/03-decisions/ADR-####-<slug>.md` (4-digit pad)
+- [ ] User approved the diff before write
+
+## Integration
+
+- **agileflow-story-writer** — completed ADRs inform Technical Notes in stories; reference the ADR number in the story's context section
+- **agileflow-epic-planner** — major epics often spawn one or more ADRs at planning time; create the ADR before writing stories so implementation decisions are settled
+- **agileflow-status-updater** — flipping an ADR from Proposed to Accepted is a status mutation; route through status-updater to keep `status.json` accurate
+- **agileflow-council** — council sessions are the primary source of ADR content; after a council reaches a decision, create an ADR to record it formally
+- **agileflow-research** — research provides the factual foundation for ADRs (benchmarks, library comparisons, community precedent); always link or summarise the research in the ADR body
+- **agileflow-planning** — use planning's impact analysis output as the context section of an ADR when the decision involves scope or delivery trade-offs
+- **agileflow-delivery** — for breaking API changes or major dependency upgrades, create an ADR before the delivery cycle begins so the rationale is documented before merge
+
+## Notes
+
+- Capture decisions even if they seem small. Future you (or a new
+  hire) won't remember why you chose option B in three months.
+- Be honest about negative consequences — undocumented downsides are
+  the source of "why is this code like this?" frustration.
+- ADRs are **immutable** once accepted. To change a decision, create a
+  new ADR with `Status: Accepted`, set the old ADR to `Superseded`,
+  and link them.
+- Include the deciders' names. Accountability matters; so does
+  knowing who to ask.
+- Date the ADR — context erodes; the date is the timestamp on the
+  thinking, not just the file.
+
+## References
+
+Load these files when you need deeper context for the relevant task:
+
+| File                              | When to load                                                                                         |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `references/madr-format-guide.md` | Writing or reviewing an ADR — MADR format, required sections, common mistakes, numbering conventions |
+
+## Workflows
+
+Follow these step-by-step when the user initiates the matching action:
+
+| File                     | When to follow                                                                                                        |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `workflows/write-adr.md` | User wants to record a decision or is comparing options — gathers context, drafts ADR, gets confirmation, writes file |