feat: initial bootstrap — structure, task_brief, blackboard, adapter bases, escalation, prompts
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
135
README.md
Normal file
135
README.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user