feat: zeroclaw agentic agency architecture — agents, skills, Rust crates
- 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
This commit is contained in:
1 parent
d18c463ffd
commit
136379c666
60 files changed
+4776
No files matched your search
@@ -0,0 +1,83 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user