agileflow 3.4.3 → 4.0.0-alpha.1

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/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,34 @@
+# Core plugin — essential AgileFlow workflow.
+# Always enabled; cannot be disabled.
+# Phase 4: skills land here. ADR / sprint-planner / retro etc. live in
+# their own opt-in plugins later.
+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:
+    - id: session-welcome
+      event: SessionStart
+      script: hooks/session-welcome.js
+      timeout: 5000
+      skipOnError: true
+  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.