Merge pull request #4 from chippy-ao/docs/improve-yakuza-plugin-documentation

docs(multi-agent-yakuza): エージェント・スキルドキュメント改善

Author: chippy-ao

.claude-plugin/marketplace.json

@@ -8,6 +8,11 @@
       "name": "plan",
       "source": "./plan",
       "description": "質問で要件を深掘りしてからプランニングするスキルと、未完了計画のリマインダー hook を提供"
+    },
+    {
+      "name": "multi-agent-yakuza",
+      "source": "./multi-agent-yakuza",
+      "description": "Yakuza組織風の階層的マルチエージェントシステム。親父（ユーザー）の命令を若頭が受け取り、若頭補佐がタスク分解、若衆が並列実行。"
     }
   ]
 }

README.md

@@ -13,7 +13,11 @@ Claude Code 用のプラグイン集
 ### 2. プラグインをインストール
 
 ```bash
+# planプラグイン
 /plugin install plan@chippy-ao-plugins
+
+# multi-agent-yakuzaプラグイン
+/plugin install multi-agent-yakuza@chippy-ao-plugins
 ```
 
 ### 3. 確認
@@ -29,6 +33,7 @@ Claude Code 用のプラグイン集
 | プラグイン | 説明 |
 |------------|------|
 | [plan](./plan/) | 質問で要件を深掘りしてからプランニングするスキルと hook を提供 |
+| [multi-agent-yakuza](./multi-agent-yakuza/) | Yakuza組織風の階層的マルチエージェントシステム。親父の命令を頭が受け取り、補佐がタスク分解、若いのと叔父貴が並列実行 |
 
 ## 使い方
 
@@ -55,6 +60,26 @@ Claude Code 用のプラグイン集
 
 詳細は [plan/README.md](./plan/README.md) を参照。
 
+### multi-agent-yakuza
+
+Yakuza組織風のマルチエージェントシステム。
+
+```bash
+# 基本的な使用方法
+ログイン機能を実装して
+
+# 進捗確認
+/yakuza:status
+```
+
+**特徴**:
+- 完全縦型組織（親父 → 頭 → 補佐 → 若いの）
+- 専門エージェント（叔父貴）の自動探索・活用
+- 最大5人の若いの + 専門エージェントで並列実行
+- 呼称ルール（親父、頭、兄貴、叔父貴、若いの）
+
+詳細は [multi-agent-yakuza/README.md](./multi-agent-yakuza/README.md) を参照。
+
 ## ライセンス
 
 MIT

multi-agent-yakuza/.claude-plugin/plugin.json

@@ -0,0 +1,21 @@
+{
+  "name": "multi-agent-yakuza",
+  "version": "1.0.0",
+  "description": "Yakuza組織風の階層的マルチエージェントシステム。親父（ユーザー）の命令を若頭が受け取り、若頭補佐がタスク分解、若衆が並列実行。",
+  "author": {
+    "name": "chippy-ao"
+  },
+  "license": "MIT",
+  "keywords": [
+    "multi-agent",
+    "yakuza",
+    "parallel",
+    "task-management",
+    "hierarchical",
+    "delegation",
+    "workflow",
+    "orchestration",
+    "organization",
+    "automation"
+  ]
+}

multi-agent-yakuza/README.md

@@ -0,0 +1,309 @@
+# Multi-Agent Yakuza Plugin
+
+Yakuza組織風の階層的マルチエージェントシステム。親父（ユーザー）の命令を若頭が受け取り、若頭補佐がタスク分解、若衆と専門エージェント（叔父貴）が並列実行する完全縦型組織構造のプラグインです。
+
+## 組織構造
+
+```
+親父（ユーザー）
+  ↕
+頭（若頭/Kashira）- Skill実装、ユーザーとの会話窓口、エージェント起動
+  ↕
+補佐/兄貴（若頭補佐/Hosa）- Agent実装、タスク分解・計画立案
+  ↕
+若いの（若衆/Wakashu）×5 + 叔父貴（専門エージェント）- 実作業実行
+```
+
+### 完全縦型組織
+
+- 若衆は補佐（兄貴）とのみやり取り
+- 補佐は若頭（頭）とのみやり取り
+- 若頭は親父とのみやり取り
+- 階層を飛ばした連絡は一切なし
+
+### 呼称ルール
+
+| 役職 | 呼ばれ方 | 呼び方 |
+|------|----------|--------|
+| ユーザー | 親父 | - |
+| 若頭 | 頭 | 親父 / 補佐 / 若いの / 叔父貴 |
+| 若頭補佐 | 補佐（頭から）<br>兄貴（若衆から） | 親父 / 頭 / 若いの / 叔父貴 |
+| 若衆 | 若いの | 親父 / 頭 / 兄貴 / 叔父貴 |
+| カスタムエージェント | 叔父貴 | - |
+
+## プラグイン構成
+
+```
+multi-agent-yakuza/
+├── .claude-plugin/
+│   └── plugin.json              # プラグイン定義
+├── agents/
+│   ├── hosa.md                  # 若頭補佐エージェント
+│   └── wakashu.md               # 若衆エージェント
+├── skills/
+│   └── kashira/
+│       ├── README.md            # スキル説明
+│       └── SKILL.md             # 若頭スキル定義
+├── commands/
+│   └── status.md                # ステータス確認コマンド
+├── hooks/
+│   ├── hooks.json               # フック定義
+│   └── welcome.sh               # セッション開始時ウェルカムメッセージ
+└── README.md                    # このファイル
+```
+
+## コンポーネント
+
+### 頭（若頭/Kashira）- Skill
+
+**役割**: ユーザーとの窓口、タスク調整、エージェント起動
+
+親父（ユーザー）の命令を受け取り、若頭補佐にタスク分解を依頼し、実行計画に基づいてエージェントを並列起動します。専門エージェント探索は補佐が自動的に実施します。
+
+詳細は [skills/kashira/README.md](skills/kashira/README.md) を参照してください。
+
+**起動方法**:
+```
+ログイン機能を実装して
+```
+
+### 補佐/兄貴（若頭補佐/Hosa）- Agent
+
+**役割**: タスク分解・計画立案
+
+- 頭（若頭）からの指示を受け取る
+- **専門エージェント探索**（全スコープ）
+  - プロジェクトエージェント: `.claude/agents/`
+  - ユーザーエージェント: `~/.claude/agents/`
+  - プラグインエージェント: `.claude/plugins/*/agents/`, `~/.claude/plugins/*/agents/`
+- 利用可能な人材（若いの×5 + 叔父貴）を把握
+- タスクを分解（1〜5個）
+- 各サブタスクを適切な人材に割り当て
+  - 汎用作業 → `multi-agent-yakuza:wakashu`
+  - 通常の専門エージェント → `agent-name`
+  - プラグインエージェント → `plugin-name:agent-name`
+- **重要**: 実行計画をMarkdownで作成し、頭に返す（実際の Task 起動は若頭が行う）
+- エラー発生時は頭に報告し、再計画を提案
+
+**使用可能ツール**:
+- TaskCreate, TaskUpdate, TaskList, Glob, Grep, Read
+
+**重要な制約**:
+- Edit, Write, Bash, Task ツールは使えない
+  - 実装作業は若衆に任せる
+  - Task起動（エージェントの実行）は若頭が行う
+  - 補佐は計画立案とTaskCreate（タスク情報の記録）のみ
+
+**割り当て例**:
+```
+タスク1: コードレビュー → code-reviewer（叔父貴）
+タスク2: セキュリティ修正 → 若いの1
+タスク3: パフォーマンス改善 → 若いの2
+タスク4: リファクタリング → code-simplifier（叔父貴）
+タスク5: テスト追加 → 若いの3
+```
+
+### 若いの（若衆/Wakashu）- Agent
+
+**役割**: 実作業実行
+
+- 兄貴（若頭補佐）からの指示を受け取り、実際の作業を実行
+- コーディング、テスト、リファクタリング、バグ修正などをこなす
+- 作業完了後、結果を兄貴に報告（成功/失敗、実施内容）
+- 最大5人まで並列実行可能
+
+**使用可能ツール**:
+- Read, Edit, Write, Bash, Grep, Glob, WebFetch, WebSearch
+
+### 叔父貴（カスタムエージェント）
+
+**役割**: 専門作業実行
+
+- ユーザーが`.claude/agents/`や`~/.claude/agents/`、またはプラグインに配置したカスタムエージェント
+- 補佐が自動的に探索し、適切なタスクに割り当て
+- 若いのと組み合わせて並列実行可能
+- 専門性の高い作業を担当
+
+**例**:
+- `code-reviewer`: コードレビュー専門
+- `test-runner`: テスト実行専門
+- `code-simplifier`: リファクタリング専門
+
+**探索範囲**:
+- `.claude/agents/` - プロジェクトエージェント
+- `~/.claude/agents/` - ユーザーエージェント
+- `.claude/plugins/*/agents/` - プロジェクトプラグインエージェント
+- `~/.claude/plugins/*/agents/` - ユーザープラグインエージェント
+
+## ワークフロー
+
+### 正常フロー（基本）
+
+```
+1. 親父: 「ログイン機能を実装して」
+2. 頭: 命令受け取り → Task(hosa)で補佐起動（フォアグラウンド）
+3. 補佐: タスク分解（3個） → TaskCreateで各タスク記録 → 実行計画を頭に返す
+4. 頭: 実行計画を確認 → 単一メッセージで Task(wakashu) × 3 を並列起動
+5. 若いの1-3: 各自のタスクを並列実行 → 完了したら結果を返す
+6. 頭: 全若いの完了後、結果を集約 → 親父に報告
+```
+
+### 正常フロー（専門エージェント活用）
+
+```
+1. 親父: 「このコードをレビューして改善して」
+2. 頭: 命令受け取り → Task(hosa)で補佐起動
+3. 補佐: 専門エージェント探索（全スコープ）
+   - プロジェクト: なし
+   - ユーザー: なし
+   - プラグイン: code-review:code-review, code-simplifier:code-simplifier 発見
+4. 補佐: タスク分解・人材割り当て（5タスク） → TaskCreateで記録 → 実行計画を頭に返す
+   1. code-review:code-review（プラグイン）: 全体レビュー
+   2. multi-agent-yakuza:wakashu（若衆1）: セキュリティ修正
+   3. multi-agent-yakuza:wakashu（若衆2）: パフォーマンス改善
+   4. code-simplifier:code-simplifier（プラグイン）: リファクタリング
+   5. multi-agent-yakuza:wakashu（若衆3）: テスト追加
+5. 頭: 実行計画を確認 → 単一メッセージで全Task並列起動（専門エージェント + 若衆）
+6. 各人材: 並列実行 → 完了報告
+7. 頭: 結果集約 → 親父に最終報告
+```
+
+### エラーフロー
+
+```
+1. 若いのがエラー
+2. 頭: エラー検知 → 補佐に再計画を依頼（Task(hosa)）
+3. 補佐: エラー分析 → TaskUpdateで状態更新 → 再計画案を作成（別の若いのに再割り当てなど）
+4. 頭: 再計画を確認 → 再実行 or 親父に報告・確認
+5. 親父: 指示（必要に応じて）
+6. 頭: 新しい指示を補佐に伝える
+```
+
+## コマンド
+
+### /multi-agent-yakuza:status
+
+現在実行中のYakuza組織タスクの進捗状況を確認
+
+```
+/multi-agent-yakuza:status
+```
+
+## インストール
+
+1. このプラグインを`.claude/plugins/`ディレクトリに配置
+
+```bash
+cp -r multi-agent-yakuza ~/.claude/plugins/
+```
+
+2. Claude Codeを再起動
+
+3. セッション開始時に自動的にウェルカムメッセージが表示されます
+
+```
+親父、困ったことがあれば何なりと。
+
+💡 使い方:
+- タスクを依頼: 「〜を実装して」「〜を修正して」など
+- 進捗確認: `/multi-agent-yakuza:status`
+```
+
+## 使い方
+
+### 基本的な使用方法
+
+若頭に命令を出すだけです：
+
+```
+ログイン機能を実装して
+```
+
+```
+バグを修正して
+```
+
+```
+このコードをリファクタリングして
+```
+
+### 進捗確認
+
+```
+/multi-agent-yakuza:status
+```
+
+### 不明確な命令の場合
+
+頭が自動的に確認してくれます：
+
+```
+親父「バグを修正して」
+頭「かしこまりました、親父。どのバグでしょうか？」
+```
+
+### 専門エージェント（叔父貴）の活用
+
+補佐が自動的に探索・選択してくれます：
+
+```
+親父「このコードをレビューして改善して」
+頭「承知しました。補佐に計画立案を指示します」
+補佐「専門エージェント探索中...」
+補佐「プラグインから code-review:code-review, code-simplifier:code-simplifier を発見」
+補佐「実行計画を作成しました：code-review で全体レビュー、若いの×3 で修正、code-simplifier でリファクタリング」
+頭「計画を確認。単一メッセージで全5タスクを並列起動します」
+```
+
+## 特徴
+
+### 完全縦型組織
+
+- 階層を飛ばした連絡は一切なし
+- すべての報告は階層を経由
+
+### 並列実行
+
+- 若いのは最大5人まで並列実行可能
+- 専門エージェント（叔父貴）も組み合わせて並列実行可能
+- **単一メッセージで複数 Task ツールを呼び出すことで並列化**
+- フォアグラウンド実行により、全タスクの完了を自動的に待機
+- タスクを効率的に処理
+
+### エラーリカバリー
+
+- 補佐（兄貴）が自動的にエラーを検知
+- 再試行可能なら別の若いのに再割り当て
+- 再試行不可能なら親父に報告
+
+### 明確な責任分担
+
+- 頭（若頭）: ユーザー対応、不明確な命令の確認、補佐起動、実行計画確認、エージェント並列起動、結果報告
+- 補佐/兄貴（若頭補佐）: 専門エージェント探索、タスク分解、人材割り当て、TaskCreate/TaskUpdate、実行計画作成
+- 若いの（若衆）: 汎用作業（実装、テスト、バグ修正など）
+- 叔父貴（カスタムエージェント）: 専門作業（コードレビュー、リファクタリングなど）
+
+### セッション開始フック
+
+- セッション開始時に自動的にウェルカムメッセージを表示
+- `hooks/welcome.sh`が`SessionStart`イベントで実行される
+- ユーザーに使い方を案内
+
+## 制約事項
+
+- 若いの（若衆）は最大5人まで
+- 専門エージェント（叔父貴）は制限なし（タスク数に応じて）
+- 頭（若頭）のみユーザーと会話可能
+- 階層を飛ばした連絡は不可
+
+## ライセンス
+
+MIT
+
+## 作者
+
+chippy-ao
+
+## バージョン
+
+1.0.0