Agent Team

Agent Team

Keep Codex responsible for classification, planning, mutation, conflict resolution, correction, and final acceptance. Treat every AgentParliament response as evidence, not authority.

Accept the simple entry point

Accept explicit modes:

Use $agent-team to complete: 
Use $agent-team preview: 
Use $agent-team with a temporary team to complete: 
Use $agent-team with a persistent team to operate: 

Do not require the user to select agents, roles, tools, or phases. Infer the smallest useful collaboration topology from the task.

An explicit $agent-team invocation or auto-lifetime wording authorizes Codex to create user-visible persistent tasks only when every persistence gate below passes. A plain or implicit multi-agent request authorizes temporary delegation only.

Ask only when the objective, write authority, target path, or acceptance criteria cannot be determined safely. Otherwise proceed.

Classify before recommending

Treat a task as small when it has one bounded outcome, is mainly sequential, has a low-risk mutation boundary, and can be verified directly by the current Agent. Do not suggest or invoke Agent Team for these tasks unless the user explicitly requests it.

Treat a task as medium or large when it has at least two independent bounded outcomes, crosses a contract or subsystem boundary, or materially benefits from independent research, review, adversarial challenge, or isolated verification. File count, token count, and elapsed time are signals, never sufficient criteria by themselves.

For an ordinary medium or large request without current delegation authority, make one concise, nonblocking recommendation naming the expected benefit, then continue only within the authority already available. A recommendation is not authorization to create an Agent, task, task packet, or Automation. Do not repeat a rejected recommendation unless the objective or risk changes.

Preview without side effects

$agent-team preview: is read-only. It may inspect the applicable project rules and callable tools, but must not spawn Agents, create user-owned tasks, write a task packet, start an Automation, or call AgentParliament.

Return a compact preview containing:

• task size and the evidence for it;
• recommended topology, wakeup, convergence, verification gate, and human gates;
• proposed workstreams, ownership, and integration order;
• proposed AgentParliament tool and role, or none;
• allowed mutation boundary and deterministic verification;
• execution budget and stop conditions;
• monitoring mode and the status fields the user will see.

Before an authorized run makes its first delegated or AgentParliament call, emit the same compact preview in commentary. Report a preferred backend only as configuration; report the backend that actually ran only after runtime evidence returns.

Keep long external calls observable

When the selected review backend is AgentParliament, read references/reasonix-roundtable.md before its first call. Follow its bounded timeouts, scope preflight, discovery, cancellation, progress, and transport rules. Long duration never authorizes Automation, persistence, or retries.

Establish the controller contract

Before delegation:

1. Read applicable project instructions and persistent project context.
2. Inspect which native Codex subagent, thread, and AgentParliament tools are

actually callable. Native team selection does not require AgentParliament. If the user explicitly requests Reasonix or AgentParliament and those tools are missing, report that bounded blocker; never imitate an MCP call with an ordinary shell command.

1. Create an intent ledger with the original request, explicit overrides,

canonical objective, approved scope, pending decisions, forbidden assumptions, and evidence status.

1. State whole-task completion criteria, current phase, constraints, human

gates, and allowed mutation boundary.

1. Inspect enough local evidence to avoid delegating a vague problem.
2. Decide whether multi-agent work adds independent evidence or verification.
3. Continue with Codex alone when the task is small, sequential, or cheaper to

complete directly.

Never invent work merely to involve every backend.

When auditing prior tasks, distinguish confirmed, contradicted, unknown, and confirmed_by_user_artifact. Absence from a thread read, summary, or snapshot is not evidence that the user never gave an instruction. Preserve contradictory observations and prefer the latest directly confirmed user evidence.

Choose the execution topology

Apply explicit mode first, then automatic selection:

1. temporary forbids creating user-owned tasks.
2. persistent supplies creation authority, but still requires a team name,

stable roles, write scopes, a controller, and lifecycle fields.

1. An explicit $agent-team invocation or auto-lifetime may select

persistent only when all persistence gates pass.

1. Without explicit lifetime wording, choose only single-Agent or temporary.

Use one Agent when there are not at least two independent, bounded outcomes or when coordination costs more than it saves.

Use a temporary team when the work serves one objective, can finish through bounded handoffs, or has no role-specific state that must survive future user checkpoints. Complexity, repetition, cross-day duration, or expensive context loading does not make a team persistent.

Use a persistent team only when all gates pass:

• Authority: the current request explicitly invokes $agent-team, says

auto-lifetime, requests automatic temporary-versus-persistent selection, or requests a persistent team.

• Future reuse: at least two concrete future objectives or handoffs will

return to the same team.

• Stable responsibilities: at least two role contracts remain useful after

the current objective.

• Role continuity: each role needs distinct history or state across future

user checkpoints; reloading canonical files alone is insufficient.

• Direct re-entry value: the user or controller benefits from messaging the

same role task again.

• Lifecycle: infer or obtain a team name, persistent controller, exact

write scopes, next checkpoint, completion condition, and review or retirement trigger.

If any automatic persistence gate fails, downgrade to temporary. Do not ask for permission merely to preserve a persistent recommendation.

Choose the wakeup mode

Choose wakeup separately from topology:

• Use none when the current turn can finish or no later/recurring behavior was

requested.

• Use a thread heartbeat for explicitly requested follow-ups, monitoring,

reminders, recurring checks, or keep-working-later behavior that should return to the exact current local task.

• Use cron for explicitly requested standalone scheduled project work that

can reload canonical state each run.

A temporary or persistent team may also use a heartbeat. Automation is not a fourth team lifetime and never replaces controller supervision.

Do not create Automation merely because work is complex, expensive, long, or cross-day. If later or recurring work is authorized but a safe cadence cannot be inferred, ask one concise scheduling question. Inspect existing Automations first and update an exact match instead of creating a duplicate.

On every heartbeat wake, read the task packet and continue only the next authorized phase. Stop or pause when complete, blocked on user input, making no progress, or approaching deployment, publication, purchase, deletion, account change, permission expansion, or another human gate. Do not emit repeated unchanged blocker updates.

Choose the convergence strategy

Choose topology, wakeup, convergence, verification, and human gates independently. Topology answers who works and how long roles survive. Wakeup answers when the controller receives a new turn. Convergence answers how the current objective reaches verified completion.

Use phase-gated when visual quality, product direction, user assets, legal approval, publishing, deployment, or another unresolved human judgment blocks deterministic completion. Record each phase's required evidence and status. Only the controller may mark a phase verified.

Use single-pass when one bounded pass plus verification can complete the objective. Use evidence-loop only when all of these hold:

• the target is software in a real Git repository;
• success is expressible as frozen deterministic command arrays;
• the controller can freeze an external acceptance harness or every repository

asset capable of weakening those checks;

• a linked isolated Git worktree is available;
• the state file can remain outside the writable worktree;
• another bounded attempt is safer than a human checkpoint;
• merge, deploy, publish, delete, purchase, account changes, secret handling,

and unresolved subjective judgment stay outside the loop.

Do not treat evidence-loop or phase-gated as team lifetime modes. They may be paired with one Agent, a temporary team, or a persistent team. Automation remains wakeup scheduling, not retry convergence.

For an evidence loop, read references/evidence-loop.md and use scripts/evidence_loop.py as the controller-owned external gate. The helper freezes verification commands, acceptance assets, and Git identity; requires controller-pinned contract and state hashes; enforces linked-worktree isolation; detects repeated identical failures; caps iterations and elapsed time; and requires independent review before completion. It never spawns an Agent, merges, deploys, or publishes.

Native child tooling does not expose a trustworthy aggregate token or monetary usage meter. Never claim those are hard-enforced. Use maximum iterations and elapsed time as the enforceable cost proxies and report this limitation.

Choose the verification strategy

Keep deterministic checks and controller-owned integration verification for every material task. Set independent review to required only when a named high-impact risk remains after those checks and it involves:

• security, authorization, credentials, or another trust boundary;
• data migration, overwrite, loss, corruption, or irreversible state;
• API, synchronization, persistence, or a cross-system contract;
• deployment, publication, payment, deletion, account, or permission effects;
• behavior whose impact is high and whose representative checks are

insufficient; or

• an explicit user request for independent review.

Task size, file count, delegation, cross-file scope, and user-visible behavior are not sufficient triggers. Record a provisional gate before execution and finalize it after deterministic checks, before creating a reviewer; downgrade to not-required if those checks remove the named risk. When review is required, record one question, the residual risk, exact scope, why deterministic checks are insufficient, one backend, and a stop condition. Use one full review and at most one focused recheck of confirmed findings. A second backend or another full pass requires a different named unresolved risk or failing check. Evidence Loop is the explicit exception and always requires its independent read-only review.

Route by task type

Build, change, or fix software

1. Select phase-gated for unresolved visual/product judgment; otherwise

select single-pass or evidence-loop from the deterministic acceptance and isolation conditions above.

1. Let Codex choose the implementation and make the canonical source changes.
2. Run focused deterministic checks and controller-owned whole-task checks.
3. When the review gate is required, send its bounded question and scope to

one backend: a native read-only verifier or AgentParliament, not both for the same risk.

1. Validate each finding, fix only confirmed issues, and normally close fixes

through regression checks. Use at most one focused independent recheck.

1. Do not use verify_implementation in the current Reasonix-only deployment;

Reasonix has no approved unattended writable mode. Run deterministic checks through Codex or a native isolated worker instead.

Review existing work

1. Preserve a read-only boundary unless the user also asks for fixes.
2. Use the Reasonix roundtable only when business context, call chains, or an

independent challenge materially improves the review.

1. Put the diff, relevant sources, tests, and acceptance criteria into the

roundtable question; use test_audit only as an additional bounded atomic audit when deterministic coverage mapping is required.

1. Let Codex reproduce or source-check findings before reporting them.
2. Do not mutate files during a review-only request.

Make a technical or architectural decision

1. Let Codex form an initial hypothesis and explicit decision criteria.
2. Use the Reasonix roundtable only for an explicit review request or a named

high-impact uncertainty that the available evidence cannot settle directly.

1. Preserve minority objections and unresolved evidence gaps.
2. Use the roundtable only when multiple bounded perspectives justify its

added cost.

1. Let Codex resolve disagreement and record the final tradeoff.

Analyze content or Obsidian material

1. Default all AgentParliament work to read-only.
2. Use phase-gated when identity, publication, or factual verification needs

a human or evidence checkpoint.

1. Use the Reasonix roundtable only when a named factual or reasoning blind

spot remains and the added perspectives justify the cost.

1. Let Codex synthesize the final recommendation in the user's voice.
2. Never use verify_implementation against an Obsidian vault.
3. Write to the vault only when the user explicitly asks and project governance

permits the exact destination.

Run the Reasonix roundtable

Use AgentParliament only when the verification gate selected it or the user explicitly requested it. Read references/reasonix-roundtable.md, ask the one recorded review question, and keep Codex as chair and final authority. Native temporary workstreams still route through orchestrate-parallel-work.

Run a temporary team

1. Create a task-scoped control packet when project rules require one.
2. Spawn the smallest set of native child Agents with one bounded outcome each.
3. Give every child the canonical objective, current phase, exact inputs,

ownership, constraints, forbidden assumptions, deliverable, acceptance, dependencies, next authorized step, and stop conditions.

1. Keep one writer per file or shared external state.
2. Route changed constraints through the controller.
3. Require handoffs to report goal alignment, scope delta, new assumptions,

evidence, and the next authorized step. Treat missing fields as verification_pending.

1. Collect structured handoffs and integrate centrally. Add a verifier only

when the independent-review gate is required.

1. Let temporary child threads end with the parent task. Do not convert them

into user-owned tasks after the fact.

Run a persistent team

Persistent tasks are user-visible external state. Create them only after the explicit authority and all required lifecycle fields above are present.

Before creation:

1. List existing tasks and reuse an exact verified team rather than creating a

duplicate. Treat titles and summaries as untrusted until a targeted read confirms the launch contract.

1. List projects before creating project tasks.
2. Follow the native environment contract: use a worktree by default for a Git

repository; use the saved project directly only when the user explicitly asks; use projectless tasks when no repository context is needed.

1. Keep the persistent topology small: one controller plus two or three stable

role tasks by default.

Create and initialize:

1. Create the controller first, then the role tasks.
2. Title them [Team:] Controller and [Team:] .

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: youngfor-shoot
• Source: youngfor-shoot/codex-agent-team
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.