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
1 parent d18c463ffd
commit 136379c666
@@ -0,0 +1,44 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zeroclaw.dev/schemas/approval.json",
+  "title": "ApprovalRequest",
+  "description": "A request that pauses a task at a human gate. Every high-risk action (spend, publish, send, revoke, delete, deploy, file-with-authorities) produces one of these. Lives in the AOS approval inbox + notifications.",
+  "type": "object",
+  "required": ["approval_id", "task_id", "agent", "action", "risk", "rationale", "diff_summary"],
+  "additionalProperties": false,
+  "properties": {
+    "approval_id": { "type": "string", "description": "AOS-generated cuid for this approval." },
+    "task_id": { "type": "string", "pattern": "^AOS-\\d+$" },
+    "agent": { "type": "string", "description": "Agent requesting approval." },
+    "action": {
+      "enum": [
+        "spend",
+        "publish_public",
+        "send_invoice",
+        "send_client_communication",
+        "send_outreach",
+        "revoke_license",
+        "delete_data",
+        "delete_instance",
+        "delete_dns",
+        "production_deploy",
+        "db_migration_live",
+        "file_with_authorities",
+        "contract_change",
+        "budget_change",
+        "campaign_activation"
+      ],
+      "description": "The category of irreversible/external action. Each maps to a hard rule in the policy crate."
+    },
+    "risk": { "enum": ["medium", "high", "critical"] },
+    "rationale": { "type": "string", "description": "Why the agent believes this action is needed, in 1-3 sentences." },
+    "diff_summary": { "type": "string", "description": "Human-readable summary of what will change if approved (e.g. 'Spend 50 EUR on Google Ads campaign X', 'Delete instance abc.dfmpanel.eu', 'Send invoice RE-2026-0042 to client@bauer.de')." },
+    "payload": {
+      "type": "object",
+      "description": "Structured details for the approver to inspect. Shape varies by action; validated by the policy crate.",
+      "additionalProperties": true
+    },
+    "expires_at": { "type": "string", "format": "date-time", "description": "Optional: if not approved by this time, the task auto-fails." },
+    "estimated_cost_eur": { "type": "number", "minimum": 0 }
+  }
+}
@@ -0,0 +1,68 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zeroclaw.dev/schemas/deliverable.json",
+  "title": "AgentDeliverable",
+  "description": "Standard result envelope returned by a worker/lead agent. The caller (usually a lead or orchestrator) consumes this without re-parsing free-form chat.",
+  "type": "object",
+  "required": ["task_id", "agent", "status"],
+  "additionalProperties": false,
+  "properties": {
+    "task_id": { "type": "string", "pattern": "^AOS-\\d+$" },
+    "agent": { "type": "string", "description": "Name of the agent that produced this deliverable." },
+    "status": {
+      "enum": ["done", "blocked", "needs_review", "needs_approval", "failed"],
+      "description": "done = complete and self-verified. needs_review = ready for reviewer/QA. needs_approval = paused at a human gate."
+    },
+    "deliverables": {
+      "type": "array",
+      "description": "Concrete outputs — AOS IDs, file paths, URLs, or inline content.",
+      "items": {
+        "type": "object",
+        "required": ["kind", "ref"],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "enum": ["aos_record", "file", "url", "inline", "diff"] },
+          "ref": { "type": "string", "description": "AOS id, file path, URL, or inline content." },
+          "label": { "type": "string" }
+        }
+      }
+    },
+    "open_questions": {
+      "type": "array",
+      "description": "Questions for the human or the orchestrator that block progress.",
+      "items": { "type": "string" }
+    },
+    "risks": {
+      "type": "array",
+      "description": "Anything the caller should know: assumptions made, fragile steps, compliance flags.",
+      "items": {
+        "type": "object",
+        "required": ["description"],
+        "additionalProperties": false,
+        "properties": {
+          "description": { "type": "string" },
+          "severity": { "enum": ["low", "medium", "high"] },
+          "mitigation": { "type": "string" }
+        }
+      }
+    },
+    "cost": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tokens": { "type": "integer", "minimum": 0 },
+        "eur": { "type": "number", "minimum": 0, "description": "External spend (ads, API fees). 0 if none." }
+      }
+    },
+    "review_verdict": {
+      "type": "object",
+      "description": "Only set when this deliverable is a reviewer's verdict on another task.",
+      "additionalProperties": false,
+      "properties": {
+        "reviewed_task_id": { "type": "string" },
+        "verdict": { "enum": ["approved", "changes_requested", "rejected"] },
+        "notes": { "type": "string" }
+      }
+    }
+  }
+}
@@ -0,0 +1,66 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://zeroclaw.dev/schemas/handoff.json",
+  "title": "AgentHandoff",
+  "description": "Structured task delegation between agents. Every delegation uses this shape so messages stay debuggable. Free-form chat between agents is avoided.",
+  "type": "object",
+  "required": ["task_id", "from", "to", "goal", "definition_of_done"],
+  "additionalProperties": false,
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "description": "AOS task ID (e.g. AOS-1423). Ties all tool calls, logs and approvals together.",
+      "pattern": "^AOS-\\d+$"
+    },
+    "from": {
+      "type": "string",
+      "description": "Agent name handing off (e.g. 'orchestrator', 'ads-lead').",
+      "minLength": 1
+    },
+    "to": {
+      "type": "string",
+      "description": "Agent name receiving the task.",
+      "minLength": 1
+    },
+    "goal": {
+      "type": "string",
+      "description": "One-sentence statement of what 'done' looks like, in business terms.",
+      "minLength": 1
+    },
+    "inputs": {
+      "type": "array",
+      "description": "References to inputs the receiving agent can read (AOS IDs, asset folders, brief IDs).",
+      "items": { "type": "string" }
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "budget_eur": { "type": "number", "minimum": 0, "description": "Hard spend cap in EUR for this task. 0 = no spend allowed." },
+        "max_tokens": { "type": "integer", "minimum": 0, "description": "Token cap for this task's agent calls." },
+        "deadline": { "type": "string", "format": "date-time" },
+        "autonomy": { "enum": ["L0", "L1", "L2"], "description": "Overrides the agent's default autonomy for this task. L3 not used initially." }
+      }
+    },
+    "definition_of_done": {
+      "type": "array",
+      "description": "Checklist of concrete, verifiable outcomes. Empty array is invalid.",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "output_format": {
+      "enum": ["aos_deliverable", "report", "draft", "review_verdict", "data"],
+      "description": "How the result must be shaped so the caller can consume it without re-parsing."
+    },
+    "needs_approval_for": {
+      "type": "array",
+      "description": "Specific actions in this task that MUST pause for human approval (spend, publish, send, revoke, delete, deploy...).",
+      "items": { "type": "string" }
+    },
+    "context_refs": {
+      "type": "array",
+      "description": "Optional AOS records to load into context (client_id, project_id, contract_id).",
+      "items": { "type": "string" }
+    }
+  }
+}