/tdd-review

description: Comprehensive code review using team-based specialized agents with self-coordination
allowed-tools: Read, Grep, Glob, Bash, Edit, Write, Task, WebFetch, TeamCreate, TeamDelete, TaskCreate, TaskUpdate, TaskList, TaskGet, SendMessage, AskUserQuestion, ToolSearch

TDD Code Review (Team-Based)

Comprehensive code review for the Go SDK. Orchestrates multiple reviewers to analyze Go idioms, error handling, type design, test coverage, and Python SDK parity.

Prerequisite: Load Deferred Tools

Team and task orchestration tools (`TeamCreate`, `TeamDelete`, `TaskCreate`, `TaskUpdate`, `TaskList`, `TaskGet`, `SendMessage`, `AskUserQuestion`) are deferred in this harness. Before entering Phase 1, load them via:

ToolSearch(query="select:TeamCreate,TeamDelete,TaskCreate,TaskUpdate,TaskList,TaskGet,SendMessage,AskUserQuestion", max_results=8)

Skip this for quick-mode runs.

Quick Mode Exception

For focused reviews, use a single bare Agent call (model: "sonnet") with NO team:

• `--quick` — Only `grumpy-gopher`
• `--errors` — Only `pr-review-toolkit:silent-failure-hunter`
• `--types` — Only `pr-review-toolkit:type-design-analyzer`
• `--tests` — Only `pr-review-toolkit:pr-test-analyzer`
• `--parity` — `grumpy-gopher` with explicit instructions to cross-reference `docs/tracking/README.md` and `../claude-agent-sdk-python/` for Python SDK divergence

If `$ARGUMENTS` contains any of these flags, extract the flag, launch the single appropriate agent with the file list, present results, and stop. Do not create a team, do not load team tools.

---

Review Scope Detection

Determine what code to review:

1. **User-specified files**: If user provided specific files or packages after the flag/arguments, use those. 2. **Unstaged changes**: `git diff --name-only` 3. **Staged changes**: `git diff --staged --name-only` 4. **Default**: Current package (`./...`)

git diff --name-only
git diff --staged --name-only

Store the file list. If no files found, report and exit cleanly (no team created).

---

Reviewer Selection

Based on files identified, select reviewers:

| File Pattern | Reviewer | |--------------|----------| | `internal/control/*` | `grumpy-gopher`, `pr-review-toolkit:silent-failure-hunter` | | `internal/parser/*` | `grumpy-gopher`, `pr-review-toolkit:silent-failure-hunter` | | `internal/subprocess/*` | `grumpy-gopher`, `pr-review-toolkit:silent-failure-hunter` | | `internal/cli/*` | `grumpy-gopher` | | `internal/shared/*` | `grumpy-gopher`, `pr-review-toolkit:type-design-analyzer` | | Root `*.go` (public API: `client.go`, `query.go`, `options.go`, `errors.go`, `transport.go`) | `grumpy-gopher`, `pr-review-toolkit:type-design-analyzer` | | `*_test.go`, `*_bench_test.go` | `pr-review-toolkit:pr-test-analyzer` | | `examples/*` | `grumpy-gopher` (informational only) | | Any Go file | `grumpy-gopher`, `pr-review-toolkit:silent-failure-hunter` (always) | | Scope spans 2+ packages | Add `pr-review-toolkit:code-reviewer` | | Diff adds large docstrings/comment blocks | Add `pr-review-toolkit:comment-analyzer` |

**Always include** for any Go files: `grumpy-gopher`, `pr-review-toolkit:silent-failure-hunter`.

Deduplicate: if a reviewer would be selected multiple times, launch once with all matching files.

Graceful Degradation

If a `pr-review-toolkit:*` reviewer is unavailable (plugin not installed), skip it with a warning in the summary and continue. Do not fail the review.

---

Phase 1: Team Creation & Spawn

Create Team

Generate a short ID from timestamp or random suffix:

TeamCreate(team_name="review-{short-id}", description="Code review for [file summary]")

Create Review Tasks

One task per selected reviewer. No dependencies - all run in parallel.

Example:

Task 1: "Review: Go idioms, project conventions, Python SDK parity" (files: [all Go files])
Task 2: "Review: Error handling and silent failures" (files: internal/control/*, internal/parser/*, internal/subprocess/*)
Task 3: "Review: Type design for public API" (files: root *.go, internal/shared/*)
Task 4: "Review: Test coverage and patterns" (files: [test files])

Each task description includes: reviewer type, file list, focus areas.

Spawn Reviewers

All reviewers use `model: "sonnet"`. Each gets this inline prompt:

You are a reviewer on team review-{short-id}.

Self-coordination loop:
1. Call TaskList for unblocked, unassigned review tasks
2. Claim lowest-ID matching task via TaskUpdate (set owner to your name)
3. Read task description via TaskGet for file list and focus areas
4. Execute review per your methodology
5. Send findings to lead via SendMessage in this format:
   - CRITICAL: [issues that must fix - bugs, security, data loss, parity breaks]
   - MAJOR: [should fix - significant quality issues]
   - MINOR: [nice to fix - style, minor improvements]
   - POSITIVE: [good patterns observed]
6. Mark task completed via TaskUpdate
7. Check TaskList for more work. If none: message lead "Review complete. Standing by."

Project-specific focus:
- Idiomatic Go (gofmt, context-first, fmt.Errorf with %w)
- Cyclomatic complexity under 15 (per gocyclo)
- No unreachable internal functions (per `make deadcode` — scoped to `internal/*` rooted at `./examples/...`); flag dead code in `internal/*` or public API symbols not wired through any internal path
- Thread-safe mocks; t.Helper() in test helpers
- Python SDK parity - cross-check ../claude-agent-sdk-python/ and docs/tracking/README.md. The goal is feature parity with the *observable behavior* of the Python SDK: wire format (JSON field names, constants, message shapes, CLI flags), public API surface, and semantics exposed to consumers. Parity on internal mechanics (helper return types, private struct layout, control flow shape) is not a goal in itself — since this is Go, prefer idiomatic Go and established Go best practices (nil-safety, context-first, error wrapping with %w, zero-value usability, small focused inte