evanflow-coder-overseer

Name: evanflow-coder-overseer
Author: evanklem

419stars18forks

How to install evanflow-coder-overseer?

evanklem/evanflow/evanflow-coder-overseer

$npx -y skills add evanklem/evanflow --skill evanflow-coder-overseer

Installs into the current project.

Summary

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 coh

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Coder-Overseer Orchestration
2
3
4	## Vocabulary
5
6	See `evanflow` meta-skill for shared terms. New roles introduced here:
7
8	- Orchestrator — the main Claude session running this skill. Authors the contract, decomposes work, spawns subagents, reconciles findings, reports to the user.
9	- Coder — subagent dispatched to implement one decomposed unit. Uses `evanflow-tdd`. Writes tests first. Outputs code + tests + brief summary.
10	- Overseer — subagent dispatched to review ONE coder's output. Looks for bugs, gaps, errors, and contract violations. Reports findings; does NOT fix them.
11	- 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.
12	- 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).
13
14	## When to Use
15
16	- Plan has 3+ truly independent tasks that can run in parallel
17	- Tasks share a contract (interfaces, types, naming) where divergence is a bug
18	- Work benefits from independent review (complex routers, multi-file refactors, new modules with cross-cutting concerns)
19
20	SKIP when:
21	- Plan has tightly sequential dependencies → use `evanflow-executing-plans` instead
22	- Tasks are trivial (orchestration overhead > benefit)
23	- A single agent can hold the whole thing in context comfortably
24
25	## The Flow
26
27	### 1. Author the Cohesion Contract (with Test Specifications)
28
29	Before spawning anyone, the orchestrator writes a contract at `.claude/orchestration/<topic>-contract.md` (or any path the user prefers). Contents:
30
31	- Shared types and interfaces — with full file paths and signatures
32	- Naming conventions for new symbols (e.g., "router files are `<resource>.ts`, services are `<resource>-service.ts`")
33	- 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")
34	- Cross-references to `CONTEXT.md` and relevant ADRs
35	- 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")
36	- 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:
37	```
38	### Coder 2: rate-limit service (example)
39
40	- test: returns full cap when no usage recorded
41	assert: `getRemainingThisWeek(userId)` returns `{ remaining: 25, resetsAt: null }` for a fresh user
42	surface: services/rate-limit.ts (public)
43
44	- test: counts ACTIVE and PENDING rows but excludes CANCELLED/FAILED
45	assert: after seeding rows of varied statuses, `getRemainingThisWeek` returns the correct count
46	surface: services/rate-limit.ts (public)
47	```
48	- 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.
49
50	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.
51
52	### 2. Decompose into Coder Tasks
53
54	Each coder task is a self-contained brief. Includes:
55
56	- One unit of work — one file, or one logical module
57	- Files to create/modify with exact paths
58	- Required behaviors to test (behavior, not mechanics — see `evanflow-tdd`)
59	- Reference to the contract with explicit "must conform to" pointers
60	- Explicit out-of-scope list so the coder doesn't expand
61
62	Max 5 coders in parallel. More than that is unmanageable to review.
63
64	### 3. Spawn Coders — RED Checkpoint First
65
66	Coder dispatch happens in two phases to enforce TDD at the orchestration level.
67
68	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:
69
70	- The self-contained brief from step 2
71	- Path to the contract
72	- Path to the plan
73	- Instructions:
74	> "Phase A: write ONLY the first failing test for your first behavior (per

People who liked this also viewed

6 picks

Type

evanflow-coder-overseer

419stars18forks

View on GitHub

How to install evanflow-coder-overseer?

evanklem/evanflow/evanflow-coder-overseer

$npx -y skills add evanklem/evanflow --skill evanflow-coder-overseer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Coder-Overseer Orchestration
2
3
4	## Vocabulary
5
6	See `evanflow` meta-skill for shared terms. New roles introduced here:
7
8	- Orchestrator — the main Claude session running this skill. Authors the contract, decomposes work, spawns subagents, reconciles findings, reports to the user.
9	- Coder — subagent dispatched to implement one decomposed unit. Uses `evanflow-tdd`. Writes tests first. Outputs code + tests + brief summary.
10	- Overseer — subagent dispatched to review ONE coder's output. Looks for bugs, gaps, errors, and contract violations. Reports findings; does NOT fix them.
11	- 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.
12	- 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).
13
14	## When to Use
15
16	- Plan has 3+ truly independent tasks that can run in parallel
17	- Tasks share a contract (interfaces, types, naming) where divergence is a bug
18	- Work benefits from independent review (complex routers, multi-file refactors, new modules with cross-cutting concerns)
19
20	SKIP when:
21	- Plan has tightly sequential dependencies → use `evanflow-executing-plans` instead
22	- Tasks are trivial (orchestration overhead > benefit)
23	- A single agent can hold the whole thing in context comfortably
24
25	## The Flow
26
27	### 1. Author the Cohesion Contract (with Test Specifications)
28
29	Before spawning anyone, the orchestrator writes a contract at `.claude/orchestration/<topic>-contract.md` (or any path the user prefers). Contents:
30
31	- Shared types and interfaces — with full file paths and signatures
32	- Naming conventions for new symbols (e.g., "router files are `<resource>.ts`, services are `<resource>-service.ts`")
33	- 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")
34	- Cross-references to `CONTEXT.md` and relevant ADRs
35	- 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")
36	- 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:
37	```
38	### Coder 2: rate-limit service (example)
39
40	- test: returns full cap when no usage recorded
41	assert: `getRemainingThisWeek(userId)` returns `{ remaining: 25, resetsAt: null }` for a fresh user
42	surface: services/rate-limit.ts (public)
43
44	- test: counts ACTIVE and PENDING rows but excludes CANCELLED/FAILED
45	assert: after seeding rows of varied statuses, `getRemainingThisWeek` returns the correct count
46	surface: services/rate-limit.ts (public)
47	```
48	- 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.
49
50	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.
51
52	### 2. Decompose into Coder Tasks
53
54	Each coder task is a self-contained brief. Includes:
55
56	- One unit of work — one file, or one logical module
57	- Files to create/modify with exact paths
58	- Required behaviors to test (behavior, not mechanics — see `evanflow-tdd`)
59	- Reference to the contract with explicit "must conform to" pointers
60	- Explicit out-of-scope list so the coder doesn't expand
61
62	Max 5 coders in parallel. More than that is unmanageable to review.
63
64	### 3. Spawn Coders — RED Checkpoint First
65
66	Coder dispatch happens in two phases to enforce TDD at the orchestration level.
67
68	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:
69
70	- The self-contained brief from step 2
71	- Path to the contract
72	- Path to the plan
73	- Instructions:
74	> "Phase A: write ONLY the first failing test for your first behavior (per

People who liked this also viewed

6 picks

Type