feat: Refactor AST generation routes workflow

- Introduced a comprehensive data model for route definitions, parameters, and validation rules.
- Established component interfaces for route parsing, comment parsing, import resolution, route building, validation, and rendering.
- Developed a detailed implementation plan outlining execution flow, user requirements, and compliance with design principles.
- Created a quickstart guide to assist users in utilizing the refactored system effectively.
- Conducted thorough research on existing architecture, identifying key improvements and establishing a refactoring strategy.
- Specified functional requirements and user scenarios to ensure clarity and testability.
- Generated a task list for implementation, emphasizing test-driven development and parallel execution where applicable.

specs/002-refactor-ast-gen/research.md

@@ -0,0 +1,137 @@
+# Phase 0: Research Findings
+
+## Research Overview
+Conducted comprehensive analysis of existing `/projects/atomctl/pkg/ast/route/` implementation to understand current architecture, identify improvement opportunities, and establish refactoring strategy.
+
+## Key Findings
+
+### 1. Current Architecture Analysis
+
+**File Structure:**
+- `route.go` (272 lines): Core parsing logic with mixed responsibilities
+- `builder.go` (155 lines): Template data construction
+- `render.go` (54 lines): Rendering coordination entry point
+- `renderer.go` (23 lines): Template rendering wrapper
+- `router.go.tpl` (47 lines): Go template for code generation
+
+**Architecture Pattern:** Monolithic design with functional approach, lacking clear component boundaries
+
+### 2. Comparison with Refactored Provider Module
+
+| Aspect | Current Route Module | Refactored Provider Module |
+|--------|---------------------|---------------------------|
+| **Architecture** | Monolithic, flat | Component-based, layered |
+| **Components** | 5 files, unclear boundaries | 15+ files, clear separation |
+| **Error Handling** | Simple, uses panic | Comprehensive error collection |
+| **Extensibility** | Limited | Highly extensible |
+| **Test Coverage** | Minimal | Comprehensive test strategy |
+| **Configuration** | Hardcoded | Configurable system |
+
+### 3. Identified Problems
+
+**Design Principle Violations:**
+- **DRY**: Duplicate import parsing and AST traversal logic with provider module
+- **SRP**: `route.go` handles parsing, validation, and construction
+- **OCP**: Adding new parameter types requires core code changes
+- **DIP**: Direct dependencies between components
+
+**Code Quality Issues:**
+- Use of `panic` instead of proper error handling
+- Hardcoded paths and package names
+- Complex type judgment logic without abstraction
+- Insufficient test coverage
+
+### 4. Refactoring Strategy
+
+**Decision**: Adopt the successful patterns from `pkg/ast/provider` refactoring
+**Rationale**:
+- Proven architecture that SOLID principles
+- Maintains backward compatibility
+- Provides clear migration path
+- Leverages existing shared utilities
+
+**Alternatives Considered:**
+- Minimal fixes to existing code (rejected: doesn't address architectural issues)
+- Complete rewrite (rejected: too risky, breaks compatibility)
+- Incremental refactoring (selected: balances improvement and stability)
+
+## Research-Driven Decisions
+
+### 1. Architecture Decision
+**Decision**: Component-based architecture following provider patterns
+**Components to Create:**
+- `RouteParser` (coordinator)
+- `CommentParser` (annotation parsing)
+- `ImportResolver` (import processing)
+- `RouteBuilder` (route construction)
+- `RouteValidator` (validation logic)
+- `RouteRenderer` (template rendering)
+
+### 2. Compatibility Decision
+**Decision**: Maintain full backward compatibility
+**Requirements:**
+- Preserve existing `@Router` and `@Bind` annotation syntax
+- Keep `cmd/gen_route.go` interface unchanged
+- Ensure generated code output remains identical
+
+### 3. Testing Strategy Decision
+**Decision**: Test-driven development approach
+**Approach:**
+- Write comprehensive tests first (contract tests)
+- Refactor implementation to make tests pass
+- Maintain test coverage throughout refactoring
+
+### 4. Performance Decision
+**Decision**: Maintain current performance characteristics
+**Targets:**
+- <2s parsing for typical projects
+- Minimal memory overhead
+- No performance regression
+
+## Implementation Strategy
+
+### Phase 1: Design & Contracts
+1. Define new component interfaces based on provider patterns
+2. Create data models and contracts
+3. Establish test scenarios and acceptance criteria
+
+### Phase 2: Task Implementation
+1. Implement new component architecture
+2. Migrate existing logic incrementally
+3. Maintain compatibility through testing
+
+### Phase 3: Validation
+1. Comprehensive testing across all scenarios
+2. Performance validation
+3. Integration testing with existing systems
+
+## Risk Assessment
+
+**Low Risk:**
+- Backward compatibility maintained
+- Incremental refactoring approach
+- Proven architectural patterns
+
+**Medium Risk:**
+- Complex parameter handling logic migration
+- Template system integration
+- Error handling standardization
+
+**Mitigation Strategies:**
+- Comprehensive test coverage
+- Incremental implementation with validation
+- Rollback capability at each stage
+
+## Success Criteria
+
+1. **Code Quality**: Clear separation of concerns, SOLID compliance
+2. **Maintainability**: Component-based architecture with clear boundaries
+3. **Testability**: Comprehensive test coverage with clear contract tests
+4. **Compatibility**: Zero breaking changes to existing functionality
+5. **Performance**: No performance regression
+
+## Conclusion
+
+The research confirms that refactoring `pkg/ast/route` using the successful patterns from `pkg/ast/provider` is the optimal approach. This will improve code maintainability, testability, and extensibility while preserving all existing functionality.
+
+**Decision Status**: ✅ APPROVED - Proceed to Phase 1 design