/tdd

argument-hint: <issue-number>
description: Autonomous TDD development cycle for GitHub issues with quality gates

TDD Development Cycle

Execute complete TDD workflow for GitHub issue #$ARGUMENTS with built-in quality gates and Python SDK parity checks.

Phase 1: Pre-flight Checks

Verify the development environment is ready:

1. **Check working directory status** - Ensure no uncommitted changes exist 2. **Verify current branch** - Should be on `main` branch 3. **Pull latest changes** - Run `git pull` to sync with remote 4. **Check for existing PRs** - Search for open PRs linked to issue #$ARGUMENTS to avoid duplicate work 5. **Verify Go environment** - Run `go version` and ensure toolchain is available 6. **Sync Python SDK** - Run `git -C ../claude-agent-sdk-python pull origin main` to ensure local Python SDK reference is current 7. **Check for blocking dependencies** - Read issue body and look for "Depends on" or "Blocked by" sections

**STOP and report to user if any check fails** - Don't proceed until issues are resolved.

---

Phase 2: Issue Validation

Retrieve and analyze issue #$ARGUMENTS:

1. **Fetch issue details** - Get title, body, labels, milestone, state via `gh issue view` 2. **Read all comments** - Check for additional context or decisions made 3. **Validate issue completeness** - Check if issue contains:

• Summary or description of the feature/fix
• Proposed Implementation section (most issues have this)
• Files to Modify section
• Example Usage (if applicable)

**If incomplete:** Report gaps to user and ask if should proceed anyway. **If complete:** Display issue summary and continue.

---

Phase 3: Discovery & Planning

**Enter plan mode for this entire phase.** Call `EnterPlanMode` at the start of Phase 3 so all discovery, design decisions, and parity tradeoffs are captured as a plan the user approves before any code is written. The phase ends with `ExitPlanMode` at the *Critical Checkpoint* below. If already in plan mode, `EnterPlanMode` is a no-op — proceed.

Design Principle: Two Co-Equal Parity Gates

This work passes through **two co-equal mandatory gates**. Both must pass. Neither compensates for the other:

1. **Observable-behavior parity with Python SDK** — JSON wire format, public API surface, CLI flags, message shapes, and semantics exposed to consumers. This is the *contract* the SDK delivers. 2. **Idiomatic Go delivery** — the *shape* of the code that delivers that contract: nil-safety, context-first, `fmt.Errorf` with `%w` wrapping, zero-value usability, small focused interfaces, gofmt/golangci-lint conformance, gocyclo under 15, channel-based concurrency, no unnecessary exports. The Go shape is itself a parity gate, not a polish step applied after the fact.

Parity is the *what*. Idiomatic Go is the *how*. A faithful translation of Python internals that violates Go idiom is a Gate-2 failure even if the wire format is exact. Conversely, a beautifully idiomatic Go API that drifts from the wire contract is a Gate-1 failure.

**Internal mechanics** (private struct layout, helper return types, control flow shape, dispatch strategy) are **not** parity targets. When a Go idiom and a Python internal shape conflict, choose the Go idiom and record the deliberate divergence in the plan (and later in the commit message + PR description — never in source comments). The plan presented at `ExitPlanMode` must name each divergence explicitly so the user approves it up front rather than discovering it in review.

Codebase Exploration

Understand existing patterns to match the project's conventions:

1. **Review Python SDK Reference:**

• **Check parity tracker first** - Read `docs/tracking/README.md` to find if this issue maps to a tracked Python SDK PR. If a tracker entry exists, use the Python PR number as the authoritative reference.
• **Read Python source directly** - Tracker notes are intentionally brief summaries, not the full spec. Read the actual Python source files at `../claude-agent-sdk-python/` for exact behavior:
• `src/claude_agent_sdk/types.py` - all public type definitions (messages, options, hooks)
• `src/claude_agent_sdk/client.py` - public Client interface
• `src/claude_agent_sdk/_internal/client.py` - internal client/transport implementation
• `src/claude_agent_sdk/_internal/transport/subprocess_cli.py` - subprocess/protocol logic
• `src/claude_agent_sdk/_internal/message_parser.py` - message parsing
• `src/claude_agent_sdk/_internal/sessions.py` - session management
• `src/claude_agent_sdk/_internal/session_mutations.py` - session mutations (rename, tag, etc.)
• **Verify exact details from Python source:** field names, JSON tags, optional vs required, default values, serialization behavior - flag any divergence that isn't justified by Go idiom
• **Fetch official documentation** using `curl -s https://platform.claude.com/docs/en/agent-sdk/python.md` for public API signatures if helpful
• Note any Go-specific adaptations needed (e.g., pointer for optional fields, interface for union types)

2. **Discover Existing Patterns:**

• Search for similar implementations in the codebase
• Review `client_test.go` as the gold standard for testing patterns
• Check existing type definitions and interfaces
• Understand error handling patterns (`fmt.Errorf` with `%w`)

3. **Identify Files to Modify:**

• Map issue's "Files to Modify" section to actual paths
• Check for related test files that need updates
• Note any re-exports needed in `types.go`

4. **Review Related Context:**

• Read issues mentioned in "Depends on" or "Blocks" sections
• Check closed PRs for similar features

Create TDD Implementation Plan

Based on exploration and issue requirements, create detailed plan with:

1. **RED Phase - Tests First:**

• Test cases to write (based on Python SDK behavior)
• Expected failures before implementation
• Table-driven test structure if multi