shared/agent-fleet-methodology

Agent fleet methodology

AGENTS.xml is the schema — who exists, what they read and write, how they hand off. This file is the grammar — the narrative rules that govern how the schema is used.

Rules

1. Subagent delegation reads AGENTS.xml, never inferred patterns.

When the orchestrator decides who to hand off to, it reads the live AGENTS.xml in the repo. It does not improvise based on role names or prior conversation patterns. If a subagent appears to be missing for a task, the answer is add it to AGENTS.xml first, then delegate. Improvised roles are drift.

2. New roles are decision-doc events.

Adding a subagent to AGENTS.xml is a non-trivial change. It opens a dated decision doc (YYYY-MM-DD-agent-fleet-extension-<slug>.md) citing the trigger (a finding, a friction-round entry, a phase-open need) and the role’s bounded scope. MR-6 (subagent additions go in AGENTS.xml, not in prompts) is what this rule operationalises.

3. Prompts do not invent invariants.

Phase prompts (01-phase-open etc.) reference invariants by ID (MR-N from META-RULES.md, I-N from each repo’s CLAUDE.md). They do not introduce new invariants. Any prompt change that would add an ungrounded claim is a broken prompt — the bootstrap rule that agents must not invent invariants they cannot ground in spec or human answers applies recursively.

4. Role outputs live under docs/roles/<role>/outputs/.

Every subagent run writes its session log to its role’s outputs directory. Decision docs reference these logs as evidence. Outputs are append-only; old runs are not pruned.

5. The handoff graph is a DAG (intra-phase).

Schema rule 6 in AGENTS.xml.tmpl: the <handoff_to> graph is a DAG when filtered to intra-phase edges. Inter-phase edges (trigger=phase.close) and remediation back-edges (trigger=audit.fail) are exempt — they are legitimate loops at phase boundaries.

6. Refusal conditions are load-bearing.

Every subagent declares <refusal_conditions>. These are not optional politeness — they are the boundary between “this subagent is doing its job” and “this subagent is being asked to do someone else’s job.” Refusing per declared conditions is a success, not a failure.

Failure modes

• Improvised handoffs. “I’ll just have the planner do this audit step.” No — spawn the auditor, even if it’s slower. Improvisation rots AGENTS.xml over time.
• Unbounded roles. A subagent whose <refusal_conditions> are hand-wavy (“when it doesn’t make sense”) will accumulate scope. Tight, enumerable refusal conditions are required.
• Missing event triggers. Adding a new <spawns_on> event without declaring it in <event_catalog> will not trigger. Schema rule 5.