262 lines
8.0 KiB
Python
Raw Normal View History

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 09:13:06 +09:00
"""
SuperClaude install command - Modern interactive installation with rich UI
"""
import typer
from typing import Optional, List
from pathlib import Path
from rich.panel import Panel
from rich.prompt import Confirm
from rich.progress import Progress, SpinnerColumn, TextColumn
from superclaude.cli._console import console
from setup import DEFAULT_INSTALL_DIR
# Create install command group
app = typer.Typer(
name="install",
help="Install SuperClaude framework components",
no_args_is_help=False, # Allow running without subcommand
)
@app.callback(invoke_without_command=True)
def install_callback(
ctx: typer.Context,
non_interactive: bool = typer.Option(
False,
"--non-interactive",
"-y",
help="Non-interactive installation with default configuration",
),
profile: Optional[str] = typer.Option(
None,
"--profile",
help="Installation profile: api (with API keys), noapi (without), or custom",
),
install_dir: Path = typer.Option(
DEFAULT_INSTALL_DIR,
"--install-dir",
help="Installation directory",
),
force: bool = typer.Option(
False,
"--force",
help="Force reinstallation of existing components",
),
dry_run: bool = typer.Option(
False,
"--dry-run",
help="Simulate installation without making changes",
),
verbose: bool = typer.Option(
False,
"--verbose",
"-v",
help="Verbose output with detailed logging",
),
):
"""
Install SuperClaude with all recommended components (default behavior)
Running `superclaude install` without a subcommand installs all components.
Use `superclaude install components` for selective installation.
"""
# If a subcommand was invoked, don't run this
if ctx.invoked_subcommand is not None:
return
# Otherwise, run the full installation
_run_installation(non_interactive, profile, install_dir, force, dry_run, verbose)
@app.command("all")
def install_all(
non_interactive: bool = typer.Option(
False,
"--non-interactive",
"-y",
help="Non-interactive installation with default configuration",
),
profile: Optional[str] = typer.Option(
None,
"--profile",
help="Installation profile: api (with API keys), noapi (without), or custom",
),
install_dir: Path = typer.Option(
DEFAULT_INSTALL_DIR,
"--install-dir",
help="Installation directory",
),
force: bool = typer.Option(
False,
"--force",
help="Force reinstallation of existing components",
),
dry_run: bool = typer.Option(
False,
"--dry-run",
help="Simulate installation without making changes",
),
verbose: bool = typer.Option(
False,
"--verbose",
"-v",
help="Verbose output with detailed logging",
),
):
"""
Install SuperClaude with all recommended components (explicit command)
This command installs the complete SuperClaude framework including:
- Core framework files and documentation
- Behavioral modes (7 modes)
- Slash commands (26 commands)
- Specialized agents (17 agents)
- MCP server integrations (optional)
"""
_run_installation(non_interactive, profile, install_dir, force, dry_run, verbose)
def _run_installation(
non_interactive: bool,
profile: Optional[str],
install_dir: Path,
force: bool,
dry_run: bool,
verbose: bool,
):
"""Shared installation logic"""
# Display installation header
console.print(
Panel.fit(
"[bold cyan]SuperClaude Framework Installer[/bold cyan]\n"
"[dim]Modern AI-enhanced development framework for Claude Code[/dim]",
border_style="cyan",
)
)
# Import and run existing installer logic
# This bridges to the existing setup/cli/commands/install.py implementation
try:
from setup.cli.commands.install import run
import argparse
# Create argparse namespace for backward compatibility
args = argparse.Namespace(
install_dir=install_dir,
force=force,
dry_run=dry_run,
verbose=verbose,
quiet=False,
yes=True, # Always non-interactive
feat: comprehensive framework improvements (#447) * refactor(docs): move core docs into framework/business/research (move-only) - framework/: principles, rules, flags (思想・行動規範) - business/: symbols, examples (ビジネス領域) - research/: config (調査設定) - All files renamed to lowercase for consistency * docs: update references to new directory structure - Update ~/.claude/CLAUDE.md with new paths - Add migration notice in core/MOVED.md - Remove pm.md.backup - All @superclaude/ references now point to framework/business/research/ * fix(setup): update framework_docs to use new directory structure - Add validate_prerequisites() override for multi-directory validation - Add _get_source_dirs() for framework/business/research directories - Override _discover_component_files() for multi-directory discovery - Override get_files_to_install() for relative path handling - Fix get_size_estimate() to use get_files_to_install() - Fix uninstall/update/validate to use install_component_subdir Fixes installation validation errors for new directory structure. Tested: make dev installs successfully with new structure - framework/: flags.md, principles.md, rules.md - business/: examples.md, symbols.md - research/: config.md * refactor(modes): update component references for docs restructure * chore: remove redundant docs after PLANNING.md migration Cleanup after Self-Improvement Loop implementation: **Deleted (21 files, ~210KB)**: - docs/Development/ - All content migrated to PLANNING.md & TASK.md * ARCHITECTURE.md (15KB) → PLANNING.md * TASKS.md (3.7KB) → TASK.md * ROADMAP.md (11KB) → TASK.md * PROJECT_STATUS.md (4.2KB) → outdated * 13 PM Agent research files → archived in KNOWLEDGE.md - docs/PM_AGENT.md - Old implementation status - docs/pm-agent-implementation-status.md - Duplicate - docs/templates/ - Empty directory **Retained (valuable documentation)**: - docs/memory/ - Active session metrics & context - docs/patterns/ - Reusable patterns - docs/research/ - Research reports - docs/user-guide*/ - User documentation (4 languages) - docs/reference/ - Reference materials - docs/getting-started/ - Quick start guides - docs/agents/ - Agent-specific guides - docs/testing/ - Test procedures **Result**: - Eliminated redundancy after Root Documents consolidation - Preserved all valuable content in PLANNING.md, TASK.md, KNOWLEDGE.md - Maintained user-facing documentation structure 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: relocate PM modules to commands/modules - Move modules to superclaude/commands/modules/ - Organize command-specific modules under commands/ 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add self-improvement loop with 4 root documents Implements Self-Improvement Loop based on Cursor's proven patterns: **New Root Documents**: - PLANNING.md: Architecture, design principles, 10 absolute rules - TASK.md: Current tasks with priority (🔴🟡🟢⚪) - KNOWLEDGE.md: Accumulated insights, best practices, failures - README.md: Updated with developer documentation links **Key Features**: - Session Start Protocol: Read docs → Git status → Token budget → Ready - Evidence-Based Development: No guessing, always verify - Parallel Execution Default: Wave → Checkpoint → Wave pattern - Mac Environment Protection: Docker-first, no host pollution - Failure Pattern Learning: Past mistakes become prevention rules **Cleanup**: - Removed: docs/memory/checkpoint.json, current_plan.json (migrated to TASK.md) - Enhanced: setup/components/commands.py (module discovery) **Benefits**: - LLM reads rules at session start → consistent quality - Past failures documented → no repeats - Progressive knowledge accumulation → continuous improvement - 3.5x faster execution with parallel patterns 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * test: validate Self-Improvement Loop workflow Tested complete cycle: Read docs → Extract rules → Execute task → Update docs Test Results: - Session Start Protocol: ✅ All 6 steps successful - Rule Extraction: ✅ 10/10 absolute rules identified from PLANNING.md - Task Identification: ✅ Next tasks identified from TASK.md - Knowledge Application: ✅ Failure patterns accessed from KNOWLEDGE.md - Documentation Update: ✅ TASK.md and KNOWLEDGE.md updated with completed work - Confidence Score: 95% (exceeds 70% threshold) Proved Self-Improvement Loop closes: Execute → Learn → Update → Improve * refactor: responsibility-driven component architecture Rename components to reflect their responsibilities: - framework_docs.py → knowledge_base.py (KnowledgeBaseComponent) - modes.py → behavior_modes.py (BehaviorModesComponent) - agents.py → agent_personas.py (AgentPersonasComponent) - commands.py → slash_commands.py (SlashCommandsComponent) - mcp.py → mcp_integration.py (MCPIntegrationComponent) Each component now clearly documents its responsibility: - knowledge_base: Framework knowledge initialization - behavior_modes: Execution mode definitions - agent_personas: AI agent personality definitions - slash_commands: CLI command registration - mcp_integration: External tool integration Benefits: - Self-documenting architecture - Clear responsibility boundaries - Easy to navigate and extend - Scalable for future hierarchical organization 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add project-specific CLAUDE.md with UV rules - Document UV as required Python package manager - Add common operations and integration examples - Document project structure and component architecture - Provide development workflow guidelines 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: resolve installation failures after framework_docs rename ## Problems Fixed 1. **Syntax errors**: Duplicate docstrings in all component files (line 1) 2. **Dependency mismatch**: Stale framework_docs references after rename to knowledge_base ## Changes - Fix docstring format in all component files (behavior_modes, agent_personas, slash_commands, mcp_integration) - Update all dependency references: framework_docs → knowledge_base - Update component registration calls in knowledge_base.py (5 locations) - Update install.py files in both setup/ and superclaude/ (5 locations total) - Fix documentation links in README-ja.md and README-zh.md ## Verification ✅ All components load successfully without syntax errors ✅ Dependency resolution works correctly ✅ Installation completes in 0.5s with all validations passing ✅ make dev succeeds 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add automated README translation workflow ## New Features - **Auto-translation workflow** using GPT-Translate - Automatically translates README.md to Chinese (ZH) and Japanese (JA) - Triggers on README.md changes to master/main branches - Cost-effective: ~¥90/month for typical usage ## Implementation Details - Uses OpenAI GPT-4 for high-quality translations - GitHub Actions integration with gpt-translate@v1.1.11 - Secure API key management via GitHub Secrets - Automatic commit and PR creation on translation updates ## Files Added - `.github/workflows/translation-sync.yml` - Auto-translation workflow - `docs/Development/translation-workflow.md` - Setup guide and documentation ## Setup Required Add `OPENAI_API_KEY` to GitHub repository secrets to enable auto-translation. ## Benefits - 🤖 Automated translation on every README update - 💰 Low cost (~$0.06 per translation) - 🛡️ Secure API key storage - 🔄 Consistent translation quality across languages 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix(mcp): update airis-mcp-gateway URL to correct organization Fixes #440 ## Problem Code referenced non-existent `oraios/airis-mcp-gateway` repository, causing MCP installation to fail completely. ## Root Cause - Repository was moved to organization: `agiletec-inc/airis-mcp-gateway` - Old reference `oraios/airis-mcp-gateway` no longer exists - Users reported "not a python/uv module" error ## Changes - Update install_command URL: oraios → agiletec-inc - Update run_command URL: oraios → agiletec-inc - Location: setup/components/mcp_integration.py lines 37-38 ## Verification ✅ Correct URL now references active repository ✅ MCP installation will succeed with proper organization ✅ No other code references oraios/airis-mcp-gateway ## Related Issues - Fixes #440 (Airis-mcp-gateway url has changed) - Related to #442 (MCP update issues) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: replace cloud translation with local Neural CLI ## Changes ### Removed (OpenAI-dependent) - ❌ `.github/workflows/translation-sync.yml` - GPT-Translate workflow - ❌ `docs/Development/translation-workflow.md` - OpenAI setup docs ### Added (Local Ollama-based) - ✅ `Makefile`: New `make translate` target using Neural CLI - ✅ `docs/Development/translation-guide.md` - Neural CLI guide ## Benefits **Before (GPT-Translate)**: - 💰 Monthly cost: ~¥90 (OpenAI API) - 🔑 Requires API key setup - 🌐 Data sent to external API - ⏱️ Network latency **After (Neural CLI)**: - ✅ **$0 cost** - Fully local execution - ✅ **No API keys** - Zero setup friction - ✅ **Privacy** - No external data transfer - ✅ **Fast** - ~1-2 min per README - ✅ **Offline capable** - Works without internet ## Technical Details **Neural CLI**: - Built in Rust with Tauri - Uses Ollama + qwen2.5:3b model - Binary size: 4.0MB - Auto-installs to ~/.local/bin/ **Usage**: ```bash make translate # Translates README.md → README-zh.md, README-ja.md ``` ## Requirements - Ollama installed: `curl -fsSL https://ollama.com/install.sh | sh` - Model downloaded: `ollama pull qwen2.5:3b` - Neural CLI built: `cd ~/github/neural/src-tauri && cargo build --bin neural-cli --release` 🤖 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-18 23:58:10 +09:00
components=["knowledge_base", "modes", "commands", "agents"], # Full install (mcp integrated into airis-mcp-gateway)
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 09:13:06 +09:00
no_backup=False,
list_components=False,
diagnose=False,
)
# Show progress with rich spinner
with Progress(
SpinnerColumn(),
TextColumn("[progress.description]{task.description}"),
console=console,
transient=False,
) as progress:
task = progress.add_task("Installing SuperClaude...", total=None)
# Run existing installer
exit_code = run(args)
if exit_code == 0:
progress.update(task, description="[green]Installation complete![/green]")
console.print("\n[bold green]✓ SuperClaude installed successfully![/bold green]")
console.print("\n[cyan]Next steps:[/cyan]")
console.print(" 1. Restart your Claude Code session")
console.print(f" 2. Framework files are now available in {install_dir}")
console.print(" 3. Use SuperClaude commands and features in Claude Code")
else:
progress.update(task, description="[red]Installation failed[/red]")
console.print("\n[bold red]✗ Installation failed[/bold red]")
console.print("[yellow]Check logs for details[/yellow]")
raise typer.Exit(1)
except ImportError as e:
console.print(f"[bold red]Error:[/bold red] Could not import installer: {e}")
console.print("[yellow]Ensure SuperClaude is properly installed[/yellow]")
raise typer.Exit(1)
except Exception as e:
console.print(f"[bold red]Unexpected error:[/bold red] {e}")
if verbose:
console.print_exception()
raise typer.Exit(1)
@app.command("components")
def install_components(
components: List[str] = typer.Argument(
...,
help="Component names to install (e.g., core modes commands agents)",
),
install_dir: Path = typer.Option(
DEFAULT_INSTALL_DIR,
"--install-dir",
help="Installation directory",
),
force: bool = typer.Option(
False,
"--force",
help="Force reinstallation",
),
dry_run: bool = typer.Option(
False,
"--dry-run",
help="Simulate installation",
),
):
"""
Install specific SuperClaude components
Available components:
- core: Core framework files and documentation
- modes: Behavioral modes (7 modes)
- commands: Slash commands (26 commands)
- agents: Specialized agents (17 agents)
- mcp: MCP server integrations
- mcp: MCP server configurations (airis-mcp-gateway)
"""
console.print(
Panel.fit(
f"[bold]Installing components:[/bold] {', '.join(components)}",
border_style="cyan",
)
)
try:
from setup.cli.commands.install import run
import argparse
args = argparse.Namespace(
install_dir=install_dir,
force=force,
dry_run=dry_run,
verbose=False,
quiet=False,
yes=True, # Non-interactive for component installation
components=components,
no_backup=False,
list_components=False,
diagnose=False,
)
exit_code = run(args)
if exit_code == 0:
console.print(f"\n[bold green]✓ Components installed: {', '.join(components)}[/bold green]")
else:
console.print("\n[bold red]✗ Component installation failed[/bold red]")
raise typer.Exit(1)
except Exception as e:
console.print(f"[bold red]Error:[/bold red] {e}")
raise typer.Exit(1)