Opus Vault

agency-company-structure

4 min read

Design: Agency Company Structure

The Idea

Model Opus as a company. Agents are employees with defined roles, a reporting hierarchy, and structured output. You are management — you set direction, review key decisions, and receive summaries. Agents do the work and report up the chain.

Org Chart

┌─────────────────────────────┐
│     You (Management/CEO)    │
│  Sets priorities, approves  │
└──────────────┬──────────────┘
               │
┌──────────────▼──────────────┐
│     Tech Lead (Orchestrator)│
│  Breaks down work, assigns, │
│  reviews, reports up        │
└──┬───────┬───────┬──────────┘
   │       │       │
┌──▼──┐ ┌──▼──┐ ┌──▼──┐
│ Dev │ │ Dev │ │ QA  │
│  A  │ │  B  │ │     │
└─────┘ └─────┘ └─────┘

Roles

RoleResponsibilityReports toModel
Tech LeadReceives feature, breaks into tasks, assigns to devs, reviews their output, writes summary reportYouOpus
DeveloperImplements a specific task (code, tests, docs). Writes a task report when doneTech LeadSonnet
QA ReviewerReviews code for bugs, style, security. Writes review reportTech LeadSonnet
PM (future)Tracks progress across features, writes daily digestYouHaiku

The Tech Lead is the key agent — it’s the orchestrator that runs the pipeline. Devs and QA are sub-agents it launches.

Reporting System

Report Types

  1. Task Report — written by Dev after completing a task
  2. Review Report — written by QA after reviewing code
  3. Feature Report — written by Tech Lead after a feature is complete (aggregates task + review reports)
  4. Daily Digest — summary of all work done that day (future, by PM)

Report Storage

vault/00_system/logs/agent-reports/
├── 2026-03-13/
│   ├── feature-FR-042-auth-refactor.md      # Tech Lead summary
│   ├── task-FR-042-01-extract-middleware.md  # Dev task report
│   ├── task-FR-042-02-add-tests.md          # Dev task report
│   └── review-FR-042.md                     # QA review report
└── 2026-03-14/
    └── ...

Reports in date folders. Feature report links to its task/review reports. This gives you:

  • Per-feature view: read the feature report for the full picture
  • Per-day view: browse a date folder to see everything that happened
  • Audit trail: every agent decision is documented

Report Template (Task)

---
type: task-report
agent: developer
feature: FR-042
task: 01-extract-middleware
status: complete | blocked | partial
created: 2026-03-13T14:32:00
duration_seconds: 45
---
 
# Task: Extract auth middleware
 
## What was done
- Extracted auth logic from routes into `src/middleware/auth.py`
- Added type hints for request context
 
## Files changed
- `src/middleware/auth.py` (new)
- `src/routes/api.py` (modified)
 
## Decisions made
- Used decorator pattern instead of class-based middleware (simpler for current scale)
 
## Blockers / Notes
- None

Report Template (Feature — Tech Lead)

---
type: feature-report
agent: tech-lead
feature: FR-042
status: complete | needs-review | blocked
created: 2026-03-13T15:10:00
tasks_total: 3
tasks_complete: 3
---
 
# Feature Report: FR-042 Auth Refactor
 
## Summary
Refactored auth into standalone middleware. All tasks complete, QA passed.
 
## Tasks
- [x] 01-extract-middleware — complete
- [x] 02-add-tests — complete
- [x] 03-update-docs — complete
 
## QA Result
Passed. No issues found. See [[review-FR-042]].
 
## For Management
- Ready to merge
- No open decisions

How It Works (Pipeline)

1. You assign a feature (or Tech Lead picks from planned/)
2. Tech Lead reads the FR, breaks it into tasks
3. Tech Lead launches Dev agents in parallel where possible
4. Each Dev writes a task report when done
5. Tech Lead launches QA agent to review all changes
6. QA writes review report
7. Tech Lead aggregates into feature report
8. Feature report surfaces to you for final review

Implementation Plan

Phase 1: Agent Definitions

  • Define tech-lead.md agent in .claude/agents/
  • Define developer.md agent
  • Define qa-reviewer.md agent
  • Create report templates in vault/_templates/

Phase 2: Reporting Infrastructure

  • Create vault/00_system/logs/agent-reports/ directory
  • Build report-writing logic into agent prompts (agents write their own reports)
  • Tech Lead reads sub-agent reports and aggregates

Phase 3: Orchestration

  • Tech Lead agent prompt includes the full pipeline logic
  • A /build skill kicks off the pipeline for a given FR
  • Tech Lead manages the sub-agents via Task tool

Phase 4: Daily Digest (future)

  • PM agent scans today’s reports folder
  • Writes a daily digest to vault/30_daily/briefings/

Key Design Decisions to Make

  1. How autonomous? Should Tech Lead auto-pick features from planned/, or always wait for you to assign?
  2. Git strategy: One branch per feature? Per task? Tech Lead creates PR?
  3. Escalation: When should agents escalate to you vs. making their own call? (e.g., architectural decisions, unclear requirements)
  4. Model routing: Opus for Tech Lead (needs judgment), Sonnet for Devs (needs speed), Haiku for PM (needs to be cheap)?
  5. Report verbosity: Full reports for everything, or only for non-trivial work?

What This Buys You

  • Visibility: You see what happened without reading diffs
  • Delegation: Assign a feature, come back to a report
  • Quality gate: QA is built into the pipeline, not an afterthought
  • History: Every decision documented, searchable in Obsidian
  • Scalability: Add more specialist agents (security reviewer, docs writer) by adding roles

Graph View

Backlinks