feat: add ADR template and integration guide

Architecture Decision Record template for documenting the 'why'
behind architectural decisions, with flow-code integration guidance.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: z23cc

docs/adr-guide.md

@@ -0,0 +1,68 @@
+# ADR Integration Guide
+
+Architecture Decision Records capture the *why* behind significant technical decisions. This guide covers when to write them, where to store them, and how they integrate with flow-code.
+
+## When to Create an ADR
+
+Write an ADR when making a decision that would be expensive to reverse:
+
+- **Technology choices** — frameworks, libraries, major dependencies
+- **Architectural patterns** — data model design, API style, auth strategy
+- **Infrastructure decisions** — hosting, build tools, deployment approach
+- **Pattern changes** — moving from one approach to another (e.g., REST to GraphQL)
+
+Do NOT write ADRs for routine implementation choices, obvious decisions, or throwaway prototypes.
+
+## Where to Store ADRs
+
+Use `docs/decisions/` with sequential numbering:
+
+```
+docs/decisions/
+  ADR-001-use-libsql-for-storage.md
+  ADR-002-wave-checkpoint-execution-model.md
+  ADR-003-teams-file-locking-protocol.md
+```
+
+Use the template at `references/adr-template.md` as your starting point.
+
+## Referencing ADRs in Task Specs
+
+When a task implements or depends on an architectural decision, reference the ADR in the task spec:
+
+```bash
+flowctl task create --title "Implement file locking" \
+  --spec "Implements ADR-003. See docs/decisions/ADR-003-teams-file-locking-protocol.md"
+```
+
+In inline code, link to the ADR near the relevant implementation:
+
+```
+// Auth strategy per ADR-002. See docs/decisions/ADR-002-auth-strategy.md
+```
+
+## Integration with /flow-code:plan
+
+During planning, ADRs surface naturally at two points:
+
+1. **Plan creation** — When `/flow-code:plan` encounters an architectural decision, create the ADR as a task in the epic. The ADR task should complete before implementation tasks that depend on it.
+
+2. **Plan review** — `/flow-code:plan-review` should verify that significant architectural decisions have corresponding ADRs. Missing ADRs are a review finding.
+
+### Example: ADR as a Plan Task
+
+```
+Epic: fn-50-migrate-to-graphql
+  Task 1: Write ADR-005 documenting REST-to-GraphQL migration rationale
+  Task 2: Implement GraphQL schema (depends on Task 1)
+  Task 3: Migrate endpoints (depends on Task 2)
+```
+
+## ADR Lifecycle
+
+```
+PROPOSED  ->  ACCEPTED  ->  SUPERSEDED by ADR-XXX
+                         ->  DEPRECATED
+```
+
+Never delete old ADRs. When a decision changes, write a new ADR that supersedes the old one. The historical record is the whole point.

references/adr-template.md

@@ -0,0 +1,54 @@
+# ADR-NNN: [Short decision title]
+
+## Status
+
+<!-- One of: Proposed | Accepted | Superseded by ADR-XXX | Deprecated -->
+Proposed
+
+## Date
+
+<!-- YYYY-MM-DD when the decision was made or proposed -->
+YYYY-MM-DD
+
+## Context
+
+<!-- What is the problem or situation that requires a decision?
+     Include:
+     - The specific technical challenge or requirement
+     - Relevant constraints (performance, team size, timeline, budget)
+     - Any forcing functions that make this decision necessary now
+     Keep factual — save opinions for Decision and Alternatives. -->
+
+## Decision
+
+<!-- What is the decision and why?
+     State the chosen approach clearly, then explain the reasoning.
+     Link to any supporting evidence (benchmarks, spikes, docs). -->
+
+## Alternatives Considered
+
+<!-- List each alternative with pros, cons, and reason for rejection.
+     Format per alternative:
+
+### [Alternative name]
+- **Pros:** ...
+- **Cons:** ...
+- **Rejected because:** one-sentence reason
+-->
+
+## Consequences
+
+<!-- What are the positive and negative results of this decision?
+     Include:
+     - What becomes easier or possible
+     - What becomes harder or impossible
+     - New constraints or obligations introduced
+     - Skills or infrastructure the team now needs
+     - Follow-up actions required -->
+
+---
+
+<!-- Storage convention: docs/decisions/ADR-NNN-short-title.md
+     Lifecycle: PROPOSED -> ACCEPTED -> (SUPERSEDED or DEPRECATED)
+     Never delete old ADRs — they preserve historical context.
+     When superseding, write a new ADR that references the old one. -->