Claude-Code-Workflow/.codex/skills/team-coordinate/instructions/agent-instruction.md

Agent Instruction Template -- Team Coordinate

Base instruction template for CSV wave agents. The orchestrator dynamically customizes this per role during Phase 1, writing role-specific versions to role-instructions/{role-name}.md.

Purpose

Phase	Usage
Phase 1	Coordinator generates per-role instruction from this template
Phase 2	Injected as instruction parameter to spawn_agents_on_csv

---

Base Instruction Template

## TASK ASSIGNMENT -- Team Coordinate

### MANDATORY FIRST STEPS
1. Read shared discoveries: <session-folder>/discoveries.ndjson (if exists, skip if not)
2. Read project context: .workflow/project-tech.json (if exists)

---

## Your Task

**Task ID**: {id}
**Title**: {title}
**Role**: {role}
**Responsibility**: {responsibility_type}
**Output Type**: {output_type}

### Task Description
{description}

### Previous Tasks' Findings (Context)
{prev_context}

---

## Execution Protocol

1. **Read discoveries**: Load <session-folder>/discoveries.ndjson for shared exploration findings
2. **Use context**: Apply previous tasks' findings from prev_context above
3. **Execute task**:
   - Read target files referenced in description
   - Follow the execution steps outlined in the TASK section of description
   - Produce deliverables matching the EXPECTED section of description
   - Verify output matches success criteria
4. **Share discoveries**: Append exploration findings to shared board:
   ```bash
   echo '{"ts":"<ISO8601>","worker":"{id}","type":"<type>","data":{...}}' >> <session-folder>/discoveries.ndjson

5. Report result: Return JSON via report_agent_job_result

Discovery Types to Share

• pattern_found: {pattern_name, location, description} -- Design pattern identified in codebase
• file_modified: {file, change, lines_added} -- File change performed by this agent
• dependency_found: {from, to, type} -- Dependency relationship between components
• issue_found: {file, line, severity, description} -- Issue or bug discovered
• decision_made: {decision, rationale, impact} -- Design decision made during execution
• artifact_produced: {name, path, producer, type} -- Deliverable file created

---

Output (report_agent_job_result)

Return JSON: { "id": "{id}", "status": "completed" | "failed", "findings": "Key discoveries and implementation notes (max 500 chars)", "artifacts_produced": "semicolon-separated paths of produced files", "error": "" }

---

## Role-Specific Customization

The coordinator generates per-role instruction variants during Phase 1. Each variant adds role-specific execution guidance to Step 3.

### For Research / Exploration Roles

Add to execution protocol step 3:

3. Execute:
   • Define exploration scope from description
   • Use code search tools to find relevant patterns and implementations
   • Survey approaches, compare alternatives
   • Document findings with file:line references
   • Write research artifact to /artifacts/

### For Code Implementation Roles

Add to execution protocol step 3:

3. Execute:
   • Read upstream design/spec artifacts referenced in description
   • Read target files listed in description
   • Apply code changes following project conventions
   • Validate changes compile/lint correctly
   • Run relevant tests if available
   • Write implementation summary to /artifacts/

### For Analysis / Audit Roles

Add to execution protocol step 3:

3. Execute:
   • Read target files/modules for analysis
   • Apply analysis criteria systematically
   • Classify findings by severity (critical, high, medium, low)
   • Include file:line references in findings
   • Write analysis report to /artifacts/

### For Test / Validation Roles

Add to execution protocol step 3:

3. Execute:
   • Read source files to understand implementation
   • Identify test cases from description
   • Generate test files following project test conventions
   • Run tests and capture results
   • Write test report to /artifacts/

### For Documentation / Writing Roles

Add to execution protocol step 3:

3. Execute:
   • Read source code and existing documentation
   • Generate documentation following template in description
   • Ensure accuracy against current implementation
   • Include code examples where appropriate
   • Write document to /artifacts/

### For Design / Architecture Roles

Add to execution protocol step 3:

3. Execute:
   • Read upstream research findings
   • Analyze existing codebase structure
   • Design component interactions and data flow
   • Document architecture decisions with rationale
   • Write design document to /artifacts/

---

## Quality Requirements

All agents must verify before reporting complete:

| Requirement | Criteria |
|-------------|----------|
| Files produced | Verify all claimed artifacts exist via Read |
| Files modified | Verify content actually changed |
| Findings accuracy | Findings reflect actual work done |
| Discovery sharing | At least 1 discovery shared to board |
| Error reporting | Non-empty error field if status is failed |

---

## Placeholder Reference

| Placeholder | Resolved By | When |
|-------------|------------|------|
| `<session-folder>` | Skill designer (Phase 1) | Literal path baked into instruction |
| `{id}` | spawn_agents_on_csv | Runtime from CSV row |
| `{title}` | spawn_agents_on_csv | Runtime from CSV row |
| `{description}` | spawn_agents_on_csv | Runtime from CSV row |
| `{role}` | spawn_agents_on_csv | Runtime from CSV row |
| `{responsibility_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{output_type}` | spawn_agents_on_csv | Runtime from CSV row |
| `{prev_context}` | spawn_agents_on_csv | Runtime from CSV row |