docs-orchestrator

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.

1. 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).

1. 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. ``

1. Config gate — Read docs-orchestrator.enabled. If false, exit immediately

with no output, no logging, no side effects.

1. 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.

1. 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.

1. 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.

1. session-memory — Session transcript, wave outputs, and agent summaries s