Add Go Module

Output: brief summary of what this module does and key design decisions.

Step 2: Update Contract Docs

Before writing any code, update the contract documents:

1. docs/architecture_spec.md: Add the new module to the architecture diagram, define its layer placement and dependency relationships
2. docs/api_spec.md: Add the Go interface definitions for this module

Ask the user to review and approve the spec changes before proceeding.

Step 3: Define Go Interfaces

Create the interface file in the correct package:

// internal/newmodule/newmodule.go

// Package newmodule provides [one-line description].
package newmodule

import "context"

// SomeInterface defines the contract for [purpose].
type SomeInterface interface {
    Method(ctx context.Context, arg Type) (Result, error)
}

Rules:

• Interface defined at the consumer side
• Implementation at the provider side
• Keep interfaces small (1-3 methods)
• Use context.Context for I/O operations

Step 4: Implement + Test

Implement the interface with a concrete struct. Write tests simultaneously.

Test requirements (per testing-tdd rule):

• Table-driven tests
• Edge cases: nil, empty, oversized, concurrent, timeout
• Mock all external dependencies via interfaces
• Target >= 80% coverage for core logic

File layout:

internal/newmodule/
├── newmodule.go       # Interface + types
├── impl.go            # Implementation
├── impl_test.go       # Tests
└── options.go         # Functional options (if needed)

Step 5: Wire Up

Connect the new module to the application:

1. Add configuration fields in internal/config/ if needed
2. Instantiate in cmd/gopherpaw/main.go with dependency injection
3. Pass to consumers via constructor parameters
4. Verify the full chain works with an integration-level test

Post-Completion

After all steps are done:

1. Run go vet ./... and go test ./...
2. Verify contract docs match the implementation
3. Update CONTEXT.md if the module changes project status/progress