External/SuperClaude
1
0
Fork 0
mirror of https://github.com/SuperClaude-Org/SuperClaude_Framework.git synced 2025-12-29 16:16:08 +00:00
Code Issues Packages Projects Releases Wiki Activity
289 Commits 9 Branches 17 Tags
Commit Graph

16 Commits

Author SHA1 Message Date
kazuki nakai
882a0d8356
refactor: PM Agent complete independence from external MCP servers (#439) 
* refactor: PM Agent complete independence from external MCP servers

## Summary
Implement graceful degradation to ensure PM Agent operates fully without
any MCP server dependencies. MCP servers now serve as optional enhancements
rather than required components.

## Changes

### Responsibility Separation (NEW)
- **PM Agent**: Development workflow orchestration (PDCA cycle, task management)
- **mindbase**: Memory management (long-term, freshness, error learning)
- **Built-in memory**: Session-internal context (volatile)

### 3-Layer Memory Architecture with Fallbacks
1. **Built-in Memory** [OPTIONAL]: Session context via MCP memory server
2. **mindbase** [OPTIONAL]: Long-term semantic search via airis-mcp-gateway
3. **Local Files** [ALWAYS]: Core functionality in docs/memory/

### Graceful Degradation Implementation
- All MCP operations marked with [ALWAYS] or [OPTIONAL]
- Explicit IF/ELSE fallback logic for every MCP call
- Dual storage: Always write to local files + optionally to mindbase
- Smart lookup: Semantic search (if available) → Text search (always works)

### Key Fallback Strategies

**Session Start**:
- mindbase available: search_conversations() for semantic context
- mindbase unavailable: Grep docs/memory/*.jsonl for text-based lookup

**Error Detection**:
- mindbase available: Semantic search for similar past errors
- mindbase unavailable: Grep docs/mistakes/ + solutions_learned.jsonl

**Knowledge Capture**:
- Always: echo >> docs/memory/patterns_learned.jsonl (persistent)
- Optional: mindbase.store() for semantic search enhancement

## Benefits
- ✅ Zero external dependencies (100% functionality without MCP)
- ✅ Enhanced capabilities when MCPs available (semantic search, freshness)
- ✅ No functionality loss, only reduced search intelligence
- ✅ Transparent degradation (no error messages, automatic fallback)

## Related Research
- Serena MCP investigation: Exposes tools (not resources), memory = markdown files
- mindbase superiority: PostgreSQL + pgvector > Serena memory features
- Best practices alignment: /Users/kazuki/github/airis-mcp-gateway/docs/mcp-best-practices.md

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

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

* chore: add PR template and pre-commit config

- Add structured PR template with Git workflow checklist
- Add pre-commit hooks for secret detection and Conventional Commits
- Enforce code quality gates (YAML/JSON/Markdown lint, shellcheck)

NOTE: Execute pre-commit inside Docker container to avoid host pollution:
  docker compose exec workspace uv tool install pre-commit
  docker compose exec workspace pre-commit run --all-files

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

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

* docs: update PM Agent context with token efficiency architecture

- Add Layer 0 Bootstrap (150 tokens, 95% reduction)
- Document Intent Classification System (5 complexity levels)
- Add Progressive Loading strategy (5-layer)
- Document mindbase integration incentive (38% savings)
- Update with 2025-10-17 redesign details

* refactor: PM Agent command with progressive loading

- Replace auto-loading with User Request First philosophy
- Add 5-layer progressive context loading
- Implement intent classification system
- Add workflow metrics collection (.jsonl)
- Document graceful degradation strategy

* fix: installer improvements

Update installer logic for better reliability

* docs: add comprehensive development documentation

- Add architecture overview
- Add PM Agent improvements analysis
- Add parallel execution architecture
- Add CLI install improvements
- Add code style guide
- Add project overview
- Add install process analysis

* docs: add research documentation

Add LLM agent token efficiency research and analysis

* docs: add suggested commands reference

* docs: add session logs and testing documentation

- Add session analysis logs
- Add testing documentation

* feat: migrate CLI to typer + rich for modern UX

## What Changed

### New CLI Architecture (typer + rich)
- Created `superclaude/cli/` module with modern typer-based CLI
- Replaced custom UI utilities with rich native features
- Added type-safe command structure with automatic validation

### Commands Implemented
- **install**: Interactive installation with rich UI (progress, panels)
- **doctor**: System diagnostics with rich table output
- **config**: API key management with format validation

### Technical Improvements
- Dependencies: Added typer>=0.9.0, rich>=13.0.0, click>=8.0.0
- Entry Point: Updated pyproject.toml to use `superclaude.cli.app:cli_main`
- Tests: Added comprehensive smoke tests (11 passed)

### User Experience Enhancements
- Rich formatted help messages with panels and tables
- Automatic input validation with retry loops
- Clear error messages with actionable suggestions
- Non-interactive mode support for CI/CD

## Testing

```bash
uv run superclaude --help     # ✓ Works
uv run superclaude doctor     # ✓ Rich table output
uv run superclaude config show # ✓ API key management
pytest tests/test_cli_smoke.py # ✓ 11 passed, 1 skipped
```

## Migration Path

- ✅ P0: Foundation complete (typer + rich + smoke tests)
- 🔜 P1: Pydantic validation models (next sprint)
- 🔜 P2: Enhanced error messages (next sprint)
- 🔜 P3: API key retry loops (next sprint)

## Performance Impact

- **Code Reduction**: Prepared for -300 lines (custom UI → rich)
- **Type Safety**: Automatic validation from type hints
- **Maintainability**: Framework primitives vs custom code

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

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

* refactor: consolidate documentation directories

Merged claudedocs/ into docs/research/ for consistent documentation structure.

Changes:
- Moved all claudedocs/*.md files to docs/research/
- Updated all path references in documentation (EN/KR)
- Updated RULES.md and research.md command templates
- Removed claudedocs/ directory
- Removed ClaudeDocs/ from .gitignore

Benefits:
- Single source of truth for all research reports
- PEP8-compliant lowercase directory naming
- Clearer documentation organization
- Prevents future claudedocs/ directory creation

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

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

* perf: reduce /sc:pm command output from 1652 to 15 lines

- Remove 1637 lines of documentation from command file
- Keep only minimal bootstrap message
- 99% token reduction on command execution
- Detailed specs remain in superclaude/agents/pm-agent.md

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

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

* perf: split PM Agent into execution workflows and guide

- Reduce pm-agent.md from 735 to 429 lines (42% reduction)
- Move philosophy/examples to docs/agents/pm-agent-guide.md
- Execution workflows (PDCA, file ops) stay in pm-agent.md
- Guide (examples, quality standards) read once when needed

Token savings:
- Agent loading: ~6K → ~3.5K tokens (42% reduction)
- Total with pm.md: 71% overall reduction

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

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

* refactor: consolidate PM Agent optimization and pending changes

PM Agent optimization (already committed separately):
- superclaude/commands/pm.md: 1652→14 lines
- superclaude/agents/pm-agent.md: 735→429 lines
- docs/agents/pm-agent-guide.md: new guide file

Other pending changes:
- setup: framework_docs, mcp, logger, remove ui.py
- superclaude: __main__, cli/app, cli/commands/install
- tests: test_ui updates
- scripts: workflow metrics analysis tools
- docs/memory: session state updates

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

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

* refactor: simplify MCP installer to unified gateway with legacy mode

## Changes

### MCP Component (setup/components/mcp.py)
- Simplified to single airis-mcp-gateway by default
- Added legacy mode for individual official servers (sequential-thinking, context7, magic, playwright)
- Dynamic prerequisites based on mode:
  - Default: uv + claude CLI only
  - Legacy: node (18+) + npm + claude CLI
- Removed redundant server definitions

### CLI Integration
- Added --legacy flag to setup/cli/commands/install.py
- Added --legacy flag to superclaude/cli/commands/install.py
- Config passes legacy_mode to component installer

## Benefits
- ✅ Simpler: 1 gateway vs 9+ individual servers
- ✅ Lighter: No Node.js/npm required (default mode)
- ✅ Unified: All tools in one gateway (sequential-thinking, context7, magic, playwright, serena, morphllm, tavily, chrome-devtools, git, puppeteer)
- ✅ Flexible: --legacy flag for official servers if needed

## Usage
```bash
superclaude install              # Default: airis-mcp-gateway (推奨)
superclaude install --legacy     # Legacy: individual official servers
```

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

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

* refactor: rename CoreComponent to FrameworkDocsComponent and add PM token tracking

## Changes

### Component Renaming (setup/components/)
- Renamed CoreComponent → FrameworkDocsComponent for clarity
- Updated all imports in __init__.py, agents.py, commands.py, mcp_docs.py, modes.py
- Better reflects the actual purpose (framework documentation files)

### PM Agent Enhancement (superclaude/commands/pm.md)
- Added token usage tracking instructions
- PM Agent now reports:
  1. Current token usage from system warnings
  2. Percentage used (e.g., "27% used" for 54K/200K)
  3. Status zone: 🟢 <75% | 🟡 75-85% | 🔴 >85%
- Helps prevent token exhaustion during long sessions

### UI Utilities (setup/utils/ui.py)
- Added new UI utility module for installer
- Provides consistent user interface components

## Benefits
- ✅ Clearer component naming (FrameworkDocs vs Core)
- ✅ PM Agent token awareness for efficiency
- ✅ Better visual feedback with status zones

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

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

* refactor(pm-agent): minimize output verbosity (471→284 lines, 40% reduction)

**Problem**: PM Agent generated excessive output with redundant explanations
- "System Status Report" with decorative formatting
- Repeated "Common Tasks" lists user already knows
- Verbose session start/end protocols
- Duplicate file operations documentation

**Solution**: Compress without losing functionality
- Session Start: Reduced to symbol-only status (🟢 branch | nM nD | token%)
- Session End: Compressed to essential actions only
- File Operations: Consolidated from 2 sections to 1 line reference
- Self-Improvement: 5 phases → 1 unified workflow
- Output Rules: Explicit constraints to prevent Claude over-explanation

**Quality Preservation**:
- ✅ All core functions retained (PDCA, memory, patterns, mistakes)
- ✅ PARALLEL Read/Write preserved (performance critical)
- ✅ Workflow unchanged (session lifecycle intact)
- ✅ Added output constraints (prevents verbose generation)

**Reduction Method**:
- Deleted: Explanatory text, examples, redundant sections
- Retained: Action definitions, file paths, core workflows
- Added: Explicit output constraints to enforce minimalism

**Token Impact**: 40% reduction in agent documentation size
**Before**: Verbose multi-section report with task lists
**After**: Single line status: 🟢 integration | 15M 17D | 36%

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

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

* refactor: consolidate MCP integration to unified gateway

**Changes**:
- Remove individual MCP server docs (superclaude/mcp/*.md)
- Remove MCP server configs (superclaude/mcp/configs/*.json)
- Delete MCP docs component (setup/components/mcp_docs.py)
- Simplify installer (setup/core/installer.py)
- Update components for unified gateway approach

**Rationale**:
- Unified gateway (airis-mcp-gateway) provides all MCP servers
- Individual docs/configs no longer needed (managed centrally)
- Reduces maintenance burden and file count
- Simplifies installation process

**Files Removed**: 17 MCP files (docs + configs)
**Installer Changes**: Removed legacy MCP installation logic

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

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

* chore: update version and component metadata

- Bump version (pyproject.toml, setup/__init__.py)
- Update CLAUDE.md import service references
- Reflect component structure changes

🤖 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-17 05:43:06 +05:30
habuchin
7c14a31bc3
Fix ModuleNotFoundError in PyPI publish workflow (#433) 
## Problem
The v4.1.6 PyPI publish workflow is failing with `ModuleNotFoundError: No module named 'SuperClaude'`.

**Failed workflow runs:**
- 5 consecutive failures since v4.1.6 release

**Root cause:**
v4.1.6 partially fixed the module import but missed updating variable references:
- ✅ Changed `import SuperClaude` → `import superclaude`
- ❌ Left `SuperClaude.__version__` unchanged (should be `superclaude.__version__`)

## Changes

Fixed 2 remaining incorrect module references:

1. **Line 125** (deployment summary step):
   - `from SuperClaude import __version__` → `from superclaude import __version__`

2. **Line 164** (test installation step):
   - `SuperClaude.__version__` → `superclaude.__version__`

## Context

- **Package name** (PyPI): `SuperClaude` (used for `pip install SuperClaude`)
- **Module name** (Python): `superclaude` (used for `import superclaude`)

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

Co-authored-by: Claude <noreply@anthropic.com>
 2025-10-15 18:32:27 +05:30
Mithun Gowda B
f973dc9ba7
Update publish-pypi.yml 
Signed-off-by: Mithun Gowda B <mithungowda.b7411@gmail.com>
 2025-10-14 15:01:36 +05:30
Mithun Gowda B
385c96c9d4
Update publish-pypi.yml 
Signed-off-by: Mithun Gowda B <mithungowda.b7411@gmail.com>
 2025-10-14 14:57:45 +05:30
Mithun Gowda B
fd1e5eda3f
Update publish-pypi.yml 
Signed-off-by: Mithun Gowda B <mithungowda.b7411@gmail.com>
 2025-10-14 14:54:58 +05:30
sarosh
cd57278069
added spec-panel, which transforms the project specs though the lens … (#346) 
Introduces a multi-expert specification review and improvement system
powered by renowned software engineering and specification experts. This
command transforms technical specifications through the lens of industry
  experts, providing actionable feedback and systematic improvement
  recommendations.

  🎯 Key Features

  Expert Panel System
  - 10 Industry Experts: Karl Wiegers, Gojko Adzic, Alistair Cockburn,
  Martin Fowler, Michael Nygard, Sam Newman, Gregor Hohpe, Lisa Crispin,
  Janet Gregory, and Kelsey Hightower
- Domain Specialization: Requirements engineering, architecture,
testing,
   compliance, and cloud-native patterns
  - Authentic Methodologies: Each expert applies their real-world
  frameworks and critique styles

  Analysis Modes
  - Discussion Mode: Collaborative improvement through expert dialogue
  - Critique Mode: Systematic review with prioritized recommendations
  - Socratic Mode: Learning-focused questioning for deeper understanding

  Focus Areas
  - Requirements: Clarity, completeness, testability validation
- Architecture: Interface design, scalability, maintainability analysis
  - Testing: Quality attributes, coverage, edge case identification
- Compliance: Regulatory requirements, security, operational excellence

  🔧 Technical Implementation

  Command Structure
  /sc:spec-panel [content|@file] [--mode discussion|critique|socratic]
  [--focus area] [--iterations N]

  MCP Integration
  - Sequential MCP: Expert panel coordination and structured analysis
  - Context7 MCP: Industry patterns and best practices
  - Persona System: Technical Writer, System Architect, Quality Engineer
  activation

  Quality Metrics
  - Clarity Score (0-10): Language precision and understandability
  - Completeness Score (0-10): Coverage of essential elements
  - Testability Score (0-10): Measurability and validation capability
  - Consistency Score (0-10): Internal coherence assessment

  📊 Output Examples

  Expert Critique Format
  KARL WIEGERS - Requirements Engineering:
  ❌ CRITICAL: Password complexity requirements not specified
  📝 RECOMMENDATION: Add requirement "System SHALL enforce password
  complexity: minimum 8 characters, mixed case, numbers"
  🎯 PRIORITY: High - Security vulnerability without standards
  📊 QUALITY IMPACT: +35% security compliance, +20% completeness

  Improvement Roadmap
  - Immediate: Critical security and clarity issues
  - Short-term: Architecture refinements and testing strategies
  - Long-term: Evolution planning and advanced optimizations

  🚀 Integration Patterns

  Workflow 
1. Generate specification using
https://github.com/github/spec-kit/blob/main/spec-driven.md
  2. Review and improve with expert panel
  3. Iterative refinement based on feedback

  CI/CD Integration
  - Specification validation in development workflow
  - Quality gate enforcement with automated checks
  - Version control integration for evolution tracking

  📈 Quality Impact

  Based on an example review:
  - Security Completeness: +35% improvement
  - Requirements Clarity: +14% improvement
  - Testability Score: +19% improvement
  - Production Readiness: +47% improvement
  - Overall Quality: +24% improvement

  🎓 Learning Features

  Educational Value
  - Socratic questioning mode for skill development
  - Expert methodology exposure and learning
  - Progressive specification writing guidance
  - Best practice pattern recognition

  Mentoring Integration
  - Step-by-step improvement guidance
  - Industry standard alignment
  - Professional specification writing techniques

  🔗 Files Changed

  - SuperClaude/Commands/spec-panel.md - Complete command specification

  🧪 Testing

  Includes comprehensive examples:
  - API specification review with security focus
  - Requirements workshop with collaborative analysis
  - Architecture validation with socratic questioning
  - Multi-iteration improvement workflows

This feature significantly enhances SuperClaude's specification analysis
  capabilities, providing professional-grade review and improvement
guidance through authentic expert perspectives and proven methodologies.
 2025-09-09 20:31:56 +05:30
markm-io
82b92a1ca1 fix: Add missing toml dependency to prevent release version skipping 
- Add toml package to build dependencies in publish-pypi.yml
- Prevents ModuleNotFoundError during version verification
- Fixes root cause of v4.0.8 version skipping issue
- Ensures reliable PyPI release workflow execution
 2025-09-05 16:02:59 -05:00
SevenThRe
494e9e6b1a feat: Add complete multilingual README support with quality automation 
- Add README-zh.md with full Chinese translation
- Add README-ja.md with full Japanese translation
- Update README.md with professional language selector
- Add GitHub Actions workflow for README quality checks
 2025-08-28 16:24:29 +09:00
NomenAK
c946fbd2eb Create FUNDING.yml 
Signed-off-by: NomenAK <39598727+NomenAK@users.noreply.github.com>
 2025-08-16 16:20:25 +02:00
NomenAK
e8afb94163 Add comprehensive PyPI publishing infrastructure 
## Version Management & Consistency
- Update to version 4.0.0b1 (proper beta versioning for PyPI)
- Add __version__ attribute to SuperClaude/__init__.py
- Ensure version consistency across pyproject.toml, __main__.py, setup/__init__.py

## Enhanced Package Configuration
- Improve pyproject.toml with comprehensive PyPI classifiers
- Add proper license specification and enhanced metadata
- Configure package discovery with inclusion/exclusion patterns
- Add development and test dependencies

## Publishing Scripts & Tools
- scripts/build_and_upload.py: Advanced Python script for building and uploading
- scripts/publish.sh: User-friendly shell wrapper for common operations
- scripts/validate_pypi_ready.py: Comprehensive validation and readiness checker
- All scripts executable with proper error handling and validation

## GitHub Actions Automation
- .github/workflows/publish-pypi.yml: Complete CI/CD pipeline
- Automatic publishing on GitHub releases
- Manual workflow dispatch for TestPyPI uploads
- Package validation and installation testing

## Documentation & Security
- PUBLISHING.md: Comprehensive PyPI publishing guide
- scripts/README.md: Detailed script usage documentation
- .env.example: Environment variable template
- Secure token handling with both .pypirc and environment variables

## Features
✅ Version consistency validation across all files
✅ Comprehensive PyPI metadata and classifiers
✅ Multi-environment publishing (TestPyPI + PyPI)
✅ Automated GitHub Actions workflow
✅ Security best practices for API token handling
✅ Complete documentation and troubleshooting guides
✅ Enterprise-grade validation and error handling

The SuperClaude Framework is now fully prepared for PyPI publication
with professional-grade automation, validation, and documentation.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-15 15:15:51 +02:00
NomenAK
b2fc8965ce
Delete .github/workflows directory 
Signed-off-by: NomenAK <39598727+NomenAK@users.noreply.github.com>
 2025-08-07 18:38:22 +02:00
NomenAK
1d03832f2d SuperClaude V4 Beta: Major framework restructuring 
- Restructured core framework components
- Added new Agents, MCP servers, and Modes documentation
- Introduced SuperClaude-Lite minimal implementation
- Enhanced Commands with session management capabilities
- Added comprehensive Hooks system with Python integration
- Removed legacy setup and profile components
- Updated .gitignore to exclude Tests/, ClaudeDocs/, and .serena/
- Consolidated configuration into SuperClaude/Config/
- Added Templates for consistent component creation

This is the initial commit for the V4 Beta branch containing all recent framework improvements and architectural changes.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-05 13:59:17 +02:00
NomenAK
2fcb88aa9b
Delete .github/workflows/claude-code-review.yml 
Signed-off-by: NomenAK <39598727+NomenAK@users.noreply.github.com>
 2025-07-15 16:46:05 +02:00
NomenAK
44c5615aa6
Delete .github/workflows/claude.yml 
Signed-off-by: NomenAK <39598727+NomenAK@users.noreply.github.com>
 2025-07-15 16:45:55 +02:00
NomenAK
468f70123c Claude Code Review workflow 2025-07-14 21:05:08 +02:00
NomenAK
359d0d28ee Claude PR Assistant workflow 2025-07-14 21:05:07 +02:00