/evanflow-coder-overseer

name: evanflow-coder-overseer
description: Orchestrate parallel implementation with coder/overseer pairs. Coders implement decomposed tasks using evanflow-tdd; overseers review each coder's output for bugs, gaps, errors, AND cohesion violations against a shared contract. A final integration overseer checks cross-coder cohesion. Use for plans with 3+ truly independent tasks that share an interface contract.

EvanFlow: Coder-Overseer Orchestration

Vocabulary

See `evanflow` meta-skill for shared terms. New roles introduced here:

• **Orchestrator** — the main Claude session running this skill. Authors the contract, decomposes work, spawns subagents, reconciles findings, reports to the user.
• **Coder** — subagent dispatched to implement one decomposed unit. Uses `evanflow-tdd`. Writes tests first. Outputs code + tests + brief summary.
• **Overseer** — subagent dispatched to review ONE coder's output. Looks for bugs, gaps, errors, and contract violations. **Reports findings; does NOT fix them.**
• **Cohesion contract** — the shared interfaces, types, invariants, and naming that must hold across ALL coder outputs. A short doc, authored by the orchestrator before any agent spawns.
• **Integration overseer** — a final subagent that reviews the *combined* output across all coders, catching inter-task cohesion drift that single-coder overseers can't see (boundary type mismatches, naming inconsistency, missed invariants).

When to Use

• Plan has **3+ truly independent tasks** that can run in parallel
• Tasks share a contract (interfaces, types, naming) where divergence is a bug
• Work benefits from independent review (complex routers, multi-file refactors, new modules with cross-cutting concerns)

**SKIP when:**

• Plan has tightly sequential dependencies → use `evanflow-executing-plans` instead
• Tasks are trivial (orchestration overhead > benefit)
• A single agent can hold the whole thing in context comfortably

The Flow

1. Author the Cohesion Contract (with Test Specifications)

Before spawning anyone, the orchestrator writes a contract at `.claude/orchestration/<topic>-contract.md` (or any path the user prefers). Contents:

• **Shared types and interfaces** — with full file paths and signatures
• **Naming conventions** for new symbols (e.g., "router files are `<resource>.ts`, services are `<resource>-service.ts`")
• **Invariants** that must hold (e.g., "all routes use the authenticated middleware", "all services return `Result<T, Error>`", "all DB writes go through the canonical write helper documented in CLAUDE.md")
• **Cross-references** to `CONTEXT.md` and relevant ADRs
• **Integration touchpoints** — where coder outputs must connect (e.g., "router A imports type X from package B; service C calls function D from service E")
• **Behavior specifications per coder** — for EACH coder, list 3–7 testable behaviors with: a test name, a one-line description of the assertion, and the public interface used to verify it. Example:

  ### Coder 2: rate-limit service (example)

  - test: returns full cap when no usage recorded
    assert: `getRemainingThisWeek(userId)` returns `{ remaining: 25, resetsAt: null }` for a fresh user
    surface: services/rate-limit.ts (public)

  - test: counts ACTIVE and PENDING rows but excludes CANCELLED/FAILED
    assert: after seeding rows of varied statuses, `getRemainingThisWeek` returns the correct count
    surface: services/rate-limit.ts (public)

• **Integration tests at touchpoints** — for every place where one coder's output is consumed by another, name an integration test that proves the connection works end-to-end. Both coders must satisfy it. **Integration tests become the executable contract** — they prevent interface drift the way prose specifications can't.

The contract is the **single source of truth** for everyone downstream. If it's wrong or ambiguous, fix it BEFORE spawning agents — patching the contract mid-orchestration causes drift.

2. Decompose into Coder Tasks

Each coder task is a self-contained brief. Includes:

• **One unit of work** — one file, or one logical module
• **Files to create/modify** with exact paths
• **Required behaviors to test** (behavior, not mechanics — see `evanflow-tdd`)
• **Reference to the contract** with explicit "must conform to" pointers
• **Explicit out-of-scope list** so the coder doesn't expand

**Max 5 coders in parallel.** More than that is unmanageable to review.

3. Spawn Coders — RED Checkpoint First

Coder dispatch happens in **two phases** to enforce TDD at the orchestration level.

**Phase A — RED checkpoint.** Single message, multiple `Agent` calls. **Prefer `subagent_type: evanflow-coder` if available** (tool-restricted to prevent git ops and other dangerous actions); else `general-purpose`. Each coder gets:

• The self-contained brief from step 2
• Path to the contract
• Path to the plan
• Instructions:

> "Phase A: write ONLY the first failing test for your first behavior (per the contract's test list for your section). Run it. Confirm it fails for the right reason — not a setup error, not an import error, not a missing dependency. Report back: test file path, test name, the exact failure message, and confirmation that the failure matches expected behavior. Do NOT write any implementation yet. Do NOT touch any production source file other than minimal scaffolding (e.g., empty function stubs that exist only so the import resolves)."

After all coders return Phase A reports, **the orchestrator verifies every test is RED**:

• Run the project's test command for affected workspaces
• Confirm each coder's named test appears in the failure list
• Confirm the failure reason matches what the coder reported
• Catch: tests passing accidentally (assertion is too weak), tests failing for wrong reason (setup bug), tests not actually running (wrong filename pattern)

If any test isn't cleanly RED, send that coder back with the specific issue. Do NOT proceed to Phase B unt