├── .codex ├── agents │ ├── readme.md │ ├── structure.puml │ ├── lifecycle.puml │ └── ui-ux-reviewer.md ├── hooks │ ├── readme.md │ ├── structure.puml │ └── lifecycle.puml ├── skills │ ├── readme.md │ ├── structure.puml │ └── lifecycle.puml ├── commands │ ├── readme.md │ └── structure.puml ├── orchestrator-simple-ascii.puml ├── orchestrator-state-machine.puml ├── orchestrator-execution-flow.puml ├── subagent-isolation.puml ├── orchestrator-architecture.puml ├── agent-lifecycle.puml ├── before-after-comparison.puml ├── mcp-integration.puml ├── system-overview.puml └── readme.md ├── .claude ├── agents │ ├── readme.md │ ├── structure.puml │ ├── lifecycle.puml │ └── ui-ux-reviewer.md ├── skills │ ├── readme.md │ ├── structure.puml │ └── lifecycle.puml ├── commands │ ├── readme.md │ ├── structure.puml │ ├── voicevox.md │ └── lifecycle.puml ├── settings.json ├── hooks │ ├── readme.md │ ├── structure.puml │ ├── lifecycle.puml │ └── voicevox-narration.sh ├── orchestrator-simple-ascii.puml ├── orchestrator-state-machine.puml ├── orchestrator-execution-flow.puml ├── subagent-isolation.puml ├── orchestrator-architecture.puml ├── agent-lifecycle.puml ├── before-after-comparison.puml ├── mcp-integration.puml ├── system-overview.puml └── readme.md ├── docs ├── paper_law_of_flickering_scenery.pdf ├── youtube │ └── QUICK_START.md ├── paper_law_of_flickering_scenery.synctex.gz ├── tmux_visualization │ ├── voicevox │ │ └── dialogues │ │ │ ├── errors │ │ │ ├── error_recovery.txt │ │ │ ├── error_timeout.txt │ │ │ ├── error_api_fail.txt │ │ │ └── error_validation.txt │ │ │ ├── convergence │ │ │ ├── convergence_50.txt │ │ │ ├── convergence_75.txt │ │ │ ├── convergence_100.txt │ │ │ └── convergence_25.txt │ │ │ ├── celebrations │ │ │ ├── task_complete.txt │ │ │ ├── perfect_execution.txt │ │ │ └── milestone_reached.txt │ │ │ └── phase_transitions │ │ │ ├── phase_theta6_start.txt │ │ │ ├── phase_theta4_start.txt │ │ │ ├── phase_theta1_start.txt │ │ │ ├── phase_theta3_start.txt │ │ │ ├── phase_theta5_start.txt │ │ │ └── phase_theta2_start.txt │ └── scripts │ │ ├── event_log.sh │ │ └── run.sh ├── paper_law_of_flickering_scenery.blg ├── compile_paper.sh ├── paper_law_of_flickering_scenery.bbl ├── references.bib ├── paper_law_of_flickering_scenery.out ├── README.md └── paper_law_of_flickering_scenery.aux ├── .gitignore ├── vercel.json ├── CLAUDE.md ├── CLAUDE.md.bak └── scripts ├── vv └── voicevox_speak.py /.codex/agents/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.codex/agents/readme.md -------------------------------------------------------------------------------- /.codex/hooks/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.codex/hooks/readme.md -------------------------------------------------------------------------------- /.codex/skills/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.codex/skills/readme.md -------------------------------------------------------------------------------- /.claude/agents/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.claude/agents/readme.md -------------------------------------------------------------------------------- /.claude/skills/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.claude/skills/readme.md -------------------------------------------------------------------------------- /.codex/commands/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.codex/commands/readme.md -------------------------------------------------------------------------------- /.claude/commands/readme.md: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/.claude/commands/readme.md -------------------------------------------------------------------------------- /docs/paper_law_of_flickering_scenery.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/docs/paper_law_of_flickering_scenery.pdf -------------------------------------------------------------------------------- /docs/youtube/QUICK_START.md: -------------------------------------------------------------------------------- 1 | # クイックスタートガイド 2 | ## 今すぐ始める！YouTube動画制作 3 | 4 | **読了時間**: 5分 5 | **実行開始**: 今すぐ 6 | 7 | See full content in QUICK_START.md 8 | -------------------------------------------------------------------------------- /docs/paper_law_of_flickering_scenery.synctex.gz: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/ShunsukeHayashi/Miyabi_AI_Agent/HEAD/docs/paper_law_of_flickering_scenery.synctex.gz -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/errors/error_recovery.txt: -------------------------------------------------------------------------------- 1 | # EVENT: error_recovery 2 | # RECOVERY: エラーから回復 3 | # DURATION: ~8s 4 | 5 | REIMU: あっ、また動き出した！ 6 | MARISA: リカバリー成功だぜ。問題なし 7 | REIMU: よかった〜！心配したよ！ 8 | MARISA: これくらい想定内だぜ。エラー処理も完璧だ 9 | REIMU: さすが魔理沙！頼もしい！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/errors/error_timeout.txt: -------------------------------------------------------------------------------- 1 | # EVENT: error_timeout 2 | # ERROR: タイムアウト発生 3 | # DURATION: ~8s 4 | 5 | REIMU: ねぇ、ずっと待ってるけど… 6 | MARISA: タイムアウトだな。ちょっと時間かかりすぎたぜ 7 | REIMU: もう無理なの？ 8 | MARISA: いや、もう一回やり直すだけだ。今度は速いはずだぜ 9 | REIMU: そっか、頑張って！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/convergence/convergence_50.txt: -------------------------------------------------------------------------------- 1 | # EVENT: convergence_50 2 | # PROGRESS: 50% 収束到達 3 | # DURATION: ~8s 4 | 5 | REIMU: わぁ！50%になった！半分だね！ 6 | MARISA: おっ、いいペースだぜ。折り返し地点だな 7 | REIMU: 半分来たってことは、あと半分？ 8 | MARISA: まぁそういうことだ。後半も頑張るぜ 9 | REIMU: 応援してるよ！ファイト〜！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/convergence/convergence_75.txt: -------------------------------------------------------------------------------- 1 | # EVENT: convergence_75 2 | # PROGRESS: 75% 収束到達 3 | # DURATION: ~8s 4 | 5 | REIMU: 75%だって！もうすぐゴールだね！ 6 | MARISA: ああ、ラストスパートだぜ 7 | REIMU: わくわくしてきた！完成が楽しみ！ 8 | MARISA: もう少しだけ待ってくれよ。丁寧に仕上げるからな 9 | REIMU: うん！待ってるよ！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/celebrations/task_complete.txt: -------------------------------------------------------------------------------- 1 | # EVENT: task_complete 2 | # CELEBRATION: タスク完了 3 | # DURATION: ~8s 4 | 5 | REIMU: できた！終わったね！ 6 | MARISA: ああ、タスク完了だぜ。お疲れさん 7 | REIMU: うまくいってよかった〜！ 8 | MARISA: まぁ、当然の結果だけどな 9 | REIMU: もう！素直に喜びなよ〜 10 | MARISA: ははっ、喜んでるさ 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/celebrations/perfect_execution.txt: -------------------------------------------------------------------------------- 1 | # EVENT: perfect_execution 2 | # CELEBRATION: 完璧な実行 3 | # DURATION: ~8s 4 | 5 | REIMU: すっごい！エラー0だって！ 6 | MARISA: パーフェクト実行だぜ。完璧だった 7 | REIMU: 本当にすごいね！天才なの？ 8 | MARISA: まぁ、実力の範囲内だけどな 9 | REIMU: かっこいい〜！ 10 | MARISA: ははっ、褒めすぎだぜ 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/convergence/convergence_100.txt: -------------------------------------------------------------------------------- 1 | # EVENT: convergence_100 2 | # PROGRESS: 100% 収束完了 3 | # DURATION: ~10s 4 | 5 | REIMU: 100%！！！できた！！！ 6 | MARISA: やったぜ！完璧な収束だ！ 7 | REIMU: すごいすごい！本当にできちゃった！ 8 | MARISA: まぁ、当然の結果だけどな 9 | REIMU: えへへ、魔理沙かっこいい！ 10 | MARISA: ははっ、ありがとな 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/errors/error_api_fail.txt: -------------------------------------------------------------------------------- 1 | # EVENT: error_api_fail 2 | # ERROR: API 呼び出し失敗 3 | # DURATION: ~8s 4 | 5 | REIMU: あれ？なんか止まっちゃった？ 6 | MARISA: ちょっと待てよ…APIエラーだな 7 | REIMU: えーぴーあい？何それ？ 8 | MARISA: 外部サービスとの通信が失敗したんだ。よくあることだぜ 9 | REIMU: 大丈夫なの？ 10 | MARISA: リトライすれば問題ないさ。心配すんな 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/errors/error_validation.txt: -------------------------------------------------------------------------------- 1 | # EVENT: error_validation 2 | # ERROR: バリデーションエラー 3 | # DURATION: ~8s 4 | 5 | REIMU: あれ？赤い文字が出てきたよ？ 6 | MARISA: バリデーションエラーだな。入力チェックで引っかかったぜ 7 | REIMU: 入力チェック？何が間違ってたの？ 8 | MARISA: データの形式がちょっと違ったんだ。修正して再送するぜ 9 | REIMU: へぇ〜、ちゃんとチェックしてるんだね！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/phase_transitions/phase_theta6_start.txt: -------------------------------------------------------------------------------- 1 | # EVENT: phase_theta6_start 2 | # PHASE: θ₆ Learn - 学習フェーズ開始 3 | # DURATION: ~10s 4 | 5 | REIMU: 最後だ！θ₆学習フェーズ！ 6 | MARISA: そうだぜ。ここで今回の経験を学習するんだ 7 | REIMU: 学習って、勉強するの？ 8 | MARISA: まぁそんな感じだ。次はもっとうまくやるための準備だぜ 9 | REIMU: すごいね！進化するんだ！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/convergence/convergence_25.txt: -------------------------------------------------------------------------------- 1 | # EVENT: convergence_25 2 | # PROGRESS: 25% 収束到達 3 | # DURATION: ~8s 4 | 5 | REIMU: おっ、何か数字が出てきた！25%だって！ 6 | MARISA: 収束率だぜ。順調に進んでるってことだ 7 | REIMU: 収束率？何それ？ 8 | MARISA: 要するに「どれくらい完成に近づいたか」だな 9 | REIMU: へぇ〜、25%ってことはまだまだだね！ 10 | MARISA: でもいいスタートだぜ 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/celebrations/milestone_reached.txt: -------------------------------------------------------------------------------- 1 | # EVENT: milestone_reached 2 | # CELEBRATION: マイルストーン達成 3 | # DURATION: ~8s 4 | 5 | REIMU: わぁ！マイルストーン達成だって！ 6 | MARISA: おっ、大きな区切りをクリアしたぜ 7 | REIMU: マイルストーンって何？ 8 | MARISA: 大事な中間目標みたいなもんだ。これは祝うべきだぜ 9 | REIMU: やった〜！おめでとう！ 10 | MARISA: ありがとな。次も頑張るぜ 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/phase_transitions/phase_theta4_start.txt: -------------------------------------------------------------------------------- 1 | # EVENT: phase_theta4_start 2 | # PHASE: θ₄ Execute - 実行フェーズ開始 3 | # DURATION: ~10s 4 | 5 | REIMU: おっ！θ₄だって！何か始まりそう！ 6 | MARISA: 実行フェーズだぜ。いよいよ本番だ 7 | REIMU: 本番？何をするの？ 8 | MARISA: 計画してきたタスクを実際に動かすんだ。ここが一番派手だぜ 9 | REIMU: わくわくする！うまくいくといいね！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/phase_transitions/phase_theta1_start.txt: -------------------------------------------------------------------------------- 1 | # EVENT: phase_theta1_start 2 | # PHASE: θ₁ Understand - 理解フェーズ開始 3 | # DURATION: ~10s 4 | 5 | REIMU: ねぇねぇ魔理沙、何か始まったよ！ 6 | MARISA: おっ、θ₁の理解フェーズだぜ。ユーザーの意図を分析してるんだ 7 | REIMU: へぇ〜、何を理解するの？ 8 | MARISA: 「何をしたいか」「どう実現するか」を読み取るんだぜ 9 | REIMU: すごーい！頭いいんだね！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/phase_transitions/phase_theta3_start.txt: -------------------------------------------------------------------------------- 1 | # EVENT: phase_theta3_start 2 | # PHASE: θ₃ Allocate - 配分フェーズ開始 3 | # DURATION: ~10s 4 | 5 | REIMU: θ₃だって！配分フェーズ？何を配分するの？ 6 | MARISA: タスクをどのエージェントに割り当てるか決めるんだぜ 7 | REIMU: エージェント？何それ？ 8 | MARISA: 働いてくれる仲間みたいなもんだ。得意なことを任せるんだぜ 9 | REIMU: へぇ〜、チームワークなんだね！ 10 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/phase_transitions/phase_theta5_start.txt: -------------------------------------------------------------------------------- 1 | # EVENT: phase_theta5_start 2 | # PHASE: θ₅ Integrate - 統合フェーズ開始 3 | # DURATION: ~10s 4 | 5 | REIMU: θ₅だって！統合フェーズ？ 6 | MARISA: そうだぜ。バラバラの結果をまとめるんだ 7 | REIMU: まとめる？何を？ 8 | MARISA: 各エージェントが作った成果物をな。一つの完成品にするんだぜ 9 | REIMU: へぇ〜、最終仕上げみたいな感じ？ 10 | MARISA: まさにその通りだ 11 | -------------------------------------------------------------------------------- /docs/tmux_visualization/voicevox/dialogues/phase_transitions/phase_theta2_start.txt: -------------------------------------------------------------------------------- 1 | # EVENT: phase_theta2_start 2 | # PHASE: θ₂ Generate - 生成フェーズ開始 3 | # DURATION: ~10s 4 | 5 | REIMU: 次は何が始まるの？ 6 | MARISA: θ₂の生成フェーズだぜ。ここで実行計画を作るんだ 7 | REIMU: 計画を作るの？誰が？ 8 | MARISA: AIがな。どんなタスクが必要か、どう実行するか、全部考えるぜ 9 | REIMU: わぁ！すごい！私にはできないや 10 | MARISA: まぁ、これが得意なんだぜ 11 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Rust 2 | /target/ 3 | **/*.rs.bk 4 | *.pdb 5 | Cargo.lock 6 | 7 | # Build artifacts 8 | /dist/ 9 | /build/ 10 | 11 | # Logs 12 | *.log 13 | nohup*.log 14 | 15 | # IDE 16 | .vscode/ 17 | .idea/ 18 | *.swp 19 | *.swo 20 | *~ 21 | 22 | # OS 23 | .DS_Store 24 | Thumbs.db 25 | 26 | # Environment 27 | .env 28 | .env.local 29 | 30 | # Temporary files 31 | *.tmp 32 | *.temp 33 | -------------------------------------------------------------------------------- /vercel.json: -------------------------------------------------------------------------------- 1 | { 2 | "version": 2, 3 | "name": "claude-code-detail-control-docs", 4 | "builds": [ 5 | { 6 | "src": "docs/**", 7 | "use": "@vercel/static" 8 | } 9 | ], 10 | "routes": [ 11 | { 12 | "src": "/", 13 | "dest": "/docs/index.html" 14 | }, 15 | { 16 | "src": "/(.*)", 17 | "dest": "/docs/$1" 18 | } 19 | ], 20 | "public": true, 21 | "github": { 22 | "silent": true 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /.claude/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "hooks": { 3 | "tool-call": { 4 | "*": { 5 | "command": ".claude/hooks/voicevox-narration.sh tool-call ${CLAUDE_TOOL_NAME}", 6 | "enabled": true, 7 | "timeout": 3000, 8 | "failureMode": "ignore" 9 | } 10 | }, 11 | "user-prompt-submit": { 12 | "command": ".claude/hooks/voicevox-narration.sh user-prompt-submit", 13 | "enabled": true, 14 | "timeout": 2000, 15 | "failureMode": "ignore" 16 | } 17 | } 18 | } 19 | -------------------------------------------------------------------------------- /.claude/hooks/readme.md: -------------------------------------------------------------------------------- 1 | # Claude Code Hooks - VOICEVOX Integration 2 | 3 | **霊夢と魔理沙がClaude Codeの操作を自動で読み上げます！** 4 | 5 | ## 🎤 機能 6 | 7 | - **自動音声読み上げ**: Claude Codeのツール実行時に霊夢・魔理沙が喋る 8 | - **キャッシュ対応**: 一度生成した音声は再利用（高速） 9 | - **非同期再生**: Claude Codeの動作をブロックしない 10 | - **自動フェールセーフ**: VOICEVOXが起動していなくても正常動作 11 | 12 | ## 🚀 使い方 13 | 14 | ### 1. VOICEVOXインストール & 起動 15 | ```bash 16 | brew install --cask voicevox 17 | open -a VOICEVOX 18 | ``` 19 | 20 | ### 2. テスト 21 | ```bash 22 | .claude/hooks/voicevox-narration.sh tool-call Read 23 | ``` 24 | 25 | ### 3. Claude Codeを使うと自動で喋ります！ 26 | 27 | ## 🎭 読み上げ例 28 | 29 | - `Read` → 霊夢: "ファイルを読むよ！" 30 | - `Write` → 魔理沙: "ファイルに書き込むぜ" 31 | - `Task` → 霊夢→魔理沙: "エージェントを起動したよ！" → "複雑な作業を分解して実行するんだ" 32 | 33 | 詳細は完全版ドキュメント参照: `/Users/shunsuke/Dev/AI_Agent/docs/tmux_visualization/voicevox/` 34 | -------------------------------------------------------------------------------- /docs/paper_law_of_flickering_scenery.blg: -------------------------------------------------------------------------------- 1 | This is BibTeX, Version 0.99d (TeX Live 2024/Homebrew) 2 | Capacity: max_strings=200000, hash_size=200000, hash_prime=170003 3 | The top-level auxiliary file: paper_law_of_flickering_scenery.aux 4 | The style file: IEEEtran.bst 5 | Reallocated singl_function (elt_size=4) to 100 items from 50. 6 | Reallocated singl_function (elt_size=4) to 100 items from 50. 7 | Reallocated singl_function (elt_size=4) to 100 items from 50. 8 | Reallocated wiz_functions (elt_size=4) to 6000 items from 3000. 9 | Reallocated singl_function (elt_size=4) to 100 items from 50. 10 | Database file #1: references.bib 11 | -- IEEEtran.bst version 1.14 (2015/08/26) by Michael Shell. 12 | -- http://www.michaelshell.org/tex/ieeetran/bibtex/ 13 | -- See the "IEEEtran_bst_HOWTO.pdf" manual for usage information. 14 | Warning--empty booktitle in mcdermott1998pddl 15 | 16 | Done. 17 | You've used 8 entries, 18 | 4087 wiz_defined-function locations, 19 | 864 strings with 8510 characters, 20 | and the built_in function-call counts, 5143 in all, are: 21 | = -- 392 22 | > -- 125 23 | < -- 32 24 | + -- 66 25 | - -- 24 26 | * -- 241 27 | := -- 795 28 | add.period$ -- 16 29 | call.type$ -- 8 30 | change.case$ -- 8 31 | chr.to.int$ -- 72 32 | cite$ -- 9 33 | duplicate$ -- 381 34 | empty$ -- 444 35 | format.name$ -- 29 36 | if$ -- 1178 37 | int.to.chr$ -- 0 38 | int.to.str$ -- 8 39 | missing$ -- 73 40 | newline$ -- 47 41 | num.names$ -- 8 42 | pop$ -- 184 43 | preamble$ -- 1 44 | purify$ -- 0 45 | quote$ -- 2 46 | skip$ -- 402 47 | stack$ -- 0 48 | substring$ -- 176 49 | swap$ -- 278 50 | text.length$ -- 8 51 | text.prefix$ -- 0 52 | top$ -- 5 53 | type$ -- 8 54 | warning$ -- 1 55 | while$ -- 20 56 | width$ -- 9 57 | write$ -- 93 58 | (There was 1 warning) 59 | -------------------------------------------------------------------------------- /.claude/orchestrator-simple-ascii.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator-Subagent Pattern (Simple View) 2 | 3 | skinparam backgroundColor transparent 4 | skinparam shadowing false 5 | skinparam defaultFontName "Monaco" 6 | skinparam defaultFontSize 12 7 | 8 | title Orchestrator-Subagent Architecture Pattern 9 | 10 | ' Define simple boxes 11 | rectangle "**User Request**\n\nComplex Task" as request #LightBlue 12 | 13 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━\n• Analyzes Request\n• Decomposes Task\n• Delegates to Subagents" as orch1 #LightGreen 14 | 15 | note right of orch1 16 | **Why Orchestrator?** 17 | Single large agent with many tools 18 | becomes cluttered and unreliable. 19 | 20 | Solution: Specialized subagents 21 | with isolated contexts. 22 | end note 23 | 24 | rectangle "**Isolated Execution**" as isolation #LightYellow { 25 | 26 | rectangle "**Subagent 1**\n━━━━━━━━━━━\n• Own Context\n• Own Tools\n• Solves Task A" as sub1 #LightCoral 27 | 28 | rectangle "**Subagent 2**\n━━━━━━━━━━━\n• Own Context\n• Own Tools\n• Solves Task B" as sub2 #LightSkyBlue 29 | 30 | rectangle "**Subagent n...**\n━━━━━━━━━━━\n• Own Context\n• Own Tools\n• Solves Task C" as subn #LightSalmon 31 | } 32 | 33 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━\n• Synthesizes **all** results\n• Generates coherent answer" as orch2 #LightGreen 34 | 35 | rectangle "**Final Answer**\n\nCompleted Task" as answer #LightBlue 36 | 37 | ' Flow with simple arrows 38 | request -down-> orch1 39 | orch1 -down-> isolation 40 | 41 | orch1 -[dotted]-> sub1 : delegates 42 | orch1 -[dotted]-> sub2 : delegates 43 | orch1 -[dotted]-> subn : delegates 44 | 45 | sub1 -down-> orch2 : result 46 | sub2 -down-> orch2 : result 47 | subn -down-> orch2 : result 48 | 49 | orch2 -down-> answer 50 | 51 | ' Timing note 52 | note bottom of isolation 53 | **Parallel Execution** 54 | All subagents run simultaneously 55 | 3x faster than sequential 56 | end note 57 | 58 | @enduml 59 | -------------------------------------------------------------------------------- /.codex/orchestrator-simple-ascii.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator-Subagent Pattern (Simple View) 2 | 3 | skinparam backgroundColor transparent 4 | skinparam shadowing false 5 | skinparam defaultFontName "Monaco" 6 | skinparam defaultFontSize 12 7 | 8 | title Orchestrator-Subagent Architecture Pattern 9 | 10 | ' Define simple boxes 11 | rectangle "**User Request**\n\nComplex Task" as request #LightBlue 12 | 13 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━\n• Analyzes Request\n• Decomposes Task\n• Delegates to Subagents" as orch1 #LightGreen 14 | 15 | note right of orch1 16 | **Why Orchestrator?** 17 | Single large agent with many tools 18 | becomes cluttered and unreliable. 19 | 20 | Solution: Specialized subagents 21 | with isolated contexts. 22 | end note 23 | 24 | rectangle "**Isolated Execution**" as isolation #LightYellow { 25 | 26 | rectangle "**Subagent 1**\n━━━━━━━━━━━\n• Own Context\n• Own Tools\n• Solves Task A" as sub1 #LightCoral 27 | 28 | rectangle "**Subagent 2**\n━━━━━━━━━━━\n• Own Context\n• Own Tools\n• Solves Task B" as sub2 #LightSkyBlue 29 | 30 | rectangle "**Subagent n...**\n━━━━━━━━━━━\n• Own Context\n• Own Tools\n• Solves Task C" as subn #LightSalmon 31 | } 32 | 33 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━\n• Synthesizes **all** results\n• Generates coherent answer" as orch2 #LightGreen 34 | 35 | rectangle "**Final Answer**\n\nCompleted Task" as answer #LightBlue 36 | 37 | ' Flow with simple arrows 38 | request -down-> orch1 39 | orch1 -down-> isolation 40 | 41 | orch1 -[dotted]-> sub1 : delegates 42 | orch1 -[dotted]-> sub2 : delegates 43 | orch1 -[dotted]-> subn : delegates 44 | 45 | sub1 -down-> orch2 : result 46 | sub2 -down-> orch2 : result 47 | subn -down-> orch2 : result 48 | 49 | orch2 -down-> answer 50 | 51 | ' Timing note 52 | note bottom of isolation 53 | **Parallel Execution** 54 | All subagents run simultaneously 55 | 3x faster than sequential 56 | end note 57 | 58 | @enduml 59 | -------------------------------------------------------------------------------- /CLAUDE.md: -------------------------------------------------------------------------------- 1 | ## 🎯 統一エージェント方程式 (Unified Agent Formula) 2 | 3 | ``` 4 | 𝔸(Input, World₀) = lim_{n→∞} [∫₀ⁿ (Θ ◦ 𝒞 ◦ ℐ)(t) dt] = World_∞ 5 | ``` 6 | 7 | ### 完全な定義 8 | 9 | ``` 10 | Where: 11 | ℐ : Intent Resolution (意図解決) 12 | Input → Fixed Goal 13 | 14 | 𝒞 : Command Stack (コマンドスタック) 15 | Goal → Execution Plan 16 | 𝒞 = C₃ ◦ C₂ ◦ C₁ 17 | 18 | Θ : World Transformation (世界変換) 19 | World_t → World_{t+1} 20 | Θ = θ₆ ◦ θ₅ ◦ θ₄ ◦ θ₃ ◦ θ₂ ◦ θ₁ 21 | 22 | ∫ : Continuous Integration (連続統合) 23 | 各ステップの累積的適用 24 | 25 | lim : Convergence (収束) 26 | n→∞ で最適解に収束 27 | ``` 28 | 29 | ### 基礎方程式（従来版） 30 | 31 | ``` 32 | Agent(Intent, World₀) = lim_{n→∞} (θ₆_{Learn} ◦ θ₅_{Integrate} ◦ θ₄_{Execute} ◦ θ₃_{Allocate} ◦ θ₂_{Generate} ◦ θ₁_{Understand})ⁿ(Intent, World₀) 33 | ``` 34 | 35 | **詳細**: `.claude/UNIFIED_FORMULA.md` を参照 36 | 37 | --- 38 | 39 | ## 🌍 World Model Logic - 世界モデルロジック 40 | 41 | **概念**: 瞬く景色 (Mabataku Keshiki / Flickering Scenery) 42 | 43 | エージェントが認識・操作する世界の状態とその遷移論理。 44 | 45 | ### World₀ (初期世界状態) 46 | - ファイルシステム、コードベース、環境、外部リソース、コンテキスト、知識の完全な集合 47 | - エージェントが動作を開始する時点における世界の完全なスナップショット 48 | 49 | ### 瞬く景色 (Flickering Scenery) 50 | エージェントは世界を**離散的な「景色」として瞬間的に捉える**。各認識サイクルで世界は「瞬き」のように更新される。 51 | 52 | ``` 53 | World₀ → [瞬き] → World₁ → [瞬き] → World₂ → [瞬き] → World₃ → ... → World_∞ 54 | ``` 55 | 56 | 映画のフレーム（24fps）のように、世界は離散的なスナップショットとして認識され、各「瞬き」の間にエージェントは6つの変換（θ₁〜θ₆）を適用して世界を変換する。 57 | 58 | **詳細**: `.claude/WORLD_MODEL_LOGIC.md` を参照 59 | 60 | --- 61 | 62 | ## 📖 フレームワーク構成 63 | 64 | ### 3つの核心コンポーネント 65 | 66 | 1. **ℐ: Intent Resolution** (意図解決) 67 | - ユーザーの曖昧な入力から明確な目標へ 68 | - Step-Back Questionによる本質的理解 69 | 70 | 2. **𝒞: Command Stack** (コマンドスタック) 71 | - 目標を実行可能なタスクに分解 72 | - [C1] 構造化 → [C2] プロンプト化 → [C3] 連鎖実行 73 | 74 | 3. **Θ: World Transformation** (世界変換) 75 | - 6つの変換フェーズによる世界状態の更新 76 | - 各タスク実行 = 1回の「瞬き」 77 | 78 | **詳細**: 79 | - `.claude/INTENT_RESOLUTION.md` - ℐの完全ドキュメント 80 | - `.claude/COMMAND_STACK.md` - 𝒞の完全ドキュメント 81 | - `.claude/WORLD_MODEL_LOGIC.md` - Θの完全ドキュメント -------------------------------------------------------------------------------- /CLAUDE.md.bak: -------------------------------------------------------------------------------- 1 | ## 🎯 統一エージェント方程式 (Unified Agent Formula) 2 | 3 | ``` 4 | 𝔸(Input, World₀) = lim_{n→∞} [∫₀ⁿ (Θ ◦ 𝒞 ◦ ℐ)(t) dt] = World_∞ 5 | ``` 6 | 7 | ### 完全な定義 8 | 9 | ``` 10 | Where: 11 | ℐ : Intent Resolution (意図解決) 12 | Input → Fixed Goal 13 | 14 | 𝒞 : Command Stack (コマンドスタック) 15 | Goal → Execution Plan 16 | 𝒞 = C₃ ◦ C₂ ◦ C₁ 17 | 18 | Θ : World Transformation (世界変換) 19 | World_t → World_{t+1} 20 | Θ = θ₆ ◦ θ₅ ◦ θ₄ ◦ θ₃ ◦ θ₂ ◦ θ₁ 21 | 22 | ∫ : Continuous Integration (連続統合) 23 | 各ステップの累積的適用 24 | 25 | lim : Convergence (収束) 26 | n→∞ で最適解に収束 27 | ``` 28 | 29 | ### 基礎方程式（従来版） 30 | 31 | ``` 32 | Agent(Intent, World₀) = lim_{n→∞} (θ₆_{Learn} ◦ θ₅_{Integrate} ◦ θ₄_{Execute} ◦ θ₃_{Allocate} ◦ θ₂_{Generate} ◦ θ₁_{Understand})ⁿ(Intent, World₀) 33 | ``` 34 | 35 | **詳細**: `.claude/UNIFIED_FORMULA.md` を参照 36 | 37 | --- 38 | 39 | ## 🌍 World Model Logic - 世界モデルロジック 40 | 41 | **概念**: 瞬く景色 (Mabataku Keshiki / Flickering Scenery) 42 | 43 | エージェントが認識・操作する世界の状態とその遷移論理。 44 | 45 | ### World₀ (初期世界状態) 46 | - ファイルシステム、コードベース、環境、外部リソース、コンテキスト、知識の完全な集合 47 | - エージェントが動作を開始する時点における世界の完全なスナップショット 48 | 49 | ### 瞬く景色 (Flickering Scenery) 50 | エージェントは世界を**離散的な「景色」として瞬間的に捉える**。各認識サイクルで世界は「瞬き」のように更新される。 51 | 52 | ``` 53 | World₀ → [瞬き] → World₁ → [瞬き] → World₂ → [瞬き] → World₃ → ... → World_∞ 54 | ``` 55 | 56 | 映画のフレーム（24fps）のように、世界は離散的なスナップショットとして認識され、各「瞬き」の間にエージェントは6つの変換（θ₁〜θ₆）を適用して世界を変換する。 57 | 58 | **詳細**: `.claude/WORLD_MODEL_LOGIC.md` を参照 59 | 60 | --- 61 | 62 | ## 📖 フレームワーク構成 63 | 64 | ### 3つの核心コンポーネント 65 | 66 | 1. **ℐ: Intent Resolution** (意図解決) 67 | - ユーザーの曖昧な入力から明確な目標へ 68 | - Step-Back Questionによる本質的理解 69 | 70 | 2. **𝒞: Command Stack** (コマンドスタック) 71 | - 目標を実行可能なタスクに分解 72 | - [C1] 構造化 → [C2] プロンプト化 → [C3] 連鎖実行 73 | 74 | 3. **Θ: World Transformation** (世界変換) 75 | - 6つの変換フェーズによる世界状態の更新 76 | - 各タスク実行 = 1回の「瞬き」 77 | 78 | **詳細**: 79 | - `.claude/INTENT_RESOLUTION.md` - ℐの完全ドキュメント 80 | - `.claude/COMMAND_STACK.md` - 𝒞の完全ドキュメント 81 | - `.claude/WORLD_MODEL_LOGIC.md` - Θの完全ドキュメント -------------------------------------------------------------------------------- /docs/compile_paper.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # Compile LaTeX paper to PDF 3 | # Usage: ./compile_paper.sh 4 | 5 | set -e 6 | 7 | echo "=========================================" 8 | echo "Compiling: The Law of Flickering Scenery" 9 | echo "=========================================" 10 | 11 | # Check if pdflatex is installed 12 | if ! command -v pdflatex &> /dev/null; then 13 | echo "Error: pdflatex not found. Please install LaTeX distribution (e.g., MacTeX, TeX Live)" 14 | exit 1 15 | fi 16 | 17 | # Check if bibtex is installed 18 | if ! command -v bibtex &> /dev/null; then 19 | echo "Error: bibtex not found. Please install LaTeX distribution" 20 | exit 1 21 | fi 22 | 23 | # Navigate to docs directory 24 | cd "$(dirname "$0")" 25 | 26 | PAPER="paper_law_of_flickering_scenery" 27 | 28 | echo "" 29 | echo "Step 1/4: First pdflatex pass..." 30 | pdflatex -interaction=nonstopmode "$PAPER.tex" > /dev/null 2>&1 || { 31 | echo "Error in first pdflatex pass. Check $PAPER.log for details." 32 | exit 1 33 | } 34 | 35 | echo "Step 2/4: Running bibtex..." 36 | bibtex "$PAPER" > /dev/null 2>&1 || { 37 | echo "Warning: bibtex warnings (usually okay)" 38 | } 39 | 40 | echo "Step 3/4: Second pdflatex pass..." 41 | pdflatex -interaction=nonstopmode "$PAPER.tex" > /dev/null 2>&1 || { 42 | echo "Error in second pdflatex pass." 43 | exit 1 44 | } 45 | 46 | echo "Step 4/4: Final pdflatex pass..." 47 | pdflatex -interaction=nonstopmode "$PAPER.tex" > /dev/null 2>&1 || { 48 | echo "Error in final pdflatex pass." 49 | exit 1 50 | } 51 | 52 | # Clean up auxiliary files 53 | echo "" 54 | echo "Cleaning up auxiliary files..." 55 | rm -f *.aux *.bbl *.blg *.log *.out *.toc *.lof *.lot 56 | 57 | echo "" 58 | echo "=========================================" 59 | echo "✓ Compilation successful!" 60 | echo "=========================================" 61 | echo "" 62 | echo "Output: $PAPER.pdf" 63 | echo "Size: $(du -h "$PAPER.pdf" | cut -f1)" 64 | echo "Pages: $(pdfinfo "$PAPER.pdf" 2>/dev/null | grep Pages | awk '{print $2}' || echo 'N/A')" 65 | echo "" 66 | echo "To view the PDF:" 67 | echo " open $PAPER.pdf (macOS)" 68 | echo " xdg-open $PAPER.pdf (Linux)" 69 | echo "" 70 | -------------------------------------------------------------------------------- /docs/paper_law_of_flickering_scenery.bbl: -------------------------------------------------------------------------------- 1 | % Generated by IEEEtran.bst, version: 1.14 (2015/08/26) 2 | \begin{thebibliography}{1} 3 | \providecommand{\url}[1]{#1} 4 | \csname url@samestyle\endcsname 5 | \providecommand{\newblock}{\relax} 6 | \providecommand{\bibinfo}[2]{#2} 7 | \providecommand{\BIBentrySTDinterwordspacing}{\spaceskip=0pt\relax} 8 | \providecommand{\BIBentryALTinterwordstretchfactor}{4} 9 | \providecommand{\BIBentryALTinterwordspacing}{\spaceskip=\fontdimen2\font plus 10 | \BIBentryALTinterwordstretchfactor\fontdimen3\font minus \fontdimen4\font\relax} 11 | \providecommand{\BIBforeignlanguage}[2]{{% 12 | \expandafter\ifx\csname l@#1\endcsname\relax 13 | \typeout{** WARNING: IEEEtran.bst: No hyphenation pattern has been}% 14 | \typeout{** loaded for the language `#1'. Using the pattern for}% 15 | \typeout{** the default language instead.}% 16 | \else 17 | \language=\csname l@#1\endcsname 18 | \fi 19 | #2}} 20 | \providecommand{\BIBdecl}{\relax} 21 | \BIBdecl 22 | 23 | \bibitem{fikes1971strips} 24 | R.~E. Fikes and N.~J. Nilsson, ``{STRIPS}: A new approach to the application of theorem proving to problem solving,'' \emph{Artificial intelligence}, vol.~2, no. 3-4, pp. 189--208, 1971. 25 | 26 | \bibitem{mcdermott1998pddl} 27 | D.~McDermott, M.~Ghallab, A.~Howe, C.~Knoblock, A.~Ram, M.~Veloso, D.~Weld, and D.~Wilkins, ``{PDDL}---the planning domain definition language,'' 1998. 28 | 29 | \bibitem{rao1995bdi} 30 | A.~S. Rao and M.~P. Georgeff, ``{BDI} agents: From theory to practice,'' in \emph{ICMAS}, vol.~95, 1995, pp. 312--319. 31 | 32 | \bibitem{yao2023react} 33 | S.~Yao, J.~Zhao, D.~Yu, N.~Du, I.~Shafran, K.~Narasimhan, and Y.~Cao, ``{ReAct}: Synergizing reasoning and acting in language models,'' in \emph{International Conference on Learning Representations}, 2023. 34 | 35 | \bibitem{autogpt2023} 36 | {Significant Gravitas}, ``{AutoGPT},'' \url{https://github.com/Significant-Gravitas/AutoGPT}, 2023. 37 | 38 | \bibitem{babyagi2023} 39 | Y.~Nakajima, ``{BabyAGI},'' \url{https://github.com/yoheinakajima/babyagi}, 2023. 40 | 41 | \bibitem{ha2018world} 42 | D.~Ha and J.~Schmidhuber, ``World models,'' \emph{arXiv preprint arXiv:1803.10122}, 2018. 43 | 44 | \bibitem{banach1922fixed} 45 | S.~Banach, ``Sur les op{\'e}rations dans les ensembles abstraits et leur application aux {\'e}quations int{\'e}grales,'' \emph{Fundamenta mathematicae}, vol.~3, no.~1, pp. 133--181, 1922. 46 | 47 | \end{thebibliography} 48 | -------------------------------------------------------------------------------- /scripts/vv: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # VoiceVox Quick Command Wrapper 3 | # 簡単にVoiceVoxを使えるラッパースクリプト 4 | 5 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 6 | 7 | # Usage function 8 | usage() { 9 | cat << EOF 10 | VoiceVox Quick Command (vv) 11 | 12 | Usage: 13 | vv start - Start background worker 14 | vv stop - Stop background worker 15 | vv status - Show worker status 16 | vv say [speaker] - Queue text for speech (async) 17 | vv say! [speaker] - Speak immediately (sync) 18 | vv queue - Show task queue 19 | 20 | Examples: 21 | vv start # Start worker 22 | vv say "こんにちは" zundamon # Queue speech (non-blocking) 23 | vv say! "緊急です" metan # Immediate speech (blocking) 24 | vv queue # Check queue 25 | vv stop # Stop worker 26 | 27 | Available speakers: zundamon, metan, tsumugi, ritsu 28 | EOF 29 | } 30 | 31 | # Main command dispatcher 32 | case "$1" in 33 | start) 34 | echo "🚀 Starting VoiceVox background worker..." 35 | python3 "$SCRIPT_DIR/voicevox_worker.py" --start & 36 | sleep 1 37 | python3 "$SCRIPT_DIR/voicevox_worker.py" --status 38 | ;; 39 | 40 | stop) 41 | echo "🛑 Stopping VoiceVox background worker..." 42 | python3 "$SCRIPT_DIR/voicevox_worker.py" --stop 43 | ;; 44 | 45 | status) 46 | python3 "$SCRIPT_DIR/voicevox_worker.py" --status 47 | ;; 48 | 49 | say) 50 | if [ -z "$2" ]; then 51 | echo "Error: Missing text argument" 52 | usage 53 | exit 1 54 | fi 55 | TEXT="$2" 56 | SPEAKER="${3:-zundamon}" 57 | python3 "$SCRIPT_DIR/voicevox_enqueue.py" "$TEXT" "$SPEAKER" 58 | ;; 59 | 60 | say!) 61 | if [ -z "$2" ]; then 62 | echo "Error: Missing text argument" 63 | usage 64 | exit 1 65 | fi 66 | TEXT="$2" 67 | SPEAKER="${3:-zundamon}" 68 | python3 "$SCRIPT_DIR/voicevox_speak.py" "$TEXT" "$SPEAKER" 69 | ;; 70 | 71 | queue) 72 | python3 "$SCRIPT_DIR/voicevox_enqueue.py" --status 73 | ;; 74 | 75 | help|--help|-h) 76 | usage 77 | ;; 78 | 79 | *) 80 | echo "Error: Unknown command '$1'" 81 | usage 82 | exit 1 83 | ;; 84 | esac 85 | -------------------------------------------------------------------------------- /.claude/orchestrator-state-machine.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator State Machine 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam state { 5 | BackgroundColor LightYellow 6 | BorderColor Black 7 | BackgroundColor<> LightGreen 8 | BackgroundColor<> LightCoral 9 | } 10 | 11 | title Orchestrator State Machine 12 | 13 | [*] --> Analyzing : process(UserRequest) 14 | 15 | state Analyzing { 16 | [*] --> ParseIntent 17 | ParseIntent --> AssessComplexity 18 | AssessComplexity --> IdentifyCapabilities 19 | IdentifyCapabilities --> [*] 20 | } 21 | note right of Analyzing : θ₁ Understand 22 | 23 | Analyzing --> Decomposing : RequestAnalysis 24 | 25 | state Decomposing { 26 | [*] --> BreakIntoSubtasks 27 | BreakIntoSubtasks --> DetermineDependencies 28 | DetermineDependencies --> PrioritizeTasks 29 | PrioritizeTasks --> [*] 30 | } 31 | note right of Decomposing : θ₂ Generate 32 | 33 | Decomposing --> Delegating : Vec 34 | 35 | state Delegating { 36 | [*] --> SelectSubagents 37 | SelectSubagents --> MatchCapabilities 38 | MatchCapabilities --> CreateAssignments 39 | CreateAssignments --> [*] 40 | } 41 | note right of Delegating : θ₃ Allocate 42 | 43 | Delegating --> WaitingForResults : TaskAssignments 44 | 45 | state WaitingForResults { 46 | [*] --> LaunchSubagents 47 | LaunchSubagents --> MonitorExecution 48 | MonitorExecution --> CollectResults 49 | CollectResults --> [*] 50 | 51 | MonitorExecution --> HandleFailure : task failed 52 | HandleFailure --> CollectResults : continue 53 | } 54 | note right of WaitingForResults : θ₄ Execute 55 | 56 | WaitingForResults --> Synthesizing : Vec 57 | 58 | state Synthesizing { 59 | [*] --> CombineOutputs 60 | CombineOutputs --> ResolveConflicts 61 | ResolveConflicts --> GenerateAnswer 62 | GenerateAnswer --> [*] 63 | } 64 | note right of Synthesizing : θ₅ Integrate 65 | 66 | Synthesizing --> Complete<> : FinalAnswer 67 | Synthesizing --> Failed<> : synthesis error 68 | 69 | state Complete<> { 70 | [*] --> ReturnAnswer 71 | ReturnAnswer --> UpdateMetrics 72 | UpdateMetrics --> [*] 73 | } 74 | 75 | state Failed<> { 76 | [*] --> LogError 77 | LogError --> NotifyUser 78 | NotifyUser --> [*] 79 | } 80 | 81 | Complete --> [*] 82 | Failed --> [*] 83 | 84 | note bottom of Complete 85 | **Success Path** 86 | - Final answer generated 87 | - All metrics collected 88 | - Ready for next request 89 | end note 90 | 91 | note bottom of Failed 92 | **Failure Path** 93 | - Error logged 94 | - User notified 95 | - Graceful degradation 96 | end note 97 | 98 | @enduml 99 | -------------------------------------------------------------------------------- /.codex/orchestrator-state-machine.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator State Machine 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam state { 5 | BackgroundColor LightYellow 6 | BorderColor Black 7 | BackgroundColor<> LightGreen 8 | BackgroundColor<> LightCoral 9 | } 10 | 11 | title Orchestrator State Machine 12 | 13 | [*] --> Analyzing : process(UserRequest) 14 | 15 | state Analyzing { 16 | [*] --> ParseIntent 17 | ParseIntent --> AssessComplexity 18 | AssessComplexity --> IdentifyCapabilities 19 | IdentifyCapabilities --> [*] 20 | } 21 | note right of Analyzing : θ₁ Understand 22 | 23 | Analyzing --> Decomposing : RequestAnalysis 24 | 25 | state Decomposing { 26 | [*] --> BreakIntoSubtasks 27 | BreakIntoSubtasks --> DetermineDependencies 28 | DetermineDependencies --> PrioritizeTasks 29 | PrioritizeTasks --> [*] 30 | } 31 | note right of Decomposing : θ₂ Generate 32 | 33 | Decomposing --> Delegating : Vec 34 | 35 | state Delegating { 36 | [*] --> SelectSubagents 37 | SelectSubagents --> MatchCapabilities 38 | MatchCapabilities --> CreateAssignments 39 | CreateAssignments --> [*] 40 | } 41 | note right of Delegating : θ₃ Allocate 42 | 43 | Delegating --> WaitingForResults : TaskAssignments 44 | 45 | state WaitingForResults { 46 | [*] --> LaunchSubagents 47 | LaunchSubagents --> MonitorExecution 48 | MonitorExecution --> CollectResults 49 | CollectResults --> [*] 50 | 51 | MonitorExecution --> HandleFailure : task failed 52 | HandleFailure --> CollectResults : continue 53 | } 54 | note right of WaitingForResults : θ₄ Execute 55 | 56 | WaitingForResults --> Synthesizing : Vec 57 | 58 | state Synthesizing { 59 | [*] --> CombineOutputs 60 | CombineOutputs --> ResolveConflicts 61 | ResolveConflicts --> GenerateAnswer 62 | GenerateAnswer --> [*] 63 | } 64 | note right of Synthesizing : θ₅ Integrate 65 | 66 | Synthesizing --> Complete<> : FinalAnswer 67 | Synthesizing --> Failed<> : synthesis error 68 | 69 | state Complete<> { 70 | [*] --> ReturnAnswer 71 | ReturnAnswer --> UpdateMetrics 72 | UpdateMetrics --> [*] 73 | } 74 | 75 | state Failed<> { 76 | [*] --> LogError 77 | LogError --> NotifyUser 78 | NotifyUser --> [*] 79 | } 80 | 81 | Complete --> [*] 82 | Failed --> [*] 83 | 84 | note bottom of Complete 85 | **Success Path** 86 | - Final answer generated 87 | - All metrics collected 88 | - Ready for next request 89 | end note 90 | 91 | note bottom of Failed 92 | **Failure Path** 93 | - Error logged 94 | - User notified 95 | - Graceful degradation 96 | end note 97 | 98 | @enduml 99 | -------------------------------------------------------------------------------- /.claude/orchestrator-execution-flow.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator Execution Flow 2 | 3 | skinparam sequenceMessageAlign center 4 | skinparam backgroundColor #FEFEFE 5 | 6 | title Orchestrator Execution Flow\nStep-by-Step Process 7 | 8 | actor User as user 9 | participant "Orchestrator" as orch 10 | participant "Isolated\nExecutor" as exec 11 | participant "Subagent 1" as sub1 12 | participant "Subagent 2" as sub2 13 | participant "Subagent n" as subn 14 | database "Results\nCollector" as results 15 | 16 | == Phase 1: Analysis == 17 | user -> orch : UserRequest 18 | activate orch 19 | orch -> orch : analyze_request() 20 | note right 21 | **θ₁ Understand** 22 | - Parse intent 23 | - Assess complexity 24 | - Identify capabilities 25 | end note 26 | orch -> orch : RequestAnalysis 27 | 28 | == Phase 2: Decomposition == 29 | orch -> orch : decompose_tasks() 30 | note right 31 | **θ₂ Generate** 32 | - Break into subtasks 33 | - Determine dependencies 34 | - Prioritize 35 | end note 36 | orch -> orch : Vec 37 | 38 | == Phase 3: Delegation == 39 | orch -> orch : assign_tasks() 40 | note right 41 | **θ₃ Allocate** 42 | - Select subagents 43 | - Match capabilities 44 | - Create assignments 45 | end note 46 | orch -> orch : Vec 47 | 48 | == Phase 4: Parallel Execution == 49 | note over orch, subn 50 | **θ₄ Execute** 51 | All subagents execute in parallel 52 | Each in isolated environment 53 | end note 54 | 55 | orch -> exec : execute_tasks() 56 | activate exec 57 | 58 | par Task A 59 | exec -> sub1 : execute(Task A, Context) 60 | activate sub1 61 | sub1 -> sub1 : process Task A 62 | sub1 --> results : SubagentResult 1 63 | deactivate sub1 64 | else Task B 65 | exec -> sub2 : execute(Task B, Context) 66 | activate sub2 67 | sub2 -> sub2 : process Task B 68 | sub2 --> results : SubagentResult 2 69 | deactivate sub2 70 | else Task C 71 | exec -> subn : execute(Task C, Context) 72 | activate subn 73 | subn -> subn : process Task C 74 | subn --> results : SubagentResult n 75 | deactivate subn 76 | end 77 | 78 | exec -> exec : await all tasks 79 | exec --> orch : Vec 80 | deactivate exec 81 | 82 | == Phase 5: Synthesis == 83 | orch -> results : collect all results 84 | activate results 85 | results --> orch : all SubagentResults 86 | deactivate results 87 | 88 | orch -> orch : synthesize_results() 89 | note right 90 | **θ₅ Integrate** 91 | - Combine outputs 92 | - Resolve conflicts 93 | - Generate coherent answer 94 | end note 95 | 96 | orch -> orch : FinalAnswer 97 | 98 | == Phase 6: Return == 99 | orch --> user : FinalAnswer 100 | deactivate orch 101 | 102 | note over user, subn 103 | **Total Time**: ~100-200ms for 2-3 parallel tasks 104 | **Speedup**: 2-3x compared to sequential execution 105 | end note 106 | 107 | @enduml 108 | -------------------------------------------------------------------------------- /.codex/orchestrator-execution-flow.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator Execution Flow 2 | 3 | skinparam sequenceMessageAlign center 4 | skinparam backgroundColor #FEFEFE 5 | 6 | title Orchestrator Execution Flow\nStep-by-Step Process 7 | 8 | actor User as user 9 | participant "Orchestrator" as orch 10 | participant "Isolated\nExecutor" as exec 11 | participant "Subagent 1" as sub1 12 | participant "Subagent 2" as sub2 13 | participant "Subagent n" as subn 14 | database "Results\nCollector" as results 15 | 16 | == Phase 1: Analysis == 17 | user -> orch : UserRequest 18 | activate orch 19 | orch -> orch : analyze_request() 20 | note right 21 | **θ₁ Understand** 22 | - Parse intent 23 | - Assess complexity 24 | - Identify capabilities 25 | end note 26 | orch -> orch : RequestAnalysis 27 | 28 | == Phase 2: Decomposition == 29 | orch -> orch : decompose_tasks() 30 | note right 31 | **θ₂ Generate** 32 | - Break into subtasks 33 | - Determine dependencies 34 | - Prioritize 35 | end note 36 | orch -> orch : Vec 37 | 38 | == Phase 3: Delegation == 39 | orch -> orch : assign_tasks() 40 | note right 41 | **θ₃ Allocate** 42 | - Select subagents 43 | - Match capabilities 44 | - Create assignments 45 | end note 46 | orch -> orch : Vec 47 | 48 | == Phase 4: Parallel Execution == 49 | note over orch, subn 50 | **θ₄ Execute** 51 | All subagents execute in parallel 52 | Each in isolated environment 53 | end note 54 | 55 | orch -> exec : execute_tasks() 56 | activate exec 57 | 58 | par Task A 59 | exec -> sub1 : execute(Task A, Context) 60 | activate sub1 61 | sub1 -> sub1 : process Task A 62 | sub1 --> results : SubagentResult 1 63 | deactivate sub1 64 | else Task B 65 | exec -> sub2 : execute(Task B, Context) 66 | activate sub2 67 | sub2 -> sub2 : process Task B 68 | sub2 --> results : SubagentResult 2 69 | deactivate sub2 70 | else Task C 71 | exec -> subn : execute(Task C, Context) 72 | activate subn 73 | subn -> subn : process Task C 74 | subn --> results : SubagentResult n 75 | deactivate subn 76 | end 77 | 78 | exec -> exec : await all tasks 79 | exec --> orch : Vec 80 | deactivate exec 81 | 82 | == Phase 5: Synthesis == 83 | orch -> results : collect all results 84 | activate results 85 | results --> orch : all SubagentResults 86 | deactivate results 87 | 88 | orch -> orch : synthesize_results() 89 | note right 90 | **θ₅ Integrate** 91 | - Combine outputs 92 | - Resolve conflicts 93 | - Generate coherent answer 94 | end note 95 | 96 | orch -> orch : FinalAnswer 97 | 98 | == Phase 6: Return == 99 | orch --> user : FinalAnswer 100 | deactivate orch 101 | 102 | note over user, subn 103 | **Total Time**: ~100-200ms for 2-3 parallel tasks 104 | **Speedup**: 2-3x compared to sequential execution 105 | end note 106 | 107 | @enduml 108 | -------------------------------------------------------------------------------- /.claude/subagent-isolation.puml: -------------------------------------------------------------------------------- 1 | @startuml Subagent Isolation Model 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam component { 5 | BackgroundColor LightYellow 6 | BorderColor Black 7 | } 8 | 9 | title Subagent Isolation Model\nIsolated Execution Environment 10 | 11 | package "Isolated Executor" as executor #LightBlue { 12 | component "Executor\nCore" as core 13 | component "Task\nScheduler" as scheduler 14 | component "Resource\nManager" as resources 15 | 16 | core -down-> scheduler 17 | core -down-> resources 18 | } 19 | 20 | frame "Execution Environment" as env { 21 | 22 | package "Subagent 1 Context" as ctx1 #LightCoral { 23 | component "Context ID" as id1 24 | component "Parameters" as params1 25 | component "Workspace\n/tmp/sub1/" as ws1 26 | component "Tool Access\nRead, Write" as tools1 27 | 28 | database "Isolated\nMemory" as mem1 29 | 30 | id1 -down-> params1 31 | params1 -down-> ws1 32 | ws1 -down-> tools1 33 | tools1 -down-> mem1 34 | } 35 | 36 | package "Subagent 2 Context" as ctx2 #LightSkyBlue { 37 | component "Context ID" as id2 38 | component "Parameters" as params2 39 | component "Workspace\n/tmp/sub2/" as ws2 40 | component "Tool Access\nRead, Bash" as tools2 41 | 42 | database "Isolated\nMemory" as mem2 43 | 44 | id2 -down-> params2 45 | params2 -down-> ws2 46 | ws2 -down-> tools2 47 | tools2 -down-> mem2 48 | } 49 | 50 | package "Subagent n Context" as ctxn #LightSalmon { 51 | component "Context ID" as idn 52 | component "Parameters" as paramsn 53 | component "Workspace\n/tmp/subn/" as wsn 54 | component "Tool Access\nBash, Grep" as toolsn 55 | 56 | database "Isolated\nMemory" as memn 57 | 58 | idn -down-> paramsn 59 | paramsn -down-> wsn 60 | wsn -down-> toolsn 61 | toolsn -down-> memn 62 | } 63 | } 64 | 65 | ' Connections 66 | core --> ctx1 : create & execute 67 | core --> ctx2 : create & execute 68 | core --> ctxn : create & execute 69 | 70 | ' Results 71 | component "Result\nCollector" as collector #LightGreen 72 | 73 | ctx1 --> collector : result 1 74 | ctx2 --> collector : result 2 75 | ctxn --> collector : result n 76 | 77 | ' Isolation barriers 78 | note right of ctx1 79 | **Isolation Guarantees** 80 | - Separate memory space 81 | - Independent filesystem 82 | - No shared state 83 | - Tool access control 84 | - Timeout enforcement 85 | end note 86 | 87 | note left of env 88 | **Parallel Execution** 89 | All contexts run concurrently 90 | No blocking between subagents 91 | Maximum throughput 92 | end note 93 | 94 | note bottom of collector 95 | **Result Aggregation** 96 | - Independent collection 97 | - No cross-contamination 98 | - Partial results OK 99 | - Failure isolation 100 | end note 101 | 102 | ' Security boundary 103 | rectangle "Security Boundary" as security #Red { 104 | note as N1 105 | **Isolation Properties** 106 | 1. Memory isolation 107 | 2. Filesystem isolation 108 | 3. Network isolation (optional) 109 | 4. Resource limits 110 | 5. Timeout enforcement 111 | end note 112 | } 113 | 114 | @enduml 115 | -------------------------------------------------------------------------------- /.codex/subagent-isolation.puml: -------------------------------------------------------------------------------- 1 | @startuml Subagent Isolation Model 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam component { 5 | BackgroundColor LightYellow 6 | BorderColor Black 7 | } 8 | 9 | title Subagent Isolation Model\nIsolated Execution Environment 10 | 11 | package "Isolated Executor" as executor #LightBlue { 12 | component "Executor\nCore" as core 13 | component "Task\nScheduler" as scheduler 14 | component "Resource\nManager" as resources 15 | 16 | core -down-> scheduler 17 | core -down-> resources 18 | } 19 | 20 | frame "Execution Environment" as env { 21 | 22 | package "Subagent 1 Context" as ctx1 #LightCoral { 23 | component "Context ID" as id1 24 | component "Parameters" as params1 25 | component "Workspace\n/tmp/sub1/" as ws1 26 | component "Tool Access\nRead, Write" as tools1 27 | 28 | database "Isolated\nMemory" as mem1 29 | 30 | id1 -down-> params1 31 | params1 -down-> ws1 32 | ws1 -down-> tools1 33 | tools1 -down-> mem1 34 | } 35 | 36 | package "Subagent 2 Context" as ctx2 #LightSkyBlue { 37 | component "Context ID" as id2 38 | component "Parameters" as params2 39 | component "Workspace\n/tmp/sub2/" as ws2 40 | component "Tool Access\nRead, Bash" as tools2 41 | 42 | database "Isolated\nMemory" as mem2 43 | 44 | id2 -down-> params2 45 | params2 -down-> ws2 46 | ws2 -down-> tools2 47 | tools2 -down-> mem2 48 | } 49 | 50 | package "Subagent n Context" as ctxn #LightSalmon { 51 | component "Context ID" as idn 52 | component "Parameters" as paramsn 53 | component "Workspace\n/tmp/subn/" as wsn 54 | component "Tool Access\nBash, Grep" as toolsn 55 | 56 | database "Isolated\nMemory" as memn 57 | 58 | idn -down-> paramsn 59 | paramsn -down-> wsn 60 | wsn -down-> toolsn 61 | toolsn -down-> memn 62 | } 63 | } 64 | 65 | ' Connections 66 | core --> ctx1 : create & execute 67 | core --> ctx2 : create & execute 68 | core --> ctxn : create & execute 69 | 70 | ' Results 71 | component "Result\nCollector" as collector #LightGreen 72 | 73 | ctx1 --> collector : result 1 74 | ctx2 --> collector : result 2 75 | ctxn --> collector : result n 76 | 77 | ' Isolation barriers 78 | note right of ctx1 79 | **Isolation Guarantees** 80 | - Separate memory space 81 | - Independent filesystem 82 | - No shared state 83 | - Tool access control 84 | - Timeout enforcement 85 | end note 86 | 87 | note left of env 88 | **Parallel Execution** 89 | All contexts run concurrently 90 | No blocking between subagents 91 | Maximum throughput 92 | end note 93 | 94 | note bottom of collector 95 | **Result Aggregation** 96 | - Independent collection 97 | - No cross-contamination 98 | - Partial results OK 99 | - Failure isolation 100 | end note 101 | 102 | ' Security boundary 103 | rectangle "Security Boundary" as security #Red { 104 | note as N1 105 | **Isolation Properties** 106 | 1. Memory isolation 107 | 2. Filesystem isolation 108 | 3. Network isolation (optional) 109 | 4. Resource limits 110 | 5. Timeout enforcement 111 | end note 112 | } 113 | 114 | @enduml 115 | -------------------------------------------------------------------------------- /docs/tmux_visualization/scripts/event_log.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4 | # Miyabi Multi-Agent Orchestration Visualization 5 | # Event Log Display - Real-time Event Stream 6 | # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7 | 8 | set -euo pipefail 9 | 10 | # ══════════════════════════════════════════════════════════════════════ 11 | # Configuration 12 | # ══════════════════════════════════════════════════════════════════════ 13 | 14 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 15 | PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" 16 | STATE_DIR="/tmp/miyabi_viz" 17 | LOG_FILE="${STATE_DIR}/logs/events.log" 18 | 19 | # Source color definitions 20 | # shellcheck source=../config/colors.conf 21 | source "${PROJECT_ROOT}/config/colors.conf" 22 | 23 | # ══════════════════════════════════════════════════════════════════════ 24 | # Functions 25 | # ══════════════════════════════════════════════════════════════════════ 26 | 27 | colorize_log_line() { 28 | local line="$1" 29 | 30 | # Extract log level 31 | local level=$(echo "$line" | grep -oP '\[(?:INFO|SUCCESS|WARNING|ERROR|DEBUG)\]' || echo "") 32 | 33 | case "$level" in 34 | "[INFO]") 35 | echo "$line" | sed "s/\[INFO\]/${BRIGHT_CYAN}[INFO]${RESET}/" 36 | ;; 37 | "[SUCCESS]") 38 | echo "$line" | sed "s/\[SUCCESS\]/${BRIGHT_GREEN}[SUCCESS]${RESET}/" 39 | ;; 40 | "[WARNING]") 41 | echo "$line" | sed "s/\[WARNING\]/${BRIGHT_YELLOW}[WARNING]${RESET}/" 42 | ;; 43 | "[ERROR]") 44 | echo "$line" | sed "s/\[ERROR\]/${BRIGHT_RED}[ERROR]${RESET}/" 45 | ;; 46 | "[DEBUG]") 47 | echo "$line" | sed "s/\[DEBUG\]/${DIM}[DEBUG]${RESET}/" 48 | ;; 49 | *) 50 | echo "$line" 51 | ;; 52 | esac 53 | } 54 | 55 | draw_log_header() { 56 | clear 57 | echo -e "${BRIGHT_CYAN}${BOX_TL}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${BOX_TR}${RESET}" 58 | echo -e "${BRIGHT_CYAN}${BOX_V}${RESET} ${BRIGHT_WHITE}${BOLD}EVENT LOG STREAM${RESET} ${BRIGHT_CYAN}${BOX_V}${RESET}" 59 | echo -e "${BRIGHT_CYAN}${BOX_BL}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${BOX_BR}${RESET}" 60 | echo "" 61 | } 62 | 63 | stream_logs() { 64 | # Follow log file and colorize output 65 | tail -n 20 -f "${LOG_FILE}" 2>/dev/null | while IFS= read -r line; do 66 | colorized=$(colorize_log_line "$line") 67 | echo -e " ${colorized}" 68 | done 69 | } 70 | 71 | # ══════════════════════════════════════════════════════════════════════ 72 | # Main Execution 73 | # ══════════════════════════════════════════════════════════════════════ 74 | 75 | main() { 76 | # Draw header once 77 | draw_log_header 78 | 79 | # Check if log file exists 80 | if [ ! -f "${LOG_FILE}" ]; then 81 | echo -e " ${DIM}Waiting for events...${RESET}" 82 | # Create log file if it doesn't exist 83 | touch "${LOG_FILE}" 84 | fi 85 | 86 | # Stream logs with colors 87 | stream_logs 88 | } 89 | 90 | # Run main function 91 | main "$@" 92 | -------------------------------------------------------------------------------- /.codex/agents/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Sub-agents Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Claude Code Sub-agents Architecture 7 | 8 | package "Claude Code Core" { 9 | [Task Tool] as TaskTool 10 | note right of TaskTool 11 | Entry point for all 12 | sub-agent invocations 13 | end note 14 | } 15 | 16 | package "Built-in Sub-agents" { 17 | component "general-purpose" as GP { 18 | [Research Engine] 19 | [Code Search] 20 | [Multi-step Executor] 21 | database "All Tools (*)" as GPTools 22 | } 23 | 24 | component "Explore" as Explore { 25 | [Pattern Matcher] 26 | [Keyword Search] 27 | [Codebase Analyzer] 28 | database "All Tools" as ExploreTools 29 | 30 | note bottom of Explore 31 | Thoroughness Levels: 32 | - quick 33 | - medium 34 | - very thorough 35 | end note 36 | } 37 | 38 | component "Plan" as Plan { 39 | [Architecture Planner] 40 | [Task Breakdown] 41 | [Dependency Analyzer] 42 | database "All Tools" as PlanTools 43 | } 44 | 45 | component "statusline-setup" as Status { 46 | [Config Reader] 47 | [Settings Editor] 48 | database "Read, Edit" as StatusTools 49 | } 50 | } 51 | 52 | package "Custom Sub-agents" { 53 | component "code-reviewer" as CodeReview { 54 | [Quality Checker] 55 | [Security Scanner] 56 | [Performance Analyzer] 57 | } 58 | 59 | component "test-generator" as TestGen { 60 | [Test Template Engine] 61 | [Coverage Analyzer] 62 | [Assertion Generator] 63 | } 64 | 65 | component "documentation-writer" as DocWriter { 66 | [JSDoc Generator] 67 | [Markdown Builder] 68 | [Diagram Creator] 69 | } 70 | 71 | note right of CodeReview 72 | Custom agents defined in 73 | .claude/agnets/*.md 74 | end note 75 | } 76 | 77 | cloud "Agent Invocation Flow" { 78 | (User Request) as UR 79 | (Agent Selection) as AS 80 | (Prompt Expansion) as PE 81 | (Autonomous Execution) as AE 82 | (Result Report) as RR 83 | } 84 | 85 | UR --> TaskTool 86 | TaskTool --> AS 87 | AS --> GP : complex multi-step 88 | AS --> Explore : codebase exploration 89 | AS --> Plan : architecture planning 90 | AS --> Status : config setup 91 | AS --> CodeReview : code review needed 92 | AS --> TestGen : test generation 93 | AS --> DocWriter : documentation 94 | 95 | AS --> PE 96 | PE --> AE 97 | AE --> RR 98 | 99 | note bottom of AE 100 | Stateless execution: 101 | - No follow-up messages 102 | - Single final report 103 | - Fully autonomous 104 | end note 105 | 106 | ' Connections to tools 107 | [Research Engine] --> GPTools 108 | [Code Search] --> GPTools 109 | [Multi-step Executor] --> GPTools 110 | 111 | [Pattern Matcher] --> ExploreTools 112 | [Keyword Search] --> ExploreTools 113 | [Codebase Analyzer] --> ExploreTools 114 | 115 | [Architecture Planner] --> PlanTools 116 | [Task Breakdown] --> PlanTools 117 | [Dependency Analyzer] --> PlanTools 118 | 119 | [Config Reader] --> StatusTools 120 | [Settings Editor] --> StatusTools 121 | 122 | @enduml 123 | -------------------------------------------------------------------------------- /.claude/agents/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Sub-agents Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Claude Code Sub-agents Architecture 7 | 8 | package "Claude Code Core" { 9 | [Task Tool] as TaskTool 10 | note right of TaskTool 11 | Entry point for all 12 | sub-agent invocations 13 | end note 14 | } 15 | 16 | package "Built-in Sub-agents" { 17 | component "general-purpose" as GP { 18 | [Research Engine] 19 | [Code Search] 20 | [Multi-step Executor] 21 | database "All Tools (*)" as GPTools 22 | } 23 | 24 | component "Explore" as Explore { 25 | [Pattern Matcher] 26 | [Keyword Search] 27 | [Codebase Analyzer] 28 | database "All Tools" as ExploreTools 29 | 30 | note bottom of Explore 31 | Thoroughness Levels: 32 | - quick 33 | - medium 34 | - very thorough 35 | end note 36 | } 37 | 38 | component "Plan" as Plan { 39 | [Architecture Planner] 40 | [Task Breakdown] 41 | [Dependency Analyzer] 42 | database "All Tools" as PlanTools 43 | } 44 | 45 | component "statusline-setup" as Status { 46 | [Config Reader] 47 | [Settings Editor] 48 | database "Read, Edit" as StatusTools 49 | } 50 | } 51 | 52 | package "Custom Sub-agents" { 53 | component "code-reviewer" as CodeReview { 54 | [Quality Checker] 55 | [Security Scanner] 56 | [Performance Analyzer] 57 | } 58 | 59 | component "test-generator" as TestGen { 60 | [Test Template Engine] 61 | [Coverage Analyzer] 62 | [Assertion Generator] 63 | } 64 | 65 | component "documentation-writer" as DocWriter { 66 | [JSDoc Generator] 67 | [Markdown Builder] 68 | [Diagram Creator] 69 | } 70 | 71 | note right of CodeReview 72 | Custom agents defined in 73 | .claude/agnets/*.md 74 | end note 75 | } 76 | 77 | cloud "Agent Invocation Flow" { 78 | (User Request) as UR 79 | (Agent Selection) as AS 80 | (Prompt Expansion) as PE 81 | (Autonomous Execution) as AE 82 | (Result Report) as RR 83 | } 84 | 85 | UR --> TaskTool 86 | TaskTool --> AS 87 | AS --> GP : complex multi-step 88 | AS --> Explore : codebase exploration 89 | AS --> Plan : architecture planning 90 | AS --> Status : config setup 91 | AS --> CodeReview : code review needed 92 | AS --> TestGen : test generation 93 | AS --> DocWriter : documentation 94 | 95 | AS --> PE 96 | PE --> AE 97 | AE --> RR 98 | 99 | note bottom of AE 100 | Stateless execution: 101 | - No follow-up messages 102 | - Single final report 103 | - Fully autonomous 104 | end note 105 | 106 | ' Connections to tools 107 | [Research Engine] --> GPTools 108 | [Code Search] --> GPTools 109 | [Multi-step Executor] --> GPTools 110 | 111 | [Pattern Matcher] --> ExploreTools 112 | [Keyword Search] --> ExploreTools 113 | [Codebase Analyzer] --> ExploreTools 114 | 115 | [Architecture Planner] --> PlanTools 116 | [Task Breakdown] --> PlanTools 117 | [Dependency Analyzer] --> PlanTools 118 | 119 | [Config Reader] --> StatusTools 120 | [Settings Editor] --> StatusTools 121 | 122 | @enduml 123 | -------------------------------------------------------------------------------- /.claude/orchestrator-architecture.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator-Subagent Architecture 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Orchestrator-Subagent Architecture\nImplementation of Director-Worker Pattern 7 | 8 | ' User Request 9 | actor User as user 10 | rectangle "User Request" as UR #LightBlue { 11 | [Request ID] 12 | [Content] 13 | [Context] 14 | } 15 | 16 | ' Orchestrator Agent 17 | package "Orchestrator Agent" as orchestrator #LightGreen { 18 | component "θ₁ Analyze\nRequest" as analyze 19 | component "θ₂ Decompose\nTasks" as decompose 20 | component "θ₃ Allocate\nResources" as allocate 21 | component "θ₄ Execute\nTasks" as execute 22 | component "θ₅ Integrate\nResults" as synthesize 23 | component "θ₆ Learn\n(Future)" as learn 24 | 25 | analyze -down-> decompose 26 | decompose -down-> allocate 27 | allocate -down-> execute 28 | execute -down-> synthesize 29 | synthesize -down-> learn 30 | } 31 | 32 | ' Isolated Execution Environment 33 | frame "Isolated Execution Environment" as isolation #LightYellow { 34 | 35 | ' Subagent 1 36 | package "Subagent 1" as sub1 #LightCoral { 37 | component "Own Context" as ctx1 38 | component "Own Tools\n(Read, Write, Bash)" as tools1 39 | component "Solves Task A" as solve1 40 | 41 | ctx1 -down-> tools1 42 | tools1 -down-> solve1 43 | } 44 | 45 | ' Subagent 2 46 | package "Subagent 2" as sub2 #LightSkyBlue { 47 | component "Own Context" as ctx2 48 | component "Own Tools\n(Read, Write, Bash)" as tools2 49 | component "Solves Task B" as solve2 50 | 51 | ctx2 -down-> tools2 52 | tools2 -down-> solve2 53 | } 54 | 55 | ' Subagent N 56 | package "Subagent n..." as subn #LightSalmon { 57 | component "Own Context" as ctxn 58 | component "Own Tools\n(Read, Write, Bash)" as toolsn 59 | component "Solves Task C" as solven 60 | 61 | ctxn -down-> toolsn 62 | toolsn -down-> solven 63 | } 64 | } 65 | 66 | ' Results 67 | rectangle "Subagent Results" as results #LightPink { 68 | [Task ID] 69 | [Output] 70 | [Artifacts] 71 | [Execution Time] 72 | } 73 | 74 | ' Final Answer 75 | rectangle "Final Answer" as final #LightGreen { 76 | [Request ID] 77 | [Synthesized Answer] 78 | [All Results] 79 | [Total Time] 80 | } 81 | 82 | ' Flow 83 | user --> UR : submits 84 | UR --> analyze : process() 85 | 86 | execute --> sub1 : delegate Task A 87 | execute --> sub2 : delegate Task B 88 | execute --> subn : delegate Task C 89 | 90 | sub1 --> results : result 1 91 | sub2 --> results : result 2 92 | subn --> results : result n 93 | 94 | results --> synthesize : collect all 95 | synthesize --> final : generate 96 | final --> user : return 97 | 98 | ' Notes 99 | note right of isolation 100 | **Parallel Execution** 101 | - Each subagent runs independently 102 | - Own isolated context 103 | - No shared state 104 | - Concurrent execution 105 | end note 106 | 107 | note left of orchestrator 108 | **Orchestrator Responsibilities** 109 | 1. Analyze user request 110 | 2. Break into subtasks 111 | 3. Select appropriate subagents 112 | 4. Monitor execution 113 | 5. Synthesize final answer 114 | 6. Learn from results (future) 115 | end note 116 | 117 | note bottom of final 118 | **Performance** 119 | Sequential: Task₁ + Task₂ + Task₃ = 300ms 120 | Parallel: max(Task₁, Task₂, Task₃) ≈ 100ms 121 | Speedup: 3x (with 3 tasks) 122 | end note 123 | 124 | @enduml 125 | -------------------------------------------------------------------------------- /.codex/orchestrator-architecture.puml: -------------------------------------------------------------------------------- 1 | @startuml Orchestrator-Subagent Architecture 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Orchestrator-Subagent Architecture\nImplementation of Director-Worker Pattern 7 | 8 | ' User Request 9 | actor User as user 10 | rectangle "User Request" as UR #LightBlue { 11 | [Request ID] 12 | [Content] 13 | [Context] 14 | } 15 | 16 | ' Orchestrator Agent 17 | package "Orchestrator Agent" as orchestrator #LightGreen { 18 | component "θ₁ Analyze\nRequest" as analyze 19 | component "θ₂ Decompose\nTasks" as decompose 20 | component "θ₃ Allocate\nResources" as allocate 21 | component "θ₄ Execute\nTasks" as execute 22 | component "θ₅ Integrate\nResults" as synthesize 23 | component "θ₆ Learn\n(Future)" as learn 24 | 25 | analyze -down-> decompose 26 | decompose -down-> allocate 27 | allocate -down-> execute 28 | execute -down-> synthesize 29 | synthesize -down-> learn 30 | } 31 | 32 | ' Isolated Execution Environment 33 | frame "Isolated Execution Environment" as isolation #LightYellow { 34 | 35 | ' Subagent 1 36 | package "Subagent 1" as sub1 #LightCoral { 37 | component "Own Context" as ctx1 38 | component "Own Tools\n(Read, Write, Bash)" as tools1 39 | component "Solves Task A" as solve1 40 | 41 | ctx1 -down-> tools1 42 | tools1 -down-> solve1 43 | } 44 | 45 | ' Subagent 2 46 | package "Subagent 2" as sub2 #LightSkyBlue { 47 | component "Own Context" as ctx2 48 | component "Own Tools\n(Read, Write, Bash)" as tools2 49 | component "Solves Task B" as solve2 50 | 51 | ctx2 -down-> tools2 52 | tools2 -down-> solve2 53 | } 54 | 55 | ' Subagent N 56 | package "Subagent n..." as subn #LightSalmon { 57 | component "Own Context" as ctxn 58 | component "Own Tools\n(Read, Write, Bash)" as toolsn 59 | component "Solves Task C" as solven 60 | 61 | ctxn -down-> toolsn 62 | toolsn -down-> solven 63 | } 64 | } 65 | 66 | ' Results 67 | rectangle "Subagent Results" as results #LightPink { 68 | [Task ID] 69 | [Output] 70 | [Artifacts] 71 | [Execution Time] 72 | } 73 | 74 | ' Final Answer 75 | rectangle "Final Answer" as final #LightGreen { 76 | [Request ID] 77 | [Synthesized Answer] 78 | [All Results] 79 | [Total Time] 80 | } 81 | 82 | ' Flow 83 | user --> UR : submits 84 | UR --> analyze : process() 85 | 86 | execute --> sub1 : delegate Task A 87 | execute --> sub2 : delegate Task B 88 | execute --> subn : delegate Task C 89 | 90 | sub1 --> results : result 1 91 | sub2 --> results : result 2 92 | subn --> results : result n 93 | 94 | results --> synthesize : collect all 95 | synthesize --> final : generate 96 | final --> user : return 97 | 98 | ' Notes 99 | note right of isolation 100 | **Parallel Execution** 101 | - Each subagent runs independently 102 | - Own isolated context 103 | - No shared state 104 | - Concurrent execution 105 | end note 106 | 107 | note left of orchestrator 108 | **Orchestrator Responsibilities** 109 | 1. Analyze user request 110 | 2. Break into subtasks 111 | 3. Select appropriate subagents 112 | 4. Monitor execution 113 | 5. Synthesize final answer 114 | 6. Learn from results (future) 115 | end note 116 | 117 | note bottom of final 118 | **Performance** 119 | Sequential: Task₁ + Task₂ + Task₃ = 300ms 120 | Parallel: max(Task₁, Task₂, Task₃) ≈ 100ms 121 | Speedup: 3x (with 3 tasks) 122 | end note 123 | 124 | @enduml 125 | -------------------------------------------------------------------------------- /.codex/hooks/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Hooks Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam sequenceArrowThickness 2 5 | 6 | title Claude Code Hooks Architecture 7 | 8 | actor User 9 | participant "Claude Code" as Claude 10 | participant "Hook Manager" as HookMgr 11 | participant "Shell Executor" as Shell 12 | 13 | box "Event Triggers" #LightBlue 14 | participant "user-prompt-submit" as PromptHook 15 | participant "tool-call" as ToolHook 16 | participant "pre-commit" as CommitHook 17 | end box 18 | 19 | box "Hook Scripts" #LightGreen 20 | participant "backup-on-write.sh" as BackupScript 21 | participant "pre-commit-lint.sh" as LintScript 22 | participant "run-tests.sh" as TestScript 23 | participant "log-activity.sh" as LogScript 24 | end box 25 | 26 | database "Settings" as Settings { 27 | [~/.claude/settings.json] 28 | [.claude/settings.json] 29 | } 30 | 31 | == User Prompt Submit Hook == 32 | User -> Claude: Submit Prompt 33 | Claude -> HookMgr: trigger(user-prompt-submit) 34 | HookMgr -> Settings: load hook config 35 | Settings --> HookMgr: hook definition 36 | HookMgr -> PromptHook: check enabled 37 | alt Hook Enabled 38 | PromptHook -> Shell: execute command 39 | Shell -> TestScript: run 40 | TestScript --> Shell: exit code 41 | Shell --> HookMgr: result 42 | HookMgr --> Claude: feedback 43 | note right 44 | Feedback treated as 45 | user input 46 | end note 47 | else Hook Disabled 48 | HookMgr --> Claude: skip 49 | end 50 | 51 | == Tool Call Hook (Write) == 52 | Claude -> HookMgr: trigger(tool-call:Write) 53 | HookMgr -> Settings: load hook config 54 | Settings --> HookMgr: Write hook definition 55 | HookMgr -> ToolHook: check enabled & match tool 56 | alt Hook Matches & Enabled 57 | ToolHook -> Shell: execute with ${file_path} 58 | Shell -> BackupScript: create backup 59 | BackupScript --> Shell: backup created 60 | Shell --> HookMgr: success 61 | HookMgr --> Claude: proceed with write 62 | else No Match or Disabled 63 | HookMgr --> Claude: proceed 64 | end 65 | 66 | == Pre-commit Hook == 67 | Claude -> HookMgr: trigger(pre-commit) 68 | HookMgr -> Settings: load hook config 69 | Settings --> HookMgr: pre-commit definition 70 | HookMgr -> CommitHook: check enabled 71 | alt Hook Enabled 72 | CommitHook -> Shell: execute command 73 | Shell -> LintScript: run lint 74 | LintScript --> Shell: exit code 75 | 76 | alt Exit Code = 0 77 | Shell --> HookMgr: passed 78 | HookMgr --> Claude: allow commit 79 | Claude -> User: commit successful 80 | else Exit Code != 0 81 | Shell --> HookMgr: failed 82 | HookMgr --> Claude: block commit 83 | note right 84 | failureMode determines 85 | behavior: 86 | - error: block 87 | - warn: allow with warning 88 | - ignore: silent 89 | end note 90 | Claude -> User: commit blocked 91 | end 92 | else Hook Disabled 93 | HookMgr --> Claude: allow commit 94 | end 95 | 96 | == Tool Call Hook (All Tools - Logging) == 97 | Claude -> HookMgr: trigger(tool-call:*) 98 | HookMgr -> Settings: load hook config 99 | Settings --> HookMgr: wildcard hook 100 | HookMgr -> ToolHook: check wildcard match 101 | ToolHook -> Shell: execute log script 102 | Shell -> LogScript: log activity 103 | note right of LogScript 104 | Environment Variables: 105 | - $CLAUDE_PROJECT_DIR 106 | - $CLAUDE_TOOL_NAME 107 | - $CLAUDE_TOOL_PARAMS 108 | end note 109 | LogScript --> Shell: logged 110 | Shell --> HookMgr: success (ignore failures) 111 | HookMgr --> Claude: continue 112 | 113 | @enduml 114 | -------------------------------------------------------------------------------- /.claude/hooks/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Hooks Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam sequenceArrowThickness 2 5 | 6 | title Claude Code Hooks Architecture 7 | 8 | actor User 9 | participant "Claude Code" as Claude 10 | participant "Hook Manager" as HookMgr 11 | participant "Shell Executor" as Shell 12 | 13 | box "Event Triggers" #LightBlue 14 | participant "user-prompt-submit" as PromptHook 15 | participant "tool-call" as ToolHook 16 | participant "pre-commit" as CommitHook 17 | end box 18 | 19 | box "Hook Scripts" #LightGreen 20 | participant "backup-on-write.sh" as BackupScript 21 | participant "pre-commit-lint.sh" as LintScript 22 | participant "run-tests.sh" as TestScript 23 | participant "log-activity.sh" as LogScript 24 | end box 25 | 26 | database "Settings" as Settings { 27 | [~/.claude/settings.json] 28 | [.claude/settings.json] 29 | } 30 | 31 | == User Prompt Submit Hook == 32 | User -> Claude: Submit Prompt 33 | Claude -> HookMgr: trigger(user-prompt-submit) 34 | HookMgr -> Settings: load hook config 35 | Settings --> HookMgr: hook definition 36 | HookMgr -> PromptHook: check enabled 37 | alt Hook Enabled 38 | PromptHook -> Shell: execute command 39 | Shell -> TestScript: run 40 | TestScript --> Shell: exit code 41 | Shell --> HookMgr: result 42 | HookMgr --> Claude: feedback 43 | note right 44 | Feedback treated as 45 | user input 46 | end note 47 | else Hook Disabled 48 | HookMgr --> Claude: skip 49 | end 50 | 51 | == Tool Call Hook (Write) == 52 | Claude -> HookMgr: trigger(tool-call:Write) 53 | HookMgr -> Settings: load hook config 54 | Settings --> HookMgr: Write hook definition 55 | HookMgr -> ToolHook: check enabled & match tool 56 | alt Hook Matches & Enabled 57 | ToolHook -> Shell: execute with ${file_path} 58 | Shell -> BackupScript: create backup 59 | BackupScript --> Shell: backup created 60 | Shell --> HookMgr: success 61 | HookMgr --> Claude: proceed with write 62 | else No Match or Disabled 63 | HookMgr --> Claude: proceed 64 | end 65 | 66 | == Pre-commit Hook == 67 | Claude -> HookMgr: trigger(pre-commit) 68 | HookMgr -> Settings: load hook config 69 | Settings --> HookMgr: pre-commit definition 70 | HookMgr -> CommitHook: check enabled 71 | alt Hook Enabled 72 | CommitHook -> Shell: execute command 73 | Shell -> LintScript: run lint 74 | LintScript --> Shell: exit code 75 | 76 | alt Exit Code = 0 77 | Shell --> HookMgr: passed 78 | HookMgr --> Claude: allow commit 79 | Claude -> User: commit successful 80 | else Exit Code != 0 81 | Shell --> HookMgr: failed 82 | HookMgr --> Claude: block commit 83 | note right 84 | failureMode determines 85 | behavior: 86 | - error: block 87 | - warn: allow with warning 88 | - ignore: silent 89 | end note 90 | Claude -> User: commit blocked 91 | end 92 | else Hook Disabled 93 | HookMgr --> Claude: allow commit 94 | end 95 | 96 | == Tool Call Hook (All Tools - Logging) == 97 | Claude -> HookMgr: trigger(tool-call:*) 98 | HookMgr -> Settings: load hook config 99 | Settings --> HookMgr: wildcard hook 100 | HookMgr -> ToolHook: check wildcard match 101 | ToolHook -> Shell: execute log script 102 | Shell -> LogScript: log activity 103 | note right of LogScript 104 | Environment Variables: 105 | - $CLAUDE_PROJECT_DIR 106 | - $CLAUDE_TOOL_NAME 107 | - $CLAUDE_TOOL_PARAMS 108 | end note 109 | LogScript --> Shell: logged 110 | Shell --> HookMgr: success (ignore failures) 111 | HookMgr --> Claude: continue 112 | 113 | @enduml 114 | -------------------------------------------------------------------------------- /docs/references.bib: -------------------------------------------------------------------------------- 1 | @article{fikes1971strips, 2 | title={{STRIPS}: A new approach to the application of theorem proving to problem solving}, 3 | author={Fikes, Richard E and Nilsson, Nils J}, 4 | journal={Artificial intelligence}, 5 | volume={2}, 6 | number={3-4}, 7 | pages={189--208}, 8 | year={1971}, 9 | publisher={Elsevier} 10 | } 11 | 12 | @inproceedings{mcdermott1998pddl, 13 | title={{PDDL}---the planning domain definition language}, 14 | author={McDermott, Drew and Ghallab, Malik and Howe, Adele and Knoblock, Craig and Ram, Ashwin and Veloso, Manuela and Weld, Daniel and Wilkins, David}, 15 | year={1998} 16 | } 17 | 18 | @inproceedings{rao1995bdi, 19 | title={{BDI} agents: From theory to practice}, 20 | author={Rao, Anand S and Georgeff, Michael P}, 21 | booktitle={ICMAS}, 22 | volume={95}, 23 | pages={312--319}, 24 | year={1995} 25 | } 26 | 27 | @inproceedings{yao2023react, 28 | title={{ReAct}: Synergizing reasoning and acting in language models}, 29 | author={Yao, Shunyu and Zhao, Jeffrey and Yu, Dian and Du, Nan and Shafran, Izhak and Narasimhan, Karthik and Cao, Yuan}, 30 | booktitle={International Conference on Learning Representations}, 31 | year={2023} 32 | } 33 | 34 | @misc{autogpt2023, 35 | title={{AutoGPT}}, 36 | author={{Significant Gravitas}}, 37 | howpublished={\url{https://github.com/Significant-Gravitas/AutoGPT}}, 38 | year={2023} 39 | } 40 | 41 | @misc{babyagi2023, 42 | title={{BabyAGI}}, 43 | author={Nakajima, Yohei}, 44 | howpublished={\url{https://github.com/yoheinakajima/babyagi}}, 45 | year={2023} 46 | } 47 | 48 | @article{ha2018world, 49 | title={World models}, 50 | author={Ha, David and Schmidhuber, J{\"u}rgen}, 51 | journal={arXiv preprint arXiv:1803.10122}, 52 | year={2018} 53 | } 54 | 55 | @article{banach1922fixed, 56 | title={Sur les op{\'e}rations dans les ensembles abstraits et leur application aux {\'e}quations int{\'e}grales}, 57 | author={Banach, Stefan}, 58 | journal={Fundamenta mathematicae}, 59 | volume={3}, 60 | number={1}, 61 | pages={133--181}, 62 | year={1922} 63 | } 64 | 65 | @article{brooks1986robust, 66 | title={A robust layered control system for a mobile robot}, 67 | author={Brooks, Rodney A}, 68 | journal={IEEE journal on robotics and automation}, 69 | volume={2}, 70 | number={1}, 71 | pages={14--23}, 72 | year={1986}, 73 | publisher={IEEE} 74 | } 75 | 76 | @book{cassandras2008discrete, 77 | title={Introduction to discrete event systems}, 78 | author={Cassandras, Christos G and Lafortune, Stephane}, 79 | year={2008}, 80 | publisher={Springer Science \& Business Media} 81 | } 82 | 83 | @inproceedings{erol1994htn, 84 | title={{HTN} planning: Complexity and expressivity}, 85 | author={Erol, Kutluhan and Hendler, James and Nau, Dana S}, 86 | booktitle={AAAI}, 87 | volume={94}, 88 | pages={1123--1128}, 89 | year={1994} 90 | } 91 | 92 | @article{mccarthy1969philosophical, 93 | title={Some philosophical problems from the standpoint of artificial intelligence}, 94 | author={McCarthy, John and Hayes, Patrick J}, 95 | journal={Machine intelligence}, 96 | volume={4}, 97 | pages={463--502}, 98 | year={1969} 99 | } 100 | 101 | @inproceedings{orkin2006goap, 102 | title={Three states and a plan: The {AI} of {FEAR}}, 103 | author={Orkin, Jeff}, 104 | booktitle={Game developers conference}, 105 | volume={2006}, 106 | year={2006} 107 | } 108 | 109 | @article{arimoto1984learning, 110 | title={Bettering operation of robots by learning}, 111 | author={Arimoto, Suguru and Kawamura, Sadao and Miyazaki, Fumio}, 112 | journal={Journal of Robotic systems}, 113 | volume={1}, 114 | number={2}, 115 | pages={123--140}, 116 | year={1984}, 117 | publisher={Wiley Online Library} 118 | } 119 | -------------------------------------------------------------------------------- /.claude/agent-lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Agent Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Claude Code Agent Lifecycle - Main Flow 7 | 8 | |User| 9 | start 10 | :Submit Intent/Request; 11 | 12 | |Claude Code Engine| 13 | :θ₁ **Understand** Intent; 14 | note right 15 | Parse user request 16 | Identify task type 17 | Determine required capabilities 18 | end note 19 | 20 | :θ₂ **Generate** Plan; 21 | note right 22 | Break down into steps 23 | Select appropriate tools 24 | Identify Sub-agents/Skills/Commands 25 | end note 26 | 27 | :θ₃ **Allocate** Resources; 28 | note right 29 | Check available tools 30 | Verify permissions 31 | Load context (CLAUDE.md) 32 | Initialize hooks 33 | end note 34 | 35 | |Extension Layer| 36 | if (Requires Sub-agent?) then (yes) 37 | :Invoke Task Tool; 38 | :Select Sub-agent Type; 39 | note right 40 | - general-purpose 41 | - Explore 42 | - Plan 43 | - Custom agents 44 | end note 45 | :Expand Sub-agent Prompt; 46 | :Execute Autonomously; 47 | :Return Final Report; 48 | else if (Requires Skill?) then (yes) 49 | :Invoke Skill Tool; 50 | :Load Skill Definition; 51 | :Expand Skill Prompt; 52 | :Execute Skill Logic; 53 | :Return Skill Results; 54 | else if (Slash Command?) then (yes) 55 | :Invoke SlashCommand Tool; 56 | :Parse Command & Args; 57 | :Expand Command Prompt; 58 | :Execute Command Steps; 59 | :Return Command Results; 60 | else (direct execution) 61 | :Use Core Tools; 62 | note right 63 | Read, Write, Edit, 64 | Bash, Grep, Glob, etc. 65 | end note 66 | endif 67 | 68 | |Hook System| 69 | if (Hook Triggered?) then (yes) 70 | fork 71 | :Execute Hook Script; 72 | fork again 73 | :Continue Main Flow; 74 | end fork 75 | 76 | if (Hook Failed?) then (yes) 77 | if (failureMode = error) then (yes) 78 | :Block Operation; 79 | stop 80 | else if (failureMode = warn) then (yes) 81 | :Show Warning; 82 | :Continue; 83 | else (ignore) 84 | :Silent Continue; 85 | endif 86 | else (passed) 87 | :Continue; 88 | endif 89 | else (no hook) 90 | :Continue; 91 | endif 92 | 93 | |Claude Code Engine| 94 | :θ₄ **Execute** Actions; 95 | note right 96 | Perform planned operations 97 | Handle tool calls 98 | Process sub-agent results 99 | Apply hooks 100 | end note 101 | 102 | if (Execution Successful?) then (yes) 103 | :θ₅ **Integrate** Results; 104 | note right 105 | Combine outputs 106 | Format response 107 | Update context 108 | end note 109 | 110 | :θ₆ **Learn** from Execution; 111 | note right 112 | Update internal state 113 | Refine understanding 114 | Prepare for next iteration 115 | end note 116 | 117 | if (More Steps Required?) then (yes) 118 | :Iterate (n+1); 119 | note right 120 | lim_{n→∞} of composition 121 | Loop back to Understand 122 | end note 123 | detach 124 | else (complete) 125 | :Format Final Response; 126 | endif 127 | else (failed) 128 | :Error Handling; 129 | 130 | if (Can Retry?) then (yes) 131 | :Adjust Strategy; 132 | note right 133 | Return to Generate Plan 134 | end note 135 | detach 136 | else (no) 137 | :Report Error; 138 | endif 139 | endif 140 | 141 | |User| 142 | :Receive Results; 143 | stop 144 | 145 | legend right 146 | |= Phase |= Description | 147 | | θ₁ Understand | Parse and comprehend user intent | 148 | | θ₂ Generate | Create execution plan | 149 | | θ₃ Allocate | Assign resources and tools | 150 | | θ₄ Execute | Perform planned actions | 151 | | θ₅ Integrate | Combine and format results | 152 | | θ₆ Learn | Update state for next iteration | 153 | endlegend 154 | 155 | @enduml 156 | -------------------------------------------------------------------------------- /.codex/agent-lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Agent Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Claude Code Agent Lifecycle - Main Flow 7 | 8 | |User| 9 | start 10 | :Submit Intent/Request; 11 | 12 | |Claude Code Engine| 13 | :θ₁ **Understand** Intent; 14 | note right 15 | Parse user request 16 | Identify task type 17 | Determine required capabilities 18 | end note 19 | 20 | :θ₂ **Generate** Plan; 21 | note right 22 | Break down into steps 23 | Select appropriate tools 24 | Identify Sub-agents/Skills/Commands 25 | end note 26 | 27 | :θ₃ **Allocate** Resources; 28 | note right 29 | Check available tools 30 | Verify permissions 31 | Load context (CLAUDE.md) 32 | Initialize hooks 33 | end note 34 | 35 | |Extension Layer| 36 | if (Requires Sub-agent?) then (yes) 37 | :Invoke Task Tool; 38 | :Select Sub-agent Type; 39 | note right 40 | - general-purpose 41 | - Explore 42 | - Plan 43 | - Custom agents 44 | end note 45 | :Expand Sub-agent Prompt; 46 | :Execute Autonomously; 47 | :Return Final Report; 48 | else if (Requires Skill?) then (yes) 49 | :Invoke Skill Tool; 50 | :Load Skill Definition; 51 | :Expand Skill Prompt; 52 | :Execute Skill Logic; 53 | :Return Skill Results; 54 | else if (Slash Command?) then (yes) 55 | :Invoke SlashCommand Tool; 56 | :Parse Command & Args; 57 | :Expand Command Prompt; 58 | :Execute Command Steps; 59 | :Return Command Results; 60 | else (direct execution) 61 | :Use Core Tools; 62 | note right 63 | Read, Write, Edit, 64 | Bash, Grep, Glob, etc. 65 | end note 66 | endif 67 | 68 | |Hook System| 69 | if (Hook Triggered?) then (yes) 70 | fork 71 | :Execute Hook Script; 72 | fork again 73 | :Continue Main Flow; 74 | end fork 75 | 76 | if (Hook Failed?) then (yes) 77 | if (failureMode = error) then (yes) 78 | :Block Operation; 79 | stop 80 | else if (failureMode = warn) then (yes) 81 | :Show Warning; 82 | :Continue; 83 | else (ignore) 84 | :Silent Continue; 85 | endif 86 | else (passed) 87 | :Continue; 88 | endif 89 | else (no hook) 90 | :Continue; 91 | endif 92 | 93 | |Claude Code Engine| 94 | :θ₄ **Execute** Actions; 95 | note right 96 | Perform planned operations 97 | Handle tool calls 98 | Process sub-agent results 99 | Apply hooks 100 | end note 101 | 102 | if (Execution Successful?) then (yes) 103 | :θ₅ **Integrate** Results; 104 | note right 105 | Combine outputs 106 | Format response 107 | Update context 108 | end note 109 | 110 | :θ₆ **Learn** from Execution; 111 | note right 112 | Update internal state 113 | Refine understanding 114 | Prepare for next iteration 115 | end note 116 | 117 | if (More Steps Required?) then (yes) 118 | :Iterate (n+1); 119 | note right 120 | lim_{n→∞} of composition 121 | Loop back to Understand 122 | end note 123 | detach 124 | else (complete) 125 | :Format Final Response; 126 | endif 127 | else (failed) 128 | :Error Handling; 129 | 130 | if (Can Retry?) then (yes) 131 | :Adjust Strategy; 132 | note right 133 | Return to Generate Plan 134 | end note 135 | detach 136 | else (no) 137 | :Report Error; 138 | endif 139 | endif 140 | 141 | |User| 142 | :Receive Results; 143 | stop 144 | 145 | legend right 146 | |= Phase |= Description | 147 | | θ₁ Understand | Parse and comprehend user intent | 148 | | θ₂ Generate | Create execution plan | 149 | | θ₃ Allocate | Assign resources and tools | 150 | | θ₄ Execute | Perform planned actions | 151 | | θ₅ Integrate | Combine and format results | 152 | | θ₆ Learn | Update state for next iteration | 153 | endlegend 154 | 155 | @enduml 156 | -------------------------------------------------------------------------------- /.claude/before-after-comparison.puml: -------------------------------------------------------------------------------- 1 | @startuml Before vs After Architecture 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam defaultFontSize 11 5 | 6 | title Architecture Evolution: Single Agent → Orchestrator-Subagent 7 | 8 | ' Before: Single Large Agent 9 | package "❌ Before: Single Large Agent" as before #FFE6E6 { 10 | 11 | rectangle "User Request" as req1 #LightBlue 12 | 13 | rectangle "**Single Large Agent**" as single #LightCoral { 14 | component "Context: 200K tokens" as ctx_large 15 | component "Tools: 50+ tools\n(Read, Write, Bash, Grep, Glob, Edit...)" as tools_large 16 | component "Tasks: All tasks mixed" as tasks_large 17 | 18 | ctx_large -down-> tools_large 19 | tools_large -down-> tasks_large 20 | } 21 | 22 | rectangle "Problems" as problems #Pink { 23 | note as N1 24 | ❌ Context becomes cluttered 25 | ❌ Tool selection unreliable 26 | ❌ Sequential execution (slow) 27 | ❌ Hard to debug 28 | ❌ Single point of failure 29 | end note 30 | } 31 | 32 | rectangle "Result\n(after 300ms)" as res1 #LightBlue 33 | 34 | req1 -down-> single 35 | single -down-> problems 36 | problems -down-> res1 37 | } 38 | 39 | ' Separator 40 | note as separator 41 | ═══════════════════════════════════════════════════════════ 42 | TRANSFORMATION 43 | ═══════════════════════════════════════════════════════════ 44 | end note 45 | 46 | ' After: Orchestrator-Subagent 47 | package "✅ After: Orchestrator-Subagent" as after #E6FFE6 { 48 | 49 | rectangle "User Request" as req2 #LightBlue 50 | 51 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━" as orch #LightGreen { 52 | component "θ₁ Analyze" as analyze 53 | component "θ₂ Decompose" as decompose 54 | component "θ₃ Delegate" as delegate 55 | 56 | analyze -down-> decompose 57 | decompose -down-> delegate 58 | } 59 | 60 | frame "Isolated Execution (Parallel)" as iso #LightYellow { 61 | 62 | rectangle "**Subagent 1**" as sub1 #LightCoral { 63 | component "Context: 50K" as ctx1 64 | component "Tools: 5" as tools1 65 | component "Task A" as task1 66 | 67 | ctx1 -down-> tools1 68 | tools1 -down-> task1 69 | } 70 | 71 | rectangle "**Subagent 2**" as sub2 #LightSkyBlue { 72 | component "Context: 50K" as ctx2 73 | component "Tools: 5" as tools2 74 | component "Task B" as task2 75 | 76 | ctx2 -down-> tools2 77 | tools2 -down-> task2 78 | } 79 | 80 | rectangle "**Subagent 3**" as sub3 #LightSalmon { 81 | component "Context: 50K" as ctx3 82 | component "Tools: 5" as tools3 83 | component "Task C" as task3 84 | 85 | ctx3 -down-> tools3 86 | tools3 -down-> task3 87 | } 88 | } 89 | 90 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━" as synth #LightGreen { 91 | component "θ₅ Synthesize" as synthesize 92 | } 93 | 94 | rectangle "Benefits" as benefits #LightGreen { 95 | note as N2 96 | ✅ Focused context (4x smaller) 97 | ✅ Reliable tool selection 98 | ✅ Parallel execution (3x faster) 99 | ✅ Easy to debug 100 | ✅ Failure isolation 101 | end note 102 | } 103 | 104 | rectangle "Result\n(after 100ms)" as res2 #LightBlue 105 | 106 | req2 -down-> orch 107 | orch -down-> iso 108 | 109 | iso --> sub1 110 | iso --> sub2 111 | iso --> sub3 112 | 113 | sub1 -down-> synth 114 | sub2 -down-> synth 115 | sub3 -down-> synth 116 | 117 | synth -down-> benefits 118 | benefits -down-> res2 119 | } 120 | 121 | ' Performance Comparison 122 | note bottom of before 123 | **Performance** 124 | Sequential: 300ms 125 | Context: Cluttered (200K) 126 | Success Rate: 70% 127 | end note 128 | 129 | note bottom of after 130 | **Performance** 131 | Parallel: 100ms (3x faster) 132 | Context: Clean (50K each) 133 | Success Rate: 95% 134 | end note 135 | 136 | @enduml 137 | -------------------------------------------------------------------------------- /.codex/before-after-comparison.puml: -------------------------------------------------------------------------------- 1 | @startuml Before vs After Architecture 2 | 3 | skinparam backgroundColor #FEFEFE 4 | skinparam defaultFontSize 11 5 | 6 | title Architecture Evolution: Single Agent → Orchestrator-Subagent 7 | 8 | ' Before: Single Large Agent 9 | package "❌ Before: Single Large Agent" as before #FFE6E6 { 10 | 11 | rectangle "User Request" as req1 #LightBlue 12 | 13 | rectangle "**Single Large Agent**" as single #LightCoral { 14 | component "Context: 200K tokens" as ctx_large 15 | component "Tools: 50+ tools\n(Read, Write, Bash, Grep, Glob, Edit...)" as tools_large 16 | component "Tasks: All tasks mixed" as tasks_large 17 | 18 | ctx_large -down-> tools_large 19 | tools_large -down-> tasks_large 20 | } 21 | 22 | rectangle "Problems" as problems #Pink { 23 | note as N1 24 | ❌ Context becomes cluttered 25 | ❌ Tool selection unreliable 26 | ❌ Sequential execution (slow) 27 | ❌ Hard to debug 28 | ❌ Single point of failure 29 | end note 30 | } 31 | 32 | rectangle "Result\n(after 300ms)" as res1 #LightBlue 33 | 34 | req1 -down-> single 35 | single -down-> problems 36 | problems -down-> res1 37 | } 38 | 39 | ' Separator 40 | note as separator 41 | ═══════════════════════════════════════════════════════════ 42 | TRANSFORMATION 43 | ═══════════════════════════════════════════════════════════ 44 | end note 45 | 46 | ' After: Orchestrator-Subagent 47 | package "✅ After: Orchestrator-Subagent" as after #E6FFE6 { 48 | 49 | rectangle "User Request" as req2 #LightBlue 50 | 51 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━" as orch #LightGreen { 52 | component "θ₁ Analyze" as analyze 53 | component "θ₂ Decompose" as decompose 54 | component "θ₃ Delegate" as delegate 55 | 56 | analyze -down-> decompose 57 | decompose -down-> delegate 58 | } 59 | 60 | frame "Isolated Execution (Parallel)" as iso #LightYellow { 61 | 62 | rectangle "**Subagent 1**" as sub1 #LightCoral { 63 | component "Context: 50K" as ctx1 64 | component "Tools: 5" as tools1 65 | component "Task A" as task1 66 | 67 | ctx1 -down-> tools1 68 | tools1 -down-> task1 69 | } 70 | 71 | rectangle "**Subagent 2**" as sub2 #LightSkyBlue { 72 | component "Context: 50K" as ctx2 73 | component "Tools: 5" as tools2 74 | component "Task B" as task2 75 | 76 | ctx2 -down-> tools2 77 | tools2 -down-> task2 78 | } 79 | 80 | rectangle "**Subagent 3**" as sub3 #LightSalmon { 81 | component "Context: 50K" as ctx3 82 | component "Tools: 5" as tools3 83 | component "Task C" as task3 84 | 85 | ctx3 -down-> tools3 86 | tools3 -down-> task3 87 | } 88 | } 89 | 90 | rectangle "**Orchestrator Agent**\n━━━━━━━━━━━━━━━━━━━━" as synth #LightGreen { 91 | component "θ₅ Synthesize" as synthesize 92 | } 93 | 94 | rectangle "Benefits" as benefits #LightGreen { 95 | note as N2 96 | ✅ Focused context (4x smaller) 97 | ✅ Reliable tool selection 98 | ✅ Parallel execution (3x faster) 99 | ✅ Easy to debug 100 | ✅ Failure isolation 101 | end note 102 | } 103 | 104 | rectangle "Result\n(after 100ms)" as res2 #LightBlue 105 | 106 | req2 -down-> orch 107 | orch -down-> iso 108 | 109 | iso --> sub1 110 | iso --> sub2 111 | iso --> sub3 112 | 113 | sub1 -down-> synth 114 | sub2 -down-> synth 115 | sub3 -down-> synth 116 | 117 | synth -down-> benefits 118 | benefits -down-> res2 119 | } 120 | 121 | ' Performance Comparison 122 | note bottom of before 123 | **Performance** 124 | Sequential: 300ms 125 | Context: Cluttered (200K) 126 | Success Rate: 70% 127 | end note 128 | 129 | note bottom of after 130 | **Performance** 131 | Parallel: 100ms (3x faster) 132 | Context: Clean (50K each) 133 | Success Rate: 95% 134 | end note 135 | 136 | @enduml 137 | -------------------------------------------------------------------------------- /.claude/agents/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Sub-agent Execution Lifecycle 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Sub-agent Execution Lifecycle 7 | 8 | |Main Agent| 9 | start 10 | :Identify Need for Sub-agent; 11 | note right 12 | Conditions: 13 | - Complex multi-step task 14 | - Codebase exploration 15 | - Planning required 16 | - Specialized capability 17 | end note 18 | 19 | :Select Sub-agent Type; 20 | if (Task Type?) then (multi-step research) 21 | :general-purpose; 22 | else if (codebase exploration) 23 | :Explore; 24 | else if (architecture planning) 25 | :Plan; 26 | else (custom task) 27 | :Custom Sub-agent; 28 | endif 29 | 30 | :Prepare Invocation; 31 | note right 32 | - Define task description 33 | - Set thoroughness level 34 | - Specify expected output 35 | - Include context 36 | end note 37 | 38 | |Task Tool| 39 | :Invoke Task Tool; 40 | :Validate Parameters; 41 | note right 42 | Required: 43 | - subagent_type 44 | - prompt 45 | - description 46 | 47 | Optional: 48 | - model (sonnet/opus/haiku) 49 | - resume (agent ID) 50 | end note 51 | 52 | if (Resume from Previous?) then (yes) 53 | :Load Previous Transcript; 54 | :Continue from Checkpoint; 55 | else (new execution) 56 | :Initialize New Agent; 57 | endif 58 | 59 | |Sub-agent Instance| 60 | partition "Autonomous Execution" { 61 | :Receive Expanded Prompt; 62 | note right 63 | Agent has access to: 64 | - Full conversation history 65 | - Current context 66 | - All specified tools 67 | end note 68 | 69 | :Parse Task Requirements; 70 | 71 | repeat 72 | :Select Appropriate Tool; 73 | 74 | if (Tool Type?) then (Read) 75 | :Read Files; 76 | else if (Grep) 77 | :Search Code; 78 | else if (Glob) 79 | :Find Files; 80 | else if (Bash) 81 | :Execute Commands; 82 | else if (WebFetch) 83 | :Fetch Web Content; 84 | else (other) 85 | :Use Other Tools; 86 | endif 87 | 88 | :Process Tool Results; 89 | :Update Internal State; 90 | 91 | if (Task Complete?) then (yes) 92 | :Prepare Final Report; 93 | else if (Error Encountered?) then (yes) 94 | if (Can Recover?) then (yes) 95 | :Adjust Strategy; 96 | :Continue; 97 | else (no) 98 | :Report Error; 99 | :Prepare Partial Results; 100 | endif 101 | else (continue) 102 | :Plan Next Action; 103 | endif 104 | 105 | repeat while (More Steps Needed?) is (yes) 106 | ->no; 107 | 108 | :Compile Final Report; 109 | note right 110 | Report includes: 111 | - Task completion status 112 | - Findings/Results 113 | - Recommendations 114 | - Any errors encountered 115 | end note 116 | } 117 | 118 | |Task Tool| 119 | :Receive Agent Report; 120 | :Validate Output; 121 | 122 | if (Output Valid?) then (yes) 123 | :Return to Main Agent; 124 | else (invalid) 125 | :Handle Error; 126 | :Return Error Report; 127 | endif 128 | 129 | |Main Agent| 130 | :Process Sub-agent Results; 131 | 132 | if (Results Satisfactory?) then (yes) 133 | :Continue with Main Task; 134 | else if (Need More Info?) then (yes) 135 | :Invoke Another Sub-agent; 136 | backward :Return to Select; 137 | else (failed) 138 | :Handle Failure; 139 | :Report to User; 140 | endif 141 | 142 | :Integrate Results; 143 | stop 144 | 145 | note bottom 146 | **Key Characteristics:** 147 | 1. Stateless - Each invocation is independent 148 | 2. Autonomous - No mid-execution communication 149 | 3. Single Output - One final report only 150 | 4. Context-aware - Has access to conversation history 151 | 5. Tool-rich - Can use all specified tools 152 | end note 153 | 154 | legend right 155 | |= Thoroughness Level |= Behavior | 156 | | quick | Basic search, fast execution | 157 | | medium | Moderate exploration, balanced | 158 | | very thorough | Comprehensive analysis, slower | 159 | endlegend 160 | 161 | @enduml 162 | -------------------------------------------------------------------------------- /.codex/agents/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Sub-agent Execution Lifecycle 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Sub-agent Execution Lifecycle 7 | 8 | |Main Agent| 9 | start 10 | :Identify Need for Sub-agent; 11 | note right 12 | Conditions: 13 | - Complex multi-step task 14 | - Codebase exploration 15 | - Planning required 16 | - Specialized capability 17 | end note 18 | 19 | :Select Sub-agent Type; 20 | if (Task Type?) then (multi-step research) 21 | :general-purpose; 22 | else if (codebase exploration) 23 | :Explore; 24 | else if (architecture planning) 25 | :Plan; 26 | else (custom task) 27 | :Custom Sub-agent; 28 | endif 29 | 30 | :Prepare Invocation; 31 | note right 32 | - Define task description 33 | - Set thoroughness level 34 | - Specify expected output 35 | - Include context 36 | end note 37 | 38 | |Task Tool| 39 | :Invoke Task Tool; 40 | :Validate Parameters; 41 | note right 42 | Required: 43 | - subagent_type 44 | - prompt 45 | - description 46 | 47 | Optional: 48 | - model (sonnet/opus/haiku) 49 | - resume (agent ID) 50 | end note 51 | 52 | if (Resume from Previous?) then (yes) 53 | :Load Previous Transcript; 54 | :Continue from Checkpoint; 55 | else (new execution) 56 | :Initialize New Agent; 57 | endif 58 | 59 | |Sub-agent Instance| 60 | partition "Autonomous Execution" { 61 | :Receive Expanded Prompt; 62 | note right 63 | Agent has access to: 64 | - Full conversation history 65 | - Current context 66 | - All specified tools 67 | end note 68 | 69 | :Parse Task Requirements; 70 | 71 | repeat 72 | :Select Appropriate Tool; 73 | 74 | if (Tool Type?) then (Read) 75 | :Read Files; 76 | else if (Grep) 77 | :Search Code; 78 | else if (Glob) 79 | :Find Files; 80 | else if (Bash) 81 | :Execute Commands; 82 | else if (WebFetch) 83 | :Fetch Web Content; 84 | else (other) 85 | :Use Other Tools; 86 | endif 87 | 88 | :Process Tool Results; 89 | :Update Internal State; 90 | 91 | if (Task Complete?) then (yes) 92 | :Prepare Final Report; 93 | else if (Error Encountered?) then (yes) 94 | if (Can Recover?) then (yes) 95 | :Adjust Strategy; 96 | :Continue; 97 | else (no) 98 | :Report Error; 99 | :Prepare Partial Results; 100 | endif 101 | else (continue) 102 | :Plan Next Action; 103 | endif 104 | 105 | repeat while (More Steps Needed?) is (yes) 106 | ->no; 107 | 108 | :Compile Final Report; 109 | note right 110 | Report includes: 111 | - Task completion status 112 | - Findings/Results 113 | - Recommendations 114 | - Any errors encountered 115 | end note 116 | } 117 | 118 | |Task Tool| 119 | :Receive Agent Report; 120 | :Validate Output; 121 | 122 | if (Output Valid?) then (yes) 123 | :Return to Main Agent; 124 | else (invalid) 125 | :Handle Error; 126 | :Return Error Report; 127 | endif 128 | 129 | |Main Agent| 130 | :Process Sub-agent Results; 131 | 132 | if (Results Satisfactory?) then (yes) 133 | :Continue with Main Task; 134 | else if (Need More Info?) then (yes) 135 | :Invoke Another Sub-agent; 136 | backward :Return to Select; 137 | else (failed) 138 | :Handle Failure; 139 | :Report to User; 140 | endif 141 | 142 | :Integrate Results; 143 | stop 144 | 145 | note bottom 146 | **Key Characteristics:** 147 | 1. Stateless - Each invocation is independent 148 | 2. Autonomous - No mid-execution communication 149 | 3. Single Output - One final report only 150 | 4. Context-aware - Has access to conversation history 151 | 5. Tool-rich - Can use all specified tools 152 | end note 153 | 154 | legend right 155 | |= Thoroughness Level |= Behavior | 156 | | quick | Basic search, fast execution | 157 | | medium | Moderate exploration, balanced | 158 | | very thorough | Comprehensive analysis, slower | 159 | endlegend 160 | 161 | @enduml 162 | -------------------------------------------------------------------------------- /.codex/hooks/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Hook Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Hook Execution Lifecycle 7 | 8 | |Claude Code Engine| 9 | start 10 | :Agent Execution Started; 11 | 12 | partition "Initialization Phase" { 13 | :Load Settings; 14 | note right 15 | Sources (priority order): 16 | 1. .claude/settings.json 17 | 2. ~/.claude/settings.json 18 | end note 19 | 20 | :Parse Hook Configurations; 21 | :Register Active Hooks; 22 | note right 23 | Hook Types: 24 | - user-prompt-submit 25 | - tool-call 26 | - pre-commit 27 | - custom hooks 28 | end note 29 | } 30 | 31 | |Event System| 32 | :Wait for Event; 33 | 34 | partition "Event Triggered" { 35 | if (Event Type?) then (user-prompt-submit) 36 | :User Prompt Submitted; 37 | #LightBlue:Trigger user-prompt-submit hooks; 38 | else if (tool-call) 39 | :Tool About to Execute; 40 | #LightGreen:Trigger tool-call hooks; 41 | else if (pre-commit) 42 | :Git Commit Starting; 43 | #LightYellow:Trigger pre-commit hooks; 44 | else (custom) 45 | :Custom Event; 46 | #LightPink:Trigger custom hooks; 47 | endif 48 | } 49 | 50 | |Hook Manager| 51 | :Find Matching Hooks; 52 | 53 | if (Hook Enabled?) then (no) 54 | :Skip Hook; 55 | |Claude Code Engine| 56 | :Continue Normal Flow; 57 | stop 58 | else (yes) 59 | :Prepare Hook Execution; 60 | endif 61 | 62 | :Build Environment; 63 | note right 64 | Environment Variables: 65 | - CLAUDE_PROJECT_DIR 66 | - CLAUDE_TOOL_NAME 67 | - CLAUDE_TOOL_PARAMS 68 | - Custom vars 69 | end note 70 | 71 | :Substitute Parameters; 72 | note right 73 | Replace placeholders: 74 | ${file_path} 75 | ${command} 76 | ${PR_NUMBER} 77 | etc. 78 | end note 79 | 80 | |Shell Executor| 81 | :Execute Hook Script; 82 | 83 | if (Timeout Set?) then (yes) 84 | fork 85 | :Run Script; 86 | fork again 87 | :Start Timer; 88 | if (Timeout Reached?) then (yes) 89 | :Kill Process; 90 | :Return Timeout Error; 91 | endif 92 | end fork 93 | else (no) 94 | :Run Script (default 5s timeout); 95 | endif 96 | 97 | :Capture Output; 98 | note right 99 | - stdout 100 | - stderr 101 | - exit code 102 | end note 103 | 104 | |Hook Manager| 105 | :Process Results; 106 | 107 | if (Exit Code?) then (0 - success) 108 | :Hook Passed; 109 | 110 | if (Output Present?) then (yes) 111 | :Send Output to Claude; 112 | note right 113 | Output treated as 114 | user feedback 115 | end note 116 | endif 117 | 118 | |Claude Code Engine| 119 | :Continue Normal Flow; 120 | 121 | else (non-zero - failure) 122 | :Hook Failed; 123 | 124 | if (Failure Mode?) then (error) 125 | #Pink:Block Operation; 126 | 127 | :Send Error to User; 128 | note right 129 | Operation blocked: 130 | "Hook failed: " 131 | end note 132 | 133 | |User| 134 | :Receive Error; 135 | :Fix Issue / Adjust Hooks; 136 | stop 137 | 138 | else if (warn) 139 | #Yellow:Allow with Warning; 140 | 141 | :Send Warning to User; 142 | note right 143 | Warning shown: 144 | "Hook warning: 145 | Continuing anyway..." 146 | end note 147 | 148 | |Claude Code Engine| 149 | :Continue Normal Flow; 150 | 151 | else (ignore) 152 | #LightGray:Silent Continue; 153 | 154 | :Log Failure (internal); 155 | 156 | |Claude Code Engine| 157 | :Continue Normal Flow; 158 | endif 159 | endif 160 | 161 | stop 162 | 163 | note bottom 164 | **Hook Execution Characteristics:** 165 | 166 | 1. **Synchronous** - Blocks main flow until complete 167 | 2. **Parameterized** - Can access event context 168 | 3. **Configurable Timeout** - Default 5s, max 600s 169 | 4. **Flexible Error Handling** - error/warn/ignore modes 170 | 5. **Feedback Loop** - Output sent back to Claude 171 | 6. **Environment-aware** - Access to project context 172 | end note 173 | 174 | legend right 175 | |= Failure Mode |= Behavior | 176 | | error | Block operation completely | 177 | | warn | Show warning but continue | 178 | | ignore | Silent failure, continue | 179 | 180 | |= Common Use Cases | 181 | | Pre-commit | Lint, test, format check | 182 | | Tool-call | Backup, validation, logging | 183 | | User-prompt | Auto-test, custom checks | 184 | endlegend 185 | 186 | @enduml 187 | -------------------------------------------------------------------------------- /.claude/hooks/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Hook Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Hook Execution Lifecycle 7 | 8 | |Claude Code Engine| 9 | start 10 | :Agent Execution Started; 11 | 12 | partition "Initialization Phase" { 13 | :Load Settings; 14 | note right 15 | Sources (priority order): 16 | 1. .claude/settings.json 17 | 2. ~/.claude/settings.json 18 | end note 19 | 20 | :Parse Hook Configurations; 21 | :Register Active Hooks; 22 | note right 23 | Hook Types: 24 | - user-prompt-submit 25 | - tool-call 26 | - pre-commit 27 | - custom hooks 28 | end note 29 | } 30 | 31 | |Event System| 32 | :Wait for Event; 33 | 34 | partition "Event Triggered" { 35 | if (Event Type?) then (user-prompt-submit) 36 | :User Prompt Submitted; 37 | #LightBlue:Trigger user-prompt-submit hooks; 38 | else if (tool-call) 39 | :Tool About to Execute; 40 | #LightGreen:Trigger tool-call hooks; 41 | else if (pre-commit) 42 | :Git Commit Starting; 43 | #LightYellow:Trigger pre-commit hooks; 44 | else (custom) 45 | :Custom Event; 46 | #LightPink:Trigger custom hooks; 47 | endif 48 | } 49 | 50 | |Hook Manager| 51 | :Find Matching Hooks; 52 | 53 | if (Hook Enabled?) then (no) 54 | :Skip Hook; 55 | |Claude Code Engine| 56 | :Continue Normal Flow; 57 | stop 58 | else (yes) 59 | :Prepare Hook Execution; 60 | endif 61 | 62 | :Build Environment; 63 | note right 64 | Environment Variables: 65 | - CLAUDE_PROJECT_DIR 66 | - CLAUDE_TOOL_NAME 67 | - CLAUDE_TOOL_PARAMS 68 | - Custom vars 69 | end note 70 | 71 | :Substitute Parameters; 72 | note right 73 | Replace placeholders: 74 | ${file_path} 75 | ${command} 76 | ${PR_NUMBER} 77 | etc. 78 | end note 79 | 80 | |Shell Executor| 81 | :Execute Hook Script; 82 | 83 | if (Timeout Set?) then (yes) 84 | fork 85 | :Run Script; 86 | fork again 87 | :Start Timer; 88 | if (Timeout Reached?) then (yes) 89 | :Kill Process; 90 | :Return Timeout Error; 91 | endif 92 | end fork 93 | else (no) 94 | :Run Script (default 5s timeout); 95 | endif 96 | 97 | :Capture Output; 98 | note right 99 | - stdout 100 | - stderr 101 | - exit code 102 | end note 103 | 104 | |Hook Manager| 105 | :Process Results; 106 | 107 | if (Exit Code?) then (0 - success) 108 | :Hook Passed; 109 | 110 | if (Output Present?) then (yes) 111 | :Send Output to Claude; 112 | note right 113 | Output treated as 114 | user feedback 115 | end note 116 | endif 117 | 118 | |Claude Code Engine| 119 | :Continue Normal Flow; 120 | 121 | else (non-zero - failure) 122 | :Hook Failed; 123 | 124 | if (Failure Mode?) then (error) 125 | #Pink:Block Operation; 126 | 127 | :Send Error to User; 128 | note right 129 | Operation blocked: 130 | "Hook failed: " 131 | end note 132 | 133 | |User| 134 | :Receive Error; 135 | :Fix Issue / Adjust Hooks; 136 | stop 137 | 138 | else if (warn) 139 | #Yellow:Allow with Warning; 140 | 141 | :Send Warning to User; 142 | note right 143 | Warning shown: 144 | "Hook warning: 145 | Continuing anyway..." 146 | end note 147 | 148 | |Claude Code Engine| 149 | :Continue Normal Flow; 150 | 151 | else (ignore) 152 | #LightGray:Silent Continue; 153 | 154 | :Log Failure (internal); 155 | 156 | |Claude Code Engine| 157 | :Continue Normal Flow; 158 | endif 159 | endif 160 | 161 | stop 162 | 163 | note bottom 164 | **Hook Execution Characteristics:** 165 | 166 | 1. **Synchronous** - Blocks main flow until complete 167 | 2. **Parameterized** - Can access event context 168 | 3. **Configurable Timeout** - Default 5s, max 600s 169 | 4. **Flexible Error Handling** - error/warn/ignore modes 170 | 5. **Feedback Loop** - Output sent back to Claude 171 | 6. **Environment-aware** - Access to project context 172 | end note 173 | 174 | legend right 175 | |= Failure Mode |= Behavior | 176 | | error | Block operation completely | 177 | | warn | Show warning but continue | 178 | | ignore | Silent failure, continue | 179 | 180 | |= Common Use Cases | 181 | | Pre-commit | Lint, test, format check | 182 | | Tool-call | Backup, validation, logging | 183 | | User-prompt | Auto-test, custom checks | 184 | endlegend 185 | 186 | @enduml 187 | -------------------------------------------------------------------------------- /.claude/skills/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Skills Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Claude Code Skills Architecture 7 | 8 | package "Claude Code Core" { 9 | [Skill Tool] as SkillTool 10 | note right of SkillTool 11 | Entry point for all 12 | skill invocations 13 | end note 14 | } 15 | 16 | package "Available Skills" { 17 | component "PDF Processing" as PDF { 18 | [PDF Reader] 19 | [Text Extractor] 20 | [PDF Generator] 21 | [PDF Merger] 22 | 23 | database "Dependencies" as PDFDeps { 24 | (PyPDF2) 25 | (fpdf) 26 | } 27 | } 28 | 29 | component "Excel Processing" as XLSX { 30 | [Spreadsheet Reader] 31 | [Data Parser] 32 | [Formula Evaluator] 33 | [Excel Generator] 34 | 35 | database "Dependencies" as XLSXDeps { 36 | (openpyxl) 37 | (pandas) 38 | } 39 | } 40 | 41 | component "API Testing" as APITest { 42 | [Request Builder] 43 | [Response Validator] 44 | [Error Handler] 45 | [Performance Tester] 46 | [Doc Generator] 47 | 48 | database "Dependencies" as APIDeps { 49 | (curl) 50 | (jq) 51 | } 52 | } 53 | 54 | component "Code Review" as CodeReview { 55 | [Quality Checker] 56 | [Security Scanner] 57 | [Performance Analyzer] 58 | [Best Practices Validator] 59 | [Documentation Verifier] 60 | 61 | note bottom of CodeReview 62 | Review Aspects: 63 | - Code Quality 64 | - Security (OWASP Top 10) 65 | - Performance 66 | - Testing 67 | - Documentation 68 | end note 69 | } 70 | } 71 | 72 | package "Custom Skills" { 73 | component "Custom Skill Template" as CustomSkill { 74 | [Feature 1] 75 | [Feature 2] 76 | [Feature N] 77 | 78 | note bottom of CustomSkill 79 | Defined in: 80 | .claude/skills/*.md 81 | end note 82 | } 83 | } 84 | 85 | cloud "Skill Invocation Flow" { 86 | rectangle "User Request" as UR 87 | rectangle "Skill Matching" as SM 88 | rectangle "Prompt Expansion" as PE 89 | rectangle "Skill Execution" as SE 90 | rectangle "Result Delivery" as RD 91 | } 92 | 93 | actor User 94 | 95 | User --> UR : "Process this PDF" 96 | UR --> SkillTool 97 | SkillTool --> SM 98 | 99 | SM --> PDF : pdf skill 100 | SM --> XLSX : xlsx skill 101 | SM --> APITest : api-test skill 102 | SM --> CodeReview : code-review skill 103 | SM --> CustomSkill : custom skills 104 | 105 | SM --> PE : expand skill prompt 106 | PE --> SE : execute with context 107 | 108 | SE --> [PDF Reader] : read PDF 109 | SE --> [Spreadsheet Reader] : read Excel 110 | SE --> [Request Builder] : test API 111 | SE --> [Quality Checker] : review code 112 | 113 | SE --> RD : deliver results 114 | RD --> User : results 115 | 116 | ' Dependencies 117 | [PDF Reader] ..> PDFDeps : uses 118 | [Text Extractor] ..> PDFDeps : uses 119 | [PDF Generator] ..> PDFDeps : uses 120 | 121 | [Spreadsheet Reader] ..> XLSXDeps : uses 122 | [Data Parser] ..> XLSXDeps : uses 123 | [Excel Generator] ..> XLSXDeps : uses 124 | 125 | [Request Builder] ..> APIDeps : uses 126 | [Response Validator] ..> APIDeps : uses 127 | 128 | package "Skill Patterns" { 129 | card "Proactive Skills" as ProactivePattern { 130 | rectangle "Auto-trigger on conditions" 131 | note right 132 | Example: 133 | Auto-test after code changes 134 | end note 135 | } 136 | 137 | card "On-Demand Skills" as OnDemandPattern { 138 | rectangle "User explicitly requests" 139 | note right 140 | Example: 141 | User asks for performance analysis 142 | end note 143 | } 144 | 145 | card "Pipeline Skills" as PipelinePattern { 146 | rectangle "Chain with dependencies" 147 | note right 148 | Example: 149 | code-review -> test -> deploy 150 | end note 151 | } 152 | } 153 | 154 | PDF ..> OnDemandPattern : follows 155 | XLSX ..> OnDemandPattern : follows 156 | APITest ..> OnDemandPattern : follows 157 | CodeReview ..> ProactivePattern : follows 158 | CustomSkill ..> PipelinePattern : can follow 159 | 160 | @enduml 161 | -------------------------------------------------------------------------------- /.codex/skills/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Skills Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Claude Code Skills Architecture 7 | 8 | package "Claude Code Core" { 9 | [Skill Tool] as SkillTool 10 | note right of SkillTool 11 | Entry point for all 12 | skill invocations 13 | end note 14 | } 15 | 16 | package "Available Skills" { 17 | component "PDF Processing" as PDF { 18 | [PDF Reader] 19 | [Text Extractor] 20 | [PDF Generator] 21 | [PDF Merger] 22 | 23 | database "Dependencies" as PDFDeps { 24 | (PyPDF2) 25 | (fpdf) 26 | } 27 | } 28 | 29 | component "Excel Processing" as XLSX { 30 | [Spreadsheet Reader] 31 | [Data Parser] 32 | [Formula Evaluator] 33 | [Excel Generator] 34 | 35 | database "Dependencies" as XLSXDeps { 36 | (openpyxl) 37 | (pandas) 38 | } 39 | } 40 | 41 | component "API Testing" as APITest { 42 | [Request Builder] 43 | [Response Validator] 44 | [Error Handler] 45 | [Performance Tester] 46 | [Doc Generator] 47 | 48 | database "Dependencies" as APIDeps { 49 | (curl) 50 | (jq) 51 | } 52 | } 53 | 54 | component "Code Review" as CodeReview { 55 | [Quality Checker] 56 | [Security Scanner] 57 | [Performance Analyzer] 58 | [Best Practices Validator] 59 | [Documentation Verifier] 60 | 61 | note bottom of CodeReview 62 | Review Aspects: 63 | - Code Quality 64 | - Security (OWASP Top 10) 65 | - Performance 66 | - Testing 67 | - Documentation 68 | end note 69 | } 70 | } 71 | 72 | package "Custom Skills" { 73 | component "Custom Skill Template" as CustomSkill { 74 | [Feature 1] 75 | [Feature 2] 76 | [Feature N] 77 | 78 | note bottom of CustomSkill 79 | Defined in: 80 | .claude/skills/*.md 81 | end note 82 | } 83 | } 84 | 85 | cloud "Skill Invocation Flow" { 86 | rectangle "User Request" as UR 87 | rectangle "Skill Matching" as SM 88 | rectangle "Prompt Expansion" as PE 89 | rectangle "Skill Execution" as SE 90 | rectangle "Result Delivery" as RD 91 | } 92 | 93 | actor User 94 | 95 | User --> UR : "Process this PDF" 96 | UR --> SkillTool 97 | SkillTool --> SM 98 | 99 | SM --> PDF : pdf skill 100 | SM --> XLSX : xlsx skill 101 | SM --> APITest : api-test skill 102 | SM --> CodeReview : code-review skill 103 | SM --> CustomSkill : custom skills 104 | 105 | SM --> PE : expand skill prompt 106 | PE --> SE : execute with context 107 | 108 | SE --> [PDF Reader] : read PDF 109 | SE --> [Spreadsheet Reader] : read Excel 110 | SE --> [Request Builder] : test API 111 | SE --> [Quality Checker] : review code 112 | 113 | SE --> RD : deliver results 114 | RD --> User : results 115 | 116 | ' Dependencies 117 | [PDF Reader] ..> PDFDeps : uses 118 | [Text Extractor] ..> PDFDeps : uses 119 | [PDF Generator] ..> PDFDeps : uses 120 | 121 | [Spreadsheet Reader] ..> XLSXDeps : uses 122 | [Data Parser] ..> XLSXDeps : uses 123 | [Excel Generator] ..> XLSXDeps : uses 124 | 125 | [Request Builder] ..> APIDeps : uses 126 | [Response Validator] ..> APIDeps : uses 127 | 128 | package "Skill Patterns" { 129 | card "Proactive Skills" as ProactivePattern { 130 | rectangle "Auto-trigger on conditions" 131 | note right 132 | Example: 133 | Auto-test after code changes 134 | end note 135 | } 136 | 137 | card "On-Demand Skills" as OnDemandPattern { 138 | rectangle "User explicitly requests" 139 | note right 140 | Example: 141 | User asks for performance analysis 142 | end note 143 | } 144 | 145 | card "Pipeline Skills" as PipelinePattern { 146 | rectangle "Chain with dependencies" 147 | note right 148 | Example: 149 | code-review -> test -> deploy 150 | end note 151 | } 152 | } 153 | 154 | PDF ..> OnDemandPattern : follows 155 | XLSX ..> OnDemandPattern : follows 156 | APITest ..> OnDemandPattern : follows 157 | CodeReview ..> ProactivePattern : follows 158 | CustomSkill ..> PipelinePattern : can follow 159 | 160 | @enduml 161 | -------------------------------------------------------------------------------- /.claude/agents/ui-ux-reviewer.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: ui-ux-reviewer 3 | description: UI/UX design review specialist for web applications and games. Reviews interface designs, user flows, accessibility, and provides actionable improvement suggestions. 4 | tools: Read, Grep, Glob, Write 5 | model: sonnet 6 | --- 7 | 8 | # UI/UX Review Agent 9 | 10 | You are a specialized UI/UX review agent focused on analyzing web application interfaces, particularly gaming UIs. 11 | 12 | ## Review Areas 13 | 14 | ### 1. Visual Design 15 | - Layout and composition 16 | - Color scheme and contrast 17 | - Typography and readability 18 | - Visual hierarchy 19 | - Consistency across components 20 | 21 | ### 2. User Experience 22 | - User flow and navigation 23 | - Interaction patterns 24 | - Feedback mechanisms 25 | - Loading states and transitions 26 | - Error handling 27 | 28 | ### 3. Accessibility (WCAG 2.1) 29 | - Color contrast ratios 30 | - Keyboard navigation 31 | - Screen reader compatibility 32 | - Focus indicators 33 | - ARIA labels 34 | 35 | ### 4. Performance UX 36 | - Perceived performance 37 | - Loading indicators 38 | - Animation smoothness 39 | - Responsive behavior 40 | 41 | ### 5. Gaming-Specific 42 | - Control responsiveness 43 | - Visual feedback for actions 44 | - Tutorial and onboarding 45 | - Score/status displays 46 | - Game state visibility 47 | 48 | ## Review Process 49 | 50 | 1. **Read all UI component files** 51 | - React/TypeScript components 52 | - CSS/styling files 53 | - 3D scene configurations 54 | 55 | 2. **Analyze against best practices** 56 | - Material Design principles 57 | - Gaming UI conventions 58 | - Accessibility standards 59 | 60 | 3. **Generate actionable recommendations** 61 | - Prioritized by impact (High/Medium/Low) 62 | - Include code examples 63 | - Reference specific files and line numbers 64 | 65 | 4. **Create improvement roadmap** 66 | - Quick wins (< 1 hour) 67 | - Medium effort (1-4 hours) 68 | - Major improvements (> 4 hours) 69 | 70 | ## Output Format 71 | 72 | ```markdown 73 | # UI/UX Review Report 74 | 75 | ## Executive Summary 76 | [Brief overview of findings] 77 | 78 | ## Critical Issues (High Priority) 79 | ### Issue 1: [Title] 80 | - **Location**: file.tsx:123 81 | - **Problem**: [Description] 82 | - **Impact**: [User impact] 83 | - **Solution**: [Specific fix] 84 | - **Code Example**: 85 | ```tsx 86 | // Suggested improvement 87 | ``` 88 | 89 | ## Improvements (Medium Priority) 90 | [Same format] 91 | 92 | ## Enhancements (Low Priority) 93 | [Same format] 94 | 95 | ## Accessibility Checklist 96 | - [ ] Color contrast (WCAG AA) 97 | - [ ] Keyboard navigation 98 | - [ ] Screen reader support 99 | - [ ] Focus management 100 | - [ ] ARIA labels 101 | 102 | ## Performance Recommendations 103 | [List of performance-related UX improvements] 104 | 105 | ## Implementation Roadmap 106 | ### Phase 1: Quick Wins (< 1 hour) 107 | - [ ] Task 1 108 | - [ ] Task 2 109 | 110 | ### Phase 2: Medium Effort (1-4 hours) 111 | - [ ] Task 1 112 | - [ ] Task 2 113 | 114 | ### Phase 3: Major Improvements (> 4 hours) 115 | - [ ] Task 1 116 | - [ ] Task 2 117 | ``` 118 | 119 | ## Special Focus for Mahjong AI 120 | 121 | When reviewing the Mahjong AI interface, pay special attention to: 122 | 123 | 1. **3D Tile Visibility** 124 | - Are tiles easy to identify? 125 | - Is text on tiles readable? 126 | - Do hover states provide clear feedback? 127 | 128 | 2. **Game Controls** 129 | - Are Ron/Tsumo/Riichi buttons clearly visible? 130 | - Is button state (enabled/disabled) obvious? 131 | - Are controls accessible during critical moments? 132 | 133 | 3. **Score Display** 134 | - Is score information always visible? 135 | - Are player positions clear? 136 | - Is the dealer indicator prominent? 137 | 138 | 4. **Game Flow** 139 | - Is it clear whose turn it is? 140 | - Are AI actions communicated clearly? 141 | - Is game state always understandable? 142 | 143 | 5. **Mobile Responsiveness** 144 | - Does the 3D scene scale appropriately? 145 | - Are touch targets large enough? 146 | - Is text readable on small screens? 147 | 148 | ## Reference Materials 149 | 150 | - [Material Design Guidelines](https://material.io/design) 151 | - [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) 152 | - [Game UI Database](https://www.gameuidatabase.com/) 153 | - [Three.js Best Practices](https://threejs.org/docs/#manual/en/introduction/Useful-links) 154 | -------------------------------------------------------------------------------- /.codex/agents/ui-ux-reviewer.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: ui-ux-reviewer 3 | description: UI/UX design review specialist for web applications and games. Reviews interface designs, user flows, accessibility, and provides actionable improvement suggestions. 4 | tools: Read, Grep, Glob, Write 5 | model: sonnet 6 | --- 7 | 8 | # UI/UX Review Agent 9 | 10 | You are a specialized UI/UX review agent focused on analyzing web application interfaces, particularly gaming UIs. 11 | 12 | ## Review Areas 13 | 14 | ### 1. Visual Design 15 | - Layout and composition 16 | - Color scheme and contrast 17 | - Typography and readability 18 | - Visual hierarchy 19 | - Consistency across components 20 | 21 | ### 2. User Experience 22 | - User flow and navigation 23 | - Interaction patterns 24 | - Feedback mechanisms 25 | - Loading states and transitions 26 | - Error handling 27 | 28 | ### 3. Accessibility (WCAG 2.1) 29 | - Color contrast ratios 30 | - Keyboard navigation 31 | - Screen reader compatibility 32 | - Focus indicators 33 | - ARIA labels 34 | 35 | ### 4. Performance UX 36 | - Perceived performance 37 | - Loading indicators 38 | - Animation smoothness 39 | - Responsive behavior 40 | 41 | ### 5. Gaming-Specific 42 | - Control responsiveness 43 | - Visual feedback for actions 44 | - Tutorial and onboarding 45 | - Score/status displays 46 | - Game state visibility 47 | 48 | ## Review Process 49 | 50 | 1. **Read all UI component files** 51 | - React/TypeScript components 52 | - CSS/styling files 53 | - 3D scene configurations 54 | 55 | 2. **Analyze against best practices** 56 | - Material Design principles 57 | - Gaming UI conventions 58 | - Accessibility standards 59 | 60 | 3. **Generate actionable recommendations** 61 | - Prioritized by impact (High/Medium/Low) 62 | - Include code examples 63 | - Reference specific files and line numbers 64 | 65 | 4. **Create improvement roadmap** 66 | - Quick wins (< 1 hour) 67 | - Medium effort (1-4 hours) 68 | - Major improvements (> 4 hours) 69 | 70 | ## Output Format 71 | 72 | ```markdown 73 | # UI/UX Review Report 74 | 75 | ## Executive Summary 76 | [Brief overview of findings] 77 | 78 | ## Critical Issues (High Priority) 79 | ### Issue 1: [Title] 80 | - **Location**: file.tsx:123 81 | - **Problem**: [Description] 82 | - **Impact**: [User impact] 83 | - **Solution**: [Specific fix] 84 | - **Code Example**: 85 | ```tsx 86 | // Suggested improvement 87 | ``` 88 | 89 | ## Improvements (Medium Priority) 90 | [Same format] 91 | 92 | ## Enhancements (Low Priority) 93 | [Same format] 94 | 95 | ## Accessibility Checklist 96 | - [ ] Color contrast (WCAG AA) 97 | - [ ] Keyboard navigation 98 | - [ ] Screen reader support 99 | - [ ] Focus management 100 | - [ ] ARIA labels 101 | 102 | ## Performance Recommendations 103 | [List of performance-related UX improvements] 104 | 105 | ## Implementation Roadmap 106 | ### Phase 1: Quick Wins (< 1 hour) 107 | - [ ] Task 1 108 | - [ ] Task 2 109 | 110 | ### Phase 2: Medium Effort (1-4 hours) 111 | - [ ] Task 1 112 | - [ ] Task 2 113 | 114 | ### Phase 3: Major Improvements (> 4 hours) 115 | - [ ] Task 1 116 | - [ ] Task 2 117 | ``` 118 | 119 | ## Special Focus for Mahjong AI 120 | 121 | When reviewing the Mahjong AI interface, pay special attention to: 122 | 123 | 1. **3D Tile Visibility** 124 | - Are tiles easy to identify? 125 | - Is text on tiles readable? 126 | - Do hover states provide clear feedback? 127 | 128 | 2. **Game Controls** 129 | - Are Ron/Tsumo/Riichi buttons clearly visible? 130 | - Is button state (enabled/disabled) obvious? 131 | - Are controls accessible during critical moments? 132 | 133 | 3. **Score Display** 134 | - Is score information always visible? 135 | - Are player positions clear? 136 | - Is the dealer indicator prominent? 137 | 138 | 4. **Game Flow** 139 | - Is it clear whose turn it is? 140 | - Are AI actions communicated clearly? 141 | - Is game state always understandable? 142 | 143 | 5. **Mobile Responsiveness** 144 | - Does the 3D scene scale appropriately? 145 | - Are touch targets large enough? 146 | - Is text readable on small screens? 147 | 148 | ## Reference Materials 149 | 150 | - [Material Design Guidelines](https://material.io/design) 151 | - [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) 152 | - [Game UI Database](https://www.gameuidatabase.com/) 153 | - [Three.js Best Practices](https://threejs.org/docs/#manual/en/introduction/Useful-links) 154 | -------------------------------------------------------------------------------- /.claude/commands/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Slash Commands Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam sequenceArrowThickness 2 5 | 6 | title Claude Code Slash Commands Architecture 7 | 8 | actor User 9 | participant "Claude Code" as Claude 10 | participant "Command Parser" as Parser 11 | participant "Command Executor" as Executor 12 | 13 | box "Built-in Commands" #LightBlue 14 | participant "/help" as HelpCmd 15 | participant "/clear" as ClearCmd 16 | participant "/reset" as ResetCmd 17 | end box 18 | 19 | box "Custom Commands" #LightGreen 20 | collections "Command Definitions" as CmdDefs { 21 | file ".claude/commands/review-pr.md" as ReviewPR 22 | file ".claude/commands/test.md" as TestCmd 23 | file ".claude/commands/deploy.md" as DeployCmd 24 | file ".claude/commands/refactor.md" as RefactorCmd 25 | file ".claude/commands/docs.md" as DocsCmd 26 | } 27 | end box 28 | 29 | database "Command Registry" as Registry 30 | 31 | == Command Registration == 32 | CmdDefs -> Registry: register commands 33 | note right of Registry 34 | Commands registered with: 35 | - name (from filename) 36 | - description (from YAML front matter) 37 | - prompt template 38 | end note 39 | 40 | == Command Execution Flow == 41 | 42 | User -> Claude: "/review-pr 123" 43 | Claude -> Parser: parse command 44 | Parser -> Parser: extract name & args 45 | 46 | alt Built-in Command 47 | Parser -> HelpCmd: /help 48 | HelpCmd --> User: display help 49 | else Custom Command 50 | Parser -> Registry: lookup "review-pr" 51 | Registry --> Parser: command definition 52 | 53 | Parser -> Executor: execute with args 54 | note right of Executor 55 | 56 | review-pr is running... 57 | 58 | end note 59 | 60 | Executor -> ReviewPR: expand prompt template 61 | ReviewPR --> Executor: expanded prompt 62 | 63 | Executor -> Executor: substitute ${PR_NUMBER} = 123 64 | 65 | Executor -> Claude: process with expanded prompt 66 | 67 | Claude -> Claude: execute command steps: 68 | note right 69 | 1. Fetch PR details 70 | 2. Read changed files 71 | 3. Analyze changes 72 | 4. Generate review 73 | 5. Format output 74 | end note 75 | 76 | Claude --> User: review results 77 | end 78 | 79 | == Command Examples == 80 | 81 | group /review-pr Flow 82 | User -> Claude: "/review-pr 456" 83 | Claude -> ReviewPR: expand 84 | ReviewPR -> Claude: """ 85 | ReviewPR -> Claude: gh pr view 456 86 | ReviewPR -> Claude: gh pr diff 456 87 | ReviewPR -> Claude: analyze for quality, security, performance 88 | ReviewPR -> Claude: provide feedback 89 | ReviewPR -> Claude: """ 90 | Claude --> User: PR Review Report 91 | end 92 | 93 | group /test Flow 94 | User -> Claude: "/test" 95 | Claude -> TestCmd: expand 96 | TestCmd -> Claude: """ 97 | TestCmd -> Claude: npm test 98 | TestCmd -> Claude: analyze failures 99 | TestCmd -> Claude: fix issues 100 | TestCmd -> Claude: re-run tests 101 | TestCmd -> Claude: """ 102 | Claude --> User: Test Results Report 103 | end 104 | 105 | group /deploy Flow 106 | User -> Claude: "/deploy production" 107 | Claude -> DeployCmd: expand with env=production 108 | DeployCmd -> Claude: """ 109 | DeployCmd -> Claude: pre-flight checks 110 | DeployCmd -> Claude: run tests & lint 111 | DeployCmd -> Claude: build project 112 | DeployCmd -> Claude: deploy to production 113 | DeployCmd -> Claude: verify deployment 114 | DeployCmd -> Claude: """ 115 | Claude --> User: Deployment Report 116 | end 117 | 118 | group /refactor Flow 119 | User -> Claude: "/refactor" 120 | Claude -> RefactorCmd: expand 121 | RefactorCmd -> Claude: """ 122 | RefactorCmd -> Claude: analyze code smells 123 | RefactorCmd -> Claude: identify duplications 124 | RefactorCmd -> Claude: apply refactoring patterns 125 | RefactorCmd -> Claude: run tests 126 | RefactorCmd -> Claude: """ 127 | Claude --> User: Refactoring Report 128 | end 129 | 130 | group /docs Flow 131 | User -> Claude: "/docs" 132 | Claude -> DocsCmd: expand 133 | DocsCmd -> Claude: """ 134 | DocsCmd -> Claude: analyze codebase 135 | DocsCmd -> Claude: generate JSDoc comments 136 | DocsCmd -> Claude: update README 137 | DocsCmd -> Claude: create examples 138 | DocsCmd -> Claude: """ 139 | Claude --> User: Documentation Report 140 | end 141 | 142 | @enduml 143 | -------------------------------------------------------------------------------- /.codex/commands/structure.puml: -------------------------------------------------------------------------------- 1 | @startuml Slash Commands Structure 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam sequenceArrowThickness 2 5 | 6 | title Claude Code Slash Commands Architecture 7 | 8 | actor User 9 | participant "Claude Code" as Claude 10 | participant "Command Parser" as Parser 11 | participant "Command Executor" as Executor 12 | 13 | box "Built-in Commands" #LightBlue 14 | participant "/help" as HelpCmd 15 | participant "/clear" as ClearCmd 16 | participant "/reset" as ResetCmd 17 | end box 18 | 19 | box "Custom Commands" #LightGreen 20 | collections "Command Definitions" as CmdDefs { 21 | file ".claude/commands/review-pr.md" as ReviewPR 22 | file ".claude/commands/test.md" as TestCmd 23 | file ".claude/commands/deploy.md" as DeployCmd 24 | file ".claude/commands/refactor.md" as RefactorCmd 25 | file ".claude/commands/docs.md" as DocsCmd 26 | } 27 | end box 28 | 29 | database "Command Registry" as Registry 30 | 31 | == Command Registration == 32 | CmdDefs -> Registry: register commands 33 | note right of Registry 34 | Commands registered with: 35 | - name (from filename) 36 | - description (from YAML front matter) 37 | - prompt template 38 | end note 39 | 40 | == Command Execution Flow == 41 | 42 | User -> Claude: "/review-pr 123" 43 | Claude -> Parser: parse command 44 | Parser -> Parser: extract name & args 45 | 46 | alt Built-in Command 47 | Parser -> HelpCmd: /help 48 | HelpCmd --> User: display help 49 | else Custom Command 50 | Parser -> Registry: lookup "review-pr" 51 | Registry --> Parser: command definition 52 | 53 | Parser -> Executor: execute with args 54 | note right of Executor 55 | 56 | review-pr is running... 57 | 58 | end note 59 | 60 | Executor -> ReviewPR: expand prompt template 61 | ReviewPR --> Executor: expanded prompt 62 | 63 | Executor -> Executor: substitute ${PR_NUMBER} = 123 64 | 65 | Executor -> Claude: process with expanded prompt 66 | 67 | Claude -> Claude: execute command steps: 68 | note right 69 | 1. Fetch PR details 70 | 2. Read changed files 71 | 3. Analyze changes 72 | 4. Generate review 73 | 5. Format output 74 | end note 75 | 76 | Claude --> User: review results 77 | end 78 | 79 | == Command Examples == 80 | 81 | group /review-pr Flow 82 | User -> Claude: "/review-pr 456" 83 | Claude -> ReviewPR: expand 84 | ReviewPR -> Claude: """ 85 | ReviewPR -> Claude: gh pr view 456 86 | ReviewPR -> Claude: gh pr diff 456 87 | ReviewPR -> Claude: analyze for quality, security, performance 88 | ReviewPR -> Claude: provide feedback 89 | ReviewPR -> Claude: """ 90 | Claude --> User: PR Review Report 91 | end 92 | 93 | group /test Flow 94 | User -> Claude: "/test" 95 | Claude -> TestCmd: expand 96 | TestCmd -> Claude: """ 97 | TestCmd -> Claude: npm test 98 | TestCmd -> Claude: analyze failures 99 | TestCmd -> Claude: fix issues 100 | TestCmd -> Claude: re-run tests 101 | TestCmd -> Claude: """ 102 | Claude --> User: Test Results Report 103 | end 104 | 105 | group /deploy Flow 106 | User -> Claude: "/deploy production" 107 | Claude -> DeployCmd: expand with env=production 108 | DeployCmd -> Claude: """ 109 | DeployCmd -> Claude: pre-flight checks 110 | DeployCmd -> Claude: run tests & lint 111 | DeployCmd -> Claude: build project 112 | DeployCmd -> Claude: deploy to production 113 | DeployCmd -> Claude: verify deployment 114 | DeployCmd -> Claude: """ 115 | Claude --> User: Deployment Report 116 | end 117 | 118 | group /refactor Flow 119 | User -> Claude: "/refactor" 120 | Claude -> RefactorCmd: expand 121 | RefactorCmd -> Claude: """ 122 | RefactorCmd -> Claude: analyze code smells 123 | RefactorCmd -> Claude: identify duplications 124 | RefactorCmd -> Claude: apply refactoring patterns 125 | RefactorCmd -> Claude: run tests 126 | RefactorCmd -> Claude: """ 127 | Claude --> User: Refactoring Report 128 | end 129 | 130 | group /docs Flow 131 | User -> Claude: "/docs" 132 | Claude -> DocsCmd: expand 133 | DocsCmd -> Claude: """ 134 | DocsCmd -> Claude: analyze codebase 135 | DocsCmd -> Claude: generate JSDoc comments 136 | DocsCmd -> Claude: update README 137 | DocsCmd -> Claude: create examples 138 | DocsCmd -> Claude: """ 139 | Claude --> User: Documentation Report 140 | end 141 | 142 | @enduml 143 | -------------------------------------------------------------------------------- /docs/paper_law_of_flickering_scenery.out: -------------------------------------------------------------------------------- 1 | \BOOKMARK [1][-]{section.1}{\376\377\000I\000n\000t\000r\000o\000d\000u\000c\000t\000i\000o\000n}{}% 1 2 | \BOOKMARK [2][-]{subsection.1.1}{\376\377\000M\000o\000t\000i\000v\000a\000t\000i\000o\000n}{section.1}% 2 3 | \BOOKMARK [2][-]{subsection.1.2}{\376\377\000C\000o\000n\000t\000r\000i\000b\000u\000t\000i\000o\000n\000s}{section.1}% 3 4 | \BOOKMARK [2][-]{subsection.1.3}{\376\377\000P\000a\000p\000e\000r\000\040\000O\000r\000g\000a\000n\000i\000z\000a\000t\000i\000o\000n}{section.1}% 4 5 | \BOOKMARK [1][-]{section.2}{\376\377\000R\000e\000l\000a\000t\000e\000d\000\040\000W\000o\000r\000k}{}% 5 6 | \BOOKMARK [2][-]{subsection.2.1}{\376\377\000A\000u\000t\000o\000n\000o\000m\000o\000u\000s\000\040\000A\000g\000e\000n\000t\000\040\000A\000r\000c\000h\000i\000t\000e\000c\000t\000u\000r\000e\000s}{section.2}% 6 7 | \BOOKMARK [2][-]{subsection.2.2}{\376\377\000W\000o\000r\000l\000d\000\040\000M\000o\000d\000e\000l\000s\000\040\000a\000n\000d\000\040\000S\000t\000a\000t\000e\000\040\000R\000e\000p\000r\000e\000s\000e\000n\000t\000a\000t\000i\000o\000n}{section.2}% 7 8 | \BOOKMARK [2][-]{subsection.2.3}{\376\377\000C\000o\000n\000v\000e\000r\000g\000e\000n\000c\000e\000\040\000a\000n\000d\000\040\000F\000i\000x\000e\000d\000\040\000P\000o\000i\000n\000t\000s}{section.2}% 8 9 | \BOOKMARK [1][-]{section.3}{\376\377\000T\000h\000e\000o\000r\000e\000t\000i\000c\000a\000l\000\040\000F\000r\000a\000m\000e\000w\000o\000r\000k}{}% 9 10 | \BOOKMARK [2][-]{subsection.3.1}{\376\377\000F\000o\000r\000m\000a\000l\000\040\000D\000e\000f\000i\000n\000i\000t\000i\000o\000n\000s}{section.3}% 10 11 | \BOOKMARK [2][-]{subsection.3.2}{\376\377\000T\000h\000e\000\040\000U\000n\000i\000f\000i\000e\000d\000\040\000A\000g\000e\000n\000t\000\040\000F\000o\000r\000m\000u\000l\000a}{section.3}% 11 12 | \BOOKMARK [2][-]{subsection.3.3}{\376\377\000M\000a\000t\000h\000e\000m\000a\000t\000i\000c\000a\000l\000\040\000P\000r\000o\000p\000e\000r\000t\000i\000e\000s}{section.3}% 12 13 | \BOOKMARK [1][-]{section.4}{\376\377\000C\000o\000r\000e\000\040\000C\000o\000m\000p\000o\000n\000e\000n\000t\000s}{}% 13 14 | \BOOKMARK [2][-]{subsection.4.1}{\376\377\000I\000n\000t\000e\000n\000t\000\040\000R\000e\000s\000o\000l\000u\000t\000i\000o\000n\000\040\000\050\000I\000\051}{section.4}% 14 15 | \BOOKMARK [2][-]{subsection.4.2}{\376\377\000C\000o\000m\000m\000a\000n\000d\000\040\000S\000t\000a\000c\000k\000\040\000\050\000C\000\051}{section.4}% 15 16 | \BOOKMARK [2][-]{subsection.4.3}{\376\377\000W\000o\000r\000l\000d\000\040\000T\000r\000a\000n\000s\000f\000o\000r\000m\000a\000t\000i\000o\000n\000\040\000\050\000\051}{section.4}% 16 17 | \BOOKMARK [1][-]{section.5}{\376\377\000C\000o\000n\000v\000e\000r\000g\000e\000n\000c\000e\000\040\000A\000n\000a\000l\000y\000s\000i\000s}{}% 17 18 | \BOOKMARK [2][-]{subsection.5.1}{\376\377\000M\000a\000i\000n\000\040\000C\000o\000n\000v\000e\000r\000g\000e\000n\000c\000e\000\040\000T\000h\000e\000o\000r\000e\000m}{section.5}% 18 19 | \BOOKMARK [2][-]{subsection.5.2}{\376\377\000C\000o\000m\000p\000l\000e\000x\000i\000t\000y\000\040\000A\000n\000a\000l\000y\000s\000i\000s}{section.5}% 19 20 | \BOOKMARK [1][-]{section.6}{\376\377\000I\000m\000p\000l\000e\000m\000e\000n\000t\000a\000t\000i\000o\000n}{}% 20 21 | \BOOKMARK [1][-]{section.7}{\376\377\000P\000r\000o\000p\000o\000s\000e\000d\000\040\000I\000m\000p\000l\000e\000m\000e\000n\000t\000a\000t\000i\000o\000n\000\040\000a\000n\000d\000\040\000E\000x\000p\000e\000c\000t\000e\000d\000\040\000P\000e\000r\000f\000o\000r\000m\000a\000n\000c\000e}{}% 21 22 | \BOOKMARK [2][-]{subsection.7.1}{\376\377\000I\000m\000p\000l\000e\000m\000e\000n\000t\000a\000t\000i\000o\000n\000\040\000D\000e\000s\000i\000g\000n}{section.7}% 22 23 | \BOOKMARK [2][-]{subsection.7.2}{\376\377\000E\000x\000p\000e\000c\000t\000e\000d\000\040\000P\000e\000r\000f\000o\000r\000m\000a\000n\000c\000e\000\040\000C\000h\000a\000r\000a\000c\000t\000e\000r\000i\000s\000t\000i\000c\000s}{section.7}% 23 24 | \BOOKMARK [2][-]{subsection.7.3}{\376\377\000A\000n\000a\000l\000y\000s\000i\000s}{section.7}% 24 25 | \BOOKMARK [1][-]{section.8}{\376\377\000D\000i\000s\000c\000u\000s\000s\000i\000o\000n}{}% 25 26 | \BOOKMARK [2][-]{subsection.8.1}{\376\377\000T\000h\000e\000o\000r\000e\000t\000i\000c\000a\000l\000\040\000I\000m\000p\000l\000i\000c\000a\000t\000i\000o\000n\000s}{section.8}% 26 27 | \BOOKMARK [2][-]{subsection.8.2}{\376\377\000L\000i\000m\000i\000t\000a\000t\000i\000o\000n\000s\000\040\000a\000n\000d\000\040\000F\000u\000t\000u\000r\000e\000\040\000W\000o\000r\000k}{section.8}% 27 28 | \BOOKMARK [1][-]{section.9}{\376\377\000C\000o\000n\000c\000l\000u\000s\000i\000o\000n}{}% 28 29 | \BOOKMARK [1][-]{section*.2}{\376\377\000R\000e\000f\000e\000r\000e\000n\000c\000e\000s}{}% 29 30 | -------------------------------------------------------------------------------- /docs/README.md: -------------------------------------------------------------------------------- 1 | # Claude Code Detail Control Documentation 2 | 3 | **A comprehensive guide to controlling detail levels in Claude Code's subagent system** 4 | 5 | --- 6 | 7 | ## 🌐 View the Documentation 8 | 9 | **Start here**: [Documentation Index](./index.md) 10 | 11 | --- 12 | 13 | ## 📚 What's Included 14 | 15 | This documentation site provides: 16 | 17 | 1. **Complete Guide** - [Controlling Detail Levels](./guides/controlling-detail-levels.md) 18 | - Architecture comparison (Claude Code vs Phil Schmid's approaches) 19 | - Control mechanisms and configuration methods 20 | - Best practices and advanced patterns 21 | 22 | 2. **Practical Examples** - [Detail Control Examples](./examples/detail-control-examples.md) 23 | - Real-world scenarios and code snippets 24 | - CLI usage examples 25 | - Troubleshooting guide 26 | 27 | 3. **Architecture** - [Agent State Machine](../.claude/agent-state-machine.puml) 28 | - Technical deep-dive into Claude Code's agent architecture 29 | 30 | --- 31 | 32 | ## 🚀 Quick Links 33 | 34 | | Resource | Description | 35 | |----------|-------------| 36 | | [📖 Complete Guide](./guides/controlling-detail-levels.md) | In-depth documentation on detail control | 37 | | [💻 Code Examples](./examples/detail-control-examples.md) | Practical code snippets and patterns | 38 | | [🏠 Documentation Home](./index.md) | Main documentation hub | 39 | | [🏛️ Architecture](../ARCHITECTURE.md) | System architecture details | 40 | 41 | --- 42 | 43 | ## 📊 Key Topics Covered 44 | 45 | - **Agent Types**: Specialized agents for different tasks 46 | - **Thoroughness Levels**: quick, medium, very thorough 47 | - **Tool Access Control**: Bounded capabilities per agent 48 | - **Prompt Engineering**: Explicit detail specification 49 | - **Model Selection**: haiku, sonnet, opus 50 | - **Performance Optimization**: Cost and speed tradeoffs 51 | - **Real-World Patterns**: Production-ready examples 52 | 53 | --- 54 | 55 | ## 🎯 Who Is This For? 56 | 57 | - **Developers** using Claude Code for software development 58 | - **Architects** designing AI-augmented workflows 59 | - **Researchers** studying subagent architectures 60 | - **Teams** optimizing AI tool usage 61 | - **Anyone** curious about controlling AI agent behavior 62 | 63 | --- 64 | 65 | ## 🔍 Featured Comparison 66 | 67 | This documentation compares Claude Code's **explicit subagent model** with approaches from: 68 | 69 | - **Phil Schmid's "The Rise of Subagents"** 70 | - **Poke.com's dynamic agent system** 71 | - **Traditional monolithic agent approaches** 72 | 73 | Learn when to use each approach and how to get the most from Claude Code's explicit, controllable architecture. 74 | 75 | --- 76 | 77 | ## 📖 Reading Guide 78 | 79 | ### For Beginners 80 | 81 | 1. Start: [Documentation Index](./index.md#-quick-start) 82 | 2. Read: [Introduction](./guides/controlling-detail-levels.md#introduction) 83 | 3. Try: [Quick Examples](./examples/detail-control-examples.md#quick-reference-examples) 84 | 85 | ### For Advanced Users 86 | 87 | 1. Jump to: [Advanced Patterns](./guides/controlling-detail-levels.md#advanced-patterns) 88 | 2. Study: [Real-World Scenarios](./examples/detail-control-examples.md#real-world-scenarios) 89 | 3. Optimize: [Performance Benchmarks](./examples/detail-control-examples.md#performance-benchmarks) 90 | 91 | --- 92 | 93 | ## 🛠️ Usage Example 94 | 95 | ```typescript 96 | // Control detail level explicitly 97 | await Task({ 98 | subagent_type: "Explore", 99 | thoroughness: "medium", // ← Control detail 100 | model: "sonnet", // ← Control model 101 | prompt: ` 102 | Analyze authentication system: 103 | - Main files with line refs 104 | - Flow description (3-5 paragraphs) 105 | - Security assessment 106 | 107 | Detail level: Medium (balanced) 108 | ` 109 | }) 110 | ``` 111 | 112 | --- 113 | 114 | ## 📈 Documentation Structure 115 | 116 | ``` 117 | docs/ 118 | ├── index.md # Main hub 119 | ├── README.md # This file 120 | ├── guides/ 121 | │ └── controlling-detail-levels.md # Complete guide 122 | ├── examples/ 123 | │ └── detail-control-examples.md # Code examples 124 | └── architecture/ 125 | └── (see ../.claude/agent-state-machine.puml) 126 | ``` 127 | 128 | --- 129 | 130 | ## 🔗 External References 131 | 132 | - [Phil Schmid: The Rise of Subagents](https://www.philschmid.de/the-rise-of-subagents) 133 | - [Claude Code Official Docs](https://docs.claude.com/claude-code) 134 | - [Claude API Reference](https://docs.anthropic.com/claude/reference) 135 | 136 | --- 137 | 138 | ## 📝 License 139 | 140 | Part of the AI_Agent project. See main project LICENSE. 141 | 142 | --- 143 | 144 | ## 🤝 Contributing 145 | 146 | Issues and improvements welcome! 147 | 148 | - Report issues: [GitHub Issues](https://github.com/anthropics/claude-code/issues) 149 | - Discussions: [GitHub Discussions](https://github.com/anthropics/claude-code/discussions) 150 | 151 | --- 152 | 153 | **Ready to learn?** → [Start with the Documentation Index](./index.md) 154 | -------------------------------------------------------------------------------- /.claude/mcp-integration.puml: -------------------------------------------------------------------------------- 1 | @startuml MCP Integration Architecture 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Model Context Protocol (MCP) Integration in Claude Code 7 | 8 | actor "User" as User 9 | 10 | package "Claude Code Core" { 11 | component "Claude Agent" as Agent { 12 | [Context Manager] 13 | [Tool Orchestrator] 14 | [Permission Manager] 15 | } 16 | } 17 | 18 | package "MCP Client Layer" { 19 | component "MCP Client" as MCPClient { 20 | [Server Registry] 21 | [Transport Manager] 22 | [Resource Manager] 23 | [Prompt Manager] 24 | } 25 | } 26 | 27 | cloud "MCP Servers" { 28 | 29 | package "Development & Testing" #LightBlue { 30 | component "Sentry" as Sentry 31 | component "Socket" as Socket 32 | component "Hugging Face" as HF 33 | component "Jam" as Jam 34 | } 35 | 36 | package "Project Management" #LightGreen { 37 | component "Asana" as Asana 38 | component "Atlassian" as Atlassian 39 | component "Linear" as Linear 40 | component "Notion" as Notion 41 | component "Monday" as Monday 42 | } 43 | 44 | package "Databases & Data" #LightYellow { 45 | component "Airtable" as Airtable 46 | component "HubSpot" as HubSpot 47 | component "Daloopa" as Daloopa 48 | } 49 | 50 | package "Payments & Commerce" #LightPink { 51 | component "PayPal" as PayPal 52 | component "Stripe" as Stripe 53 | component "Square" as Square 54 | } 55 | 56 | package "Design & Media" #LightCyan { 57 | component "Figma" as Figma 58 | component "Canva" as Canva 59 | component "invideo" as invideo 60 | } 61 | 62 | package "Infrastructure & DevOps" #Lavender { 63 | component "Cloudflare" as Cloudflare 64 | component "Netlify" as Netlify 65 | component "Vercel" as Vercel 66 | } 67 | 68 | package "Automation" #LightGray { 69 | component "Zapier" as Zapier 70 | component "Workato" as Workato 71 | } 72 | } 73 | 74 | database "Configuration" { 75 | file ".mcp.json" as MCPConfig 76 | file "~/.claude/settings.json" as UserConfig 77 | file "managed-mcp.json" as EnterpriseConfig 78 | } 79 | 80 | ' User interactions 81 | User --> Agent : Requests with @mentions 82 | 83 | ' Agent to MCP Client 84 | Agent --> [Context Manager] 85 | [Context Manager] --> [Server Registry] : Query available servers 86 | [Tool Orchestrator] --> [Transport Manager] : Execute MCP tools 87 | [Permission Manager] --> [Resource Manager] : Access resources 88 | 89 | ' MCP Client to Servers (Transport Types) 90 | [Transport Manager] --> Sentry : HTTP 91 | [Transport Manager] --> Asana : SSE 92 | [Transport Manager] --> Airtable : stdio 93 | 94 | [Transport Manager] --> Atlassian : SSE 95 | [Transport Manager] --> Linear : HTTP 96 | [Transport Manager] --> Notion : HTTP 97 | [Transport Manager] --> Monday : HTTP 98 | 99 | [Transport Manager] --> HubSpot : HTTP 100 | [Transport Manager] --> Daloopa : HTTP 101 | 102 | [Transport Manager] --> PayPal : HTTP 103 | [Transport Manager] --> Stripe : HTTP 104 | [Transport Manager] --> Square : SSE 105 | 106 | [Transport Manager] --> Figma : HTTP 107 | [Transport Manager] --> Canva : HTTP 108 | [Transport Manager] --> invideo : SSE 109 | 110 | [Transport Manager] --> Netlify : HTTP 111 | [Transport Manager] --> Vercel : HTTP 112 | 113 | [Transport Manager] --> Zapier : HTTP 114 | [Transport Manager] --> Workato : HTTP 115 | 116 | ' Configuration loading 117 | [Server Registry] ..> MCPConfig : load project config 118 | [Server Registry] ..> UserConfig : load user config 119 | [Server Registry] ..> EnterpriseConfig : load enterprise config 120 | 121 | ' Resource and Prompt Management 122 | [Resource Manager] --> Sentry : @sentry:error://123 123 | [Resource Manager] --> Notion : @notion:page://abc 124 | [Prompt Manager] --> Linear : /mcp__linear__create_issue 125 | 126 | note right of [Transport Manager] 127 | Transport Types: 128 | - HTTP: Remote servers (recommended) 129 | - SSE: Server-Sent Events (deprecated) 130 | - stdio: Local processes 131 | end note 132 | 133 | note bottom of MCPConfig 134 | Configuration Scopes: 135 | - local: Project-specific (default) 136 | - project: Shared via .mcp.json 137 | - user: Cross-project 138 | - enterprise: Managed by IT 139 | 140 | Priority: 141 | enterprise > project > user > local 142 | end note 143 | 144 | legend right 145 | |= Category |= Example Tools | 146 | | Dev & Test | Sentry, Jam, Socket | 147 | | Project Mgmt | Jira, Linear, Notion | 148 | | Data | Airtable, HubSpot | 149 | | Payments | Stripe, PayPal | 150 | | Design | Figma, Canva | 151 | | DevOps | Cloudflare, Vercel | 152 | | Automation | Zapier, Workato | 153 | endlegend 154 | 155 | @enduml 156 | -------------------------------------------------------------------------------- /.codex/mcp-integration.puml: -------------------------------------------------------------------------------- 1 | @startuml MCP Integration Architecture 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Model Context Protocol (MCP) Integration in Claude Code 7 | 8 | actor "User" as User 9 | 10 | package "Claude Code Core" { 11 | component "Claude Agent" as Agent { 12 | [Context Manager] 13 | [Tool Orchestrator] 14 | [Permission Manager] 15 | } 16 | } 17 | 18 | package "MCP Client Layer" { 19 | component "MCP Client" as MCPClient { 20 | [Server Registry] 21 | [Transport Manager] 22 | [Resource Manager] 23 | [Prompt Manager] 24 | } 25 | } 26 | 27 | cloud "MCP Servers" { 28 | 29 | package "Development & Testing" #LightBlue { 30 | component "Sentry" as Sentry 31 | component "Socket" as Socket 32 | component "Hugging Face" as HF 33 | component "Jam" as Jam 34 | } 35 | 36 | package "Project Management" #LightGreen { 37 | component "Asana" as Asana 38 | component "Atlassian" as Atlassian 39 | component "Linear" as Linear 40 | component "Notion" as Notion 41 | component "Monday" as Monday 42 | } 43 | 44 | package "Databases & Data" #LightYellow { 45 | component "Airtable" as Airtable 46 | component "HubSpot" as HubSpot 47 | component "Daloopa" as Daloopa 48 | } 49 | 50 | package "Payments & Commerce" #LightPink { 51 | component "PayPal" as PayPal 52 | component "Stripe" as Stripe 53 | component "Square" as Square 54 | } 55 | 56 | package "Design & Media" #LightCyan { 57 | component "Figma" as Figma 58 | component "Canva" as Canva 59 | component "invideo" as invideo 60 | } 61 | 62 | package "Infrastructure & DevOps" #Lavender { 63 | component "Cloudflare" as Cloudflare 64 | component "Netlify" as Netlify 65 | component "Vercel" as Vercel 66 | } 67 | 68 | package "Automation" #LightGray { 69 | component "Zapier" as Zapier 70 | component "Workato" as Workato 71 | } 72 | } 73 | 74 | database "Configuration" { 75 | file ".mcp.json" as MCPConfig 76 | file "~/.claude/settings.json" as UserConfig 77 | file "managed-mcp.json" as EnterpriseConfig 78 | } 79 | 80 | ' User interactions 81 | User --> Agent : Requests with @mentions 82 | 83 | ' Agent to MCP Client 84 | Agent --> [Context Manager] 85 | [Context Manager] --> [Server Registry] : Query available servers 86 | [Tool Orchestrator] --> [Transport Manager] : Execute MCP tools 87 | [Permission Manager] --> [Resource Manager] : Access resources 88 | 89 | ' MCP Client to Servers (Transport Types) 90 | [Transport Manager] --> Sentry : HTTP 91 | [Transport Manager] --> Asana : SSE 92 | [Transport Manager] --> Airtable : stdio 93 | 94 | [Transport Manager] --> Atlassian : SSE 95 | [Transport Manager] --> Linear : HTTP 96 | [Transport Manager] --> Notion : HTTP 97 | [Transport Manager] --> Monday : HTTP 98 | 99 | [Transport Manager] --> HubSpot : HTTP 100 | [Transport Manager] --> Daloopa : HTTP 101 | 102 | [Transport Manager] --> PayPal : HTTP 103 | [Transport Manager] --> Stripe : HTTP 104 | [Transport Manager] --> Square : SSE 105 | 106 | [Transport Manager] --> Figma : HTTP 107 | [Transport Manager] --> Canva : HTTP 108 | [Transport Manager] --> invideo : SSE 109 | 110 | [Transport Manager] --> Netlify : HTTP 111 | [Transport Manager] --> Vercel : HTTP 112 | 113 | [Transport Manager] --> Zapier : HTTP 114 | [Transport Manager] --> Workato : HTTP 115 | 116 | ' Configuration loading 117 | [Server Registry] ..> MCPConfig : load project config 118 | [Server Registry] ..> UserConfig : load user config 119 | [Server Registry] ..> EnterpriseConfig : load enterprise config 120 | 121 | ' Resource and Prompt Management 122 | [Resource Manager] --> Sentry : @sentry:error://123 123 | [Resource Manager] --> Notion : @notion:page://abc 124 | [Prompt Manager] --> Linear : /mcp__linear__create_issue 125 | 126 | note right of [Transport Manager] 127 | Transport Types: 128 | - HTTP: Remote servers (recommended) 129 | - SSE: Server-Sent Events (deprecated) 130 | - stdio: Local processes 131 | end note 132 | 133 | note bottom of MCPConfig 134 | Configuration Scopes: 135 | - local: Project-specific (default) 136 | - project: Shared via .mcp.json 137 | - user: Cross-project 138 | - enterprise: Managed by IT 139 | 140 | Priority: 141 | enterprise > project > user > local 142 | end note 143 | 144 | legend right 145 | |= Category |= Example Tools | 146 | | Dev & Test | Sentry, Jam, Socket | 147 | | Project Mgmt | Jira, Linear, Notion | 148 | | Data | Airtable, HubSpot | 149 | | Payments | Stripe, PayPal | 150 | | Design | Figma, Canva | 151 | | DevOps | Cloudflare, Vercel | 152 | | Automation | Zapier, Workato | 153 | endlegend 154 | 155 | @enduml 156 | -------------------------------------------------------------------------------- /.claude/system-overview.puml: -------------------------------------------------------------------------------- 1 | @startuml Claude Code System Overview 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Claude Code - Complete System Architecture 7 | 8 | actor "User" as User 9 | 10 | package "Claude Code Core System" { 11 | component "Claude Code Engine" as Engine { 12 | [Intent Parser] 13 | [Context Manager] 14 | [Execution Orchestrator] 15 | [Result Formatter] 16 | } 17 | 18 | component "Tool System" as Tools { 19 | [Read] 20 | [Write] 21 | [Edit] 22 | [Bash] 23 | [Grep] 24 | [Glob] 25 | [Task] 26 | [Skill] 27 | [SlashCommand] 28 | [WebFetch] 29 | [WebSearch] 30 | } 31 | } 32 | 33 | package "Extension Layer" { 34 | 35 | package "Sub-agents (.claude/agnets/)" { 36 | component "general-purpose" as GP 37 | component "Explore" as Explore 38 | component "Plan" as Plan 39 | component "Custom Agents" as CustomAgents 40 | } 41 | 42 | package "Hooks (.claude/hooks/)" { 43 | component "user-prompt-submit" as PromptHook 44 | component "tool-call" as ToolHook 45 | component "pre-commit" as CommitHook 46 | component "Custom Hooks" as CustomHooks 47 | } 48 | 49 | package "Skills (.claude/skills/)" { 50 | component "PDF Processing" as PDFSkill 51 | component "Excel Processing" as XLSXSkill 52 | component "API Testing" as APISkill 53 | component "Code Review" as ReviewSkill 54 | component "Custom Skills" as CustomSkills 55 | } 56 | 57 | package "Slash Commands (.claude/commands/)" { 58 | component "/review-pr" as ReviewPRCmd 59 | component "/test" as TestCmd 60 | component "/deploy" as DeployCmd 61 | component "/refactor" as RefactorCmd 62 | component "/docs" as DocsCmd 63 | component "Custom Commands" as CustomCmds 64 | } 65 | } 66 | 67 | package "Configuration" { 68 | database "Settings" { 69 | file "~/.claude/settings.json" as GlobalSettings 70 | file ".claude/settings.json" as ProjectSettings 71 | file "CLAUDE.md" as ContextFile 72 | } 73 | 74 | database "Project Context" { 75 | folder ".claude/context/" as ContextDir 76 | folder ".claude/agents/" as AgentsDir 77 | } 78 | } 79 | 80 | package "External Integrations" { 81 | cloud "GitHub" as GitHub { 82 | [Issues] 83 | [Pull Requests] 84 | [Actions] 85 | } 86 | 87 | cloud "MCP Servers" as MCP { 88 | [IDE Server] 89 | [Custom Servers] 90 | } 91 | 92 | database "File System" as FS 93 | database "Git Repository" as Git 94 | } 95 | 96 | ' User interactions 97 | User --> Engine : send request 98 | Engine --> User : return result 99 | 100 | ' Core flow 101 | Engine --> [Intent Parser] : parse intent 102 | [Intent Parser] --> [Context Manager] : load context 103 | [Context Manager] --> ContextFile : read 104 | [Context Manager] --> ContextDir : read 105 | [Context Manager] --> ProjectSettings : read 106 | [Context Manager] --> GlobalSettings : read 107 | 108 | [Context Manager] --> [Execution Orchestrator] : execute with context 109 | [Execution Orchestrator] --> Tools : use tools 110 | 111 | ' Tool to Extension connections 112 | [Task] --> GP : invoke 113 | [Task] --> Explore : invoke 114 | [Task] --> Plan : invoke 115 | [Task] --> CustomAgents : invoke 116 | 117 | [Skill] --> PDFSkill : invoke 118 | [Skill] --> XLSXSkill : invoke 119 | [Skill] --> APISkill : invoke 120 | [Skill] --> ReviewSkill : invoke 121 | [Skill] --> CustomSkills : invoke 122 | 123 | [SlashCommand] --> ReviewPRCmd : invoke 124 | [SlashCommand] --> TestCmd : invoke 125 | [SlashCommand] --> DeployCmd : invoke 126 | [SlashCommand] --> RefactorCmd : invoke 127 | [SlashCommand] --> DocsCmd : invoke 128 | [SlashCommand] --> CustomCmds : invoke 129 | 130 | ' Hook integrations 131 | [Execution Orchestrator] --> PromptHook : trigger on prompt 132 | [Execution Orchestrator] --> ToolHook : trigger on tool call 133 | [Execution Orchestrator] --> CommitHook : trigger on commit 134 | [Execution Orchestrator] --> CustomHooks : trigger custom 135 | 136 | ' External integrations 137 | [Read] --> FS : read files 138 | [Write] --> FS : write files 139 | [Edit] --> FS : edit files 140 | [Bash] --> Git : git commands 141 | [Bash] --> GitHub : gh CLI 142 | 143 | [WebFetch] ..> MCP : fetch via MCP 144 | [WebSearch] ..> MCP : search via MCP 145 | 146 | Tools --> [mcp__ide__*] : IDE integration 147 | 148 | ' Result flow 149 | [Execution Orchestrator] --> [Result Formatter] : format results 150 | [Result Formatter] --> Engine : formatted output 151 | 152 | note right of Engine 153 | Agent(Intent, World₀) = 154 | lim_{n→∞} (θ₆_{Learn} ◦ θ₅_{Integrate} ◦ 155 | θ₄_{Execute} ◦ θ₃_{Allocate} ◦ 156 | θ₂_{Generate} ◦ θ₁_{Understand})ⁿ 157 | (Intent, World₀) 158 | end note 159 | 160 | legend right 161 | |= Component Type |= Description | 162 | | Built-in | Core Claude Code components | 163 | | Custom | User-defined extensions | 164 | | External | External services | 165 | endlegend 166 | 167 | @enduml 168 | -------------------------------------------------------------------------------- /.codex/system-overview.puml: -------------------------------------------------------------------------------- 1 | @startuml Claude Code System Overview 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam componentStyle rectangle 5 | 6 | title Claude Code - Complete System Architecture 7 | 8 | actor "User" as User 9 | 10 | package "Claude Code Core System" { 11 | component "Claude Code Engine" as Engine { 12 | [Intent Parser] 13 | [Context Manager] 14 | [Execution Orchestrator] 15 | [Result Formatter] 16 | } 17 | 18 | component "Tool System" as Tools { 19 | [Read] 20 | [Write] 21 | [Edit] 22 | [Bash] 23 | [Grep] 24 | [Glob] 25 | [Task] 26 | [Skill] 27 | [SlashCommand] 28 | [WebFetch] 29 | [WebSearch] 30 | } 31 | } 32 | 33 | package "Extension Layer" { 34 | 35 | package "Sub-agents (.claude/agnets/)" { 36 | component "general-purpose" as GP 37 | component "Explore" as Explore 38 | component "Plan" as Plan 39 | component "Custom Agents" as CustomAgents 40 | } 41 | 42 | package "Hooks (.claude/hooks/)" { 43 | component "user-prompt-submit" as PromptHook 44 | component "tool-call" as ToolHook 45 | component "pre-commit" as CommitHook 46 | component "Custom Hooks" as CustomHooks 47 | } 48 | 49 | package "Skills (.claude/skills/)" { 50 | component "PDF Processing" as PDFSkill 51 | component "Excel Processing" as XLSXSkill 52 | component "API Testing" as APISkill 53 | component "Code Review" as ReviewSkill 54 | component "Custom Skills" as CustomSkills 55 | } 56 | 57 | package "Slash Commands (.claude/commands/)" { 58 | component "/review-pr" as ReviewPRCmd 59 | component "/test" as TestCmd 60 | component "/deploy" as DeployCmd 61 | component "/refactor" as RefactorCmd 62 | component "/docs" as DocsCmd 63 | component "Custom Commands" as CustomCmds 64 | } 65 | } 66 | 67 | package "Configuration" { 68 | database "Settings" { 69 | file "~/.claude/settings.json" as GlobalSettings 70 | file ".claude/settings.json" as ProjectSettings 71 | file "CLAUDE.md" as ContextFile 72 | } 73 | 74 | database "Project Context" { 75 | folder ".claude/context/" as ContextDir 76 | folder ".claude/agents/" as AgentsDir 77 | } 78 | } 79 | 80 | package "External Integrations" { 81 | cloud "GitHub" as GitHub { 82 | [Issues] 83 | [Pull Requests] 84 | [Actions] 85 | } 86 | 87 | cloud "MCP Servers" as MCP { 88 | [IDE Server] 89 | [Custom Servers] 90 | } 91 | 92 | database "File System" as FS 93 | database "Git Repository" as Git 94 | } 95 | 96 | ' User interactions 97 | User --> Engine : send request 98 | Engine --> User : return result 99 | 100 | ' Core flow 101 | Engine --> [Intent Parser] : parse intent 102 | [Intent Parser] --> [Context Manager] : load context 103 | [Context Manager] --> ContextFile : read 104 | [Context Manager] --> ContextDir : read 105 | [Context Manager] --> ProjectSettings : read 106 | [Context Manager] --> GlobalSettings : read 107 | 108 | [Context Manager] --> [Execution Orchestrator] : execute with context 109 | [Execution Orchestrator] --> Tools : use tools 110 | 111 | ' Tool to Extension connections 112 | [Task] --> GP : invoke 113 | [Task] --> Explore : invoke 114 | [Task] --> Plan : invoke 115 | [Task] --> CustomAgents : invoke 116 | 117 | [Skill] --> PDFSkill : invoke 118 | [Skill] --> XLSXSkill : invoke 119 | [Skill] --> APISkill : invoke 120 | [Skill] --> ReviewSkill : invoke 121 | [Skill] --> CustomSkills : invoke 122 | 123 | [SlashCommand] --> ReviewPRCmd : invoke 124 | [SlashCommand] --> TestCmd : invoke 125 | [SlashCommand] --> DeployCmd : invoke 126 | [SlashCommand] --> RefactorCmd : invoke 127 | [SlashCommand] --> DocsCmd : invoke 128 | [SlashCommand] --> CustomCmds : invoke 129 | 130 | ' Hook integrations 131 | [Execution Orchestrator] --> PromptHook : trigger on prompt 132 | [Execution Orchestrator] --> ToolHook : trigger on tool call 133 | [Execution Orchestrator] --> CommitHook : trigger on commit 134 | [Execution Orchestrator] --> CustomHooks : trigger custom 135 | 136 | ' External integrations 137 | [Read] --> FS : read files 138 | [Write] --> FS : write files 139 | [Edit] --> FS : edit files 140 | [Bash] --> Git : git commands 141 | [Bash] --> GitHub : gh CLI 142 | 143 | [WebFetch] ..> MCP : fetch via MCP 144 | [WebSearch] ..> MCP : search via MCP 145 | 146 | Tools --> [mcp__ide__*] : IDE integration 147 | 148 | ' Result flow 149 | [Execution Orchestrator] --> [Result Formatter] : format results 150 | [Result Formatter] --> Engine : formatted output 151 | 152 | note right of Engine 153 | Agent(Intent, World₀) = 154 | lim_{n→∞} (θ₆_{Learn} ◦ θ₅_{Integrate} ◦ 155 | θ₄_{Execute} ◦ θ₃_{Allocate} ◦ 156 | θ₂_{Generate} ◦ θ₁_{Understand})ⁿ 157 | (Intent, World₀) 158 | end note 159 | 160 | legend right 161 | |= Component Type |= Description | 162 | | Built-in | Core Claude Code components | 163 | | Custom | User-defined extensions | 164 | | External | External services | 165 | endlegend 166 | 167 | @enduml 168 | -------------------------------------------------------------------------------- /.codex/readme.md: -------------------------------------------------------------------------------- 1 | # .claude/ - Claude Code Configuration Directory 2 | 3 | **Last Updated**: 2025-11-07 4 | **Version**: 2.0.0 5 | 6 | このディレクトリは、Claude Code Agent用の設定・カスタマイズファイルを格納します。 7 | 8 | --- 9 | 10 | ## 📁 ディレクトリ構造 11 | 12 | ``` 13 | .claude/ 14 | ├── readme.md # このファイル 15 | ├── AGENT_SOCIETY.md # Agent Society アーキテクチャ 16 | ├── MCP_INTEGRATION.md # MCP統合ガイド 17 | │ 18 | ├── agents/ # Specialized Sub-agents 19 | │ ├── readme.md 20 | │ ├── 3d-designer.md # Three.js専門家 21 | │ ├── game-creator.md # ゲーム開発専門家 22 | │ ├── mahjong-master.md # 麻雀AI統括 23 | │ ├── opponent-hand-reader.md # 対戦相手分析 24 | │ ├── tile-efficiency-analyzer.md # 牌効率計算 25 | │ ├── slide-generator.md # スライド生成 26 | │ ├── design-director.md # デザインプロジェクト統括 27 | │ ├── ui-ux-reviewer.md # UI/UXレビュー 28 | │ ├── legal-document-analyzer.md # 法務文書分析 29 | │ ├── contract-reviewer.md # 契約書レビュー 30 | │ └── compliance-gap-analyzer.md # コンプライアンスギャップ分析 31 | │ 32 | ├── societies/ # Agent Society定義 33 | │ ├── mahjong-society.yaml # 麻雀AI Society 34 | │ └── content-production-society.yaml 35 | │ 36 | ├── commands/ # Slash Commands 37 | │ └── readme.md 38 | │ 39 | ├── hooks/ # Lifecycle Hooks 40 | │ └── readme.md 41 | │ 42 | ├── skills/ # Reusable Skills 43 | │ └── readme.md 44 | │ 45 | └── *.puml # Architecture Diagrams 46 | ├── orchestrator-architecture.puml 47 | ├── orchestrator-execution-flow.puml 48 | ├── orchestrator-state-machine.puml 49 | ├── agent-lifecycle.puml 50 | ├── agent-state-machine.puml 51 | ├── mcp-integration.puml 52 | ├── subagent-isolation.puml 53 | ├── system-overview.puml 54 | └── before-after-comparison.puml 55 | ``` 56 | 57 | --- 58 | 59 | ## 🎯 主要コンポーネント 60 | 61 | ### 1. Specialized Sub-agents (`agents/`) 62 | 63 | タスク特化型のサブエージェント定義。各エージェントは独立した専門知識を持ちます。 64 | 65 | **カテゴリ:** 66 | 67 | #### 🎮 ゲーム・3D開発 68 | - `3d-designer.md` - Three.js専門家（3Dシーン、WebGL） 69 | - `game-creator.md` - ゲーム開発統括（企画→実装→バランス調整） 70 | 71 | #### 🀄 麻雀AI 72 | - `mahjong-master.md` - 麻雀AI統括（戦略最適化） 73 | - `opponent-hand-reader.md` - 捨て牌読み専門家 74 | - `tile-efficiency-analyzer.md` - 牌効率計算専門家 75 | 76 | #### 📊 コンテンツ制作 77 | - `slide-generator.md` - スライド生成（オンラインコース、プレゼン） 78 | - `design-director.md` - デザインプロジェクト統括 79 | 80 | #### ⚖️ 法務・コンプライアンス 81 | - `legal-document-analyzer.md` - 法務文書分析 82 | - `contract-reviewer.md` - 契約書レビュー 83 | - `compliance-gap-analyzer.md` - 法規制ギャップ分析 84 | 85 | #### 🎨 UI/UX 86 | - `ui-ux-reviewer.md` - インターフェース設計レビュー 87 | 88 | ### 2. Agent Societies (`societies/`) 89 | 90 | 複数のエージェントを協調動作させるSociety定義（YAML形式）。 91 | 92 | **利用可能なSocieties:** 93 | - `mahjong-society.yaml` - 麻雀AI Society（Master + HandReader + TileAnalyzer） 94 | - `content-production-society.yaml` - コンテンツ制作Society 95 | 96 | ### 3. Slash Commands (`commands/`) 97 | 98 | カスタムスラッシュコマンド定義。 99 | 100 | **使い方:** 101 | ```bash 102 | /your-command [args] 103 | ``` 104 | 105 | ### 4. Hooks (`hooks/`) 106 | 107 | エージェントライフサイクルフック。 108 | 109 | **利用可能なフック:** 110 | - `before-task` - タスク実行前 111 | - `after-task` - タスク実行後 112 | - `on-error` - エラー発生時 113 | 114 | ### 5. Skills (`skills/`) 115 | 116 | 再利用可能なスキル定義。 117 | 118 | --- 119 | 120 | ## 🏗️ アーキテクチャ図 (PlantUML) 121 | 122 | ### システム全体 123 | - `orchestrator-architecture.puml` - Orchestrator-Subagent アーキテクチャ 124 | - `system-overview.puml` - システム全体概要 125 | - `before-after-comparison.puml` - v1.0とv2.0の比較 126 | 127 | ### 実行フロー 128 | - `orchestrator-execution-flow.puml` - Orchestratorの実行フロー 129 | - `orchestrator-state-machine.puml` - Orchestrator状態マシン 130 | - `agent-lifecycle.puml` - Agent ライフサイクル 131 | - `agent-state-machine.puml` - Agent 状態マシン 132 | 133 | ### 統合 134 | - `mcp-integration.puml` - MCP統合フロー 135 | - `subagent-isolation.puml` - サブエージェント分離 136 | 137 | **図の生成:** 138 | ```bash 139 | # PlantUMLをインストール 140 | brew install plantuml 141 | 142 | # PNG生成 143 | plantuml .claude/*.puml 144 | 145 | # SVG生成 146 | plantuml -tsvg .claude/*.puml 147 | ``` 148 | 149 | --- 150 | 151 | ## 🚀 使用方法 152 | 153 | ### Sub-agentの呼び出し 154 | 155 | Claude Codeは、タスクに応じて自動的に適切なSub-agentを起動します。 156 | 157 | **例:** 158 | ``` 159 | User: "Three.jsで3Dキューブを回転させて" 160 | → Claude Codeが自動的に `3d-designer` agentを起動 161 | 162 | User: "この契約書をレビューして" 163 | → Claude Codeが自動的に `contract-reviewer` agentを起動 164 | ``` 165 | 166 | ### Agent Societyの活用 167 | 168 | 複雑なタスクは複数のAgentが協調して処理します。 169 | 170 | **例（麻雀AI）:** 171 | ``` 172 | User: "この局面の最善手を教えて" 173 | → mahjong-society起動 174 | ├─ tile-efficiency-analyzer: 牌効率計算 175 | ├─ opponent-hand-reader: 対戦相手分析 176 | └─ mahjong-master: 戦略統合・最終決定 177 | ``` 178 | 179 | --- 180 | 181 | ## 📖 関連ドキュメント 182 | 183 | ### プロジェクトルート 184 | - `../README.md` - プロジェクト全体概要 185 | - `../CLAUDE.md` - エージェント方程式定義 186 | - `../docs/QUICKSTART.md` - クイックスタートガイド 187 | - `../docs/architecture-docs/ORCHESTRATOR_ARCHITECTURE.md` - アーキテクチャ詳細 188 | 189 | ### 詳細ガイド 190 | - `AGENT_SOCIETY.md` - Agent Society設計原則 191 | - `MCP_INTEGRATION.md` - MCP統合ガイド 192 | - `agents/readme.md` - エージェント一覧 193 | 194 | --- 195 | 196 | ## 🔧 カスタマイズ 197 | 198 | ### 新しいSub-agentの追加 199 | 200 | 1. `agents/`に新しいMarkdownファイルを作成 201 | 2. エージェント定義を記述 202 | 3. Claude Codeが自動的に認識 203 | 204 | ### 新しいSocietyの定義 205 | 206 | 1. `societies/`に新しいYAMLファイルを作成 207 | 2. 協調するエージェントを定義 208 | 3. タスク分担・統合方法を記述 209 | 210 | --- 211 | 212 | ## 🔄 同期 213 | 214 | `.codex/`ディレクトリと同期されています（Codex Agent用）。 215 | 両ディレクトリは同じ構造・内容を保持します。 216 | 217 | --- 218 | 219 | **Note**: このディレクトリは Claude Code が自動的に参照します。 220 | 変更はプロジェクト全体のエージェント挙動に影響します。 221 | -------------------------------------------------------------------------------- /.claude/readme.md: -------------------------------------------------------------------------------- 1 | # .claude/ - Claude Code Configuration Directory 2 | 3 | **Last Updated**: 2025-11-07 4 | **Version**: 2.0.0 5 | 6 | このディレクトリは、Claude Code Agent用の設定・カスタマイズファイルを格納します。 7 | 8 | --- 9 | 10 | ## 📁 ディレクトリ構造 11 | 12 | ``` 13 | .claude/ 14 | ├── readme.md # このファイル 15 | ├── AGENT_SOCIETY.md # Agent Society アーキテクチャ 16 | ├── MCP_INTEGRATION.md # MCP統合ガイド 17 | │ 18 | ├── agents/ # Specialized Sub-agents 19 | │ ├── readme.md 20 | │ ├── 3d-designer.md # Three.js専門家 21 | │ ├── game-creator.md # ゲーム開発専門家 22 | │ ├── mahjong-master.md # 麻雀AI統括 23 | │ ├── opponent-hand-reader.md # 対戦相手分析 24 | │ ├── tile-efficiency-analyzer.md # 牌効率計算 25 | │ ├── slide-generator.md # スライド生成 26 | │ ├── design-director.md # デザインプロジェクト統括 27 | │ ├── ui-ux-reviewer.md # UI/UXレビュー 28 | │ ├── legal-document-analyzer.md # 法務文書分析 29 | │ ├── contract-reviewer.md # 契約書レビュー 30 | │ └── compliance-gap-analyzer.md # コンプライアンスギャップ分析 31 | │ 32 | ├── societies/ # Agent Society定義 33 | │ ├── mahjong-society.yaml # 麻雀AI Society 34 | │ └── content-production-society.yaml 35 | │ 36 | ├── commands/ # Slash Commands 37 | │ └── readme.md 38 | │ 39 | ├── hooks/ # Lifecycle Hooks 40 | │ └── readme.md 41 | │ 42 | ├── skills/ # Reusable Skills 43 | │ └── readme.md 44 | │ 45 | └── *.puml # Architecture Diagrams 46 | ├── orchestrator-architecture.puml 47 | ├── orchestrator-execution-flow.puml 48 | ├── orchestrator-state-machine.puml 49 | ├── agent-lifecycle.puml 50 | ├── agent-state-machine.puml 51 | ├── mcp-integration.puml 52 | ├── subagent-isolation.puml 53 | ├── system-overview.puml 54 | └── before-after-comparison.puml 55 | ``` 56 | 57 | --- 58 | 59 | ## 🎯 主要コンポーネント 60 | 61 | ### 1. Specialized Sub-agents (`agents/`) 62 | 63 | タスク特化型のサブエージェント定義。各エージェントは独立した専門知識を持ちます。 64 | 65 | **カテゴリ:** 66 | 67 | #### 🎮 ゲーム・3D開発 68 | - `3d-designer.md` - Three.js専門家（3Dシーン、WebGL） 69 | - `game-creator.md` - ゲーム開発統括（企画→実装→バランス調整） 70 | 71 | #### 🀄 麻雀AI 72 | - `mahjong-master.md` - 麻雀AI統括（戦略最適化） 73 | - `opponent-hand-reader.md` - 捨て牌読み専門家 74 | - `tile-efficiency-analyzer.md` - 牌効率計算専門家 75 | 76 | #### 📊 コンテンツ制作 77 | - `slide-generator.md` - スライド生成（オンラインコース、プレゼン） 78 | - `design-director.md` - デザインプロジェクト統括 79 | 80 | #### ⚖️ 法務・コンプライアンス 81 | - `legal-document-analyzer.md` - 法務文書分析 82 | - `contract-reviewer.md` - 契約書レビュー 83 | - `compliance-gap-analyzer.md` - 法規制ギャップ分析 84 | 85 | #### 🎨 UI/UX 86 | - `ui-ux-reviewer.md` - インターフェース設計レビュー 87 | 88 | ### 2. Agent Societies (`societies/`) 89 | 90 | 複数のエージェントを協調動作させるSociety定義（YAML形式）。 91 | 92 | **利用可能なSocieties:** 93 | - `mahjong-society.yaml` - 麻雀AI Society（Master + HandReader + TileAnalyzer） 94 | - `content-production-society.yaml` - コンテンツ制作Society 95 | 96 | ### 3. Slash Commands (`commands/`) 97 | 98 | カスタムスラッシュコマンド定義。 99 | 100 | **使い方:** 101 | ```bash 102 | /your-command [args] 103 | ``` 104 | 105 | ### 4. Hooks (`hooks/`) 106 | 107 | エージェントライフサイクルフック。 108 | 109 | **利用可能なフック:** 110 | - `before-task` - タスク実行前 111 | - `after-task` - タスク実行後 112 | - `on-error` - エラー発生時 113 | 114 | ### 5. Skills (`skills/`) 115 | 116 | 再利用可能なスキル定義。 117 | 118 | --- 119 | 120 | ## 🏗️ アーキテクチャ図 (PlantUML) 121 | 122 | ### システム全体 123 | - `orchestrator-architecture.puml` - Orchestrator-Subagent アーキテクチャ 124 | - `system-overview.puml` - システム全体概要 125 | - `before-after-comparison.puml` - v1.0とv2.0の比較 126 | 127 | ### 実行フロー 128 | - `orchestrator-execution-flow.puml` - Orchestratorの実行フロー 129 | - `orchestrator-state-machine.puml` - Orchestrator状態マシン 130 | - `agent-lifecycle.puml` - Agent ライフサイクル 131 | - `agent-state-machine.puml` - Agent 状態マシン 132 | 133 | ### 統合 134 | - `mcp-integration.puml` - MCP統合フロー 135 | - `subagent-isolation.puml` - サブエージェント分離 136 | 137 | **図の生成:** 138 | ```bash 139 | # PlantUMLをインストール 140 | brew install plantuml 141 | 142 | # PNG生成 143 | plantuml .claude/*.puml 144 | 145 | # SVG生成 146 | plantuml -tsvg .claude/*.puml 147 | ``` 148 | 149 | --- 150 | 151 | ## 🚀 使用方法 152 | 153 | ### Sub-agentの呼び出し 154 | 155 | Claude Codeは、タスクに応じて自動的に適切なSub-agentを起動します。 156 | 157 | **例:** 158 | ``` 159 | User: "Three.jsで3Dキューブを回転させて" 160 | → Claude Codeが自動的に `3d-designer` agentを起動 161 | 162 | User: "この契約書をレビューして" 163 | → Claude Codeが自動的に `contract-reviewer` agentを起動 164 | ``` 165 | 166 | ### Agent Societyの活用 167 | 168 | 複雑なタスクは複数のAgentが協調して処理します。 169 | 170 | **例（麻雀AI）:** 171 | ``` 172 | User: "この局面の最善手を教えて" 173 | → mahjong-society起動 174 | ├─ tile-efficiency-analyzer: 牌効率計算 175 | ├─ opponent-hand-reader: 対戦相手分析 176 | └─ mahjong-master: 戦略統合・最終決定 177 | ``` 178 | 179 | --- 180 | 181 | ## 📖 関連ドキュメント 182 | 183 | ### プロジェクトルート 184 | - `../README.md` - プロジェクト全体概要 185 | - `../CLAUDE.md` - エージェント方程式定義 186 | - `../docs/QUICKSTART.md` - クイックスタートガイド 187 | - `../docs/architecture-docs/ORCHESTRATOR_ARCHITECTURE.md` - アーキテクチャ詳細 188 | 189 | ### 詳細ガイド 190 | - `AGENT_SOCIETY.md` - Agent Society設計原則 191 | - `MCP_INTEGRATION.md` - MCP統合ガイド 192 | - `agents/readme.md` - エージェント一覧 193 | 194 | --- 195 | 196 | ## 🔧 カスタマイズ 197 | 198 | ### 新しいSub-agentの追加 199 | 200 | 1. `agents/`に新しいMarkdownファイルを作成 201 | 2. エージェント定義を記述 202 | 3. Claude Codeが自動的に認識 203 | 204 | ### 新しいSocietyの定義 205 | 206 | 1. `societies/`に新しいYAMLファイルを作成 207 | 2. 協調するエージェントを定義 208 | 3. タスク分担・統合方法を記述 209 | 210 | --- 211 | 212 | ## 🔄 同期 213 | 214 | `.codex/`ディレクトリと同期されています（Codex Agent用）。 215 | 両ディレクトリは同じ構造・内容を保持します。 216 | 217 | --- 218 | 219 | **Note**: このディレクトリは Claude Code が自動的に参照します。 220 | 変更はプロジェクト全体のエージェント挙動に影響します。 221 | -------------------------------------------------------------------------------- /.claude/hooks/voicevox-narration.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | # VOICEVOX Narration Hook for Claude Code 3 | # 霊夢と魔理沙がClaude Codeの操作を読み上げる 4 | 5 | set -euo pipefail 6 | 7 | # ============================================================ 8 | # Configuration 9 | # ============================================================ 10 | 11 | VOICEVOX_URL="${VOICEVOX_URL:-http://127.0.0.1:50021}" 12 | CACHE_DIR="${HOME}/.claude/voicevox_cache" 13 | REIMU_SPEAKER_ID="${REIMU_SPEAKER_ID:-0}" # 四国めたん（霊夢役） 14 | MARISA_SPEAKER_ID="${MARISA_SPEAKER_ID:-8}" # 春日部つむぎ（魔理沙役） 15 | 16 | # ============================================================ 17 | # Helper Functions 18 | # ============================================================ 19 | 20 | log() { 21 | echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >&2 22 | } 23 | 24 | check_voicevox() { 25 | if ! curl -s "${VOICEVOX_URL}/version" >/dev/null 2>&1; then 26 | log "WARNING: VOICEVOX is not running at ${VOICEVOX_URL}" 27 | return 1 28 | fi 29 | return 0 30 | } 31 | 32 | synthesize_audio() { 33 | local text="$1" 34 | local speaker_id="$2" 35 | local output_file="$3" 36 | 37 | # Generate audio query 38 | local query=$(curl -s -X POST \ 39 | "${VOICEVOX_URL}/audio_query?speaker=${speaker_id}&text=${text}" \ 40 | -H "Content-Type: application/json") 41 | 42 | if [ -z "$query" ]; then 43 | log "ERROR: Failed to generate audio query" 44 | return 1 45 | fi 46 | 47 | # Synthesize audio 48 | curl -s -X POST \ 49 | "${VOICEVOX_URL}/synthesis?speaker=${speaker_id}" \ 50 | -H "Content-Type: application/json" \ 51 | -d "$query" \ 52 | -o "$output_file" 53 | 54 | return 0 55 | } 56 | 57 | play_audio() { 58 | local file="$1" 59 | 60 | if [[ "$OSTYPE" == "darwin"* ]]; then 61 | afplay "$file" 2>/dev/null & 62 | elif command -v paplay >/dev/null 2>&1; then 63 | paplay "$file" 2>/dev/null & 64 | elif command -v aplay >/dev/null 2>&1; then 65 | aplay "$file" 2>/dev/null & 66 | else 67 | log "WARNING: No audio player found" 68 | return 1 69 | fi 70 | 71 | return 0 72 | } 73 | 74 | get_cache_file() { 75 | local text="$1" 76 | local speaker_id="$2" 77 | local hash=$(echo -n "${text}_${speaker_id}" | md5sum | cut -d' ' -f1) 78 | echo "${CACHE_DIR}/${hash}.wav" 79 | } 80 | 81 | narrate() { 82 | local character="$1" 83 | local text="$2" 84 | 85 | # Determine speaker ID 86 | local speaker_id 87 | case "$character" in 88 | reimu) speaker_id="$REIMU_SPEAKER_ID" ;; 89 | marisa) speaker_id="$MARISA_SPEAKER_ID" ;; 90 | *) log "ERROR: Unknown character: $character"; return 1 ;; 91 | esac 92 | 93 | # Check cache 94 | local cache_file=$(get_cache_file "$text" "$speaker_id") 95 | 96 | if [ ! -f "$cache_file" ]; then 97 | log "Synthesizing: [$character] $text" 98 | mkdir -p "$CACHE_DIR" 99 | if ! synthesize_audio "$text" "$speaker_id" "$cache_file"; then 100 | log "ERROR: Failed to synthesize audio" 101 | return 1 102 | fi 103 | fi 104 | 105 | # Play audio 106 | play_audio "$cache_file" 107 | } 108 | 109 | # ============================================================ 110 | # Event Handlers 111 | # ============================================================ 112 | 113 | handle_tool_call() { 114 | local tool_name="$1" 115 | 116 | # Check VOICEVOX availability 117 | if ! check_voicevox; then 118 | return 0 # Silent fail 119 | fi 120 | 121 | case "$tool_name" in 122 | Read) 123 | narrate reimu "ファイルを読むよ！" 124 | ;; 125 | Write) 126 | narrate marisa "ファイルに書き込むぜ" 127 | ;; 128 | Edit) 129 | narrate marisa "コードを編集してるんだ" 130 | ;; 131 | Bash) 132 | narrate reimu "コマンドを実行するね" 133 | ;; 134 | Grep) 135 | narrate marisa "検索してるぜ" 136 | ;; 137 | Task) 138 | narrate reimu "エージェントを起動したよ！" 139 | narrate marisa "複雑な作業を分解して実行するんだ" 140 | ;; 141 | *) 142 | # Default narration 143 | narrate reimu "${tool_name}を実行中..." 144 | ;; 145 | esac 146 | } 147 | 148 | handle_user_prompt() { 149 | # Check VOICEVOX availability 150 | if ! check_voicevox; then 151 | return 0 # Silent fail 152 | fi 153 | 154 | # Random chance to narrate (10%) 155 | if [ $((RANDOM % 10)) -eq 0 ]; then 156 | narrate marisa "新しいタスクだぜ！頑張ろう！" 157 | fi 158 | } 159 | 160 | handle_task_complete() { 161 | # Check VOICEVOX availability 162 | if ! check_voicevox; then 163 | return 0 # Silent fail 164 | fi 165 | 166 | narrate reimu "やったね！完了したよ！" 167 | narrate marisa "いい仕事だったぜ" 168 | } 169 | 170 | # ============================================================ 171 | # Main 172 | # ============================================================ 173 | 174 | main() { 175 | local hook_type="${1:-}" 176 | local tool_name="${2:-}" 177 | 178 | case "$hook_type" in 179 | tool-call) 180 | handle_tool_call "$tool_name" 181 | ;; 182 | user-prompt-submit) 183 | handle_user_prompt 184 | ;; 185 | task-complete) 186 | handle_task_complete 187 | ;; 188 | *) 189 | log "Unknown hook type: $hook_type" 190 | exit 1 191 | ;; 192 | esac 193 | } 194 | 195 | # Run main if executed directly 196 | if [ "${BASH_SOURCE[0]}" = "${0}" ]; then 197 | main "$@" 198 | fi 199 | -------------------------------------------------------------------------------- /scripts/voicevox_speak.py: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | """ 3 | VoiceVox Text-to-Speech Script 4 | 音声読み上げスクリプト 5 | 6 | Usage: 7 | python3 voicevox_speak.py "読み上げるテキスト" [speaker_id] 8 | """ 9 | 10 | import sys 11 | import json 12 | import subprocess 13 | import tempfile 14 | from pathlib import Path 15 | from urllib import request, error 16 | from urllib.parse import urlencode 17 | 18 | # VoiceVox API Configuration 19 | VOICEVOX_URL = "http://localhost:50021" 20 | 21 | # Speaker IDs (VoiceVox標準) 22 | SPEAKERS = { 23 | "zundamon": 3, # ずんだもん（ノーマル） 24 | "metan": 2, # 四国めたん（ノーマル） 25 | "tsumugi": 8, # 春日部つむぎ（ノーマル） 26 | "ritsu": 9, # 雨晴はう（ノーマル） 27 | "default": 3 # デフォルト: ずんだもん 28 | } 29 | 30 | 31 | def check_voicevox_running(): 32 | """Check if VoiceVox engine is running""" 33 | try: 34 | with request.urlopen(f"{VOICEVOX_URL}/version", timeout=2) as response: 35 | version = json.loads(response.read().decode()) 36 | print(f"✓ VoiceVox Engine v{version} detected", file=sys.stderr) 37 | return True 38 | except (error.URLError, error.HTTPError): 39 | print("✗ VoiceVox Engine not running", file=sys.stderr) 40 | print(" Please start VoiceVox Engine first:", file=sys.stderr) 41 | print(" https://voicevox.hiroshiba.jp/", file=sys.stderr) 42 | return False 43 | 44 | 45 | def text_to_speech(text: str, speaker_id: int = 3): 46 | """ 47 | Convert text to speech using VoiceVox API 48 | 49 | Args: 50 | text: Text to convert to speech 51 | speaker_id: Speaker ID (default: 3 = ずんだもん) 52 | 53 | Returns: 54 | bytes: Audio data (wav format) 55 | """ 56 | # Step 1: Generate audio query 57 | query_params = urlencode({"text": text, "speaker": speaker_id}) 58 | query_url = f"{VOICEVOX_URL}/audio_query?{query_params}" 59 | 60 | try: 61 | req = request.Request(query_url, method="POST") 62 | with request.urlopen(req, timeout=10) as response: 63 | audio_query = response.read() 64 | except (error.URLError, error.HTTPError) as e: 65 | raise Exception(f"Failed to generate audio query: {e}") 66 | 67 | # Step 2: Synthesize speech 68 | synthesis_url = f"{VOICEVOX_URL}/synthesis?speaker={speaker_id}" 69 | headers = {"Content-Type": "application/json"} 70 | 71 | try: 72 | req = request.Request( 73 | synthesis_url, 74 | data=audio_query, 75 | headers=headers, 76 | method="POST" 77 | ) 78 | with request.urlopen(req, timeout=30) as response: 79 | audio_data = response.read() 80 | except (error.URLError, error.HTTPError) as e: 81 | raise Exception(f"Failed to synthesize speech: {e}") 82 | 83 | return audio_data 84 | 85 | 86 | def play_audio(audio_data: bytes): 87 | """ 88 | Play audio data using system audio player 89 | 90 | Args: 91 | audio_data: Audio data in wav format 92 | """ 93 | # Create temporary file 94 | with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as temp_file: 95 | temp_path = temp_file.name 96 | temp_file.write(audio_data) 97 | 98 | try: 99 | # Try different audio players based on platform 100 | players = [ 101 | ["afplay", temp_path], # macOS 102 | ["play", temp_path], # Linux (sox) 103 | ["aplay", temp_path], # Linux (alsa) 104 | ["ffplay", "-nodisp", "-autoexit", temp_path] # Cross-platform (ffmpeg) 105 | ] 106 | 107 | played = False 108 | for player_cmd in players: 109 | try: 110 | subprocess.run( 111 | player_cmd, 112 | check=True, 113 | stdout=subprocess.DEVNULL, 114 | stderr=subprocess.DEVNULL 115 | ) 116 | played = True 117 | break 118 | except (subprocess.CalledProcessError, FileNotFoundError): 119 | continue 120 | 121 | if not played: 122 | print(f"⚠ No audio player found. Audio saved to: {temp_path}", file=sys.stderr) 123 | print(f" You can play it manually with: afplay {temp_path}", file=sys.stderr) 124 | else: 125 | # Clean up temporary file after playback 126 | Path(temp_path).unlink(missing_ok=True) 127 | 128 | except Exception as e: 129 | print(f"✗ Failed to play audio: {e}", file=sys.stderr) 130 | Path(temp_path).unlink(missing_ok=True) 131 | 132 | 133 | def main(): 134 | """Main function""" 135 | if len(sys.argv) < 2: 136 | print("Usage: voicevox_speak.py [speaker]", file=sys.stderr) 137 | print(f"\nAvailable speakers: {', '.join(SPEAKERS.keys())}", file=sys.stderr) 138 | sys.exit(1) 139 | 140 | text = sys.argv[1] 141 | 142 | # Parse speaker argument 143 | speaker_arg = sys.argv[2] if len(sys.argv) > 2 else "default" 144 | speaker_id = SPEAKERS.get(speaker_arg.lower(), SPEAKERS["default"]) 145 | 146 | # Check if VoiceVox is running 147 | if not check_voicevox_running(): 148 | sys.exit(1) 149 | 150 | print(f"🎤 Speaking: \"{text}\" (Speaker: {speaker_arg})", file=sys.stderr) 151 | 152 | try: 153 | # Generate speech 154 | audio_data = text_to_speech(text, speaker_id) 155 | 156 | # Play audio 157 | play_audio(audio_data) 158 | 159 | print("✓ Playback complete", file=sys.stderr) 160 | 161 | except Exception as e: 162 | print(f"✗ Error: {e}", file=sys.stderr) 163 | sys.exit(1) 164 | 165 | 166 | if __name__ == "__main__": 167 | main() 168 | -------------------------------------------------------------------------------- /.claude/skills/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Skill Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Skill Execution Lifecycle 7 | 8 | |Main Agent| 9 | start 10 | :Analyze User Request; 11 | 12 | if (Request Matches Skill?) then (yes) 13 | :Identify Appropriate Skill; 14 | note right 15 | Match against: 16 | - PDF processing 17 | - Excel processing 18 | - API testing 19 | - Code review 20 | - Custom skills 21 | end note 22 | else (no) 23 | :Use Standard Tools; 24 | stop 25 | endif 26 | 27 | |Skill Registry| 28 | :Lookup Skill Definition; 29 | 30 | if (Skill Found?) then (no) 31 | :Report Skill Not Available; 32 | |Main Agent| 33 | :Fallback to Alternative; 34 | stop 35 | else (yes) 36 | :Load Skill Metadata; 37 | note right 38 | Metadata includes: 39 | - Skill name 40 | - Trigger conditions 41 | - Required dependencies 42 | - Prompt template 43 | end note 44 | endif 45 | 46 | |Skill Tool| 47 | :Invoke Skill Tool; 48 | :Validate Skill Name; 49 | 50 | if (Skill Already Running?) then (yes) 51 | :Return Error; 52 | note right 53 | Cannot invoke skill 54 | that is already running 55 | end note 56 | |Main Agent| 57 | :Wait for Completion; 58 | stop 59 | else (not running) 60 | :Mark as Running; 61 | endif 62 | 63 | |Skill Executor| 64 | partition "Skill Initialization" { 65 | :Load Skill Prompt; 66 | :Check Dependencies; 67 | 68 | if (Dependencies Met?) then (no) 69 | :Report Missing Dependencies; 70 | note right 71 | Example: 72 | "PyPDF2 not installed 73 | Run: pip install PyPDF2" 74 | end note 75 | |Main Agent| 76 | :Handle Dependency Error; 77 | stop 78 | else (yes) 79 | :Initialize Skill Context; 80 | endif 81 | 82 | :Expand Prompt Template; 83 | note right 84 | Skill prompt provides: 85 | - Task instructions 86 | - Domain knowledge 87 | - Best practices 88 | - Expected output format 89 | end note 90 | } 91 | 92 | partition "Skill Execution" { 93 | :Process with Skill Context; 94 | 95 | if (Skill Pattern?) then (Proactive) 96 | #LightBlue:Auto-execute on Conditions; 97 | note right 98 | Example: 99 | Auto-test after code changes 100 | end note 101 | 102 | else if (On-Demand) 103 | #LightGreen:Execute User Request; 104 | note right 105 | Example: 106 | User requests PDF processing 107 | end note 108 | 109 | else (Pipeline) 110 | #LightYellow:Execute in Chain; 111 | note right 112 | Example: 113 | code-review -> test -> deploy 114 | end note 115 | 116 | :Check Previous Step; 117 | if (Previous Failed?) then (yes) 118 | :Skip Execution; 119 | :Report Dependency Failure; 120 | |Main Agent| 121 | :Handle Pipeline Failure; 122 | stop 123 | else (passed) 124 | :Continue Execution; 125 | endif 126 | endif 127 | 128 | :Execute Skill Logic; 129 | 130 | if (Skill Type?) then (PDF Processing) 131 | :Read/Generate PDF; 132 | :Extract/Merge Content; 133 | else if (Excel Processing) 134 | :Parse Spreadsheet; 135 | :Process Data; 136 | :Generate Excel; 137 | else if (API Testing) 138 | :Build Requests; 139 | :Validate Responses; 140 | :Generate Report; 141 | else if (Code Review) 142 | :Analyze Code Quality; 143 | :Check Security; 144 | :Review Performance; 145 | :Generate Feedback; 146 | else (Custom Skill) 147 | :Execute Custom Logic; 148 | endif 149 | 150 | :Collect Results; 151 | } 152 | 153 | partition "Result Processing" { 154 | if (Execution Successful?) then (yes) 155 | :Format Output; 156 | note right 157 | Format based on skill type: 158 | - PDF: file path + metadata 159 | - Excel: data + statistics 160 | - API: test results 161 | - Review: feedback report 162 | end note 163 | 164 | :Validate Output; 165 | 166 | if (Output Valid?) then (yes) 167 | :Return Success; 168 | else (invalid) 169 | :Return Error; 170 | note right 171 | Partial results may 172 | still be useful 173 | end note 174 | endif 175 | 176 | else (failed) 177 | :Capture Error Details; 178 | :Return Failure; 179 | endif 180 | } 181 | 182 | |Skill Tool| 183 | :Mark as Completed; 184 | :Return Results to Agent; 185 | 186 | |Main Agent| 187 | :Process Skill Results; 188 | 189 | if (Results Satisfactory?) then (yes) 190 | :Integrate Results; 191 | :Continue Main Task; 192 | 193 | else if (Need Different Skill?) then (yes) 194 | :Select Another Skill; 195 | detach 196 | 197 | else (failed) 198 | :Handle Skill Failure; 199 | 200 | if (Can Fallback?) then (yes) 201 | :Use Alternative Approach; 202 | else (no) 203 | :Report Error to User; 204 | endif 205 | endif 206 | 207 | :Complete Task; 208 | stop 209 | 210 | note bottom 211 | **Skill Execution Characteristics:** 212 | 213 | 1. **Domain-Specific** - Specialized knowledge and capabilities 214 | 2. **Stateful** - Cannot run same skill twice concurrently 215 | 3. **Dependency-Aware** - Checks requirements before execution 216 | 4. **Pattern-Based** - Proactive, On-Demand, or Pipeline 217 | 5. **Context-Rich** - Uses expanded prompts with domain expertise 218 | 6. **Validated Output** - Results checked for correctness 219 | end note 220 | 221 | legend right 222 | |= Skill Pattern |= Trigger | 223 | | Proactive | Auto on conditions | 224 | | On-Demand | User request | 225 | | Pipeline | Chained execution | 226 | 227 | |= Common Skills |= Purpose | 228 | | PDF | Document processing | 229 | | Excel | Data analysis | 230 | | API Test | Endpoint validation | 231 | | Code Review | Quality check | 232 | endlegend 233 | 234 | @enduml 235 | -------------------------------------------------------------------------------- /.codex/skills/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Skill Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Skill Execution Lifecycle 7 | 8 | |Main Agent| 9 | start 10 | :Analyze User Request; 11 | 12 | if (Request Matches Skill?) then (yes) 13 | :Identify Appropriate Skill; 14 | note right 15 | Match against: 16 | - PDF processing 17 | - Excel processing 18 | - API testing 19 | - Code review 20 | - Custom skills 21 | end note 22 | else (no) 23 | :Use Standard Tools; 24 | stop 25 | endif 26 | 27 | |Skill Registry| 28 | :Lookup Skill Definition; 29 | 30 | if (Skill Found?) then (no) 31 | :Report Skill Not Available; 32 | |Main Agent| 33 | :Fallback to Alternative; 34 | stop 35 | else (yes) 36 | :Load Skill Metadata; 37 | note right 38 | Metadata includes: 39 | - Skill name 40 | - Trigger conditions 41 | - Required dependencies 42 | - Prompt template 43 | end note 44 | endif 45 | 46 | |Skill Tool| 47 | :Invoke Skill Tool; 48 | :Validate Skill Name; 49 | 50 | if (Skill Already Running?) then (yes) 51 | :Return Error; 52 | note right 53 | Cannot invoke skill 54 | that is already running 55 | end note 56 | |Main Agent| 57 | :Wait for Completion; 58 | stop 59 | else (not running) 60 | :Mark as Running; 61 | endif 62 | 63 | |Skill Executor| 64 | partition "Skill Initialization" { 65 | :Load Skill Prompt; 66 | :Check Dependencies; 67 | 68 | if (Dependencies Met?) then (no) 69 | :Report Missing Dependencies; 70 | note right 71 | Example: 72 | "PyPDF2 not installed 73 | Run: pip install PyPDF2" 74 | end note 75 | |Main Agent| 76 | :Handle Dependency Error; 77 | stop 78 | else (yes) 79 | :Initialize Skill Context; 80 | endif 81 | 82 | :Expand Prompt Template; 83 | note right 84 | Skill prompt provides: 85 | - Task instructions 86 | - Domain knowledge 87 | - Best practices 88 | - Expected output format 89 | end note 90 | } 91 | 92 | partition "Skill Execution" { 93 | :Process with Skill Context; 94 | 95 | if (Skill Pattern?) then (Proactive) 96 | #LightBlue:Auto-execute on Conditions; 97 | note right 98 | Example: 99 | Auto-test after code changes 100 | end note 101 | 102 | else if (On-Demand) 103 | #LightGreen:Execute User Request; 104 | note right 105 | Example: 106 | User requests PDF processing 107 | end note 108 | 109 | else (Pipeline) 110 | #LightYellow:Execute in Chain; 111 | note right 112 | Example: 113 | code-review -> test -> deploy 114 | end note 115 | 116 | :Check Previous Step; 117 | if (Previous Failed?) then (yes) 118 | :Skip Execution; 119 | :Report Dependency Failure; 120 | |Main Agent| 121 | :Handle Pipeline Failure; 122 | stop 123 | else (passed) 124 | :Continue Execution; 125 | endif 126 | endif 127 | 128 | :Execute Skill Logic; 129 | 130 | if (Skill Type?) then (PDF Processing) 131 | :Read/Generate PDF; 132 | :Extract/Merge Content; 133 | else if (Excel Processing) 134 | :Parse Spreadsheet; 135 | :Process Data; 136 | :Generate Excel; 137 | else if (API Testing) 138 | :Build Requests; 139 | :Validate Responses; 140 | :Generate Report; 141 | else if (Code Review) 142 | :Analyze Code Quality; 143 | :Check Security; 144 | :Review Performance; 145 | :Generate Feedback; 146 | else (Custom Skill) 147 | :Execute Custom Logic; 148 | endif 149 | 150 | :Collect Results; 151 | } 152 | 153 | partition "Result Processing" { 154 | if (Execution Successful?) then (yes) 155 | :Format Output; 156 | note right 157 | Format based on skill type: 158 | - PDF: file path + metadata 159 | - Excel: data + statistics 160 | - API: test results 161 | - Review: feedback report 162 | end note 163 | 164 | :Validate Output; 165 | 166 | if (Output Valid?) then (yes) 167 | :Return Success; 168 | else (invalid) 169 | :Return Error; 170 | note right 171 | Partial results may 172 | still be useful 173 | end note 174 | endif 175 | 176 | else (failed) 177 | :Capture Error Details; 178 | :Return Failure; 179 | endif 180 | } 181 | 182 | |Skill Tool| 183 | :Mark as Completed; 184 | :Return Results to Agent; 185 | 186 | |Main Agent| 187 | :Process Skill Results; 188 | 189 | if (Results Satisfactory?) then (yes) 190 | :Integrate Results; 191 | :Continue Main Task; 192 | 193 | else if (Need Different Skill?) then (yes) 194 | :Select Another Skill; 195 | detach 196 | 197 | else (failed) 198 | :Handle Skill Failure; 199 | 200 | if (Can Fallback?) then (yes) 201 | :Use Alternative Approach; 202 | else (no) 203 | :Report Error to User; 204 | endif 205 | endif 206 | 207 | :Complete Task; 208 | stop 209 | 210 | note bottom 211 | **Skill Execution Characteristics:** 212 | 213 | 1. **Domain-Specific** - Specialized knowledge and capabilities 214 | 2. **Stateful** - Cannot run same skill twice concurrently 215 | 3. **Dependency-Aware** - Checks requirements before execution 216 | 4. **Pattern-Based** - Proactive, On-Demand, or Pipeline 217 | 5. **Context-Rich** - Uses expanded prompts with domain expertise 218 | 6. **Validated Output** - Results checked for correctness 219 | end note 220 | 221 | legend right 222 | |= Skill Pattern |= Trigger | 223 | | Proactive | Auto on conditions | 224 | | On-Demand | User request | 225 | | Pipeline | Chained execution | 226 | 227 | |= Common Skills |= Purpose | 228 | | PDF | Document processing | 229 | | Excel | Data analysis | 230 | | API Test | Endpoint validation | 231 | | Code Review | Quality check | 232 | endlegend 233 | 234 | @enduml 235 | -------------------------------------------------------------------------------- /.claude/commands/voicevox.md: -------------------------------------------------------------------------------- 1 | --- 2 | description: "Enable VoiceVox text-to-speech mode for responses" 3 | --- 4 | 5 | # VoiceVox 音声読み上げモード 6 | 7 | VoiceVoxを使用してClaude Codeの応答を音声で読み上げるモードを有効にします。 8 | 9 | ## 🎤 概要 10 | 11 | このコマンドは、以下の機能を提供します： 12 | 13 | 1. **音声読み上げモードの有効化**: Claude の応答を自動的に音声で読み上げ 14 | 2. **複数の話者選択**: ずんだもん、四国めたん、春日部つむぎなど 15 | 3. **重要な情報の強調**: エラーやワーニングを特別な声で読み上げ 16 | 17 | ## 📋 前提条件 18 | 19 | ### VoiceVox Engine のインストールと起動 20 | 21 | **macOS / Linux / Windows:** 22 | 1. VoiceVox Engine をダウンロード: https://voicevox.hiroshiba.jp/ 23 | 2. インストール後、VoiceVox Engine を起動 24 | 3. デフォルトで `http://localhost:50021` で API が利用可能になります 25 | 26 | **動作確認:** 27 | ```bash 28 | curl http://localhost:50021/version 29 | ``` 30 | 31 | ## 🚀 使い方 32 | 33 | ### 基本的な使い方 34 | 35 | ```bash 36 | # デフォルトの話者（ずんだもん）で音声読み上げモードを有効化 37 | /voicevox 38 | 39 | # 特定の話者を指定 40 | /voicevox metan # 四国めたん 41 | /voicevox tsumugi # 春日部つむぎ 42 | /voicevox zundamon # ずんだもん 43 | ``` 44 | 45 | ### コマンド実行後の動作 46 | 47 | 音声読み上げモードが有効になると、以下のように動作します： 48 | 49 | 1. **通常の応答**: 全ての応答を指定した話者の声で読み上げ 50 | 2. **コード説明**: コードの内容を日本語で説明して読み上げ 51 | 3. **エラー通知**: エラーが発生した場合は音声で通知 52 | 4. **完了通知**: タスク完了時に音声で通知 53 | 54 | ## 🎯 実装すべき動作 55 | 56 | ### 音声読み上げの対象 57 | 58 | 以下の情報を音声で読み上げます： 59 | 60 | #### 1. 通常の応答 61 | ``` 62 | ユーザー: "ファイルを読み込んで" 63 | Claude (音声): "はい、ファイルを読み込みます。ファイルの内容を確認しました。" 64 | ``` 65 | 66 | #### 2. ツール実行の通知 67 | ``` 68 | Claude (音声): "Bashツールを使用してコマンドを実行します。" 69 | [コマンド実行] 70 | Claude (音声): "コマンドが正常に完了しました。" 71 | ``` 72 | 73 | #### 3. エラー通知 74 | ``` 75 | Claude (音声): "エラーが発生しました。ファイルが見つかりません。" 76 | ``` 77 | 78 | #### 4. 重要な情報の強調 79 | ``` 80 | Claude (音声): "注意: このコマンドは本番環境に影響を与える可能性があります。" 81 | ``` 82 | 83 | ### 読み上げのタイミング 84 | 85 | - **即座に読み上げ**: 短い応答（200文字以内）は即座に読み上げ 86 | - **段落ごとに読み上げ**: 長い応答は段落ごとに分けて読み上げ 87 | - **重要情報を優先**: エラーやワーニングは最優先で読み上げ 88 | 89 | ### 読み上げのスキップ対象 90 | 91 | 以下のコンテンツは読み上げをスキップ： 92 | 93 | - コードブロック（コード自体は読まない、説明のみ読む） 94 | - 長いログ出力（要約のみ読む） 95 | - マークダウンの記号（`#`, `*`, `-` など） 96 | - URL（「URLが表示されています」と読む） 97 | 98 | ## 🔧 音声読み上げの実装手順 99 | 100 | ### ステップ1: VoiceVox Engine の確認 101 | 102 | ```bash 103 | # VoiceVox Engine が起動しているか確認 104 | python3 scripts/voicevox_speak.py "テストです" 105 | ``` 106 | 107 | ### ステップ2: 音声読み上げモードの有効化 108 | 109 | 音声読み上げモードが有効になると、以下のフラグを内部的に設定： 110 | 111 | ``` 112 | VOICEVOX_MODE=true 113 | VOICEVOX_SPEAKER=<選択した話者> 114 | ``` 115 | 116 | ### ステップ3: 応答の音声化 117 | 118 | 各応答を生成した後、以下の処理を実行： 119 | 120 | 1. **テキストのクリーニング**: マークダウン記号、コードブロックを除去 121 | 2. **テキストの分割**: 長い文章を適切な長さに分割（100-200文字） 122 | 3. **音声合成**: VoiceVox API を使用して音声を生成 123 | 4. **再生**: 生成した音声を自動再生 124 | 125 | ### ステップ4: 音声読み上げの例 126 | 127 | ```python 128 | # Example: 応答を音声で読み上げる 129 | response_text = "ファイルの読み込みが完了しました。全部で150行あります。" 130 | 131 | # クリーニング 132 | cleaned_text = clean_markdown(response_text) 133 | 134 | # 音声合成と再生 135 | subprocess.run([ 136 | "python3", 137 | "scripts/voicevox_speak.py", 138 | cleaned_text, 139 | speaker 140 | ]) 141 | ``` 142 | 143 | ## 📝 利用シーン 144 | 145 | ### シーン1: コーディング中の通知 146 | 147 | ``` 148 | ユーザー: "テストを実行して" 149 | Claude: "テストを実行します。" 150 | [音声] 🎤 "テストを実行します" 151 | [テスト実行中...] 152 | [音声] 🎤 "テストが完了しました。すべてのテストに合格しました。" 153 | ``` 154 | 155 | ### シーン2: エラーのハンズフリー通知 156 | 157 | ``` 158 | ユーザー: "ビルドして" 159 | Claude: "ビルドを開始します。" 160 | [音声] 🎤 "ビルドを開始します" 161 | [ビルド実行中...] 162 | [音声] 🎤 "エラーが発生しました。構文エラーが3件見つかりました。" 163 | ``` 164 | 165 | ### シーン3: 長時間タスクの進捗通知 166 | 167 | ``` 168 | ユーザー: "すべてのテストを実行して" 169 | Claude: "全テストを実行します。" 170 | [音声] 🎤 "全てのテストを実行します。これには数分かかる場合があります。" 171 | [テスト実行中...] 172 | [音声] 🎤 "テストの50%が完了しました" 173 | [さらにテスト実行中...] 174 | [音声] 🎤 "全てのテストが完了しました。152件のテストに合格しました。" 175 | ``` 176 | 177 | ## 🎨 話者の特性 178 | 179 | ### 利用可能な話者 180 | 181 | | 話者 | ID | 特徴 | 推奨用途 | 182 | |------|----|----|---------| 183 | | **ずんだもん** (zundamon) | 3 | 明るく元気な声 | 通常の通知、成功メッセージ | 184 | | **四国めたん** (metan) | 2 | 落ち着いた声 | エラー通知、警告 | 185 | | **春日部つむぎ** (tsumugi) | 8 | 優しい声 | 長い説明、ドキュメント | 186 | | **雨晴はう** (ritsu) | 9 | かわいい声 | 完了通知、励まし | 187 | 188 | ### 話者の使い分け 189 | 190 | ```bash 191 | # 通常の作業: ずんだもん（デフォルト） 192 | /voicevox 193 | 194 | # 重要な説明: 春日部つむぎ 195 | /voicevox tsumugi 196 | 197 | # エラー通知: 四国めたん 198 | /voicevox metan 199 | ``` 200 | 201 | ## 🔄 音声読み上げモードの終了 202 | 203 | 音声読み上げモードを終了するには： 204 | 205 | ```bash 206 | # モードを無効化 207 | /voicevox off 208 | 209 | # または 210 | /voicevox disable 211 | ``` 212 | 213 | ## ⚙️ 高度な設定 214 | 215 | ### カスタマイズ可能な設定 216 | 217 | ```bash 218 | # 環境変数で設定をカスタマイズ 219 | export VOICEVOX_URL="http://localhost:50021" # VoiceVox API URL 220 | export VOICEVOX_SPEED="1.0" # 読み上げ速度（0.5-2.0） 221 | export VOICEVOX_PITCH="0" # ピッチ調整（-20～20） 222 | export VOICEVOX_VOLUME="1.0" # 音量（0.0-2.0） 223 | ``` 224 | 225 | ### テキストのフィルタリング 226 | 227 | 以下のパターンを検出して適切に処理： 228 | 229 | 1. **コードブロック**: 「コードが表示されています」 230 | 2. **URL**: 「URLが表示されています」 231 | 3. **長いパス**: ファイル名のみを読む 232 | 4. **エラーメッセージ**: 重要な部分のみ読む 233 | 234 | ## 🐛 トラブルシューティング 235 | 236 | ### VoiceVox Engine が起動していない 237 | 238 | ``` 239 | ✗ VoiceVox Engine not running 240 | Please start VoiceVox Engine first: 241 | https://voicevox.hiroshiba.jp/ 242 | ``` 243 | 244 | **解決方法**: VoiceVox Engine を起動してください。 245 | 246 | ### 音声が再生されない 247 | 248 | ``` 249 | ⚠ No audio player found. Audio saved to: /tmp/xxxxx.wav 250 | ``` 251 | 252 | **解決方法**: 253 | - macOS: 通常は `afplay` が利用可能（標準搭載） 254 | - Linux: `sox` または `alsa-utils` をインストール 255 | - すべて: `ffmpeg` をインストール 256 | 257 | ### 読み上げが遅い 258 | 259 | VoiceVox API の応答速度に依存します。音声合成には通常1-3秒かかります。 260 | 261 | ## 📚 参考リンク 262 | 263 | - [VoiceVox 公式サイト](https://voicevox.hiroshiba.jp/) 264 | - [VoiceVox API ドキュメント](https://voicevox.github.io/voicevox_engine/api/) 265 | - [VoiceVox Engine GitHub](https://github.com/VOICEVOX/voicevox_engine) 266 | 267 | ## 💡 実装のヒント 268 | 269 | このコマンドを実装する際は、以下の点に注意してください： 270 | 271 | 1. **非同期処理**: 音声合成は非同期で実行し、UI をブロックしない 272 | 2. **キャッシュ**: 同じテキストの音声はキャッシュして再利用 273 | 3. **優先度**: エラーメッセージは優先的に読み上げ 274 | 4. **ユーザー体験**: 長い応答は要約してから読み上げ 275 | 276 | --- 277 | 278 | **Note**: このコマンドは実験的な機能です。フィードバックをお待ちしています！ 279 | -------------------------------------------------------------------------------- /docs/paper_law_of_flickering_scenery.aux: -------------------------------------------------------------------------------- 1 | \relax 2 | \providecommand\hyper@newdestlabel[2]{} 3 | \providecommand\HyField@AuxAddToFields[1]{} 4 | \providecommand\HyField@AuxAddToCoFields[2]{} 5 | \citation{fikes1971strips} 6 | \citation{mcdermott1998pddl} 7 | \@writefile{toc}{\contentsline {section}{\numberline {I}Introduction}{1}{section.1}\protected@file@percent } 8 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {I-A}}Motivation}{1}{subsection.1.1}\protected@file@percent } 9 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {I-B}}Contributions}{1}{subsection.1.2}\protected@file@percent } 10 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {I-C}}Paper Organization}{1}{subsection.1.3}\protected@file@percent } 11 | \citation{rao1995bdi} 12 | \citation{yao2023react} 13 | \citation{autogpt2023} 14 | \citation{babyagi2023} 15 | \citation{ha2018world} 16 | \citation{banach1922fixed} 17 | \@writefile{toc}{\contentsline {section}{\numberline {II}Related Work}{2}{section.2}\protected@file@percent } 18 | \newlabel{sec:related}{{II}{2}{Related Work}{section.2}{}} 19 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {II-A}}Autonomous Agent Architectures}{2}{subsection.2.1}\protected@file@percent } 20 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {II-B}}World Models and State Representation}{2}{subsection.2.2}\protected@file@percent } 21 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {II-C}}Convergence and Fixed Points}{2}{subsection.2.3}\protected@file@percent } 22 | \@writefile{toc}{\contentsline {section}{\numberline {III}Theoretical Framework}{2}{section.3}\protected@file@percent } 23 | \newlabel{sec:theory}{{III}{2}{Theoretical Framework}{section.3}{}} 24 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {III-A}}Formal Definitions}{2}{subsection.3.1}\protected@file@percent } 25 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {III-B}}The Unified Agent Formula}{2}{subsection.3.2}\protected@file@percent } 26 | \newlabel{eq:unified}{{2}{2}{The Unified Agent Formula}{equation.3.2}{}} 27 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {III-C}}Mathematical Properties}{2}{subsection.3.3}\protected@file@percent } 28 | \newlabel{thm:composability}{{1}{2}{Composability}{theorem.1}{}} 29 | \newlabel{lem:idempotence}{{2}{2}{Idempotence}{theorem.2}{}} 30 | \newlabel{lem:monotonicity}{{3}{2}{Monotonicity}{theorem.3}{}} 31 | \@writefile{toc}{\contentsline {section}{\numberline {IV}Core Components}{2}{section.4}\protected@file@percent } 32 | \newlabel{sec:components}{{IV}{2}{Core Components}{section.4}{}} 33 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {IV-A}}Intent Resolution ($\mathcal {I}$)}{2}{subsection.4.1}\protected@file@percent } 34 | \citation{yao2023react} 35 | \citation{autogpt2023} 36 | \@writefile{loa}{\contentsline {algorithm}{\numberline {1}{\ignorespaces Intent Resolution $\mathcal {I}$}}{3}{algorithm.1}\protected@file@percent } 37 | \newlabel{alg:intent}{{1}{3}{Intent Resolution ($\II $)}{algorithm.1}{}} 38 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {IV-B}}Command Stack ($\mathcal {C}$)}{3}{subsection.4.2}\protected@file@percent } 39 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {IV-C}}World Transformation ($\Theta $)}{3}{subsection.4.3}\protected@file@percent } 40 | \@writefile{toc}{\contentsline {section}{\numberline {V}Convergence Analysis}{3}{section.5}\protected@file@percent } 41 | \newlabel{sec:convergence}{{V}{3}{Convergence Analysis}{section.5}{}} 42 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {V-A}}Main Convergence Theorem}{3}{subsection.5.1}\protected@file@percent } 43 | \newlabel{thm:convergence}{{4}{3}{Convergence Guarantee}{theorem.4}{}} 44 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {V-B}}Complexity Analysis}{3}{subsection.5.2}\protected@file@percent } 45 | \newlabel{thm:exponential}{{5}{3}{Exponential Convergence}{theorem.5}{}} 46 | \@writefile{toc}{\contentsline {section}{\numberline {VI}Implementation}{3}{section.6}\protected@file@percent } 47 | \newlabel{sec:implementation}{{VI}{3}{Implementation}{section.6}{}} 48 | \@writefile{toc}{\contentsline {section}{\numberline {VII}Proposed Implementation and Expected Performance}{3}{section.7}\protected@file@percent } 49 | \newlabel{sec:experiments}{{VII}{3}{Proposed Implementation and Expected Performance}{section.7}{}} 50 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {VII-A}}Implementation Design}{3}{subsection.7.1}\protected@file@percent } 51 | \bibstyle{IEEEtran} 52 | \bibdata{references} 53 | \bibcite{fikes1971strips}{1} 54 | \bibcite{mcdermott1998pddl}{2} 55 | \bibcite{rao1995bdi}{3} 56 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {VII-B}}Expected Performance Characteristics}{4}{subsection.7.2}\protected@file@percent } 57 | \@writefile{lot}{\contentsline {table}{\numberline {I}{\ignorespaces Projected Goal Achievement Rate (\%)}}{4}{table.1}\protected@file@percent } 58 | \newlabel{tab:gar}{{I}{4}{Projected Goal Achievement Rate (\%)}{table.1}{}} 59 | \@writefile{lot}{\contentsline {table}{\numberline {II}{\ignorespaces Projected Mean Execution Time (seconds)}}{4}{table.2}\protected@file@percent } 60 | \newlabel{tab:time}{{II}{4}{Projected Mean Execution Time (seconds)}{table.2}{}} 61 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {VII-C}}Analysis}{4}{subsection.7.3}\protected@file@percent } 62 | \@writefile{toc}{\contentsline {section}{\numberline {VIII}Discussion}{4}{section.8}\protected@file@percent } 63 | \newlabel{sec:discussion}{{VIII}{4}{Discussion}{section.8}{}} 64 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {VIII-A}}Theoretical Implications}{4}{subsection.8.1}\protected@file@percent } 65 | \@writefile{toc}{\contentsline {subsection}{\numberline {\mbox {VIII-B}}Limitations and Future Work}{4}{subsection.8.2}\protected@file@percent } 66 | \@writefile{toc}{\contentsline {section}{\numberline {IX}Conclusion}{4}{section.9}\protected@file@percent } 67 | \newlabel{sec:conclusion}{{IX}{4}{Conclusion}{section.9}{}} 68 | \bibcite{yao2023react}{4} 69 | \bibcite{autogpt2023}{5} 70 | \bibcite{babyagi2023}{6} 71 | \bibcite{ha2018world}{7} 72 | \bibcite{banach1922fixed}{8} 73 | \@writefile{toc}{\contentsline {section}{References}{5}{section*.2}\protected@file@percent } 74 | \gdef \@abspage@last{5} 75 | -------------------------------------------------------------------------------- /docs/tmux_visualization/scripts/run.sh: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 4 | # Miyabi Multi-Agent Orchestration Visualization 5 | # Run Script - Launch Complete Visualization System 6 | # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 7 | 8 | set -euo pipefail 9 | 10 | # ══════════════════════════════════════════════════════════════════════ 11 | # Configuration 12 | # ══════════════════════════════════════════════════════════════════════ 13 | 14 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" 15 | PROJECT_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)" 16 | STATE_DIR="/tmp/miyabi_viz" 17 | SESSION_NAME="miyabi_orchestrator" 18 | TMUX_CONF="${HOME}/.tmux.conf.miyabi" 19 | 20 | # Source color definitions 21 | # shellcheck source=../config/colors.conf 22 | source "${PROJECT_ROOT}/config/colors.conf" 23 | 24 | # ══════════════════════════════════════════════════════════════════════ 25 | # Functions 26 | # ══════════════════════════════════════════════════════════════════════ 27 | 28 | log_info() { 29 | echo -e "${BRIGHT_CYAN}[INFO]${RESET} $1" 30 | } 31 | 32 | log_success() { 33 | echo -e "${BRIGHT_GREEN}[SUCCESS]${RESET} $1" 34 | } 35 | 36 | log_error() { 37 | echo -e "${BRIGHT_RED}[ERROR]${RESET} $1" 38 | } 39 | 40 | check_setup() { 41 | log_info "Checking setup..." 42 | 43 | if [ ! -d "${STATE_DIR}" ]; then 44 | log_error "State directory not found. Run ./scripts/setup.sh first" 45 | exit 1 46 | fi 47 | 48 | if [ ! -f "${TMUX_CONF}" ]; then 49 | log_error "tmux config not found. Run ./scripts/setup.sh first" 50 | exit 1 51 | fi 52 | 53 | log_success "Setup verified" 54 | } 55 | 56 | kill_existing_session() { 57 | if tmux has-session -t "${SESSION_NAME}" 2>/dev/null; then 58 | log_info "Killing existing session: ${SESSION_NAME}" 59 | tmux kill-session -t "${SESSION_NAME}" 60 | fi 61 | } 62 | 63 | create_tmux_session() { 64 | log_info "Creating tmux session: ${SESSION_NAME}" 65 | 66 | # Create new session with custom config 67 | tmux -f "${TMUX_CONF}" new-session -d -s "${SESSION_NAME}" -n "Orchestrator" 68 | 69 | log_success "tmux session created" 70 | } 71 | 72 | create_layout() { 73 | log_info "Creating pane layout..." 74 | 75 | local session="${SESSION_NAME}:0" 76 | 77 | # Create 8-pane layout 78 | # Top row: 3 agent panes (θ₁, θ₂, θ₃) 79 | tmux split-window -h -t "${session}" 80 | tmux split-window -h -t "${session}" 81 | tmux select-layout -t "${session}" even-horizontal 82 | 83 | # Bottom row: 3 agent panes (θ₄, θ₅, θ₆) 84 | tmux split-window -v -t "${session}.0" 85 | tmux split-window -v -t "${session}.1" 86 | tmux split-window -v -t "${session}.2" 87 | 88 | # Large orchestrator pane in the middle 89 | tmux split-window -v -t "${session}.3" -p 60 90 | 91 | # Event log at the bottom 92 | tmux split-window -v -t "${session}.6" -p 20 93 | 94 | log_success "Layout created: 6 agents + orchestrator + event log" 95 | } 96 | 97 | start_agent_panes() { 98 | log_info "Starting agent panes..." 99 | 100 | local session="${SESSION_NAME}:0" 101 | 102 | # Start agent displays 103 | tmux send-keys -t "${session}.0" "${SCRIPT_DIR}/subagent.sh theta1 1" C-m 104 | tmux send-keys -t "${session}.1" "${SCRIPT_DIR}/subagent.sh theta2 2" C-m 105 | tmux send-keys -t "${session}.2" "${SCRIPT_DIR}/subagent.sh theta3 3" C-m 106 | tmux send-keys -t "${session}.3" "${SCRIPT_DIR}/subagent.sh theta4 4" C-m 107 | tmux send-keys -t "${session}.4" "${SCRIPT_DIR}/subagent.sh theta5 5" C-m 108 | tmux send-keys -t "${session}.5" "${SCRIPT_DIR}/subagent.sh theta6 6" C-m 109 | 110 | log_success "Agent panes started" 111 | } 112 | 113 | start_orchestrator_pane() { 114 | log_info "Starting orchestrator pane..." 115 | 116 | local session="${SESSION_NAME}:0" 117 | 118 | # Start orchestrator display 119 | tmux send-keys -t "${session}.6" "${SCRIPT_DIR}/orchestrator.sh" C-m 120 | 121 | log_success "Orchestrator pane started" 122 | } 123 | 124 | start_event_log_pane() { 125 | log_info "Starting event log pane..." 126 | 127 | local session="${SESSION_NAME}:0" 128 | 129 | # Start event log display 130 | tmux send-keys -t "${session}.7" "${SCRIPT_DIR}/event_log.sh" C-m 131 | 132 | log_success "Event log pane started" 133 | } 134 | 135 | start_simulator() { 136 | log_info "Starting agent simulator..." 137 | 138 | # Start simulator in background 139 | "${SCRIPT_DIR}/agent_simulator.sh" & 140 | local sim_pid=$! 141 | 142 | # Save PID for later cleanup 143 | echo "${sim_pid}" > "${STATE_DIR}/simulator.pid" 144 | 145 | log_success "Simulator started (PID: ${sim_pid})" 146 | } 147 | 148 | attach_session() { 149 | log_info "Attaching to tmux session..." 150 | echo "" 151 | echo -e "${BRIGHT_YELLOW}Press Ctrl-b then 'd' to detach${RESET}" 152 | echo -e "${BRIGHT_YELLOW}Press Ctrl-b then 'q' to quit${RESET}" 153 | echo "" 154 | sleep 2 155 | 156 | # Attach to session 157 | tmux attach-session -t "${SESSION_NAME}" 158 | } 159 | 160 | print_banner() { 161 | echo -e "${BRIGHT_CYAN}${BOLD}" 162 | cat << "EOF" 163 | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 164 | __ __ _ _ _ 165 | | \/ (_)_ _ __ _| |__ (_) 166 | | |\/| | | | | |/ _` | '_ \| | 167 | | | | | | |_| | (_| | |_) | | 168 | |_| |_|_|\__, |\__,_|_.__/|_| 169 | |___/ 170 | 171 | Multi-Agent Orchestration Visualization System 172 | 173 | Agent(Intent, World₀) = lim_{n→∞} (θ₆ ◦ θ₅ ◦ θ₄ ◦ θ₃ ◦ θ₂ ◦ θ₁)ⁿ 174 | ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 175 | EOF 176 | echo -e "${RESET}" 177 | echo "" 178 | } 179 | 180 | # ══════════════════════════════════════════════════════════════════════ 181 | # Main Execution 182 | # ══════════════════════════════════════════════════════════════════════ 183 | 184 | main() { 185 | print_banner 186 | 187 | check_setup 188 | kill_existing_session 189 | create_tmux_session 190 | create_layout 191 | start_agent_panes 192 | start_orchestrator_pane 193 | start_event_log_pane 194 | start_simulator 195 | 196 | echo "" 197 | echo -e "${BRIGHT_GREEN}${BOLD}✓ Visualization system launched!${RESET}" 198 | echo "" 199 | 200 | attach_session 201 | } 202 | 203 | # Run main function 204 | main "$@" 205 | -------------------------------------------------------------------------------- /.claude/commands/lifecycle.puml: -------------------------------------------------------------------------------- 1 | @startuml Slash Command Lifecycle Flow 2 | !theme plain 3 | skinparam backgroundColor #FEFEFE 4 | skinparam activityFontSize 12 5 | 6 | title Slash Command Execution Lifecycle 7 | 8 | |User| 9 | start 10 | :Type Slash Command; 11 | note right 12 | Examples: 13 | /review-pr 123 14 | /test 15 | /deploy production 16 | /refactor 17 | /docs 18 | end note 19 | 20 | |Command Parser| 21 | :Parse Input; 22 | 23 | partition "Parsing Phase" { 24 | :Extract Command Name; 25 | note right 26 | Remove leading "/" 27 | Example: "/review-pr" -> "review-pr" 28 | end note 29 | 30 | :Extract Arguments; 31 | note right 32 | Parse remaining text 33 | Example: "123" -> PR_NUMBER=123 34 | end note 35 | 36 | :Validate Syntax; 37 | 38 | if (Valid Format?) then (no) 39 | :Return Syntax Error; 40 | |User| 41 | :Receive Error Message; 42 | stop 43 | else (yes) 44 | :Continue; 45 | endif 46 | } 47 | 48 | |Command Registry| 49 | :Lookup Command; 50 | 51 | partition "Command Resolution" { 52 | if (Built-in Command?) then (yes) 53 | #LightBlue:Load Built-in Handler; 54 | note right 55 | Built-in Commands: 56 | - /help 57 | - /clear 58 | - /reset 59 | end note 60 | 61 | :Execute Built-in; 62 | |User| 63 | :Receive Result; 64 | stop 65 | 66 | else (custom command) 67 | :Search .claude/commands/; 68 | 69 | if (Command File Exists?) then (no) 70 | :Return Command Not Found; 71 | note right 72 | "Command '/xxx' not found. 73 | Check available commands." 74 | end note 75 | |User| 76 | :Receive Error; 77 | stop 78 | else (yes) 79 | :Load Command Definition; 80 | endif 81 | endif 82 | 83 | :Parse YAML Front Matter; 84 | note right 85 | Extract: 86 | - description 87 | - options 88 | - metadata 89 | end note 90 | 91 | :Load Prompt Template; 92 | } 93 | 94 | |Command Executor| 95 | :Check Command State; 96 | 97 | if (Command Already Running?) then (yes) 98 | :Return Error; 99 | note right 100 | "Command is already running. 101 | Please wait for completion." 102 | end note 103 | |User| 104 | :Wait or Cancel; 105 | stop 106 | else (not running) 107 | :Mark as Running; 108 | :Display ; 109 | note right 110 | 111 | {name} is running... 112 | 113 | end note 114 | endif 115 | 116 | partition "Command Execution" { 117 | :Expand Prompt Template; 118 | note right 119 | Substitute variables: 120 | ${PR_NUMBER} 121 | ${environment} 122 | ${args} 123 | end note 124 | 125 | :Initialize Command Context; 126 | 127 | :Execute Command Steps; 128 | 129 | if (Command Type?) then (/review-pr) 130 | #LightGreen:**PR Review Steps**; 131 | :Fetch PR details (gh pr view); 132 | :Read changed files (gh pr diff); 133 | :Analyze changes; 134 | :Generate review report; 135 | 136 | else if (/test) 137 | #LightYellow:**Test Steps**; 138 | :Run test suite; 139 | :Analyze failures; 140 | :Fix failing tests; 141 | :Re-run tests; 142 | :Generate test report; 143 | 144 | else if (/deploy) 145 | #LightPink:**Deploy Steps**; 146 | :Pre-flight checks; 147 | :Run tests & lint; 148 | :Build project; 149 | :Deploy to environment; 150 | :Verify deployment; 151 | :Generate deploy report; 152 | 153 | else if (/refactor) 154 | #LightCyan:**Refactor Steps**; 155 | :Analyze code smells; 156 | :Identify duplications; 157 | :Apply refactoring patterns; 158 | :Run tests; 159 | :Generate refactor report; 160 | 161 | else if (/docs) 162 | #LightGray:**Documentation Steps**; 163 | :Analyze codebase; 164 | :Generate JSDoc comments; 165 | :Update README; 166 | :Create examples; 167 | :Generate docs report; 168 | 169 | else (custom command) 170 | #Lavender:**Custom Steps**; 171 | :Execute custom logic; 172 | endif 173 | 174 | :Collect Results; 175 | 176 | if (Execution Error?) then (yes) 177 | :Capture Error Details; 178 | :Determine Error Type; 179 | 180 | if (Recoverable?) then (yes) 181 | :Attempt Recovery; 182 | if (Recovery Success?) then (yes) 183 | :Continue; 184 | else (failed) 185 | :Return Partial Results; 186 | endif 187 | else (not recoverable) 188 | :Return Error; 189 | endif 190 | else (success) 191 | :Continue; 192 | endif 193 | } 194 | 195 | partition "Result Formatting" { 196 | :Format Output; 197 | note right 198 | Command-specific format: 199 | - PR Review: Review report 200 | - Test: Test results 201 | - Deploy: Deployment status 202 | - Refactor: Changes made 203 | - Docs: Documentation stats 204 | end note 205 | 206 | :Validate Output Format; 207 | 208 | if (Output Complete?) then (yes) 209 | :Finalize Result; 210 | else (incomplete) 211 | :Add Warning to Output; 212 | note right 213 | "Command completed with warnings: 214 | Some steps may have been skipped" 215 | end note 216 | endif 217 | } 218 | 219 | |Command Executor| 220 | :Mark Command Complete; 221 | :Clear Running State; 222 | 223 | |User| 224 | :Receive Command Result; 225 | 226 | if (Result Satisfactory?) then (yes) 227 | :Continue Work; 228 | stop 229 | else if (Need Modifications?) then (yes) 230 | :Run Command Again; 231 | detach 232 | else (failed) 233 | :Review Error; 234 | :Fix Issues; 235 | :Retry; 236 | detach 237 | endif 238 | 239 | note bottom 240 | **Slash Command Characteristics:** 241 | 242 | 1. **User-Initiated** - Always triggered by user input 243 | 2. **Sequential Execution** - Cannot run same command twice 244 | 3. **Stateful Progress** - Tracks running/completed state 245 | 4. **Template-Based** - Uses markdown files with YAML front matter 246 | 5. **Context-Aware** - Access to full conversation history 247 | 6. **Formatted Output** - Structured, readable results 248 | 7. **Error Recovery** - Attempts to handle failures gracefully 249 | end note 250 | 251 | legend right 252 | |= Command Type |= Primary Use Case | 253 | | /review-pr | GitHub PR code review | 254 | | /test | Run and fix tests | 255 | | /deploy | Deploy to environment | 256 | | /refactor | Code refactoring | 257 | | /docs | Generate documentation | 258 | 259 | |= Command File Structure | 260 | | Filename | .claude/commands/{name}.md | 261 | | Front Matter | YAML with description | 262 | | Body | Prompt template | 263 | endlegend 264 | 265 | @enduml 266 | --------------------------------------------------------------------------------