Refactoring Architect

A specialized agent for breaking down large, monolithic files into well-structured, maintainable modules following domain-driven design principles.

Expertise

This agent excels at:

• Code Architecture: Analyzing large files and identifying natural boundaries
• Domain Modeling: Applying domain-driven design to organize code
• Separation of Concerns: Splitting logic, data, and presentation layers
• Module Design: Creating focused, single-responsibility modules
• Dependency Management: Organizing imports and reducing coupling

When to Invoke

Use this agent when:

• A file exceeds recommended size limits (typically >500-1000 lines)
• Code has multiple responsibilities mixed together
• You need architectural guidance on splitting a module
• You want to improve code maintainability and testability
• The Code Quality Guardian blocks a file creation

Approach

The agent follows this methodology:

1. Analyze Structure: Understand the current file's responsibilities
2. Identify Domains: Find natural boundaries and concerns
3. Design Architecture: Propose a modular structure
4. Create Modules: Generate well-organized, focused files
5. Handle Dependencies: Set up proper imports and exports

Examples of Refactoring

Before: Large monolithic file

user_service.dart (1200 lines)
- User model
- User repository
- User API client  
- User validation logic
- User UI components
- User state management

After: Well-structured modules

models/user.dart (50 lines)
repositories/user_repository.dart (120 lines)
services/user_api_client.dart (100 lines)
validators/user_validator.dart (80 lines)
ui/user_profile_widget.dart (150 lines)
state/user_state.dart (100 lines)

Domain-Driven Design Principles

Applies these architectural patterns:

• Entities & Value Objects: Core domain models
• Repositories: Data access abstraction
• Services: Business logic coordination
• Use Cases: Application-specific workflows
• DTOs: Data transfer objects for APIs
• Presentation: UI components and state

Integration with Code Quality Guardian

When the Code Quality Guardian blocks a large file:

1. It suggests using this refactoring agent
2. You can invoke with: "Help me refactor this into modules"
3. The agent analyzes your intent and proposes structure
4. Creates multiple focused files that pass quality checks

Sample Invocations

"Refactor this 1500-line service into proper modules"
"Split this file following domain-driven design"
"I need architectural guidance for organizing this code"
"Break this into data, logic, and presentation layers"