External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-17 17:56:46 +00:00
Code Issues Packages Projects Releases Wiki Activity
SuperClaude/docs/Developer-Guide
History
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
..
contributing-code.md
refactor: PEP8 compliance - directory rename and code formatting (#425)
2025-10-14 08:47:09 +05:30
documentation-index.md
refactor: PEP8 compliance - directory rename and code formatting (#425)
2025-10-14 08:47:09 +05:30
README.md
refactor: PEP8 compliance - directory rename and code formatting (#425)
2025-10-14 08:47:09 +05:30
technical-architecture.md
refactor: PEP8 compliance - directory rename and code formatting (#425)
2025-10-14 08:47:09 +05:30
testing-debugging.md
refactor: PEP8 compliance - directory rename and code formatting (#425)
2025-10-14 08:47:09 +05:30

README.md

SuperClaude Framework Developer Guide

A documentation suite for understanding and extending the SuperClaude Context-Oriented Configuration Framework.

Documentation Overview

This Developer Guide provides documentation for understanding SuperClaude's context architecture and how to extend it:

Contributing Code Guide

Purpose: Guidelines for contributing context files and framework improvements
Audience: Contributors and framework maintainers
Key Topics: Adding context files, naming conventions, documentation standards

Context Architecture Guide

Purpose: Understanding how context files work and are structured
Audience: Anyone wanting to understand or extend SuperClaude
Key Topics: Context file structure, import system, agent/command patterns

Verification & Troubleshooting Guide

Purpose: Verifying installation and troubleshooting context file issues
Audience: Users and maintainers
Key Topics: File verification, common issues, diagnostic commands

Documentation Index

Purpose: Comprehensive navigation guide and topic-based organization
Audience: All users seeking efficient information discovery
Key Features: Skill level pathways, cross-references, quality validation, usage guidelines

Quick Navigation

For New Contributors

  1. Start with Contributing Code Guide for environment setup
  2. Review Technical Architecture Guide for system understanding
  3. Use Testing & Debugging Guide for testing basics

For System Architects

  1. Begin with Technical Architecture Guide for complete system design
  2. Reference Contributing Code Guide for component patterns
  3. Review Testing & Debugging Guide for validation frameworks

For Testing Engineers

  1. Start with Testing & Debugging Guide for comprehensive testing procedures
  2. Reference Contributing Code Guide for development integration
  3. Use Technical Architecture Guide for architecture context

Key Framework Concepts

Context-Oriented Configuration

SuperClaude is a collection of .md instruction files that Claude Code reads to modify its behavior. It is NOT executing software.

IMPORTANT: SuperClaude is NOT a CLI tool or executable software. When you see /sc: commands in documentation, these are context trigger patterns you type in Claude Code conversations, not terminal commands.

Agent Context Files

Specialized instruction sets that provide domain expertise when activated by @agent-[name] or automatically by keywords.

Command Context Files

Workflow patterns triggered by /sc:[command] context patterns (not CLI commands) that guide Claude Code through structured development tasks when you type them in Claude Code conversations.

MCP Integration

External tools (actual software) that can be configured to provide additional capabilities like documentation lookup or code analysis.

What SuperClaude Is NOT

  • ❌ Not Software: No code executes, no processes run
  • ❌ Not Testable: Context files are instructions, not functions
  • ❌ Not Optimizable: No performance to measure or improve
  • ❌ Not Persistent: Each Claude conversation is independent

Documentation Features

Cross-Referenced Integration

All three documents are strategically cross-referenced, enabling seamless navigation between development workflows, architectural understanding, and testing procedures.

Accessibility & Inclusivity

  • Screen Reader Support: Full navigation guidance and diagram descriptions
  • Skill Level Pathways: Clear progression from beginner to advanced
  • Comprehensive Glossaries: 240+ technical terms with detailed definitions
  • Learning Resources: Time estimates and prerequisite guidance

Consistent Terminology

Unified technical vocabulary ensures clear communication across all documentation, with key terms defined consistently throughout comprehensive glossaries.

Comprehensive Code Examples

All code examples include proper documentation, error handling, and follow consistent formatting standards suitable for production use.

Security-First Approach

Security considerations are embedded throughout all documentation, from development practices to testing procedures to architectural design.

Professional Quality Standards

  • WCAG 2.1 Compliant: Full accessibility standards compliance
  • Technical Accuracy: All examples tested and verified
  • Framework Integration: Documentation quality matches framework sophistication
  • Community Focus: Inclusive design for developers of all abilities

Document Status

✅ Phase 1 Complete: Critical issues resolved, basic structure established
✅ Phase 2 Complete: Cross-document consistency, navigation improvements, security integration
✅ Phase 3 Complete: Advanced examples, visual diagrams, enhanced architecture documentation
✅ Phase 4 Complete: Accessibility improvements, comprehensive glossaries, skill level guidance, professional polish

Accessibility & Quality Enhancements (Phase 4)

  • 240+ Glossary Terms: Comprehensive technical definitions across all documents
  • Screen Reader Support: Full accessibility with navigation guidance and diagram descriptions
  • Skill Level Pathways: Clear learning progressions from beginner to advanced
  • Professional Polish: Documentation quality aligned with framework sophistication

Getting Started

Prerequisites

  • Python 3.8+ (for installation tool)
  • Claude Code installed
  • Optional: Node.js 16+ for MCP servers

Understanding the Framework

# Check installation
ls ~/.claude/
# You'll see context files, not executable code

# View a command context
cat ~/.claude/commands/implement.md
# You'll see instructions for Claude, not code

# View an agent context  
cat ~/.claude/agents/python-expert.md
# You'll see expertise definitions, not programs

Extending SuperClaude

  1. Add Commands: Create new .md files in ~/.claude/commands/
  2. Add Agents: Create new .md files in ~/.claude/agents/
  3. Add Modes: Create new .md files in ~/.claude/modes/

No compilation, no testing, no deployment - just add context files and Claude Code will read them automatically.

Support and Resources

Documentation Issues

  • Broken Links: Report cross-reference issues in GitHub issues
  • Unclear Content: Request clarification through GitHub discussions
  • Missing Information: Suggest improvements through pull requests

Development Support

  • Technical Questions: Use GitHub discussions for architecture and implementation questions
  • Bug Reports: Submit detailed issues with reproduction steps
  • Feature Requests: Propose enhancements through GitHub issues

Community Resources

Contributing to Documentation

We welcome contributions to improve documentation quality, accuracy, and completeness:

Documentation Standards

  • Clarity: Write for your target audience skill level
  • Consistency: Follow established terminology and formatting
  • Completeness: Provide working examples and complete procedures
  • Cross-References: Link related concepts across documents

Submission Process

  1. Fork the repository and create a feature branch
  2. Make documentation improvements following our standards
  3. Test all code examples and verify cross-references
  4. Submit pull request with clear description of changes

SuperClaude Framework: Building the future of AI-assisted development through intelligent orchestration and behavioral programming.

For the latest updates and community discussions, visit our GitHub repository.