agileflow 3.4.3 → 4.0.0-alpha.2

package/README.md

@@ -1,129 +1,37 @@
-<p align="center">
-  <img src="assets/banner.png" alt="AgileFlow" />
-</p>
+# AgileFlow v4 (alpha)
 
-[![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
-[![Commands](https://img.shields.io/badge/commands-142-blue)](https://docs.agileflow.projectquestorg.com/docs/commands)
-[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-131-orange)](https://docs.agileflow.projectquestorg.com/docs/agents)
-[![Skills](https://img.shields.io/badge/skills-dynamic-purple)](https://docs.agileflow.projectquestorg.com/docs/features/skills)
+> **Status:** pre-release skeleton. Not for production use. See `CHANGELOG.md` and plan at `/home/bk/.claude/plans/fizzy-stirring-kahan.md`.
 
-**AI-driven agile development for Claude Code, Cursor, Windsurf, OpenAI Codex, and more.** Combining Scrum, Kanban, ADRs, and docs-as-code principles into one framework-agnostic system.
+AgileFlow v4 is a clean-break rewrite of the `agileflow` npm package. It replaces v3's 94-command / 149-agent / everything-enabled-by-default surface with a skills-first architecture and opt-in plugin categories.
 
----
+## Why v4
 
-## Quick Start
+- **Skills-first** — the primary interaction surface is skills (auto-discovered by Claude Code), with slash commands as optional thin wrappers.
+- **Opt-in plugins** — only the `core` plugin (Epic, Story, Status, Babysit) installs by default; Ads / SEO / Audit / Council / Mobile / Compliance are user-activated.
+- **Hook meta-orchestrator** — 6 Claude Code hook entry points dispatch an internal chain with `runAfter` / `skipOnError` / per-hook `timeout`, eliminating v3's cascading SessionStart failures.
+- **Unified config** — one user-facing `agileflow.config.json` at project root replaces the scattered `.agileflow/config.yaml` + `.claude/settings.json` + `manifest.yaml` surface of v3.
 
-```bash
-npx agileflow@latest setup
-```
-
-The `npx` command always fetches the latest version.
-
-**Updates:** `npx agileflow@latest update`
+## Install (alpha)
 
 ```bash
-/agileflow:help              # View all commands
-/agileflow:babysit           # Interactive mentor for implementation
-/agileflow:configure         # Configure hooks, status line, etc.
+npm i agileflow@alpha
+npx agileflow setup
 ```
 
-### Supported IDEs
-
-| IDE | Status | Config Location |
-|-----|--------|-----------------|
-| Claude Code | Supported | `.claude/commands/agileflow/` |
-| Cursor | Supported | `.cursor/commands/agileflow/` |
-| Windsurf | Supported | `.windsurf/workflows/agileflow/` |
-| OpenAI Codex | Supported | `.codex/skills/` and `~/.codex/prompts/` |
-
----
-
-## Why AgileFlow?
-
-Traditional project management tools create friction between planning and execution. AgileFlow eliminates this gap by embedding project management directly into your AI-assisted coding workflow.
-
-- **No context switching** - Manage epics, stories, and status without leaving your terminal
-- **AI-native workflows** - Purpose-built for Claude Code's capabilities
-- **Docs-as-code** - All project artifacts live in your repository as plain text
-- **Intelligent agents** - 55 specialized AI agents for different domains
-- **Framework-agnostic** - Works with any tech stack
-
----
-
-## Core Components
-
-| Component | Count | Description |
-|-----------|-------|-------------|
-| [Commands](https://docs.agileflow.projectquestorg.com/docs/commands) | 142 | Slash commands for agile workflows |
-| [Agents/Experts](https://docs.agileflow.projectquestorg.com/docs/agents) | 131 | Specialized agents with self-improving knowledge bases |
-| [Skills](https://docs.agileflow.projectquestorg.com/docs/features/skills) | Dynamic | Browse and install from skills.sh marketplace via `/agileflow:skill:recommend` |
-
----
-
-## Features
-
-| Feature | Description | Docs |
-|---------|-------------|------|
-| Agent Expertise | Self-improving agents that maintain domain knowledge | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/agent-expertise-system) |
-| Agent Teams | Multi-domain expert coordination with quality gates | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/agent-teams) |
-| Skills System | Browse and install skills from the skills.sh marketplace | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/skills) |
-| Parallel Sessions | Isolated workspaces with boundary protection | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/parallel-sessions) |
-| Loop Mode | Autonomous story execution until epic completion | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/loop-mode) |
-| AI Council | Three-perspective strategic decision analysis | [Learn more](https://docs.agileflow.projectquestorg.com/docs/commands/council) |
-| Logic Audit | Multi-agent logic bug detection with consensus voting | [Learn more](https://docs.agileflow.projectquestorg.com/docs/commands/logic-audit) |
-| Damage Control | Block destructive commands with PreToolUse hooks | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/damage-control) |
-| Smart Detection | Contextual feature recommendations with 42 detectors | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/smart-detect) |
-| Visual Mode | Screenshot verification for UI development | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/visual-mode) |
-| Context Preservation | Preserve state during automatic context compaction | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/compact-context) |
-| Research Pipeline | Structured research workflow with synthesis | [Learn more](https://docs.agileflow.projectquestorg.com/docs/commands/research) |
-| Automations | Scheduled recurring tasks without a daemon | [Learn more](https://docs.agileflow.projectquestorg.com/docs/commands/automate) |
-| Tmux Integration | Multi-window terminal sessions with keybindings and status bar | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/tmux-keybindings) |
-| IDE Integrations | Claude Code, Cursor, Windsurf, OpenAI Codex support | [Learn more](https://docs.agileflow.projectquestorg.com/docs/features/ide-integrations) |
+## Phase status
 
-See the [full features overview](https://docs.agileflow.projectquestorg.com/docs/features) for details.
+| Phase | Scope | Status |
+|-------|-------|--------|
+| 1 — Skeleton + Config | `package.json`, config loader, CLI entry, stubs | **in progress** |
+| 2 — Installer + Plugin Loader | sync engine port, plugin registry | pending |
+| 3 — Hook Orchestrator | manifest-driven chain dispatcher | pending |
+| 4 — Core Plugin Content | Epic, Story, Status, Babysit | pending |
+| 5 — Skill Validator + CI + alpha.1 publish | CI, validator, personalization | pending |
 
----
+## Relationship to v3
 
-## Examples
-
-```bash
-# Create an epic
-/agileflow:epic EPIC=EP-0001 TITLE="User Authentication" OWNER=AG-API GOAL="Secure login"
-
-# Work on a story
-/agileflow:babysit
-
-# Multi-expert analysis
-/agileflow:multi-expert Is this authentication implementation secure?
-
-# AI Council for strategic decisions
-/agileflow:council Should we use microservices or a monolith?
-
-# Parallel sessions
-/agileflow:session:new
-```
-
----
-
-## Documentation
-
-Full documentation at **[docs.agileflow.projectquestorg.com](https://docs.agileflow.projectquestorg.com)**.
-
-| Section | Link |
-|---------|------|
-| Getting Started | [docs.agileflow.projectquestorg.com/docs/getting-started](https://docs.agileflow.projectquestorg.com/docs/getting-started) |
-| Installation | [docs.agileflow.projectquestorg.com/docs/installation](https://docs.agileflow.projectquestorg.com/docs/installation) |
-| Commands | [docs.agileflow.projectquestorg.com/docs/commands](https://docs.agileflow.projectquestorg.com/docs/commands) |
-| Agents | [docs.agileflow.projectquestorg.com/docs/agents](https://docs.agileflow.projectquestorg.com/docs/agents) |
-| Features | [docs.agileflow.projectquestorg.com/docs/features](https://docs.agileflow.projectquestorg.com/docs/features) |
-
----
+v3 lives at `packages/cli/` (temporarily renamed to `agileflow-v3-legacy` on the `v4` branch to avoid workspace name collision). v3 patches happen on `main` only. When v4 reaches core parity the `v4` branch merges to `main` and `packages/cli/` is removed.
 
 ## License
 
-MIT
-
-## Support
-
-- [Documentation](https://docs.agileflow.projectquestorg.com) - Full docs site
-- [GitHub Issues](https://github.com/projectquestorg/AgileFlow/issues) - Bug reports and feature requests
+MIT — see `LICENSE`.

package/bin/agileflow.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * AgileFlow v4 CLI entry.
+ *
+ * Thin shebang wrapper — all logic lives in src/cli/index.js so the
+ * dispatcher is unit-testable without spawning a process.
+ */
+const { run } = require('../src/cli/index.js');
+
+run(process.argv).catch((err) => {
+  // Fail-loud at the top level; commander itself handles structured exits.
+  // eslint-disable-next-line no-console
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exit(1);
+});

package/bin/hooks/pre-bash.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook dispatcher: PreToolUse for the Bash tool.
+ *
+ * Registered in `.claude/settings.json` as a `PreToolUse` hook with
+ * `matcher: "Bash"`. Claude Code only invokes this dispatcher when a
+ * Bash tool call is about to fire. We pass `matcher: "Bash"` through to
+ * the orchestrator so manifest hooks with their own matcher field can
+ * filter further (e.g. an MCP-tool-only hook will not run here).
+ */
+const path = require('path');
+const { runEvent } = require('../../src/runtime/hooks/orchestrator.js');
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const agileflowDir = path.join(projectDir, '.agileflow');
+
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const stdin = Buffer.concat(chunks);
+
+  const result = await runEvent({
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    agileflowDir,
+    stdin,
+  });
+  process.exit(result.exitCode);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('PreToolUse:Bash dispatcher error:', err && err.stack ? err.stack : err);
+  process.exit(0);
+});

package/bin/hooks/pre-compact.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook dispatcher: PreCompact.
+ *
+ * Runs immediately before context compaction. Hooks here preserve
+ * critical state (open-task lists, session metadata) so it survives the
+ * compaction summary. Always fails open — losing a hook should never
+ * block compaction.
+ */
+const path = require('path');
+const { runEvent } = require('../../src/runtime/hooks/orchestrator.js');
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const agileflowDir = path.join(projectDir, '.agileflow');
+
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const stdin = Buffer.concat(chunks);
+
+  const result = await runEvent({
+    event: 'PreCompact',
+    agileflowDir,
+    stdin,
+  });
+  // Always exit 0 — compaction must not be blocked even on hook chain failure.
+  process.exit(result.exitCode === 0 ? 0 : 0);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('PreCompact dispatcher error:', err && err.stack ? err.stack : err);
+  process.exit(0);
+});

package/bin/hooks/pre-edit.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook dispatcher: PreToolUse for the Edit tool.
+ *
+ * Registered in `.claude/settings.json` as a `PreToolUse` hook with
+ * `matcher: "Edit"`. Mirror of pre-bash.js for the Edit tool.
+ */
+const path = require('path');
+const { runEvent } = require('../../src/runtime/hooks/orchestrator.js');
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const agileflowDir = path.join(projectDir, '.agileflow');
+
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const stdin = Buffer.concat(chunks);
+
+  const result = await runEvent({
+    event: 'PreToolUse',
+    matcher: 'Edit',
+    agileflowDir,
+    stdin,
+  });
+  process.exit(result.exitCode);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('PreToolUse:Edit dispatcher error:', err && err.stack ? err.stack : err);
+  process.exit(0);
+});

package/bin/hooks/pre-write.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook dispatcher: PreToolUse for the Write tool.
+ *
+ * Registered in `.claude/settings.json` as a `PreToolUse` hook with
+ * `matcher: "Write"`. Mirror of pre-bash.js for the Write tool.
+ */
+const path = require('path');
+const { runEvent } = require('../../src/runtime/hooks/orchestrator.js');
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const agileflowDir = path.join(projectDir, '.agileflow');
+
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const stdin = Buffer.concat(chunks);
+
+  const result = await runEvent({
+    event: 'PreToolUse',
+    matcher: 'Write',
+    agileflowDir,
+    stdin,
+  });
+  process.exit(result.exitCode);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('PreToolUse:Write dispatcher error:', err && err.stack ? err.stack : err);
+  process.exit(0);
+});

package/bin/hooks/session-start.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook dispatcher: SessionStart.
+ *
+ * Registered once in `.claude/settings.json` and invoked by Claude Code
+ * at session boot. Reads `.agileflow/hook-manifest.yaml`, runs the
+ * SessionStart chain via the orchestrator, and exits with the chain's
+ * resolved exit code.
+ *
+ * Always fails open unless a hook with `skipOnError: false` failed: the
+ * orchestrator returns 0 even when individual hooks errored, as long as
+ * they had `skipOnError: true`. This is the v3 cascade-failure fix.
+ */
+const path = require('path');
+const { runEvent } = require('../../src/runtime/hooks/orchestrator.js');
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const agileflowDir = path.join(projectDir, '.agileflow');
+
+  // Read stdin (Claude Code may pipe a JSON payload).
+  /** @type {Buffer[]} */
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const stdin = Buffer.concat(chunks);
+
+  const result = await runEvent({
+    event: 'SessionStart',
+    agileflowDir,
+    stdin,
+  });
+
+  process.exit(result.exitCode);
+}
+
+main().catch((err) => {
+  // Hook dispatcher must NEVER throw uncaught — that would block
+  // session start. Log to stderr and fail open.
+  // eslint-disable-next-line no-console
+  console.error('SessionStart dispatcher error:', err && err.stack ? err.stack : err);
+  process.exit(0);
+});

package/bin/hooks/stop.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook dispatcher: Stop.
+ *
+ * Runs when the agent stops. Hooks here perform cleanup, capture
+ * end-of-session metrics, or trigger self-improvement loops. Like
+ * PreCompact, this dispatcher always exits 0 — a Stop hook failure
+ * should not be treated as a blocking event.
+ */
+const path = require('path');
+const { runEvent } = require('../../src/runtime/hooks/orchestrator.js');
+
+async function main() {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const agileflowDir = path.join(projectDir, '.agileflow');
+
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  const stdin = Buffer.concat(chunks);
+
+  await runEvent({
+    event: 'Stop',
+    agileflowDir,
+    stdin,
+  });
+  // Stop is non-blocking — always exit 0 regardless of chain outcome.
+  process.exit(0);
+}
+
+main().catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error('Stop dispatcher error:', err && err.stack ? err.stack : err);
+  process.exit(0);
+});

package/content/plugins/ads/plugin.yaml

@@ -0,0 +1,14 @@
+id: ads
+name: Ads
+description: Meta, Google, TikTok, LinkedIn, YouTube, Microsoft ad audits + /ads:* suite.
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  commands: []
+  skills: []
+  agents: []
+  hooks: []
+  templates: []

package/content/plugins/audit/plugin.yaml

@@ -0,0 +1,14 @@
+id: audit
+name: Code Audit
+description: Multi-agent audits for quality, security, logic, perf, tests, a11y, arch, API, flows, completeness.
+version: 1.0.0
+enabledByDefault: false
+
+depends: []
+
+provides:
+  commands: []
+  skills: []
+  agents: []
+  hooks: []
+  templates: []

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

@@ -0,0 +1,55 @@
+#!/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/content/plugins/core/hooks/context-loader.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+/**
+ * Core hook: context-loader (SessionStart).
+ *
+ * Prints a compact project snapshot to stdout so Claude Code includes
+ * it in the session prompt. Lean v4 implementation (~200 lines, vs.
+ * v3's 79KB welcome banner). Output is pure text — no ANSI colors.
+ *
+ * Sections (ordered by load-bearing-ness for Claude):
+ *   1. Project header (cwd, agileflow version, ide)
+ *   2. Active story / epic (from docs/09-agents/status.json if present)
+ *   3. Ready stories (top 5 by priority)
+ *   4. Git state (branch, dirty files)
+ *   5. Recent commits (last 5)
+ *   6. Hook health (last 3 entries from hook-execution.jsonl)
+ *
+ * Fail-open: any read error becomes a one-line "(unavailable)" note.
+ * The hook always exits 0; orchestrator-side `skipOnError: true` is
+ * defensive belt-and-suspenders.
+ */
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const agileflowDir = path.join(projectDir, ".agileflow");
+
+/** Read JSON file, returning null on any error. */
+function readJSON(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Run a git command; return its stdout trimmed, or null on error. */
+function git(args) {
+  try {
+    return execSync(`git ${args}`, {
+      cwd: projectDir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Tail the last N JSONL entries from a file. */
+function tailJSONL(p, n) {
+  try {
+    const lines = fs.readFileSync(p, "utf8").trim().split("\n");
+    return lines
+      .slice(-n)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+const lines = [];
+const out = (s = "") => lines.push(s);
+
+out("## AgileFlow project context");
+out("");
+
+// 1. Project header
+const config = readJSON(path.join(projectDir, "agileflow.config.json")) || {};
+const enabledPlugins = Object.entries(config.plugins || {})
+  .filter(([, v]) => v && v.enabled)
+  .map(([id]) => id);
+out(`cwd:      ${projectDir}`);
+out(`ide:      ${(config.ide && config.ide.primary) || "claude-code"}`);
+out(`plugins:  ${enabledPlugins.join(", ") || "(none)"}`);
+out(
+  `tone:     ${(config.personalization && config.personalization.tone) || "concise"}`,
+);
+out("");
+
+// 2. Active story / epic
+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 }));
+  if (inProgress.length) {
+    out("## In progress");
+    for (const s of inProgress) {
+      out(
+        `  ${s.id} ${s.title || ""} (owner: ${s.owner || "?"}, est: ${s.estimate || "?"})`,
+      );
+    }
+    out("");
+  }
+
+  // 3. Ready stories — top 5 by priority then estimate
+  const ready = Object.entries(status.stories)
+    .filter(([, s]) => s && s.status === "ready")
+    .map(([id, s]) => ({ id, ...s }))
+    .sort((a, b) => {
+      const pa = parseInt(String(a.priority || "P9").replace("P", ""), 10);
+      const pb = parseInt(String(b.priority || "P9").replace("P", ""), 10);
+      if (pa !== pb) return pa - pb;
+      return (a.estimate || 99) - (b.estimate || 99);
+    })
+    .slice(0, 5);
+  if (ready.length) {
+    out("## Ready (top 5)");
+    for (const s of ready) {
+      out(
+        `  ${s.id} [${s.priority || "P?"} · ${s.estimate || "?"}pts] ${s.title || ""}`,
+      );
+    }
+    out("");
+  }
+}
+
+// 4. Git state
+const branch = git("rev-parse --abbrev-ref HEAD");
+const dirty = git("status --short");
+if (branch) {
+  out("## Git");
+  out(`  branch:   ${branch}`);
+  if (dirty) {
+    const lines2 = dirty.split("\n").slice(0, 10);
+    out(
+      `  changes:  ${lines2.length} file(s)${dirty.split("\n").length > 10 ? " (showing first 10)" : ""}`,
+    );
+    for (const l of lines2) out(`    ${l}`);
+  } else {
+    out("  changes:  (clean)");
+  }
+  out("");
+}
+
+// 5. Recent commits
+const log = git("log --oneline -5");
+if (log) {
+  out("## Recent commits");
+  for (const l of log.split("\n")) out(`  ${l}`);
+  out("");
+}
+
+// 6. Hook health
+const hookLog = tailJSONL(
+  path.join(agileflowDir, "logs/hook-execution.jsonl"),
+  3,
+);
+if (hookLog.length) {
+  out("## Recent hook runs");
+  for (const e of hookLog) {
+    const status = e.status === "ok" ? "OK" : e.status.toUpperCase();
+    out(
+      `  ${e.timestamp || "?"} [${status}] ${e.event}/${e.hookId} (${e.durationMs || 0}ms)`,
+    );
+  }
+  out("");
+}
+
+process.stdout.write(lines.join("\n") + "\n");
+process.exit(0);