refactor: responsibility-driven component architecture

Rename components to reflect their responsibilities:
- framework_docs.py → knowledge_base.py (KnowledgeBaseComponent)
- modes.py → behavior_modes.py (BehaviorModesComponent)
- agents.py → agent_personas.py (AgentPersonasComponent)
- commands.py → slash_commands.py (SlashCommandsComponent)
- mcp.py → mcp_integration.py (MCPIntegrationComponent)

Each component now clearly documents its responsibility:
- knowledge_base: Framework knowledge initialization
- behavior_modes: Execution mode definitions
- agent_personas: AI agent personality definitions
- slash_commands: CLI command registration
- mcp_integration: External tool integration

Benefits:
- Self-documenting architecture
- Clear responsibility boundaries
- Easy to navigate and extend
- Scalable for future hierarchical organization

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

setup/components/__init__.py

@@ -1,15 +1,24 @@
-"""Component implementations for SuperClaude installation system"""
+"""
+Component Directory
 
-from .framework_docs import FrameworkDocsComponent
-from .commands import CommandsComponent
-from .mcp import MCPComponent
-from .agents import AgentsComponent
-from .modes import ModesComponent
+Each module defines an installable responsibility unit:
+- knowledge_base: Framework knowledge initialization
+- behavior_modes: Execution mode definitions
+- agent_personas: AI agent personality definitions
+- slash_commands: CLI command registration
+- mcp_integration: External tool integration via MCP
+"""
+
+from .knowledge_base import KnowledgeBaseComponent
+from .behavior_modes import BehaviorModesComponent
+from .agent_personas import AgentPersonasComponent
+from .slash_commands import SlashCommandsComponent
+from .mcp_integration import MCPIntegrationComponent
 
 __all__ = [
-    "FrameworkDocsComponent",
-    "CommandsComponent",
-    "MCPComponent",
-    "AgentsComponent",
-    "ModesComponent",
+    "KnowledgeBaseComponent",
+    "BehaviorModesComponent",
+    "AgentPersonasComponent",
+    "SlashCommandsComponent",
+    "MCPIntegrationComponent",
 ]

setup/components/agent_personas.py

@@ -1,4 +1,4 @@
-"""
+"""\nAgent Personas Component\n\nResponsibility: Defines AI agent personalities and role-based behaviors.\nProvides specialized personas for different task types.\n"""\n\n"""
 Agents component for SuperClaude specialized AI agents installation
 """
 
@@ -9,7 +9,7 @@ from ..core.base import Component
 from setup import __version__
 
 
-class AgentsComponent(Component):
+class AgentPersonasComponent(Component):
     """SuperClaude specialized AI agents component"""
 
     def __init__(self, install_dir: Optional[Path] = None):

setup/components/behavior_modes.py

@@ -1,4 +1,4 @@
-"""
+"""\nBehavior Modes Component\n\nResponsibility: Defines and manages execution modes for Claude behavior.\nControls how Claude responds to different contexts and user intent.\n"""\n\n"""
 Modes component for SuperClaude behavioral modes
 """
 
@@ -10,7 +10,7 @@ from setup import __version__
 from ..services.claude_md import CLAUDEMdService
 
 
-class ModesComponent(Component):
+class BehaviorModesComponent(Component):
     """SuperClaude behavioral modes component"""
 
     def __init__(self, install_dir: Optional[Path] = None):

setup/components/knowledge_base.py

@@ -1,6 +1,9 @@
 """
-Framework documentation component for SuperClaude
-Manages core framework documentation files (CLAUDE.md, FLAGS.md, PRINCIPLES.md, etc.)
+Knowledge Base Component for SuperClaude
+
+Responsibility: Provides structured knowledge initialization for the framework.
+Manages framework knowledge documents (principles, rules, flags, research config, business patterns).
+These files form the foundation of Claude's understanding of the SuperClaude framework.
 """
 
 from typing import Dict, List, Tuple, Optional, Any
@@ -12,20 +15,25 @@ from ..services.claude_md import CLAUDEMdService
 from setup import __version__
 
 
-class FrameworkDocsComponent(Component):
-    """SuperClaude framework documentation files component"""
+class KnowledgeBaseComponent(Component):
+    """
+    Knowledge Base Component
+
+    Responsibility: Initialize and maintain SuperClaude's knowledge base.
+    Installs framework knowledge documents that guide Claude's behavior and decision-making.
+    """
 
     def __init__(self, install_dir: Optional[Path] = None):
-        """Initialize framework docs component"""
+        """Initialize knowledge base component"""
         super().__init__(install_dir)
 
     def get_metadata(self) -> Dict[str, str]:
         """Get component metadata"""
         return {
-            "name": "framework_docs",
+            "name": "knowledge_base",
             "version": __version__,
-            "description": "SuperClaude framework documentation (CLAUDE.md, FLAGS.md, PRINCIPLES.md, RULES.md, etc.)",
-            "category": "documentation",
+            "description": "SuperClaude knowledge base (principles, rules, flags, patterns)",
+            "category": "knowledge",
         }
 
     def is_reinstallable(self) -> bool:
@@ -43,7 +51,7 @@ class FrameworkDocsComponent(Component):
                 "name": "superclaude",
                 "description": "AI-enhanced development framework for Claude Code",
                 "installation_type": "global",
-                "components": ["framework_docs"],
+                "components": ["knowledge_base"],
             },
             "superclaude": {
                 "enabled": True,
@@ -54,8 +62,8 @@ class FrameworkDocsComponent(Component):
         }
 
     def _install(self, config: Dict[str, Any]) -> bool:
-        """Install framework docs component"""
-        self.logger.info("Installing SuperClaude framework documentation...")
+        """Install knowledge base component"""
+        self.logger.info("Installing SuperClaude knowledge base...")
 
         return super()._install(config)
 
@@ -68,7 +76,7 @@ class FrameworkDocsComponent(Component):
 
             # Add component registration to metadata (with file list for sync)
             self.settings_manager.add_component_registration(
-                "framework_docs",
+                "knowledge_base",
                 {
                     "version": __version__,
                     "category": "documentation",
@@ -77,7 +85,7 @@ class FrameworkDocsComponent(Component):
                 },
             )
 
-            self.logger.info("Updated metadata with framework docs component registration")
+            self.logger.info("Updated metadata with knowledge base component registration")
 
             # Migrate any existing SuperClaude data from settings.json
             if self.settings_manager.migrate_superclaude_data():
@@ -109,9 +117,9 @@ class FrameworkDocsComponent(Component):
         return True
 
     def uninstall(self) -> bool:
-        """Uninstall framework docs component"""
+        """Uninstall knowledge base component"""
         try:
-            self.logger.info("Uninstalling SuperClaude framework docs component...")
+            self.logger.info("Uninstalling SuperClaude knowledge base component...")
 
             # Remove framework files
             removed_count = 0
@@ -123,7 +131,7 @@ class FrameworkDocsComponent(Component):
                 else:
                     self.logger.warning(f"Could not remove {filename}")
 
-            # Update metadata to remove framework docs component
+            # Update metadata to remove knowledge base component
             try:
                 if self.settings_manager.is_component_installed("framework_docs"):
                     self.settings_manager.remove_component_registration("framework_docs")
@@ -134,7 +142,7 @@ class FrameworkDocsComponent(Component):
                             del metadata[key]
 
                     self.settings_manager.save_metadata(metadata)
-                    self.logger.info("Removed framework docs component from metadata")
+                    self.logger.info("Removed knowledge base component from metadata")
             except Exception as e:
                 self.logger.warning(f"Could not update metadata: {e}")
 
@@ -144,20 +152,20 @@ class FrameworkDocsComponent(Component):
             return True
 
         except Exception as e:
-            self.logger.exception(f"Unexpected error during framework docs uninstallation: {e}")
+            self.logger.exception(f"Unexpected error during knowledge base uninstallation: {e}")
             return False
 
     def get_dependencies(self) -> List[str]:
-        """Get component dependencies (framework docs has none)"""
+        """Get component dependencies (knowledge base has none)"""
         return []
 
     def update(self, config: Dict[str, Any]) -> bool:
         """
-        Sync framework docs component (overwrite + delete obsolete files).
+        Sync knowledge base component (overwrite + delete obsolete files).
         No backup needed - SuperClaude source files are always authoritative.
         """
         try:
-            self.logger.info("Syncing SuperClaude framework docs component...")
+            self.logger.info("Syncing SuperClaude knowledge base component...")
 
             # Get previously installed files from metadata
             metadata = self.settings_manager.load_metadata()
@@ -209,11 +217,11 @@ class FrameworkDocsComponent(Component):
             return success
 
         except Exception as e:
-            self.logger.exception(f"Unexpected error during framework docs sync: {e}")
+            self.logger.exception(f"Unexpected error during knowledge base sync: {e}")
             return False
 
     def validate_installation(self) -> Tuple[bool, List[str]]:
-        """Validate framework docs component installation"""
+        """Validate knowledge base component installation"""
         errors = []
 
         # Check if all framework files exist

setup/components/mcp_integration.py

@@ -1,4 +1,4 @@
-"""
+"""\nMCP Integration Component\n\nResponsibility: Integrates Model Context Protocol for external tool access.\nManages connections to specialized MCP servers and capabilities.\n"""\n\n"""
 MCP component for MCP server integration
 """
 
@@ -15,7 +15,7 @@ from setup import __version__
 from ..core.base import Component
 
 
-class MCPComponent(Component):
+class MCPIntegrationComponent(Component):
     """MCP servers integration component"""
 
     def __init__(self, install_dir: Optional[Path] = None):

setup/components/slash_commands.py

@@ -1,4 +1,4 @@
-"""
+"""\nSlash Commands Component\n\nResponsibility: Registers and manages slash commands for CLI interactions.\nProvides custom command definitions and execution logic.\n"""\n\n"""
 Commands component for SuperClaude slash command definitions
 """
 
@@ -9,7 +9,7 @@ from ..core.base import Component
 from setup import __version__
 
 
-class CommandsComponent(Component):
+class SlashCommandsComponent(Component):
     """SuperClaude slash commands component"""
 
     def __init__(self, install_dir: Optional[Path] = None):

setup/core/installer.py

@@ -149,7 +149,7 @@ class Installer:
 
         # Framework components are ALWAYS updated to latest version
         # These are SuperClaude implementation files, not user configurations
-        framework_components = {'framework_docs', 'agents', 'commands', 'modes', 'core', 'mcp'}
+        framework_components = {'knowledge_base', 'agents', 'commands', 'modes', 'core', 'mcp'}
 
         if component_name in framework_components:
             # Always update framework components to latest version