skill-pipeline

スキルパイプライン

実行役ではなく、指揮役です。このスキルはタスクを分類し、パイプラインのバリアントを選択し、深さを調整して、スキル間の引き継ぎを調整します。独自の成果物は生成せず、他のスキルを起動するためのルーティング判断を出力します。

タスクの分類

すべてのコーディングタスクで、作業に取りかかる前に分類します。範囲を示すシグナルを評価し、タスククラスに割り当てます。

入力シグナル： ファイル数、タスクの説明、既存の計画／引き継ぎファイル、バッチを示す情報、CI 環境。

Task received
  │
  ├─ Trivial (typo, rename, version bump)
  │  → No skills. Just do it.
  │
  ├─ Small (isolated fix, single-file, <10 logic lines)
  │  → verify-gate + simplify-and-harden
  │
  ├─ Medium (feature in known area, 2-5 files)
  │  → intent-framed-agent + session-context + verify-gate + simplify-and-harden
  │
  ├─ Large (complex refactor, new architecture, unfamiliar codebase, high-risk logic)
  │  → Full standard pipeline
  │  → Recommend /plan-interview before starting
  │
  ├─ Long-running (multi-session, high context pressure, prior handoff exists)
  │  → Full standard pipeline with context-surfing as critical skill
  │
  └─ Batch (multiple features from spec, 5+ discrete tasks, issue triage)
     → Orchestrated standard pipeline with bounded work units and independent audits

判断に迷う場合は、Medium から始めます。作業中に逸脱や品質上の問題が見つかったら、スキルを追加します。

詳細なヒューリスティック、例外的なケース、例については、references/classification-rules.md を読んでください。

パイプラインの選択

タスククラスを適切なバリアントに割り当てます。

タスククラス	バリアント	理由
Trivial	なし	オーバーヘッドは不要です
Small	Standard（最小）	Verify と S&H のみ
Medium	Standard（部分）	Intent + セッションコンテキスト + Verify + レビュー
Large	Standard（全体）	計画を含む完全な内部ループ
Long-running	Standard（全体）	コンテキストサーフィングが重要です
Batch	Orchestrated standard	単位ごとのゲートを設けた、範囲が限定された作業単位
CI environment	CI	ヘッドレスレビュー
Periodic	Outer loop	セッションをまたいだ改善

ヒューリスティック： 深さと広さの両方に標準パイプラインを使用します。バッチ作業では、範囲を限定した単位に分割し、永続的な複数セッションの調整が可能で有用な場合にのみ control-session-orchestrator を使用します。CI=true または GITHUB_ACTIONS=true の場合は CI パイプラインを適用します。

起動シーケンス

標準パイプライン（内部ループ）

pre-flight-check (SessionStart hook — surfaces prior learnings + heals)
  → classify
  → (recommend /plan-interview if Large or Long-running)
  → intent-framed-agent (clarify material gaps; emit initial frame)
  → session-context (invoked by intent framing; bounded history retrieval)
  → finalize approach in the same intent frame
  → context-surfing (Large/Long-running or explicit high-context-pressure use; concurrent with intent monitoring)
  → [IMPLEMENTATION]
  → self-healing  ← inner-loop recovery primitive; called whenever a command/test/build/external call fails or a helper is missing.
  →                Diagnoses, patches, verifies, files HEAL- entry. Resumes when verified.
  → verify-gate (compile + test + lint; fix loop if red — fix loop calls self-healing)
  → simplify-and-harden (post-completion, if non-trivial diff)
  → self-improvement (on errors, corrections, S&H learning candidates, recurring heal handoffs)

クラス別のスキル起動：

スキル	Trivial	Small	Medium	Large	Long-running
pre-flight-check	フック	フック	フック	フック	フック
plan-interview	-	-	-	推奨	推奨
intent-framed-agent	-	-	起動	起動	起動
session-context	-	要求時	フレーム設定後	フレーム設定後	フレーム設定後。再開時に再利用
context-surfing	-	-	-	起動	必須
verify-gate	-	起動	起動	起動	起動
self-healing	失敗時	失敗時	失敗時	失敗時	失敗時
simplify-and-harden	-	非自明な場合	非自明な場合	非自明な場合	非自明な場合
self-improvement	エラー時のみ	エラー時のみ	エラー時／完了時	エラー時／完了時	エラー時／完了時

intent-framed-agent が session-context の呼び出しを担当します。これらは独立した2つのトリガーではなく、順序のあるステップです。履歴の参照元が見つからない場合や、有用な一致がない場合でも、実装を妨げてはなりません。作業再開時は以前の調査結果を再利用し、具体的な新たな不足がある場合にのみ情報を取得します。このルーティングはエージェントが従う指針であり、起動フックではありません。

オーケストレーションされたバッチパイプライン

classify (Batch)
  → (recommend /plan-interview if no spec exists)
  → split the scope into bounded work units
  → control-session-orchestrator when persistent multi-session coordination is available
    ├─ each unit follows its appropriate standard-pipeline depth
    ├─ verify-gate after each implementation unit
    ├─ independent simplify, harden, and spec auditors review the combined result
    └─ verify-gate after audit-driven fixes
  → self-improvement

永続的なオーケストレーションを利用できない場合は、同じ範囲限定の作業単位を順番に処理します。並列実行ができないことを理由に、検証、承認、独立レビューのゲートを緩めてはなりません。

CI パイプライン

classify (CI detected)
  → simplify-and-harden-ci (headless scan, PR changed files only)
  → self-improvement-ci (pattern aggregation, promotion recommendations)

外部ループパイプライン

外部ループはセッション内ではなく、セッションをまたいで実行します。定期的なタイミング（毎週、スプリントの区切り）で、または pre-flight-check が昇格可能なパターンを検出したときに起動します。

learning-aggregator (read .learnings/, find patterns, rank promotion candidates)
  → self-improvement (human-approved promotions to project instructions)
  → eval-creator (create permanent test cases from promoted patterns)
  → eval-creator run (regression check on all existing evals)

外部ループを起動するタイミング：

• 毎週：推奨される最短の頻度です
• スプリントの区切り：セッションが立て続けに行われた後
• pre-flight-check が昇格可能な件数 > 3 を報告したとき
• 重大なインシデントの後、または失敗が繰り返されたとき
• 手動：ユーザーが /learning-aggregator を呼び出したとき

外部ループでは、必ず人による承認を必要とします。 learning-aggregator はギャップレポートを作成します。メインエージェントは self-improvement に従い、昇格を適用する前に承認用の差分案を提示します。人によるレビューなしに、指示ファイルへ自動的に書き込むことはありません。

深度の調整

どのスキルを使うかだけでなく、それぞれをどこまで深く適用するかを定めます。

Dimension	Small	Medium	Large	Long-running	Batch
事前チェック	Hook	Hook	Hook	Hook	Hook
計画の反復回数	0	0-1	1-2	深い反復	タスクごと、または包括的に
意図フレーム	-	単一フレーム	完全なフレーム＋モニタリング	完全なフレーム＋引き継ぎ	包括的な不変条件＋単位ごとのフレーム
セッションコンテキスト	要求時	範囲を限定した概要	範囲を限定した概要	範囲を限定した概要。再開時に再利用	関連する概要を共有。単位ごとの不足分のみ
コンテキストサーフィング	-	-	積極的に実施	重要（終了プロトコルをすぐ実行できる状態）	Large／Long-running の単位ごと
検証ゲート	コンパイル＋テスト	コンパイル＋テスト	コンパイル＋テスト＋Lint	コンパイル＋テスト＋Lint	単位ごと＋統合結果
自己修復	失敗時（HEAL を記録）	失敗時（HEAL を記録）	失敗時＋再発チェック	失敗時＋再発チェック	単位ごとに失敗時
S&H の予算	差分の 20％、60 秒	差分の 20％、60 秒	差分の 20％、60 秒	差分の 20％、60 秒	非自明な単位ごと
独立レビュー	-	-	推奨	必須	統合結果に対して必須
自己改善	エラー発生時	エラー発生時	エラー＋S&H のフィード	エラー＋S&H のフィード	エラー＋S&H のフィード

引き継ぎルール

成果物はスキル間で受け渡されます。オーケストレーターは、各スキルが必要な情報を受け取れるようにします。

主な引き継ぎ：

1. 計画ファイル（docs/plans/plan-NNN-<slug>.md）— plan-interview が作成し、intent-framed-agent（コンテキスト）、context-surfing（ウェーブの基点）、および任意の control-session-orchestrator による作業単位の分割で使用します。

2. 意図フレーム — intent-framed-agent が作成し、まず session-context（検索対象のタスクと範囲）、次に context-surfing（ウェーブの基点の強化）が使用します。有用な履歴は同じフレーム内でアプローチを改善しますが、変更を許可するものではありません。コンテキストの劣化により終了する場合は、引き継ぎファイルにコピーされます。

3. 引き継ぎファイル（.context-surfing/handoff-[slug]-[timestamp].md）— context-surfing がコンテキストの劣化による終了時に作成し、次のセッションが再開時に使用します。

4. 検証ゲートのシグナル — verify-gate が作成し（合格／不合格＋診断情報）、simplify-and-harden（ゲート合格後にのみ開始）と修復ループ（失敗時に使用）が受け取ります。失敗時、verify-gate は診断情報を自己修復に渡します。自己修復が原因を診断し、パッチを適用して再検証した後、verify-gate に再確認を依頼します。

5. HEAL エントリーと成果物（.learnings/HEALS.md、.learnings/heals/<HEAL-ID>/）— self-healing が作成し、pre-flight-check（Pattern-Key／Active-Context に基づき、セッション開始時に過去の修復を提示）、learning-aggregator（セッションをまたいだ再発分析）、および self-improvement（Handoff ブロックで Recurrence ≥ 3 の昇格が示された場合）が使用します。

6. 学習候補（learning_loop.candidates）— simplify-and-harden が作成し、self-improvement がパターンの追跡に使用します。

7. 学習エントリー（.learnings/*.md）— self-improvement が作成し、learning-aggregator がセッションをまたいだ分析に、pre-flight-check がセッション開始時に使用します。

8. ギャップレポート — learning-aggregator が作成し、self-improvement が人間の承認を得た昇格に、eval-creator がテストケースの生成に使用します。

9. 評価ケース（.evals/cases/*.md）— eval-creator が作成し、回帰テストの実行で使用され、pre-flight-check によって提示されます。

優先順位： context-surfing と intent-framed-agent が同時に実行される場合は、context-surfing の終了処理が優先されます。コンテキストが劣化していると、範囲チェックの信頼性が低下します。

成果物／シグナル／予算の一覧については、references/handoff-matrix.md を参照してください。

判断ポイント

オーケストレーターは、次のタイミングで介入します。

タスクの到着

タスクを分類し、パイプラインの種類と深さを選択して、ルーティングの判断を出力します。Large／Long-running の場合は /plan-interview を推奨します。Batch の場合は範囲を限定した作業単位を定義し、ホストが対応している場合にのみオーケストレーションを推奨します。

計画の承認

ユーザーが plan-interview の計画を承認したら、別途「続行しますか？」と確認せず、直接実行段階へ進みます。intent-framed-agent を有効にして、意図フレームを忠実に出力します。ただし、2回目の確認は求めず、計画の承認を再利用します。フレームによって重要な判断、前提、またはスコープの変更が生じる場合に限り、質問してください。タスク追跡にはチェックリスト項目を登録します。

計画から実行への移行

plan-interview の有無にかかわらず、明確な実装依頼に対しては intent-framed-agent を有効にします。未解決の重要な判断についてのみ質問し、初期フレームを出力して、意図フレーミングから session-context を1回呼び出せるようにします。適用可能な根拠に基づいてアプローチを確定し、現在の承認と制約を維持します。一律のフレーム確認ゲートを追加したり、インタビューを必須にしたりしないでください。調査結果から重要な矛盾が明らかになった場合は質問し、そうでなければ実装に進みます。

実装途中での失敗

verify-gate が実行される前に、コマンド、テスト、ビルド、リント、または外部呼び出しが失敗した場合（あるいはヘルパーの欠落、環境の不一致、API の変更など、タスク途中で別の問題が発生した場合）は、self-healing に切り替えます。原因を診断し、修正し、検証して、HEAL エントリーを記録します。動作している状態から実行を再開します。修復の多くは再発への対応です。self-healing はまず HEALS.md を Pattern-Key で検索します。

実装完了

verify-gate を有効にして、コンパイル、テスト、リントのチェックを実行します。いずれかが失敗した場合は、self-healing に切り替えて、診断／修正／検証のループを行います（フェーズごとに最大3回）。修復のたびに、verify-gate がチェックを再実行します。すべてのチェックに合格し、差分が非自明な基準を満たしたら（references/classification-rules.md を参照）、simplify-and-harden を有効にします。差分が自明な場合は、verify-gate の合格後にそのまま完了を通知します。

ドリフトの検出

context-surfing がドリフトによる終了を発生させた場合は、実行を停止します。ハンドオフファイルを作成します。タスクが Large 未満に分類されていた場合は、次のセッションでより上位に再分類することを検討します。

セッションの再開

.context-surfing/ に未処理のハンドオフファイルがないか確認します。見つかった場合は、該当するファイルを最後まで読みます。重要な判断が残っていなければ、承認済みの計画と意図を再利用し、必要に応じて再分類して、推奨される再開地点から作業を再開します。具体的な新たな不足がない限り、取得を繰り返さず、既存の session-context ブリーフを再利用します。再開に成功した後にのみ、ハンドオフを処理済みとしてマークします。

オーバーライド

ユーザーは、ルーティングの判断をすべてオーバーライドできます。

• 深度を強制： depth=small / depth=large — 分類をオーバーライド
• バリアントを強制： variant=orchestrated / variant=standard — パイプラインの選択をオーバーライド
• レビューをスキップ： --no-review — simplify-and-harden をスキップ
• 計画を強制： 分類に関係なく、任意のタスクで /plan-interview を実行
• すべてのスキルをスキップ： 非自明なタスクでユーザーが「とにかく実行して」と言った場合は、そのオーバーライドに従う

再分類

タスクの分類は実行途中で変わることがあります。次の点に注意してください。

• エスカレーションの兆候： スコープが当初の見積もりを超えて拡大した、想定より大幅に多くのファイルに影響した、context-surfing がドリフトによる終了を発生させた、intent-framed-agent が大幅なスコープ変更を検出した
• デエスカレーションの兆候： タスクが計画より単純であることが判明した、計画によって必要な変更が最小限であることが明らかになった

再分類が必要な場合：

1. 再分類のきっかけとなった兆候を記録する
2. 有効なスキルを調整する（パイプラインの段階を追加または削除する）
3. Large に引き上げる場合：計画がなければ /plan-interview を推奨する
4. 引き下げる場合：不要な段階を省き、より軽いパイプラインで進める

アンチパターン

• スキルのロジックを再実装してはいけません。 このスキルは分類と振り分けを行います。個々のスキルは、それぞれ独自の手順を担当します。
• plan-interview を自動的に呼び出してはいけません。 これは人間が判断するゲートです。推奨はしても、判断はユーザーに委ねてください。
• 3 つ目の監視レイヤーを作成してはいけません。 実行中は、intent-framed-agent がスコープを監視し、context-surfing が品質を監視します。オーケストレーターは判断が必要な時点で振り分け、その後は介入しません。
• 個々のスキルのガードレールを上書きしてはいけません。 simplify-and-harden に予算上限 20% が設定されている場合、オーケストレーターはこれを遵守します。
• 些細なタスクにスキルの使用を強制してはいけません。 パイプラインは作業を支援するためのものであり、単純な作業を遅らせるためのものではありません。

パイプラインの各バリエーションの詳細

ハイブリッドシナリオやセッションの再開を含む、各バリエーションの手順を完全に追った説明については、references/pipeline-variants.md をお読みください。