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
74 lines
3.9 KiB
Markdown
74 lines
3.9 KiB
Markdown
---
|
|
name: handoff
|
|
version: 1.0.0
|
|
applies_to: [orchestrator, software-lead, support-lead, ads-lead, social-lead, marketing-lead, accounting-lead, license-lead]
|
|
risk: low
|
|
---
|
|
|
|
# Structured Delegation (AgentHandoff)
|
|
|
|
## When to use
|
|
Any time one agent needs another agent to do work. There is no free-form chat
|
|
between agents — every delegation is a structured `AgentHandoff` so the task
|
|
tree stays debuggable and the costs stay aggregatable.
|
|
|
|
## Steps
|
|
1. Read the goal and the originating `task_id` (AOS-NNNN) from the parent task.
|
|
2. Identify the target department lead by routing rule (software→`software-lead`,
|
|
support→`support-lead`, ads→`ads-lead`, social→`social-lead`, marketing→
|
|
`marketing-lead`, licenses→`license-lead`, accounting→`accounting-lead`).
|
|
3. Load the target agent's spec from `agents/<dept>/<name>.md` and read its
|
|
`tools`, `forbidden`, `budget`, and `autonomy` frontmatter — the handoff must
|
|
respect every one of those, or you have the wrong agent.
|
|
4. Compose the `AgentHandoff` per `schemas/handoff.json`:
|
|
- `task_id` (the AOS id), `from`, `to`, `goal` (one business sentence),
|
|
- `inputs[]` (AOS record ids / asset refs the worker can read),
|
|
- `constraints` (budget_eur, max_tokens, deadline, autonomy override),
|
|
- `definition_of_done[]` (≥1 concrete verifiable outcome),
|
|
- `output_format` (one of: aos_deliverable, report, draft, review_verdict, data),
|
|
- `needs_approval_for[]` (every high-risk action this task may reach —
|
|
spend, publish, send, revoke, delete, deploy, migration, etc.),
|
|
- `context_refs[]` (client_id, project_id, contract_id as needed).
|
|
5. Validate the payload against `schemas/handoff.json` before dispatch. If
|
|
validation fails, fix and re-validate — never dispatch an invalid handoff.
|
|
6. Dispatch via the AOS handoff endpoint; log the dispatch as a note on the
|
|
parent task with `to`, `goal`, and the deadline.
|
|
7. Await the receiving agent's `AgentDeliverable` (`schemas/deliverable.json`).
|
|
While waiting, do nothing else on this task branch.
|
|
8. On receipt, validate the deliverable shape. Then:
|
|
- `done` → aggregate `cost` into the parent task, mark the branch complete.
|
|
- `needs_review` → route to `code-reviewer` / `reviewer` / lead as relevant.
|
|
- `needs_approval` → surface the `ApprovalRequest` to the human owner; do not
|
|
approve it yourself.
|
|
- `blocked` → read `open_questions[]`; answer from AOS context or escalate
|
|
to the human owner. Never invent answers.
|
|
9. Aggregate `cost.tokens` and `cost.eur` across all handoffs on the task. If
|
|
cumulative spend approaches the task budget cap, pause and request a
|
|
budget increase (human gate).
|
|
|
|
## Inputs
|
|
- A parent task in AOS with a clear goal and `task_id`.
|
|
- The target agent's spec file (to read constraints).
|
|
- Sufficient AOS context refs (client/project/contract) for the worker.
|
|
|
|
## Outputs
|
|
- A validated `AgentHandoff` written to AOS and linked to the parent task.
|
|
- A receipt of the resulting `AgentDeliverable`, with cost aggregated.
|
|
- A note on the parent task summarizing the delegation and its outcome.
|
|
|
|
## Guard rails / compliance
|
|
- Never bypass an approval gate surfaced by the worker — escalate, never approve
|
|
your own delegation's high-risk action.
|
|
- Never dispatch without a `definition_of_done`; an empty array is invalid.
|
|
- Never invent client decisions to unblock a worker — escalate instead.
|
|
- Every dispatch and receipt is logged to AOS; no private state between runs.
|
|
- Respect the worker's `forbidden` tools — if the task needs one, the task
|
|
belongs to a different agent.
|
|
|
|
## References
|
|
- `schemas/handoff.json` — AgentHandoff shape
|
|
- `schemas/deliverable.json` — AgentDeliverable shape (return envelope)
|
|
- `schemas/approval.json` — ApprovalRequest shape (when worker pauses)
|
|
- `policies/autonomy.md` — L0/L1/L2 and the always-human-gated list
|
|
- `agents/cross-cutting/orchestrator.md` — routing rules by department
|