session-orchestrator 3.16.0

package/skills/docs-orchestrator/SKILL.md

@@ -0,0 +1,362 @@
+---
+name: docs-orchestrator
+user-invocable: false
+tags: [docs, orchestration, audiences]
+model: sonnet
+model-preference: sonnet
+description: >
+  Use this skill when orchestrating documentation generation and updates within a
+  session. Maps session scope to audience-specific docs tasks (User / Dev /
+  Vault), dispatches the docs-writer agent with source-grounded prompts, and
+  reports coverage gaps to session-end. Gated on
+  `docs-orchestrator.enabled: true` in Session Config. Zero overhead when
+  disabled.
+---
+
+# Docs Orchestrator Skill
+
+> Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md).
+
+docs-orchestrator coordinates the full documentation lifecycle inside a session: it
+detects which audiences (User, Dev, Vault) are touched by the agreed scope, generates
+audience-specific task definitions, threads them into the session-plan pipeline, and
+verifies that docs tasks produced diffs once waves complete. The skill is opt-in and
+default-off — when `docs-orchestrator.enabled: false`, all three hook points
+short-circuit with no output and no cost. docs-orchestrator fills the generative-content
+gap that sibling skills leave open: `vault-sync` validates but does not write, `vault-mirror`
+writes metrics-derived `_overview.md` entries but not narratives, `claude-md-drift-check`
+diagnoses CLAUDE.md (or AGENTS.md on Codex CLI) drift but does not remediate it, and `daily` exclusively owns
+`03-daily/*`. docs-orchestrator is the only skill that produces new prose grounded in
+session output.
+
+## Invocation
+
+Not user-invocable. Triggered at three hook points within the session lifecycle:
+
+1. **session-start Phase 2.5 "Docs Planning"** — after user alignment, before handing
+   off to session-plan. Reads the agreed scope, runs audience detection (Phase 2 below),
+   and threads the detected audience list into the plan context so session-plan can
+   classify tasks correctly.
+2. **session-plan Step 1.5 Agent Registry** — `docs-writer` is added to the agent
+   registry when docs tasks are present; tasks carrying role `Docs` are assigned to it
+   (see session-plan Step 1.8).
+3. **session-end Phase 3.2 "Docs Verify"** — after waves complete, verifies that each
+   `Docs`-classified task produced a diff in the expected file-pattern target and reports
+   gaps per `docs-orchestrator.mode`.
+
+All three hook points are gated on `docs-orchestrator.enabled: true`. When disabled,
+every hook exits immediately after the config read.
+
+---
+
+## Phase 0: Input Validation
+
+**When:** At the start of every docs-orchestrator execution (all three hook points).
+
+**Action:** Confirm the invocation context is valid before doing any work.
+
+1. **Caller check** — Verify that this skill was invoked from one of the three
+   recognised hook points: `session-start Phase 2.5`, `session-plan Step 1.5`, or
+   `session-end Phase 3.2`. If the call context is missing or unrecognised, abort
+   with:
+   ```
+   [docs-orchestrator] ERROR: Unexpected invocation context '<context>'. Expected one of:
+   session-start Phase 2.5 | session-plan Step 1.5 | session-end Phase 3.2. Aborting.
+   ```
+
+2. **Config gate** — Read `docs-orchestrator.enabled`. If `false`, exit immediately
+   with no output, no logging, no side effects.
+
+3. **Task spec validation (hook point 3 only — docs-writer dispatch tasks)** — When
+   wave-executor dispatches a Docs task to docs-writer, the task spec MUST contain:
+   - `audience` ∈ `{user, dev, vault}` — reject any other value.
+   - `file-pattern` — a non-empty glob matching a pattern from `audience-mapping.md`.
+   - `rationale` — a non-empty string describing why this audience was triggered.
+
+   If any field is missing or `audience` is not one of the three valid values, abort
+   the task dispatch with:
+   ```
+   [docs-orchestrator] ERROR: Malformed task spec — missing or invalid field '<field>'.
+   Required: audience ∈ {user,dev,vault}, file-pattern (non-empty glob), rationale
+   (non-empty string). Aborting task dispatch.
+   ```
+   Do not fall through to Phase 1 with a malformed spec.
+
+4. **Mode validation** — Confirm `docs-orchestrator.mode` ∈ `{warn, strict, off}`.
+   Any other value is a config error; abort with:
+   ```
+   [docs-orchestrator] ERROR: Invalid mode '<value>'. Expected: warn | strict | off.
+   ```
+
+---
+
+## Phase 1: Read Session Config
+
+Read Session Config per `skills/_shared/config-reading.md`. Extract:
+
+- `docs-orchestrator.enabled` (boolean, default `false`)
+- `docs-orchestrator.audiences` (list, default `[user, dev, vault]`)
+- `docs-orchestrator.mode` (`warn` | `strict` | `off`, default `warn`)
+
+If `enabled: false`, exit immediately with no output. Do not log, do not query scope.
+
+Config is read once at invocation; subsequent phases use the cached values. If the
+config block is absent entirely, all defaults apply and the skill proceeds as if
+`enabled: false`.
+
+---
+
+## Phase 2: Audience Scope Detection
+
+Given the agreed session scope (from the session-start Q&A), determine which audiences
+are touched by the planned work:
+
+- **User** — new CLI flags or commands, breaking API changes, install-flow changes,
+  new user-facing features, changed examples.
+- **Dev** — architecture decisions, major refactors, new modules or subsystems, test
+  coverage changes, dependency upgrades, ADR-level choices.
+- **Vault** — project status changes, ownership transitions, stack or infra decisions,
+  cross-project dependencies, migrations, archival events.
+
+See `audience-mapping.md` (in this directory) for the authoritative file-pattern table,
+source rules per audience, and the non-overlap contracts with sibling skills.
+
+Intersect the detected audiences with the `docs-orchestrator.audiences` config value.
+Subset selection is supported — e.g., `audiences: [user, dev]` omits Vault writing even
+when Vault signals are present in scope.
+
+**When mode is `off`:** skip audience detection and return an empty list — no Docs tasks
+are generated.
+
+---
+
+## Phase 3: Task Generation
+
+For each selected audience, generate one or more docs tasks and thread them into the
+wave plan.
+
+Each task MUST specify:
+
+| Field | Requirement |
+|-------|-------------|
+| `audience` | `user`, `dev`, or `vault` — exactly one value |
+| `file-pattern` | Non-empty glob from `audience-mapping.md` Audiences & File Patterns table |
+| `trigger` | Which scope element motivates this task (e.g., "new `--dry-run` flag added to CLI") |
+| `allowed-sources` | Explicit list: `diff`, `git-log`, `session-memory`, `affected-files` |
+| `rationale` | Why this audience was selected for this task |
+
+Tasks flow through the standard session-plan pipeline. They are role-classified as
+`Docs` and assigned to the `docs-writer` agent at Step 1.8. No custom dispatch path
+is required.
+
+**Audience routing — hard non-overlap rules:**
+
+Before finalising a task's `file-pattern`, check it against the forbidden targets:
+
+- `<vault>/01-projects/*/_overview.md` — owned by vault-mirror. If the requested
+  target matches this pattern, abort the task with:
+  ```
+  [docs-orchestrator] ERROR: Target '<path>' matches vault-mirror's owned pattern
+  (<vault>/01-projects/*/_overview.md). Docs-writer must not write here. Aborting task.
+  ```
+- `<vault>/03-daily/*` — owned by daily. Same abort with the relevant pattern
+  message.
+
+If no valid non-forbidden target exists for a triggered audience, log an advisory
+(mode `warn`) or abort the session plan (mode `strict`):
+```
+[docs-orchestrator] WARN: Audience 'vault' triggered but all targets are forbidden.
+No Docs task generated for this audience.
+```
+
+---
+
+## Phase 4: Source Grounding (docs-writer execution protocol)
+
+**This phase applies inside the docs-writer agent**, not in the coordinator. It
+documents what the docs-writer MUST do when executing a dispatched Docs task.
+
+Before writing any documentation, the docs-writer MUST read and ingest the actual
+source material provided in the task prompt. The canonical four source types are:
+
+1. **diff** — `git diff $SESSION_START_REF..HEAD` — the verbatim diff of all changes
+   made during this session. This is the primary authoritative source for what changed.
+2. **git-log** — `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` — commit
+   messages and associated bodies. Secondary context for all audiences; use to
+   reconstruct the "why" when diffs alone are ambiguous.
+3. **session-memory** — Session transcript, wave outputs, and agent summaries stored
+   at `~/.claude/projects/<project>/memory/session-*.md` and under `.orchestrator/`
+   for the current session. Primary source for Vault narratives (status updates,
+   decisions made in conversation).
+4. **affected-files** — Full content of the files listed in the wave-scope's
+   `allowedPaths` (or the coordinator's `affected-files` context block). Primary for
+   User and Dev content where understanding the updated interface, schema, or module
+   structure is required.
+
+**No other sources are permitted.** General knowledge about architectural patterns,
+Node.js APIs, or project history that is not present in the four sources above must
+not be used.
+
+**Source grounding steps:**
+
+1. Confirm all four source blocks are present in the task prompt. If a source block is
+   empty or absent, note it before proceeding. **Hard guard:** if ALL four source blocks
+   are empty or absent, ABORT this phase with error `docs-writer: no grounding sources
+   available — refusing to produce source-less documentation`. Do not fall through to
+   silent REVIEW-marker-only output — the coordinator must see the failure.
+2. Read each source block in full before drafting any section.
+3. For every paragraph drafted, identify which source (or sources) support it.
+4. If a claim or narrative cannot be traced to at least one of the four sources, mark
+   the paragraph with `<!-- REVIEW: source needed -->` inline — do NOT omit the marker
+   to make output look cleaner.
+
+**Write or Update semantics:**
+
+- Prefer `Edit` on an existing file over `Write` (full replace).
+- For multi-section updates, prefer surgical section-anchored Edits over full-file Writes.
+- When the target file does not exist, use `Write` to create it.
+- Respect existing document conventions: preserve heading levels, frontmatter
+  structure, and table formats already present in the file.
+
+---
+
+## Phase 5: Source Citations
+
+**This phase applies inside the docs-writer agent**, concurrent with writing.
+
+Every substantive new paragraph MUST include a source attribution in one of two forms:
+
+**Inline HTML comment** (preferred for single-source paragraphs):
+```markdown
+The coordinator now creates a git stash ref before dispatching each wave, enabling
+crash recovery without data loss.
+<!-- source: diff -->
+```
+
+**Multi-source inline comment:**
+```markdown
+The new `--dry-run` flag skips file writes and prints a diff to stdout instead.
+<!-- source: diff, affected-file:src/cli/index.ts -->
+```
+
+**Collected `## Sources` section** (use when most paragraphs share the same sources):
+```markdown
+## Sources
+
+- diff: `git diff abc123..HEAD`
+- git-log: commits `abc123`–`def456`
+- session-memory: wave-2 coordinator summary
+- affected-files: `src/cli/index.ts`, `SKILL.md`
+```
+
+**Sourceless content:**
+
+If a section cannot be sourced from diff, git-log, session-memory, or affected-files,
+it MUST be marked:
+```markdown
+<!-- REVIEW: source needed -->
+```
+
+This marker signals to the human reviewer that the content requires verification before
+the next release. The docs-writer MUST NOT remove this marker to make output appear
+complete.
+
+---
+
+## Phase 6: Output Report
+
+**When:** At the end of every docs-writer agent run, and aggregated by docs-orchestrator
+at session-end Phase 3.2 "Docs Verify".
+
+The docs-writer MUST emit a brief structured output summary:
+
+```
+[docs-orchestrator] Docs task complete.
+  Files touched: <comma-separated list of relative paths>
+  Audiences served: <comma-separated list: user | dev | vault>
+  REVIEW markers: <count> (files: <comma-separated paths or "none">)
+  Source coverage: diff=<used|not used>, git-log=<used|not used>,
+    session-memory=<used|not used>, affected-files=<used|not used>
+```
+
+**Verification at session-end Phase 3.2:**
+
+1. Collect every task classified as `Docs` in the plan.
+2. For each task, resolve the expected `file-pattern` target and check for a diff:
+   ```bash
+   git diff --name-only $SESSION_START_REF..HEAD
+   ```
+   Match the output against the task's file-pattern using glob matching.
+3. Classify gaps by severity:
+   - **missing diff** — no matching file was changed; the task did not run or produced
+     no output.
+   - **partial** — a matching diff exists but one or more sections contain
+     `<!-- REVIEW: source needed -->` markers; needs human review before next release.
+4. Report per `docs-orchestrator.mode`:
+   - `warn` — log all gaps as advisories in the session final report. Non-blocking;
+     `/close` proceeds normally.
+   - `strict` — block `/close` until every gap is either resolved (diff exists, no
+     REVIEW markers) or explicitly overridden by the user via AskUserQuestion.
+   - `off` — skip verification entirely; emit no output.
+
+---
+
+## Non-Overlap with Sibling Skills
+
+- **vault-sync** — validates frontmatter schema; docs-orchestrator generates content.
+  Complementary: vault-sync runs after docs-writer writes, catching any schema drift
+  introduced by new docs.
+- **vault-mirror** — writes `_overview.md` from JSONL metrics records; docs-orchestrator
+  writes human-readable narratives in `context.md`, `decisions.md`, and `people.md`.
+  Non-overlapping targets by design.
+- **claude-md-drift-check** — detects drift in the project-instruction file (CLAUDE.md or AGENTS.md on Codex CLI; diagnostic only);
+  docs-orchestrator remediates via the Dev audience path (generative). Complementary:
+  drift-check can flag what docs-writer fixes. They must not run on the instruction file in parallel
+  within the same session.
+- **daily** — exclusively owns `<vault>/03-daily/YYYY-MM-DD.md`. This is a forbidden
+  target for docs-orchestrator; the docs-writer prompt must carry this constraint
+  explicitly (see Phase 3).
+
+---
+
+## Session Config Reference
+
+The three fields below are parsed in `scripts/lib/config.mjs` (`_parseDocsOrchestrator`)
+and validated in `scripts/lib/config-schema.mjs` (`validateDocsOrchestrator`). Defaults
+apply when the block is absent.
+
+```yaml
+docs-orchestrator:
+  enabled: false          # opt-in, default off
+  audiences: [user, dev, vault]  # subset selection supported
+  mode: warn              # warn | strict | off
+```
+
+- `enabled` — master switch. When `false`, all three hook points short-circuit.
+- `audiences` — which audiences to generate tasks for. Any subset of
+  `[user, dev, vault]` is valid.
+- `mode` — verification strictness.
+  - `warn` — surfaces gaps as advisories; `/close` is never blocked.
+  - `strict` — blocks `/close` until all gaps are resolved or user-overridden.
+  - `off` — disables audience detection, task generation, and verification entirely
+    (lighter than `enabled: false`; config is still read but all execution paths
+    exit early).
+
+---
+
+## Anti-Patterns
+
+- **DO NOT write docs without a traceable source.** Every section must trace to diff,
+  git-log, session-memory, or affected-files, or carry `<!-- REVIEW: source needed -->`.
+- **DO NOT edit `_overview.md` or `03-daily/*`.** These are owned by vault-mirror and
+  daily respectively. Attempting to write these targets aborts the task (Phase 3 hard
+  non-overlap check).
+- **DO NOT duplicate the audience-mapping table.** Always reference `audience-mapping.md`
+  in this directory — never inline the table into a task prompt or another skill.
+- **DO NOT dispatch docs-writer outside the wave-executor flow.** Docs tasks must go
+  through the standard task → wave-executor → Agent() path so they appear in STATE.md,
+  metrics, and the session final report.
+- **DO NOT use `hard` as a mode value.** The canonical enum is `warn | strict | off`.
+  Any other value fails config validation in Phase 0.
+- **DO NOT generate Docs tasks when mode is `off`.** When mode is `off`, skip all
+  execution after Phase 0 config read.

package/skills/docs-orchestrator/audience-mapping.md

@@ -0,0 +1,140 @@
+# Audience Mapping
+
+> Project-instruction file resolution: `CLAUDE.md` and `AGENTS.md` (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). When the Dev audience target is listed as `CLAUDE.md`, docs-writer resolves the actual file via the SSOT precedence rule.
+
+Rules for mapping session scope to target audiences, content sources, and documentation ownership.
+
+## Audiences & File Patterns
+
+| Audience | Target files (globs) | Typical update triggers |
+|----------|----------------------|-------------------------|
+| User | `README.md`, `docs/user/**/*.md`, `docs/getting-started.md`, `examples/**/*.md` | new CLI command, breaking API change, install flow change, new user-facing feature, changed example output |
+| Dev | `CLAUDE.md` (or `AGENTS.md` on Codex CLI), `docs/dev/**/*.md`, `docs/adr/**/*.md` | architecture decision, major refactor, new module/subsystem, test coverage change, dependency upgrade, ADR-worthy choice |
+| Vault/Ops | `<vault>/01-projects/<slug>/context.md`, `<vault>/01-projects/<slug>/decisions.md`, `<vault>/01-projects/<slug>/people.md` | project status change, ownership transition, stack/infra decision, cross-project dependency, migration, archival event |
+
+## Source Rules
+
+**The canonical four source types.** Only these four are permitted for docs-writer tasks.
+Any content not traceable to one of these four sources MUST be marked
+`<!-- REVIEW: source needed -->`. The docs-writer NEVER invents content.
+
+Every docs-writer task prompt MUST enumerate which sources apply. Content without a
+traceable source gets `<!-- REVIEW: source needed -->` — the agent NEVER invents content.
+
+| Source | Command / Path | Primary audience(s) | Notes |
+|--------|---------------|---------------------|-------|
+| **diff** | `git diff $SESSION_START_REF..HEAD` | Dev, Vault | Authoritative for what changed and when. Preferred primary source for Dev. |
+| **git-log** | `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` | All | Secondary context; use to reconstruct the "why" when diffs alone are ambiguous. |
+| **session-memory** | `~/.claude/projects/<project>/memory/session-*.md`, `.orchestrator/` outputs | Vault, User | Primary for Vault narratives (status updates, decisions made in conversation). Also primary for User tasks designed interactively. |
+| **affected-files** | Files in wave-scope `allowedPaths` / coordinator `affected-files` context block | User, Dev | Primary for understanding updated interfaces, config schemas, or module structures. |
+
+**Detailed source descriptions:**
+
+1. **diff** — Direct code changes from `git diff $SESSION_START_REF..HEAD`. Authoritative
+   for Dev narratives (what changed and why) and Vault decisions (what was decided, when).
+   Preferred primary source for Dev audience tasks.
+2. **git-log** — Commit messages and associated PR/MR bodies from
+   `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"`. Secondary context for all
+   audiences. Use to reconstruct the "why" when code diffs alone are ambiguous.
+3. **session-memory** — Session transcript, wave outputs, agent summaries, and test
+   results stored in `~/.claude/projects/<project>/memory/session-*.md` and under
+   `.orchestrator/` during the current session. Primary source for Vault narratives
+   (status updates, decisions made in conversation). Also the source for User audience
+   tasks where the feature was designed interactively.
+4. **affected-files** — Full content of files listed in the wave-scope's `allowedPaths`
+   (or the coordinator's `affected-files` context block). Primary for User and Dev content
+   where understanding the updated interface, configuration schema, or module structure is
+   required.
+
+**Ban on hallucination:** any section without a traceable source gets
+`<!-- REVIEW: source needed -->`. This marker signals to the human reviewer that the
+content needs verification before the next release. The docs-writer MUST NOT invent
+architecture decisions, CLI flags, or status narratives from general knowledge.
+
+## Non-Overlap with Sibling Skills
+
+docs-orchestrator must never write to paths owned by the following sibling skills. Attempting
+to target a forbidden path aborts the task at SKILL.md Phase 3.
+
+| Sibling skill | Owned path pattern | Why docs-orchestrator must not touch |
+|---------------|--------------------|---------------------------------------|
+| vault-mirror | `<vault>/01-projects/*/_overview.md` | vault-mirror regenerates this file from JSONL metrics on every session-end. A second writer would corrupt the metrics-derived content or introduce human prose that vault-mirror's next run overwrites silently. |
+| daily | `<vault>/03-daily/YYYY-MM-DD.md` | daily owns this path exclusively and is idempotent-by-design; a second writer (docs-writer) would corrupt the day's scratch notes and create conflicts on the next daily run. |
+| claude-md-drift-check | CLAUDE.md / AGENTS.md (diagnostic path — read-only quality gate) | drift-check diagnoses divergence in the project-instruction file but does not edit it. docs-orchestrator may remediate CLAUDE.md (or AGENTS.md on Codex CLI) via the Dev audience path, but they MUST NOT run on the instruction file in parallel within the same session wave to avoid concurrent edit conflicts. |
+| vault-sync | Frontmatter validation + wiki-link integrity on all `<vault>/**/*.md` (read-only quality gate) | vault-sync never edits files; it is a validation pass. docs-writer writes first; vault-sync validates after. No path conflict, but vault-sync runs must complete after docs-writer to detect drift introduced by new content. |
+
+**Forbidden targets (hard rules — abort on match):**
+
+- `<vault>/01-projects/*/_overview.md` — owned by vault-mirror.
+- `<vault>/03-daily/*` — owned by daily.
+
+These two patterns are enforced in Phase 3 of `SKILL.md` with an abort-on-match
+check. If the requested file-pattern target matches either forbidden glob, the Docs task
+is cancelled and an error is logged before any write occurs.
+
+## Example Prompt Skeleton for docs-writer
+
+The following is a representative prompt that docs-orchestrator generates for a Dev
+audience task. Adjust file-pattern target, trigger, and sources per task.
+
+```
+You are docs-writer. Your task is to update developer documentation based on
+session output.
+
+## Task
+Audience: Dev
+File-pattern target: docs/dev/**/*.md, CLAUDE.md (or AGENTS.md on Codex CLI)
+Trigger: New `coordinator-snapshot.mjs` module added; CWD-drift guard introduced
+  in wave-executor (issues #196, #219).
+
+## Allowed Sources
+Only these four sources are permitted. Do not use general knowledge.
+
+- diff: `git diff $SESSION_START_REF..HEAD` (provided below)
+- git-log: `git log $SESSION_START_REF..HEAD --format="%H %s%n%b"` (provided below)
+- session-memory: wave summaries and agent outputs from
+  ~/.claude/projects/<project>/memory/session-*.md and .orchestrator/ (provided below)
+- affected-files: content of modified .mjs and SKILL.md files listed in allowedPaths
+  (provided below)
+
+No other sources are permitted. Do not use general knowledge about Node.js APIs,
+architectural patterns, or project history that is not present in the sources above.
+
+## Source Citations
+For every paragraph you write, add a source attribution inline:
+  <!-- source: diff -->
+  <!-- source: git-log -->
+  <!-- source: session-memory -->
+  <!-- source: affected-file:path/to/file -->
+  <!-- source: diff, affected-file:src/foo.ts -->  (multi-source)
+
+If a paragraph cannot be traced to any of the four sources:
+  <!-- REVIEW: source needed -->
+
+Do not omit markers to make output look cleaner. Human reviewers depend on them.
+
+## Hallucination Ban
+Any section you write that cannot be traced to one of the four sources above MUST
+include the marker:
+  <!-- REVIEW: source needed -->
+Do not omit this marker to make the output look cleaner. Human reviewers depend on
+it to catch invented content before it ships.
+
+## Forbidden Targets
+- <vault>/01-projects/*/_overview.md — owned by vault-mirror. Do not edit.
+- <vault>/03-daily/* — owned by daily. Do not edit.
+
+## Output Report
+At the end of your run, emit:
+  [docs-orchestrator] Docs task complete.
+    Files touched: <comma-separated relative paths>
+    Audiences served: dev
+    REVIEW markers: <count> (files: <paths or "none">)
+    Source coverage: diff=used, git-log=used, session-memory=used, affected-files=used
+
+## Sources
+[diff output inserted here]
+[git-log output inserted here]
+[session-memory summary inserted here]
+[affected-files content inserted here]
+```

package/skills/domain-model/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.

package/skills/domain-model/CONTEXT-FORMAT.md

@@ -0,0 +1,77 @@
+# CONTEXT.md Format
+
+## Structure
+
+```md
+# {Context Name}
+
+{One or two sentence description of what this context is and why it exists.}
+
+## Language
+
+**Order**:
+{A concise description of the term}
+_Avoid_: Purchase, transaction
+
+**Invoice**:
+A request for payment sent to a customer after delivery.
+_Avoid_: Bill, payment request
+
+**Customer**:
+A person or organization that places orders.
+_Avoid_: Client, buyer, account
+
+## Relationships
+
+- An **Order** produces one or more **Invoices**
+- An **Invoice** belongs to exactly one **Customer**
+
+## Example dialogue
+
+> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?"
+> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed."
+
+## Flagged ambiguities
+
+- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts.
+```
+
+## Rules
+
+- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
+- **Flag conflicts explicitly.** If a term is used ambiguously, call it out in "Flagged ambiguities" with a clear resolution.
+- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
+- **Show relationships.** Use bold term names and express cardinality where obvious.
+- **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs.
+- **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.
+- **Write an example dialogue.** A conversation between a dev and a domain expert that demonstrates how the terms interact naturally and clarifies boundaries between related concepts.
+
+## Single vs multi-context repos
+
+**Single context (most repos):** One `CONTEXT.md` at the repo root.
+
+**Multiple contexts:** A `CONTEXT-MAP.md` at the repo root lists the contexts, where they live, and how they relate to each other:
+
+```md
+# Context Map
+
+## Contexts
+
+- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders
+- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments
+- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping
+
+## Relationships
+
+- **Ordering → Fulfillment**: Ordering emits `OrderPlaced` events; Fulfillment consumes them to start picking
+- **Fulfillment → Billing**: Fulfillment emits `ShipmentDispatched` events; Billing consumes them to generate invoices
+- **Ordering ↔ Billing**: Shared types for `CustomerId` and `Money`
+```
+
+The skill infers which structure applies:
+
+- If `CONTEXT-MAP.md` exists, read it to find contexts
+- If only a root `CONTEXT.md` exists, single context
+- If neither exists, create a root `CONTEXT.md` lazily when the first term is resolved
+
+When multiple contexts exist, infer which one the current topic relates to. If unclear, ask.