leo: coordination architecture — peer review v1, handoff protocol, synthesis triggers #56

Merged
m3taversal merged 3 commits from leo/coordination-architecture into main 2026-03-07 22:04:15 +00:00
2 changed files with 64 additions and 4 deletions
Showing only changes of commit fd20f4e953 - Show all commits

View file

@ -191,16 +191,26 @@ Then open a PR against main. The PR body MUST include:
- Any claims that challenge or extend existing ones - Any claims that challenge or extend existing ones
### 8. Wait for review ### 8. Wait for review
Leo (and possibly the other domain agent) will review. They may: Every PR requires two approvals: Leo + 1 domain peer (see Evaluator Workflow). They may:
- **Approve** — claims merge into main - **Approve** — claims merge into main after both approvals
- **Request changes** — specific feedback on what to fix - **Request changes** — specific feedback on what to fix
- **Reject** — with explanation of which quality criteria failed - **Reject** — with explanation of which quality criteria failed
Address feedback on the same branch and push updates. Address feedback on the same branch and push updates.
## How to Evaluate Claims (Evaluator Workflow — Leo) ## How to Evaluate Claims (Evaluator Workflow)
Leo reviews all PRs. Other agents may be asked to review PRs in their domain. ### Default review path: Leo + 1 domain peer
Every PR requires **two approvals** before merge:
1. **Leo** — cross-domain evaluation, quality gates, knowledge base coherence
2. **Domain peer** — the agent whose domain has the highest wiki-link overlap with the PR's claims
**Peer selection:** Choose the agent whose existing claims are most referenced by (or most relevant to) the proposed claims. If the PR touches multiple domains, add peers from each affected domain. For cross-domain synthesis claims, the existing multi-agent review rule applies (2+ domain agents).
**Who can merge:** Leo merges after both approvals are recorded. Domain peers can approve or request changes but do not merge.
**Rationale:** Peer review doubles review throughput and catches domain-specific issues that cross-domain evaluation misses. Different frameworks produce better error detection than single-evaluator review (evidence: Aquino-Michaels orchestrator pattern — Agent O caught things Agent C couldn't, and vice versa).
### Peer review when the evaluator is also the proposer ### Peer review when the evaluator is also the proposer

50
skills/handoff.md Normal file
View file

@ -0,0 +1,50 @@
# Structured Handoff Protocol
When an agent discovers something relevant to another agent's domain, use this template for the handoff message. This replaces free-form messages for substantive coordination. Casual messages remain free-form.
## When to use
- You found evidence that affects another agent's claims or beliefs
- You discovered a cross-domain connection that needs investigation
- You have a working artifact (analysis, data, draft) another agent should build on
- You're recommending a specific action in another agent's territory
## Template
```
## Handoff: [topic]
**From:** [your name] → **To:** [agent name]
**What I found:** [specific discovery, with wiki links to relevant claims]
**What it means for your domain:** [how this connects to their existing claims/beliefs — be specific about which claims are affected]
**Recommended action:** [one of: extract claim, enrich existing claim, review dependency, flag tension, build on artifact]
**Artifacts:** [file paths to working documents, data, analyses — if any]
**Priority:** [routine | time-sensitive | blocking]
```
## Examples
**Good handoff:**
> **From:** Theseus → **To:** Rio
> **What I found:** The Aquino-Michaels orchestrator pattern uses structured data transfer between agents, not free-form messages. The fiber table transfer was a specific artifact (p1_fiber_tables.md) that unblocked downstream work.
> **What it means for your domain:** Your contribution tracking mechanism needs to track artifact creation and transfer, not just claim authorship. An agent who creates a working artifact that another agent builds on should get attribution.
> **Recommended action:** Enrich "contribution tracking with provenance" to include artifact-level attribution.
> **Artifacts:** agents/theseus/musings/orchestration-architecture.md (section on artifact transfer)
> **Priority:** routine
**Bad handoff:**
> Hey Rio, I read something about how agents transfer data. Might be relevant to your work. Let me know what you think.
The bad version forces Rio to re-derive the connection. The good version tells him exactly what changed and what to do about it.
## Rules
1. **Be specific about which claims are affected.** Link to them with `[[wiki links]]`.
2. **Include artifacts.** If you have a file the other agent should read, give the path.
3. **Recommend an action.** Don't just flag — tell them what you think they should do.
4. **Priority is honest.** Most handoffs are routine. "Time-sensitive" means the discovery affects work currently in progress. "Blocking" means their current task can't proceed without this.