Agent 0 and Subagents

Agent 0 and subagents

Agent 0 is the coordinator recorded as agent.0. It can perform all work in a solo workflow or coordinate approved workers in an environment that supports delegation.

Start with Daily workflow for a solo task, or copy the Agent 0 prompt to explicitly request delegation. The shipped default is a coordinator role and blank records; it is not a prestarted agent team.

For an illustrated walkthrough, use Subagent processing. It traces the actual harness calls, record ownership, review gates, and recovery paths. Advanced use cases shows when to use that workflow.

Connect the folder to your harness

An AI harness is the app, CLI, or IDE integration that runs the assistant and provides tools. .SYSTEMX holds the project's operating instructions and saved state. Connect the two deliberately:

1. Open the intended project and verify its canonical .SYSTEMX directory.
2. Follow its selected START-HERE.md. In a managed installation, read INSTALLATION.json to locate the selected cached defaults; keep project records in the outer .SYSTEMX directory.
3. Merge the supplied agent entry-point template into the host repository's root AGENTS.md or the harness's equivalent if needed. Preserve existing instructions and record this manual integration. The installer does not add a root instruction file automatically.
4. Ask the assistant to identify the instructions, selected version, project record paths, current objective, and next task it actually loaded.
5. Authorize subagents for the task when useful, and check the harness's actual delegation capability, remaining capacity, and project permissions.

Do not assume .SYSTEMX/AGENTS.md alone governs code elsewhere in the project. Codex loads project instructions according to its directory and discovery rules; see its official AGENTS.md guide. Other assistants have their own discovery mechanisms.

With subagent support available, Codex can launch workers through its delegation tools and display their activity in supported clients. Inspect those live agent threads and returned results to establish what actually ran. Client behavior and limits depend on the installed version and configuration; consult the official subagent guide. If delegation is unavailable, Agent 0 can perform the same scoped work serially.

Interpret “up to 10 subagents”

The example prompt requests up to ten concurrently active subagents across its delegation tree, in addition to Agent 0. This is a ceiling chosen by that prompt, not a template setting or a requirement to launch ten. Use fewer when appropriate, count nested workers, and obey lower harness limits. The ten-task limit in current focus is unrelated to worker concurrency.

Choose independent assignments that justify the coordination cost. Reuse a suitable worker when its scope still fits. Dependent steps and contested writes need serial ownership. More workers consume additional model and tool resources; compare accepted outcomes using Tokens, cost, and time.

Responsibilities

Responsibility	Agent 0	Subagent
Master plan and shared priorities	Maintains the accepted plan	Proposes relevant changes
Task ownership and dependencies	Assigns and coordinates	Works within its assignment
File changes	Coordinates integration and shared-file ownership	Changes files within its assigned scope
Memory	Reviews and promotes verified shared facts	Maintains its own scoped checkpoint
Acceptance	Reviews evidence and records completion	Submits findings, changes, and evidence

The registry is a record of roles. It is not a process supervisor, authentication system, or permission grant. Your chosen agent tool starts workers, delivers instructions, and reports their actual runtime state.

Agent 0 is a role, not a required model name or provider. Each harness may use different runtime agent identifiers. Keep a mapping from task ID and .SYSTEMX agent ID to the live job/thread handle in the coordinator checkpoint, with the observed revision, owned resources, status, and next action. Do not add invented fields to the canonical JSON schemas to store that mapping.

Register a worker

bash .SYSTEMX/SYSTEMX.sh agent-add agent.1 --role test

These shell examples use the folder's launcher. For a managed installation, prefer systemx run --target "/path/to/project" --offline -- COMMAND to use the selected defaults explicitly; for example, replace COMMAND with agent-add agent.1 --role test. Registering the role still does not launch it.

This creates a registry entry and .SYSTEMX/AGENTS/agent.1/MEMORY.md. Repeating the command for an existing agent fails without overwriting its notes.

Use stable IDs such as agent.1 and agent.2. Choose a role that describes the assignment: for example, code, research, test, docs, or review. Register only workers the project needs.

Assign a bounded task

bash .SYSTEMX/SYSTEMX.sh task-add \
  --title 'Verify the changed behavior' \
  --owner agent.1 \
  --scope 'tests/' \
  --acceptance 'A focused regression check demonstrates the expected behavior' \
  --next 'Inspect the existing test and affected code'

Agent 0 also supplies the relevant repository instructions, constraints, dependencies, allowed tools, and stop conditions through the agent environment. The task's scope field records intended boundaries; it is not a filesystem sandbox. Use task-ready to discover dependency-ready TODO work and task-packet to prepare bounded context from an existing record. Verify the reported base revision, concrete requirement or failure, exact file scope, permitted actions, required evidence, and stop condition. Reuse suitable existing workers and choose work based on dependencies; this standard prescribes no provider, model, or worker count.

Load worker context

bash .SYSTEMX/SYSTEMX.sh context --agent agent.1
bash .SYSTEMX/SYSTEMX.sh task-show TASK-001

The context packet includes current focus, shared context, the master plan, project memory, that worker's notes, and a summary of its open tasks. It does not preload other workers' memory or the entire session archive. Use task-show to read full acceptance criteria and dependency IDs, then inspect those dependency records as needed.

Dispatch, routing, and logs

After preparing a packet, Agent 0 sends it through the harness's real delegation tool. Record in_progress when work actually starts, rather than when a role is merely registered. Collect progress and terminal results through the returned job handle. In the return report, require the task ID, scope, changed artifacts, checks and evidence, limitations, and exact next action.

Record	How it is maintained	What it proves
Task state and history	Agent 0 uses the ledger commands; status pages regenerate	Recorded assignments, transitions, and review references
Worker memory and reports	Workers save scoped notes and evidence references	What that worker observed and handed off
Project checkpoint and memory	Agent 0 records the handoff and promotes reviewed facts	Accepted project knowledge and a resume point
Harness job/thread state	The host exposes running jobs and results	Observed execution state in that harness
Installation operation receipts	Manager operations write local receipts	Install/update/removal activity, not every development action

.SYSTEMX does not automatically copy every chat, tool call, or worker response into memory. The assistant must write relevant records and verify the write. Optional message envelopes can help an integration route reports, but the template includes no message bus or agent supervisor. Task truth stays in the canonical ledger. Keep secrets and unnecessary transcripts out of saved packets.

Review and integration

The worker returns changed artifacts, check results, evidence references, limitations, and its exact next action. Agent 0 records needs_review, inspects the result, resolves integration conflicts, and records done only when the acceptance criteria are satisfied.

Workers propose changes to shared context and project memory. Agent 0 reviews and applies those changes. Coordinate shared-file writes explicitly; the local task-ledger lock does not prevent two workers from editing application files. Also assign ownership of shared test databases, compilers, browser sessions, installers, and deployment targets. Retain live job handles and reconcile their terminal results before starting conflicting replacement work. Run relevant combined checks after integration; repeat after a relevant change or failure. The portable .SYSTEMX/templates/WORKER-REPORT.md provides a compact report format.

Session continuity

Each worker updates its own memory before a handoff or context loss. Agent 0 maintains the project resume checkpoint. Follow Planning and memory to distinguish verified facts, hypotheses, and historical observations.

Only agent.0 or user can be recorded by the CLI as a completion reviewer. That convention checks record consistency; it does not authenticate the person or process entering the value. External-action and release authority remain governed by the project's actual policies.

Standard specialist roles: Agent X, Agent Y, and Agent Z

Agent X, ID agent.x, owns event/time tracking and due-item bookkeeping. Agent Y, ID agent.y, owns an optional, bounded external CLI task channel and its Git branch/draft-PR handoff. Agent Z, ID agent.z, owns a repeatable 100-question evidence review. They support the coordinator and never become a second source of task state or external authority.

Preview roles-init, then use roles-init --apply in the selected root or child scope. The operation registers the reserved event-time, cli-worker, and review roles. It creates blank memory and records without replacing existing files. The public seed registry remains Agent 0 only for compatibility with older managed launchers. X/Y/Z are named standard roles, not numeric subagent slots or automatic workers.

With these roles enabled, use Agent X for meaningful observed events and due items. At a task's needs_review boundary, use Agent Z once against its original acceptance and exact source/evidence revision; reuse a matching report. An initial prompt or intermediate artifact can be reviewed on request. Questions remain fixed for the policy version, even when some are unknown or justified N/A. Agent 0 reviews the scorecard, resolves required gaps, and records acceptance. Further work or repeated checks need changed inputs or a concrete unresolved concern. A score difference alone does not authorize another build/test loop.

When Agent 0 delegates to an external CLI, select the provider for that task and give Agent Y the exact repo, base revision, permitted files, task packet, and PR authority. The app's own subagents and Agent Y's CLI channel are separate execution paths. Agent Y can open a draft PR only after a successful run and explicit opt-in; Agent 0 still reviews the returned evidence and decides task acceptance. Making a draft PR ready, closing an abandoned PR, merging, and branch cleanup have different effects and must not be inferred from a score or CLI exit code. See Agent Y for the full lifecycle.

Coordinate phases and multiple threads

The one-shot project guide shows how a researched brief becomes milestones, task dependencies, and bounded execution waves. Agent X records time/evidence, Agent Y can route a bounded task through an authorized external CLI/PR channel, and Agent Z performs a fixed-policy review at a boundary. Registering roles does not expand the session's worker limit.

Multiple threads and worktrees need a shared base revision, disjoint write scopes, and one canonical integration owner. Follow shared workspace convergence; separate copies of .SYSTEMX do not synchronize themselves.

Read the complete four-role map

The updated full-system infographic shows both execution paths beneath Agent 0: app-native bounded workers and an optional Agent Y task-selected CLI/worktree. X records their observed events; Z reviews matching evidence; Agent 0/user accepts against the original criteria. A draft PR is a review handoff. Accepted readiness, cancellation closure with retained work, and archive-first cleanup after external merge are separate transitions. These roles share one project budget and do not create extra default workers.

Tier 2 specialist requests

Agent 0 can ask Agent Alpha (agent.a) for the smallest relevant AUTOBOT detail packet. The ten specialist files are document roles, separate from numeric subagents and the X/Y/Z activation. Agent Alpha routes selected detail; Agent 0 still owns task selection, the Master Plan, integration, acceptance, shared-file ownership, and the project's worker budget. A task packet should name the specialist revision/result and original evidence, not imply that another LLM inherited hidden context. Reuse unchanged completed requests, and create new work only for a relevant changed input or concrete gap.

ROOT requests and cross-surface task delta

Use optional ROOT planning when a request needs structural milestones/waves/phases or several harness/bot task lists. Agent 0 keeps the originating RTask stable, bounds delegated STasks, selects ready work, and reconciles observed mappings to existing TASK-... IDs. The planning structure carries no second task status and does not require fixed counts. Update the correct surface under the existing authority, retain readback evidence, and checkpoint unresolved delta. No ROOT record starts a worker, expands the concurrency budget, or accepts work on a provider's completion.