AI Team Workflow

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

<!-- .claude/proposals/feat-payment-retry.md -->
# 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)

# 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

<!-- PR description template for agent-submitted PRs -->
## 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

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