Sub-agent definitions

Updated Oct 17, 2026

agents/subagents.yml is the provider-neutral manifest of the managed sub-agent definitions (currently wyvern, scribe, alchemist, scrutineer, journeyman, artisan, and natural-philosopher). Each entry carries a shared description and instructions body plus per-provider blocks for Codex CLI, Claude Code, and goose. Downstream provisioning tooling (for example the dev-env-rocky agent_tools Ansible role) loads the manifest from a checkout of this repository and renders each enabled provider's native configuration file. The schema is documented in the manifest's header comment, and the deployment contracts are pinned by tests/test_subagent_definitions.py and tests/test_natural_philosopher.py.

For Codex, journeyman and alchemist use gpt-6.1-sol with medium reasoning; natural-philosopher uses the same model with high reasoning.

natural-philosopher designs evidence-led steps for one selected GIST idea and its parent goal. Supply the relevant sources, existing IDs, constraints, owned document paths, inquiry budget, and experiment permissions. It reads roadmap-doc, returns hypotheses, coherent workstreams, evidence criteria, and decision gates, and leaves approval to the parent. It may use bounded Wyvern reconnaissance or explicitly authorized Alchemist experiments when the host supports delegation. Without experiment authority it designs only; without owned document paths it returns a report rather than editing files. See ADR 0004 for the contracts, provider limits, and a worked example.

Each hypothesis carries its own verdict, which the report keeps separate from its overall status. The diagram below traces one hypothesis from untested, through a verdict and a decision gate, to the status the report returns.

Natural Philosopher hypothesis verdict and decision gate flowEvery hypothesis begins untested and takes one of three verdicts: not-falsified when the evidence does not falsify it, falsified when a falsification condition is met, or inconclusive when the evidence is insufficient or conflicting. Each verdict then reaches a decision gate. Not-falsified proceeds when the acceptance criteria are met. Falsified leads to revise when the preferred bet is defeated, or to stop when proceeding would change the mandate. Inconclusive leads to defer when bounded further inquiry is required, or to escalated when budget, authority, or scope is blocked. The proceed, revise, defer, and stop gates all return a report that is ready-for-review, because each one is a recommendation for the parent to weigh. Escalated is the report's other status, and the only one that does not carry a recommendation.

evidence does not falsify

falsification condition met

evidence is insufficient or conflicting

acceptance criteria met

preferred bet defeated

bounded further inquiry required

proceeding would change the mandate

budget, authority, or scope blocked

not-falsified

ready-for-review

untested

falsified

inconclusive

proceed

revise

defer

stop

escalated

Hypothesis verdicts, the decision gate each one reaches, and the report status that follows. A verdict describes one hypothesis; a status describes the whole report.

scrutineer runs a summoned assignment in up to three modes: the deterministic local commit gates, an optional coderabbit review --agent pass run only when explicitly requested, and GitHub Actions monitoring. A monitoring-only assignment watches the requested runs without starting local gates or a new review; those activities are reported as not-requested rather than passed or silently skipped. A docs-only diff, where every changed path ends in .md, scopes the gate set to make markdownlint and make nixie.

Every monitoring assignment runs its polls and waits in the foreground for the duration of the active turn. Scrutineer does not leave detached watchers running or treat a later background result as evidence. When requested, it can also monitor reviews and checks already posted to a GitHub pull request. It collects the required check states and the requested reviewers' submitted reviews, binds reviews to the refreshed PR head, and preserves findings from review comments and CodeRabbit's pre-merge report, including its failed, warning and passed rows. Reviews on an older head are stale; resolved inline threads are excluded, while unresolved threads and comments that cannot be tied to the current head remain visible as unresolved or unverified evidence. A failed CodeRabbit row remains a finding even if its outer GitHub check is green. Monitoring is complete only when all required checks are terminal and every expected reviewer has submitted a review on the current head; findings can still prevent a clean verdict. If the observation deadline arrives first, pending checks and missing current-head reviews are reported as incomplete, never as clean.

Actions monitoring correlates an explicit repository, expected commit SHA, run ID and attempt; PR-head, synthetic-merge and post-merge integration evidence are kept distinct, and the latest run on a branch is never substituted for the assigned candidate. Candidates are resolved from the pull request's own check links or from an exact commit; checks that are not Actions runs are classified separately rather than monitored, and every candidate is verified before it is watched. A deadline bounds the watcher itself, and reaching it stops only local observation: scrutineer never reruns, cancels, dispatches, approves or merges, and it does not cancel hosted runs when the deadline is reached. Only status=completed with conclusion=success counts as success; pending, cancelled, skipped and neutral states are preserved, and CLI, credential or API problems are reported as infrastructure-error rather than as a workflow failure. Every observed run and attempt contributes run metadata and watcher output (run.json, watch.log) to a private bundle under /tmp, alongside a root summary.md. Failed-step logs (failed.log) are captured only for a run that reaches status=completed with a non-success conclusion; a run still pending at the deadline is reported with the evidence gathered so far and its last known status, treated as neither success nor failure, and it has no failure-log artefact. When capture does not apply, the bundle carries a short failed-log.omitted note recording the observed status and conclusion, so a missing failure log is never ambiguous. Missing, expired or inaccessible logs are reported explicitly, with the reason, rather than read as success. scrutineer never edits tracked files.

journeyman delivers one full approved ExecPlan, or one named plateau of it, end-to-end. It may delegate small, bounded, measurable, testable work items to artisan agents.

artisan accepts exactly one bounded task packet. It cannot delegate and must escalate incomplete packets or work outside the packet's scope.

Managed subagents receive the MCP servers provisioned by the parent agent client. Every subagent's Claude allow-list includes CodeGraph; the journeyman and natural-philosopher allow-lists also include Firecrawl and DeepWiki. Codex subagent entries deliberately omit mcp_servers, so Codex inherits the complete credentialed parent registry. Goose recipes omit extensions, so goose inherits the parent's configured extensions. As a result, Codex and goose may expose other parent MCPs to every role, while Claude access stays limited to the listed allow-lists. Tool access never expands the assignment's authority.