[plan] Document type patterns and best practices

[github-actions]

Objective

Update developer documentation to reflect the new type patterns and provide guidance on when to use different typing approaches in the codebase.

Context

The Typist analysis identified both good patterns to follow and appropriate uses of any. Documentation should:

• Explain when to use semantic type aliases (like FeatureFlag, LineLength)
• Clarify when map[string]any is appropriate (dynamic YAML/JSON)
• Document the new ValidatableTool interface pattern
• Provide guidelines to prevent future type name collisions

Implementation Steps

1. Update AGENTS.md Developer Instructions section:

   • Add section on "Type Patterns and Best Practices"
   • Document semantic type aliases pattern
   • Explain appropriate uses of any types
   • Add guidelines for avoiding type name collisions

2. Create or update specs/go-type-patterns.md:

   • Document ValidatableTool interface pattern
   • Explain FeatureFlag type alias pattern
   • Show examples of when to use each approach
   • Include anti-patterns (what NOT to do)

3. Add inline code documentation:

   • Document ValidatableTool interface with usage examples
   • Document FeatureFlag type with usage examples
   • Add comments explaining why map[string]any is used for YAML parsing

Files to Create/Modify

• AGENTS.md - Add type patterns section
• specs/go-type-patterns.md (new) - Detailed type pattern guide
• pkg/workflow/permissions_validator.go - Add interface documentation
• pkg/constants/constants.go - Add type alias documentation

Acceptance Criteria

• Developer documentation updated with type patterns
• New spec file created with detailed guidance
• Interface and type aliases have clear documentation
• Examples show both correct and incorrect usage
• Guidelines prevent future type collisions
• Documentation reviewed for clarity

Estimated Effort

1 hour

Priority

Low-Medium - Important for maintainability and future contributors

Dependencies

Should be completed last, after all code changes are finalized
Related to #6836

AI generated by Plan Command for discussion #6829