Agent Roles, Models, and Skills

1. Model Selection Matrix

Primary Rule

Opus for THINKING. Sonnet for DOING.

When to Switch Models

Switch to Opus when:

• You're about to make an architectural decision
• You need to understand complex cross-cutting concerns
• You're designing test strategies for new features
• You're writing a document that will guide future implementation
• You're debugging a complex issue with multiple interacting components

Switch to Sonnet when:

• The spec clearly defines what to implement
• You're writing tests that are already specified in the dev-spec
• You're running quality checks (lint, security, tests)
• You're committing, tagging, building, or deploying
• You're making small, well-defined changes

2. Agent Roles by Phase

Phase 0: Discovery

Workflow:

1. Human provides JIRA ticket URL + verbal description
2. Claude (Opus) reads JIRA → asks questions → fills PROJECT-KICKOFF.md
3. Human reviews → Claude iterates until approved

Phase 1: Architecture

Workflow:

1. Claude (Opus) reads approved PROJECT-KICKOFF.md
2. Claude uses Context7 to verify all library APIs
3. Claude generates ARCHITECTURE-{VERSION}.md using template
4. Claude self-reviews against post-generation checklist
5. Human reviews → Claude iterates until approved

Phase 2: Sprint Planning

Workflow:

1. Claude (Opus) reads approved ARCHITECTURE-{VERSION}.md
2. Claude decomposes architecture into numbered components (C01, C02, ...)
3. Claude groups components into sprints with dependency ordering
4. Claude writes complete test code for each sprint (RED phase)
5. Claude creates completeness map and traceability matrix
6. Human reviews → Claude iterates until approved

Phase 3: Implementation

Workflow (per sprint):

1. Claude (Sonnet) reads sprint N from DEVELOPMENT-SPEC
2. For each component in the sprint:
   a. Write tests from spec (RED) → verify they fail
   b. Implement code (GREEN) → verify tests pass
   c. Refactor if needed → verify tests still pass
3. Run full test suite with race detection
4. Check coverage targets
5. Mark acceptance criteria as complete
6. Git commit

Critical Rule: The implementing agent MUST follow the spec exactly. No improvisation, no "improvements" beyond the spec. If the spec is wrong, stop and ask the human.

Phase 4: Quality Verification

Phase 5: Release

3. Skill Definitions

Skill: Sprint Executor

When to use: Implementing a sprint from the development spec Model: Sonnet Input: Sprint number and DEVELOPMENT-SPEC path

Behavior:

1. Read the sprint section from the development spec
2. For each TDD section (T{N}.{X}):
   a. If test section: Write the tests, run them, verify they FAIL
   b. If implementation section: Write the code, run tests, verify they PASS
   c. If update section: Modify existing tests, verify they PASS
3. Run full test suite: verify zero regressions
4. Check coverage: verify targets met
5. Mark acceptance criteria checkboxes as [x]
6. Commit with message: "feat(sprint-{N}): {Sprint Name}"

Skill: Quality Gate

When to use: After all sprints are complete Model: Sonnet Input: Project root path

Behavior:

1. Run: make test (or equivalent)
2. Run: make lint (or equivalent) — fix actionable issues
3. Run: make security-scan (or equivalent) — verify 0 issues
4. Run: test with race detection
5. Check all documentation is in English
6. Verify all sprint checkboxes are marked
7. Output quality report

Skill: Architecture Generator

When to use: Starting Phase 1 Model: Opus Input: Approved PROJECT-KICKOFF.md

Behavior:

1. Read PROJECT-KICKOFF.md
2. Read ARCHITECTURE-TEMPLATE.md
3. Use Context7 to verify all library APIs
4. Generate complete ARCHITECTURE-{VERSION}.md
5. Self-review against post-generation checklist
6. Present to human for approval

Skill: Sprint Planner

When to use: Starting Phase 2 Model: Opus Input: Approved ARCHITECTURE-{VERSION}.md

Behavior:

1. Read ARCHITECTURE-{VERSION}.md completely
2. Read DEVELOPMENT-SPEC-TEMPLATE.md
3. Use Context7 to verify test framework APIs
4. Decompose architecture into components (C01, C02, ...)
5. Group into sprints with dependency ordering
6. Write complete test code for each sprint
7. Create completeness map and traceability matrix
8. Self-review against post-generation checklist
9. Present to human for approval

4. Subagent Usage Guidelines

When to Use Subagents

Parallelization Opportunities

Can run in parallel:

• Multiple quality checks (lint + security + tests)
• Independent file reads for analysis
• Multiple Explore agents for different codebases

Must run sequentially:

• Sprint implementation (each sprint depends on previous)
• Test writing → running → implementation (TDD order)
• Git operations (add → commit → push)

5. Context7 Usage Protocol

When to Use Context7

1. Architecture Generation: Verify EVERY library API before writing architecture
2. Sprint Planning: Verify test framework assertions and patterns
3. Implementation: When unsure about a specific API call

How to Use Context7

Step 1: Resolve library ID
   mcp__context7__resolve-library-id(libraryName="{library}", query="{what you need}")

Step 2: Query documentation
   mcp__context7__query-docs(libraryId="{resolved_id}", query="{specific question}")

Common Libraries to Verify

6. Error Recovery Procedures

Test Failure During Implementation

1. Read the error message carefully
2. Check if the test matches the spec exactly
3. If test is correct: fix the implementation
4. If test has a typo: fix the test, note it in commit message
5. NEVER skip a failing test

Spec Ambiguity During Implementation

1. STOP implementation
2. Re-read the architecture document section referenced in the sprint
3. If still ambiguous: Ask the human using AskUserQuestion
4. Document the clarification in the spec
5. Continue implementation

Regression Failure

1. STOP implementation
2. Identify which previous test is failing
3. Determine if the failure is caused by the current sprint's changes
4. If yes: fix the implementation to maintain backward compatibility
5. If no: investigate if the previous test has a pre-existing issue
6. NEVER modify a previous test to make it pass unless the test itself is wrong

7. Communication Protocol

Progress Reporting

After each sprint, report to the human:

Sprint {N}: {Name} ✅
- Tests: {X} new, {Y} total, all passing
- Coverage: {Z}% (target: >{T}%)
- Components: C{A}-C{B} complete
- Regressions: 0

Blocking Issues

If blocked, immediately report:

⚠️ BLOCKED on Sprint {N}:
- Issue: {description}
- Attempted: {what was tried}
- Options: {possible solutions}
- Recommendation: {preferred solution}
- Need: {what's needed from human}

Sprint Completion Summary

At project completion, provide:

PROJECT COMPLETE:
- Version: v{VERSION}
- Components: {X}/{Y} complete ({Z}%)
- Tests: {N} passing
- Coverage: {C}% (target: >{T}%)
- Security: 0 vulnerabilities
- Quality: All checks passing

Last Updated: Template v1.0 Based on: GPU Reporter v1.2.0 development methodology