136 lines
5.2 KiB
Markdown
136 lines
5.2 KiB
Markdown
# 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
|
||
```
|