mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 17:56:46 +00:00

refactor: PEP8 compliance - directory rename and code formatting (#425 )

* 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>

2025-10-14 08:47:09 +05:30

SuperClaude Examples Cookbook

Status: ✅ Status: Current - Comprehensive collection of practical SuperClaude usage examples organized by complexity and domain.

Focused Recipe Collections: The SuperClaude Examples Cookbook has been restructured into three focused collections for better usability and progressive learning.

Recipe Collections Overview

Basic Examples Collection

Essential commands and single-agent workflows

Copy-paste ready commands for immediate use
Essential SuperClaude patterns and fundamentals
Common development tasks and troubleshooting
Perfect starting point for new users

Best for: New users, quick task execution, learning fundamentals

Advanced Workflows Collection

Multi-agent coordination and complex orchestration

Multi-agent collaboration patterns
Enterprise-scale project workflows
Session management and persistence
Complex system development patterns

Best for: Experienced users, enterprise projects, complex coordination

Integration Patterns Collection

Framework integration and cross-tool coordination

Framework-specific integration patterns
Performance optimization recipes
Cross-tool coordination strategies
Monitoring and observability patterns

Best for: Expert users, system architects, performance optimization

By Experience Level

Beginner → Start with Basic Examples

Essential commands and patterns
Simple troubleshooting workflows
Copy-paste solutions for common tasks

Intermediate → Progress to Advanced Workflows

Multi-agent coordination
Complex project orchestration
Session management patterns

Expert → Master Integration Patterns

Framework integration strategies
Performance optimization recipes
Enterprise-scale architecture patterns

By Use Case

Web Development

Frontend: Basic Examples → Integration Patterns
Backend: Basic Examples → Integration Patterns
Full-Stack: Advanced Workflows

Mobile Development

React Native: Basic Examples → Integration Patterns
Cross-Platform: Integration Patterns

DevOps & Infrastructure

CI/CD: Basic Examples → Integration Patterns
Monitoring: Advanced Workflows → Integration Patterns

Performance & Security

Security: Basic Examples → Advanced Workflows
Performance: Integration Patterns

Verified Commands Reference

Core Commands:

/sc:brainstorm - Interactive requirements discovery
/sc:analyze - Codebase analysis and assessment
/sc:implement - Feature implementation with best practices
/sc:troubleshoot - Systematic problem diagnosis
/sc:test - Comprehensive testing and validation
/sc:spawn - Complex multi-agent coordination
/sc:load / /sc:save - Session management
/sc:reflect - Context analysis and optimization

Verified Flags:

--think, --think-hard, --ultrathink - Analysis depth control
--uc - Ultra-compressed token-efficient mode
--orchestrate - Intelligent coordination mode
--c7, --serena, --all-mcp - MCP server integration
--focus [domain] - Domain-specific optimization
--scope [level] - Analysis scope control

Learning Progression Roadmap

Phase 1: Foundation (Week 1-2)

Setup: Complete Installation Guide
Basics: Practice Basic Examples
Patterns: Learn Basic Usage Patterns
Success: Can execute common development tasks independently

Phase 2: Coordination (Week 3-6)

Agents: Understand Multi-Agent Patterns
Workflows: Practice Complex Project Workflows
Orchestration: Master Advanced Orchestration
Success: Can coordinate complex multi-step projects

Phase 3: Integration (Month 2+)

Frameworks: Learn Framework Integration
Performance: Master Optimization Recipes
Troubleshooting: Advanced Debugging Workflows
Success: Can integrate SuperClaude with any development stack

Phase 4: Expertise (Month 3+)

Architecture: Design custom integration patterns
Contribution: Contribute to SuperClaude framework
Leadership: Mentor community and solve complex problems
Success: Framework development and community leadership

Quick Reference Matrix

Task Type	Beginner	Intermediate	Expert
Analysis	Basic Analysis	Multi-Agent Analysis	Integration Analysis
Implementation	Simple Features	Complex Projects	Framework Integration
Testing	Basic Testing	Comprehensive Testing	Testing Integration
Troubleshooting	Common Issues	System Debugging	Distributed Debugging
Performance	Basic Optimization	System Optimization	Expert Optimization

Success Milestones

✅ Basic Proficiency

Can install and configure SuperClaude
Comfortable with 5-10 core commands
Can complete simple workflows independently
Understands basic flag usage

✅ Intermediate Mastery

Masters multi-agent coordination
Can orchestrate complex workflows
Understands session management
Comfortable with advanced flag combinations

✅ Expert Integration

Can integrate any development framework
Masters performance optimization
Develops custom integration patterns
Contributes to framework development

Support Resources

Documentation:

Commands Reference - Complete command documentation
Agents Guide - Multi-agent coordination
MCP Servers - Enhanced capabilities
Advanced Workflows - Complex coordination patterns

Community:

GitHub Discussions - Community support
GitHub Issues - Bug reports and features
Contributing Guide - Framework contribution

Advanced:

Technical Architecture - Deep system understanding
Troubleshooting Guide - Common issues and solutions

Your Journey: Start with Basic Examples, progress through Advanced Workflows, and master Integration Patterns. SuperClaude grows with you from simple commands to sophisticated development orchestration.

Remember: Every expert was once a beginner. Focus on practical application, experiment with different approaches, and leverage the community for support and learning.

8.8 KiB

Raw Blame History

SuperClaude Examples Cookbook

Recipe Collections Overview

Basic Examples Collection

Advanced Workflows Collection

Integration Patterns Collection

Quick Navigation Guide

By Experience Level

By Use Case

Verified Commands Reference

Learning Progression Roadmap

Phase 1: Foundation (Week 1-2)

Phase 2: Coordination (Week 3-6)

Phase 3: Integration (Month 2+)

Phase 4: Expertise (Month 3+)

Quick Reference Matrix

Success Milestones

✅ Basic Proficiency

✅ Intermediate Mastery

✅ Expert Integration

Support Resources

8.8 KiB Raw Blame History

SuperClaude Examples Cookbook

Recipe Collections Overview

Basic Examples Collection

Advanced Workflows Collection

Integration Patterns Collection

Quick Navigation Guide

By Experience Level

By Use Case

Verified Commands Reference

Learning Progression Roadmap

Phase 1: Foundation (Week 1-2)

Phase 2: Coordination (Week 3-6)

Phase 3: Integration (Month 2+)

Phase 4: Expertise (Month 3+)

Quick Reference Matrix

Success Milestones

✅ Basic Proficiency

✅ Intermediate Mastery

✅ Expert Integration

Support Resources

8.8 KiB

Raw Blame History