docster/agents.md

Claude Code Agents

This project uses specialized Claude Code agents for different types of Haskell refactoring. Each agent has focused expertise to provide targeted improvements.

Available Agents

haskell-refactoring-expert

Purpose: Basic code quality and structural improvements

Expertise:

• Type consistency (String vs Text vs ByteString)
• Module organization and file splitting (>150 lines)
• Naming conventions and clarity
• Dependency management
• Basic code structure improvements

When to use:

• Inconsistent type usage across the codebase
• Large files that need module organization
• Poor naming or unclear function responsibilities
• Mixed concerns in single modules

Example: Converting a 300-line Main.hs into proper module hierarchy

haskell-higher-order

Purpose: Advanced functional programming patterns and architectural refactoring

Expertise:

• Monad transformer patterns (ExceptT, ReaderT, StateT)
• Pipeline composition with monadic operators
• Higher-order abstractions and strategy patterns
• Effect management and pure/IO separation
• Functional design patterns

When to use:

• Nested case statements handling Either values in IO
• Duplicated functions that differ only in specific steps
• Manual threading of configuration or state
• Imperative-style code that could be more functional
• Complex error handling that needs cleanup

Example: Converting nested Either/IO handling to ExceptT pipelines

Agent Boundaries and Trade-offs

Complementary Design

These agents are designed to work sequentially:

1. First pass: haskell-refactoring-expert for structural cleanup
2. Second pass: haskell-higher-order for functional patterns

Why Separate Agents?

Benefits:

• Focused expertise: Each agent has deep knowledge in its domain
• Clear boundaries: Easy to know which agent to use
• Manageable complexity: Avoids instruction bloat in single agent
• Progressive enhancement: Apply increasingly sophisticated refactoring
• Composability: Can run both agents or just one as needed

Trade-offs:

• Coordination overhead: Need to run multiple agents
• Context switching: Each agent analyzes code independently
• Potential overlap: Some patterns might fit both agents

Decision Framework

Use haskell-refactoring-expert when you have:

• ❌ Mixed String/Text types
• ❌ Large monolithic files (>150 lines)
• ❌ Unclear naming or responsibilities
• ❌ Basic structural issues

Use haskell-higher-order when you have:

• ❌ Nested error handling (Either in IO)
• ❌ Duplicated function structures
• ❌ Manual state/config threading
• ❌ Imperative-style patterns

Use both agents when:

• ❌ You want comprehensive refactoring
• ❌ Code has both structural and architectural issues
• ❌ You're doing major codebase improvements

Usage Patterns

Sequential Refactoring

# Run basic refactoring first
/agent haskell-refactoring-expert "Please refactor the Main.hs file"

# Then apply advanced patterns  
/agent haskell-higher-order "Please improve the error handling patterns"

Targeted Improvements

# Just structural cleanup
/agent haskell-refactoring-expert "Split this large module"

# Just functional patterns
/agent haskell-higher-order "Convert these nested cases to monadic style"

Evolution Strategy

These agents can evolve independently:

• haskell-refactoring-expert: Add more structural patterns, linting rules
• haskell-higher-order: Add more advanced patterns (free monads, effect systems)

New specialized agents could be added:

• haskell-performance: Optimization-focused refactoring
• haskell-testing: Test-driven refactoring and property-based testing
• haskell-domain: Domain modeling and type design

The key is maintaining clear boundaries and complementary functionality.