System Internals, Champ Agent Swarm

What is a Work Packet?

The work packet is the fundamental unit of communication in the swarm. Every task, from a one-line fix to a full feature, travels as a packet.

The Analogy

Think of a work packet as a sealed envelope you hand to an agent. Inside the envelope:

Instruction, what to do ("implement user authentication")
Context, files to read, directories to explore, reference docs, notes
Expected Output, what kind of deliverable (files, PR, report, plan)
Success Criteria, how to know it's done correctly
Test Command, a shell command to verify the result

The agent opens the envelope, does the work, and returns a Work Result, a structured response with status, summary, output files, and test results.

Why Packets?

Any agent can invoke any other agent
Packets are the universal protocol, no hierarchy, no special channels. Dev can ask QA to verify. QA can ask Dev to fix. Champ orchestrates all of them.

Full audit trail
Every packet gets a unique ID (wp-{hex8}), phase history with timestamps, and an event log entry. Nothing happens without a record.

Retry-safe
Packets track their phase (PENDING → DONE/FAILED) and fix iteration count. A failed packet can be restarted from scratch. The fix loop can re-run verification multiple times.

Decoupled
The board (shared/packets.json) is just a JSON file. Any process can read it, any process can write to it. No server, no database, no message queue.

Packet Anatomy, Every Field Explained

Identity & Routing

`id`	`wp-{hex8}`, unique ID generated from crypto.randomUUID()
`agent`	Target agent name (e.g. "dev", "qa", "architect")
`invoked_by`	Who created it, "human" for CLI, or another agent's name
`priority`	P0 P1 P2, urgency level (default P1)
`timeout_minutes`	Max execution time (default 60)
`complexity`	simple medium complex, drives model selection and fix loop limits

Lifecycle State

`status`	Legacy: pending → accepted → in_progress → done/failed/blocked
`phase`	FSM: PENDING → ACCEPTED → EXECUTING → VERIFYING → FIXING → DONE/FAILED/BLOCKED/CANCELLED
`phase_history`	Array of `{phase, timestamp, reason}`, full transition audit
`active`	Boolean, false once in a terminal phase
`fix_iteration`	Current fix loop count (0-indexed, resets on restart)

Payload, The Actual Work

`instruction`	Free-text task description. This becomes the core of the agent's prompt.
`context`	`.files`, specific file paths to read `.directories`, dirs to explore `.references`, related packet IDs or doc links `.notes`, free-text extra context
`expected_output`	`.type`, one of: files pr report review plan decision `.description`, what the output should contain
`success_criteria`	String array, each criterion is checked against the result
`test_command`	Shell command to verify output (e.g. `bun test`)

Optional, Verification

verificationSpec Structured checks array: {type, command, required}
Types: test, typecheck, lint, build, runtime, security, performance

WorkPacket

            id: "wp-a1b2c3d4"

            agent: "dev"

            instruction: "Add JWT auth middleware"

            context.files: ["server.ts"]

            success_criteria: ["All tests pass"]

            test_command: "bun test"

            complexity: "medium"

            phase: "PENDING"

Created by: protocol.ts → createPacket()

Stored in: shared/packets.json

Agent processes

→ → →

Fix loop may
cycle 3-10 times

WorkResult

            packet_id: "wp-a1b2c3d4"

            status: "done"

            summary: "Added JWT middleware..."

            output_files: ["auth.ts"]

            tests_passed: true

            criteria_met: { "All tests pass": true }

            verificationResult.passed: true

Created by: protocol.ts → createResult()

Stored in: shared/results.json

How Packets Flow Through the System

Human / Agent
creates packet via
CLI invoke or follow_up

→

Board
postPacket() writes
to packets.json

→

Runner
builds prompt,
launches in tmux

→

Claude
processes prompt,
emits workresult block

→

Verifier
runs test command
+ structured checks

→

Board
saveResult() writes
to results.json

If verification fails and iterations remain, the packet loops back through the Fix Loop (EXECUTING → VERIFYING → FIXING → EXECUTING).
Agents can also emit follow_up_packets in their result to spawn new work.

Harness Modules (29)

Click any module to explore its exported functions, types, and dependencies.

Click any module above to see its functions, types, imports, and role in the system.

Module Dependency Graph

Directed edges show which modules import from which. Root modules have no harness dependencies.

Work Packet Lifecycle FSM

Every work packet transitions through these phases. Defined in protocol.ts PHASE_TRANSITIONS.

Fix Loop (Ralph Loop)

The execute-verify-fix cycle in runner.ts runWithFixLoop(). Bounded by complexity: simple=3, medium=5, complex=10 iterations.

Prompt Assembly Pipeline

How a work packet becomes a fully enriched prompt sent to Claude. Spans runner.ts, prompt-utils.ts, skill-loader.ts, and prompt-enricher.ts.

CLI Command Routing

The invoke command's size-aware routing decision tree. Defined in cli.ts.

Shared State & File Schema

All JSON/JSONL files in shared/ that form the communication layer between agents.

End-to-End Data Flow

From CLI invocation to completed work result, every module touched and every file written.