# Zeroclaw — Agentic Agency Architecture

This directory defines the **agent organization** that runs the day-to-day work of
the agency (software, web design, ads, social, marketing, support, licenses,
accounting). Agent behavior lives here as versioned markdown; deterministic
infrastructure (money, licenses, signing, numbering) lives in the Rust crates.

## How it fits together

```
agents/      canonical agent specs by department (one .md per agent)
skills/      reusable procedures (SKILL.md + scripts + templates)
playbooks/   human-readable SOPs
schemas/      handoff, deliverable, approval JSON schemas
policies/     autonomy levels, budgets, allow/deny lists
routing.toml  model routing by tier (one place to change)
crates/       Rust workspace: aos-mcp, aos-policy, aos-license, aos-ledger, aos-sync
evals/        golden tasks per agent/skill
runtimes/     generated output for claude-code, desktop, hermes (aos-sync writes here)
docs/         PRD, ADRs
```

## Three rules

1. **Agents are files, tools are code.** Prompt-defined behavior in `agents/`;
   money/license/signing logic in Rust crates. Never trust an LLM to do math.
2. **One source of truth.** Agency OS (Next.js + Postgres) holds clients,
   projects, leads, licenses, invoices. Agents touch it only through the
   `aos-mcp` MCP server — no private state.
3. **Least privilege + human gates.** Each agent gets only the tools in its
   spec frontmatter. Spending, publishing, invoices, client contact,
   revocation, deletes → always human-approved regardless of autonomy level.

## Using an agent from Claude Code

Agent specs in `agents/<dept>/<name>.md` compile (via `aos-sync`) to
`.claude/agents/*.md` subagents. Skills in `skills/*/SKILL.md` compile to
`.claude/skills/`. Run `cargo run -p aos-sync` after editing specs.

## Autonomy levels (see policies/autonomy.md)

| Level | Meaning |
|-------|---------|
| L0 | Read/analyze only (audits, research, reports) |
| L1 | Drafts; human approves before anything leaves the system |
| L2 | Acts alone within caps and reversible scope (triage, internal tasks) |
| L3 | Full autonomy — not used initially |

Always human-approved: spending, publishing publicly, sending invoices,
first client contact, revoking licenses, deleting data/instances/DNS,
production deploys, anything filed with authorities, contract changes.

## Model routing (routing.toml)

| Tier | Used for | Model class |
|------|----------|-------------|
| T1 | Orchestrator, architect, reviewer, security | strongest Claude |
| T2 | Department leads, complex workers | mid-tier Claude |
| T3 | Bulk: classification, drafts, summaries, reports | GLM / DeepSeek / small Claude |

Rule: no T3 model touches a tool marked `risk: high` without a T1/T2 reviewer pass.

## Compliance (blocking, EU/German)

DSGVO, GoBD, UWG, DDG/Impressum, ad and cookie rules built in. See
`policies/compliance.md`. Personal data stays on EU-compliant providers by
default; using third-party backends (Z.ai, DeepSeek) for client personal data
needs a legal review first.

## Roadmap

- **Phase 0** — spec format, handoff schema, `aos-sync` MVP, `aos-mcp`
  read-only, autonomy policy v1.
- **Phase 1** — Orchestrator + Software dept + Support + Leads Finder.
  Approval inbox in AOS. Run on real internal projects.
- **Phase 2** — Accounting (`aos-ledger`), License Manager (`aos-license`),
  Project Manager, daily/weekly reports via Hermes.
- **Phase 3** — Marketing/SEO, Social, Ads (draft-only, strict spend gate),
  Web Design.
- **Phase 4** — `aos-eval` regression suite, cost dashboards, L2 autonomy.

Ship one department end to end before adding the next. Measure with eval
tasks and cost per task.