CAST v6.0 — Swarm Control Plane

CAST is the control plane for Anthropic's native Agent Teams. Define multiagent swarms in YAML, let the framework handle orchestration, quality gates, and observability.

CAST Framework

Table of Contents

• What is CAST?
• Quick Start
• Your First Workflow
• Architecture
• Personal Overlay — Layered Configuration
• Swarm System
• Agent Constellation Dashboard
• Agent Roster
• Token Efficiency & Cost Optimization
• Hook Event Coverage
• Observability & cast.db v8
• Peer Messaging & Gossip Protocol
• Multi-Agent Pipelines (v4.6+)
• Agent Memory & Persistence (v4.3+)
• Project Structure
• Scheduled Tasks
• Test Suite
• Version History
• CAST Ecosystem
• Local-First & Offline
• Contributing
• License
• Author
• Stats

---

What is CAST?

CAST transforms Agent Teams into a production control plane:

• Swarm composition in YAML. Define teams, assign roles, set quality gates. CAST bootstraps worktrees, seeds teammates with identity + prompts, manages peer messaging.
• Structural quality gates. Code changes mandate a reviewer pass. Raw git commit and git push are hard-blocked by hooks.
• Full observability. Every session, task, peer message, and token spend logs to cast.db (SQLite).
• Local model routing. Haiku agents route to Ollama; cost per swarm drops 40-60% with LiteLLM proxy.

---

Quick Start

brew tap ek33450505/cast && brew install cast && cast doctor

Or: claude plugin install ek33450505/cast — or clone + bash install.sh.

---

Your First Workflow

1. Plan — /plan add user auth feature → planner writes an Agent Dispatch Manifest.
2. Execute — /orchestrate next → code-writer implements, code-reviewer checks, test-runner verifies, commit agent stages.
3. Ship — /ship → tests, CI sanity check, push, journal entry.

---

Architecture

CAST operates alongside Anthropic Agent Teams: Anthropic handles execution parallelism, CAST handles definition, composition, and observability. See docs/architecture/ARCHITECTURE.md for the full guide including Agent Teams comparison table.

---

Personal Overlay — Layered Configuration

CAST ships in two layers: core (always installed) and personal (optional, --personal flag).

Layer	Contents	Installed
rules-core/	Generic conventions (shell, python, typescript)	Always
agents/core/	Specialist agents (code-writer, debugger, planner, …)	Always
rules-personal/	Maintainer project catalog, identity traits	--personal
agents/personal/	Maintainer-specific agents (e.g., portfolio-sync)	--personal

New clones get a trustworthy, generic installation. rules-personal/ ships empty for clones to populate.

---

Swarm System

CAST swarms are defined in YAML and bootstrapped with cast swarm bootstrap. Teams get isolated worktrees, agent identity, peer messaging, and quality gates. See docs/architecture/ARCHITECTURE.md.

---

Agent Constellation Dashboard

Constellation — force-directed graph showing agent nodes, task satellites, token heatmaps, peer messages, and hook audit trails in real time. Part of claude-code-dashboard. See docs/observability/OBSERVABILITY.md.

---

Agent Roster

30 core specialists. Each is a markdown file in ~/.claude/agents/ with YAML frontmatter defining model, memory, and isolation. Agent responses validate against JSON schemas in schemas/. See docs/agents/AGENT-ROSTER.md for the full table with model tiers.

Key agents: code-writer, debugger, planner, researcher, security, code-reviewer, commit, push, test-writer, devops, bash-specialist, migration-reviewer, api-contract, dep-auditor, perf-sentinel.

---

Token Efficiency & Cost Optimization

Model tiering, response budgets, Ollama local routing, laconic mode, and RTK compression achieve ~30-50% token spend reduction. See docs/TOKEN-OPTIMIZATION.md.

---

Hook Event Coverage

Hooks cover the full swarm lifecycle: SessionStart, TaskCreated, WorktreeCreate, PreToolUse:Bash (commit guard), PostToolUse, PostCompact, SessionEnd. See docs/observability/OBSERVABILITY.md.

---

Observability & cast.db v8

SQLite WAL mode at ~/.claude/cast.db — append-only, never truncated. Stores swarm_sessions, teammate_runs, teammate_messages, agent_runs, routing_events, stream_events. See docs/observability/OBSERVABILITY.md.

---

Peer Messaging & Gossip Protocol

Teammates communicate via cast.db message bus — no central broker, fully decentralized. Types: task_claim, status_update, peer_query, idle_event. See docs/architecture/ARCHITECTURE.md.

---

Multi-Agent Pipelines (v4.6+)

The /orchestrate skill executes Agent Dispatch Manifests (ADM) — JSON plan files defining sequential/parallel agent batches. owns_files prevents write conflicts between parallel agents. See docs/architecture/ARCHITECTURE.md for the full ADM format.

cast exec ~/.claude/plans/my-plan.md
cast parallel ~/.claude/plans/my-plan.md --dry-run

---

Agent Memory & Persistence (v4.3+)

Each agent accumulates domain knowledge in ~/.claude/agent-memory-local/<name>/MEMORY.md. Features: FTS5 full-text search, relevance scoring, temporal validity (history preserved), shared pool (agent='shared'), procedural memory, session distiller. See docs/architecture/ARCHITECTURE.md.

---

Project Structure

claude-agent-team/
  agents/{core,personal}/   ← agent definitions
  config/                   ← LiteLLM proxy, managed-settings.d/
  rules-{core,personal}/    ← conventions and overlays
  docs/                     ← architecture docs, diagrams
  schemas/                  ← JSON schemas (status-block, work-log, routing-event)
  scripts/                  ← hook scripts, swarm bootstrap, utilities
  swarm-configs/            ← YAML team definitions
  tests/                    ← BATS suite (core, hooks, swarm, agents, scripts)
  .github/workflows/        ← bats-ci.yml

Runtime installs to ~/.claude/ — agents, memory, plans, swarm sessions, cast.db, scripts.

---

Scheduled Tasks

Hybrid model: RemoteTriggers for AI-powered tasks (briefings, standups, reports); cron for local shell maintenance (CI monitoring, log cleanup, cast.db pruning). cast tidy cleans items older than 14 days.

---

Test Suite

501 BATS tests across 5 directories. 0 failures. Coverage: core hooks, swarm bootstrap, message bus, database migrations, guard logic, event emission, memory persistence. Run with `bats tests/`.

---

Version History

See CHANGELOG.md.

---

CAST Ecosystem

Repo	Description	Distribution
claude-agent-team	Core framework	Homebrew ek33450505/cast, Claude plugin
cast-hooks	Hook scripts — 13 hooks	Homebrew ek33450505/cast-hooks
cast-dash	TUI dashboard	Homebrew ek33450505/cast-dash
cast-memory	Standalone memory persistence	Homebrew ek33450505/cast-memory
cast-parallel	Parallel plan execution	Homebrew ek33450505/cast-parallel
claude-code-dashboard	React UI — Constellation graph	Standalone repo

---

Local-First & Offline

macOS Keychain, age encryption (Secure Enclave), WAL-safe SQLite backups, offline queue with auto-replay, Ollama fallback. All observability stays in cast.db on disk — zero cloud lock-in.

---

Contributing

See CONTRIBUTING.md. Open an issue first for non-trivial changes. PRs trigger cast-pr-review.yml — code-reviewer agent reviews your diff.

---

License

MIT — see LICENSE.

---

Author

Edward Kubiak — Full-stack engineer, Claude Code expert.
GitHub: ek33450505 | CAST Portfolio: castframework.dev

---

Stats

30 agents | 501 tests | 19 commands | 16 skills