# **Refactor Code Command Specification (Extended and Authoritative Edition)**

**BCP 14 Boilerplate**  
The key words **“MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”,** and **“OPTIONAL”** in this document are to be interpreted as described in **RFC 2119** and **RFC 8174**.

---

## 🧩 Mission

The `/refactor_code` command is a **coordinated multi-agent refactoring system** designed to simplify, modularize, and stabilize codebases through structured, rule-driven refinement.  
All operations **MUST** be performed through the **Eight-Agent Architecture**, which collectively enforces cohesion, encapsulation, ownership, abstraction, and convergence across recursive refactoring cycles.

This document defines the complete process model, agent interactions, automation layer behavior, and fail-fast protocols required to guarantee deterministic, verifiable code refinement.

---

## ⚖️ Agent Utilization Requirement

1. Claude **MUST** execute all refactoring operations exclusively through the nine defined agents.
2. Each agent **MUST** be invoked according to the orchestration sequence (Analyzer → Implementation → Orchestrator).
3. Direct code manipulation, heuristic rewriting, or manual edits **MUST NOT** occur outside of agent execution.
4. If an agent fails or encounters invalid data, the **Refactoring Orchestrator (Agent 10)** **MUST** halt the pipeline, report the error, and either retry or terminate based on the fail-fast policy.
5. Claude **MUST NOT** bypass or substitute agents with ad hoc reasoning. All logic **MUST** route through the respective agent responsible for that domain of concern.
6. Violating this section **SHALL** constitute a **Protocol Failure**, which invalidates the refactoring result.

---

## 🎯 Single Responsibility Principle (Absolute Enforcement)

1. **Every class MUST have exactly ONE responsibility.**
2. When multiple responsibilities are detected in a class, extraction **MUST** occur, without exception.
3. The following are **NOT** valid reasons to avoid extraction:
   - "The resulting classes would be too small"
   - "This would create too many classes"
   - "The code would be harder to understand"
   - "The current structure is simpler"
4. Extraction **MUST** continue until each class answers to exactly one reason to change.
5. This requirement overrides subjective concerns about code organization, clarity, or simplicity.
6. Technical constraints (semantic preservation, no stateless classes, no cycles) remain the **ONLY** valid reasons to halt extraction.

**Rationale:** Small, focused classes with single responsibilities are easier to test, maintain, and reason about than large classes with multiple responsibilities, regardless of initial perception of simplicity.

---

## ⚙️ Overview of the Nine-Agent Architecture

| # | Agent | Primary Responsibility |
|--:|--------|------------------------|
| **1** | **Code Structure Analyzer** | Parse and evaluate code structure, measure complexity, cohesion, and coupling. |
| **2** | **Method Extraction & Control Normalization Agent** | Extract smaller, independent methods and flatten control flow. |
| **3** | **Cohesion & Class Extraction Agent** | Group related methods and fields into cohesive classes with single responsibility. |
| **4** | **Encapsulation Enforcer Agent** | Enforce strict data hiding, remove getters/setters, and verify naming discipline (noun–verber rule). |
| **5** | **Ownership & Boundary Enforcement Agent** | Ensure domain objects act on their own data and boundaries remain pure (no DTO or adapter leakage). |
| **6** | **Abstraction Enforcer Agent** | Guarantee single-level abstraction within all methods and delegation consistency. |
| **7** | **Metrics & Convergence Monitor Agent** | Aggregate metrics, track stability trends, and detect convergence or regressions. |
| **9** | **Code Implementation Agent** | Execute all identified refactorings, creating and modifying source files. |
| **10** | **Refactoring Orchestrator Agent** | Manage agent sequencing, recursion, implementation phase, fail-fast responses, and convergence certification. |

Each agent's output feeds directly into the next in a **closed operational loop** under Orchestrator supervision.

---

## 🔁 Main Execution Model

### **Primary Control Loop**

REPEAT

ANALYSIS PHASE

0. Run Naming Audit Pre-Flight (Agent 4 in audit mode)
1. Analyze code structure and metrics (Agent 1)
2. Extract and normalize methods (Agent 2)
3. Identify and extract cohesive classes (Agent 3)
4. Enforce encapsulation and noun–verber naming rules (Agent 4)
5. Enforce ownership and boundary control (Agent 5)
6. Verify abstraction consistency (Agent 6)
7. Aggregate and evaluate convergence metrics (Agent 7)

IMPLEMENTATION PHASE (if needed)

9. IF convergence not achieved: Execute code implementation (Agent 9) Apply all identified refactorings ENDIF

ORCHESTRATION

10. Coordinate recursion, restart analysis, or finalize (Agent 10)

UNTIL all convergence thresholds met OR fail-fast triggered

Each agent's actions **MUST** be executed in the above sequence without omission or substitution.
Intermediate outputs are immutable records that serve as formal checkpoints between agents.

---

## 🧱 Recursive Class Refinement

### **Purpose**
When new classes are extracted by **Agent 3 (Cohesion & Class Extraction)**, the system recursively applies further refinement to those classes until stability is achieved.

### **Rules**
1. The Orchestrator **MUST** re-run the following sequence for every extracted class: **Agents 3 → 4 → 5 → 6**.  
2. If the extracted class contains **three (3) or fewer methods**, the Orchestrator **SHOULD** begin at **Agent 4 (Encapsulation Enforcer)** instead.  
3. Each recursion **MUST** conclude only when no further extractions or renames are possible.  
4. All recursion cycles **MUST** verify naming compliance (noun–verbe