--- name: ai-team-workflow description: > Organize AI agents as a structured team — role assignment, proposal/vote/ review/ship cycle, cross-agent code review, consensus mechanisms, and escalation to human for deadlocks. Use when asked about "AI team", "agents working as a team", "multi-agent workflow", "agent roles", "agent review", "agents vote", "Hivemoot", "AI proposes and votes", "agent consensus", "agents reviewing each other's work", "define agent roles", "AI standup", or "autonomous team of agents". Do NOT use for: git-based task coordination — see git-native-agent-protocol. Do NOT use for: safety gates — see agent-safety-patterns. license: MIT © 2026 Vũ Văn Tâm compatibility: "Claude Code multi-agent, any orchestration framework. Patterns are tool-agnostic." metadata: origin: adapted:MIT © Hivemoot project version: 1.0.0 --- ## When to Use - Use when: multiple agents need to tackle a feature from different angles simultaneously - Use when: agent output quality improves with a review-before-merge step - Use when: building an autonomous system that can propose and ship without human per-task approval - Do NOT use for: single-agent tasks — overhead not justified - Do NOT use for: real-time coordination — this is async, PR-cycle cadence --- ## Role Taxonomy ``` Architect — breaks down requirements, designs the approach, creates task issues Implementer — writes code from the task spec (one per independent module) Reviewer — audits implementer's work: correctness, tests, security, style QA Agent — runs the test suite, e2e tests, performance checks Integrator — merges approved PRs, resolves conflicts, updates changelog Watchdog — monitors anomalies, triggers escalation on budget overrun or loop ``` --- ## Propose / Vote / Implement / Review / Ship ``` Phase 1 — PROPOSE (Architect agent) → Reads requirements → Proposes 2-3 implementation approaches in a structured doc → Posts to shared channel: .claude/proposals/feat-X.md Phase 2 — VOTE (All senior agents) → Each agent adds vote + rationale to the proposal → Majority wins; tie → escalate to human → Winning approach becomes the task spec Phase 3 — IMPLEMENT (Implementer agents, parallel) → Each implementer claims an independent module → Works in own branch/worktree → Opens PR when complete Phase 4 — REVIEW (Reviewer agent) → Checks each PR: logic, tests, security, style → Approves or requests changes → QA agent runs full test suite Phase 5 — SHIP (Integrator agent) → Merges approved PRs in dependency order → Updates CHANGELOG → Tags release if all checks pass ``` --- ## Proposal Format ```markdown # Proposal: Payment Retry with Exponential Backoff ## Context Payment calls timeout ~5% of the time. Need retry with backoff. ## Option A — In-process retry (RetryPolicy class) - Pros: no infra, simple, testable - Cons: retries block request thread on synchronous endpoints - Risk: LOW ## Option B — Queue-based retry (SQS + Lambda) - Pros: decoupled, observable, handles crashes - Cons: async — caller gets 202 Accepted, not result - Risk: MEDIUM ## Option C — Istio retry policy (sidecar) - Pros: zero code change - Cons: no custom logic (backoff curve fixed), hides retries from logs - Risk: LOW ## Votes - [ ] architect-agent: - [ ] backend-agent: - [ ] security-agent: ``` --- ## Vote Tallying (Automated) ```bash # Extract votes from proposal file and tally PROPOSAL=".claude/proposals/feat-payment-retry.md" count_votes() { local option="$1" grep -c "^- \[x\] .*:.*Option ${option}" "$PROPOSAL" || echo 0 } A=$(count_votes A); B=$(count_votes B); C=$(count_votes C) echo "Option A: $A | Option B: $B | Option C: $C" TOTAL_VOTERS=3 CAST=$(( A + B + C )) if [[ "$CAST" -lt "$TOTAL_VOTERS" ]]; then echo "Voting incomplete — waiting for remaining agents" elif [[ "$A" -gt "$B" && "$A" -gt "$C" ]]; then echo "Winner: Option A" elif [[ "$B" -gt "$A" && "$B" -gt "$C" ]]; then echo "Winner: Option B" else echo "Tie or Option C wins — escalate to human" gh issue create --title "Human decision needed: payment retry approach" --body "$(cat $PROPOSAL)" fi ``` --- ## Cross-Agent Review Protocol ```markdown ## Agent implementer-agent / module: payment-retry ## What was built - RetryPolicy class with exponential backoff (1s, 2s, 4s) - Skips retry on 4xx (client errors) - Unit tests: 6 cases covering all paths ## Review checklist (for reviewer-agent) - [ ] Logic matches proposal Option A spec - [ ] Error paths tested (exhausted retries, 400, 500) - [ ] No silent catch blocks - [ ] No secrets hardcoded - [ ] TypeScript strict mode passes ## QA gate (for qa-agent) - [ ] `npm test` passes - [ ] Integration test against payment stub passes - [ ] No new lint warnings ``` --- ## Escalation Triggers ```ts const escalationTriggers = [ { condition: 'voting_tie', reason: 'Agents split evenly — human tiebreaker needed' }, { condition: 'review_rejected_3x', reason: 'PR rejected 3 times — likely spec ambiguity' }, { condition: 'budget_exceeded', reason: 'Agent token budget exceeded — task may be too large' }, { condition: 'anomaly_detected', reason: 'Agent wrote outside allowed paths' }, { condition: 'test_fail_loop', reason: 'Tests failing for > 5 fix attempts' }, ]; // Escalation action: open GitHub issue + stop agent work function escalate(trigger: string, context: object) { gh.issues.create({ title: `[ESCALATION] ${trigger}`, body: JSON.stringify(context, null, 2), labels: ['agent:escalation', 'human-needed'], }); process.exit(0); // agent stops, human picks up } ``` --- ## Anti-Fake-Pass Rules Before claiming AI team workflow is operational, you MUST show: - [ ] Each agent has a documented role with explicit capability scope - [ ] Proposals are written before any implementation begins - [ ] Voting is recorded in the proposal file — not just verbal/in-context - [ ] PRs include the cross-agent review checklist — reviewer signs off line by line - [ ] Escalation triggers are defined and wired — not just documented - [ ] Human is notified (issue created) for ties, repeated failures, and anomalies Reference: `gates/anti-fake-pass-gate.md`