kazuki nakai 050d5ea2ab
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-10-14 08:47:09 +05:30

20 KiB
Raw Blame History

SuperClaude コマンドガイド

/sc:*SuperClaude は、ワークフロー用コマンドと@agent-*スペシャリスト用コマンドの 21 個の Claude Code コマンドを提供します。

コマンドの種類

タイプ 使用場所 形式
スラッシュコマンド クロード・コード /sc:[command] /sc:implement "feature"
エージェント クロード・コード @agent-[name] @agent-security "review"
インストール ターミナル SuperClaude [command] SuperClaude install

クイックテスト

# Terminal: Verify installation
python3 -m SuperClaude --version
# Claude Code CLI verification: claude --version

# Claude Code: Test commands
/sc:brainstorm "test project"    # Should ask discovery questions
/sc:analyze README.md           # Should provide analysis

ワークフロー/sc:brainstorm "idea"→→/sc:implement "feature"/sc:test

🎯 SuperClaude コマンドの理解

SuperClaudeの仕組み

SuperClaude は、Claude Code が特殊な動作を実行するために読み込む動作コンテキストファイルを提供します。 と入力すると/sc:implement、Claude Code はimplement.mdコンテキストファイルを読み込み、その動作指示に従います。

SuperClaude コマンドはソフトウェアによって実行されるのではなく、フレームワークから特殊な命令ファイルを読み取ることで Claude コードの動作を変更するコンテキスト トリガーです。

コマンドの種類:

  • スラッシュコマンド/sc:*):ワークフローパターンと動作​​モードをトリガーする
  • エージェントの呼び出し@agent-*):特定のドメインスペシャリストを手動で起動する
  • フラグ--think--safe-mode):コマンドの動作と深さを変更する

コンテキストメカニズム:

  1. ユーザー入力: 入力する/sc:implement "auth system"
  2. コンテキスト読み込み: クロードコード読み取り~/.claude/superclaude/Commands/implement.md
  3. 行動の採用:クロードはドメインの専門知識、ツールの選択、検証パターンを適用します
  4. 強化された出力: セキュリティ上の考慮事項とベストプラクティスを備えた構造化された実装

重要なポイント: これにより、従来のソフトウェア実行ではなくコンテキスト管理を通じて洗練された開発ワークフローが作成されます。

インストールコマンドと使用コマンド

🖥️ ターミナルコマンド(実際の CLI ソフトウェア):

  • SuperClaude install- フレームワークコンポーネントをインストールします
  • SuperClaude update- 既存のインストールを更新します
  • SuperClaude uninstall- フレームワークのインストールを削除します
  • python3 -m SuperClaude --version- インストール状態を確認する

💬 クロード コード コマンド(コンテキスト トリガー):

  • /sc:brainstorm- 要件検出コンテキストをアクティブ化します
  • /sc:implement- 機能開発コンテキストをアクティブ化します
  • @agent-security- セキュリティスペシャリストのコンテキストをアクティブ化します
  • すべてのコマンドはClaude Codeチャットインターフェース内でのみ機能します

クイック スタート/sc:brainstorm "your project idea"→ /sc:implement "feature name"→を試して/sc:test、コア ワークフローを体験してください。

🧪 セットアップのテスト

🖥️ ターミナル検証(ターミナル/CMDで実行

# Verify SuperClaude is working (primary method)
python3 -m SuperClaude --version
# Example output: SuperClaude 4.1.5

# Claude Code CLI version check
claude --version

# Check installed components
python3 -m SuperClaude install --list-components | grep mcp
# Example output: Shows installed MCP components

💬 クロードコードテスト(クロードコードチャットに入力)

# Test basic /sc: command
/sc:brainstorm "test project"
# Example behavior: Interactive requirements discovery starts

# Test command help
/sc:help
# Example behavior: List of available commands

テストが失敗した場合:インストールガイドまたはトラブルシューティングを確認してください

📝 コマンドクイックリファレンス

コマンドタイプ 走る場所 形式 目的
🖥️ インストール ターミナル/CMD SuperClaude [command] セットアップとメンテナンス SuperClaude install
🔧 構成 ターミナル/CMD python3 -m SuperClaude [command] 高度な設定 python3 -m SuperClaude --version
💬 スラッシュコマンド クロード・コード /sc:[command] ワークフロー自動化 /sc:implement "feature"
🤖 エージェントの呼び出し クロード・コード @agent-[name] 手動スペシャリストの有効化 @agent-security "review"
強化されたフラグ クロード・コード /sc:[command] --flags 行動修正 /sc:analyze --think-hard

注意:すべての/sc:コマンドと@agent-呼び出しは、ターミナルではなくClaude Codeチャット内で動作します。これらのコマンドと呼び出しは、Claude CodeがSuperClaudeフレームワークから特定のコンテキストファイルを読み取るようにトリガーします。

目次


必須コマンド

即時の生産性向上のためのコアワークフロー コマンド:

/sc:brainstorm- プロジェクト発見

目的: 対話型の要件検出とプロジェクト計画
構文:/sc:brainstorm "your idea" [--strategy systematic|creative]

ユースケース:

  • 新しいプロジェクトの計画:/sc:brainstorm "e-commerce platform"
  • 機能の探索:/sc:brainstorm "user authentication system"
  • 問題解決:/sc:brainstorm "slow database queries"

/sc:implement- 機能開発

目的: インテリジェントなスペシャリストルーティングによるフルスタック機能の実装
構文:/sc:implement "feature description" [--type frontend|backend|fullstack] [--focus security|performance]

ユースケース:

  • 認証:/sc:implement "JWT login system"
  • UI コンポーネント:/sc:implement "responsive dashboard"
  • API:/sc:implement "REST user endpoints"
  • データベース:/sc:implement "user schema with relationships"

/sc:analyze- コード評価

目的: 品質、セキュリティ、パフォーマンスにわたる包括的なコード分析
構文:/sc:analyze [path] [--focus quality|security|performance|architecture]

ユースケース:

  • プロジェクトの健全性:/sc:analyze .
  • セキュリティ監査:/sc:analyze --focus security
  • パフォーマンスレビュー:/sc:analyze --focus performance

/sc:troubleshoot- 問題診断

目的: 根本原因分析による体系的な問題診断
構文:/sc:troubleshoot "issue description" [--type build|runtime|performance]

ユースケース:

  • ランタイムエラー:/sc:troubleshoot "500 error on login"
  • ビルドの失敗:/sc:troubleshoot --type build
  • パフォーマンスの問題:/sc:troubleshoot "slow page load"

/sc:test- 品質保証

目的: カバレッジ分析による包括的なテスト
構文:/sc:test [--type unit|integration|e2e] [--coverage] [--fix]

ユースケース:

  • 完全なテストスイート:/sc:test --coverage
  • ユニットテスト:/sc:test --type unit --watch
  • E2E検証:/sc:test --type e2e

/sc:improve- コード強化

目的: 体系的なコードの改善と最適化を適用する
構文:/sc:improve [path] [--type performance|quality|security] [--preview]

ユースケース:

  • 一般的な改善点:/sc:improve src/
  • パフォーマンスの最適化:/sc:improve --type performance
  • セキュリティ強化:/sc:improve --type security

/sc:document- ドキュメント生成

目的: コードとAPIの包括的なドキュメントを生成する
構文:/sc:document [path] [--type api|user-guide|technical] [--format markdown|html]

ユースケース:

  • APIドキュメント:/sc:document --type api
  • ユーザーガイド:/sc:document --type user-guide
  • 技術ドキュメント:/sc:document --type technical

/sc:workflow- 実装計画

目的: 要件から構造化された実装計画を生成する
構文:/sc:workflow "feature description" [--strategy agile|waterfall] [--format markdown]

ユースケース:

  • 機能計画:/sc:workflow "user authentication"
  • スプリント計画:/sc:workflow --strategy agile
  • アーキテクチャ計画:/sc:workflow "microservices migration"

一般的なワークフロー

実証済みのコマンドの組み合わせ:

新しいプロジェクトのセットアップ

/sc:brainstorm "project concept"      # Define requirements
/sc:design "system architecture"      # Create technical design  
/sc:workflow "implementation plan"    # Generate development roadmap

機能開発

/sc:implement "feature name"          # Build the feature
/sc:test --coverage                   # Validate with tests
/sc:document --type api               # Generate documentation  

コード品質の改善

/sc:analyze --focus quality           # Assess current state
/sc:improve --preview                 # Preview improvements
/sc:test --coverage                   # Validate changes

バグ調査

/sc:troubleshoot "issue description"  # Diagnose the problem
/sc:analyze --focus problem-area      # Deep analysis
/sc:improve --fix --safe-mode         # Apply targeted fixes

完全なコマンドリファレンス

開発コマンド

指示 目的 最適な用途
ワークフロー 実施計画 プロジェクトロードマップ、スプリント計画
埋め込む 機能開発 フルスタック機能、API開発
建てる プロジェクトのコンパイル CI/CD、プロダクションビルド
デザイン システムアーキテクチャ API仕様、データベーススキーマ

分析コマンド

指示 目的 最適な用途
分析する コード評価 品質監査、セキュリティレビュー
トラブルシューティング 問題診断 バグ調査、パフォーマンスの問題
説明する コードの説明 学習、コードレビュー

品質コマンド

指示 目的 最適な用途
改善する コード強化 パフォーマンスの最適化、リファクタリング
掃除 技術的負債 デッドコードの削除、整理
テスト 品質保証 テスト自動化、カバレッジ分析
書類 ドキュメント APIドキュメント、ユーザーガイド

プロジェクト管理

指示 目的 最適な用途
見積もり プロジェクト見積もり タイムライン計画、リソース割り当て
タスク タスク管理 複雑なワークフロー、タスク追跡
スポーン メタオーケストレーション 大規模プロジェクト、並列実行

ユーティリティコマンド

指示 目的 最適な用途
ギット バージョン管理 コミット管理、ブランチ戦略
索引 コマンド検出 機能の探索、コマンドの検索

セッションコマンド

指示 目的 最適な用途
負荷 コンテキストの読み込み セッションの初期化、プロジェクトのオンボーディング
保存 セッションの永続性 チェックポイント、コンテキスト保存
反映する タスクの検証 進捗評価、完了検証
選択ツール ツールの最適化 パフォーマンスの最適化、ツールの選択

コマンドインデックス

機能別:

  • 計画:ブレインストーミング、設計、ワークフロー、見積もり
  • 開発実装、ビルド、git
  • 分析:分析、トラブルシューティング、説明
  • 品質: 改善、クリーンアップ、テスト、ドキュメント化
  • 管理: タスク、スポーン、ロード、保存、反映
  • ユーティリティ: インデックス、選択ツール

複雑さ別:

  • 初心者:ブレインストーミング、実装、分析、テスト
  • 中級:ワークフロー、設計、改善、ドキュメント
  • 上級:スポーン、タスク、選択ツール、リフレクト

トラブルシューティング

コマンドの問題:

  • コマンドが見つかりません: インストールを確認してください:python3 -m SuperClaude --version
  • 応答なし: Claude Codeセッションを再開する
  • 処理遅延--no-mcpMCPサーバーなしでテストするために使用します

クイックフィックス:

次のステップ