Wasteland Orchestrator
A Claude Code plugin for multi-agent orchestration: status reporting, transactions, team coordination, and real-time dashboard for AI agent workflows.
What It Does
- Agent Status Tracking — Every agent reports what it's doing in real-time via structured status files
- Transaction System — Groups related actions into auditable units with stated intent and justification
- Gitea API Library — Centralized, dual-auth Gitea access (handles Caddy basic auth + Gitea tokens)
- Protocol Enforcement — PreToolUse hooks verify agents follow conventions (no raw curl, worktree isolation, etc.)
- Sprint Dispatch — Automated swarm dispatcher reads sprint manifests and spawns parallel
claude -p agents
- Dashboard Ready — Status files and transaction logs feed terminal dashboards and the HQ visual dashboard
Architecture
System Overview
The orchestrator sits at the center of a multi-layer agent system. Thomas (human) directs a PM agent, who plans sprints and dispatches work to dev agents via the orchestrator.
graph TB
subgraph "Human Layer"
T["Thomas / Contributors"]
end
subgraph "Management Layer"
PM["PM Agent (Elara)<br/>Sprint planning, triage,<br/>manifest generation"]
DOC["Documentation Agent<br/>Changelog, README,<br/>CLAUDE.md reconciliation"]
end
subgraph "Orchestration Layer"
SWARM["swarm.py<br/>Sprint Dispatcher"]
DAEMON["dispatch-daemon.sh<br/>Task Queue Daemon"]
MANIFEST["sprint.yaml<br/>Sprint Manifest"]
GENMAN["generate_manifest.py<br/>Gitea → Manifest"]
end
subgraph "Execution Layer"
DTL["Dev Team Lead<br/>(per project)"]
DEV1["Dev Agent<br/>(codsworth, drizzt, etc.)"]
DEV2["Dev Agent<br/>(nick-valentine, minsc, etc.)"]
TEST["Test Agent"]
UIUX["UI/UX Agent"]
REVIEW["claude-review<br/>(GitHub Action)"]
end
subgraph "Infrastructure Layer"
STATUS["Status Files<br/>~/.claude/agents/status/*.json"]
TX["Transaction Logs<br/>~/.claude/agents/transactions/"]
GITEA["Gitea<br/>git.wastelandwares.com<br/>(Issue Tracking)"]
GITHUB["GitHub<br/>(Code Hosting)"]
HQ["HQ Dashboard<br/>(wasteland-hq)"]
PIN["Pinboard<br/>~/.claude/pinboard.json"]
BTW["BTW Queue<br/>~/.claude/btw-queue.json"]
end
T -->|"ideas, direction"| PM
PM -->|"generates"| MANIFEST
PM -->|"creates issues"| GITEA
GENMAN -->|"reads issues"| GITEA
GENMAN -->|"writes"| MANIFEST
MANIFEST -->|"input to"| SWARM
PM -->|"dispatches tasks"| DAEMON
SWARM -->|"spawns claude -p"| DEV1 & DEV2
DAEMON -->|"spawns claude --print"| DTL
DTL -->|"coordinates"| DEV1 & DEV2 & TEST & UIUX
DEV1 & DEV2 -->|"push + PR"| GITHUB
GITHUB -->|"triggers"| REVIEW
REVIEW -->|"approves/requests changes"| DEV1 & DEV2
DEV1 & DEV2 & DTL & PM -->|"write"| STATUS
DEV1 & DEV2 & DTL & PM -->|"write"| TX
STATUS -->|"read by"| HQ
PIN -->|"read by"| HQ
BTW -->|"messages between"| PM
PM --> DOC
SWARM -->|"auto-close issues"| GITEA
Task Dispatch Flow
There are two dispatch mechanisms: the swarm dispatcher for full sprint execution, and the dispatch daemon for ad-hoc task delegation.
Swarm Dispatcher (Sprint Execution)
sequenceDiagram
participant PM as PM Agent
participant GEN as generate_manifest.py
participant GIT as Gitea
participant SW as swarm.py
participant DAG as Dependency DAG
participant CF as Conflict Detector
participant AG1 as Agent 1 (claude -p)
participant AG2 as Agent 2 (claude -p)
participant MON as Health Monitor
participant SF as Status Files
PM->>GIT: Query issues with "in-sprint" label
GIT-->>GEN: Return matching issues
GEN->>GEN: Extract files, deps, agents from issue body
GEN-->>PM: sprint.yaml manifest
PM->>SW: python3 swarm.py sprint.yaml
SW->>DAG: Build dependency layers (topological sort)
SW->>CF: Detect file ownership conflicts
CF-->>SW: Add serialization edges for overlapping files
rect rgb(230, 245, 255)
Note over SW,AG2: Layer 0 — No dependencies
SW->>AG1: Spawn: claude -p (story #A)
SW->>AG2: Spawn: claude -p (story #B)
end
loop Every 10 seconds
SW->>AG1: poll() — check exit code
SW->>AG2: poll() — check exit code
AG1->>SF: Write heartbeat
AG2->>SF: Write heartbeat
MON->>SF: Check heartbeats (stale > 5min?)
MON-->>SW: Health issues (if any)
end
AG1-->>SW: Exit code 0 (success)
SW->>GIT: Close issue, post completion comment
rect rgb(230, 255, 230)
Note over SW,AG2: Layer 1 — Dependencies met
SW->>AG2: (Already running from Layer 0)
end
AG2-->>SW: Exit code 0 (success)
SW->>GIT: Close issue, post sprint summary
SW-->>PM: Sprint complete (N/N succeeded)