Agent orchestration

# Sequential: each agent depends on the previous one
> Step 1: Use the planner agent to plan the refactoring
> Step 2: Use the tdd-guide agent to implement according to the plan
> Step 3: Use the code-reviewer agent to validate the code
> Step 4: Use the doc-updater agent to update the docs

# Parallel: agents work at the same time
> Launch in parallel:
> - Agent security-reviewer: audit the auth module
> - Agent code-reviewer: review the API module
> - Agent e2e-runner: test the user journey
> Then synthesize the results from all three agents.

# Conceptually, Claude Code does:
# 1. Launches 3 sub-agents in parallel (run_in_background: true)
# 2. Waits for all 3 to finish
# 3. Consolidates results into a single report

# Complete release pipeline
> Execute this pipeline:
>
> Phase 1 (parallel):
>   - Agent tdd-guide: verify all tests pass
>   - Agent security-reviewer: security audit
>
> Phase 2 (sequential, after Phase 1):
>   - Agent code-reviewer: final code review
>
> Phase 3 (parallel, after Phase 2):
>   - Agent doc-updater: documentation update
>   - Agent e2e-runner: end-to-end tests
>
> Phase 4 (sequential, after Phase 3):
>   - Prepare the release tag and changelog

# Split-role: multiple perspectives on the same problem
> Analyze this PR from 4 different angles:
>
> Agent 1 (factual): Verify the code does what the PR says
> Agent 2 (senior): Evaluate quality and maintainability
> Agent 3 (security): Look for security flaws
> Agent 4 (consistency): Check consistency with the rest of the codebase
>
> Then synthesize the 4 analyses into a consolidated report.

# Strategy 1: Via files
Agent A writes its results to a file.
Agent B reads that file at the start of its mission.

# Strategy 2: Via the prompt
The orchestrator agent summarizes Agent A's result
and includes it in Agent B's prompt.

# Strategy 3: Via Git
Agent A commits its changes.
Agent B works on the same branch and sees the modifications.

# Conceptually, Claude Code creates isolated worktrees:

# Agent 1 works in /tmp/worktree-security
git worktree add /tmp/worktree-security main

# Agent 2 works in /tmp/worktree-tests
git worktree add /tmp/worktree-tests main

# Agent 3 works in /tmp/worktree-docs
git worktree add /tmp/worktree-docs main

# Each agent modifies its files without affecting the others
# At the end, changes are merged

# Without background: forced sequential
# Agent A works... (60 seconds)
# Agent B works... (60 seconds)
# Total: 120 seconds

# With background: parallel
# Agent A works in background... (60 seconds)
# Agent B works in background... (60 seconds)
# Total: 60 seconds (both in parallel)

# GOOD: Concise results
"The security audit found 3 issues:
1 CRITICAL (missing CSRF), 2 MEDIUM (rate limiting)."

# BAD: Verbose results
"I analyzed each file one by one. First auth.ts,
which contains 342 lines of code. Line 42 is
interesting because..." (500-line report)

# BAD: Overlap
Agent 1: "Review the code and check security"
Agent 2: "Check security and code quality"
# → Both do security = duplication

# GOOD: Distinct responsibilities
Agent 1: "Review code quality (readability, patterns, tests)"
Agent 2: "Security audit only (injection, XSS, secrets)"
# → Each in its own domain, no overlap

## Success criteria for the testing agent
- All tests pass (exit code 0)
- Code coverage > 80%
- No flaky tests (rerun 3 times if a test fails)
- Coverage report generated in /coverage

# Fallback plan
If the security-reviewer agent finds a CRITICAL issue:
  → Stop the pipeline
  → Notify the developer with the issue details
  → Do NOT continue to review or release

If the e2e-runner agent fails on a test:
  → Rerun the test 2 times (might be a flaky test)
  → If still failing, flag it and continue

> Execute a release pipeline for version 2.3.0:
>
> 1. PLANNING (sequential)
>    - Use the planner agent to list all changes
>      since the last tag
>
> 2. CHECKS (parallel)
>    - Agent tdd-guide: all tests pass, coverage 80%+
>    - Agent security-reviewer: full security audit
>    - Agent refactor-cleaner: no dead code introduced
>
> 3. REVIEW (split-role)
>    - Quality perspective: clean and maintainable code
>    - Performance perspective: no regressions
>    - Consistency perspective: coherent with the codebase
>
> 4. DOCUMENTATION (parallel)
>    - Agent doc-updater: update technical docs
>    - Generate the changelog since the last tag
>
> 5. RELEASE (sequential)
>    - If everything is green: create the v2.3.0 tag
>    - Generate the release notes
>
> If a CRITICAL step fails, stop everything and give me
> a detailed report of the problem.

# Leader: the orchestrator agent
> You coordinate 3 workers for the "CSV export" feature.
> Break down the task and assign each part.

# Worker 1: Backend
# → Implement the /api/export endpoint
# Worker 2: Frontend
# → Add the export button to the UI
# Worker 3: Tests
# → Write E2E tests for the export flow

# Agent Teams in peer-to-peer mode
# Each agent works and signals when done
# Other agents react to changes

# Developer agent: codes → signals "code ready"
# Tester agent: detects "code ready" → writes tests
# Reviewer agent: detects "tests written" → reviews everything

# .github/workflows/agent-review.yml
name: Agent Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Agent Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude --print --max-turns 15 \
            "Do a complete review of this PR.
             Analyze the diff with git diff origin/main...HEAD.
             Produce a report with issues by severity.
             If you find a CRITICAL, end with EXIT_CODE=1."

# .gitlab-ci.yml
agent-security-audit:
  stage: review
  image: node:20-alpine
  before_script:
    - npm install -g @anthropic-ai/claude-code
  script:
    - |
      claude --print --max-turns 10 \
        "Security audit on the diff for this MR.
         Look for: SQL injections, XSS, hardcoded secrets,
         vulnerable dependencies. JSON format."
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

// scripts/ci-review.ts
import { claude } from "@anthropic-ai/claude-code-sdk";

async function ciReview() {
  // Phase 1: Security
  const security = await claude({
    prompt: "Security audit of the diff against main",
    options: { maxTurns: 10, allowedTools: ["Bash", "Read", "Grep"] },
  });

  // Phase 2: Tests
  const tests = await claude({
    prompt: "Verify that test coverage is > 80%",
    options: { maxTurns: 8, allowedTools: ["Bash", "Read"] },
  });

  // Consolidated result
  const hasCritical = security.text.includes("CRITICAL");
  const lowCoverage = tests.text.includes("< 80%");

  if (hasCritical || lowCoverage) {
    console.error("Review failed:");
    if (hasCritical) console.error("- CRITICAL security issue");
    if (lowCoverage) console.error("- Insufficient coverage");
    process.exit(1);
  }

  console.log("Review OK");
}

ciReview();