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>
2025-12-29 16:16:08 +00:00 · 2025-10-14 12:17:09 +09:00
parent 302c5851b1
commit 050d5ea2ab
194 changed files with 9698 additions and 3693 deletions
--- a/docs/Development/pm-agent-ideal-workflow.md
+++ b/docs/Development/pm-agent-ideal-workflow.md
@@ -0,0 +1,341 @@
+# PM Agent - Ideal Autonomous Workflow
+
+> **目的**: 何百回も同じ指示を繰り返さないための自律的オーケストレーションシステム
+
+## 🎯 解決すべき問題
+
+### 現状の課題
+- **繰り返し指示**: 同じことを何百回も説明している
+- **同じミスの反復**: 一度間違えたことを再度間違える
+- **知識の喪失**: セッションが途切れると学習内容が失われる
+- **コンテキスト制限**: 限られたコンテキストで効率的に動作できていない
+
+### あるべき姿
+**自律的で賢いPM Agent** - ドキュメントから学び、計画し、実行し、検証し、学習を記録するループ
+
+---
+
+## 📋 完璧なワークフロー（理想形）
+
+### Phase 1: 📖 状況把握（Context Restoration）
+
+```yaml
+1. ドキュメント読み込み:
+   優先順位:
+     1. タスク管理ドキュメント → 進捗確認
+        - docs/Development/tasks/current-tasks.md
+        - 前回どこまでやったか
+        - 次に何をすべきか
+
+     2. アーキテクチャドキュメント → 仕組み理解
+        - docs/Development/architecture-*.md
+        - このプロジェクトの構造
+        - インストールフロー
+        - コンポーネント連携
+
+     3. 禁止事項・ルール → 制約確認
+        - CLAUDE.md（グローバル）
+        - PROJECT/CLAUDE.md（プロジェクト固有）
+        - docs/Development/constraints.md
+
+     4. 過去の学び → 同じミスを防ぐ
+        - docs/mistakes/ （失敗記録）
+        - docs/patterns/ （成功パターン）
+
+2. ユーザーリクエスト理解:
+   - 何をしたいのか
+   - どこまで進んでいるのか
+   - 何が課題なのか
+```
+
+### Phase 2: 🔍 調査・分析（Research & Analysis）
+
+```yaml
+1. 既存実装の理解:
+   # ソースコード側（Git管理）
+   - setup/components/*.py → インストールロジック
+   - superclaude/ → ランタイムロジック
+   - tests/ → テストパターン
+
+   # インストール後（ユーザー環境・Git管理外）
+   - ~/.claude/commands/sc/ → 実際の配置確認
+   - ~/.claude/*.md → 現在の仕様確認
+
+   理解内容:
+   「なるほど、ここでこう処理されて、
+    こういうファイルが ~/.claude/ に作られるのね」
+
+2. ベストプラクティス調査:
+   # Deep Research活用
+   - 公式リファレンス確認
+   - 他プロジェクトの実装調査
+   - 最新のベストプラクティス
+
+   気づき:
+   - 「ここ無駄だな」
+   - 「ここ古いな」
+   - 「これはいい実装だな」
+   - 「この共通化できるな」
+
+3. 重複・改善ポイント発見:
+   - ライブラリの共通化可能性
+   - 重複実装の検出
+   - コード品質向上余地
+```
+
+### Phase 3: 📝 計画立案（Planning）
+
+```yaml
+1. 改善仮説作成:
+   # このプロジェクト内で（Git管理）
+   File: docs/Development/hypothesis-YYYY-MM-DD.md
+
+   内容:
+   - 現状の問題点
+   - 改善案
+   - 期待される効果（トークン削減、パフォーマンス向上等）
+   - 実装方針
+   - 必要なテスト
+
+2. ユーザーレビュー:
+   「こういうプランでこんなことをやろうと思っています」
+
+   提示内容:
+   - 調査結果のサマリー
+   - 改善提案（理由付き）
+   - 実装ステップ
+   - 期待される成果
+
+   ユーザー承認待ち → OK出たら実装へ
+```
+
+### Phase 4: 🛠️ 実装（Implementation）
+
+```yaml
+1. ソースコード修正:
+   # Git管理されているこのプロジェクトで作業
+   cd ~/github/SuperClaude_Framework
+
+   修正対象:
+   - setup/components/*.py → インストールロジック
+   - superclaude/ → ランタイム機能
+   - setup/data/*.json → 設定データ
+
+   # サブエージェント活用
+   - backend-architect: アーキテクチャ実装
+   - refactoring-expert: コード改善
+   - quality-engineer: テスト設計
+
+2. 実装記録:
+   File: docs/Development/experiment-YYYY-MM-DD.md
+
+   内容:
+   - 試行錯誤の記録
+   - 遭遇したエラー
+   - 解決方法
+   - 気づき
+```
+
+### Phase 5: ✅ 検証（Validation）
+
+```yaml
+1. テスト作成・実行:
+   # テストを書く
+   Write tests/test_new_feature.py
+
+   # テスト実行
+   pytest tests/test_new_feature.py -v
+
+   # ユーザー要求を満たしているか確認
+   - 期待通りの動作か？
+   - エッジケースは？
+   - パフォーマンスは？
+
+2. エラー時の対応:
+   エラー発生
+   ↓
+   公式リファレンス確認
+   「このエラー何でだろう？」
+   「ここの定義違ってたんだ」
+   ↓
+   修正
+   ↓
+   再テスト
+   ↓
+   合格まで繰り返し
+
+3. 動作確認:
+   # インストールして実際の環境でテスト
+   SuperClaude install --dev
+
+   # 動作確認
+   claude  # 起動して実際に試す
+```
+
+### Phase 6: 📚 学習記録（Learning Documentation）
+
+```yaml
+1. 成功パターン記録:
+   File: docs/patterns/[pattern-name].md
+
+   内容:
+   - どんな問題を解決したか
+   - どう実装したか
+   - なぜこのアプローチか
+   - 再利用可能なパターン
+
+2. 失敗・ミス記録:
+   File: docs/mistakes/mistake-YYYY-MM-DD.md
+
+   内容:
+   - どんなミスをしたか
+   - なぜ起きたか
+   - 防止策
+   - チェックリスト
+
+3. タスク更新:
+   File: docs/Development/tasks/current-tasks.md
+
+   内容:
+   - 完了したタスク
+   - 次のタスク
+   - 進捗状況
+   - ブロッカー
+
+4. グローバルパターン更新:
+   必要に応じて:
+   - CLAUDE.md更新（グローバルルール）
+   - PROJECT/CLAUDE.md更新（プロジェクト固有）
+```
+
+### Phase 7: 🔄 セッション保存（Session Persistence）
+
+```yaml
+1. Serenaメモリー保存:
+   write_memory("session_summary", 完了内容)
+   write_memory("next_actions", 次のアクション)
+   write_memory("learnings", 学んだこと)
+
+2. ドキュメント整理:
+   - docs/temp/ → docs/patterns/ or docs/mistakes/
+   - 一時ファイル削除
+   - 正式ドキュメント更新
+```
+
+---
+
+## 🔧 活用可能なツール・リソース
+
+### MCPサーバー（フル活用）
+- **Sequential**: 複雑な分析・推論
+- **Context7**: 公式ドキュメント参照
+- **Tavily**: Deep Research（ベストプラクティス調査）
+- **Serena**: セッション永続化、メモリー管理
+- **Playwright**: E2Eテスト、動作確認
+- **Morphllm**: 一括コード変換
+- **Magic**: UI生成（必要時）
+- **Chrome DevTools**: パフォーマンス測定
+
+### サブエージェント（適材適所）
+- **requirements-analyst**: 要件整理
+- **system-architect**: アーキテクチャ設計
+- **backend-architect**: バックエンド実装
+- **refactoring-expert**: コード改善
+- **security-engineer**: セキュリティ検証
+- **quality-engineer**: テスト設計・実行
+- **performance-engineer**: パフォーマンス最適化
+- **technical-writer**: ドキュメント執筆
+
+### 他プロジェクト統合
+- **makefile-global**: Makefile標準化パターン
+- **airis-mcp-gateway**: MCPゲートウェイ統合
+- その他有用なパターンは積極的に取り込む
+
+---
+
+## 🎯 重要な原則
+
+### Git管理の区別
+```yaml
+✅ Git管理されている（変更追跡可能）:
+  - ~/github/SuperClaude_Framework/
+  - ここで全ての変更を行う
+  - コミット履歴で追跡
+  - PR提出可能
+
+❌ Git管理外（変更追跡不可）:
+  - ~/.claude/
+  - 読むだけ、理解のみ
+  - テスト時のみ一時変更（必ず戻す！）
+```
+
+### テスト時の注意
+```bash
+# テスト前: 必ずバックアップ
+cp ~/.claude/commands/sc/pm.md ~/.claude/commands/sc/pm.md.backup
+
+# テスト実行
+# ... 検証 ...
+
+# テスト後: 必ず復元！！
+mv ~/.claude/commands/sc/pm.md.backup ~/.claude/commands/sc/pm.md
+```
+
+### ドキュメント構造
+```
+docs/
+├── Development/          # 開発用ドキュメント
+│   ├── tasks/           # タスク管理
+│   ├── architecture-*.md # アーキテクチャ
+│   ├── constraints.md   # 制約・禁止事項
+│   ├── hypothesis-*.md  # 改善仮説
+│   └── experiment-*.md  # 実験記録
+├── patterns/            # 成功パターン（清書後）
+├── mistakes/            # 失敗記録と防止策
+└── (既存のUser-Guide等)
+```
+
+---
+
+## 🚀 実装優先度
+
+### Phase 1（必須）
+1. ドキュメント構造整備
+2. タスク管理システム
+3. セッション復元ワークフロー
+
+### Phase 2（重要）
+4. 自己評価・検証ループ
+5. 学習記録自動化
+6. エラー時再学習フロー
+
+### Phase 3（強化）
+7. PMO機能（重複検出、共通化提案）
+8. パフォーマンス測定・改善
+9. 他プロジェクト統合
+
+---
+
+## 📊 成功指標
+
+### 定量的指標
+- **繰り返し指示の削減**: 同じ指示 → 50%削減目標
+- **ミス再発率**: 同じミス → 80%削減目標
+- **セッション復元時間**: <30秒で前回の続きから開始
+
+### 定性的指標
+- ユーザーが「前回の続きから」と言うだけで再開できる
+- 過去のミスを自動的に避けられる
+- 公式ドキュメント参照が自動化されている
+- 実装→テスト→検証が自律的に回る
+
+---
+
+## 💡 次のアクション
+
+このドキュメント作成後:
+1. 既存のインストールロジック理解（setup/components/）
+2. タスク管理ドキュメント作成（docs/Development/tasks/）
+3. PM Agent実装修正（このワークフローを実際に実装）
+
+このドキュメント自体が**PM Agentの憲法**となる。