orchestrator.md - mozsearch

++ ---

++ 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):

++    curl -s "https://codereview.qt-project.org/changes/qt%2F{repo}~{id}/detail" \

++      | tail -n +2 | python3 -c "import sys,json; ..."

++

++    # Commit message:

++    curl -s "https://codereview.qt-project.org/changes/qt%2F{repo}~{id}/revisions/current/commit" \

++      | tail -n +2 | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('message',''))"

++

++    # File list:

++    curl -s "https://codereview.qt-project.org/changes/qt%2F{repo}~{id}/revisions/current/files" \

++      | 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:

++ 1. WebFetch: https://doc-snapshots.qt.io/qt6-dev/images/{filename}

++ 2. Clone: git clone --depth 1 https://code.qt.io/qt/{repo}.git /tmp/{repo}

++ ```

++

++ Reference: [QUIP 21](https://contribute.qt-project.org/quips/21) for

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

Revision control