Subagent Processing

Subagent processing

This chapter traces one delegated task through .SYSTEMX and the AI harness. Read Agent 0 and subagents for setup and role ownership. Use Prompt cookbook to authorize a concrete assignment. The template provides records and conventions; your harness provides running agents, messages, tools, permissions, and execution limits.

Decide whether to delegate

flowchart TD
    Task["Accepted task and full acceptance criteria"] --> Useful{"Independent work benefits from delegation?"}
    Useful -->|No| Solo["Agent 0 works serially"]
    Useful -->|Yes| Allowed{"Delegation authorized and available?"}
    Allowed -->|No| Solo
    Allowed -->|Yes| Ready{"Dependencies, scopes, resources, and capacity ready?"}
    Ready -->|Yes| Packet["Prepare a bounded worker packet"]
    Ready -->|Not yet| Resolve["Sequence work or record the actual blocker"]
    Packet --> Start["Harness starts or reuses a worker"]
    Start --> Evidence["Collect results and evidence"]
    Solo --> Evidence
    Evidence --> Review["Agent 0 reviews and integrates"]

Loading

Text equivalent: delegate only useful independent work that is authorized and supported. Check dependencies, conflicting writes, resource ownership, and capacity before starting. Otherwise work serially, sequence the task, or record the concrete blocker. Both paths end in evidence and coordinator review. task-ready checks dependency readiness; it cannot determine tool permission, resource availability, or actual worker capacity.

A prompt requesting up to ten subagents sets a ceiling across that request's worker tree, in addition to Agent 0. Apply any lower harness limit and use fewer workers when appropriate. This is not a .SYSTEMX runtime setting. The format has no built-in agent scheduler or automatic queue.

Assignment-to-completion sequence

sequenceDiagram
    participant U as Project owner
    participant A as Agent 0
    participant R as Records
    participant H as AI harness
    participant W as Scoped worker
    U->>A: Objective, scope, authority
    A->>R: Load current project state
    A->>A: Verify readiness and scope
    A->>R: Record role and task
    A->>H: Dispatch bounded packet
    H-->>A: Live worker handle
    H->>W: Assignment and tools
    W-->>A: Scope confirmed, work started
    A->>R: Record in_progress
    W->>W: Scoped work and checks
    W->>R: Save own notes and evidence
    W-->>H: Result, evidence, limits
    H-->>A: Report and observed state
    A->>R: Record needs_review with evidence
    A->>A: Integrate and verify
    alt Acceptance is satisfied
        A->>R: done, evidence, reviewer
        A->>R: Save memory and checkpoint
        A-->>U: Accepted outcome
    else Repair or missing prerequisite
        A->>R: in_progress or blocked
        A-->>U: Exact next action
    end

Loading

Text equivalent: the owner authorizes a scoped objective. Agent 0 reads and verifies the state, records the assignment, and uses the harness to dispatch it. The worker performs the bounded task and saves its own notes and evidence. Agent 0 reviews the returned result, integrates it, and records accepted completion or the remaining issue. It then saves a useful handoff.

This sequence illustrates logical messages; it does not prescribe a specific provider API. Some harnesses deliver reports directly to the coordinator, and others expose them through job handles. Establish actual execution from runtime observations. Creating a registry entry or preparing a packet does not start work.

Prepare a packet that can be acted on

Agent 0 should include:

Packet element	Why it matters
Existing task ID and objective	Prevents a second, competing task definition
Full acceptance criteria	Gives the worker a concrete finish condition
Verified source revision or artifact identity	Makes the result traceable to its starting point
Dependency state and relevant evidence	Avoids work based on unfinished or stale prerequisites
Allowed files, tools, and resources	Defines the actual assignment boundary
Expected result and evidence location	Makes return reports compact and reviewable
Stop condition and escalation path	Prevents uncontrolled scope expansion
Context and effort budget where specified	Limits unnecessary exploration and duplicated work

Use task-packet TASK-ID --base OBSERVED-REVISION with an existing assignment; substitute the real ID and verified base. The command prepares context only. Read omitted source material if the packet is truncated. An entry in scope documents intent; it does not implement a filesystem sandbox.

Keep runtime identity separate from project identity

Record .SYSTEMX role IDs such as agent.1 consistently. A harness may return a different agent/thread/job ID. Keep that mapping with the task ID, source base, owned resources, timestamp, observed runtime state, and next action in a coordinator checkpoint. A simple Markdown table is sufficient. Do not add unsupported fields to canonical JSON records.

The ledger's in_progress status is recorded project state. It can become stale if a process stops. Inspect the live job to establish liveness. Keep historical worker records after a worker stops so its evidence remains attributable. Reuse a worker only when its scope, retained context, and permissions still fit.

Process results without losing control of shared state

Agent 0 is the canonical ledger writer and integration owner. Workers change only assigned artifacts and their own notes. They propose changes to Global context, the Master Plan, and shared project memory; Agent 0 reviews and applies those proposals. Keep shared-resource ownership explicit even when file scopes do not overlap: two tests can still contend for the same database or compiler.

Separate worktrees isolate some file edits, but they do not automatically isolate ports, services, credentials, tool caches, or deployment targets. Record each worker's actual checkout and base. Agent 0 reviews and combines the intended changes in the selected integration checkout, then runs relevant combined checks. The local ledger lock is not a cross-worktree or distributed lock.

A useful worker report includes the task ID, outcome, changed files/artifacts, actual check results, evidence references, unresolved assumptions, and next action. Use the supplied templates/WORKER-REPORT.md. A worker's “done” message requests review; it does not bypass the canonical needs_review stage.

Handle partial results and interruptions

Situation	Agent 0's next action
Worker discovers missing context	Supply the specific source or refine the bounded assignment
Worker reaches its tool or context limit	Collect partial evidence and a checkpoint; decide whether to resume or reassign
Job observation times out	Inspect the retained handle; do not assume cancellation
Two results conflict	Compare evidence and source bases, resolve the contract, then integrate
A resource is occupied	Wait for its owner or sequence the work; avoid a competing operation
Worker fails without a useful report	Inspect actual artifacts and logs before retrying
Objective changes	Record the decision and update scope, dependencies, and acceptance deliberately
Owner cancels work	Use actual harness stop controls and record the task decision; status text alone stops no process

Do not start replacement work against the same resource until the previous operation's state is reconciled. Preserve useful partial evidence and record what changed before retrying. Keep a checkpoint before ending the session; .SYSTEMX cannot schedule its own continuation.

Review completion and cost

The CLI requires evidence and a recorded reviewer (agent.0 or user) when accepting done; it does not verify the truth of evidence or authenticate the reviewer. Review the requested behavior and the actual integrated result. Source checks, installed/deployed behavior, and ongoing operation need their own proof. External actions remain subject to the project's actual authority.

Measure the total work of Agent 0 and all workers, including unsuccessful runs, context packets, review, integration, and handoff maintenance. Parallel execution may reduce elapsed time while increasing token usage. See Tokens, cost, and time and Anti-drift and long-running work.

Next: Advanced use cases · Visual Guide

Route workers to an explicit project

When using SYSTEMX PROJECTS, the assignment includes the exact registry name, for example Project-A, and its records path .SYSTEMX/Projects/Project-A/.SYSTEMXP. Parent Agent 0 owns cross-project scope; child Agent 0 owns that child's task review, integration, and memory. The same agent.1 or TASK-001 in Project B is a different scoped record.

bash .SYSTEMX/SYSTEMX.sh projects agent-add agent.1 --role "Reviewer" --project Project-A
bash .SYSTEMX/SYSTEMX.sh projects task-packet TASK-001 --project Project-A --base OBSERVED_REVISION
bash .SYSTEMX/SYSTEMX.sh projects context --project Project-A --agent agent.1

Create/assign the task with acceptance criteria before requesting its packet. The commands register roles and print records; the harness launches workers only within the user's authorization. Route reports as Project-A:TASK-001, preserve evidence scope, and promote accepted facts only into that child's memory. Cross-project dependencies need explicit outer coordination and original proof. The session's shared worker/resource limit applies across children; opening a new project does not grant another automatic allowance. Do not load sibling history or write another project's ledger because its role IDs look familiar.

Event and peer-review handoff

When enabled, Agent X records meaningful observations with separate occurrence and recording times, actor IDs, source revisions, and original evidence. Agent Z reviews a task at needs_review using the fixed 100 questions. Agent 0 reviews its gaps and evidence against the original acceptance criteria before accepting completion. A score is not a permission grant or proof of a live service. Reuse a matching scorecard; new review work needs changed code, evidence, policy, or a documented correction to a prior judgment. Role registration does not start an extra process, increase worker limits, or schedule a job.

External CLI lane with Agent Y

An app-native subagent and an external CLI provider are separate execution contexts. Agent Y gives a task owned by agent.y one explicitly selected provider, local Git repository/base, isolated worktree, allowed paths, and optional draft-PR policy. Preparing its Y-... job does not run the CLI; the applied run supplies the actual process result. Agent 0 retains task-ledger ownership, checks the changed paths and commit, and runs/cites the project's required checks independently. Agent Y does not retain provider stdout or test output. Agent X may record the observed run and PR transitions; Agent Z reviews the actual result at the chosen boundary. A draft PR is a handoff, not completed work or a merge.

Count simultaneous CLI runs and app workers together for the project's concurrency, token, time, and shared-resource budget. The CLI does not inherit the app's private chat memory. Provide a bounded packet and promote only reviewed results to project memory. A failed or unknown external operation requires process/GitHub readback before a retry or conflicting replacement.

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 may carry a task through a selected CLI/worktree, and Agent Z performs a fixed-policy review at a boundary; these roles may be performed by the same assistant and do not require permanent extra processes. 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.