Prompt and Artifact Composition

This is the canonical reference for how agents-fleet composes coordinator and worker prompts, what authors may extend, and which behavior remains owned by the runtime.

Artifact model

agents-fleet loads four v2 Markdown artifact types:

Artifact	Serialized suffix	Purpose
Role	.role.md	A coordinator or worker persona
Skill	.skill.md	Reusable knowledge and instructions
Workflow	.workflow.md	Coordinator execution guidance and stages
Crew	.crew.md	A coordinator role, worker roster, topology, and workflow

Use lowercase kebab-case names such as docs-reviewer and typescript-conventions. Roles and skills are composed into prompts; crews and workflows select and overlay those components.

Coordinator prompt order

The coordinator prompt is assembled in this fixed order:

1. Persona — the active coordinator role body.
2. Independent coordinator operational guidance — the separately resolved coordinator-operational-guidance atomic skill. It is not part of the persona and follows normal artifact-tier precedence.
3. Crew overlay — the pre-wrapped <active-crew> block, when a crew is active.
4. Workflow overlay — the pre-wrapped <active-workflow> block, when a workflow is active.
5. Discovered instructions — applicable repository instruction files.
6. Project context — generated project/FLEET context.
7. Fleet intelligence — the <fleet-intelligence> block, when available.
8. Generated invariant core — the runtime-generated coordinator contract, always appended last.

The last position matters: user-authored prose can specialize the coordinator, but cannot supersede the runtime's current tool catalog, delegation rules, completion rules, concurrency constraints, security boundaries, or topology contract.

If coordinator-operational-guidance is missing or rejected, startup warns and uses minimal fallback guidance. reload_registry re-resolves the guidance and recomposes both the active SDK prompt and recovery configuration while retaining active crew and workflow overlays.

AGENTS_FLEET_DISABLE_CENTRAL_PROMPT=1 disables only the generated coordinator core. It is a diagnostic-only legacy killswitch, not a supported extension mechanism or production configuration. It never disables the mandatory worker core.

Native ROOT authority is not a prompt layer

In native mode (opt-in for fresh sessions with --native-root), RootProductionSession supplies native planner guidance alongside project context and installs the outermost task-tool adapters at initial registration and recovery/reload. The ordinary generated invariant core remains last; neither a crew overlay nor a custom role can opt out of ROOT admission by changing prose.

Fresh sessions without a mode flag, explicit --no-native-root and legacy saved-session resume retain legacy Fleet execution without native resources. Saved sessions keep their mode; opposite-mode resume is refused instead of migrating tasks. Native execution uses the same host-resolved custom roles, skills, MCP, acknowledged YOLO and Claude worker inputs under existing policies. Neither the fresh default nor a mode flag grants trust or permissions; AGENTS_FLEET_NATIVE_ROOT is ignored.

Task tools propose a durable draft. Only an explicit root_plan_commit can admit its exact version for execution; the runtime then owns scheduling, evidence validation, declared-verifier decisions and downstream eligibility. Ordinary chat needs no task DAG. Reports, DoD checkboxes and completion text are not acceptance. Existing workflows remain child executors, not an alternative source of root acceptance or Git authority.

Native worker preparation preserves role/skill/crew sources and hashes, model, effective profile, provider/MCP settings and authorized isolated/shared workspace choices. Both providers retain their authorized writable profiles; canonical nonspawnable types, internal workflow-runner routing and current planning-mode restrictions still apply. Existing independent project trust settings and SEC acknowledgements remain separate: no additional native ack is required for an already authorized configuration, and unattended mode is not escalation. Prepared operations recheck current sources/grants before crossing rather than silently adopting changed policy.

Artifact discovery or trust does not itself authorize a worker profile or an integration target. Human decisions and exact manual starts use authenticated native operator controls, not prompt-written completion flags. Workers can delegate only within their admitted scope; reports/messages cannot rewrite their committed acceptance contract. See Coordinator Planning for contracts and exact controls.

Worker prompt order

Worker prompts have only two layers, in this order:

1. Role plus skills — the role body and requested atomic skills composed by the registry.
2. Mandatory worker core — the runtime-generated worker contract, appended last for every worker.

Skills add domain knowledge, conventions, checklists, and task-specific instructions. They do not grant tools or permissions. The worker's agent type and runtime permission profile determine read, write, shell, and communication capabilities.

The mandatory core owns worker identity and capability framing, assumption tracking, completion behavior, and topology-specific communication:

Topology	Runtime communication contract
silent	No inter-agent communication tool names are injected
hub	Workers report through report_to_coordinator
mesh	Workers can report to the coordinator and use peer messaging

Explorer and reviewer permission restrictions remain runtime-enforced even if a role or skill asks for write or shell access. Artifact prose cannot widen a permission profile, change topology, or bypass tool policy.

Extendable versus runtime-owned behavior

Authors may extend:

• Persona, tone, domain process, and output expectations in roles.
• Reusable project knowledge, conventions, and checklists in skills.
• Team membership, model preferences, dependency ordering, and a topology selection in crews.
• Stages, artifacts, branching, gates, parameters, and prose guidance in workflows.

The runtime owns:

• The live coordinator tool catalog and delegation/security boundaries.
• Worker identity, permission profiles, and available tools.
• Topology communication invariants.
• Completion/task-integrity and runtime-concurrency rules.
• The final coordinator invariant core and final mandatory worker core.

Do not copy runtime contracts into custom roles or skills. Besides becoming stale, copied contracts can contradict the generated final layer.

Reserved tags and headings

Role and skill bodies are rejected when they try to masquerade as code-owned prompt blocks. Do not use <central-block>, <core-block>, or their closing forms. The following coordinator headings are also reserved:

• ## Fleet Tools Reference (including the always available variant)
• ### Runtime fleet-tool catalog
• ### Delegation and security boundary
• ### Completion and task integrity
• ### Topology contract
• ### Inline-tool boundary
• ### Runtime concurrency

Ordinary discussion of tools is allowed; the restriction is intentionally narrow and protects exact runtime-owned tags and headings.

Tiers and trust

Artifacts resolve by name in this precedence order:

Precedence	Tier	Location
Lowest	Bundled	Assets shipped with agents-fleet
	User	~/.fleet/{roles,skills,workflows,crews}/
	Team main	Trusted team meta-repo checkout
	Team member	Trusted members/<name> overlay
Highest	Trusted project	<cwd>/.fleet/{roles,skills,workflows,crews}/

The team tiers are optional and v2-only. Enable them with --team; on first use, pass --trust-team or set AGENTS_FLEET_TRUST_TEAM=1 to confirm the meta-repo and pin its fingerprint. Later runs trust that same fingerprint automatically; a changed repository URL requires explicit re-trust. The member overlay loads after team main. See Team Meta-Repo for the pointer format, synchronization, and TOFU details.

Bundled and user roles, skills, and crews always load. Project roles, skills, and crews are off by default; enable them with --trust-project-skills or AGENTS_FLEET_TRUST_PROJECT_SKILLS=1.

Project workflows use a separate trust control. They load by default for direct and crew references, and their slash-command synthesis is enabled by default. --no-trust-project-workflows or AGENTS_FLEET_TRUST_PROJECT_WORKFLOWS=0 disables only command synthesis. It does not enable or disable project roles, skills, or crews.

The save tools can write project artifacts during the current trusted coordinator session. That write capability does not change startup discovery policy: after a reload or restart, project roles, skills, and crews are available only when project-skill trust is enabled. Project workflows follow their separate workflow policy.

Reload and restart behavior

Call reload_registry after adding or editing an artifact on disk. It reloads workflows, crews, roles, skills, and gates; refreshes coordinator composition; and makes new definitions available to subsequent command invocations and worker spawns. Existing in-flight workflow runs keep the parsed snapshot with which they were dispatched.

A restart also reloads the registry, but reevaluates CLI, environment, and configuration trust settings from scratch. Saving an artifact does not make a future session trust project roles, skills, or crews automatically.

Related guides

• Authoring Crews
• Building Workflows
• Workflow Authoring Capability
• Team Meta-Repo
• Configuration