actx swarm

actx swarm

Orchestrate multi-agent workstreams from a YAML or JSON manifest. The swarm engine handles dependency resolution, file-lock isolation, write-scope conflict detection, and agent subprocess lifecycle management.

Usage

actx swarm <subcommand>

Subcommands

Subcommand	Description
start --manifest <path>	Parse a manifest and dispatch agent subprocesses
status	Show active agents and workstream status

Options (start)

Option	Required	Description
--manifest <path>	Yes	Path to YAML or JSON swarm manifest file

Manifest Format

phase: 23
workstreams:
  - id: ws-auth
    name: "Implement Auth Module"
    role: implementer
    scope:
      files: ["src/auth/**"]
    depends: []
    exit: ["tests pass", "no lint errors"]
agents:
  - id: agent-1
    typeId: implementer
    busy: false

How It Works

1. Manifest parsing — validates workstream definitions and agent pool
2. Isolation check — detects write-scope overlaps between concurrent workstreams
3. Dependency resolution — uses the Dispatcher to order workstreams by depends graph
4. File locking — acquires exclusive locks on each workstream’s scoped files
5. Agent spawning — launches subprocess per assignment with environment context (ACTX_WORKSTREAM, ACTX_ROLE, ACTX_PHASE, ACTX_SCOPE, ACTX_GIT_BRANCH)
6. Completion tracking — monitors exit codes and releases locks on completion

Error Codes

Code	Meaning
MANIFEST_NOT_FOUND	Manifest file does not exist
MANIFEST_PARSE_ERROR	YAML/JSON syntax error
MANIFEST_INVALID	Missing required fields (id, name, role)
NO_WORKSTREAMS	No workstreams defined or all are blocked
ISOLATION_CONFLICT	Two or more workstreams have overlapping write scopes
LOCK_CONFLICT	File lock already held by another agent
SPAWN_FAILED	Agent subprocess failed to start

See Also

• actx dispatch — single-phase dispatch engine
• actx phase — phase gate management
• Multi-Agent Swarms — architecture guide