Z User
136379c666
- 18 agent specs across Software, Support, Marketing, Cross-cutting (orchestrator + 7 software + 5 support + 3 cross-cutting + leads-finder) - 8 reusable skills (handoff, pr-review, dokploy-deploy, campaign-structure, content-calendar, ticket-triage, license-lifecycle, invoice-draft) - 3 JSON schemas: handoff, deliverable, approval - Policies: autonomy levels, tool risk classification, compliance (DSGVO/GoBD/UWG) - routing.toml: model tiers T1/T2/T3 + provider config (PII gating) - Rust workspace (5 crates, all compile + 16 tests pass): - aos-mcp: tool registry + risk tagging - aos-policy: autonomy levels, budget enforcement, approval requests - aos-license: ed25519 license issue/verify (real crypto + CLI binary) - aos-ledger: integer-cents money math, gapless numbering, VAT, audit chain - aos-sync: frontmatter validator (18/18 specs pass), CLI binary - CLAUDE.md entry point with architecture overview + roadmap
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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.
|