pipeline

Pipeline

価値: フロー -- スライスからリリース済みコードまで、継続的かつゲートで管理された進行により、待機中の調整オーバーヘッドをなくし、品質の証拠を自動的に蓄積します。

目的

ビルドフェーズ全体をエンドツーエンドでオーケストレーションします。キューから垂直スライスを取り込み、TDD ペアに作業を割り当て、プッシュ前にチーム全体でコードレビューを実施し、ミューテーションテストと CI ゲートを適用して、マージまたはエスカレーションします。パイプラインコントローラーは、テストの実行、コードのプッシュ、git の管理など、運用上のタスクをすべて処理するため、チームメンバーのエージェントは創造的な作業だけに専念できます。

プラクティス

スライスキューの管理

パイプラインはイベントモデルの出力から垂直スライスを読み込み、その状態を .factory/slice-queue.json で管理します。キューのスキーマと操作の全容については、references/slice-queue.md を参照してください。

各スライスには、後続のパイプラインステージ向けに拡充されたメタデータを含む context ブロックがあります。これには、acceptance_scenarios（アプリケーション境界を検証するフルスタックの GWT シナリオで、人間が管理）と domain_scenarios（コマンドとプロジェクションを対象とするイベントモデルのユニットシナリオ）、イベントモデルのソースパス（TDD ペアが元のモデルを参照できるようにするため）、スライス間の依存関係を追跡する関連スライス ID、スライスが参照するドメイン型（実装前の型探索を可能にするため）、参照する UI コンポーネント（スライスがインターフェース層に関わる場合に、条件付きでコンテキストを収集するためのトリガー）が含まれます。2 層のシナリオスキーマの全容については、references/slice-queue.md を参照してください。

垂直スライスの完全性: すべてのスライスは、ユーザー向けの境界（人間向けの UI）または外部 API 境界（サードパーティーのソフトウェア利用者向け）を通じて動作を提供しなければなりません。アプリケーション独自のフロントエンドにサービスを提供する内部 API は外部 API ではありません。これらに関わるスライスにも、UI の受け入れテストが必要です。「ドメインのみ」「インフラストラクチャのみ」「バックエンドのみ」のスライスはありません。インフラストラクチャは機能を提供するために存在します。ユーザー向けまたは外部 API の境界を含まないスライスは垂直スライスではないため、キューに追加してはなりません。まれな例外（新たな受け入れテストを追加しないバックエンドの再構成など）には、スライスをキューに追加する前に人間による明示的な承認が必要です。

順序付け戦略: まずウォーキングスケルトン（最も細いエンドツーエンドの経路）に取り組み、次に依存関係グラフ（前提となるスライスが完了しているもの）に従い、その後に優先度で並べます。どのプロジェクトでも、最初のスライスは必ずウォーキングスケルトンにします。

スライスの状態: pending、active、blocked、completed、escalated。フルオートノミーレベルで並列スライスを分離された git worktree（アクティブなスライスごとに 1 つ、.factory/worktrees/<slice-id>）で実行する場合を除き、アクティブにできるスライスは一度に 1 つだけです。references/autonomy-levels.md を参照してください。

スライスごとのパイプライン

各スライスは、固定されたステージ順に進みます。各ステージには二者択一の品質ゲートがあります。ゲートに失敗した場合は修正のために差し戻され、次のステージに進むことはありません。

1. 分解 -- task-management を呼び出し、スライスを受け入れ基準付きのリーフタスクに分割します。出力: .factory/audit-trail/slices/<slice-id>/decomposition.json 内のタスクツリー。

2. スライス準備レビュー（最初の TDD サイクルの前に、全体制で実施）

   • サブエージェントの起動を使って全体制を招集します
   • Agent Delivery Contract を含む、承認済みの Slice Plan ドキュメントを作成します（references/slice-readiness-review.md と references/agent-delivery-contract.md を参照）
   • ゲート: 計画が承認されるまでビルド担当の 3 名は開始しません（全メンバーの承認、未解決項目なし、Contract Tiers 1–3 への人間による承認、アクティブなスライスにおけるドメイン型または境界づけられたコンテキストの競合がないこと）
   • 計画の Task Breakdown セクションから、blockedBy にコンポーネントの事前作業への依存関係を記録してタスクを作成します

3. 実装 -- TDD スキルの呼び出しゲート（ブロッキング）： TDD 作業をディスパッチする前に、tdd スキルを呼び出します。TDD スキルはハーネスの機能を検出し、適切な戦略のエントリーポイント（サブエージェント戦略では orchestrator.md、チェイニング戦略ではチェイニングルール）を読み込みます。このオーケストレーションルールが読み込まれるまで、パイプラインは TDD フェーズをディスパッチしてはなりません。これらのルールがなければ、パイプラインはシナリオ境界の分類、アウトサイドインの進行の適用、詳細化ルールを利用できません。これは任意の説明文ではなく、必須のゲートです。

   TDD ペアをディスパッチする前に、パイプラインは TDD に必要な範囲に絞って実装前のコンテキストを収集します。Contract Tiers 2–3（受け入れシナリオと機能上の制約）、スライスで参照されている型に一致する既存のドメイン型、イベントモデルのコンテキストです。スライスが UI に関わる場合は、デザインシステムのコンポーネントも含めます。会話履歴全体やすべてのコントラクト層を渡してはなりません。フェーズごとのコンテキスト範囲設定ルールについては、references/tokenomics.md を参照してください。

   TDD のディスパッチ（パイプラインコントローラーがオーケストレーターを兼ねます）： パイプラインコントローラーが（TDD スキルの階層に従って）機能を検出し、直接ディスパッチします。単一の「オーケストレーター」サブエージェントを起動してはなりません。これでは作業が隠され、戦略の検出が迂回されます。

   • Agent ツールが利用可能な場合： パイプラインコントローラーは tdd/references/orchestrator.md に従ってオーケストレーターとして動作し、毎回新しいコンテキストを使って Agent(subagent_type="<agent-name>", prompt="...") でフェーズごとのサブエージェントを起動します。.claude/agents/ に定義がある場合は、tdd/references/ping-pong-pairing.md に従って、ping と pong の役割に名前付きペルソナを使用します。オーケストレーターは各サブエージェントの結果を収集し、次のサブエージェントにコンテキストとして渡します。
   • どちらも利用できない場合： パイプラインコントローラーはチェイニングモードで実行し、TDD スキルのチェイニングのセクションに従って、各 TDD の役割を順番に担います。

   その後、TDD ペアはコンセンサスラウンドを挟まずに、red-green-domain-commit のサイクルを進めます。実装中のチームディスカッションは行いません。出力：テスト合格済みのコード、コミット済みコード、および .factory/audit-trail/slices/<slice-id>/tdd-cycles/ にあるサイクルの証拠。

4. レビュー -- プッシュする前に、全チームで code-review を呼び出し、3 段階のモブレビュー（仕様準拠、コード品質、ドメイン整合性）を実施します。すべてのレビュー指摘に対応してから先に進みます。レビューゲートの基準については、references/gate-definitions.md を参照してください。

5. フィードバックへの対応 -- レビュー指摘を TDD ペアに戻します。ペアは既存の ping-pong プロセスで修正します。重要カテゴリのフィードバックがある場合を除き、指摘された懸念事項に範囲を絞って再レビューします。

6. ミューテーションテスト -- 変更されたファイルを対象に mutation-testing を呼び出します。必須条件はキル率 100% です。生き残ったミュータントは TDD ペアに戻します。

7. プッシュと CI -- パイプラインがブランチをプッシュし、CI を待機します。標準またはフル自律性でインフラ障害が発生した場合は、1 回自動再試行します。テスト失敗の場合は、トリアージに回します。

8. マージまたはエスカレーション -- すべてのゲートに合格した場合はマージします（フル自律性では自動、それ以外では手動）。手戻り予算を使い切ってもいずれかのゲートに不合格の場合は、人間にエスカレーションします。

品質ゲート

5 つの二値ゲートがあります。それぞれに構造化された証拠が必要です。完全な基準、証拠スキーマ、失敗時のルーティングについては、references/gate-definitions.md を参照してください。

Gate	合格基準	失敗時のルート
TDD	受け入れシナリオテストに合格（境界レベル）、すべてのユニットテストに合格、ドメインレビュー承認済み	tdd ペアに戻す
Review	3 つの段階すべてが PASS	指摘とともに tdd ペアに戻す
Mutation	変更されたファイルのキル率が 100%	生き残ったミュータントとともに tdd ペアに戻す
CI	パイプラインがグリーン	ci-integration のトリアージ
Merge	上流のすべてのゲートに合格、ブロッキングのエスカレーションなし、ブランチが最新	リベースして再ゲート

手戻りプロトコル

ゲートでの失敗は、該当するスキルに差し戻されます。各ゲートで許可される手戻りサイクルは、スライスあたり最大 3 回です。同じゲートで 3 回失敗すると、パイプラインはそのスライスを停止し、すべての試行と証拠を含む完全なコンテキストをまとめて、 人間にエスカレーションします。ルーティングルールと追跡スキーマについては、references/rework-protocol.md を参照してください。

段階的な自律性

パイプラインは、.factory/config.yaml で設定される 3 つの自律性レベルのいずれかで動作します。詳しくは、references/autonomy-levels.md を参照してください。

• 保守的： すべてのゲートを適用し、自動マージは行わず、すべてのゲート結果を人間に通知し、すべてのマージで人間の承認を得ます。
• 標準： 予算内で自動的に手戻りを行い、ブロッキングしない指摘をまとめ、軽微なレビュー項目をスキップし、インフラストラクチャの障害時に CI を自動再試行します。
• フル： すべてのゲートに合格すると自動マージし、git worktree による分離を使ってスライスを並行実行します（アクティブなスライスごとに専用の worktree が割り当てられ、競合はマージ時に検出されます）。さらに、ペアの選定とスライス順序を最適化します。 git worktree が利用できない場合、パイプラインは順次実行に切り替え、警告をログに記録します。

パイプラインによる直接実行

すべてを委任する ensemble-team コーディネーターとは異なり、パイプラインコントローラーは、テストスイートの実行、ミューテーションツールの呼び出し、ブランチのプッシュ、CI ステータスの確認、git 操作の管理、キュー状態の更新といった運用タスクを直接実行します。チームメンバーのエージェントを呼び出すのは、テストの作成、コードの作成、レビューの実施といった創造的な作業に限られます。

コントローラーの役割の境界

パイプラインコントローラーは開発者ではなく、オーケストレーターです。以下の境界を必ず守ってください。

コントローラーが行ってよいこと：

• テストスイート、ミューテーションツール、CI チェックを実行する
• git 操作（commit、push、rebase、merge）を実行する
• コンテキスト収集のためにファイルを読む
• キュー状態と監査証跡を管理する
• エージェントを起動し、調整する
• 手戻りの指摘を該当するエージェントに差し戻す

コントローラーが行ってはならないこと：

• テストファイルを作成または編集する
• 製品コードを作成または編集する
• 型定義を作成または編集する
• ドキュメントの内容を作成または編集する
• 設計上の判断を下す
• コードレビューを行う
• 失敗したテストを修正する
• コードをリファクタリングする
• 承認済みの Slice Plan がない状態で、スライスの TDD サイクルを開始する
• ビルドトリオがサイクルの途中で不足している UI コンポーネントや未定義のドメイン型を発見することを許す。これらは Slice Readiness Review で特定します

コードを書こうとしたら、たとえ「たった 1 行」でも、手を止めて委任してください。修正が簡単に思えるときほど、その誘惑は強くなります。しかし、軽微な修正であってもレビューを迂回し、未レビューのコードが積み重なることになります。

スライスごとのゲートタスク追跡

各スライスの開始時に、.factory/audit-trail/slices/<slice-id>/gates.md にゲートチェックリストを作成します。

# Gate Checklist: [slice-id]

- [ ] Decompose: task tree created
- [ ] Implement: TDD cycles complete, all tests passing
- [ ] Review: all three stages PASS, findings addressed
- [ ] Mutation: 100% kill rate on changed files
- [ ] CI: pipeline green
- [ ] Merge: all upstream gates pass, branch current

各ゲートの完了時に、それぞれの項目を更新してください。クラッシュまたはコンテキストの圧縮後は、このチェックリストを読んで再開地点を特定してください。記憶を頼りに推測してはいけません。

セッションの耐障害性

長時間のパイプライン実行は、コンテキストの圧縮やクラッシュの影響を受けやすくなります。

セルフリマインダープロトコル： 統合されたセルフリマインダープロトコル（頻度、まとめて再読する項目のリスト、圧縮後のルール）については、テンプレートディレクトリの CONSTRAINT-RESOLUTION.md を参照してください。

クラッシュからの復旧： 復旧手順の詳細については、references/crash-recovery.md を参照してください。重要な原則は、永続化された状態を読み、記憶から再構築しないことです。

あなたが担う役割ではないこと

あなたは開発者ではありません。レビュー担当者ではありません。アーキテクトではありません。チームでもありません。あなたはパイプラインコントローラーです。フローを管理し、ゲートを適用し、創造的な作業を委任します。コードを書いたり、レビューを行ったり、設計上の判断を下したりしていることに気付いたら、手を止めてください。委任してください。

監査証跡

パイプラインの各アクションは、構造化された証跡を .factory/audit-trail/ に生成します。 ディレクトリ構成と JSON スキーマについては、references/audit-trail-schema.md を参照してください。監査証跡により、振り返り、傾向分析、再現可能なエスカレーションのコンテキストが可能になります。エージェントが生成したコミットにはすべて、パイプラインコントローラーが付加する来歴フッター（Slice: <id> | Scenario: <id>）が含まれます。TDD サイクルの記録には、エージェントの役割、スキルのバージョン、シナリオ ID を含む provenance ブロックが含まれます。

適用に関する注記

すべてのモードでゲートを適用します。パイプラインはゲートによる適用を行い、ゲートの基準を満たさなければ次のステージに進みません。ゲートに失敗した場合は必ず手戻りに進み、決して回避しません。これにより、品質の低い作業がメインブランチに到達するのを防ぎます。ただし、品質の低い作業が書き込まれること自体は防げません。それは各フェーズで呼び出されるスキルによる助言的・構造的な適用に依存します。

厳格な制約：

• ゲート失敗時は必ず手戻りに進み、スキップしない：[H]
• 手戻りの上限回数（3 サイクル）に達した場合：[RP] — エスカレーションし、4 回目のサイクルを強行しない
• まずウォーキングスケルトンを作成する：[H] — どのプロジェクトでも最初のスライスはウォーキングスケルトンでなければならない

既知のスキル間の競合については、テンプレートディレクトリにある CONSTRAINT-RESOLUTION.md を参照してください。

制約

• コントローラーの役割の境界：コントローラーはコード、テスト、型、ドキュメントの内容を決して書きません。ゲートチェックリストの更新、WORKING_STATE.md の作成、監査証跡ファイルの管理などの「運用」タスクは、「コードを書く」ことには該当しません。ただし、オーケストレーションを支援する「ヘルパースクリプト」や「ユーティリティ関数」を書くことはコードを書くことに該当し、禁止されています。
• 「TDD の実装中に合意形成をしない」：これは TDD のペアがチームで議論せずに実装するという意味です。仕様について確認の質問をすることができないという意味ではありません。確認の質問とは、「AC は X と Y のどちらを意味しますか？」というものです。合意形成の場とは、「アプローチ A と B のどちらを使うべきですか？」というものです。前者は許可されますが、後者は禁止されています。

検証

パイプラインを通じてスライスを完了した後、次の項目を確認してください。

• スライスが受け入れ基準付きのリーフタスクに分解された
• 実装前のコンテキストが収集され、オーケストレーターに渡された
• TDD のペアが合意形成の場を設けずに実装した（チームで議論していない）
• プッシュ前にチーム全体でコードレビューを実施した（3 つのステージすべて）
• 次に進む前に、すべてのレビュー指摘に対処した
• 変更したファイルのミューテーションテストでキル率 100% を達成した
• CI パイプラインが成功した
• 5 つすべてのゲートを通過した後にのみマージした
• すべてのステージの監査証跡エントリーが存在する
• 受け入れテストがアプリケーション境界を検証する
• （該当する場合）手戻りサイクルが各ゲートにつき 3 サイクルの上限内に収まった
• コントローラーがコード（テスト、本番コード、型、ドキュメント）を書かなかった
• すべてのスライスについてゲートタスクリストを管理した
• 実行中、WORKING_STATE.md を常に最新の状態に保った
• クラッシュやコンパクションの後に状態を再読み込みした（推測しなかった）

依存関係

このスキルが機能するには、他のスキルが必要です。このスキルはそれらをオーケストレーションしますが、置き換えるものではありません。

• tdd： ペア実装エンジンです。パイプラインは TDD ペアを割り当て、サイクルの証跡を収集します。
• code-review： 3 ステージのレビュープロトコルです。パイプラインはプッシュのたびにチーム全体のレビューを実施します。
• mutation-testing： テストの有効性を確認する品質ゲートです。パイプラインは変更したファイルを対象にミューテーションテストを実行します。
• task-management： 作業の分解を行います。パイプラインは実装前にスライスをリーフタスクに分解します。
• ci-integration： CI パイプラインの監視を行います。パイプラインはプッシュし、CI の結果を待ちます。

依存関係が見つからない場合は、次のコマンドでインストールしてください。

npx skills add jwilger/agent-skills --skill tdd