Document type patterns and best practices for Go code

[Copilot]

Adds comprehensive documentation on type patterns following the Typist analysis that identified both good patterns to follow and appropriate uses of any.

New Specification

specs/go-type-patterns.md - 18KB guide covering:

• Semantic type aliases - Domain-specific primitives (LineLength, Version, feature flag constants)
• Dynamic types - Appropriate use of map[string]any for YAML/JSON parsing
• Interface patterns - Behavior contracts and configuration interfaces
• Type safety - Guidelines, anti-patterns, decision trees

AGENTS.md Updates

Added "Type Patterns and Best Practices" section in Development Guidelines:

// ✅ Semantic type alias for domain concept
type LineLength int
const MaxExpressionLineLength LineLength = 120

// ✅ Dynamic type for unknown structure at compile time
func ProcessFrontmatter(frontmatter map[string]any) error

// ✅ Document why 'any' is necessary
// githubTool uses any because tool configuration structure
// varies based on engine and toolsets
func ValidatePermissions(permissions *Permissions, githubTool any)

Inline Documentation

Enhanced documentation in:

• pkg/constants/constants.go - Semantic type aliases with usage examples
• pkg/workflow/permissions_validator.go - Why any is appropriate for dynamic tool config
• pkg/parser/frontmatter.go - Dynamic YAML parsing pattern explanation

References specs/go-type-patterns.md for detailed guidance on when to use each pattern.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Document type patterns and best practices</issue_title>
<issue_description>## 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

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Document type patterns and best practices #6841

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.