0 Fork 0

Files

T

Z User 136379c666 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

2026-10-30 13:01:03 +00:00

3.6 KiB

Raw Blame History

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

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.
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.
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.

3.6 KiB Raw Blame History