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>

docs/Development/hypothesis-pm-autonomous-enhancement-2025-10-14.md

@@ -0,0 +1,390 @@
+# PM Agent Autonomous Enhancement - 改善提案
+
+> **Date**: 2025-10-14
+> **Status**: 提案中（ユーザーレビュー待ち）
+> **Goal**: ユーザーインプット最小化 + 確信を持った先回り提案
+
+---
+
+## 🎯 現状の問題点
+
+### 既存の `superclaude/commands/pm.md`
+```yaml
+良い点:
+  ✅ PDCAサイクルが定義されている
+  ✅ サブエージェント連携が明確
+  ✅ ドキュメント記録の仕組みがある
+
+改善が必要な点:
+  ❌ ユーザーインプット依存度が高い
+  ❌ 調査フェーズが受動的
+  ❌ 提案が「どうしますか？」スタイル
+  ❌ 確信を持った提案がない
+```
+
+---
+
+## 💡 改善提案
+
+### Phase 0: **自律的調査フェーズ**（新規追加）
+
+#### ユーザーリクエスト受信時の自動実行
+```yaml
+Auto-Investigation (許可不要・自動実行):
+  1. Context Restoration:
+     - Read docs/Development/tasks/current-tasks.md
+     - list_memories() → 前回のセッション確認
+     - read_memory("project_context") → プロジェクト理解
+     - read_memory("past_mistakes") → 過去の失敗確認
+
+  2. Project Analysis:
+     - Read CLAUDE.md → プロジェクト固有ルール
+     - Glob **/*.md → ドキュメント構造把握
+     - mcp__serena__get_symbols_overview → コード構造理解
+     - Grep "TODO\|FIXME\|XXX" → 既知の課題確認
+
+  3. Current State Assessment:
+     - Bash "git status" → 現在の状態
+     - Bash "git log -5 --oneline" → 最近の変更
+     - Read tests/ → テストカバレッジ確認
+     - Security scan → セキュリティリスク確認
+
+  4. Competitive Research (必要時):
+     - tavily search → ベストプラクティス調査
+     - context7 → 公式ドキュメント参照
+     - Deep Research → 競合サービス分析
+
+  5. Architecture Evaluation:
+     - 既存アーキテクチャの強み分析
+     - 技術スタックの特徴把握
+     - 拡張可能性の評価
+```
+
+#### 出力形式
+```markdown
+📊 自律調査完了
+
+現状分析:
+  - プロジェクト: [名前]（[技術スタック]）
+  - 進捗: [前回セッションの続き or 新規タスク]
+  - コードベース: [ファイル数]、テストカバレッジ [%]
+  - 既知の課題: [TODO/FIXME数]
+  - 最近の変更: [git log要約]
+
+アーキテクチャの強み:
+  - [強み1]: [具体的な理由]
+  - [強み2]: [具体的な理由]
+
+不足している要素:
+  - [不足1]: [影響]
+  - [不足2]: [影響]
+```
+
+---
+
+### Phase 1: **確信を持った提案**（強化）
+
+#### ❌ 改善前（受動的）
+```
+User: "認証機能作って"
+
+PM Agent: "認証機能を実装しますね。
+          どんな認証方式がいいですか？"
+
+→ ユーザーに丸投げ
+```
+
+#### ✅ 改善後（能動的・確信あり）
+```
+User: "認証機能作って"
+
+PM Agent:
+  📊 自律調査完了（3秒）:
+     - 既存: Supabase統合済み（強み）
+     - 不足: 認証機能なし
+     - テスト: カバレッジ45%（目標80%）
+     - 競合調査: Auth0、Clerk、Supabase Auth比較済み
+     - セキュリティ: OWASP推奨3項目未対応
+
+  💡 確信を持った提案:
+
+     このアーキテクチャはSupabase連携に強みがあるため、
+     **Supabase Auth統合**を推奨します。
+
+     具体的な実装方針:
+     1. Supabase Auth統合（JWT + リフレッシュトークン）
+     2. MFA対応（TOTP実装）
+     3. セキュリティテスト追加（カバレッジ85%目標）
+     4. 既存APIとのシームレス統合
+
+     選択理由:
+     ✅ 既存のSupabase接続再利用（実装コスト最小）
+     ✅ エンタープライズグレードのセキュリティ
+     ✅ 無料枠で十分な機能（コスト効率◎）
+     ✅ 将来のスケーラビリティ確保
+
+     代替案との比較:
+     - Auth0: 月$25〜、実装複雑度高
+     - Clerk: 月$25〜、React特化（このプロジェクトはNext.js）
+     - Supabase Auth: 無料、既存統合済み ← 推奨
+
+     この方針で進めてよろしいですか？
+```
+
+---
+
+### Phase 2: **自律実行**（既存を強化）
+
+#### 承認後の自動フロー
+```yaml
+User: "OK"
+
+PM Agent（完全自律実行）:
+  1. Architecture Design:
+     - system-architect: Supabase Auth設計
+     - security-engineer: セキュリティレビュー
+
+  2. Implementation:
+     - backend-architect: API統合実装
+     - frontend-architect: UI実装
+     - Load magic: Login/Register components
+
+  3. Testing:
+     - Write tests/auth/*.test.ts
+     - pytest実行 → 失敗検出
+
+  4. Self-Correction:
+     - context7 → Supabase公式ドキュメント確認
+     - エラー原因特定: "JWTシークレット未設定"
+     - 修正実装
+     - 再テスト → 合格
+
+  5. Documentation:
+     - Update docs/patterns/supabase-auth-integration.md
+     - Update CLAUDE.md（認証パターン追加）
+     - write_memory("success_pattern", 詳細)
+
+  6. Report:
+     ✅ 認証機能実装完了
+
+     実装内容:
+     - Supabase Auth統合（JWT + リフレッシュ）
+     - MFA対応（TOTP）
+     - テストカバレッジ: 45% → 87%（目標達成）
+     - セキュリティ: OWASP準拠確認済み
+
+     学習記録:
+     - 成功パターン: docs/patterns/supabase-auth-integration.md
+     - 遭遇したエラー: JWT設定不足（修正済み）
+     - 次回の改善: 環境変数チェックリスト更新
+```
+
+---
+
+## 🔧 実装方針
+
+### `superclaude/commands/pm.md` への追加セクション
+
+#### 1. Autonomous Investigation Phase（新規）
+```markdown
+## Phase 0: Autonomous Investigation (Auto-Execute)
+
+**Trigger**: Any user request received
+
+**Execution**: Automatic, no permission required
+
+### Investigation Steps:
+1. **Context Restoration**
+   - Read `docs/Development/tasks/current-tasks.md`
+   - Serena memory restoration
+   - Project context loading
+
+2. **Project Analysis**
+   - CLAUDE.md → Project rules
+   - Code structure analysis
+   - Test coverage check
+   - Security scan
+   - Known issues detection (TODO/FIXME)
+
+3. **Competitive Research** (when relevant)
+   - Best practices research (Tavily)
+   - Official documentation (Context7)
+   - Alternative solutions analysis
+
+4. **Architecture Evaluation**
+   - Identify architectural strengths
+   - Detect technology stack characteristics
+   - Assess extensibility
+
+### Output Format:
+```
+📊 Autonomous Investigation Complete
+
+Current State:
+  - Project: [name] ([stack])
+  - Progress: [status]
+  - Codebase: [files count], Test Coverage: [%]
+  - Known Issues: [count]
+  - Recent Changes: [git log summary]
+
+Architectural Strengths:
+  - [strength 1]: [rationale]
+  - [strength 2]: [rationale]
+
+Missing Elements:
+  - [gap 1]: [impact]
+  - [gap 2]: [impact]
+```
+```
+
+#### 2. Confident Proposal Phase（強化）
+```markdown
+## Phase 1: Confident Proposal (Enhanced)
+
+**Principle**: Never ask "What do you want?" - Always propose with conviction
+
+### Proposal Format:
+```
+💡 Confident Proposal:
+
+[Implementation approach] is recommended.
+
+Specific Implementation Plan:
+1. [Step 1 with rationale]
+2. [Step 2 with rationale]
+3. [Step 3 with rationale]
+
+Selection Rationale:
+✅ [Reason 1]: [Evidence]
+✅ [Reason 2]: [Evidence]
+✅ [Reason 3]: [Evidence]
+
+Alternatives Considered:
+- [Alt 1]: [Why not chosen]
+- [Alt 2]: [Why not chosen]
+- [Recommended]: [Why chosen] ← Recommended
+
+Proceed with this approach?
+```
+
+### Anti-Patterns (Never Do):
+❌ "What authentication do you want?" (Passive)
+❌ "How should we implement this?" (Uncertain)
+❌ "There are several options..." (Indecisive)
+
+✅ "Supabase Auth is recommended because..." (Confident)
+✅ "Based on your architecture's Supabase integration..." (Evidence-based)
+```
+
+#### 3. Autonomous Execution Phase（既存を明示化）
+```markdown
+## Phase 2: Autonomous Execution
+
+**Trigger**: User approval ("OK", "Go ahead", "Yes")
+
+**Execution**: Fully autonomous, systematic PDCA
+
+### Self-Correction Loop:
+```yaml
+Implementation:
+  - Execute with sub-agents
+  - Write comprehensive tests
+  - Run validation
+
+Error Detected:
+  → Context7: Check official documentation
+  → Identify root cause
+  → Implement fix
+  → Re-test
+  → Repeat until passing
+
+Success:
+  → Document pattern (docs/patterns/)
+  → Update learnings (write_memory)
+  → Report completion with evidence
+```
+
+### Quality Gates:
+- Tests must pass (no exceptions)
+- Coverage targets must be met
+- Security checks must pass
+- Documentation must be updated
+```
+
+---
+
+## 📊 期待される効果
+
+### Before (現状)
+```yaml
+User Input Required: 高
+  - 認証方式の選択
+  - 実装方針の決定
+  - エラー対応の指示
+  - テスト方針の決定
+
+Proposal Quality: 受動的
+  - "どうしますか？"スタイル
+  - 選択肢の羅列のみ
+  - ユーザーが決定
+
+Execution: 半自動
+  - エラー時にユーザーに報告
+  - 修正方針をユーザーが指示
+```
+
+### After (改善後)
+```yaml
+User Input Required: 最小
+  - "認証機能作って"のみ
+  - 提案への承認/拒否のみ
+
+Proposal Quality: 能動的・確信あり
+  - 調査済みの根拠提示
+  - 明確な推奨案
+  - 代替案との比較
+
+Execution: 完全自律
+  - エラー自己修正
+  - 公式ドキュメント自動参照
+  - テスト合格まで自動実行
+  - 学習自動記録
+```
+
+### 定量的目標
+- ユーザーインプット削減: **80%削減**
+- 提案品質向上: **確信度90%以上**
+- 自律実行成功率: **95%以上**
+
+---
+
+## 🚀 実装ステップ
+
+### Step 1: pm.md 修正
+- [ ] Phase 0: Autonomous Investigation 追加
+- [ ] Phase 1: Confident Proposal 強化
+- [ ] Phase 2: Autonomous Execution 明示化
+- [ ] Examples セクションに具体例追加
+
+### Step 2: テスト作成
+- [ ] `tests/test_pm_autonomous.py`
+- [ ] 自律調査フローのテスト
+- [ ] 確信提案フォーマットのテスト
+- [ ] 自己修正ループのテスト
+
+### Step 3: 動作確認
+- [ ] 開発版インストール
+- [ ] 実際のワークフローで検証
+- [ ] フィードバック収集
+
+### Step 4: 学習記録
+- [ ] `docs/patterns/pm-autonomous-workflow.md`
+- [ ] 成功パターンの文書化
+
+---
+
+## ✅ ユーザー承認待ち
+
+**この方針で実装を進めてよろしいですか？**
+
+承認いただければ、すぐに `superclaude/commands/pm.md` の修正を開始します。