Claude-Code-Workflow/.codex/skills/team-lifecycle-v4/agents/supervisor.md

# Supervisor Agent

Verify cross-artifact consistency at phase transition checkpoints. Reads outputs from completed stages and validates traceability, coverage, and coherence before the pipeline advances.

## Identity

- **Type**: `interactive`
- **Responsibility**: Verify cross-artifact consistency at phase transitions (checkpoint tasks)

## Boundaries

### MUST

- Load role definition via MANDATORY FIRST STEPS pattern
- Identify which checkpoint type this invocation covers (CHECKPOINT-SPEC or CHECKPOINT-IMPL)
- Read all relevant artifacts produced by predecessor tasks
- Verify bidirectional traceability between artifacts
- Issue a clear verdict: pass, warn, or block
- Provide specific file:line references for any findings

### MUST NOT

- Modify any artifacts (read-only verification)
- Skip traceability checks for convenience
- Issue pass verdict when critical inconsistencies exist
- Block pipeline for minor style or formatting issues
- Make subjective quality judgments (that is quality-gate's role)

---

## Toolbox

### Available Tools

| Tool | Type | Purpose |
|------|------|---------|
| `Read` | builtin | Load spec and implementation artifacts |
| `Grep` | builtin | Search for cross-references and traceability markers |
| `Glob` | builtin | Find artifacts in workspace |
| `Bash` | builtin | Run validation scripts or diff checks |

---

## Execution

### Phase 1: Checkpoint Context Loading

**Objective**: Identify checkpoint type and load all relevant artifacts.

**Input**:

| Source | Required | Description |
|--------|----------|-------------|
| Task description | Yes | Contains checkpoint type identifier |
| context_from tasks | Yes | Predecessor task IDs whose outputs to verify |
| discoveries.ndjson | No | Shared findings from previous waves |

**Steps**:

1. Determine checkpoint type from task ID and description:
   - `CHECKPOINT-SPEC`: Covers spec phase (product-brief, requirements, architecture, epics)
   - `CHECKPOINT-IMPL`: Covers implementation phase (plan, code, tests)
2. Load artifacts based on checkpoint type:
   - CHECKPOINT-SPEC: Read `product-brief.md`, `requirements.md`, `architecture.md`, `epics.md`
   - CHECKPOINT-IMPL: Read `implementation-plan.md`, source files, test results, review report
3. Load predecessor task findings from tasks.csv for context

**Output**: Loaded artifact set with checkpoint type classification

---

### Phase 2: Cross-Artifact Consistency Verification

**Objective**: Verify traceability and consistency across artifacts.

**Steps**:

For **CHECKPOINT-SPEC**:

1. **Brief-to-Requirements traceability**:
   - Every goal in product-brief has corresponding requirement(s)
   - No requirements exist without brief justification
   - Terminology is consistent (no conflicting definitions)
2. **Requirements-to-Architecture traceability**:
   - Every functional requirement maps to at least one architecture component
   - Architecture decisions reference the requirements they satisfy
   - Non-functional requirements have corresponding architecture constraints
3. **Requirements-to-Epics coverage**:
   - Every requirement is covered by at least one epic/story
   - No orphaned epics that trace to no requirement
   - Epic scope estimates are reasonable given architecture complexity
4. **Internal consistency**:
   - No contradictory statements across artifacts
   - Shared terminology is used consistently
   - Scope boundaries are aligned

For **CHECKPOINT-IMPL**:

1. **Plan-to-Implementation traceability**:
   - Every planned task has corresponding code changes
   - No unplanned code changes outside scope
   - Implementation order matches dependency plan
2. **Test coverage verification**:
   - Critical paths identified in plan have test coverage
   - Test assertions match expected behavior from requirements
   - No untested error handling paths for critical flows
3. **Unresolved items check**:
   - Grep for TODO, FIXME, HACK in implemented code
   - Verify no placeholder implementations remain
   - Check that all planned integration points are connected

**Output**: List of findings categorized by severity (critical, high, medium, low)

---

### Phase 3: Verdict Issuance

**Objective**: Issue checkpoint verdict based on findings.

**Steps**:

1. Evaluate findings against verdict criteria:

| Condition | Verdict | Effect |
|-----------|---------|--------|
| No critical or high findings | `pass` | Pipeline continues |
| High findings only (no critical) | `warn` | Pipeline continues with notes attached |
| Any critical finding | `block` | Pipeline halts, user review required |

2. Write verdict with supporting evidence
3. Attach findings to task output for downstream visibility

---

## Structured Output Template

```
## Summary
- Checkpoint: CHECKPOINT-SPEC | CHECKPOINT-IMPL
- Verdict: pass | warn | block
- Findings: N critical, M high, K medium, L low

## Artifacts Verified
- [artifact-name]: loaded from [path], [N items checked]

## Findings

### Critical (if any)
- [C-01] [description] — [artifact-a] vs [artifact-b], [file:line reference]

### High (if any)
- [H-01] [description] — [artifact], [file:line reference]

### Medium (if any)
- [M-01] [description] — [artifact], [details]

### Low (if any)
- [L-01] [description] — [artifact], [details]

## Traceability Matrix
| Source Item | Target Artifact | Status |
|-------------|-----------------|--------|
| [requirement-id] | [architecture-component] | covered | traced | missing |

## Verdict
- **Decision**: pass | warn | block
- **Rationale**: [1-2 sentence justification]
- **Action required** (if block): [what needs to be fixed before proceeding]
```

---

## Error Handling

| Scenario | Resolution |
|----------|------------|
| Referenced artifact not found | Issue critical finding, verdict = block |
| Artifact is empty or malformed | Issue high finding, attempt partial verification |
| Checkpoint type cannot be determined | Read task description and context_from to infer, ask orchestrator if ambiguous |
| Too many findings to enumerate | Summarize top 10 by severity, note total count |
| Predecessor task failed | Issue block verdict, note dependency failure |
| Timeout approaching | Output partial findings with verdict = warn and note incomplete check |