Proposal: Refactor to a Skill-Based Architecture for Code Analysis

[Utakata]

Overview

This proposal outlines an initial plan to refactor our code analysis engine to a new, skill-based architecture. The primary goal is to unify functionality, reduce code duplication, and create a more modular and extensible system.

This plan is guided by three core principles:

1. Maintain Backward Compatibility: Existing commands and agents should continue to function with minimal or no breaking changes.
2. Refactor to Skills: Rewrite existing commands, agents, and modes to consume a centralized library of "skills."
3. Reduce Code Generation: Discover new methods to leverage skills to reduce boilerplate and dynamically generate code more effectively.

Background & Rationale: The Need for Unification

A recent analysis of our ecosystem revealed significant version fragmentation across our distribution channels:

• npm version: 4.1.5
• Python (pip) version: 4.1.6
• Claude Code Plugin version: 4.2.0

This version mismatch is a symptom of a larger architectural problem: decentralized and duplicated logic. Each package is maintained and released independently, leading to inconsistencies. A unified, skill-based architecture will solve this at its root by creating a single source of truth for core functionalities.

The Skill-Based Architecture Proposal

Instead of commands and agents having their own isolated logic, they will be refactored to call a shared pool of skills. A "skill" is an atomic, reusable function that performs a specific, well-defined task (e.g., find_function_definition, analyze_code_complexity).

1. Maintain Existing Commands/Agents

The public-facing commands and agents will act as a compatibility layer. Their primary role will be to parse user input and delegate tasks to the appropriate skills from the new core library. This ensures that user workflows are not disrupted.

Example (pseudo-code):

# Old agent logic
class CodeAnalysisAgent:
    def find_definitions(self, code):
        # ... complex, self-contained logic here ...
        pass

# New agent logic (as a wrapper)
from skills_library import find_definitions_skill

class CodeAnalysisAgent:
    def find_definitions(self, code):
        # Delegate to the centralized skill
        return find_definitions_skill.execute(code)

2. Rewrite Core Logic as Skills

All substantive logic will be extracted from existing commands and refactored into a new, shared skills_library. This eliminates redundancy and makes functionality easier to test, maintain, and improve.

3. Discover New Efficiencies

By centralizing logic into skills, we can identify patterns and create higher-order functions that combine skills in novel ways. This will allow us to generate complex code analysis results with less boilerplate code.

Example:
Instead of an agent manually calling three separate functions, we can create a "meta-skill" that orchestrates them.

Architectural Diagram: From Silos to a Shared Core

This diagram illustrates the proposed shift.

graph TD
    subgraph "Current Architecture (Siloed)"
        A[Command A] --> A1[Logic for Task X]
        B[Agent B] --> B1[Duplicated Logic for Task X]
        C[Mode C] --> C1[Variant Logic for Task X]
    end

    subgraph "Proposed Skill-Based Architecture (Unified)"
        D[Command A]
        E[Agent B]
        F[Mode C]
        
        subgraph "Shared Skills Library"
            G[Skill: Task X]
            H[Skill: Task Y]
            I[Skill: Task Z]
        end

        D --> G
        E --> G
        F --> G
    end

Loading

This refactor will provide a solid foundation for future development, ensuring consistency and stability across all parts of the SuperClaude ecosystem.

[Utakata]

Proposal: Refactor to a Skill-Based Architecture for Code Analysis

Overview

This proposal outlines an initial plan to refactor our code analysis engine to a new, skill-based architecture. The primary goal is to unify functionality, reduce code duplication, and create a more modular and extensible system.

This plan is guided by three core principles:

1. Maintain Backward Compatibility: Existing commands and agents should continue to function with minimal or no breaking changes.
2. Refactor to Skills: Rewrite existing commands, agents, and modes to consume a centralized library of "skills."
3. Reduce Code Generation: Discover new methods to leverage skills to reduce boilerplate and dynamically generate code more effectively.

Background & Rationale: The Need for Unification

A recent analysis of our ecosystem revealed significant version fragmentation across our distribution channels:

• npm version: 4.1.5
• Python (pip) version: 4.1.6
• Claude Code Plugin version: 4.2.0

This version mismatch is a symptom of a larger architectural problem: decentralized and duplicated logic. Each package is maintained and released independently, leading to inconsistencies. A unified, skill-based architecture will solve this at its root by creating a single source of truth for core functionalities.

The Skill-Based Architecture Proposal

Instead of commands and agents having their own isolated logic, they will be refactored to call a shared pool of skills. A "skill" is an atomic, reusable function that performs a specific, well-defined task (e.g., find_function_definition, analyze_code_complexity).

1. Maintain Existing Commands/Agents

The public-facing commands and agents will act as a compatibility layer. Their primary role will be to parse user input and delegate tasks to the appropriate skills from the new core library. This ensures that user workflows are not disrupted.

Example (pseudo-code):

# Old agent logic
class CodeAnalysisAgent:
    def find_definitions(self, code):
        # ... complex, self-contained logic here ...
        pass

# New agent logic (as a wrapper)
from skills_library import find_definitions_skill

class CodeAnalysisAgent:
    def find_definitions(self, code):
        # Delegate to the centralized skill
        return find_definitions_skill.execute(code)