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 Project records
    participant H as AI harness
    participant W as Scoped worker
    U->>A: Objective, boundaries, and delegation authority
    A->>R: Read selected instructions, plan, focus, tasks, and memory
    A->>A: Verify dependencies, live state, scopes, and capacity
    A->>R: Register needed role and record bounded task
    A->>H: Start or reuse an authorized worker with its packet
    H-->>A: Actual worker or job handle
    H->>W: Deliver assignment and available tools
    W-->>A: Confirm scope and that work has started
    A->>R: Record in_progress and runtime mapping
    W->>W: Perform scoped work and relevant checks
    W->>R: Save own memory and evidence references
    W-->>H: Result, changed artifacts, checks, limits, next action
    H-->>A: Return worker result and observed runtime state
    A->>R: Record needs_review with evidence
    A->>A: Review scope, integrate changes, run relevant combined checks
    alt Acceptance is satisfied
        A->>R: Record done with reviewer and evidence
        A->>R: Promote verified facts and save next focus/checkpoint
        A-->>U: Accepted outcome and evidence scope
    else Repair or missing prerequisite
        A->>R: Return to in_progress or record blocked with reason
        A-->>U: Remaining issue and precise 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