# the-agency

A tiered, multi-agent orchestration framework that decomposes high-level goals into executable work across five specialised tiers (T1–T5), backed by a SQLite blackboard and pluggable adapters for LLM, VCS, notifications, and agent runtimes.

---

## What is the-agency?

the-agency implements a **structured, goal-anchored pipeline** where every task flows through a hierarchy:

| Tier | Role | Responsibility |
|---|---|---|
| T1 | Visionary | Decomposes a goal into workstreams; sets the immutable `goal_anchor` |
| T2 | Architect | Designs technical architecture and subtasks for each workstream |
| T3 | Squad Lead | Breaks architecture subtasks into concrete implementation tasks |
| T4 | Implementer | Produces code, config, and other artifacts |
| T5 | Verifier | Reviews T4 artifacts against acceptance criteria |

Each tier produces structured JSON. A central **Blackboard** (SQLite) tracks all runs, workstreams, briefs, and events. An **EscalationHandler** decides whether to retry, salvage, or escalate failures automatically.

---

## Quick Start

### Prerequisites

- Python 3.11+
- An Anthropic API key (or other supported LLM provider)

### Installation

```bash
git clone <your-repo-url> the-agency
cd the-agency
git submodule update --init --recursive   # pulls agents/ persona library
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env                      # add your API keys
```

### Configuration

Edit `config/team.yaml` to set:
- `run.goal` — the top-level objective for this run
- `adapters` — which adapter implementations to use
- `models.provider` — your LLM provider
- `retry_defaults` — per-failure-type retry budgets

Edit `config/role_registry.yaml` to map tier+role keys to agent persona files in `agents/`.

### Running (Phase 2)

```bash
# Phase 2 team_runner is stubbed — see core/team_runner.py
python -m core.team_runner --config config/team.yaml
```

---

## How to Add a New Adapter

1. **LLM adapter** — subclass `adapters/base/llm.py:LLMAdapter`, implement `complete()` and `resolve_model()`, place the file in `adapters/llm/`.
2. **VCS adapter** — subclass `adapters/base/vcs.py:VCSAdapter`, implement `create_branch()`, `commit()`, `create_pr()`, `get_pr_status()`, place in `adapters/vcs/`.
3. **Notify adapter** — subclass `adapters/base/notify.py:NotifyAdapter`, implement `send()`, place in `adapters/notify/`.
4. **Runtime adapter** — subclass `adapters/base/runtime.py:RuntimeAdapter`, implement `spawn()`, `get_result()`, `kill()`, place in `adapters/runtime/`.
5. Register the adapter key in `config/team.yaml` under `adapters.<type>: <your_key>`.
6. Add adapter loading logic in `core/team_runner.py` (Phase 2).

---

## How to Extend the Role Registry

The role registry (`config/role_registry.yaml`) maps tier+role keys to agent persona files in the `agents/` submodule.

To add a new role:

1. Confirm (or add) the persona `.md` file exists under `agents/`.
2. Add an entry under the appropriate tier key in `config/role_registry.yaml`:

```yaml
t4:
  my_new_role: agents/engineering/engineering-my-new-role.md
```

3. Use `my_new_role` as the `role` field when constructing a `TaskBrief` for T4.

---

## Build Order Reference

The bootstrap was assembled in this order; Phase 2 continues from step 13.

| Step | Artifact | Description |
|---|---|---|
| 1 | `agents/` | Git submodule — agent persona library |
| 2 | Directory structure | `core/`, `adapters/`, `prompts/`, `config/`, `runs/` |
| 3 | `config/role_registry.yaml` | Tier→role→persona mapping |
| 4 | `core/task_brief.py` | Dataclass schema for all work units |
| 5 | `core/blackboard.py` | SQLite-backed shared state store |
| 6 | `adapters/base/*.py` | Abstract base classes for all adapter types |
| 7 | `core/escalation.py` | Failure classification and retry/escalate logic |
| 8 | `prompts/*.md` | System prompts for T1–T5 agents |
| 9 | `config/team.yaml` | Run configuration and model map |
| 10 | `README.md` | This file |
| 11 | `requirements.txt` | Python dependencies |
| 12 | `.gitignore` | Standard Python ignores + run DB exclusion |
| 13 | Phase 2 stubs | Adapter implementations, team runner |

---

## Project Structure

```
the-agency/
├── agents/                   # git submodule — agent persona .md files
├── core/
│   ├── task_brief.py         # TaskBrief dataclass
│   ├── blackboard.py         # SQLite-backed state store
│   ├── escalation.py         # EscalationHandler
│   └── team_runner.py        # [Phase 2] Orchestration entry point
├── adapters/
│   ├── base/                 # Abstract base classes
│   ├── llm/                  # LLM adapter implementations
│   ├── vcs/                  # VCS adapter implementations
│   ├── notify/               # Notification adapter implementations
│   └── runtime/              # Agent runtime adapter implementations
├── prompts/                  # T1–T5 system prompts
├── config/
│   ├── team.yaml             # Run configuration
│   └── role_registry.yaml    # Tier/role → persona file mapping
├── runs/                     # Per-run state (blackboard.db files)
├── requirements.txt
└── .gitignore
```