mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
refactor: PEP8 compliance - directory rename and code formatting (#425)
* fix(orchestration): add WebFetch auto-trigger for infrastructure configuration Problem: Infrastructure configuration changes (e.g., Traefik port settings) were being made based on assumptions without consulting official documentation, violating the 'Evidence > assumptions' principle in PRINCIPLES.md. Solution: - Added Infrastructure Configuration Validation section to MODE_Orchestration.md - Auto-triggers WebFetch for infrastructure tools (Traefik, nginx, Docker, etc.) - Enforces MODE_DeepResearch activation for investigation - BLOCKS assumption-based configuration changes Testing: Verified WebFetch successfully retrieves Traefik official docs (port 80 default) This prevents production outages from infrastructure misconfiguration by ensuring all technical recommendations are backed by official documentation. * feat: Add PM Agent (Project Manager Agent) for seamless orchestration Introduces PM Agent as the default orchestration layer that coordinates all sub-agents and manages workflows automatically. Key Features: - Default orchestration: All user interactions handled by PM Agent - Auto-delegation: Intelligent sub-agent selection based on task analysis - Docker Gateway integration: Zero-token baseline with dynamic MCP loading - Self-improvement loop: Automatic documentation of patterns and mistakes - Optional override: Users can specify sub-agents explicitly if desired Architecture: - Agent spec: SuperClaude/Agents/pm-agent.md - Command: SuperClaude/Commands/pm.md - Updated docs: README.md (15→16 agents), agents.md (new Orchestration category) User Experience: - Default: PM Agent handles everything (seamless, no manual routing) - Optional: Explicit --agent flag for direct sub-agent access - Both modes available simultaneously (no user downside) Implementation Status: - ✅ Specification complete - ✅ Documentation complete - ⏳ Prototype implementation needed - ⏳ Docker Gateway integration needed - ⏳ Testing and validation needed Refs: kazukinakai/docker-mcp-gateway (IRIS MCP Gateway integration) * feat: Add Agent Orchestration rules for PM Agent default activation Implements PM Agent as the default orchestration layer in RULES.md. Key Changes: - New 'Agent Orchestration' section (CRITICAL priority) - PM Agent receives ALL user requests by default - Manual override with @agent-[name] bypasses PM Agent - Agent Selection Priority clearly defined: 1. Manual override → Direct routing 2. Default → PM Agent → Auto-delegation 3. Delegation based on keywords, file types, complexity, context User Experience: - Default: PM Agent handles everything (seamless) - Override: @agent-[name] for direct specialist access - Transparent: PM Agent reports delegation decisions This establishes PM Agent as the orchestration layer while respecting existing auto-activation patterns and manual overrides. Next Steps: - Local testing in agiletec project - Iteration based on actual behavior - Documentation updates as needed * refactor(pm-agent): redesign as self-improvement meta-layer Problem Resolution: PM Agent's initial design competed with existing auto-activation for task routing, creating confusion about orchestration responsibilities and adding unnecessary complexity. Design Change: Redefined PM Agent as a meta-layer agent that operates AFTER specialist agents complete tasks, focusing on: - Post-implementation documentation and pattern recording - Immediate mistake analysis with prevention checklists - Monthly documentation maintenance and noise reduction - Pattern extraction and knowledge synthesis Two-Layer Orchestration System: 1. Task Execution Layer: Existing auto-activation handles task routing (unchanged) 2. Self-Improvement Layer: PM Agent meta-layer handles documentation (new) Files Modified: - SuperClaude/Agents/pm-agent.md: Complete rewrite with meta-layer design - Category: orchestration → meta - Triggers: All user interactions → Post-implementation, mistakes, monthly - Behavioral Mindset: Continuous learning system - Self-Improvement Workflow: BEFORE/DURING/AFTER/MISTAKE RECOVERY/MAINTENANCE - SuperClaude/Core/RULES.md: Agent Orchestration section updated - Split into Task Execution Layer + Self-Improvement Layer - Added orchestration flow diagram - Clarified PM Agent activates AFTER task completion - README.md: Updated PM Agent description - "orchestrates all interactions" → "ensures continuous learning" - Docs/User-Guide/agents.md: PM Agent section rewritten - Section: Orchestration Agent → Meta-Layer Agent - Expertise: Project orchestration → Self-improvement workflow executor - Examples: Task coordination → Post-implementation documentation - PR_DOCUMENTATION.md: Comprehensive PR documentation added - Summary, motivation, changes, testing, breaking changes - Two-layer orchestration system diagram - Verification checklist Integration Validated: Tested with agiletec project's self-improvement-workflow.md: ✅ PM Agent aligns with existing BEFORE/DURING/AFTER/MISTAKE RECOVERY phases ✅ Complements (not competes with) existing workflow ✅ agiletec workflow defines WHAT, PM Agent defines WHO executes it Breaking Changes: None - Existing auto-activation continues unchanged - Specialist agents unaffected - User workflows remain the same - New capability: Automatic documentation and knowledge maintenance Value Proposition: Transforms SuperClaude into a continuously learning system that accumulates knowledge, prevents recurring mistakes, and maintains fresh documentation without manual intervention. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * docs: add Claude Code conversation history management research Research covering .jsonl file structure, performance impact, and retention policies. Content: - Claude Code .jsonl file format and message types - Performance issues from GitHub (memory leaks, conversation compaction) - Retention policies (consumer vs enterprise) - Rotation recommendations based on actual data - File history snapshot tracking mechanics Source: Moved from agiletec project (research applicable to all Claude Code projects) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: add Development documentation structure Phase 1: Documentation Structure complete - Add Docs/Development/ directory for development documentation - Add ARCHITECTURE.md - System architecture with PM Agent meta-layer - Add ROADMAP.md - 5-phase development plan with checkboxes - Add TASKS.md - Daily task tracking with progress indicators - Add PROJECT_STATUS.md - Current status dashboard and metrics - Add pm-agent-integration.md - Implementation guide for PM Agent mode This establishes comprehensive documentation foundation for: - System architecture understanding - Development planning and tracking - Implementation guidance - Progress visibility Related: #pm-agent-mode #documentation #phase-1 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat: PM Agent session lifecycle and PDCA implementation Phase 2: PM Agent Mode Integration (Design Phase) Commands/pm.md updates: - Add "Always-Active Foundation Layer" concept - Add Session Lifecycle (Session Start/During Work/Session End) - Add PDCA Cycle (Plan/Do/Check/Act) automation - Add Serena MCP Memory Integration (list/read/write_memory) - Document auto-activation triggers Agents/pm-agent.md updates: - Add Session Start Protocol (MANDATORY auto-activation) - Add During Work PDCA Cycle with example workflows - Add Session End Protocol with state preservation - Add PDCA Self-Evaluation Pattern - Add Documentation Strategy (temp → patterns/mistakes) - Add Memory Operations Reference Key Features: - Session start auto-activation for context restoration - 30-minute checkpoint saves during work - Self-evaluation with think_about_* operations - Systematic documentation lifecycle - Knowledge evolution to CLAUDE.md Implementation Status: - ✅ Design complete (Commands/pm.md, Agents/pm-agent.md) - ⏳ Implementation pending (Core components) - ⏳ Serena MCP integration pending Salvaged from mistaken development in ~/.claude directory Related: #pm-agent-mode #session-lifecycle #pdca-cycle #phase-2 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * fix: disable Serena MCP auto-browser launch Disable web dashboard and GUI log window auto-launch in Serena MCP server to prevent intrusive browser popups on startup. Users can still manually access the dashboard at http://localhost:24282/dashboard/ if needed. Changes: - Add CLI flags to Serena run command: - --enable-web-dashboard false - --enable-gui-log-window false - Ensures Git-tracked configuration (no reliance on ~/.serena/serena_config.yml) - Aligns with AIRIS MCP Gateway integration approach 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * refactor: rename directories to lowercase for PEP8 compliance - Rename superclaude/Agents -> superclaude/agents - Rename superclaude/Commands -> superclaude/commands - Rename superclaude/Core -> superclaude/core - Rename superclaude/Examples -> superclaude/examples - Rename superclaude/MCP -> superclaude/mcp - Rename superclaude/Modes -> superclaude/modes This change follows Python PEP8 naming conventions for package directories. * style: fix PEP8 violations and update package name to lowercase Changes: - Format all Python files with black (43 files reformatted) - Update package name from 'SuperClaude' to 'superclaude' in pyproject.toml - Fix import statements to use lowercase package name - Add missing imports (timedelta, __version__) - Remove old SuperClaude.egg-info directory PEP8 violations reduced from 2672 to 701 (mostly E501 line length due to black's 88 char vs flake8's 79 char limit). * docs: add PM Agent development documentation Add comprehensive PM Agent development documentation: - PM Agent ideal workflow (7-phase autonomous cycle) - Project structure understanding (Git vs installed environment) - Installation flow understanding (CommandsComponent behavior) - Task management system (current-tasks.md) Purpose: Eliminate repeated explanations and enable autonomous PDCA cycles 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(pm-agent): add self-correcting execution and warning investigation culture ## Changes ### superclaude/commands/pm.md - Add "Self-Correcting Execution" section with root cause analysis protocol - Add "Warning/Error Investigation Culture" section enforcing zero-tolerance for dismissal - Define error detection protocol: STOP → Investigate → Hypothesis → Different Solution → Execute - Document anti-patterns (retry without understanding) and correct patterns (research-first) ### docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md - Add PDCA workflow hypothesis document for PM Agent autonomous enhancement ## Rationale PM Agent must never retry failed operations without understanding root causes. All warnings and errors require investigation via context7/WebFetch/documentation to ensure production-quality code and prevent technical debt accumulation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> * feat(installer): add airis-mcp-gateway MCP server option ## Changes - Add airis-mcp-gateway to MCP server options in installer - Configuration: GitHub-based installation via uvx - Repository: https://github.com/oraios/airis-mcp-gateway - Purpose: Dynamic MCP Gateway for zero-token baseline and on-demand tool loading ## Implementation Added to setup/components/mcp.py self.mcp_servers dictionary with: - install_method: github - install_command: uvx test installation - run_command: uvx runtime execution - required: False (optional server) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com> --------- Co-authored-by: kazuki <kazuki@kazukinoMacBook-Air.local> Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
kazuki nakai
378
docs/Development/installation-flow-understanding.md
Normal file
378
docs/Development/installation-flow-understanding.md
Normal file
@@ -0,0 +1,378 @@
|
||||
# SuperClaude Installation Flow - Complete Understanding
|
||||
|
||||
> **学習内容**: インストーラーがどうやって `~/.claude/` にファイルを配置するかの完全理解
|
||||
|
||||
---
|
||||
|
||||
## 🔄 インストールフロー全体像
|
||||
|
||||
### ユーザー操作
|
||||
```bash
|
||||
# Step 1: パッケージインストール
|
||||
pipx install SuperClaude
|
||||
# または
|
||||
npm install -g @bifrost_inc/superclaude
|
||||
|
||||
# Step 2: セットアップ実行
|
||||
SuperClaude install
|
||||
```
|
||||
|
||||
### 内部処理の流れ
|
||||
|
||||
```yaml
|
||||
1. Entry Point:
|
||||
File: superclaude/__main__.py → main()
|
||||
|
||||
2. CLI Parser:
|
||||
File: superclaude/__main__.py → create_parser()
|
||||
Command: "install" サブコマンド登録
|
||||
|
||||
3. Component Manager:
|
||||
File: setup/cli/install.py
|
||||
Role: インストールコンポーネントの調整
|
||||
|
||||
4. Commands Component:
|
||||
File: setup/components/commands.py → CommandsComponent
|
||||
Role: スラッシュコマンドのインストール
|
||||
|
||||
5. Source Files:
|
||||
Location: superclaude/commands/*.md
|
||||
Content: pm.md, implement.md, test.md, etc.
|
||||
|
||||
6. Destination:
|
||||
Location: ~/.claude/commands/sc/*.md
|
||||
Result: ユーザー環境に配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 CommandsComponent の詳細
|
||||
|
||||
### クラス構造
|
||||
```python
|
||||
class CommandsComponent(Component):
|
||||
"""
|
||||
Role: スラッシュコマンドのインストール・管理
|
||||
Parent: setup/core/base.py → Component
|
||||
Install Path: ~/.claude/commands/sc/
|
||||
"""
|
||||
```
|
||||
|
||||
### 主要メソッド
|
||||
|
||||
#### 1. `__init__()`
|
||||
```python
|
||||
def __init__(self, install_dir: Optional[Path] = None):
|
||||
super().__init__(install_dir, Path("commands/sc"))
|
||||
```
|
||||
**理解**:
|
||||
- `install_dir`: `~/.claude/` （ユーザー環境）
|
||||
- `Path("commands/sc")`: サブディレクトリ指定
|
||||
- 結果: `~/.claude/commands/sc/` にインストール
|
||||
|
||||
#### 2. `_get_source_dir()`
|
||||
```python
|
||||
def _get_source_dir(self) -> Path:
|
||||
# setup/components/commands.py の位置から計算
|
||||
project_root = Path(__file__).parent.parent.parent
|
||||
# → ~/github/SuperClaude_Framework/
|
||||
|
||||
return project_root / "superclaude" / "commands"
|
||||
# → ~/github/SuperClaude_Framework/superclaude/commands/
|
||||
```
|
||||
|
||||
**理解**:
|
||||
```
|
||||
Source: ~/github/SuperClaude_Framework/superclaude/commands/*.md
|
||||
Target: ~/.claude/commands/sc/*.md
|
||||
|
||||
つまり:
|
||||
superclaude/commands/pm.md
|
||||
↓ コピー
|
||||
~/.claude/commands/sc/pm.md
|
||||
```
|
||||
|
||||
#### 3. `_install()` - インストール実行
|
||||
```python
|
||||
def _install(self, config: Dict[str, Any]) -> bool:
|
||||
self.logger.info("Installing SuperClaude command definitions...")
|
||||
|
||||
# 既存コマンドのマイグレーション
|
||||
self._migrate_existing_commands()
|
||||
|
||||
# 親クラスのインストール実行
|
||||
return super()._install(config)
|
||||
```
|
||||
|
||||
**理解**:
|
||||
1. ログ出力
|
||||
2. 旧バージョンからの移行処理
|
||||
3. 実際のファイルコピー（親クラスで実行）
|
||||
|
||||
#### 4. `_migrate_existing_commands()` - マイグレーション
|
||||
```python
|
||||
def _migrate_existing_commands(self) -> None:
|
||||
"""
|
||||
旧Location: ~/.claude/commands/*.md
|
||||
新Location: ~/.claude/commands/sc/*.md
|
||||
|
||||
V3 → V4 移行時の処理
|
||||
"""
|
||||
old_commands_dir = self.install_dir / "commands"
|
||||
new_commands_dir = self.install_dir / "commands" / "sc"
|
||||
|
||||
# 旧場所からファイル検出
|
||||
# 新場所へコピー
|
||||
# 旧場所から削除
|
||||
```
|
||||
|
||||
**理解**:
|
||||
- V3: `/analyze` → V4: `/sc:analyze`
|
||||
- 名前空間衝突を防ぐため `/sc:` プレフィックス
|
||||
|
||||
#### 5. `_post_install()` - メタデータ更新
|
||||
```python
|
||||
def _post_install(self) -> bool:
|
||||
# メタデータ更新
|
||||
metadata_mods = self.get_metadata_modifications()
|
||||
self.settings_manager.update_metadata(metadata_mods)
|
||||
|
||||
# コンポーネント登録
|
||||
self.settings_manager.add_component_registration(
|
||||
"commands",
|
||||
{
|
||||
"version": __version__,
|
||||
"category": "commands",
|
||||
"files_count": len(self.component_files),
|
||||
},
|
||||
)
|
||||
```
|
||||
|
||||
**理解**:
|
||||
- `~/.claude/.superclaude.json` 更新
|
||||
- インストール済みコンポーネント記録
|
||||
- バージョン管理
|
||||
|
||||
---
|
||||
|
||||
## 📋 実際のファイルマッピング
|
||||
|
||||
### Source（このプロジェクト）
|
||||
```
|
||||
~/github/SuperClaude_Framework/superclaude/commands/
|
||||
├── pm.md # PM Agent定義
|
||||
├── implement.md # Implement コマンド
|
||||
├── test.md # Test コマンド
|
||||
├── analyze.md # Analyze コマンド
|
||||
├── research.md # Research コマンド
|
||||
├── ...（全26コマンド）
|
||||
```
|
||||
|
||||
### Destination（ユーザー環境）
|
||||
```
|
||||
~/.claude/commands/sc/
|
||||
├── pm.md # → /sc:pm で実行可能
|
||||
├── implement.md # → /sc:implement で実行可能
|
||||
├── test.md # → /sc:test で実行可能
|
||||
├── analyze.md # → /sc:analyze で実行可能
|
||||
├── research.md # → /sc:research で実行可能
|
||||
├── ...（全26コマンド）
|
||||
```
|
||||
|
||||
### Claude Code動作
|
||||
```
|
||||
User: /sc:pm "Build authentication"
|
||||
|
||||
Claude Code:
|
||||
1. ~/.claude/commands/sc/pm.md 読み込み
|
||||
2. YAML frontmatter 解析
|
||||
3. Markdown本文を展開
|
||||
4. PM Agent として実行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 他のコンポーネント
|
||||
|
||||
### Modes Component
|
||||
```python
|
||||
File: setup/components/modes.py
|
||||
Source: superclaude/modes/*.md
|
||||
Target: ~/.claude/*.md
|
||||
|
||||
Example:
|
||||
superclaude/modes/MODE_Brainstorming.md
|
||||
↓
|
||||
~/.claude/MODE_Brainstorming.md
|
||||
```
|
||||
|
||||
### Agents Component
|
||||
```python
|
||||
File: setup/components/agents.py
|
||||
Source: superclaude/agents/*.md
|
||||
Target: ~/.claude/agents/*.md（または統合先）
|
||||
```
|
||||
|
||||
### Core Component
|
||||
```python
|
||||
File: setup/components/core.py
|
||||
Source: superclaude/core/CLAUDE.md
|
||||
Target: ~/.claude/CLAUDE.md
|
||||
|
||||
これがグローバル設定！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💡 開発時の注意点
|
||||
|
||||
### ✅ 正しい変更方法
|
||||
```bash
|
||||
# 1. ソースファイルを変更（Git管理）
|
||||
cd ~/github/SuperClaude_Framework
|
||||
vim superclaude/commands/pm.md
|
||||
|
||||
# 2. テスト追加
|
||||
Write tests/test_pm_command.py
|
||||
|
||||
# 3. テスト実行
|
||||
pytest tests/test_pm_command.py -v
|
||||
|
||||
# 4. コミット
|
||||
git add superclaude/commands/pm.md tests/
|
||||
git commit -m "feat: enhance PM command"
|
||||
|
||||
# 5. 開発版インストール
|
||||
pip install -e .
|
||||
# または
|
||||
SuperClaude install --dev
|
||||
|
||||
# 6. 動作確認
|
||||
claude
|
||||
/sc:pm "test"
|
||||
```
|
||||
|
||||
### ❌ 間違った変更方法
|
||||
```bash
|
||||
# ダメ！Git管理外を直接変更
|
||||
vim ~/.claude/commands/sc/pm.md
|
||||
|
||||
# 変更は次回インストール時に上書きされる
|
||||
SuperClaude install # ← 変更が消える！
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 PM Mode改善の正しいフロー
|
||||
|
||||
### Phase 1: 理解（今ここ！）
|
||||
```bash
|
||||
✅ setup/components/commands.py 理解完了
|
||||
✅ superclaude/commands/*.md の存在確認完了
|
||||
✅ インストールフロー理解完了
|
||||
```
|
||||
|
||||
### Phase 2: 現在の仕様確認
|
||||
```bash
|
||||
# ソース確認（Git管理）
|
||||
Read superclaude/commands/pm.md
|
||||
|
||||
# インストール後確認（参考用）
|
||||
Read ~/.claude/commands/sc/pm.md
|
||||
|
||||
# 「なるほど、こういう仕様になってるのか」
|
||||
```
|
||||
|
||||
### Phase 3: 改善案作成
|
||||
```bash
|
||||
# このプロジェクト内で（Git管理）
|
||||
Write docs/Development/hypothesis-pm-enhancement-2025-10-14.md
|
||||
|
||||
内容:
|
||||
- 現状の問題（ドキュメント寄りすぎ、PMO機能不足）
|
||||
- 改善案（自律的PDCA、自己評価）
|
||||
- 実装方針
|
||||
- 期待される効果
|
||||
```
|
||||
|
||||
### Phase 4: 実装
|
||||
```bash
|
||||
# ソースファイル修正
|
||||
Edit superclaude/commands/pm.md
|
||||
|
||||
変更例:
|
||||
- PDCA自動実行の強化
|
||||
- docs/ ディレクトリ活用の明示
|
||||
- 自己評価ステップの追加
|
||||
- エラー時再学習フローの追加
|
||||
```
|
||||
|
||||
### Phase 5: テスト・検証
|
||||
```bash
|
||||
# テスト追加
|
||||
Write tests/test_pm_enhanced.py
|
||||
|
||||
# テスト実行
|
||||
pytest tests/test_pm_enhanced.py -v
|
||||
|
||||
# 開発版インストール
|
||||
SuperClaude install --dev
|
||||
|
||||
# 実際に使ってみる
|
||||
claude
|
||||
/sc:pm "test enhanced workflow"
|
||||
```
|
||||
|
||||
### Phase 6: 学習記録
|
||||
```bash
|
||||
# 成功パターン記録
|
||||
Write docs/patterns/pm-autonomous-workflow.md
|
||||
|
||||
# 失敗があれば記録
|
||||
Write docs/mistakes/mistake-2025-10-14.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Component間の依存関係
|
||||
|
||||
```yaml
|
||||
Commands Component:
|
||||
depends_on: ["core"]
|
||||
|
||||
Core Component:
|
||||
provides:
|
||||
- ~/.claude/CLAUDE.md（グローバル設定）
|
||||
- 基本ディレクトリ構造
|
||||
|
||||
Modes Component:
|
||||
depends_on: ["core"]
|
||||
provides:
|
||||
- ~/.claude/MODE_*.md
|
||||
|
||||
Agents Component:
|
||||
depends_on: ["core"]
|
||||
provides:
|
||||
- エージェント定義
|
||||
|
||||
MCP Component:
|
||||
depends_on: ["core"]
|
||||
provides:
|
||||
- MCPサーバー設定
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 次のアクション
|
||||
|
||||
理解完了！次は：
|
||||
|
||||
1. ✅ `superclaude/commands/pm.md` の現在の仕様確認
|
||||
2. ✅ 改善提案ドキュメント作成
|
||||
3. ✅ 実装修正（PDCA強化、PMO機能追加）
|
||||
4. ✅ テスト追加・実行
|
||||
5. ✅ 動作確認
|
||||
6. ✅ 学習記録
|
||||
|
||||
このドキュメント自体が**インストールフローの完全理解記録**として機能する。
|
||||
次回のセッションで読めば、同じ説明を繰り返さなくて済む。
|
||||
Reference in New Issue
Block a user