kazuki nakai 050d5ea2ab
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

8.0 KiB

name description category complexity mcp-servers personas
help List all available /sc commands and their functionality utility low

/sc:help - Command Reference Documentation

Triggers

  • Command discovery and reference lookup requests
  • Framework exploration and capability understanding needs
  • Documentation requests for available SuperClaude commands

Behavioral Flow

  1. Display: Present complete command list with descriptions
  2. Complete: End interaction after displaying information

Key behaviors:

  • Information display only - no execution or implementation
  • Reference documentation mode without action triggers

Here is a complete list of all available SuperClaude (/sc) commands.

Command Description
/sc:analyze Comprehensive code analysis across quality, security, performance, and architecture domains
/sc:brainstorm Interactive requirements discovery through Socratic dialogue and systematic exploration
/sc:build Build, compile, and package projects with intelligent error handling and optimization
/sc:business-panel Multi-expert business analysis with adaptive interaction modes
/sc:cleanup Systematically clean up code, remove dead code, and optimize project structure
/sc:design Design system architecture, APIs, and component interfaces with comprehensive specifications
/sc:document Generate focused documentation for components, functions, APIs, and features
/sc:estimate Provide development estimates for tasks, features, or projects with intelligent analysis
/sc:explain Provide clear explanations of code, concepts, and system behavior with educational clarity
/sc:git Git operations with intelligent commit messages and workflow optimization
/sc:help List all available /sc commands and their functionality
/sc:implement Feature and code implementation with intelligent persona activation and MCP integration
/sc:improve Apply systematic improvements to code quality, performance, and maintainability
/sc:index Generate comprehensive project documentation and knowledge base with intelligent organization
/sc:load Session lifecycle management with Serena MCP integration for project context loading
/sc:reflect Task reflection and validation using Serena MCP analysis capabilities
/sc:save Session lifecycle management with Serena MCP integration for session context persistence
/sc:select-tool Intelligent MCP tool selection based on complexity scoring and operation analysis
/sc:spawn Meta-system task orchestration with intelligent breakdown and delegation
/sc:spec-panel Multi-expert specification review and improvement using renowned specification and software engineering experts
/sc:task Execute complex tasks with intelligent workflow management and delegation
/sc:test Execute tests with coverage analysis and automated quality reporting
/sc:troubleshoot Diagnose and resolve issues in code, builds, deployments, and system behavior
/sc:workflow Generate structured implementation workflows from PRDs and feature requirements

SuperClaude Framework Flags

SuperClaude supports behavioral flags to enable specific execution modes and tool selection patterns. Use these flags with any /sc command to customize behavior.

Mode Activation Flags

Flag Trigger Behavior
--brainstorm Vague project requests, exploration keywords Activate collaborative discovery mindset, ask probing questions
--introspect Self-analysis requests, error recovery Expose thinking process with transparency markers
--task-manage Multi-step operations (>3 steps) Orchestrate through delegation, systematic organization
--orchestrate Multi-tool operations, parallel execution Optimize tool selection matrix, enable parallel thinking
--token-efficient Context usage >75%, large-scale operations Symbol-enhanced communication, 30-50% token reduction

MCP Server Flags

Flag Trigger Behavior
--c7 / --context7 Library imports, framework questions Enable Context7 for curated documentation lookup
--seq / --sequential Complex debugging, system design Enable Sequential for structured multi-step reasoning
--magic UI component requests (/ui, /21) Enable Magic for modern UI generation from 21st.dev
--morph / --morphllm Bulk code transformations Enable Morphllm for efficient multi-file pattern application
--serena Symbol operations, project memory Enable Serena for semantic understanding and session persistence
--play / --playwright Browser testing, E2E scenarios Enable Playwright for real browser automation and testing
--all-mcp Maximum complexity scenarios Enable all MCP servers for comprehensive capability
--no-mcp Native-only execution needs Disable all MCP servers, use native tools

Analysis Depth Flags

Flag Trigger Behavior
--think Multi-component analysis needs Standard structured analysis (~4K tokens), enables Sequential
--think-hard Architectural analysis, system-wide dependencies Deep analysis (~10K tokens), enables Sequential + Context7
--ultrathink Critical system redesign, legacy modernization Maximum depth analysis (~32K tokens), enables all MCP servers

Execution Control Flags

Flag Trigger Behavior
--delegate [auto|files|folders] >7 directories OR >50 files Enable sub-agent parallel processing with intelligent routing
--concurrency [n] Resource optimization needs Control max concurrent operations (range: 1-15)
--loop Improvement keywords (polish, refine, enhance) Enable iterative improvement cycles with validation gates
--iterations [n] Specific improvement cycle requirements Set improvement cycle count (range: 1-10)
--validate Risk score >0.7, resource usage >75% Pre-execution risk assessment and validation gates
--safe-mode Resource usage >85%, production environment Maximum validation, conservative execution

Output Optimization Flags

Flag Trigger Behavior
--uc / --ultracompressed Context pressure, efficiency requirements Symbol communication system, 30-50% token reduction
--scope [file|module|project|system] Analysis boundary needs Define operational scope and analysis depth
--focus [performance|security|quality|architecture|accessibility|testing] Domain-specific optimization Target specific analysis domain and expertise application

Flag Priority Rules

  • Safety First: --safe-mode > --validate > optimization flags
  • Explicit Override: User flags > auto-detection
  • Depth Hierarchy: --ultrathink > --think-hard > --think
  • MCP Control: --no-mcp overrides all individual MCP flags
  • Scope Precedence: system > project > module > file

Usage Examples

# Deep analysis with Context7 enabled
/sc:analyze --think-hard --context7 src/

# UI development with Magic and validation
/sc:implement --magic --validate "Add user dashboard"

# Token-efficient task management
/sc:task --token-efficient --delegate auto "Refactor authentication system"

# Safe production deployment
/sc:build --safe-mode --validate --focus security

Boundaries

Will:

  • Display comprehensive list of available SuperClaude commands
  • Provide clear descriptions of each command's functionality
  • Present information in readable tabular format
  • Show all available SuperClaude framework flags and their usage
  • Provide flag usage examples and priority rules

Will Not:

  • Execute any commands or create any files
  • Activate implementation modes or start projects
  • Engage TodoWrite or any execution tools

Note: This list is manually generated and may become outdated. If you suspect it is inaccurate, please consider regenerating it or contacting a maintainer.