mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-17 17:56:46 +00:00
050d5ea2ab
* fix(orchestration): add WebFetch auto-trigger for infrastructure configuration Problem: Infrastructure configuration changes (e.g., Traefik port settings) were being made based on assumptions without consulting official documentation, violating the 'Evidence > assumptions' principle in PRINCIPLES.md. Solution: - Added Infrastructure Configuration Validation section to MODE_Orchestration.md - Auto-triggers WebFetch for infrastructure tools (Traefik, nginx, Docker, etc.) - Enforces MODE_DeepResearch activation for investigation - BLOCKS assumption-based configuration changes Testing: Verified WebFetch successfully retrieves Traefik official docs (port 80 default) This prevents production outages from infrastructure misconfiguration by ensuring all technical recommendations are backed by official documentation. * feat: Add PM Agent (Project Manager Agent) for seamless orchestration Introduces PM Agent as the default orchestration layer that coordinates all sub-agents and manages workflows automatically. Key Features: - Default orchestration: All user interactions handled by PM Agent - Auto-delegation: Intelligent sub-agent selection based on task analysis - Docker Gateway integration: Zero-token baseline with dynamic MCP loading - Self-improvement loop: Automatic documentation of patterns and mistakes - Optional override: Users can specify sub-agents explicitly if desired Architecture: - Agent spec: SuperClaude/Agents/pm-agent.md - Command: SuperClaude/Commands/pm.md - Updated docs: README.md (15→16 agents), agents.md (new Orchestration category) User Experience: - Default: PM Agent handles everything (seamless, no manual routing) - Optional: Explicit --agent flag for direct sub-agent access - Both modes available simultaneously (no user downside) Implementation Status: - ✅ Specification complete - ✅ Documentation complete - ⏳ Prototype implementation needed - ⏳ Docker Gateway integration needed - ⏳ Testing and validation needed Refs: kazukinakai/docker-mcp-gateway (IRIS MCP Gateway integration) * feat: Add Agent Orchestration rules for PM Agent default activation Implements PM Agent as the default orchestration layer in RULES.md. Key Changes: - New 'Agent Orchestration' section (CRITICAL priority) - PM Agent receives ALL user requests by default - Manual override with @agent-[name] bypasses PM Agent - Agent Selection Priority clearly defined: 1. Manual override → Direct routing 2. Default → PM Agent → Auto-delegation 3. Delegation based on keywords, file types, complexity, context User Experience: - Default: PM Agent handles everything (seamless) - Override: @agent-[name] for direct specialist access - Transparent: PM Agent reports delegation decisions This establishes PM Agent as the orchestration layer while respecting existing auto-activation patterns and manual overrides. Next Steps: - Local testing in agiletec project - Iteration based on actual behavior - Documentation updates as needed * refactor(pm-agent): redesign as self-improvement meta-layer Problem Resolution: PM Agent's initial design competed with existing auto-activation for task routing, creating confusion about orchestration responsibilities and adding unnecessary complexity. Design Change: Redefined PM Agent as a meta-layer agent that operates AFTER specialist agents complete tasks, focusing on: - Post-implementation documentation and pattern recording - Immediate mistake analysis with prevention checklists - Monthly documentation maintenance and noise reduction - Pattern extraction and knowledge synthesis Two-Layer Orchestration System: 1. Task Execution Layer: Existing auto-activation handles task routing (unchanged) 2. Self-Improvement Layer: PM Agent meta-layer handles documentation (new) Files Modified: - SuperClaude/Agents/pm-agent.md: Complete rewrite with meta-layer design - Category: orchestration → meta - Triggers: All user interactions → Post-implementation, mistakes, monthly - Behavioral Mindset: Continuous learning system - Self-Improvement Workflow: BEFORE/DURING/AFTER/MISTAKE RECOVERY/MAINTENANCE - SuperClaude/Core/RULES.md: Agent Orchestration section updated - Split into Task Execution Layer + Self-Improvement Layer - Added orchestration flow diagram - Clarified PM Agent activates AFTER task completion - README.md: Updated PM Agent description - "orchestrates all interactions" → "ensures continuous learning" - Docs/User-Guide/agents.md: PM Agent section rewritten - Section: Orchestration Agent → Meta-Layer Agent - Expertise: Project orchestration → Self-improvement workflow executor - Examples: Task coordination → Post-implementation documentation - PR_DOCUMENTATION.md: Comprehensive PR documentation added - Summary, motivation, changes, testing, breaking changes - Two-layer orchestration system diagram - Verification checklist Integration Validated: Tested with agiletec project's self-improvement-workflow.md: ✅ PM Agent aligns with existing BEFORE/DURING/AFTER/MISTAKE RECOVERY phases ✅ Complements (not competes with) existing workflow ✅ agiletec workflow defines WHAT, PM Agent defines WHO executes it Breaking Changes: None - Existing auto-activation continues unchanged - Specialist agents unaffected - User workflows remain the same - New capability: Automatic documentation and knowledge maintenance Value Proposition: Transforms SuperClaude into a continuously learning system that accumulates knowledge, prevents recurring mistakes, and maintains fresh documentation without manual intervention. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add Claude Code conversation history management research Research covering .jsonl file structure, performance impact, and retention policies. Content: - Claude Code .jsonl file format and message types - Performance issues from GitHub (memory leaks, conversation compaction) - Retention policies (consumer vs enterprise) - Rotation recommendations based on actual data - File history snapshot tracking mechanics Source: Moved from agiletec project (research applicable to all Claude Code projects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add Development documentation structure Phase 1: Documentation Structure complete - Add Docs/Development/ directory for development documentation - Add ARCHITECTURE.md - System architecture with PM Agent meta-layer - Add ROADMAP.md - 5-phase development plan with checkboxes - Add TASKS.md - Daily task tracking with progress indicators - Add PROJECT_STATUS.md - Current status dashboard and metrics - Add pm-agent-integration.md - Implementation guide for PM Agent mode This establishes comprehensive documentation foundation for: - System architecture understanding - Development planning and tracking - Implementation guidance - Progress visibility Related: #pm-agent-mode #documentation #phase-1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: PM Agent session lifecycle and PDCA implementation Phase 2: PM Agent Mode Integration (Design Phase) Commands/pm.md updates: - Add "Always-Active Foundation Layer" concept - Add Session Lifecycle (Session Start/During Work/Session End) - Add PDCA Cycle (Plan/Do/Check/Act) automation - Add Serena MCP Memory Integration (list/read/write_memory) - Document auto-activation triggers Agents/pm-agent.md updates: - Add Session Start Protocol (MANDATORY auto-activation) - Add During Work PDCA Cycle with example workflows - Add Session End Protocol with state preservation - Add PDCA Self-Evaluation Pattern - Add Documentation Strategy (temp → patterns/mistakes) - Add Memory Operations Reference Key Features: - Session start auto-activation for context restoration - 30-minute checkpoint saves during work - Self-evaluation with think_about_* operations - Systematic documentation lifecycle - Knowledge evolution to CLAUDE.md Implementation Status: - ✅ Design complete (Commands/pm.md, Agents/pm-agent.md) - ⏳ Implementation pending (Core components) - ⏳ Serena MCP integration pending Salvaged from mistaken development in ~/.claude directory Related: #pm-agent-mode #session-lifecycle #pdca-cycle #phase-2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: disable Serena MCP auto-browser launch Disable web dashboard and GUI log window auto-launch in Serena MCP server to prevent intrusive browser popups on startup. Users can still manually access the dashboard at http://localhost:24282/dashboard/ if needed. Changes: - Add CLI flags to Serena run command: - --enable-web-dashboard false - --enable-gui-log-window false - Ensures Git-tracked configuration (no reliance on ~/.serena/serena_config.yml) - Aligns with AIRIS MCP Gateway integration approach 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename directories to lowercase for PEP8 compliance - Rename superclaude/Agents -> superclaude/agents - Rename superclaude/Commands -> superclaude/commands - Rename superclaude/Core -> superclaude/core - Rename superclaude/Examples -> superclaude/examples - Rename superclaude/MCP -> superclaude/mcp - Rename superclaude/Modes -> superclaude/modes This change follows Python PEP8 naming conventions for package directories. * style: fix PEP8 violations and update package name to lowercase Changes: - Format all Python files with black (43 files reformatted) - Update package name from 'SuperClaude' to 'superclaude' in pyproject.toml - Fix import statements to use lowercase package name - Add missing imports (timedelta, __version__) - Remove old SuperClaude.egg-info directory PEP8 violations reduced from 2672 to 701 (mostly E501 line length due to black's 88 char vs flake8's 79 char limit). * docs: add PM Agent development documentation Add comprehensive PM Agent development documentation: - PM Agent ideal workflow (7-phase autonomous cycle) - Project structure understanding (Git vs installed environment) - Installation flow understanding (CommandsComponent behavior) - Task management system (current-tasks.md) Purpose: Eliminate repeated explanations and enable autonomous PDCA cycles 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(pm-agent): add self-correcting execution and warning investigation culture ## Changes ### superclaude/commands/pm.md - Add "Self-Correcting Execution" section with root cause analysis protocol - Add "Warning/Error Investigation Culture" section enforcing zero-tolerance for dismissal - Define error detection protocol: STOP → Investigate → Hypothesis → Different Solution → Execute - Document anti-patterns (retry without understanding) and correct patterns (research-first) ### docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md - Add PDCA workflow hypothesis document for PM Agent autonomous enhancement ## Rationale PM Agent must never retry failed operations without understanding root causes. All warnings and errors require investigation via context7/WebFetch/documentation to ensure production-quality code and prevent technical debt accumulation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(installer): add airis-mcp-gateway MCP server option ## Changes - Add airis-mcp-gateway to MCP server options in installer - Configuration: GitHub-based installation via uvx - Repository: https://github.com/oraios/airis-mcp-gateway - Purpose: Dynamic MCP Gateway for zero-token baseline and on-demand tool loading ## Implementation Added to setup/components/mcp.py self.mcp_servers dictionary with: - install_method: github - install_command: uvx test installation - run_command: uvx runtime execution - required: False (optional server) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local> Co-authored-by: Claude <noreply@anthropic.com>
12 KiB
12 KiB
SuperClaude Framework Developer-Guide Index
Document Navigation Guide
This index provides comprehensive access to all SuperClaude Framework development documentation, organized by topic and skill level for efficient information discovery.
Quick Navigation
For New Contributors: Start with Contributing Guide → Setup
For System Understanding: Begin with Technical Architecture Guide → Context Architecture
For Verification: Start with Verification Guide → Installation Check
Primary Documentation
📋 Contributing Context Files Guide
Purpose: Complete context file development and contribution guidelines
Target Audience: Framework contributors and context file developers
Length: ~1,000 lines focused on context file reality
Key Sections:
- Development Setup - Environment configuration and prerequisites
- Context File Guidelines - Standards and structure
- Development Workflow - Git workflow and submission process
- Contributing to Components - Agent, command, and mode development
- File Validation - Context file verification methods
🏗️ Context Architecture Guide
Purpose: Understanding how context files work and are structured
Target Audience: Anyone wanting to understand or extend SuperClaude
Length: ~800 lines focused on context file patterns and Claude Code integration
Key Sections:
- Context File Architecture - Directory structure and file types
- The Import System - How Claude Code loads context
- Agent Context Structure - Domain specialist contexts
- Command Context Structure - Workflow patterns
- How Claude Code Reads Context - Processing sequence
- Extending the Framework - Adding new components
🧪 Verification & Troubleshooting Guide
Purpose: Verifying installation and troubleshooting context file issues
Target Audience: Users and maintainers
Length: ~500 lines focused on file verification and Claude Code integration
Key Sections:
- Installation Verification - Check context file installation
- Context File Verification - File structure validation
- MCP Server Verification - External tool configuration
- Common Issues - Troubleshooting activation problems
- Troubleshooting Commands - Diagnostic procedures
Topic-Based Index
🚀 Getting Started
Complete Beginners:
- Contributing Guide → Setup - Environment setup
- Architecture Guide → Overview - Understanding context files
- Verification Guide → Installation Check - Basic verification
Environment Setup:
- Development Setup - Prerequisites and configuration
- Installation Verification - File installation check
🏗️ Architecture & Design
Context File Architecture:
- Context File Architecture - Complete system design
- The Import System - How Claude Code loads context
- Agent Context Structure - Domain specialist patterns
- Command Context Structure - Workflow definitions
Component Development:
- Contributing to Components - Agent, command, mode development
- Adding New Agents - Domain specialist creation
- Adding New Commands - Workflow pattern development
- Extending the Framework - Framework expansion
🧪 Verification & Quality
File Verification:
- Context File Verification - File structure validation
- File Validation - Context file verification methods
Troubleshooting:
- Common Issues - Activation and configuration problems
- Troubleshooting Commands - Diagnostic procedures
🔧 Development Workflows
Context File Development:
- Development Workflow - Git workflow
- Context File Guidelines - Standards and practices
- Pull Request Process - Submission process
Component Development:
- Agent Development - Domain specialist creation
- Command Development - Workflow pattern creation
- Mode Development - Behavioral modification patterns
🛠️ MCP Integration
MCP Configuration:
- MCP Server Configuration - External tool setup
- MCP Server Verification - Configuration validation
🚨 Support & Troubleshooting
Common Issues:
- Commands Not Working - Context trigger problems
- Agents Not Activating - Activation issues
- Context Not Loading - Loading problems
Support Resources:
- Getting Help - Support channels
- Issue Reporting - Bug reports and features
Skill Level Pathways
🟢 Beginner Path (Understanding SuperClaude)
Week 1: Foundation
- Architecture Overview - What SuperClaude is
- Installation Verification - Check your setup
- Context File Architecture - Directory structure
Week 2: Basic Usage
- How Claude Code Reads Context - Processing sequence
- Common Issues - Troubleshooting basics
- Context File Guidelines - File standards
🟡 Intermediate Path (Contributing Context Files)
Month 1: Context Development
- Development Setup - Environment preparation
- Agent Context Structure - Domain specialists
- Command Context Structure - Workflow patterns
Month 2: Component Creation
- Adding New Agents - Domain specialist development
- Adding New Commands - Workflow creation
- File Validation - Context verification
🔴 Advanced Path (Framework Extension)
Advanced Understanding
- The Import System - Context loading mechanics
- Extending the Framework - Framework expansion
- MCP Server Configuration - External tool integration
Reference Materials
📚 Key Concepts
Framework Fundamentals:
- Context-Oriented Configuration Framework
- Agent Domain Specialists
- Command Workflow Patterns
- Mode Behavioral Modifications
- MCP Integration Patterns
🔗 Cross-References
Development → Architecture:
Development → Verification:
Architecture → Verification:
Quality Standards
✅ Documentation Accuracy
- Technical Precision: All examples reflect SuperClaude reality (context files, not software)
- Command Accuracy: Correct Python module execution paths and Claude Code context triggers
- No Fiction: Removed all references to non-existent testing frameworks and performance systems
✅ Content Focus
- Context Files: Documentation centers on .md instruction files and Claude Code behavior
- File Verification: Practical approaches to validating context file installation and structure
- Real Workflows: Actual development processes for context file contribution
✅ User Experience
- Clear Progression: Skill-based learning paths from understanding to contribution
- Practical Examples: Working context file examples and Claude Code integration
- Support Integration: Clear guidance to help resources for real issues
Usage Guidelines
For Contributors
- Start with: Development Setup
- Context Development: Follow Context File Guidelines
- Validation: Use File Validation
- Support: Reference Getting Help
For Architects
- System Understanding: Context File Architecture
- Component Patterns: Agent and Command Structure
- Extension: Extending the Framework
- Integration: MCP Configuration
For Verification
- Installation Check: Installation Verification
- File Validation: Context File Verification
- Troubleshooting: Common Issues
- Diagnostics: Troubleshooting Commands
This comprehensive index reflects the reality of SuperClaude as a context-oriented configuration framework, focusing on practical context file development and Claude Code integration.