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

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)

# 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:

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