agileflow 3.4.3 → 4.0.0-alpha.2

package/content/plugins/core/hooks/damage-control-bash.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Core hook: damage-control-bash (PreToolUse, matcher: Bash).
+ *
+ * Reads damage-control-patterns.yaml and rejects Bash commands that
+ * match an `error`-severity pattern of kind `bash`. `warn`-severity
+ * patterns log but do not block.
+ *
+ * Stdin payload (Claude Code-shaped):
+ *   { tool_name: "Bash", tool_input: { command: "...", description: "..." } }
+ *
+ * Exit codes:
+ *   0  allow (default)
+ *   2  block (Claude Code surfaces stderr to the user)
+ */
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const patternsPath = path.join(
+  projectDir,
+  ".agileflow/plugins/core/hooks/damage-control-patterns.yaml",
+);
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0); // No payload, nothing to gate.
+  }
+  const command =
+    payload &&
+    payload.tool_input &&
+    typeof payload.tool_input.command === "string"
+      ? payload.tool_input.command
+      : "";
+  if (!command) process.exit(0);
+
+  let patterns = [];
+  try {
+    const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
+    patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
+  } catch {
+    process.exit(0); // No patterns file, fail open.
+  }
+
+  for (const p of patterns) {
+    if (p.kind !== "bash") continue;
+    let re;
+    try {
+      re = new RegExp(p.regex, "i");
+    } catch {
+      continue;
+    }
+    if (re.test(command)) {
+      if (p.severity === "error") {
+        process.stderr.write(
+          `agileflow damage-control: BLOCKED — ${p.reason}\n  pattern: ${p.regex}\n  command: ${command.slice(0, 200)}\n`,
+        );
+        process.exit(2);
+      }
+      // severity: warn — log, do not block
+      process.stderr.write(`agileflow damage-control: WARN — ${p.reason}\n`);
+    }
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/content/plugins/core/hooks/damage-control-edit.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Core hook: damage-control-edit (PreToolUse, matcher: Edit).
+ *
+ * Reads damage-control-patterns.yaml and rejects Edit operations whose
+ * file_path matches an `error`-severity pattern of kind `edit`.
+ *
+ * Stdin payload:
+ *   { tool_name: "Edit", tool_input: { file_path: "...", old_string, new_string } }
+ *
+ * Exit codes: 0 allow, 2 block.
+ */
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const patternsPath = path.join(
+  projectDir,
+  ".agileflow/plugins/core/hooks/damage-control-patterns.yaml",
+);
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  const filePath =
+    payload &&
+    payload.tool_input &&
+    typeof payload.tool_input.file_path === "string"
+      ? payload.tool_input.file_path
+      : "";
+  if (!filePath) process.exit(0);
+
+  let patterns = [];
+  try {
+    const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
+    patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
+  } catch {
+    process.exit(0);
+  }
+
+  for (const p of patterns) {
+    if (p.kind !== "edit") continue;
+    let re;
+    try {
+      re = new RegExp(p.regex, "i");
+    } catch {
+      continue;
+    }
+    if (re.test(filePath)) {
+      if (p.severity === "error") {
+        process.stderr.write(
+          `agileflow damage-control: BLOCKED edit — ${p.reason}\n  path: ${filePath}\n`,
+        );
+        process.exit(2);
+      }
+      process.stderr.write(
+        `agileflow damage-control: WARN — ${p.reason} (path: ${filePath})\n`,
+      );
+    }
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/content/plugins/core/hooks/damage-control-patterns.yaml

@@ -0,0 +1,100 @@
+# Damage control pattern library.
+#
+# The pre-Bash / pre-Edit / pre-Write hooks load this file and reject
+# tool invocations whose payload matches any pattern below. Each entry
+# explains WHY it's blocked so the error message can cite the rule.
+#
+# Pattern syntax:
+#   - `regex`: JS RegExp source (used with `new RegExp(pattern, 'i')`)
+#   - `kind`:  one of bash | edit | write — which hook applies the rule
+#   - `severity`: error (block, exit 2) | warn (allow but log warning)
+#   - `reason`: human-readable rationale shown in the block message
+#
+# Adding a pattern: keep it surgical. False positives are worse than
+# missed catches because they train users to bypass the guard.
+
+patterns:
+  # --- Catastrophic filesystem operations ---
+  - regex: 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s+(/|~|\$HOME)\b'
+    kind: bash
+    severity: error
+    reason: rm -rf on / or $HOME is almost certainly a mistake — refuse outright
+
+  - regex: 'rm\s+-[a-zA-Z]*[rfRF][a-zA-Z]*\s+/\*'
+    kind: bash
+    severity: error
+    reason: rm -rf /* deletes the entire filesystem
+
+  - regex: '\bdd\s+if=.*\s+of=/dev/(sd|nvme|hd)'
+    kind: bash
+    severity: error
+    reason: dd to a raw block device wipes the disk
+
+  - regex: '\bmkfs\.\w+\s+/dev/'
+    kind: bash
+    severity: error
+    reason: mkfs on a device formats it — destroys all data
+
+  - regex: '>\s*/dev/(sd|nvme|hd)\w+'
+    kind: bash
+    severity: error
+    reason: writing directly to a block device corrupts the disk
+
+  - regex: ':\(\)\{\s*:\|:\&\s*\};:'
+    kind: bash
+    severity: error
+    reason: classic fork bomb
+
+  # --- Risky git operations ---
+  - regex: 'git\s+push\s+.*--force(\s|$)'
+    kind: bash
+    severity: warn
+    reason: force push can rewrite shared history — confirm intent
+
+  - regex: 'git\s+(reset|checkout)\s+.*--hard'
+    kind: bash
+    severity: warn
+    reason: --hard discards uncommitted work — confirm before running
+
+  - regex: 'git\s+clean\s+-[a-zA-Z]*[fdx]+'
+    kind: bash
+    severity: warn
+    reason: git clean -fdx removes untracked files including .gitignored — confirm
+
+  # --- Edit / Write path scope ---
+  # The edit/write hooks evaluate the file_path payload, not the command.
+  - regex: "^/etc/(passwd|shadow|sudoers)$"
+    kind: edit
+    severity: error
+    reason: editing system credential files would compromise the host
+
+  - regex: "^/etc/(passwd|shadow|sudoers)$"
+    kind: write
+    severity: error
+    reason: writing to system credential files would compromise the host
+
+  - regex: '\.ssh/(id_[a-z]+|authorized_keys|known_hosts)$'
+    kind: edit
+    severity: warn
+    reason: editing SSH credentials — confirm this is intentional
+
+  - regex: '\.ssh/(id_[a-z]+|authorized_keys|known_hosts)$'
+    kind: write
+    severity: warn
+    reason: writing to SSH credentials — confirm this is intentional
+
+  - regex: '\.env(\.|$)'
+    kind: write
+    severity: warn
+    reason: writing to a .env file — confirm it does not commit secrets
+
+  # --- npm / pnpm risk ---
+  - regex: 'npm\s+publish(\s|$)'
+    kind: bash
+    severity: warn
+    reason: npm publish ships to a public registry — confirm version + auth
+
+  - regex: 'rm\s+-rf?\s+(node_modules|\.git)\b'
+    kind: bash
+    severity: warn
+    reason: nuking node_modules / .git is recoverable but slow — confirm

package/content/plugins/core/hooks/damage-control-write.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/**
+ * Core hook: damage-control-write (PreToolUse, matcher: Write).
+ *
+ * Mirror of damage-control-edit.js for the Write tool. Same patterns
+ * file (kind: write entries). Blocks writing system credential files,
+ * warns on writes to .ssh/ and .env*.
+ */
+const fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const patternsPath = path.join(
+  projectDir,
+  ".agileflow/plugins/core/hooks/damage-control-patterns.yaml",
+);
+
+async function readStdin() {
+  const chunks = [];
+  for await (const c of process.stdin) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    process.exit(0);
+  }
+  const filePath =
+    payload &&
+    payload.tool_input &&
+    typeof payload.tool_input.file_path === "string"
+      ? payload.tool_input.file_path
+      : "";
+  if (!filePath) process.exit(0);
+
+  let patterns = [];
+  try {
+    const parsed = yaml.load(fs.readFileSync(patternsPath, "utf8"));
+    patterns = Array.isArray(parsed && parsed.patterns) ? parsed.patterns : [];
+  } catch {
+    process.exit(0);
+  }
+
+  for (const p of patterns) {
+    if (p.kind !== "write") continue;
+    let re;
+    try {
+      re = new RegExp(p.regex, "i");
+    } catch {
+      continue;
+    }
+    if (re.test(filePath)) {
+      if (p.severity === "error") {
+        process.stderr.write(
+          `agileflow damage-control: BLOCKED write — ${p.reason}\n  path: ${filePath}\n`,
+        );
+        process.exit(2);
+      }
+      process.stderr.write(
+        `agileflow damage-control: WARN — ${p.reason} (path: ${filePath})\n`,
+      );
+    }
+  }
+  process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/content/plugins/core/hooks/pre-compact-state.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Core hook: pre-compact-state (PreCompact).
+ *
+ * Captures the state Claude needs to know AFTER the compaction summary
+ * replaces most of the conversation: the active story, the active
+ * command, recent decisions, and the dirty git state. Without this,
+ * compaction often loses thread on multi-turn implementation work.
+ *
+ * Output is plain markdown printed to stdout — Claude Code includes
+ * the hook's stdout in the prompt context after compaction.
+ *
+ * Exits 0 always (must not block compaction).
+ */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+function readJSON(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function git(args) {
+  try {
+    return execSync(`git ${args}`, {
+      cwd: projectDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+const out = [];
+out.push("## Pre-compaction state preservation");
+out.push("");
+
+const status = readJSON(path.join(projectDir, "docs/09-agents/status.json"));
+if (status && status.stories) {
+  const inProgress = Object.entries(status.stories)
+    .filter(([, s]) => s && s.status === "in_progress")
+    .map(([id, s]) => `${id} ${s.title || ""}`);
+  if (inProgress.length) {
+    out.push("Active stories:");
+    for (const s of inProgress) out.push(`  - ${s}`);
+    out.push("");
+  }
+}
+
+// Active command from session-state if it exists
+const sessionState = readJSON(
+  path.join(projectDir, "docs/09-agents/session-state.json"),
+);
+if (sessionState && sessionState.active_command) {
+  out.push(
+    `Active command: ${sessionState.active_command.name || "(unknown)"}`,
+  );
+  out.push("");
+}
+
+const branch = git("rev-parse --abbrev-ref HEAD");
+const dirty = git("status --short");
+if (branch || dirty) {
+  out.push("Git:");
+  if (branch) out.push(`  branch: ${branch}`);
+  if (dirty) {
+    const lines = dirty.split("\n").slice(0, 8);
+    out.push(`  dirty:  ${lines.length} file(s)`);
+    for (const l of lines) out.push(`    ${l}`);
+  }
+  out.push("");
+}
+
+const log = git("log --oneline -3");
+if (log) {
+  out.push("Recent commits:");
+  for (const l of log.split("\n")) out.push(`  ${l}`);
+  out.push("");
+}
+
+out.push("After compaction, resume from this state.");
+process.stdout.write(out.join("\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,82 @@
+# Core plugin — essential AgileFlow workflow.
+# Always enabled; cannot be disabled.
+#
+# Hooks declared here are CANDIDATES — the install-time aggregator
+# filters them by the user's `behaviors:` map in agileflow.config.json.
+# A hook ID that maps to a disabled behavior never enters the
+# generated hook-manifest.yaml. See apps/cli/src/runtime/hooks/aggregator.js.
+id: core
+name: Core
+description: Epic, Story, Status, Babysit — essential agile workflow.
+version: 1.0.0
+enabledByDefault: true
+cannotDisable: true
+
+depends: []
+
+provides:
+  commands: []
+  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: []
+  hooks:
+    # SessionStart — context loading + (optional) mentor injection.
+    - id: context-loader
+      event: SessionStart
+      script: hooks/context-loader.js
+      timeout: 5000
+      skipOnError: true
+      behavior: loadContext
+
+    - id: babysit-mentor-injector
+      event: SessionStart
+      script: hooks/babysit-mentor-injector.js
+      timeout: 2000
+      skipOnError: true
+      runAfter: [context-loader]
+      behavior: babysitDefault
+
+    # PreToolUse — damage control. skipOnError false: errors should
+    # block dangerous operations rather than be tolerated.
+    - id: damage-control-bash
+      event: PreToolUse
+      matcher: Bash
+      script: hooks/damage-control-bash.js
+      timeout: 3000
+      skipOnError: false
+      behavior: damageControl
+
+    - id: damage-control-edit
+      event: PreToolUse
+      matcher: Edit
+      script: hooks/damage-control-edit.js
+      timeout: 3000
+      skipOnError: false
+      behavior: damageControl
+
+    - id: damage-control-write
+      event: PreToolUse
+      matcher: Write
+      script: hooks/damage-control-write.js
+      timeout: 3000
+      skipOnError: false
+      behavior: damageControl
+
+    # PreCompact — preserve state across compaction.
+    - id: pre-compact-state
+      event: PreCompact
+      script: hooks/pre-compact-state.js
+      timeout: 5000
+      skipOnError: true
+      behavior: preCompactState
+
+  templates: []

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

@@ -0,0 +1,179 @@
+---
+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]
+---
+
+<!-- {{PERSONALIZATION_BLOCK}} -->
+
+# 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
+- **agileflow-epic-planner** — major epics often spawn one or more
+  ADRs at planning time
+- **agileflow-status-updater** — flipping an ADR from Proposed to
+  Accepted is a status mutation through that skill
+
+## 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.