Skip to content

Latest commit

 

History

History
164 lines (139 loc) · 9.06 KB

config.md

File metadata and controls

164 lines (139 loc) · 9.06 KB

multi-agent configuration

Owner document for the role map the multi-agent skills resolve. The bundled values live in defaults.yaml; a consumer layer overrides them per key. How layers are found and ordered across the marketplace is the config-cascade convention; this page owns the keys.

Layers

Layer Path
Bundled ${CLAUDE_PLUGIN_ROOT}/reference/defaults.yaml
User-global ~/.claude/multi-agent.yaml
Team <home>/multi-agent.yaml, <home> being the convention home the repository binds, else docs/conventions
Personal override .claude/multi-agent.local.yaml (gitignored)

Later layers win per key. Team and personal override are read only when the root is a repository that is neither $HOME nor an ancestor of it (lib/config-root.sh). The team file is validated by schemas/multi-agent.schema.json. The resolver no longer reads the old team locations, the config block in docs/conventions/multi-agent.md and .claude/multi-agent.yaml; /multi-agent:setup check names each one it finds. While the team YAML is absent, the first /multi-agent:setup apply --layer team write copies the keys of one of them, the block when there is one, into the new YAML and leaves the old file in place. Every layer declares schema: 1; a layer that does not parse or names another schema is skipped and named in notes, and the layers around it still apply. The format is a YAML subset: nested mappings, scalars, comments. No lists. /multi-agent:setup apply writes a layer after a preview and an explicit yes.

Keys

Key Values Bundled
roles.<role>.model inherit, or an alias: opus, sonnet, haiku, fable per role
roles.<role>.effort low, medium, high, xhigh, max per role
workloads.<w> true declares workload <w>, false withdraws it; <w> holds only letters, digits, _ and -, and does not start with - code, research and mechanical declared
roles.<role>.workloads.<w>.model / .effort as above; <w> is a declared workload worker.workloads.mechanical.model: sonnet (opt out with roles.worker.workloads.mechanical.model: inherit in any layer); a layer may set others, for example worker.workloads.mechanical.effort: low
frontier comma-separated aliases treated as frontier fable
fanout.frontier_guard true, false true
fanout.model an alias opus
verification, verification_skills.<skill> off, light, standard, strict light

verification is not part of the role map. It sets whether /multi-agent:audit-defaults runs its skeptic panel: light and off skip it and report every finding unverified, so no diff is proposed. It is read from the team file at the default branch only, through lib/read-verification.sh; the resolver ignores it in every layer, and the user-global and personal files cannot set it. A skill entry beats the plugin value (verification level).

Roles are orchestrator, worker, verifier and retrieval. A layer naming another role or key is reported and ignored, and so is a workload no layer declares. A declaration in any layer covers values set in every layer, so a team layer can declare a workload that a personal override tunes. A full model id (claude-opus-5-5) is rejected, so a role map stays portable across providers. Whether a role may name haiku is decided in routing-rubric.md; the resolver accepts it and adds a note. inherit means the calling workflow omits opts.model. For what an alias resolves to per provider, see model config: model aliases; for the model an agent with no model runs on, see workflows: cost.

For the values the subagent model field accepts, and the order in which a subagent with no model resolves one, see sub-agents: choose a model.

The effort values are the full set this resolver accepts; which of them a spawn can use depends on the model it runs on. For each model's supported levels, see model config: adjust effort level.

pointer*, basis_*, claim_*, reason_*, as_of and recheck record where each bundled default's basis lives. A role's basis_model and basis_effort say whether an upstream statement sets that value (upstream, with pointer_<field> and claim_<field>) or it is a judgment (judgment, with reason_<field>); a workloads.<w>.<field> value records the same keys on its role as basis_<w>_<field> and so on. The resolver prints the basis beside each value, and a guarded fan-out model takes fanout.model's basis. They are read from the bundled layer only, and /multi-agent:audit-defaults checks each upstream pointer against its value.

Tiering by difficulty

Route a stage by how hard its work is, not by its topic. Mechanical work (renames, formatting, one transformation applied at many sites, log filtering) goes through the mechanical workload, which runs the worker on sonnet by default. The hardest stage that one agent runs (a final synthesis, a judge, a design decision) takes the role's single variant, which keeps the role's own model. Everything else takes the role's default for its workload. The bundled mechanical model is this repository's judgment, weighing the well-scoped coding row of which Claude model should you build with: pick a model by task, as of 2026-11-09; recheck when that row changes its starting model.

Where effort applies

Role effort reaches workflow agent() calls, which pass opts.effort explicitly, and Agent tool dispatches with no named type, which pass it as the per-spawn effort parameter (route's Output section). A named agent runs at its effort frontmatter unless its dispatcher passes effort on the call or a source ranked above both applies. When it sets none, it runs at the session's level on the main conversation's model; on another model that level does not apply. route reads no settings file, so the effort it prints is the level a caller asks for, before any cap. A loop lane's level is its own lanes[].effort, not the orchestrator role.

Hard cap

maxEffortLevel is the consumer's hard cap over every role and every named agent's pinned effort: any higher level, from a role, frontmatter or the session, runs at the cap. Which settings scopes set it, how values across scopes and a model's modelSettings entry combine, and how an organization effort limit applies alongside it are read at the pointers below.

The fan-out guard

Every role resolves to two variants. single serves a stage that runs one agent (a final synthesis or judge); fanout serves a stage that runs more than one. With fanout.frontier_guard: true, a fan-out variant whose model would be inherit under a frontier session, or under a session the caller did not name, or that names a frontier alias, takes fanout.model instead. So the resolver never emits a frontier session's own model for a fan-out stage. What the agent runs on is the harness's call: see sub-agents: choose a model and run every subagent on one model. Under an Opus session opus and inherit name the same model, so the guard changes nothing there.

Setting fanout.frontier_guard: false is an explicit opt-in to frontier fan-outs. Set it on the layer whose scope you mean: the personal override for one checkout, the user-global file for every repository on one machine.

Example team file

This docs/conventions/multi-agent.yaml raises the worker's effort and declares a deep workload, which a caller selects with /multi-agent:route worker deep. A consumer maps its own labels (an issue's complexity, say) onto workloads in its own convention; the plugin ships no such mapping.

schema: 1
workloads:
  deep: true
roles:
  worker:
    effort: high
    workloads:
      deep:
        model: opus
        effort: xhigh
fanout:
  frontier_guard: true