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
291 Commits 9 Branches 17 Tags
8ec7e5e017bf53bb0e27e2cb27ce2e0bdb9ecbc2
Commit Graph

9 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
NomenAK
6afa3b0f9c 🚀 Prepare for dual PyPI/NPM release v4.0 
- Fix version consistency (PyPI: 4.0.0, NPM: 4.0.3)
- Update license format to PEP 639 compliance
- Restore NPM package components (bin/ and package.json)
- Fix NPM package name to @superclaude-org/superclaude
- Add comprehensive RELEASE_INSTRUCTIONS.md
- Update .gitignore to include NPM files
- Ready for production release on both PyPI and NPM

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-22 20:39:46 +02:00
NomenAK
a4d1be0e26 🧹 Clean up repository by removing development artifacts 
- Remove CRUSH.md personal file
- Remove Node.js artifacts: package.json, package-lock.json, bin/ directory
- Remove Python lock file: uv.lock
- Update .gitignore to prevent future inclusion of these artifacts
- Maintain clean repository structure with only essential framework files

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-22 20:11:21 +02:00
NomenAK
886323b240 📚 Major documentation improvements and corrections 
- Fix directory structure in technical-architecture.md to match actual ~/.claude/ structure
- Correct session management documentation to show true persistent memory via Serena MCP
- Add comprehensive flags documentation with 40+ missing command-specific flags
- Remove verification status sections across all documentation
- Fix component counts: 14 agents, 5 modes, 21 commands
- Update gitignore to exclude CRUSH.md and TODO.txt personal files
- Standardize documentation structure and remove fictional content

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-22 20:09:27 +02:00
NomenAK
40840dae0b Restructure documentation: Create focused guide ecosystem from oversized user guide 
- Transform 28K+ token superclaude-user-guide.md into 4.5K token overview (84% reduction)
- Extract specialized guides: examples-cookbook.md, troubleshooting-guide.md, best-practices.md, session-management.md, technical-architecture.md
- Add comprehensive cross-references between all guides for improved navigation
- Maintain professional documentation quality with technical-writer agent approach
- Remove template files and consolidate agent naming (backend-engineer → backend-architect, etc.)
- Update all existing guides with cross-references and related guides sections
- Create logical learning paths from beginner to advanced users
- Eliminate content duplication while preserving all valuable information

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-15 21:30:29 +02:00
NomenAK
85bcee15c4 Enhance project cleanup and update gitignore for PyPI publishing 
## Enhanced .gitignore
- Add PyPI publishing exclusions (*.whl, *.tar.gz, twine.log, .twine/)
- Improve security exclusions (.pypirc for API tokens)
- Add comprehensive development tool exclusions (.mypy_cache/, .ruff_cache/, etc.)
- Expand build artifact exclusions (additional package formats)
- Add IDE-specific exclusions for better development experience
- Include publishing and release directory exclusions

## Version Consistency
- Update VERSION file to proper PyPI format (4.0.0b1)
- Maintain consistency across all version references

## Project Cleanup
- Remove Python cache directories (__pycache__)
- Remove egg-info directories (SuperClaude.egg-info)
- Remove temporary setup completion files
- Clean development artifacts for distribution readiness

## New Maintenance Tool
- Add scripts/cleanup.sh: Comprehensive cleanup script for:
  - Python cache files and compiled bytecode
  - Build artifacts (dist/, build/, *.egg-info)
  - Test artifacts (.pytest_cache/, coverage files)
  - Development tool cache (.mypy_cache/, .ruff_cache/)
  - Temporary and backup files
  - PyPI publishing artifacts
  - OS-specific files (.DS_Store, Thumbs.db)

## Security Enhancements
- Exclude .pypirc from version control (contains API tokens)
- Ensure sensitive files are properly ignored
- Remove temporary setup files from repository

This ensures a clean, secure, and professionally organized
repository ready for PyPI publication with comprehensive
development tool support and proper artifact management.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-15 15:20:35 +02:00
NomenAK
d273b60f2e Update .gitignore with comprehensive Python project patterns 
Enhanced .gitignore with:
- Complete Python packaging patterns (pip, poetry, pipenv)
- Testing and coverage tools (pytest, tox, coverage)
- Virtual environment patterns (.venv, env, etc)
- Modern IDE support (VS Code, PyCharm, Sublime)
- Security patterns (.env files, certificates, keys)
- Build artifacts (wheels, distributions, installers)
- Documentation builds (Sphinx, MkDocs)
- SuperClaude-specific patterns (.serena, .superclaude)

Organized in logical sections for better maintainability.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-08-14 22:09:36 +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
59d74b8af2 Initial commit: SuperClaude v3 Beta clean architecture 
Complete foundational restructure with:
- Simplified project architecture
- Comprehensive documentation system
- Modern installation framework
- Clean configuration management
- Updated profiles and settings

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-07-14 14:28:11 +02:00