--- name: docs-orchestrator user-invocable: false tags: [docs, orchestration, audiences] model-preference: sonnet description: > Opt-in orchestration for 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 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 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 ''. 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 ''. 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 ''. 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: - `/01-projects/*/_overview.md` — owned by vault-mirror. If the requested target matches this pattern, abort the task with: ``` [docs-orchestrator] ERROR: Target '' matches vault-mirror's owned pattern (/01-projects/*/_overview.md). Docs-writer must not write here. Aborting task. ``` - `/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//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 `` 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. ``` **Multi-source inline comment:** ```markdown The new `--dry-run` flag skips file writes and prints a diff to stdout instead. ``` **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 ``` 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: Audiences served: REVIEW markers: (files: ) Source coverage: diff=, git-log=, session-memory=, affected-files= ``` **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 `` 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 CLAUDE.md (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 CLAUDE.md in parallel within the same session. - **daily** — exclusively owns `/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 ``. - **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.