wasteland-orchestrator

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)