superkick 0.1.0

data/README.md

@@ -0,0 +1,1155 @@
+# Superkick
+
+**An autonomous development environment (ADE) for AI coding agents.**
+
+AI coding agents work heads-down in a single terminal session. Meanwhile, CI
+fails, reviewers leave comments, teammates flag blockers — a whole world the
+agent can't see.
+
+Superkick fixes that. It wraps your AI CLI in a transparent proxy, monitors the
+outside world, and injects relevant context directly into the session at idle
+moments. It can also spawn and coordinate entire teams of agents autonomously —
+picking up new issues, running multi-step workflows, and managing their own
+working copies.
+
+## How it works
+
+Superkick wraps AI coding CLIs (Claude Code, GitHub Copilot, OpenAI Codex, Google
+Gemini, Goose) in a transparent PTY proxy and runs background **monitors** that watch
+external services — GitHub CI, PR reviews, CircleCI pipelines, Shortcut stories,
+or any shell command you configure.
+
+When something happens, Superkick waits for the agent to go idle, then injects the
+relevant context directly into the session as a prompt. CI fails? The agent
+already knows. PR review comes in? It's reading it.
+
+```
+  superkick agent (one per AI CLI session)
+  +--------------------------------------+
+  | PtyProxy                             |         superkick server
+  |  |                                   | Control +-----------------------------------+
+  |  +---> Buffer::Server                |<------->| Control::Server (server.sock)     |
+  |  |      (buffer-<id>.sock)           |         |                                   |
+  |  +---> OutputLogger                  |         | AgentStore                        |
+  |  |      (logs/<id>.log)              |         |  +-- Agent                        |
+  |  +---> SessionRecorder              |         |      +-- recording_path           |
+  |  |      (recordings/<id>.cast)      |         |           (transient link)        |
+  |  +---> Attach::Server                |         |      +-- monitors: { ... }        |
+  |  |      (attach-<id>.sock)           |         |      +-- buffer_socket_path <-----+-+
+  |  +---> InputBuffer                   |         |           (transient link)        | |
+  |         (partial input + guards)     |         |                                   | |
+  |                                      |         | Supervisor                        | |
+  |  proxy_stdin  --> InputBuffer -->PTY |         |  +-- owns monitor threads         | |
+  |  proxy_output --> guard detect -->out |         |                                   | |
+  |  drain_inject ------------------>PTY |         | Injector                          | |
+  +--------------------------------------+         |  +-- reads buffer_socket----------+-+
+            | PTY                                  |                                   |
+            v                                      | Spawners                          |
+  +--------------------------------------+         |  +-- spawn new agents on events   |
+  | AI CLI (claude / copilot / ...)      |--MCP--> |                                   |
+  +--------------------------------------+    |    | McpServer                         |
+                                              +--->|  (16 tools for AI CLI)            |
+                                                   +-----------------------------------+
+```
+
+1. **`superkick agent start`** wraps your AI CLI in a PTY proxy that tracks terminal output and idle state
+2. The **server** (`superkick server start`) runs monitors that poll external services
+3. When the CLI is idle and a noteworthy event occurs, Superkick injects a context prompt directly into the PTY
+4. The AI CLI also communicates with Superkick via **MCP tools** to discover and manage monitors
+
+## Quick start
+
+```bash
+gem install superkick
+superkick setup
+```
+
+The setup wizard walks you through driver selection, monitor configuration,
+and MCP integration. For manual configuration, see the [getting started tutorial](docs/tutorials/getting-started.md).
+
+Once configured:
+
+```bash
+# Start the server (background)
+superkick server start -d
+
+# Launch your AI CLI through Superkick
+superkick agent start
+
+# Enable tab completion (add to .bashrc / .zshrc)
+eval "$(superkick completion bash)"   # or zsh
+```
+
+When the AI CLI starts, Superkick detects your GitHub repo and branch from git,
+starts monitoring for CI results and PR activity, and injects context when
+events occur. No copy-pasting needed.
+
+## Documentation
+
+Beyond this README, Superkick has documentation organized by learning style:
+
+| | |
+|---|---|
+| **Tutorials** | [Getting started](docs/tutorials/getting-started.md) · [First spawner pipeline](docs/tutorials/first-spawner-pipeline.md) · [Team workflow](docs/tutorials/team-workflow.md) |
+| **How-to guides** | [Customize templates](docs/how-to/customize-templates.md) · [Configure notifications](docs/how-to/configure-notifications.md) · [Troubleshooting](docs/how-to/troubleshooting.md) |
+| **Explanation** | [How injection works](docs/explanation/injection-model.md) · [Spawner workflows](docs/explanation/spawner-workflows.md) · [Agent teams](docs/explanation/agent-teams.md) |
+| **Reference** | [Template variables](docs/reference/templates.md) · [Event types & payloads](docs/reference/event-types.md) |
+
+See the [full documentation index](docs/README.md) for everything.
+
+## Key concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Driver** | Describes how to drive a specific AI CLI: executable name, idle prompt patterns, injection guards, and MCP installer. |
+| **Monitor** | Watches an external service and emits events (e.g. CI failure, new PR comment). Optionally includes a `Probe` class for auto-detection from the local environment. |
+| **Spawner** | Server-level poller that watches for external events and spawns new agent processes (e.g. new Shortcut stories trigger new coding agents). |
+| **Goal** | Defines what "finished" means for a spawned agent — the server checks it periodically and terminates the agent on completion (e.g. PR merged, CLI exited). |
+| **VersionControl** | Adapter for VCS operations — acquires isolated working copies (clone or worktree) and cleans them up. Spawners declare a `repository:` key and the appropriate adapter handles the rest. |
+| **RepositorySource** | Catalog of repositories with metadata (tags, descriptions, dependencies). Used by planning agents to discover where work belongs. Supports static entries, directory scanning, and GitHub organization fetching. |
+| **Team** | A group of agents working toward a shared objective. A planning agent (lead) decomposes tasks and spawns workers. Workers communicate via a shared team log. |
+| **InjectionQueue** | Agent-side queue that checks injection preconditions locally (CLI must be idle for `idle_threshold` seconds) and writes to the PTY. Supports TTL, priority, and supersede-by-key semantics. |
+| **Injector** | Orchestrates injection: renders a Liquid template and enqueues it on the agent's `InjectionQueue` via the buffer socket. |
+| **Notifier** | Alerts the user after a successful injection (terminal bell, shell command, etc.). Pluggable — add custom notifiers for OS notifications, webhooks, or chat integrations. |
+
+## Built-in drivers
+
+| Driver | CLI command | Prompt patterns | MCP config file |
+|--------|-------------|-----------------|-----------------|
+| `claude_code` | `claude` | `> `, `Human: `, `$ ` | `~/.claude/settings.json` |
+| `copilot` | `copilot` | `@ ` | `~/.copilot/mcp-config.json` |
+| `codex` | `codex` | `codex> ` | `~/.codex/config.toml` |
+| `gemini` | `gemini` | `gemini> `, `> ` | `~/.gemini/settings.json` |
+| `goose` | `goose` | `goose> `, `> ` | `~/.config/goose/config.yaml` |
+
+## Built-in integrations
+
+### GitHub
+
+Provides: **monitor**, **spawners**, **goals**
+
+- **Monitor** (`:github`) — watches CI check runs, PR comments, and PR reviews. Auto-detected from your git remote and branch.
+- **Spawner** (`:github_issues`) — watches for newly created or reopened issues and spawns agents. Supports filtering by labels, assignee, milestone, and creator.
+- **Spawner** (`:github_check_failed`) — watches check suites for failures on configured branches and spawns agents to fix them. Works across CI providers.
+- **Goal** (`:github_pr_merged`) — completes a spawned agent when its PR is merged. Auto-detects repo and branch from the agent's working directory.
+- **Goal** (`:github_issue_resolved`) — completes a spawned agent when the associated issue is closed (any close reason).
+
+See [GitHub integration README](lib/superkick/integrations/github/README.md) for full details.
+
+### CircleCI
+
+Provides: **monitor**
+
+- **Monitor** (`:circleci`) — watches pipeline workflows for success/failure, lists failed jobs. Auto-detected from `.circleci/config.yml` and your git remote.
+
+See [CircleCI integration README](lib/superkick/integrations/circleci/README.md) for full details.
+
+### Shortcut
+
+Provides: **monitor**, **spawner**
+
+- **Monitor** (`:shortcut`) — watches a story for state changes, comments, blockers, owner changes, description updates, and related story changes. Auto-detected from the `sc-XXXXX` branch pattern.
+- **Spawner** (`:shortcut`) — watches a search query for new stories and spawns agents to work on them.
+
+See [Shortcut integration README](lib/superkick/integrations/shortcut/README.md) for full details.
+
+### Bugsnag
+
+Provides: **spawner**
+
+- **Spawner** (`:bugsnag`) — watches Bugsnag for open errors and spawns agents to fix them. Supports filtering by severity, release stage, error class, version, and minimum event count.
+
+See [Bugsnag integration README](lib/superkick/integrations/bugsnag/README.md) for full details.
+
+### Datadog
+
+Provides: **notifier**, **spawner** (error tracking + alerts), **monitor**, **goal**
+
+- **Notifier** (`:datadog`) — sends events and metrics to Datadog via DogStatsD (UDP). See [Notifications](#notifications) for details.
+- **Spawner** (`:datadog`) — watches Datadog Error Tracking for open error groups and spawns agents to fix them. Supports filtering by service, environment, source, and minimum event count.
+- **Alert Spawner** (`:datadog_alerts`) — watches Datadog monitors for triggered alerts and spawns agents to triage them. Supports filtering by status, tags, monitor type, and priority. Monitors that recover and re-alert are re-dispatched as new agents.
+- **Alert Monitor** (`:datadog_alert`) — polls a specific Datadog monitor for status changes and injects events when the alert recovers, escalates, or changes state. Typically auto-configured by the alert spawner.
+- **Alert Goal** (`:datadog_alert_resolved`) — completes when the Datadog monitor returns to OK status. Auto-terminates the agent when the alert resolves.
+
+See [Datadog integration README](lib/superkick/integrations/datadog/README.md) for full details.
+
+### Honeybadger
+
+Provides: **notifier**, **spawner**
+
+- **Notifier** (`:honeybadger`) — sends structured events to Honeybadger Insights via the Events API. See [Notifications](#notifications) for details.
+- **Spawner** (`:honeybadger`) — watches Honeybadger for unresolved faults and spawns agents to fix them. Supports filtering by environment, fault class, and minimum occurrence count.
+
+See [Honeybadger integration README](lib/superkick/integrations/honeybadger/README.md) for full details.
+
+### Shell
+
+Provides: **monitor**
+
+- **Monitor** (`:shell`) — runs a custom command each poll interval, dispatches events based on exit status. Supports multiple named instances. Auto-detected from executable scripts in `.superkick/shell/`.
+
+See [Shell integration README](lib/superkick/integrations/shell/README.md) for full details.
+
+### Slack
+
+Provides: **notifier**, **spawner**, **monitor**
+
+- **Notifier** (`:slack`) — posts rich Block Kit messages to Slack. See [Notifications](#notifications) for details.
+- **Spawner** (`:slack`) — watches a Slack channel for new messages and spawns agents to handle them. Auto-attaches a per-agent Slack notifier that posts lifecycle events back to the originating thread, and a thread monitor for follow-up replies.
+- **Thread Monitor** (`:slack_thread`) — polls a Slack thread for new replies and injects them as high-priority events.
+
+See [Slack integration README](lib/superkick/integrations/slack/README.md) for full details.
+
+## Notifications
+
+Superkick fires **notifiers** on two kinds of events:
+
+1. **Monitor injections** — after context is injected into an agent session
+2. **Agent lifecycle events** — when spawned agents change state (`agent_spawned`, `agent_completed`, `agent_failed`, `agent_timed_out`, `agent_blocked`, `agent_stalled`, `agent_terminated`, `agent_claimed`, `agent_unclaimed`, `agent_pending_approval`, `workflow_triggered`, `workflow_iterations_exceeded`, `budget_warning`, `budget_exceeded`)
+3. **Attach events** — when attach client modes change (`attach_promoted`, `attach_demoted`, `attach_idle_timeout`, `attach_force_takeover`)
+
+This is especially useful when you step away from the terminal — you'll know when agents finish, stall, or need approval.
+
+### Terminal bell (default)
+
+When no `notifications:` section is configured, Superkick writes a BEL character (`\a`) to stderr. Most terminal emulators respond with a visual or audible alert:
+
+- **iTerm2** bounces the dock icon
+- **tmux** marks the window with activity
+- **GNOME Terminal** flashes the tab title
+- **Windows Terminal** flashes the taskbar
+
+### Command notifier
+
+Run any shell command when an injection occurs. Event details are available as environment variables:
+
+| Variable | Example |
+|----------|---------|
+| `SUPERKICK_EVENT_TYPE` | `ci_failure`, `pr_comment` |
+| `SUPERKICK_MONITOR_TYPE` | `github`, `shell` |
+| `SUPERKICK_MONITOR_NAME` | `github`, `disk-check` |
+| `SUPERKICK_AGENT_ID` | `abc123` |
+| `SUPERKICK_MESSAGE` | `Superkick: ci_failure from github` |
+
+```yaml
+# config.yml
+notifications:
+  - type: terminal_bell
+  - type: command
+    run: "notify-send 'Superkick' '$SUPERKICK_MESSAGE'"
+  - type: command
+    run: "curl -s -X POST $SLACK_WEBHOOK -d '{\"text\": \"$SUPERKICK_MESSAGE\"}'"
+    events:                          # optional — restrict which events fire
+      - agent_blocked
+      - agent_completed
+      - agent_pending_approval
+```
+
+Commands are killed after `timeout_seconds` (default 10) to prevent hung processes. Multiple notifiers can be configured — each runs independently, so one failure doesn't block the others. When `events:` is absent on a notifier, it receives all events.
+
+### Slack notifier
+
+Post rich Block Kit messages to Slack. Supports two authentication modes:
+
+**Incoming Webhook** — simplest setup, posts to a single channel:
+
+```yaml
+notifications:
+  - type: slack
+    webhook_url: <%= env("SLACK_WEBHOOK_URL") %>
+```
+
+**Web API** — can target any channel, requires a bot token with `chat:write` scope:
+
+```yaml
+notifications:
+  - type: slack
+    token: <%= env("SLACK_BOT_TOKEN") %>
+    channel: "#superkick-notifications"
+    events:
+      - agent_completed
+      - agent_failed
+      - agent_blocked
+```
+
+Messages include a header with an event-specific emoji, the notification message, and a context line with agent/monitor metadata. In Web API mode, messages for the same agent are automatically **threaded** — the first event creates a new thread, and subsequent events (blocked, completed, failed) reply to it, keeping the channel clean. Webhook mode sends standalone messages (Slack webhooks don't support threading).
+
+The Slack spawner automatically attaches a **per-agent Slack notifier** to each spawned agent, pre-seeded with the originating thread's `thread_ts`. This means lifecycle events (spawned, completed, failed, etc.) are posted back to the Slack thread where the message originated — no global notifier configuration needed.
+
+### Datadog notifier
+
+Send events and metrics to Datadog via DogStatsD (UDP). Events appear in the Event Explorer; counters and gauges appear in Metrics Explorer for dashboards and alerts. No gem dependency — uses the standard DogStatsD UDP protocol directly.
+
+```yaml
+notifications:
+  - type: datadog
+    statsd_host: localhost       # default — your Datadog Agent
+    statsd_port: 8125            # default DogStatsD port
+    prefix: superkick            # metric name prefix
+    tags:
+      - "env:production"
+      - "team:platform"
+```
+
+Emitted metrics (tagged with `agent_id`, `event_type`, `monitor_type`, `monitor_name`, plus global tags):
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `<prefix>.event` | Counter | Incremented on every event |
+| `<prefix>.agent.duration` | Gauge | Seconds from spawn to terminal event |
+
+Events include the notification message, an alert type mapped from the event (success/error/warning/info), and all standard tags. Duration is computed automatically — the notifier tracks spawn times per agent and emits duration on terminal events.
+
+### Honeybadger notifier
+
+Send structured events to [Honeybadger Insights](https://www.honeybadger.io/for/insights/) via the Events API. Events appear in the Insights dashboard for search, filtering, graphing, and alerting.
+
+```yaml
+notifications:
+  - type: honeybadger
+    api_key: <%= env("HONEYBADGER_API_KEY") %>
+    tags:
+      - production
+      - team-alpha
+```
+
+Each event includes `event_type`, `agent_id`, `severity` (mapped from event type), `message`, monitor metadata, and optional `duration_seconds` on terminal events. Like the Datadog notifier, duration is computed automatically from tracked spawn times.
+
+### Custom notifiers
+
+Notifiers are pluggable. See the [notifier skill](skills/superkick-new-notifier/SKILL.md) for a step-by-step guide to adding your own.
+
+## Spawners
+
+Spawners are server-level pollers that watch external services and automatically spawn new agent processes in response to events. While monitors inject context into an existing agent, spawners create entirely new agents.
+
+```yaml
+# config.yml
+spawners:
+  shortcut:
+    token: <%= env("SHORTCUT_TOKEN") %>
+
+    search: "owner:me state:'In Progress'"
+    driver: claude_code
+    repository: my-app
+    branch_template: "fix-{{ agent_id }}"
+    goal:
+      type: github_pr_merged
+    max_duration: 7200           # hard timeout in seconds
+    cooldown: 300                # minimum seconds between spawns
+    approval_required: true      # require human approval before spawning
+    stall_threshold: 600         # seconds idle before agent_stalled notification
+```
+
+### Approval gates
+
+When `approval_required: true`, spawn events are held for human review instead of spawning immediately. An `agent_pending_approval` notification fires, and the user approves or rejects via the CLI:
+
+```bash
+superkick approvals                 # list pending approvals
+superkick approve <id>              # approve a pending spawn
+superkick reject <id> -r "reason"   # reject (persistent within server lifetime)
+superkick reject --clear <id>       # clear a rejection to allow re-dispatch
+superkick reject --clear-all        # clear all rejections
+```
+
+### Agent claim & handoff
+
+Spawned agents run autonomously with goal checking, but you can **claim** an agent to take manual control — pausing goal checking, stall detection, and the `max_duration` timer:
+
+```bash
+superkick agent claim AGENT_ID      # pause autonomous operation
+superkick agent unclaim AGENT_ID    # resume autonomous operation
+```
+
+When attached to a running agent (`superkick agent attach AGENT_ID -i`), you can also use escape sequences (default: Ctrl-A prefix):
+
+| Sequence | Action |
+|----------|--------|
+| Ctrl-A, d | Detach from agent |
+| Ctrl-A, c | Claim agent (pauses autonomous operation; auto-promotes to RW if slot is vacant) |
+| Ctrl-A, u | Unclaim agent (resumes autonomous operation) |
+| Ctrl-A, w | Request read-write promotion (only if RW slot is vacant) |
+| Ctrl-A, W | Force read-write promotion (demotes existing RW holder) |
+| Ctrl-A, r | Voluntarily demote to read-only |
+
+The escape prefix is configurable for tmux/screen users (see [Configuration](#configuration-settings)).
+
+RW clients are automatically demoted to read-only after `attach_rw_idle_timeout` seconds (default 300) of no input. Use `--force` / `-f` on the attach command to take over RW from another client at connect time.
+
+### Repository acquisition
+
+When a spawner specifies `repository:`, the system automatically acquires an isolated working copy using the appropriate **VersionControl** adapter:
+
+```yaml
+spawners:
+  fix_issues:
+    repository: api                      # looks up from repository source
+    branch_template: "fix-{{ agent_id }}"    # Liquid template (default: "superkick-{{ agent_id }}")
+    base_branch: main                    # branch to base from (default: "main")
+```
+
+The Git adapter uses **worktrees** when the repository has a local path (fast, shared objects) and falls back to **clone** when only a URL is available. Working copies are created under `~/.superkick/workspaces/<agent_id>` and cleaned up when the agent ends.
+
+### Goals
+
+A **goal** defines what "finished" means for a spawned agent. The server checks the goal periodically and terminates the agent when it reaches a terminal status.
+
+| Goal | Description |
+|------|-------------|
+| `agent_exit` | Completes when the AI CLI process exits |
+| `command` | Runs a shell command periodically; exit code determines status |
+| `agent_signal` | Completes when the AI CLI calls the `superkick_signal_goal` MCP tool (**default** — can be omitted) |
+| `github_pr_merged` | Completes when the agent's GitHub PR is merged (see [GitHub integration](lib/superkick/integrations/github/README.md)) |
+| `github_issue_resolved` | Completes when the associated GitHub issue is closed (any close reason) |
+| `datadog_alert_resolved` | Completes when a Datadog monitor returns to OK status (see [Datadog integration](lib/superkick/integrations/datadog/README.md)) |
+
+### Spawner workflows
+
+When a spawned agent reaches its goal (or fails), Superkick can automatically spawn the **next agent** in a pipeline using `on_complete:` and `on_fail:` hooks. This enables multi-stage workflows:
+
+```
+Issue spawner → implementation agent completes → review agent spawns → PR merged → done
+                                    └─ fails → retry agent spawns
+```
+
+#### Configuration
+
+Add `on_complete:` and/or `on_fail:` to any spawner config. Two forms are supported:
+
+**Inline config** — define the next stage directly:
+
+```yaml
+spawners:
+  implement:
+    type: github_issues
+    repo: org/app
+    driver: claude_code
+    repository: app
+    on_complete:
+      goal:
+        type: github_pr_merged
+      prompt_template: review          # template name for the kickoff prompt
+      max_duration: 1800
+    on_fail:
+      prompt_template: fix_and_retry
+```
+
+**Spawner reference** — point to another named spawner:
+
+```yaml
+spawners:
+  implement:
+    type: github_issues
+    repo: org/app
+    on_complete:
+      spawner: review_pr              # reuse another spawner's full config
+    on_fail:
+      spawner: notify_failure
+```
+
+#### How it works
+
+1. A spawned agent's goal reaches a terminal status (`:completed` or `:failed`)
+2. The Supervisor calls `Spawn::WorkflowExecutor#fire`
+3. The executor resolves the workflow config (inline or spawner reference)
+4. An enriched event is built — the parent's serialized context (Drops like `issue`, `story`, plus scalars like `repo`, `branch`) is forwarded wholesale so the next agent has full context
+5. The new agent is spawned in a background thread through the normal spawn path (workspace setup, kickoff injection, goal checking)
+6. A `workflow_triggered` lifecycle notification fires
+
+#### VCS inheritance
+
+By default, a workflow spawn **inherits the parent's VCS state** — the parent's working copy is handed to the child without teardown. This means:
+
+- The child starts in the same working directory (e.g. the same git worktree)
+- The last agent in the chain handles cleanup
+- No redundant repository acquisition between stages
+
+To give a workflow step its own working copy instead, add an explicit `repository:` key:
+
+```yaml
+on_complete:
+  repository: app
+  base_branch: main
+```
+
+#### Iteration limiting
+
+For cyclic workflows (`allow_cycles: true`), you **must** set `max_iterations` to prevent infinite recursion. This controls how many times a specific spawner can fire within a single workflow chain. Acyclic workflows don't need any limit — they're naturally bounded by graph structure.
+
+```yaml
+spawners:
+  implement:
+    allow_cycles: true
+    max_iterations: 3                 # this spawner can fire at most 3 times per chain
+    on_fail:
+      spawner: implement              # retry on failure
+```
+
+When the limit is reached, a `workflow_iterations_exceeded` notification fires and no further agents are spawned.
+
+#### Cycle detection
+
+At server startup, Superkick validates all spawner configs for reference cycles (e.g. `A → B → A`). Cycles are detected statically via chain walking on the spawner reference graph and prevent the server from starting. Inline configs are leaf nodes — they don't create edges in the graph.
+
+## Repository source
+
+When working across multiple repositories, Superkick needs to know what repositories exist and what they do. The **repository source** provides a structured catalog that planning agents use to decompose tasks and spawn workers in the right places.
+
+### Configuration
+
+Each key under `repositories:` is a user-chosen name. Entries without a `type:` key are static repository definitions. Entries with a `type:` key are repository sources that discover repositories automatically.
+
+```yaml
+# config.yml
+repositories:
+  # Static entries — you define each repository directly
+  api_service:
+    path: ~/projects/api-service
+    url: git@github.com:org/api-service
+    description: "Core REST API — user, auth, billing endpoints"
+    tags: [backend, api, ruby]
+    context_documents: [readme, claude_md] # include these docs in planning context
+    dependencies: [shared_types]
+
+  web_frontend:
+    path: ~/projects/web-frontend
+    description: "React SPA consuming api-service"
+    tags: [frontend, react, typescript]
+
+  # Directory scan — auto-detects repos in a local directory
+  local:
+    type: directory
+    path: ~/projects
+    version_controlled_only: true        # only include dirs under version control (default)
+    depth: 1                             # subdirectory depth (default 1, max 5)
+    exclude: [node_modules, deprecated]
+
+  # GitHub organization — fetches repos from a GitHub org
+  company:
+    type: github_organization
+    organization: my-company
+    token: <%= env("GITHUB_TOKEN") %>
+    topic_filter: [production]           # only repos with ALL listed topics
+    exclude: [legacy-app]
+    visibility: all                      # public, private, or all
+```
+
+Static entries and typed sources can be freely mixed. When there's a single source, it's returned directly. When there are multiple, they're composited automatically (first-found wins on name collisions).
+
+### Source types
+
+| Type | Description |
+|------|-------------|
+| *(no type)* | Static repository entry — you define name, path, URL, tags, and dependencies directly |
+| `directory` | Scans a local directory for subdirectories. Auto-detects git remotes, project language tags, and git descriptions |
+| `github_organization` | Fetches repositories from a GitHub organization or user account via the API. All metadata comes from the API — no SSH keys needed |
+
+### How it's used
+
+- **Planning agents** receive the repository catalog as part of their kickoff prompt, giving them a structured view of available repositories
+- The **`repository:`** spawner config key resolves a repository from the source and acquires an isolated working copy via the appropriate **VersionControl** adapter
+- Repositories serve as a **whitelist** — planning agents can only spawn workers for repositories in the source
+
+## Agent teams
+
+Teams coordinate multiple agents working toward a shared objective. A **planning agent** (the team lead) reads a task, discovers which repositories are affected, decomposes the work, and spawns **worker agents** — one per repository. The team succeeds when all workers finish.
+
+### Team workflow
+
+When a spawner has `workflow: team`, it creates a planning agent instead of a normal worker:
+
+```yaml
+# config.yml
+repositories:
+  api_service:
+    path: ~/projects/api-service
+    description: "Core REST API"
+    tags: [backend, ruby]
+    context_documents: [readme]
+  web_frontend:
+    path: ~/projects/web-frontend
+    description: "React SPA"
+    tags: [frontend, react]
+
+spawners:
+  feature_team:
+    type: github_issues
+    repo: org/api-service
+    labels: [multi-repo]
+    workflow: team                       # creates a planning agent, not a worker
+    driver: claude_code
+    max_duration: 7200                   # 2 hours for the entire team
+    approval_required: true
+```
+
+### How it works
+
+```
+GitHub issue created
+  → Spawner detects new issue
+  → Planning agent spawns (team lead)
+  → Reads issue + repository source
+  → Decomposes work: "API needs a new endpoint, frontend needs a new page"
+  → Spawns worker agent in api_service (git worktree)
+  → Spawns worker agent in web_frontend (git worktree)
+  → Workers execute in parallel, broadcasting status to team log
+  → Planning agent monitors progress, coordinates if needed
+  → All workers complete → lead signals goal complete via MCP → done
+```
+
+The planning agent uses MCP tools to manage the team:
+
+| Tool | Description |
+|------|-------------|
+| `superkick_spawn_worker` | Spawn a worker agent in a specific repository (with optional `role` label) |
+| `superkick_discover_repositories` | List available repositories with descriptions, tags, and dependencies |
+| `superkick_team_status` | Read the team log — see what teammates are doing |
+| `superkick_post_update` | Broadcast a status update or send a targeted message to a teammate |
+| `superkick_list_teammates` | List all agents on the team with roles and status |
+| `superkick_publish_artifact` | Share structured data (plans, specs) with the team |
+| `superkick_read_artifact` | Read an artifact published by a teammate |
+| `superkick_list_artifacts` | List all artifacts for the team |
+
+### Team log
+
+Each team has a shared, append-only log where agents broadcast updates. This is the primary communication channel — agents radiate status rather than polling each other:
+
+```bash
+superkick team status TEAM_ID
+# Team: github-issue-org-app-42 (3 agents)
+#
+#   github-issue-org-app-42          lead/Lead        [in_progress]
+#   github-issue-org-app-42-api      worker/API dev   [in_progress]
+#   github-issue-org-app-42-web      worker/Frontend  [in_progress]
+#
+# Latest updates:
+#   [github-issue-org-app-42] [decision] Decomposed into api-service + web-frontend
+#   [github-issue-org-app-42-api] [progress] Added /preferences endpoint, writing tests
+#   [github-issue-org-app-42-web] [blocker] Waiting for api-service PreferencesResponse type
+```
+
+Targeted messages (`superkick_post_update` with `target_agent_id`) are for directed coordination — they're injected into the target's prompt and recorded in the team log (visible to the whole team). Agents can also share structured data via **artifacts** (`superkick_publish_artifact` / `superkick_read_artifact`).
+
+Team leads automatically receive a **team feed** — a monitor that injects digest summaries of teammate activity. Workers can opt in via `superkick_add_monitor`.
+
+Watch team activity in real time:
+
+```bash
+superkick team watch TEAM_ID    # streams color-coded updates (Ctrl-C to stop)
+```
+
+Interactive agents can join an existing team as human members:
+
+```bash
+superkick agent start --team TEAM_ID --role "Code reviewer"   # --no-feed to disable digest
+```
+
+### Team lead goal
+
+Team leads default to the `:agent_signal` goal — the planning agent signals completion via the `superkick_signal_goal` MCP tool once all workers have finished and results are satisfactory. Since `agent_signal` is the default goal type, this does not need to be explicitly configured.
+
+### Driver profiles
+
+Named driver configurations can be defined under `drivers.profiles` and referenced by name from spawner configs:
+
+```yaml
+drivers:
+  profiles:
+    review:
+      type: claude_code
+      config_dir: ~/.superkick/driver-configs/review/.claude
+      env:
+        ANTHROPIC_API_KEY: <%= env("REVIEW_KEY") %>
+    worker:
+      type: claude_code
+      config_dir: ~/.superkick/driver-configs/worker/.claude
+      args: ["--verbose"]
+```
+
+Reference a profile from a spawner with `driver: { profile: :review }`. Inline overrides are deep-merged on top:
+
+```yaml
+spawners:
+  my_spawner:
+    driver:
+      profile: review
+      env:
+        EXTRA_VAR: value    # merged on top of profile env
+```
+
+### Driver cascade
+
+Driver config follows a three-level cascade (most specific wins), with deep-merging at each level:
+
+1. **Top-level default** — `driver:` in config root
+2. **Per-spawner** — `driver:` on the spawner config (string or hash, may reference a profile)
+3. **Per-role** — nested `team:` config on a `workflow: team` spawner
+
+Deep merge rules: scalar keys (`type`, `config_dir`, `command`) — more-specific wins; `args` — arrays are concatenated; `env` — hashes are merged. A string at a more-specific level replaces the entire config (no merge).
+
+```yaml
+spawners:
+  feature_team:
+    workflow: team
+    driver:
+      profile: review                    # base from named profile
+    team:
+      lead:
+        driver:                          # planning agent gets overrides
+          config_dir: ~/.superkick/driver-configs/lead/.claude
+      worker:
+        driver:                          # workers can use a different model
+          env:
+            CLAUDE_MODEL: claude-sonnet-4-6
+```
+
+### Resource limits
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `max_workers_per_team` | `5` | Maximum workers a planning agent can spawn |
+| `max_duration` | — | Hard timeout for the entire team (lead + all workers) |
+| `max_concurrent` | — | Total agents (lead + workers) across all active teams for a spawner |
+
+## Cost tracking
+
+Superkick tracks token usage and cost for spawned agents. Cost data comes from two sources:
+
+1. **PTY output parsing** — driver-specific patterns extract cost from the CLI's output (e.g. Claude Code's `Total cost: $1.50` status bar)
+2. **MCP self-reporting** — the AI CLI calls `superkick_report_cost` with cumulative totals
+
+Both sources handle cumulative-to-delta conversion automatically, so refreshing status bars or repeated reports don't double-count.
+
+### Viewing costs
+
+```bash
+superkick agent cost                    # show costs for all agents
+superkick agent cost AGENT_ID           # show cost for a specific agent
+```
+
+### Budget enforcement
+
+Budgets can be set at three levels — per-agent, per-spawner, and global:
+
+```yaml
+# config.yml
+budget:
+  max_cost_usd: 100.0               # global cap across all agents
+  window_hours: 24                   # time window for aggregate tracking
+  warning_threshold_percentage: 80   # fire warning at 80% of max
+
+spawners:
+  feature_team:
+    type: github_issues
+    budget:
+      max_cost_usd: 50.0            # aggregate cap for this spawner's agents
+      window_hours: 24
+      per_agent:
+        max_cost_usd: 5.0           # cap per individual agent
+```
+
+When a budget threshold is crossed, `budget_warning` or `budget_exceeded` lifecycle notifications fire. Budget checking only applies to spawned agents — interactive agents are always exempt.
+
+### Cost polling
+
+For headless spawned agents, the **cost poller** periodically injects the driver's cost command (e.g. `/cost`) when cost data goes stale. This ensures cost tracking stays current even for long-running agents.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `cost_poll_interval` | `300` (5 min) | How often to check for stale cost data |
+| `cost_stale_after` | `600` (10 min) | Seconds before cost data is considered stale |
+
+## Configuration
+
+Superkick loads configuration from `~/.superkick/` (override with `SUPERKICK_DIR` env var):
+
+### `config.yml`
+
+```yaml
+# Which AI CLI driver to use
+driver: claude_code
+
+# Superkick tuning
+superkick:
+  poll_interval: 30          # seconds between monitor ticks
+  idle_threshold: 5.0        # seconds idle before injection allowed
+  inject_clear_delay: 0.15   # sleep between PTY writes
+  rate_limit_backoff: 60     # seconds to sleep on API rate limit
+  error_backoff: 10          # seconds to sleep on error
+  log_level: info            # debug, info, warn, error
+  attach_escape_key: ctrl-a  # escape prefix for attach sessions (ctrl-a through ctrl-z)
+  attach_rw_idle_timeout: 300 # seconds before idle RW attach client is demoted to RO (0 to disable)
+  attach_replay_buffer_size: 65536 # bytes of output history replayed to new attach clients (hosted mode)
+  attach_max_connections: 10  # max concurrent attach users per agent (hosted mode)
+
+# Hosted server connection (omit for local mode)
+# server:
+#   url: https://superkick.example.com
+#   api_key: <%= env("SUPERKICK_API_KEY") %>
+
+# Named monitor configs (merged with auto-detected config)
+monitors:
+  github:
+    token: <%= env("GITHUB_TOKEN") %>
+    privileged: true                 # prevent AI from adding/removing this monitor
+
+# Post-injection notifications (defaults to terminal_bell when absent)
+notifications:
+  - type: terminal_bell
+  - type: command
+    run: "notify-send 'Superkick' '$SUPERKICK_MESSAGE'"
+  - type: slack
+    webhook_url: <%= env("SLACK_WEBHOOK_URL") %>
+
+# Spawners — server-level pollers that spawn new agents
+spawners:
+  shortcut:
+    token: <%= env("SHORTCUT_TOKEN") %>
+
+    search: "owner:me state:'In Progress'"
+    driver: claude_code
+    repository: my-app
+    branch_template: "fix-{{ agent_id }}"
+
+# Repository source — catalog for planning agents
+repositories:
+  api_service:
+    path: ~/projects/api-service
+    description: "Core REST API"
+    tags: [backend, ruby]
+  company:
+    type: github_organization
+    organization: my-company
+    token: <%= env("GITHUB_TOKEN") %>
+
+# Global cost budget
+budget:
+  max_cost_usd: 100.0
+  window_hours: 24
+
+# Gem-based plugins
+plugins:
+  - name: superkick-my-service
+```
+
+The config file is processed through ERB before YAML parsing, so you can use `<%= env("VAR") %>` to reference environment variables.
+
+### `config.rb`
+
+For programmatic configuration (loaded after `config.yml`, always wins):
+
+```ruby
+Superkick.use(:claude_code)
+
+Superkick.configure do |c|
+  c.poll_interval  = 15
+  c.idle_threshold = 3.0
+end
+```
+
+### Configuration settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `poll_interval` | `30` | Seconds between monitor ticks |
+| `idle_threshold` | `5.0` | Seconds the CLI must be idle before injection |
+| `inject_clear_delay` | `0.15` | Sleep between PTY write chunks |
+| `rate_limit_backoff` | `60` | Sleep on API rate limit errors |
+| `error_backoff` | `10` | Sleep on general errors before retry |
+| `log_level` | `:info` | Logger level (`:debug`, `:info`, `:warn`, `:error`) |
+| `attach_escape_key` | `ctrl-a` | Escape prefix for attach sessions (`ctrl-a` through `ctrl-z`). tmux/screen users may prefer `ctrl-b` or `ctrl-]` |
+| `attach_rw_idle_timeout` | `300` | Seconds of inactivity before an RW attach client is auto-demoted to read-only. Set to `0` to disable |
+| `attach_replay_buffer_size` | `65536` | Bytes of output history replayed to new attach clients in hosted mode |
+| `attach_max_connections` | `10` | Maximum concurrent attach user connections per agent in hosted mode |
+| `max_workers_per_team` | `5` | Maximum workers a planning agent can spawn per team |
+| `cost_poll_interval` | `300` | Seconds between cost staleness checks for headless agents |
+| `cost_stale_after` | `600` | Seconds before cost data is considered stale |
+| `notifications` | `[]` | Array of notifier configs; defaults to terminal bell when empty |
+| `repositories` | `{}` | Repository source config (see [Repository source](#repository-source)) |
+| `budget` | `{}` | Global cost budget (`max_cost_usd`, `window_hours`) |
+| `runtime` | `{}` | Agent runtime config (see [Docker runtime](#docker-runtime)) |
+| `session_recording.enabled` | `true` | Record timestamped sessions in asciicast v2 format |
+| `session_recording.max_size` | `104857600` | Max recording file size in bytes (100 MB) before rotation |
+
+### Session recording
+
+Superkick records complete, timestamped agent sessions (all input and output) in the [asciicast v2](https://docs.asciinema.org/manual/asciicast/v2/) format. Recordings are saved to `~/.superkick/recordings/<agent-id>.cast` and can be played back with `asciinema play` or in a browser via [asciinema-player](https://docs.asciinema.org/manual/player/).
+
+Session recording is enabled by default. To disable it:
+
+```yaml
+session_recording:
+  enabled: false
+```
+
+To adjust the max recording file size (default 100 MB, with one rotated `.1` file):
+
+```yaml
+session_recording:
+  max_size: 209715200  # 200 MB
+```
+
+In hosted mode, completed recordings are automatically uploaded to the hosted server when the agent exits.
+
+### Docker runtime
+
+By default, spawned agents run as local processes on the same machine. To provision agents in Docker containers instead, configure the Docker runtime:
+
+```yaml
+runtime:
+  type: docker
+  docker:
+    image: superkick/agent:latest        # required
+    host: unix:///var/run/docker.sock    # Docker daemon (default: Unix socket)
+    pull_policy: missing                 # always, missing, never
+    memory: 4G                           # container memory limit
+    cpu: 2                               # CPU cores
+    network: superkick-net               # Docker network name
+    stop_timeout: 30                     # seconds before SIGKILL
+    auto_remove: true                    # remove container after exit
+    env:                                 # additional env vars
+      GITHUB_TOKEN: <%= env("GITHUB_TOKEN") %>
+    volumes:                             # host:container mounts
+      - /home/user/.ssh:/root/.ssh:ro
+      - /home/user/.gitconfig:/root/.gitconfig:ro
+    labels:                              # container labels
+      app: superkick
+    privileged: false                    # run in privileged mode (for DinD)
+    cap_add:                             # Linux capabilities to add
+      - SYS_ADMIN
+    security_opt:                        # security options
+      - seccomp:unconfined
+    container_runtime: sysbox-runc       # OCI runtime (for unprivileged DinD)
+    registry:                            # private registry auth
+      username: <%= env("DOCKER_REGISTRY_USER") %>
+      password: <%= env("DOCKER_REGISTRY_PASSWORD") %>
+      server: ghcr.io
+    tls:                                 # TLS for TCP connections
+      ca: /path/to/ca.pem
+      cert: /path/to/cert.pem
+      key: /path/to/key.pem
+```
+
+When running with a local server, the runtime auto-mounts the server's Unix socket directory into the container for seamless connectivity. Container names follow the pattern `superkick-<agent-id>`. All containers are labeled with `superkick.agent_id` for identification.
+
+### Filesystem layout
+
+```
+~/.superkick/
+  config.yml          # YAML configuration
+  config.rb           # Ruby configuration (optional)
+  superkick.log          # Server log file
+  sessions/           # JSON agent persistence files
+  templates/          # User template overrides
+  teams/              # Team logs (ndjson, one per team)
+  logs/               # Per-agent output logs
+  recordings/         # Per-agent session recordings (asciicast v2)
+  run/                # Runtime files (transient)
+    server.sock       # Server IPC socket
+    server.pid        # Server PID file
+    buffer-<id>.sock  # Per-agent PTY buffer sockets
+    attach-<id>.sock  # Per-agent attach sockets
+```
+
+## CLI commands
+
+| Command | Description |
+|---------|-------------|
+| `superkick server start [-d]` | Start the server (`-d` to daemonize) |
+| `superkick server stop` | Send SIGTERM to the server |
+| `superkick server status` | Show server and agent status |
+| `superkick server log [-n LINES]` | Tail the server log file |
+| `superkick agent start [--driver NAME] [-- ARGS]` | Launch an AI CLI through the PTY proxy |
+| `superkick agent list [--json]` | List all active agents |
+| `superkick agent log AGENT_ID [-n LINES] [-f]` | Tail an agent's output log |
+| `superkick agent stop AGENT_ID` | Stop a spawned agent |
+| `superkick agent attach AGENT_ID [-i] [-f]` | Attach to a running agent (read-only; `-i` for read-write; `-f` / `--force` to take over RW from another client) |
+| `superkick agent claim AGENT_ID` | Claim a spawned agent (pause autonomous operation) |
+| `superkick agent unclaim AGENT_ID` | Release a claimed agent back to autonomous operation |
+| `superkick agent cost [AGENT_ID]` | Show cost tracking for an agent or all agents |
+| `superkick team list [--json]` | List active teams |
+| `superkick team status TEAM_ID [--full]` | Show team log summary (or full log) |
+| `superkick team watch TEAM_ID [--no-color]` | Watch team activity in real time |
+| `superkick team stop TEAM_ID` | Terminate all agents in a team |
+| `superkick spawner list [--json]` | List configured spawners and their status |
+| `superkick spawner start NAME` | Start a stopped spawner |
+| `superkick spawner stop NAME` | Stop a running spawner |
+| `superkick spawner install-templates [--force]` | Copy default spawner Liquid templates |
+| `superkick approve ID` | Approve a pending spawn |
+| `superkick reject ID [--reason REASON]` | Reject a pending spawn |
+| `superkick approvals [--json] [--rejections]` | List pending approvals or rejections |
+| `superkick monitor list` | List available monitor types |
+| `superkick monitor install-templates [--force]` | Copy default monitor Liquid templates to `~/.superkick/templates/` |
+| `superkick mcp configure` | Configure the MCP server for the active driver |
+| `superkick completion SHELL` | Print shell completion script (`bash` or `zsh`) |
+
+Global option: `--dir PATH` (or `-C PATH`) overrides the Superkick base directory.
+
+## MCP tools
+
+These tools are exposed via the MCP stdio server (`superkick mcp`) and called by the AI CLI. In local mode, tool calls are handled by `McpServer` over a Unix socket. In hosted mode, `Hosted::McpProxy` transparently forwards requests to the hosted server's MCP endpoint over HTTP. The agent's identity is read from the `SUPERKICK_AGENT_ID` environment variable (set automatically by the PTY proxy) — tools do not require `agent_id` as a parameter:
+
+| Tool | Description |
+|------|-------------|
+| `superkick_discover_monitors` | List available monitor types and probe-detected configs |
+| `superkick_discover_goals` | List available goal types and their configuration options |
+| `superkick_add_monitor` | Add a monitor to this agent |
+| `superkick_remove_monitor` | Remove a monitor from this agent |
+| `superkick_signal_goal` | Signal goal status (`completed`, `failed`, `errored`, `in_progress`) |
+| `superkick_report_cost` | Report cumulative token usage and cost (delta computed server-side) |
+| `superkick_status` | Report server and agent status |
+| `superkick_spawn_worker` | Spawn a worker agent in a specific repository (with optional `role` label) |
+| `superkick_discover_repositories` | List available repositories with descriptions, tags, and dependencies |
+| `superkick_post_update` | Broadcast a status update or send a targeted message to a teammate |
+| `superkick_team_status` | Read the team log summary or full history |
+| `superkick_list_teammates` | List all agents on the team with roles and status |
+| `superkick_publish_artifact` | Share structured data with the team (plans, specs) |
+| `superkick_read_artifact` | Read an artifact published by a teammate |
+| `superkick_list_artifacts` | List all artifacts for the team |
+
+## Extending Superkick
+
+Superkick is designed for extension via eight plugin points:
+
+- **Drivers** — add support for a new AI CLI. See the [driver skill](skills/superkick-new-driver/SKILL.md) for a step-by-step guide.
+- **Monitors** — add a new event source (CI system, chat service, etc.). See the [monitor skill](skills/superkick-new-monitor/SKILL.md) for a step-by-step guide.
+- **Spawners** — add a new agent spawning trigger (project management tools, queues, etc.). See the [spawner skill](skills/superkick-new-spawner/SKILL.md) for a step-by-step guide.
+- **Goals** — define completion criteria for spawned agents (PR merged, command exit code, etc.). See the [goal skill](skills/superkick-new-goal/SKILL.md) for a step-by-step guide.
+- **Version control adapters** — add support for a new VCS (Mercurial, Subversion, etc.). See the [version control skill](skills/superkick-new-version-control/SKILL.md) for a step-by-step guide.
+- **Repository sources** — add a new repository discovery source (GitLab, Bitbucket, a custom catalog API). See the [repository source skill](skills/superkick-new-repository-source/SKILL.md) for a step-by-step guide.
+- **Agent runtimes** — add a new compute backend for spawned agents (Kubernetes, Firecracker, etc.). The runtime interface is documented in [CLAUDE.md](CLAUDE.md).
+- **Notifiers** — add a new notification channel (OS notifications, chat webhooks, sound effects, etc.). See the [notifier skill](skills/superkick-new-notifier/SKILL.md) for a step-by-step guide.
+
+All eight can be extracted into standalone gems and loaded via `plugins:` in `config.yml`.
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run the full test suite
+bundle exec rake test
+
+# Run a single test file
+bundle exec rake test TEST=test/monitor_test.rb
+
+# Run a specific test by name
+bundle exec rake test TEST=test/monitor_test.rb TESTOPTS="-n test_dispatches_event"
+
+# Run all tests matching a name pattern
+bundle exec rake test TESTOPTS="-n /rate_limit/"
+
+# Lint with Standard.rb
+bundle exec rake standard
+
+# Auto-fix lint violations
+bundle exec rake standard:fix
+
+# Run tests + lint together (the default)
+bundle exec rake
+```
+
+For a detailed guide to the architecture, key classes, design patterns, and how to extend Superkick, see [CLAUDE.md](CLAUDE.md).
+
+### Project structure
+
+```
+lib/superkick/
+  cli.rb                 # Thor CLI interface (server, agent, monitor, spawner, team, mcp)
+  cli/                   # CLI subcommands (server, agent, monitor, spawner, team, mcp)
+  server.rb              # Server lifecycle
+  mcp_server.rb          # MCP stdio server — local mode (16 tools)
+  hosted/mcp_proxy.rb    # MCP stdio-to-HTTP proxy — hosted mode
+  configuration.rb       # Global settings
+  yaml_config.rb         # config.yml loader
+  version.rb             # Gem version constant
+  pty_proxy.rb           # PTY wrapper (stdin/output/inject threads)
+  input_buffer.rb        # Partial input tracking + guard state
+  injection_queue.rb     # Agent-side injection queue with TTL, priority, supersede-by-key
+  injection_guard.rb     # PatternGuard data class for suppressing injection
+  injector.rb            # Injection orchestration
+  inject_handler.rb      # Monitor event handler
+  output_logger.rb       # Tees PTY output to per-agent log files
+  history_buffer.rb      # Ring buffer of recent PTY output for attach replay
+  process_runner.rb      # Subprocess execution with reliable timeouts
+  connection.rb          # Newline-delimited JSON framing (shared by control + data plane)
+  client_registry.rb     # Shared module for client factory methods
+  registry.rb            # Test isolation for class-level registries
+  buffer/
+    server.rb            # Per-agent buffer socket server
+    client.rb            # Buffer client (Unix socket transport)
+  attach/
+    server.rb            # Per-agent attach endpoint with RW exclusivity
+    client.rb            # CLI client for attach sessions
+    protocol.rb          # Binary frame protocol for attach
+  control/
+    server.rb            # Control plane Unix socket server
+    client.rb            # Control plane client (Unix socket transport)
+    reply.rb             # Typed response wrapper
+  hosted/
+    bridge.rb            # Abstract base class for agent-side WebSocket bridges
+    buffer/              # Hosted buffer transport (client, bridge, relay, relay_store)
+    attach/              # Hosted attach transport (client, bridge, relay, relay_store)
+    control/
+      client.rb          # HTTPS control client for remote servers
+  template_renderer.rb   # Liquid rendering with template filters
+  template_filters.rb    # Core Liquid filters (time, short_sha, truncate)
+  liquid.rb              # Liquid DSL module for declaring filters/blocks/tags
+  drop.rb                # Base class for Liquid Drops with serialize/rehydrate
+  drops.rb               # Core Drops (TeamDrop, SpawnerDrop, MonitorDrop, AgentDrop)
+  notifier.rb            # Abstract Notifier base class + registry
+  notifier_state_store.rb # Injectable state storage for stateful notifiers
+  notifier_template.rb   # Structured template rendering for notifiers
+  notification_dispatcher.rb # Stateful notification dispatcher
+  notifiers/             # Built-in notifiers (terminal_bell, command)
+  poller.rb              # Abstract Poller base class — shared run loop
+  monitor.rb             # Abstract Monitor base class + Monitor::Probe
+  spawner.rb             # Abstract Spawner base class (server-level pollers)
+  spawn/
+    agent_spawner.rb     # Repository acquisition + agent subprocess lifecycle
+    handler.rb           # Spawner event handler (dedup, approval gates)
+    injector.rb          # Kickoff prompt injection into spawned agents
+    approval_store.rb    # Pending spawn approvals + rejection tracking
+    workflow_executor.rb # Orchestrates workflow spawns (on_complete/on_fail)
+    workflow_validator.rb # Static cycle detection for workflow configs
+  agent.rb               # Live agent object (id, monitors, team, cost)
+  agent_store.rb         # Agent registry (JSON persistence)
+  agent/
+    runtime.rb           # Abstract runtime base class + registry
+    runtimes/
+      local.rb           # Local process spawning (default)
+  team/
+    log.rb               # Append-only ndjson team communication log
+    log_store.rb         # Server-level lazy registry of Team::Log instances
+    log_entry_drop.rb    # Liquid Drop for team log entries
+    artifact_store.rb    # Per-team persistent artifact storage
+    log_monitor.rb       # Polls team log, injects digest events
+    log_notifier.rb      # Internal notifier that writes team log entries
+  supervisor.rb          # Supervisor — monitor + spawner + goal checker thread lifecycle
+  repository_source.rb   # Repository catalog (static, directory, composite)
+  version_control.rb     # Abstract VersionControl base class + registry
+  version_controls/      # Built-in VCS adapters (git)
+  cost_accumulator.rb    # Thread-safe per-agent cost tracking
+  cost_extractor.rb      # Line-buffered PTY output cost parser
+  cost_poller.rb         # Periodic cost command injection for stale agents
+  budget_checker.rb      # Multi-level budget evaluation (agent/spawner/global)
+  driver.rb              # Abstract Driver base class + CostPattern + registry
+  driver/
+    profile_source.rb    # Named driver profile sources
+  drivers/               # Built-in CLI drivers (claude_code, copilot, codex, gemini, goose)
+  goal.rb                # Abstract Goal base class + registry
+  goals/                 # Built-in goals (agent_exit, command, agent_signal)
+  integrations/          # Built-in integrations (github, circleci, shortcut, shell, slack,
+                         #   bugsnag, datadog, honeybadger, docker)
+```
+
+## License
+
+[Business Source License 1.1](LICENSE) — source-available with production use
+permitted (except competing SaaS offerings). Converts to [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+after four years per version.
+
+A [commercial license](LICENSE-COMMERCIAL.md) is available for use cases outside
+the BSL's Additional Use Grant. See the [CLA](CLA.md) for contributor terms.