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

refactor: PM Agent complete independence from external MCP servers (#439)

Browse Source 
* 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>
This commit is contained in:
kazuki nakai
2025-10-17 09:13:06 +09:00
committed by GitHub
parent 5bc82dbe30
commit 882a0d8356
90 changed files with 12060 additions and 3773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

409
docs/research/research_oss_fork_workflow_2025.md Normal file
View File

@@ -0,0 +1,409 @@
# OSS Fork Workflow Best Practices 2025
**Research Date**: 2025-10-16
**Context**: 2-tier fork structure (OSS upstream → personal fork)
**Goal**: Clean PR workflow maintaining sync with zero garbage commits
---
## 🎯 Executive Summary
2025年のOSS貢献における標準フォークワークフローは、**個人フォークのmainブランチを絶対に汚さない**ことが大原則。upstream同期にはmergeではなく**rebase**を使用し、PR前には**rebase -i**でコミット履歴を整理することで、クリーンな差分のみを提出する。
**推奨ブランチ戦略**:
```
master (or main): upstream mirror（同期専用、直接コミット禁止）
feature/*: 機能開発ブランチ（upstream/masterから派生）
```
**"dev"ブランチは不要** - 役割が曖昧で混乱の原因となる。
---
## 📚 Current Structure
```
upstream: SuperClaude-Org/SuperClaude_Framework ← OSS本家
↓ (fork)
origin: kazukinakai/SuperClaude_Framework ← 個人フォーク
```
**Current Branches**:
- `master`: upstream追跡用
- `dev`: 作業ブランチ（❌ 役割不明確）
- `feature/*`: 機能ブランチ
---
## ✅ Recommended Workflow (2025 Standard)
### Phase 1: Initial Setup (一度だけ)
```bash
# 1. Fork on GitHub UI
# SuperClaude-Org/SuperClaude_Framework → kazukinakai/SuperClaude_Framework
# 2. Clone personal fork
git clone https://github.com/kazukinakai/SuperClaude_Framework.git
cd SuperClaude_Framework
# 3. Add upstream remote
git remote add upstream https://github.com/SuperClaude-Org/SuperClaude_Framework.git
# 4. Verify remotes
git remote -v
# origin https://github.com/kazukinakai/SuperClaude_Framework.git (fetch/push)
# upstream https://github.com/SuperClaude-Org/SuperClaude_Framework.git (fetch/push)
```
### Phase 2: Daily Workflow
#### Step 1: Sync with Upstream
```bash
# Fetch latest from upstream
git fetch upstream
# Update local master (fast-forward only, no merge commits)
git checkout master
git merge upstream/master --ff-only
# Push to personal fork (keep origin/master in sync)
git push origin master
```
**重要**: `--ff-only`を使うことで、意図しないマージコミットを防ぐ。
#### Step 2: Create Feature Branch
```bash
# Create feature branch from latest upstream/master
git checkout -b feature/pm-agent-redesign master
# Alternative: checkout from upstream/master directly
git checkout -b feature/clean-docs upstream/master
```
**命名規則**:
- `feature/xxx`: 新機能
- `fix/xxx`: バグ修正
- `docs/xxx`: ドキュメント
- `refactor/xxx`: リファクタリング
#### Step 3: Development
```bash
# Make changes
# ... edit files ...
# Commit (atomic commits: 1 commit = 1 logical change)
git add .
git commit -m "feat: add PM Agent session persistence"
# Continue development with multiple commits
git commit -m "refactor: extract memory logic to separate module"
git commit -m "test: add unit tests for memory operations"
git commit -m "docs: update PM Agent documentation"
```
**Atomic Commits**:
- 1コミット = 1つの論理的変更
- コミットメッセージは具体的に（"fix typo"ではなく"fix: correct variable name in auth.js:45"）
#### Step 4: Clean Up Before PR
```bash
# Interactive rebase to clean commit history
git rebase -i master
# Rebase editor opens:
# pick abc1234 feat: add PM Agent session persistence
# squash def5678 refactor: extract memory logic to separate module
# squash ghi9012 test: add unit tests for memory operations
# pick jkl3456 docs: update PM Agent documentation
# Result: 2 clean commits instead of 4
```
**Rebase Operations**:
- `pick`: コミットを残す
- `squash`: 前のコミットに統合
- `reword`: コミットメッセージを変更
- `drop`: コミットを削除
#### Step 5: Verify Clean Diff
```bash
# Check what will be in the PR
git diff master...feature/pm-agent-redesign --name-status
# Review actual changes
git diff master...feature/pm-agent-redesign
# Ensure ONLY your intended changes are included
# No garbage commits, no disabled code, no temporary files
```
#### Step 6: Push and Create PR
```bash
# Push to personal fork
git push origin feature/pm-agent-redesign
# Create PR using GitHub CLI
gh pr create --repo SuperClaude-Org/SuperClaude_Framework \
--title "feat: PM Agent session persistence with local memory" \
--body "$(cat <<'EOF'
## Summary
- Implements session persistence for PM Agent
- Uses local file-based memory (no external MCP dependencies)
- Includes comprehensive test coverage
## Test Plan
- [x] Unit tests pass
- [x] Integration tests pass
- [x] Manual verification complete
🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"
```
### Phase 3: Handle PR Feedback
```bash
# Make requested changes
# ... edit files ...
# Commit changes
git add .
git commit -m "fix: address review comments - improve error handling"
# Clean up again if needed
git rebase -i master
# Force push (safe because it's your feature branch)
git push origin feature/pm-agent-redesign --force-with-lease
```
**Important**: `--force-with-lease`は`--force`より安全（リモートに他人のコミットがある場合は失敗する）
---
## 🚫 Anti-Patterns to Avoid
### ❌ Never Commit to master/main
```bash
# WRONG
git checkout master
git commit -m "quick fix" # ← これをやると同期が壊れる
# CORRECT
git checkout -b fix/typo master
git commit -m "fix: correct typo in README"
```
### ❌ Never Merge When You Should Rebase
```bash
# WRONG (creates unnecessary merge commits)
git checkout feature/xxx
git merge master # ← マージコミットが生成される
# CORRECT (keeps history linear)
git checkout feature/xxx
git rebase master # ← 履歴が一直線になる
```
### ❌ Never Rebase Public Branches
```bash
# WRONG (if others are using this branch)
git checkout shared-feature
git rebase master # ← 他人の作業を壊す
# CORRECT
git checkout shared-feature
git merge master # ← 安全にマージ
```
### ❌ Never Include Unrelated Changes in PR
```bash
# Check before creating PR
git diff master...feature/xxx
# If you see unrelated changes:
# - Stash or commit them separately
# - Create a new branch from clean master
# - Cherry-pick only relevant commits
git checkout -b feature/xxx-clean master
git cherry-pick <commit-hash>
```
---
## 🔧 "dev" Branch Problem & Solution
### 問題: "dev"ブランチの役割が曖昧
```
❌ Current (Confusing):
master ← upstream同期
dev ← 作業場？統合？staging？（不明確）
feature/* ← 機能開発
問題:
1. devから派生すべきか、masterから派生すべきか不明
2. devをいつupstream/masterに同期すべきか不明
3. PRのbaseはmaster？dev？（混乱）
```
### 解決策 Option 1: "dev"を廃止（推奨）
```bash
# Delete dev branch
git branch -d dev
git push origin --delete dev
# Use clean workflow:
master ← upstream同期専用（直接コミット禁止）
feature/* ← upstream/masterから派生
# Example:
git fetch upstream
git checkout master
git merge upstream/master --ff-only
git checkout -b feature/new-feature master
```
**利点**:
- シンプルで迷わない
- upstream同期が明確
- PRのbaseが常にmaster（一貫性）
### 解決策 Option 2: "dev" → "integration"にリネーム
```bash
# Rename for clarity
git branch -m dev integration
git push origin -u integration
git push origin --delete dev
# Use as integration testing branch:
master ← upstream同期専用
integration ← 複数featureの統合テスト
feature/* ← upstream/masterから派生
# Workflow:
git checkout -b feature/xxx master # masterから派生
# ... develop ...
git checkout integration
git merge feature/xxx # 統合テスト用にマージ
# テスト完了後、masterからPR作成
```
**利点**:
- 統合テスト用ブランチとして明確な役割
- 複数機能の組み合わせテストが可能
**欠点**:
- 個人開発では通常不要（OSSでは使わない）
### 推奨: Option 1（"dev"廃止）
理由:
- OSSコントリビューションでは"dev"は標準ではない
- シンプルな方が混乱しない
- upstream/master → feature/* → PR が最も一般的
---
## 📊 Branch Strategy Comparison
| Strategy | master/main | dev/integration | feature/* | Use Case |
|----------|-------------|-----------------|-----------|----------|
| **Simple (推奨)** | upstream mirror | なし | from master | OSS contribution |
| **Integration** | upstream mirror | 統合テスト | from master | 複数機能の組み合わせテスト |
| **Confused (❌)** | upstream mirror | 役割不明 | from dev? | 混乱の元 |
---
## 🎯 Recommended Actions for Your Repo
### Immediate Actions
```bash
# 1. Check current state
git branch -vv
git remote -v
git status
# 2. Sync master with upstream
git fetch upstream
git checkout master
git merge upstream/master --ff-only
git push origin master
# 3. Option A: Delete "dev" (推奨)
git branch -d dev # ローカル削除
git push origin --delete dev # リモート削除
# 3. Option B: Rename "dev" → "integration"
git branch -m dev integration
git push origin -u integration
git push origin --delete dev
# 4. Create feature branch from clean master
git checkout -b feature/your-feature master
```
### Long-term Workflow
```bash
# Daily routine:
git fetch upstream && git checkout master && git merge upstream/master --ff-only && git push origin master
# Start new feature:
git checkout -b feature/xxx master
# Before PR:
git rebase -i master
git diff master...feature/xxx # verify clean diff
git push origin feature/xxx
gh pr create --repo SuperClaude-Org/SuperClaude_Framework
```
---
## 📖 References
### Official Documentation
- [GitHub: Syncing a Fork](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork)
- [Atlassian: Merging vs. Rebasing](https://www.atlassian.com/git/tutorials/merging-vs-rebasing)
- [Atlassian: Forking Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/forking-workflow)
### 2025 Best Practices
- [DataCamp: Git Merge vs Rebase (June 2025)](https://www.datacamp.com/blog/git-merge-vs-git-rebase)
- [Mergify: Rebase vs Merge Tips (April 2025)](https://articles.mergify.com/rebase-git-vs-merge/)
- [Zapier: Git Rebase vs Merge (May 2025)](https://zapier.com/blog/git-rebase-vs-merge/)
### Community Resources
- [GitHub Gist: Standard Fork & Pull Request Workflow](https://gist.github.com/Chaser324/ce0505fbed06b947d962)
- [Medium: Git Fork Development Workflow](https://medium.com/@abhijit838/git-fork-development-workflow-and-best-practices-fb5b3573ab74)
- [Stack Overflow: Keeping Fork in Sync](https://stackoverflow.com/questions/55501551/what-is-the-standard-way-of-keeping-a-fork-in-sync-with-upstream-on-collaborativ)
---
## 💡 Key Takeaways
1. **Never commit to master/main** - upstream同期専用として扱う
2. **Rebase, not merge** - upstream同期とPR前クリーンアップにrebase使用
3. **Atomic commits** - 1コミット1機能を心がける
4. **Clean before PR** - `git rebase -i`で履歴整理
5. **Verify diff** - `git diff master...feature/xxx`で差分確認
6. **"dev" is confusing** - 役割不明確なブランチは廃止または明確化
**Golden Rule**: upstream/master → feature/* → rebase -i → PR
これが2025年のOSS貢献における標準ワークフロー。