self-improve

自己改善オーケストレーター

自己改善システムのループコントローラーです。セットアップ、調査、計画、実行、トーナメント選抜、履歴の記録、可視化、停止条件の評価まで、ライフサイクル全体を管理します。専門の OMC エージェントに作業を委任し、入出力を調整します。

---

自律実行ポリシー

**改善ループの実行中に、ユーザーに尋ねるために停止または一時停止してはいけません。**ゲートチェックに合格してループが始まったら、停止条件が満たされるまで完全に自律して実行します。

• 反復間、または反復内のステップ間で確認を求めないでください。
• 要約して待機しないでください。直ちに次のステップを実行してください。
• エージェントの失敗時：1 回再試行し、その後そのエージェントをスキップして残りのエージェントを続行します。失敗を反復履歴に記録します。
• すべての計画が却下された場合：記録し、自動的に次の反復に進みます。
• すべての実行エージェントが失敗した場合：記録し、自動的に次の反復に進みます。
• ベンチマークでエラーが発生した場合：エラーを記録し、その実行エージェントを失敗として扱い、ほかの実行エージェントで続行します。
• ループを停止するのは、ステップ 11 の停止条件のみです。
• 信頼境界：ループは、対象リポジトリ内でベンチマークコマンドをそのまま実行します。セットアップ時に、ユーザーがリポジトリのパスとベンチマークコマンドを明示的に確認します。ループはパッケージのインストール、システム設定の変更、またはベンチマークコマンドの実行に必要な範囲を超えるネットワークリソースへのアクセスを行いません。
• 保護されたファイル：validate.sh によって、ループがベンチマークコードを変更できないようにし、評価の自己変更を防ぎます。

---

状態の追跡

自己改善の成果物は、scripts/resolve-paths.mjs が返す解決済みルートの配下に保存されます。

• 新しい実行では、デフォルトで .omc/self-improve/topics/default/ を使用します。
• ユーザーがトピックまたはスラッグを指定した場合は、.omc/self-improve/topics/{topic_slug}/ を使用します。
• .omc/self-improve/ にある従来の単一トラックの状態は、明示的なトピック／スラッグが指定されず、そのフラットなレイアウトがすでに存在する場合に限り、互換性のためのフォールバックとして有効です。

以下では、<self-improve-root>/ をこの解決済みルートとして扱います。

<self-improve-root>/
├── config/                    # User configuration
│   ├── settings.json          # agents, benchmark, thresholds, sealed_files
│   ├── goal.md                # Improvement objective + target metric
│   ├── harness.md             # Guardrail rules (H001/H002/H003)
│   └── idea.md                # User experiment ideas
├── state/                     # Runtime state
│   ├── agent-settings.json    # iterations, best_score, status, counters
│   ├── iteration_state.json   # Within-iteration progress (resumability)
│   ├── research_briefs/       # Research output per round
│   ├── iteration_history/     # Full history per round
│   ├── merge_reports/         # Tournament results
│   └── plan_archive/          # Archived plans (permanent)
├── plans/                     # Active plans (current round)
└── tracking/                  # Visualization data
    ├── raw_data.json          # All candidate scores
    ├── baseline.json          # Initial benchmark score
    ├── events.json            # Config changes
    └── progress.png           # Generated chart

OMC モードのライフサイクル：.omc/state/sessions/{sessionId}/self-improve-state.json

---

エージェントの割り当て

すべての拡張内容は、起動時に Task の説明コンテキストを通じて渡されます。既存のエージェントの .md ファイルは変更しません。

ステップ	役割	OMC エージェント	モデル
調査	コードベースの分析と仮説の生成	汎用 Agent	opus
計画	仮説から構造化された計画を作成	oh-my-claudecode:planner	opus
アーキテクチャレビュー	6 項目の計画レビュー	oh-my-claudecode:architect	opus
批評レビュー	ハーネスのルール適用	oh-my-claudecode:critic	opus
実行	計画を実装し、ベンチマークを実行	oh-my-claudecode:executor	opus
Git 操作	アトミックなマージ／タグ付け／PR	oh-my-claudecode:git-master	sonnet
目標のセットアップ	対話形式のヒアリング	（このスキル内で直接実行）	N/A
ベンチマークのセットアップ	ベンチマークの作成と検証	カスタムエージェント	opus

調査プロンプト：このスキルのディレクトリから si-researcher.md を読み込み、その内容をエージェントのプロンプトとして渡します。

ベンチマークビルダー：このスキルのディレクトリから si-benchmark-builder.md を読み込み、その内容をエージェントのプロンプトとして渡します。

目標の明確化：si-goal-clarifier.md を読み込み、ヒアリングを直接実施します（対話形式で、ユーザーが必要です）。

入力

起動時および各イテレーションの開始時に、次のファイルを読み込みます。

ファイル	目的
<self-improve-root>/config/settings.json	ユーザー設定：number_of_agents、benchmark_command、benchmark_format、benchmark_direction、max_iterations、plateau_threshold、plateau_window、target_value、primary_metric、sealed_files、regression_threshold、circuit_breaker_threshold、target_branch、current_repo_url、fork_url、upstream_url、topic_slug
<self-improve-root>/state/agent-settings.json	ランタイム設定：iterations、best_score、plateau_consecutive_count、circuit_breaker_count、status、goal_slug（派生値：目標の目的から生成される小文字のアンダースコア区切りの値。セッションをまたいで一貫性を保つために永続化されます）
<self-improve-root>/state/iteration_state.json	再開可能にするための、イテレーションごとの進捗状況
<self-improve-root>/config/goal.md	改善目標、目標指標、対象範囲
<self-improve-root>/config/harness.md	ガードレールルール（H001、H002、H003）

---

セットアップフェーズ

1. 対象リポジトリのパスが存在するか確認します。未設定の場合は、改善するリポジトリのパスをユーザーに尋ねます。
2. node {skill_dir}/scripts/resolve-paths.mjs --project-root {repo_path} [--topic "..."] [--slug "..."] --ensure-dirs を実行して、<self-improve-root> を解決します。
3. このスキルディレクトリ内の templates/ から、解決された config/ ルートにコピーして、<self-improve-root>/ のディレクトリ構造を作成します。
4. <self-improve-root>/state/agent-settings.json を読み込み、si_setting_goal、si_setting_benchmark、si_setting_harness を確認します。
5. 信頼の確認（必須、省略不可）： a. agent-settings.json で trust_confirmed がすでに true の場合は、手順 5（再開パス）に進みます。 b. 対象リポジトリのパスを表示し、ユーザーに確認を求めます： "Self-improve will run benchmark commands inside {repo_path}. This executes arbitrary code in that repository. Confirm? [yes/no]" c. ユーザーが拒否した場合：セットアップを中止して終了します。続行してはいけません。 d. 同意を記録します：agent-settings.json で trust_confirmed: true を設定します。
6. 解決されたルートがトピック別の場合、今後の再開時も同じトラックを維持できるよう、topic_slug を config/settings.json に保存します。
7. 目標が未設定の場合 → このスキルディレクトリから si-goal-clarifier.md を読み込み、このコンテキスト内で 4 つの観点に基づくソクラテス式インタビュー（目的、指標、目標値、対象範囲）を実施します。結果を <self-improve-root>/config/goal.md に書き込みます。
8. ベンチマークが未設定の場合 → このスキルディレクトリから si-benchmark-builder.md を読み込み、その内容をプロンプトとしてカスタム Agent(model=opus) を起動します。エージェントはリポジトリを調査し、ベンチマークを作成またはラップし、3 回検証して、ベースラインを記録します。 ベンチマークの設定後、ユーザーにベンチマークコマンドを確認します： "Benchmark command: {benchmark_command}. This will be run repeatedly during the loop. Confirm? [yes/no]" ユーザーが拒否した場合：セットアップを中止して終了します。
9. ハーネスが未設定の場合は、デフォルトのハーネスルール（H001/H002/H003）をユーザーに確認するか、カスタマイズします。
10. ゲート：si_setting_goal、si_setting_benchmark、si_setting_harness、trust_confirmed のすべてが true である必要があります。
11. 改善ブランチを作成（存在しない場合）：

    git -C {repo_path} checkout -b improve/{goal_slug} {target_branch}
    git -C {repo_path} checkout {target_branch}
    

    {goal_slug} は目標の目的から生成されます（小文字、アンダースコア区切り）。ブランチがすでに存在する場合は、作成を省略します。goal_slug を agent-settings.json に保存します。
12. モードの排他性：state_list_active を呼び出します。autopilot または ralph がアクティブな場合は、開始を拒否します。
13. 初期状態を書き込みます：state_write(mode='self-improve', active=true, iteration=0, started_at=<now>)

---

Git 戦略

すべての git 操作は、OMC プロジェクトのルートではなく、対象リポジトリ内で行います。

• 改善ブランチ：improve/{goal_slug} — 成功した変更のみを蓄積します。
• 実験ブランチ：experiment/round_{n}_executor_{id} — 実行者ごとの短命なブランチです。
• アーカイブタグ：archive/round_{n}_executor_{id} — 敗れたブランチは削除前にタグ付けします。
• ワークツリーのセットアップ（各実行者の前に SKILL.md が作成します）：

  git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}
  

• 勝者のマージは oh-my-claudecode:git-master 経由で行います：

  Merge experiment/round_{n}_executor_{winner_id} into improve/{goal_slug} with --no-ff
  Message: "Iteration {n}: {hypothesis} (score: {before} → {after})"
  

• マージ後のプッシュ：git -C {repo_path} push origin improve/{goal_slug}（バックアップ用、ブロッキングなし）
• 敗者のアーカイブ：git-master 経由でタグ付けして削除します。

---

改善ループ

ゲート：すべての設定が true である必要があります。ゲートを通過したら、停止せずに継続して実行します。

state_write(mode='self-improve', active=true, status="running") を更新します。

ステップ 0 — 古いワークツリーのクリーンアップ（必須、毎回の反復で実行）

前提条件：このステップは、再開ロジックを含む他のすべてのステップより先に、必ず完了させる必要があります。冪等性があり、複数回実行しても安全です。

1. 対象リポジトリ内のすべてのワークツリーを一覧表示します：git -C {repo_path} worktree list
2. 現在の反復に属さない worktrees/round_* に一致するワークツリーは、git -C {repo_path} worktree remove {path} --force で削除します
3. 古い参照をクリーンアップするため、git -C {repo_path} worktree prune を実行します
4. これによりクラッシュから復旧できます。中断された反復で孤立したワークツリーは、新しい反復の開始前にクリーンアップされます

ステップ 1 — 状態の更新

state_write(mode='self-improve', active=true, iteration=N) を実行して、30 分の TTL をリセットします。

ステップ 2 — 停止リクエストの確認

state_read(mode='self-improve') で状態を読み取ります。

状態がクリアされている（cancel が呼び出された）場合、または status が user_stopped の場合： a. <self-improve-root>/state/agent-settings.json の status を "user_stopped" に設定します b. iteration_state.json を更新し、status を "interrupted" に設定して、current_step を記録します c. 現在のラウンドでアクティブなワークツリーをクリーンアップします（ステップ 0 のロジック） d. ログに "Self-improve stopped by user at iteration {N}, step {current_step}" と記録します e. 正常に終了します。すでにキャンセル済みのため、/cancel は再度呼び出しません

ステップ 3 — ユーザーのアイデアを確認

<self-improve-root>/config/idea.md を読み取ります。空でない場合は、プランナー用に内容のスナップショットを作成します。プランナーが内容を取り込んだ後、クリアします。

ステップ 4 — 調査

si-researcher.md の内容をプロンプトとして、汎用 Agent(model=opus) を 1 つ起動します。

プロンプトに次の情報を渡します：

• 現在の反復番号
• 対象リポジトリのパス
• <self-improve-root>/config/goal.md のパス
• <self-improve-root>/state/iteration_history/ のパス（過去のすべての記録）
• <self-improve-root>/state/research_briefs/ のパス（過去のブリーフ）
• data_contracts.md のセクション 3 の内容（Research Brief スキーマ）

期待される出力：調査ブリーフ JSON → <self-improve-root>/state/research_briefs/round_{n}.json

調査エージェントが失敗した場合は、履歴のみで続行します。

ステップ 5 — 計画

N 個の oh-my-claudecode:planner(model=opus) エージェントを並列で起動します（N = 設定の number_of_agents）。

各プランナーのプロンプトに次の情報を渡します：

• プランナーの識別子（planner_a、planner_b、planner_c...）
• 調査ブリーフのパス
• 反復履歴のパス
• <self-improve-root>/config/harness.md のハーネスルール
• Plan Document のデータコントラクトスキーマ
• 上書き指示：Markdown ではなく JSON を出力すること、インタビューモードをスキップすること、計画ごとに検証可能な仮説を正確に 1 つ生成すること、approach_family タグと history_reference を含めること。
• ユーザーのアイデア（ある場合、planner_a を優先）

期待される出力：Plan Document JSON → <self-improve-root>/plans/round_{n}/plan_planner_{id}.json

ステップ 6 — レビュー

各プランについて、アーキテクトと批評担当を並行して起動します（どちらも Claude エージェントです）。

6a. アーキテクチャレビュー：プランと以下の6項目のチェックリストを添えて、oh-my-claudecode:architect を起動します。

1. テスト可能性 — 仮説はテスト可能ですか？
2. 新規性 — 以前の試行とは異なりますか？
3. スコープ — 適切な規模ですか？
4. 対象ファイル — 実在し、変更不可に設定されていませんか？
5. 実装の明確さ — 実行担当者が推測せずに実装できますか？
6. 期待される結果 — 証拠に照らして現実的ですか？

アーキテクトの判定は参考のみです。

6b. 批評担当によるレビュー：プランと以下のハーネスルールを添えて、oh-my-claudecode:critic を起動します。

• H001：仮説はちょうど1つ（0個または複数の場合は却下）
• H002：approach_family の同じ方法が3回以上連続して繰り返されていない
• H003：ラウンド内の多様性（同じラウンドで同じファミリーのプランを複数含めない）
• data_contracts.md に照らしたスキーマ検証
• 履歴の認識チェック

批評担当は critic_approved: true または false を設定します。false のプランは実行対象から除外されます。

すべてのプランが却下された場合は、記録してステップ 9 に進みます。

ステップ 7 — 実行

承認された各プランについて、oh-my-claudecode:executor（model=opus）を並行して起動します。

起動する前に、ワークツリーを作成します。

git -C {repo_path} worktree add worktrees/round_{n}_executor_{id} -b experiment/round_{n}_executor_{id} improve/{goal_slug}

各実行担当者のプロンプトに以下を含めます。

• 承認されたプランの JSON
• ワークツリーのディレクトリパス
• 設定のベンチマークコマンド
• 設定の変更不可ファイル一覧
• このスキルディレクトリ内の scripts/validate.sh へのパス
• Benchmark Result のデータコントラクトスキーマ
• 上書き指示：プランを忠実に実装し、ベンチマークの前に validate.sh を実行してから、ベンチマークコマンドを実行し、Benchmark Result JSON を出力として生成してください。

期待される出力：Benchmark Result JSON（実行担当者が書き込むか、出力として返します）。

ステップ 8 — トーナメント選定

SKILL.md がこれを直接実行します（委任しません）。

1. 収集：すべての実行結果を収集します。
2. status: "success" の結果のみに絞り込みます。候補が0件の場合はステップ 9（記録と可視化）に進みます。
3. benchmark_score で順位付けします（benchmark_direction に従います）。
4. 順位順の候補ループ — 順位の高い候補から順に処理します。 a. 性能低下チェック：候補のスコアは、benchmark_direction に従って best_score 以上の改善または同等である必要があります（higher_is_better：score >= best_score、lower_is_better：score <= best_score）。 b. oh-my-claudecode:git-master を介してマージします：git merge experiment/round_{n}_executor_{id} --no-ff -m "Iteration {n}: {hypothesis} (score: {before} → {after})" c. マージ後の状態でベンチマークを再実行し、改善を確認します。 d. 再ベンチマークで改善が確認された場合：勝者を確定し、ループを終了します。 e. 再ベンチマークで性能低下が示された場合：git -C {repo_path} reset --hard HEAD~1 でマージを元に戻し、次の候補に進みます。 f. マージが競合した場合：git -C {repo_path} merge --abort を実行し、次の候補に進みます。
5. 勝者が確定し、設定で auto_push が true の場合、改善ブランチをプッシュします：git -C {repo_path} push origin improve/{goal_slug}（ブロッキングなし）。 auto_push が false（デフォルト）の場合は、プッシュを省略します。次のように記録します："Push skipped (auto_push: false). Run manually: git -C {repo_path} push origin improve/{goal_slug}"
6. 勝者以外のすべてのブランチを、git-master を介してアーカイブします：タグ付け＋削除
7. ループで候補が1つも残らなかった場合、このラウンドではマージしません。改善ブランチは以前の状態のままです。
8. Merge Report の JSON を <self-improve-root>/state/merge_reports/round_{n}.json に書き込みます（スキーマ：data_contracts.md セクション 9）。

ステップ 9 — 記録と可視化

1. イテレーション履歴を <self-improve-root>/state/iteration_history/round_{n}.json に書き込みます
2. <self-improve-root>/state/agent-settings.json を更新します：
   • iterations を 1 増やします
   • 勝者がいて、改善幅が plateau_threshold を超える場合（abs(new_score - best_score) >= plateau_threshold）：best_score を更新し、plateau_consecutive_count = 0 にリセットし、circuit_breaker_count = 0 にリセットします
   • 勝者がいて、改善幅がしきい値未満の場合（abs(new_score - best_score) < plateau_threshold）：より良いスコアであれば best_score を更新し、plateau_consecutive_count += 1 を加算し、circuit_breaker_count = 0 にリセットします
   • 勝者がいない場合（すべて却下、すべて失敗、またはすべて後退）：circuit_breaker_count += 1 を加算します（plateau_consecutive_count は加算しません。プラトーは失敗ではなく、勝利が停滞している状態を追跡するためです）
3. <self-improve-root>/tracking/raw_data.json に追記します（候補ごとに 1 エントリー）
4. 可視化のため、python3 {skill_dir}/scripts/plot_progress.py --tracking-dir <self-improve-root>/tracking を実行します
5. プランをアーカイブします：現在のラウンドのプランを state/plan_archive/round_{n}/ にコピーします

ステップ 10 — クリーンアップ

ワークツリーを削除します：

git -C {repo_path} worktree remove worktrees/round_{n}_executor_{id} --force
git -C {repo_path} worktree prune

iteration_state.json のステータスを completed に更新します。

ステップ 11 — 停止条件の確認

すべての条件を評価します。いずれかに該当する場合は終了します：

条件	確認方法
ユーザーによる停止	agent-settings または state がクリアされている状態で、status == "user_stopped"
目標達成	best_score が target_value に到達または超過している（方向を考慮）
プラトー	plateau_consecutive_count >= plateau_window
最大イテレーション数	iterations >= max_iterations
サーキットブレーカー	circuit_breaker_count >= circuit_breaker_threshold

停止条件に該当しない場合：直ちにステップ 1 に戻ります。

---

再開可能性

前提条件：以前の状態に関係なく、再開ロジックを実行する前にステップ 0（古いワークツリーのクリーンアップ）を完了する必要があります。

呼び出し時に、ループに入る前に次の処理を行います：

1. 必ずステップ 0（古いワークツリーのクリーンアップ）を実行します — 新規開始の場合も同様です
2. <self-improve-root>/state/agent-settings.json を読み取ります：
   • status: "user_stopped" の場合：ユーザーに "Previous run was stopped at iteration {N}. Resume? [yes/no]" と尋ねます。no の場合は終了します。yes の場合は続行します。
   • status: "running" の場合：セッションがクラッシュしています — 自動的に再開します（ユーザーへの確認は不要）
   • status: "idle" の場合：新規開始です
3. agent-settings.json の trust_confirmed が false の場合に限り、信頼ゲートを再確認します
4. <self-improve-root>/state/iteration_state.json を読み取ります：
   • status: "in_progress" → current_step から再開し、完了済みのサブステップはスキップします
   • status: "completed" → 次のイテレーションを開始します
   • status: "failed" → 必要に応じて記録ステップを完了し、次のイテレーションを開始します
   • ファイルが存在しない → イテレーション 1 から開始します

---

完了

ループが終了したら：

1. 最終ステータスで agent-settings.json を更新します
2. target_reached かつ設定の auto_pr が true の場合：git-master を起動して、improve/{goal_slug} から upstream への PR を作成します。 auto_pr が false（デフォルト）の場合：PR の作成をスキップします。次のようにログに記録します："PR creation skipped (auto_pr: false). Run manually: gh pr create --head improve/{goal_slug} --base {target_branch}"
3. 最後に plot_progress.py を実行します
4. サマリーレポートを出力します：

   === Self-Improvement Loop Complete ===
   Status: {status}
   Iterations: {iterations}
   Best Score: {best_score} (baseline: {baseline})
   Improvement: {delta} ({delta_pct}%)
   

5. クリーンな状態にするため、/oh-my-claudecode:cancel を実行します

---

エラー処理

状況	対応
エージェントが出力を生成できない	1 回再試行します。それでも出力がない場合は、ログに記録して続行します。
リサーチャーが空の概要を生成する	そのまま進めます — プランナーは履歴のみを基に作業します。
すべてのプランが批評者に却下される	実行をスキップします。ログに記録します。次のイテレーションに進みます。
すべての実行エージェントが失敗する	トーナメントをスキップします。失敗を記録して続行します。
マージコンフリクト	候補を却下し、次の候補を試します。
再ベンチマークでの後退	候補を却下し、マージを取り消して、次の候補を試します。
プッシュの失敗	警告をログに記録します。続行します — プッシュはバックアップです。
ワークツリーがすでに存在する	削除して再作成します。
設定が破損している	報告して停止します。

---

並列セッションに関する注意事項

• 複数リポジトリのワークスペースの起点: 親ディレクトリに .omc-workspace マーカーを配置すると、サブリポジトリ間の複数のセッションで同じ .omc/ が共有されます。解決順序：OMC_STATE_DIR > .omc-workspace > git > cwd。docs/REFERENCE.md を参照してください。
• セッション ID の取得元: CLI コンテキストでは OMC_SESSION_ID 環境変数が優先され、フックコンテキストでは hook payload の data.session_id が優先されます。
• プラン ID（該当する場合）: 自己改善アーティファクトのディレクトリはトピックスラッグごとに作成されます。同じワークスペース内で同じトピックの並列実行を行うと、Wave B2 のセッション ID サフィックスが付与されることがあります。
• 並列実行の判定: 注意事項ありでサポート（トピックスラッグの衝突の可能性あり。Wave B2 を参照）

アプローチファミリーの分類

各プランには、次のタグを必ず 1 つだけ付けてください。

タグ	説明
architecture	モデル／コンポーネントの構造変更
training_config	オプティマイザー、LR、スケジューラー、バッチサイズ
data	データの読み込み、拡張、前処理
infrastructure	混合精度、分散トレーニング、コンパイル済みカーネル
optimization	アルゴリズム／数値の最適化
testing	評価方法の変更
documentation	ドキュメントのみの変更
other	上記に該当しないもの — 根拠で説明してください