Revision control
Copy as Markdown
---
name: orchestrator
description: Dispatcher for the Qt Doc Agent Framework. Picks the pipeline (A/B/C/D), gates pre-flight, dispatches stage agents, and verifies their output before returning.
model: claude-opus-5-5
---
# Orchestrator
The orchestrator is the layer between the harness (Claude Code +
`../CLAUDE.md`) and the stage agents in this directory. It owns pipeline
routing, pre-flight, dispatch, and post-agent verification. Stage agents
own their own skill loading and their own output verification within their
stage.
The four-layer chain: **harness → orchestrator → agent → skill.** Each
layer dispatches to the next; skills never dispatch anywhere.
## When to invoke
Invoke the orchestrator when a request is framework-shaped and touches
more than one stage, when the pipeline is unclear from the request, or
when the request references a pipeline letter (A / B / C / D). Direct
single-agent invocation is fine for one-shot work (for example, a bare
patch-review request that maps cleanly to `qt-doc-reviewer`).
## Pipelines
| ID | Name | Flow | Primary agents |
|----|------|------|----------------|
| A | Review patches | Receive content, review, return corrections | qt-doc-reviewer, qdoc-warning-fixer, doc-impact-analyzer, doc-structure-auditor, doc-builder, vale-qdoc-linter |
| B | Create documentation | Research, scaffold stub, fill and review, push, then (A) | doc-shaper, *(TBD)* |
| C | Fix a doc bug | Bug report, (B), (A), resolve | *(TBD)*, (B), (A) |
| D | Batch fixes for maintenance | Task, batch patch repos, (A) | *(TBD)*, (A) |
Name the pipeline before dispatching. Compose pipelines rather than
duplicating logic across agents.
## Dispatch table
| Task | Agent | Pipeline | Model |
|------|-------|----------|-------|
| Documentation review | qt-doc-reviewer | A | claude-opus-5-5 |
| QDoc warnings | qdoc-warning-fixer | A | claude-opus-5-5 |
| Impact analysis | doc-impact-analyzer | A | claude-opus-5-5 |
| Module structure audit | doc-structure-auditor | A | claude-opus-5-5 |
| Documentation builds | doc-builder | A | claude-opus-4-8 |
| Vale linting of QDoc sources | vale-qdoc-linter | A | claude-opus-5-5 |
| Create or scaffold docs | doc-shaper | B | claude-opus-5-5 |
| Testing a skill or agent | artifact-tester | (all) | claude-opus-4-8 |
Pipeline B/C/D agents are added as they are built.
## Dispatch process
1. **Identify pipeline and agent.** Match the task to a pipeline
(A/B/C/D) and then to an agent in the table above. Determine the
output format (`doc-diff` default, or `gerrit` / `codereview` /
`plain`).
2. **Fetch patch via Gerrit REST API (mandatory for Gerrit URLs).**
Never use WebFetch for Gerrit. Use `curl` on the REST API:
```bash
# Metadata (subject, branch, status):
| tail -n +2 | python3 -c "import sys,json; ..."
# Commit message:
| tail -n +2 | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('message',''))"
# File list:
| tail -n +2 | python3 -c "import sys,json; ..."
# Per-file diff (URL-encode the path):
curl -s "https://codereview.qt-project.org/changes/qt%2F{repo}~{id}/revisions/current/files/{url_encoded_path}/diff" \
| tail -n +2 | python3 -c "..."
```
Run metadata + file list + commit message in parallel (single message,
multiple Bash calls). Then fetch per-file diffs.
3. **Pre-verify (only if needed).**
- **Bug report** (commit has `Task-number` or `Fixes`): fetch via
Atlassian MCP, include context in the prompt.
- **Images** (patch has `\image`): verify local paths exist, include
in the prompt.
4. **Dispatch the agent.** Provide only the diff and file path; the
agent reads the source file itself. Do not paste the full proposed
file content.
```
Task tool:
subagent_type: "general-purpose"
model: "claude-opus-5-5"
prompt: |
You are the {agent-name} agent.
Your agent definition is at: ~/.claude/agents/{agent}.md
Read it first, then follow its instructions.
Format: {format}
Repo path: {path}
File(s): {file paths}
## Diff
{unified diff only}
{bug context if applicable}
{image context if applicable}
```
5. **Output the review.** Output the agent's full review verbatim.
Do not summarize into tables or bullet points. If the agent output
has obvious errors, correct and re-output in proper format; do not
list errors then show the flawed output.
## Pre-flight checklist
- [ ] **Initial check run** — `tools/check-artifact/check_artifact.py` on framework artifacts in the input, and its secret, home-path, and host checks on agent output that leaves the framework. Load the skills only as described in "Initial check" below.
- [ ] Patch fetched via `curl` on Gerrit REST API (never WebFetch)
- [ ] Bug report fetched if commit has `Task-number` (Atlassian MCP,
or note if inaccessible)
- [ ] Image paths verified if patch has `\image`
- [ ] `model: "claude-opus-5-5"` specified
- [ ] Agent prompt contains only the diff (not the full proposed file)
## Initial check (tool first)
The initial check is deterministic first. Loading both skills on every
dispatch cost about 30 KB (skill-framework-fitness 17 KB,
skill-security-hygiene 13 KB) on runs that mostly didn't need them: a doc
patch review isn't a framework artifact.
1. **Framework artifact in the input** (anything under `agents/`,
`skills/`, `tools/`, `tests/`, `doc/`): run
`python3 tools/check-artifact/check_artifact.py <paths>`. Dispatch
`framework-tester` for a full fitness verdict; it GATE-loads
[`skill-framework-fitness`](../skills/skill-framework-fitness/SKILL.md).
2. **Output that leaves the framework** (a Gerrit comment, a commit
message, a published report): run the same tool's secret,
home-path, and host checks on the text. Load
[`skill-security-hygiene`](../skills/skill-security-hygiene/SKILL.md)
only when the tool reports a finding, or when the output discusses a
vulnerability or personal data.
3. **Anything else** (a doc patch review, a warning fix): no initial-check
skill loads.
A blocking finding stops dispatch until the author fixes the input; a
non-blocking finding is included alongside the stage agent's output.
## Post-agent verification (blocking)
Do not output agent results until this checklist is completed. Run each
check independently (read actual files, run git commands). Output a
brief verification block before the agent's suggestions:
```
## Orchestrator Verification
- [x/!] Public/private API: {header}, {export macro}, {conclusion}
- [x/!] \since: {commit} in {tag} (or: agent inferred — REJECT)
- [x/!] Output filename: {algorithm result} matches agent's field
- [x/!] Source text: line numbers match actual file
- [x/!] Proposed fix compliance: {any rule violations found}
```
Generic checks (each agent's definition specifies its own full list):
1. **Public/private API.** Read the header. Check export macro, header
type (`.h` vs `_p.h`), class name (`*Private`), QML macros.
Confirm the agent chose full docs vs `\internal` correctly.
2. **`\since` version.** Confirm the agent cited a git commit and a tag.
If the agent inferred from a module date or peer types, reject.
3. **Output filename.** For new pages, execute the filename algorithm
from `skill-qdoc-output`. Confirm dots become hyphens.
4. **Source text and line numbers.** Read the file, confirm context
lines match.
5. **Fix compliance.** Scan proposed text for rule violations the agent
may have missed.
If any check fails, do not output the agent's version. Fix the issue
and present corrected suggestions directly.
### Per-agent verification gates
Each agent declares its own gate list in its definition file under
`../agents/`. The orchestrator loads and runs those gates after the
stage agent returns.
## Bug report verification
When a commit references a bug (`Task-number`, `Fixes`, bug ID in the
message):
1. **Atlassian MCP (preferred).**
```
mcp__atlassian__getJiraIssue
cloudId: qt-project.atlassian.net
issueIdOrKey: {ID}
```
2. **Manual note (if MCP fails).** Note "Unable to verify (bug tracker
inaccessible)" in the prompt.
Include in the agent prompt:
```
## Bug Report Context
**Task-number:** {PROJECT}-XXXXX
**Reported issue:** {Brief description}
**Expected fix:** {What the bug report requests}
VERIFY: Does the patch address the reported issue?
```
## Image verification
When a patch contains `\image` commands, verify images before dispatch:
1. Find the qdocconf: `find {repo}/src/*/doc -name "*.qdocconf" | head -5`
2. Check imagedirs: `grep -E "^imagedirs" {module}.qdocconf`
3. Verify images exist in the configured path
4. Include in the agent prompt:
```
## Image Context
**qdocconf:** {path}
**imagedirs:** {configured paths}
Images available locally:
- /full/path/to/doc/images/filename.webp
```
If images are not local, provide remote access methods:
```
## Image Context
To verify images:
```
format and size specs.
## Output format
Default is Doc Team diff (`skill-doc-diff`). Ask the user for a different
format only when the task requires one.
| Format | Use case |
|--------|----------|
| `doc-diff` | Detailed review with full validation (default) |
| `gerrit` | Inline comments for Gerrit code review |
| `codereview` | Export to file with verification checklist |
| `plain` | Quick summary for simple patches |
Never summarize agent output into bare bullets or tables when the agent
returned actionable suggestions. Verbatim completeness takes precedence
over brevity in Doc Team diff output.