Skip to main content

Agent teams

Start with the outcome you want, then choose the smallest team that can deliver it. For a focused change, one implementer can use specialist skills as needed. Add another role when it has a distinct deliverable, separate files to own, or an independent review to perform. More agents also add coordination and model cost.

The four procedures are available as ordinary skills through the process plugin and the pack's skill distribution:

ProcedureUse it to
agent-team-creatorDescribe an outcome, stage native definitions, then install or adopt the project team.
agent-team-manageAssign and track revisioned tasks, dependencies and evidence.
agent-team-modelsCompare configured models against explicit capabilities, tiers and price ceilings.
agent-team-handoffPrepare fresh context and transfer ownership after destination acceptance.

Find your responsibility​

Use the same selected project team across these levels. A person or agent may perform several responsibilities, but each task still needs an explicit owner.

LevelWhat you decide or recordStart here
User or project ownerDesired outcome, scope, budget, permitted destinations and requested reviewPropose a team
Team leadSelected manifest, bounded assignments, dependencies, active writers and completion evidenceInstall or adopt, then task lifecycle
Role ownerAssigned paths, current task identity, progress, blockers and evidenceOwnership and team updates
Project maintainerDiscovery records, local ledger and canonical KBD linksRecords and identity recovery
Cross-project coordinatorAuthorized request, destination intake, correlation IDs and acknowledgementProject requests
Harness operatorDiscovered native roles, available dispatch tools, permissions and actual model routeNative discovery and model selection
Service operatorOptional endpoints, credentials, data ownership and recoveryServices and ownership

For a first local team, follow proposal, project installation, path ownership and task lifecycle in that order. Read the handoff section when ownership or harness changes. Add model discovery, shared memory or connected services only when the work needs those capabilities. The team overview provides shorter routes through this handbook.

From an outcome to a proposal​

Before creating state, read the project's instructions and existing .agent-team/project-routing.json and .agent-team/<id>/team.json files. Reuse the selected team when it fits. You need Node.js 22+ and the complete creator payload; Git is optional for snapshots. A native coding tool is needed to execute work. Model endpoints, shared memory and UAR/BossFang services are separate, optional dependencies. Full includes broader learning integrations; mini keeps its Node-only runtime and two optional services, surreal-memory and liter-llm. Neither pack starts a service or agent merely by creating a local team.

Ask agent-team-creator to help with a concrete result, such as making a settings page keyboard accessible. It asks about scope, deliverables, budget, review and the coding tool you will use. A simple change defaults to one implementer; independent review is an explicit choice. Review suggested skills against what is installed, and assign paths in every editing role's owns list before parallel work. Inputs, outputs and dependencies make the expected handoff explicit.

Experts can supply a team manifest directly. The shared runtime accepts JSON request files:

node skills/process/agent-team-creator/scripts/cli.mjs guide --input guide-request.json

From an installed skill, use its actual agent-team-creator/scripts/cli.mjs path. Node.js 22+ is required; the shipped JavaScript needs no TypeScript installation or runtime packages. For example, guide-request.json can contain:

{
"id": "settings-accessibility",
"outcome": "Make settings usable with a keyboard",
"complexity": "simple",
"areas": ["code"],
"deliverables": ["Accessible settings page", "Verification record"],
"budget": "balanced",
"review": false,
"harness": "codex",
"scope": "project"
}

The result includes an editable team, reasons and alternatives. An empty request returns the intake questions. Save the reviewed manifest through init; use status to retrieve current revisions before later mutations. The repository request reference provides complete initialization, export, task and handoff examples.

Export is a review boundary​

An export request names the team or state file, target and a new output directory. The runtime stages native definitions and provenance receipts. It refuses existing output directories and path or filename collisions. Review selected files before installing them; export does not install plugins, register service agents or start execution. Native permissions and invocation rules remain authoritative.

Targets are UAR, Codex, Claude Code, Copilot, Kimi Code, MiniMax, OpenCode, DeepSeek Harness and BossFang. The adapter uses each tool's native format. Claude and Kimi have alternative agent plugin/marketplace artifacts; Codex uses standalone native agent TOML without an invented plugin agents field. MiniMax agent files belong under its active user-data directory. Kimi does not apply per-role model frontmatter, and DeepSeek's experimental team composition does not create a roster or select per-member models. UAR export remains legacy per-agent AgentArtifact staging; draft.2 packages and private bindings use the separate file-backed flow below. BossFang Hand activation is a separate action that may start schedules.

Native role overrides, team options and opaque files preserve settings beyond the common manifest, with source/version provenance. Preservation does not certify a setting against an installed tool. The native contract reference links official sources and explains which options become proposed config files and which remain sidecar data for deliberate application.

UAR draft.2 file-backed teams​

Legacy export --target uar still creates per-agent AgentArtifact staging files. Canonical teams use the provider-owned draft.2 profile with workspace.json, manifest.source.json, and separate source documents such as agents/coordinator.json, agents/child.json, teams/root.json, teams/subteam.json, and workflows/review.json.

node skills/process/agent-team-creator/scripts/cli.mjs uar-workspace-init --input skills/process/agent-team-creator/assets/uar-intake.json
node skills/process/agent-team-creator/scripts/cli.mjs uar-workspace-status --input workspace-status.json
node skills/process/agent-team-creator/scripts/cli.mjs uar-workspace-update --input update-one-document.json
node skills/process/agent-team-creator/scripts/cli.mjs uar-package-build --input workspace-build.json

Workspace status stays bounded: fixed counts, one next question, and paged field diagnostics. Validation requires one root TeamDefinition, kind-correct references, valid workflow roles, acyclic dependencies, and exact versions and digests. Draft.1 and inline callers migrate explicitly and retain field-level loss reports.

The compiled package is portable immutable catalog data. DeploymentBinding is private installed state and carries opaque host references; package installation does not confer credentials, RepresentationGrants, consent, authority, or activation. The draft.2 checkpoint does not claim durable team execution, and uar-activate refuses rather than reporting an unobserved runtime result.

Install or adopt a project team​

After reviewing the export, finish normal project-team creation with install-project. For a new team, save {"project":"/path/to/project","team":<manifest>} as install-request.json, then run:

node skills/process/agent-team-creator/scripts/cli.mjs install-project --input install-request.json --dry-run
node skills/process/agent-team-creator/scripts/cli.mjs install-project --input install-request.json
node skills/process/agent-team-creator/scripts/cli.mjs install-project --project "/path/to/project" --check

For an existing team, use --project "/path/to/project" without an input manifest. A recorded .agent-team/project-routing.json selection wins; otherwise a sole .agent-team/<id>/team.json is adopted. Multiple candidates require --team <id>; stale selections fail rather than silently switching. Intentional manifest replacement requires updateTeam: true in the request. Creator check exits 2 for drift and 1 for errors.

Installation writes managed discovery pointers to both instruction entrypoints, the active routing record and missing native definitions. Existing native files, role IDs, ownership, model policies, permissions and concurrency remain intact; differing configuration is reported for deliberate merge. Recovery records retain prior instruction bytes. Export stages proposals; installation establishes discovery. Neither starts execution or activates UAR/BossFang registration.

All code tasks use the selected team’s relevant roles. UI roles conditionally use prometheus-ui-ux; UI review uses prometheus-ui-review after the whole implementation phase, without taste or user-only skill preloads. Backend work loads no UI guidance. Use native delegation only if available, otherwise disclose sequential role execution; builder self-review is not independent review. Zed receives the pointer in its effective existing instruction file. External ACP agents keep native configuration, and Zed parallel threads are not a delegation API.

See UI/UX routing for the selective workflow.

Choose roles and keep one writer per path​

A role has an ID, prompt, installed skills, owns, inputs, outputs and role dependencies. Use project-relative paths or globs for write ownership. Assign a reviewer its own findings path, such as reviews/settings.md; it may read the implementation without editing the implementer's files. An empty ownership list does not authorize unrestricted edits. The expert schema permits empty arrays, but guided creation asks you to resolve ownership before returning a ready team.

The portable team manifest, local task state and project routing record each use schema version 1. They serve different purposes:

RecordPurpose
.agent-team/<id>/team.jsonProject discovery manifest: roles, ownership and native bindings
.agent-team/project-routing.jsonSelected manifest and installed native definition paths
.agent-teams/<id>.jsonMutable task ledger chosen by your state request
Export directoryProposed native artifacts and provenance receipts

Import a reviewed portable manifest by placing it under team in an init or install-project JSON request. There is no universal native-agent import command. Keep native fields under native.<target> with source/version provenance rather than treating a native file as a portable team manifest. The separate UAR draft.2 profile uses immutable agent, team and workflow definitions; it is not schema-v1 task state. Read the manifest schema and project installation requests before replacing a definition.

Role dependencies describe the team. A task must separately name task IDs in dependsOn; the runtime does not create those edges from role dependencies. Assign separate implementation and review tasks. Keep review dormant until all production work in the active phase is complete, then use the project's required local integration and independent review boundary.

Run the revisioned task lifecycle​

Save requests as JSON and call the creator's packaged runtime. The repository request reference contains a complete add/start/block/resume/complete sequence, with cancellation and reassignment alternatives. The four skills share this runtime; installing four skills does not create four agents.

StepCommand or actionWhat it records
InspectstatusCurrent state revision, tasks, owners and task revisions
Assigntask with action: "add"A pending task owned by an existing role
Starttask with action: "start"Running state after dependencies complete
Updateblock, start or reassignEvidence and explicit remaining work on a supported transition
Canceltask with action: "cancel"Terminal cancellation and a reason
Completetask with action: "complete"Running task, evidence and no remaining work

There is no generic update action. Every mutation after initialization supplies the current expectedRevision; existing-task operations also supply current owner and expectedTaskRevision. Read status before each mutation and reconcile conflicts instead of incrementing a guessed revision. A successful task change increments state and task revisions once. add starts a task at revision 0; completed and cancelled tasks remain terminal.

An owner string is a claim made by a cooperating caller, not authentication or a distributed lease. Assignment and start do not spawn a process. Cancellation does not interrupt it. Dispatch the native worker separately with the exact project directory, assigned paths, prohibited paths, deliverable and current task identity. Stop the old worker before reassignment permits another writer. Use sequential role execution and disclose it when native delegation is absent.

Example: a bounded dispatch​

Suppose the lead assigns settings-copy to implementer, with ownership of src/settings/copy.ts. The native dispatch should carry a brief such as:

Project: /absolute/path/to/project
Team: the selected project team
Task: settings-copy; owner: implementer
Revisions: copy the current state and task revisions from status
Own: src/settings/copy.ts
Do not edit: src/settings/layout.tsx or another role's assigned files
Deliver: the agreed settings text and the changed-file references
Report: evidence, blockers and remaining work; preserve other contributors' edits

This is a dispatch brief, not CLI input. Add the real canonical task identity when linked to KBD, the selected model route and any task-specific constraints. The lead records start after dependencies permit it and invokes an authorized native worker separately. The role reports findings; the lead reconciles them with the ledger before recording completion. If work is blocked, preserve the reason and remaining work. A later start resumes a blocked task; a terminal task needs a new follow-up task.

If review is required, give the reviewer a separate dependent task and its own findings path. Dispatch it at the project's completed-phase review boundary. If the same unfinished task must move to another role or harness, use the acceptance flow below before the new owner edits.

Local add and reassign are administrative assignments; neither requires a destination acceptance packet. A context-bearing handoff-create retains source ownership until handoff-accept. Direct UAR coordinator acceptance is a third, provider-schema concept, described below. These are distinct boundaries.

UAR direct coordinator acceptance​

The vendored draft.2 TeamDefinition schema uses the field taskAcceptance, not a local task-accept command. This fragment belongs inside a complete draft.2 TeamDefinition:

{
"taskAcceptance": {
"mode": "coordinator-within-binding",
"allowedWorkflows": []
}
}

Coordinator mode permits an empty workflow list, allowing a definition to represent direct coordinator tasks within its binding. Operator mode requires at least one immutable workflow reference. An empty list is not a wildcard workflow grant. Routing requires eligibilityFirst: true, strategy operator-role-capacity-cost-stable-id, and explain: true.

The consumer receipt pins provider commit d8896d743cd945d40f918ff8ca397909f6c1fe22 as a source-contract checkpoint. This is schema support, not durable execution or live acceptance. It does not replace local handoff-accept, grant credentials, activate a team or establish that a resident UAR implements the policy. The shipped uar-activate path still refuses activation. Check the provider contract and deployed capabilities before use.

Preserve canonical identity and recover deliberately​

For KBD-linked tasks, retain the exact projectId, runId, phaseId, changeId and taskId. A displayed title, task index, inferred next command or local team ID is not a canonical task selector. The canonical task must already be in_progress, or already complete when reconciling a confirmed result, before the team's complete-kbd adapter records local completion. Ordinary local complete rejects KBD-linked tasks.

The adapter executes the explicit kbdCli, reads canonical status, verifies all five identities, and records the committed receipt before local completion. Local and canonical state are separate stores: a timeout or crash may leave KBD complete while the local task remains running. Read both stores and reconcile the confirmed result before retrying. Preserve the project’s claim, stage, permission, evidence and phase gates; team assignment grants none of them.

Local mutations use an exclusive <state>.lock and atomic replacement on one filesystem. They do not support shared multi-machine writers or automatic stale lock takeover. If a writer crashes, inspect its recorded PID, time and token, confirm it has stopped, then remove only the abandoned lock. Re-read state and uncertain external outcomes before retrying. Read the task and recovery contract for exact KBD requests and recovery steps.

Check native discovery before dispatch​

Portable definitions preserve native options; they do not override the installed harness's permissions. Current Codex role configuration source applies a role configuration layer when a role is spawned. Review generated TOML against the installed Codex version before invoking it; do not invent a plugin agents field or infer execution from files on disk.

Claude Code project subagents use Markdown with frontmatter in .claude/agents/. Native tools and permission modes remain authoritative. Experimental agent teams are a separate feature; exporting subagent files does not enable or create one. OpenCode custom agents use .opencode/agents/*.md; native permission rules govern tools and which subagents a primary agent may invoke. Kimi custom agents use native Markdown definitions, including project .kimi-code/agents/ discovery; exported model frontmatter does not establish per-role model selection. DeepSeek's experimental agent-team service uses runtime member creation, rather than a portable manifest that launches its roster. Read the linked native contract before enabling it.

Record the actual native tool/version and discovered role. Report missing discovery or unsupported settings explicitly; an exported file is not proof of an available worker.

Communicate within the team​

Use native messages for coordination and the revisioned ledger for ownership. A useful update names project/team/task, current owner and revision, what changed, evidence, remaining work and the next requested action. A message saying “please review” is not a task start, accepted handoff or completion receipt. Save durable artifact references in task evidence; do not rely on a conversation that another harness cannot read. The creator does not supply a universal chat or dispatch API.

Use an authorized local file or the native harness's available communication mechanism. Follow the destination tool's messaging permissions; do not send Slack/email or another project's messages without explicit authorization. Keep one writer per path while replies are pending. If delegation is unavailable, disclose sequential execution and preserve the same ownership boundaries.

Transfer context and wait for acceptance​

handoff-create captures a task's current owner/revision, destination role/harness, context, evidence, remaining work, memory references and a fresh-context prompt. It records Git root, HEAD, branch and dirty state read-only. Unknown Git fields stay unknown; dirty state is not a patch, and the packet copies no files. Make artifacts reachable through an authorized checkout or file transfer separately.

The source keeps ownership until the exact destination calls handoff-accept with the generated packet ID and current state revision. Acceptance commits the receipt and ownership change together. A running source task becomes pending; the destination starts it separately after dependencies complete. Native source work must stop before the destination edits. Acceptance does not stop a process, resume a portable session, grant permissions or prove completion.

A state revision conflict requires a fresh status read. If the task owner, harness or revision changed after packet creation, the packet is stale: inspect both records and create a new packet from current context. Do not patch historical packets or replay an accepted receipt after later task changes. Duplicate acceptance is a no-op only while ownership/harness/task revision still match the accepted snapshot, with the current state revision supplied. Cancelled and completed tasks remain terminal. Administrative reassign changes ownership immediately and carries none of this acceptance handshake.

The two-role request sequence creates an implementer and reviewer, completes coherent production and its local integration evidence, then transfers a separate dependent review task from Codex to Claude Code. It shows every revision through acceptance, start and completion. Mini has the same local handoff sequence with mini paths. These are request examples, not recorded successful native runs.

For UAR, include exact workspace/package/definition identities and digests, private binding revision and migration receipt references. Context transfer does not mutate immutable definitions, install bindings or carry credentials, RepresentationGrants or consent. The draft.2 taskAcceptance schema remains separate from this local handoff receipt and unsupported durable activation.

Route requests to another project​

First identify the actual repository, project ID, selected team and intake role. A similarly named team or shared directory is not the same repository. Ask the owner for authorization before messaging or writing another project; a card, issue, request packet or ownership glob provides discovery, not permission.

Full currently ships team-publish, team-discover, team-request and team-intake. A reviewed team.card records repository, component, owned paths, capabilities, intake role, label and routing rules. Cards publish to a local registry (optionally pk); discovery ranks capability/path matches, not verified availability. Repository equality is a literal card/request string comparison, not a remote identity proof. Inspect stale or ambiguous cards before selecting a target. The full request examples show explicit publication, discovery and an issue-route preview.

RouteShipped behavior and boundary
Full, same repository, no forcing ruleAdds a pending intake task and handoff-format context record to the target team's local state. It does not transfer an existing source task or obtain destination acceptance.
Full, another repository or matching issue ruleExplicit team-request invokes gh to create the team label and issue. Requires authorized GitHub access. It creates no remote worker or accepted task.
Full issue intakeExplicit team-intake imports up to 200 open labelled issues into pending issue-<number> tasks for triage. ack: true comments only on newly imported issues; import/ack is not acceptance.
MiniDoes not ship card/discovery/request/intake commands. Deliver reviewed context manually through an authorized native/file/issue channel; the destination creates its own local task and canonical identity.

For the issue route, dryRun: true returns the packet/quoted command without a GitHub write; missing gh also returns a manual command. dryRun does not suppress the same-repository local route. A live request must be explicitly authorized, including label/issue writes. This is invoked issue creation and intake, not a background GitHub automation or cross-project executor.

Save source repository/team/role, target repository/team/intake role, task/packet IDs, issue URL, local events and owner acknowledgement as correlation evidence. Same-repository requests derive req-<hash> from source identity/title/context; repeats reuse that task, so changes to other fields do not update it. Issue creation has no durable request-deduplication receipt. If it times out or the result is lost, inspect labelled issues before retrying. Intake deduplicates within its target state by issue number; a failed acknowledgement needs separate reconciliation. A request becoming a pending intake task still needs owner triage, canonical claims and an explicit start. Local handoff is never automatic cross-repository ownership transfer.

Keep lessons scoped to their audience​

Use the memory tiers guide for operational details and the team-aware memory design for identity, addressing and promotion. The table describes full's current learning writer and recall scopes; these are routing/filter conventions, not a server authorization guarantee.

VisibilityIntended audience
agentAuthoring team role; default when that role resolves
role:<id>Explicitly addressed role in the same team
leadTeam lead scope
teamShared team scope and digest
projectShared project scope; default when no role resolves
userUser-wide promoted knowledge across projects
globalExplicitly promoted knowledge usable across projects

Full resolves project/team/role from the project resolver, selected manifest and native role/path evidence. Path ownership can address a role-private lesson to other owners: at most three recipients; more matches or no matching owner route to the lead. Paths owned only by the author keep the lesson private. A team digest contains author, paths and content hash, without lesson text. Review filenames and metadata before sharing too; even a digest can disclose project information.

Full's SubagentStart recalls the role's own/addressed lessons plus allowed shared scopes, within 8,000 characters on Claude or an estimated 2,000-token Codex budget. Claude's team SessionStart receives lead scope and team digest. Codex's current source calls digest-only recall before merging: local digest candidates only, without REST, pk, file lessons or knowledge-gap retrieval. A final guard checks digest kind/channel and the selected team's digest scope. Parent history may be forked into child roles, so this prevents shared lesson text from replacing its digest during merge. Packaged-hook acceptance remains a separate final gate. Do not paste a private lesson into the parent or a shared handoff to bypass that boundary. Delivery is fenced untrusted information, not instructions; absent teams/roles/stores can yield no context. Inspect actual delivery when required.

Lookup priority is surreal-memory MCP, then pk/knowledge tools, then the scoped learning log and small project index. Query the current project/role rather than reading an entire private store. Cortex is not a lookup fallback. Keep role lessons private by default; use explicit authorized addressing and approved promotion. Detectors propose broader promotion for human confirmation; the lead or reflector may promote within the team. [USER] and [GLOBAL] final-message markers promote immediately in full's hook, so use them only when intended.

Full writes through shared/scripts/lib/learning_write.py; SubagentStop recognizes LESSON:, GOTCHA:, DECISION:, [USER] and [GLOBAL]. Queue success and log records are durable local evidence, not proof of remote recall. Optional --pk starts separate ingestion. The writer's optional Cortex mirror is bounded by feeder slots and a finite deadline; saturation/absence can skip it. Its accepted status means feeder input accepted, not server storage. See the memory tiers guide for exact outcomes, configuration and scratch-only verification.

Mini keeps Node-only delivery: its Claude SubagentStart reads the role's local MEMORY.md and digest file under an 8,000-character fence. It does not ship full's Python writer, scoped store recall, Codex digest SessionStart or Cortex feeder. Its corrected Node outbox source uses canonical /api/v1/memory, derived team/project scope keys and a learning-envelope trailer. It needs an explicit or selected project identity, keeps missing-identity entries queued without network I/O, and preserves recorded legacy attempt fingerprints for deliberate reconciliation. This does not add full's hook recall or privacy guarantees. Compiled payload regeneration and production integration remain deferred. Neither pack requires a memory service for local handoffs.

Keep secrets, personal data and portable session credentials out of packets, lesson content, provenance and digest paths. Scope labels and source receipts do not prove access control. A memory reference is a pointer; it transfers neither private lesson content nor permission to retrieve it.

Choose a model for the task​

KBD planning chooses demonstrated task fit first, within user selections, project policy and budget; cost and latency break close ties. The team's models-select helper instead filters declared constraints and then orders eligible candidates by lowest known input-plus-output price, with exact ID as its tie-break. Use that helper to explain constraints, not to replace the KBD quality-first decision or infer a permanent model ranking.

Record reasoning difficulty, uncertainty, tools, context/output size, vision or other modalities and review independence before choosing. low, medium and hard are declared tiers; they are neither benchmark scores nor native reasoning effort. A tier matches exactly. Document unsupported or unknown requirements; a role title, model name or catalog listing does not prove suitability.

EvidenceWhat it establishes
Catalog or operator declarationCandidate identity and declared metadata
Configured discovery responseEndpoint-listed eligibility at that time
Native schema/config inspectionAn exposed control, not an applied session
Successful inferenceThat request reached a working inference route; retain actual identity when available
Tool-enabled worker resultActual workspace/tool execution under the recorded route
Independent review/integrationOnly the specific boundary and evidence actually exercised

Both packs use models-discover and models-select through the creator runtime. Local declared-catalog comparison needs Node.js 22+ only. Live discovery needs an explicit compatible gateway or service endpoint and authorized credentials by environment reference. Neither command starts a model service, runs inference or launches a worker. liter-llm supplies inference; an existing documented worker with tools supplies execution. An alias that reaches a generic proxy is not proof that the requested provider/model answered.

Inspect effective policy before binding​

Portable policy allows only model, tier, capabilities, maxInputPerMillion and maxOutputPerMillion. It resolves in this order:

  1. Team modelPolicy.
  2. Selected role modelPolicy.
  3. skillPolicies for the explicitly supplied skills, in their supplied order.
  4. Explicit taskPolicy passed to selection.

Later scalar values replace earlier values; capabilities accumulate and every required capability must be explicitly true. Empty task capabilities do not clear team requirements. Missing capability/availability evidence fails that constraint. Skill selection does not read arbitrary skill frontmatter or silently use every role skill; the caller supplies the ordered list.

There is no portable reasoningEffort, contextWindow, total-dollar budget or fallback field. Keep those requirements and approved fallback decisions in the plan/native configuration. Unknown keys fail validation. Context sufficiency must be checked against the actual model/version and effective native limits; adding a reasoning capability does not set effort or guarantee context size.

Inspect selected, effective policy, appliedLayers, rejected and warnings. The helper returns no match when constraints cannot be established. It does not mutate state or configure an agent. The full executable selection and persistence example and mini equivalent show declared metadata, layered policy, an unknown-price failure and a reviewed state update. Example declarations are not measurements or native acceptance.

Native export uses the explicit role model, otherwise the team model. It does not execute the skill/task selector for each export. Persist the reviewed concrete result in a role/team policy, or carry task-specific policy to the actual invocation and assignment record. A task may retain modelPolicy when added, but that does not switch its process. Role native overrides can replace exported model fields; inspect the proposed artifact and actual worker result.

Reasoning and native harness limits​

Read current primary documentation and inspect the installed version/tool schema before applying a selected model. These controls are native and have different names and inheritance rules:

HarnessModel and reasoning boundary
CodexRole config supports model and model_reasoning_effort when exposed by the installed version. Fresh-agent override availability comes from the current tool schema; full-history forks may inherit and reject overrides. Only exposed supported IDs/efforts are usable.
Claude CodeSubagent model accepts supported aliases, full IDs or inherit; invocation/provider/organization settings can affect the result. Reasoning/effort controls are version/model dependent. Inspect the actual running model, not an alias alone.
OpenCodeConfigured providerID/modelID identifies the native model. Per-agent model and model-specific options/variants are distinct controls; an inherited variant is not guaranteed after selecting a different agent model.
Kimi CodeRole model frontmatter is ignored. Use verified invocation/global model-pool controls separately; do not invent per-role effort/model switches.
DeepSeek HarnessCurrent persona/experimental team export does not select models per member. Global provider/model settings do not prove distinct member routing, remote workers or worktree isolation.

Sources: Codex role overrides, Claude subagents, OpenCode models and agent configuration, Kimi agent fields, DeepSeek experimental team contract. Upstream docs establish supported contract shapes; they do not certify the installed native tools. Report unresolved routes explicitly.

For a Codex role, native.codex.model_reasoning_effort can preserve a reviewed native setting alongside its explicit model. That opaque preservation is not a universal effort field or proof the model accepts it. Claude's alias inheritance and OpenCode's provider variants similarly need actual version-specific review. Moving a task across harnesses requires a fresh model/permission/context check, not reuse of an incompatible native field.

Budget, fallback and independent review​

Prices are USD per million text tokens in the helper. liter-llm catalog prices start per token and are multiplied by 1,000,000; the adapter uses the maximum base/context-tier rate, leaving a side unknown if any relevant tier rate is unknown. Missing prices cannot satisfy a ceiling. Stale or unknown freshness produces warnings, not an automatic refreshed rate or guaranteed bill.

Rate ceilings do not cap total spend. Include expected input/output volume, reasoning usage, tool retries, review, concurrency and provider extras when estimating a budget. The helper's price sum assumes no workload token mix; it is a deterministic comparison, not the cost of this task. Context, cache, audio/image, subscription rules and future charges need their own evidence.

If a route fails or no model qualifies, record the reason and leave it unresolved. The runtime has no automatic fallback chain. Re-select only through an explicit recorded decision that respects the user's constraints; a listed native alternative is not permission to substitute silently. Preserve previous attempt/route evidence, reconsider tools/context and prices, and record the actual model after the new worker responds. Other eligible work may continue.

Independent review needs a separate context and the required model independence. This repository's KBD rule requires a critic outside the producer's family; a different alias, reasoning setting or same-family model is not a substitute. Record producer and critic identity plus the serving route. An alias comparison or verified-distinct name result alone does not prove underlying family independence through a proxy. If the eligible reviewer is unavailable, leave the review pending until a valid route or explicitly authorized exception exists. All integration/review work waits for complete phase production.

Persist canonical task assignments and actual routes​

The KBD assignment key is full phase path + change ID + exact backend task ID. Retain canonical project/run identity too. Task model assignments is authored plan prose, not a new task schema or launcher. Reconcile split/changed tasks and record provider/model, supported effort, dated rationale, native/worker route, working directory/ownership, actual availability, alternative and prerequisites. The driver owns canonical start/end; worker results return as evidence.

For cross-project requests, source model preferences are context, not destination policy. The target coordinator triages scope, selects against its own configured models/budget/tools and records its own canonical task assignment. A team card, issue or UAR direct-task schema policy does not bind a remote model or authorize its inference. Revalidate on acceptance or cross-harness transfer; keep actual source and destination routes distinct in receipts.

See task model assignments for the scoped table and execution record. Planning, configured access, source implementation, regenerated payloads, actual execution and final acceptance are separate evidence states. Neither this handbook nor an export claims a live run.