/docs-orchestrator

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 a