[plan] Document Go type safety patterns and best practices

[github-actions]

Objective

Create comprehensive documentation for Go type safety patterns and best practices to guide future development and prevent regression.

Context

The codebase already has excellent type safety examples (semantic type aliases in pkg/constants/constants.go, migration patterns in pkg/workflow/tools_types.go), but these patterns aren't formally documented. This issue ensures best practices are captured and easily accessible to contributors.

Approach

1. Create specs/go-type-safety.md with sections on:

   • When to use semantic type aliases (following LineLength, Version, FeatureFlag patterns)
   • When map[string]any is appropriate vs when to use structs
   • How to migrate from untyped to typed configurations
   • Examples of good and bad patterns
   • Type name collision prevention

2. Update AGENTS.md with quick reference:

   • Link to the new spec
   • Add to "Type Patterns and Best Practices" section
   • Include decision tree for choosing type patterns

3. Add inline documentation to exemplary code:

   • Add godoc comments to pkg/constants/constants.go explaining semantic types
   • Add godoc to pkg/workflow/tools_types.go explaining migration pattern
   • Document the MapToolConfig transitional pattern

4. Create a type safety checklist for PR reviews:

   • Questions to ask when reviewing new types
   • Red flags to watch for
   • When to require stronger typing

Files to Create/Modify

• Create: specs/go-type-safety.md - Comprehensive type safety guide
• Update: AGENTS.md - Add type safety quick reference
• Update: pkg/constants/constants.go - Add godoc explaining semantic types
• Update: pkg/workflow/tools_types.go - Enhance migration documentation
• Create: .github/PULL_REQUEST_TEMPLATE.md section on type safety (optional)

Acceptance Criteria

• specs/go-type-safety.md created with comprehensive guidance
• AGENTS.md updated with type safety quick reference
• Key code files have enhanced godoc comments
• Documentation includes decision trees and examples
• All examples are tested and accurate

Estimated Effort

3-4 hours
Related to #7369

AI generated by Plan Command for discussion #7368