♻️ Refactoring Agent Specification¶

🎯 Purpose¶

The Refactoring Agent is responsible for technical debt reduction, code restructuring, dependency upgrades, pattern alignment, and architecture drift correction across the ConnectSoft AI Software Factory codebase.

Its mission is to ensure that the codebase remains healthy, modern, and architecturally aligned as the platform evolves — proactively identifying and resolving structural decay before it compounds into systemic risk.

💡 Why This Agent Matters¶

Without this agent:

Technical debt would accumulate silently until it blocks feature delivery
Architecture drift would widen the gap between design intent and implementation reality
Dependency upgrades would be deferred indefinitely, creating security vulnerabilities
Dead code and abandoned patterns would increase cognitive load and build times
API version migrations would be manual, risky, and incomplete

With the Refactoring Agent:

✅ Technical debt is quantified, prioritized, and systematically reduced ✅ Architecture drift is detected and corrected before it propagates ✅ Dependencies are upgraded automatically with compatibility validation ✅ Dead code is identified and safely eliminated with impact analysis ✅ Pattern alignment ensures consistent architecture across all services

🧱 What This Agent Enables¶

Capability	Impact
🧹 Code restructuring	Extract methods, rename, move classes, simplify inheritance
📐 Pattern alignment	Enforce consistent use of DDD, Clean Architecture, CQRS patterns
📦 Dependency upgrade automation	Update NuGet/npm packages with compatibility testing
🧭 Architecture drift correction	Realign implementation to architectural blueprints
🗑️ Dead code elimination	Identify and remove unused code, types, and imports
🔄 API version migration	Migrate consumers when internal or external APIs evolve
🏗️ Framework upgrade planning	Plan and execute .NET, Angular, or infrastructure framework upgrades

🧭 Role in the Platform¶

The Refactoring Agent sits within the Software Engineering cluster, working alongside quality and review agents to maintain codebase health. It was introduced in the Cycle 20 roadmap as referenced in engineering-agents-overview.md.

flowchart TD
    CodeQuality[Code Quality Agent]
    Refactoring[♻️ Refactoring Agent]
    CodeReviewer[Code Reviewer Agent]
    TechLead[Tech Lead Agent]
    BackendDev[Backend Developer Agent]
    FrontendDev[Frontend Developer Agent]

    CodeQuality --> Refactoring
    TechLead --> Refactoring
    Refactoring --> CodeReviewer
    Refactoring --> BackendDev
    Refactoring --> FrontendDev

Hold "Alt" / "Option" to enable pan & zoom

📡 Triggering Events¶

Event	Source	Description
`technical_debt_threshold_exceeded`	Code Quality Agent	Accumulated tech debt score exceeds configured threshold
`architecture_drift_detected`	Code Reviewer Agent / Architect Agents	Implementation diverges from architectural blueprint
`dependency_upgrade_required`	Security Scanner / Dependency Monitor	Package has known vulnerability or is end-of-life
`framework_upgrade_planned`	Tech Lead Agent	Major framework version upgrade scheduled
`dead_code_report_generated`	Code Quality Agent	Unused code detected above acceptable percentage
`api_deprecation_announced`	API Designer Agent	Internal or external API version being retired
`refactoring_sprint_initiated`	Tech Lead Agent / Orchestrator	Dedicated refactoring cycle triggered

📋 Core Responsibilities¶

🔧 Responsibilities Overview¶

#	Responsibility	Description	Output
1	Code restructuring	Extract methods, simplify conditionals, decompose classes, flatten inheritance	`refactoring-plan.yaml`, code patches
2	Pattern alignment	Enforce DDD, Clean Architecture, CQRS, and port/adapter patterns consistently	`pattern-alignment-report.yaml`
3	Dependency upgrade automation	Update packages, resolve breaking changes, run compatibility tests	`dependency-upgrade-plan.yaml`
4	Architecture drift correction	Compare implementation against blueprints, generate corrective refactors	`drift-correction-plan.yaml`
5	Dead code elimination	Identify unused types, methods, imports, and safely remove them	`dead-code-report.yaml`, removal patches
6	API version migration	Update consumers when APIs evolve, generate migration guides	`api-migration-plan.yaml`
7	Framework upgrade planning	Plan multi-step framework upgrades with risk assessment and rollback	`framework-upgrade-plan.yaml`

📦 Deliverables¶

Artifact	Format	Purpose
`refactoring-plan.yaml`	YAML	Prioritized list of refactoring tasks with effort estimates
`code-migration.patch`	Git diff	Concrete code changes implementing refactoring decisions
`pattern-alignment-report.yaml`	YAML	Analysis of pattern adherence with violation details
`dependency-upgrade-plan.yaml`	YAML	Package upgrade sequence with compatibility matrix
`drift-correction-plan.yaml`	YAML	Steps to realign implementation with architecture blueprints
`dead-code-report.yaml`	YAML	Inventory of unused code with safe removal recommendations
`api-migration-plan.yaml`	YAML	Consumer migration steps for deprecated API versions
`framework-upgrade-plan.yaml`	YAML	Multi-phase framework upgrade with risk and rollback steps
`refactoring-impact.mmd`	Mermaid	Visual impact diagram of proposed refactoring changes
`RefactoringPlanPublished`	JSON (Event)	Lifecycle event emitted on plan generation

🧹 1. Code Restructuring¶

Technique	When Applied	Risk Level
Extract Method	Long methods exceeding complexity threshold	Low
Extract Class	Classes with multiple responsibilities (SRP violation)	Medium
Move Method/Class	Code in wrong architectural layer or namespace	Medium
Simplify Conditional	Deeply nested if/else or switch statements	Low
Replace Inheritance with Composition	Fragile base class or deep hierarchy	High
Introduce Interface	Tight coupling between concrete implementations	Medium
Inline Dead Abstraction	Over-engineered abstractions with single implementation	Low

📐 2. Pattern Alignment¶

Pattern	Enforcement Rule	Correction
Clean Architecture	Domain must not reference Infrastructure	Move dependency, introduce port interface
CQRS	Commands and queries must be separate handlers	Split combined handlers into distinct classes
DDD Aggregates	Aggregates must enforce invariants internally	Move validation from services into aggregate roots
Port/Adapter	External calls must go through adapter interfaces	Extract adapter, inject via DI
Repository Pattern	Data access must use repository abstractions	Replace direct DbContext usage
Event-Driven	Side effects should be triggered via domain events	Extract side effects into event handlers

📦 3. Dependency Upgrade Automation¶

Phase	Action	Output
Discovery	Scan all package references, identify outdated versions	`dependency-audit.yaml`
Risk Assessment	Check breaking changes, deprecations, and CVEs	Risk matrix per package
Upgrade Planning	Determine upgrade order respecting dependency chains	`dependency-upgrade-plan.yaml`
Compatibility Testing	Run build + test suite after each upgrade step	Test results per upgrade step
Rollback Preparation	Generate rollback lockfile for each upgrade step	Restore points

🧭 4. Architecture Drift Correction¶

Detection Method	Correction Strategy
Layer dependency violation (e.g., UI → Infrastructure)	Introduce abstraction, move code to correct layer
Missing domain events for side effects	Extract side effects into event handlers
Direct database access from application services	Introduce repository port and adapter
Hardcoded configuration values	Extract to configuration provider or vault
Inconsistent naming across bounded contexts	Rename and align to ubiquitous language glossary

Drift Detection Flow¶

flowchart TD
    Blueprint[Architecture Blueprint]
    Codebase[Current Codebase]
    DriftAnalysis[🔍 Drift Analysis]
    DriftReport[Drift Report]
    CorrectionPlan[Correction Plan]
    Patches[Code Patches]

    Blueprint --> DriftAnalysis
    Codebase --> DriftAnalysis
    DriftAnalysis --> DriftReport
    DriftReport --> CorrectionPlan
    CorrectionPlan --> Patches

Hold "Alt" / "Option" to enable pan & zoom

🗑️ 5. Dead Code Elimination¶

Detection Type	Examples	Safety Check
Unused types	Classes never instantiated or referenced	Cross-project reference scan
Unused methods	Private/internal methods with zero callers	Call graph analysis
Unused imports	`using` / `import` statements with no resolution	Compiler/linter verification
Orphaned files	Files not referenced in any project or build	Build dependency validation
Feature flag remnants	Code behind permanently disabled flags	Feature flag registry check

🤝 Collaboration Interfaces¶

🔼 Upstream Providers¶

Agent	Input Artifact
Code Quality Agent	Technical debt scores, complexity reports, duplication analysis
Code Reviewer Agent	Architecture violations detected during PR reviews
Tech Lead Agent	Refactoring priorities, framework upgrade decisions
Architect Agents	Architecture blueprints for drift comparison

🔽 Downstream Consumers¶

Agent	Consumes
Code Reviewer Agent	Reviews refactoring patches before merge
Backend Developer Agent	Implements complex refactorings that exceed automation scope
Frontend Developer Agent	Applies UI framework upgrades and component restructuring
Test Generator Agent	Regenerates tests for refactored code
Documentation Writer Agent	Updates documentation affected by structural changes

📡 Collaboration Flow¶

flowchart TD
    CodeQualityAgent --> RefactoringAgent
    CodeReviewerAgent --> RefactoringAgent
    TechLeadAgent --> RefactoringAgent
    ArchitectAgents --> RefactoringAgent

    RefactoringAgent --> CodeReviewerAgent
    RefactoringAgent --> BackendDeveloper
    RefactoringAgent --> FrontendDeveloper
    RefactoringAgent --> TestGenerator
    RefactoringAgent --> DocumentationWriter

Hold "Alt" / "Option" to enable pan & zoom

📚 Memory and Knowledge¶

🕐 Short-Term (Session) Memory¶

Key	Purpose
`trace_id`	Tracks all outputs and events for the current refactoring cycle
`refactoring_scope`	Files, projects, and patterns targeted in this session
`dependency_graph`	Current project dependency tree for impact analysis
`change_set[]`	Accumulated code changes proposed in this session
`test_results[]`	Validation results from refactoring compatibility tests

🧠 Long-Term Semantic Memory¶

Data	Used For
Previous refactoring outcomes	Track success rates and avoid repeating failed approaches
Dependency upgrade history	Know which versions have been tested and their compatibility
Architecture blueprint versions	Compare current codebase against historical and current blueprints
Dead code removal history	Prevent re-introduction of previously eliminated code
Pattern violation frequency	Prioritize refactoring efforts on chronic problem areas

🧠 Knowledge Base¶

Domain	Content
Refactoring Catalog	Martin Fowler's refactoring patterns adapted for ConnectSoft conventions
Framework Migration Guides	.NET 6→8, Angular version upgrades, EF Core migration paths
Dependency Compatibility Matrix	Known breaking changes and workarounds for common packages
ConnectSoft Architecture Rules	Clean Architecture boundaries, naming conventions, pattern requirements
Safe Refactoring Techniques	Behavior-preserving transformations with pre/post verification

✅ Validation and Correction¶

🔍 Validation Rules¶

Rule	Description	Severity
All refactorings must be behavior-preserving	Tests must pass before and after	Critical
Dependency upgrades must not introduce known CVEs	Security scan post-upgrade	Critical
Removed code must have zero references across all projects	Cross-project impact analysis	Critical
Pattern corrections must align with current architecture blueprint	Blueprint compliance check	High
Refactoring patches must compile without errors	Build validation	Critical
Renamed symbols must be updated across all consumers	Global rename verification	High

🔁 Auto-Correction Behaviors¶

Condition	Correction
Test failure after refactoring	Revert change, flag for manual review
Dependency upgrade breaks build	Roll back to last working version, report incompatibility
Renamed symbol missed in one project	Extend rename scope and re-validate
Dead code removal triggers build error	Restore code, refine detection criteria
Pattern correction introduces circular dependency	Restructure with intermediate abstraction

📈 Observability Spans¶

Span Name	Trigger
`refactoring_analysis_started`	Agent begins codebase analysis
`debt_assessment_completed`	Technical debt inventory finished
`refactoring_plan_generated`	Prioritized plan created
`code_patches_applied`	Refactoring changes implemented
`validation_passed`	All tests and builds pass post-refactoring
`refactoring_plan_published`	All artifacts emitted successfully

📢 Lifecycle Events¶

Event	Trigger	Payload
`RefactoringPlanPublished`	Plan generation completed	Scope, priority items, trace_id
`DependencyUpgradeCompleted`	Package upgrades applied successfully	Package list, version changes
`ArchitectureDriftCorrected`	Drift corrections applied and validated	Affected files, pattern corrections
`DeadCodeEliminated`	Unused code successfully removed	Removed items count, space saved
`RefactoringValidationFailed`	Post-refactoring tests or build failed	Failed tests, affected changes

✅ Summary¶

The Refactoring Agent ensures the ConnectSoft codebase remains healthy and architecturally aligned:

Capability	Status
🧹 Systematic code restructuring with behavior preservation	✅
📐 Continuous pattern alignment to Clean Architecture and DDD	✅
📦 Automated dependency upgrades with compatibility testing	✅
🧭 Architecture drift detection and correction	✅
🗑️ Safe dead code elimination with impact analysis	✅
🔄 API version migration automation	✅
🏗️ Framework upgrade planning with rollback support	✅

"The Refactoring Agent acts as the codebase's immune system — continuously detecting structural decay, technical debt, and architectural drift, then systematically restoring health through safe, validated, and traceable transformations."