fagan

Fagan

入力ではなく、判断にトークンを使いましょう。

実際のストーリー（STE-1、PR #986）がボードを進みます。オープンウェイトモデルが実装し、レビューで一度差し戻された後、マージされました。14分間のタイムラプスです。

お試しください（macOS。Linux では Ollama または LM Studio を使用）。その後、クイックスタートをご覧ください。

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash

フロンティアモデルはトークンごとに料金がかかりますが、判断力に優れています。ローカルモデルは無料で動作し、入力作業には十分です。このパイプラインは、ソフトウェアエンジニアリングをまさにその境界で分担します。フロンティアモデルが作業を分解して計画し、差分をレビューし、リスクのある事項を裁定する一方、ローカルモデルは追加費用なしで実装を書きます。

低コストな側を信頼できるものにするのは、検査です。Michael Fagan による1976年の IBM の研究では、正式な検査によってリリース製品の欠陥の82％が発見されました。コード1,000行あたり38件で、単体テストの8件を上回ります。品質を左右するのは作成者ではなく、ゲートです。そのため、このプロジェクトはゲートに予算を投じます。実装前に TDD を徹底し、独立したレビュー工程を設け、受け入れオラクルによる評価を行い、リスクに応じたオーバーロードが取り消せない操作では人間の判断を仰ぎ、マージゲートでリベース後のブランチに対してテスト一式を再実行してからマージします。

目標は明確で具体的です。月額20ドルの予算で、エンタープライズ級のエンジニアリング規律（作業の分解、TDD、コードレビュー、依存関係に基づくデリバリー）を実現します。

詳しいリファレンスについては、REFERENCE.mdをご覧ください。

始める前に： 以下の信頼性と制限事項をお読みください。これは実際に使われている、自律型コーディングパイプラインであり、失敗モードも文書化されています。現時点では、機能を説明するだけで PR ができあがるような、完全に任せきりのツールではありません。

プラットフォームのサポート

macOS で開発し、日常的に運用しています。コア機能（MCP サーバー、ダッシュボード、Claude バックエンドのディスパッチ／レビュー、テスト一式）は標準的な Python で実装されており、CI ではプッシュごとに Ubuntu 上の Python 3.11～3.14、および macOS 上の 3.14 でテストしています。次の2つはmacOS 専用です。

• launchd/*.plist — macOS では、スケジューラー、MLX スーパーバイザー、使用量ポーラーを launchd ジョブとしてパッケージ化しています。Linux では、独自に init ファイルを作成する代わりに、scripts/generate_systemd_units.sh で systemd 相当の設定を生成するか（以下のスケジューラーを参照）、エントリーポイントをフォアグラウンドのターミナル／tmux セッションで直接実行してください。
• MLX（PIPELINE_LOCAL_PROVIDER=mlx）— Apple Silicon 専用です。Linux では、Ollama または LM Studio を使ってローカルディスパッチを問題なく実行できます（PIPELINE_LOCAL_PROVIDER=ollama ／ lmstudio）。

Windows ではテストしていません。

クイックスタート

ワンライナーでインストール

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh | bash

リポジトリを ~/.fagan にクローンし（場所は FAGAN_INSTALL_DIR、ソース URL は FAGAN_REPO_URL で変更できます）、その中で scripts/install.sh を実行します。以下の手動でのクローンと実行の手順と同じですが、コマンドを入力する必要はありません。後で再実行すると、再クローンする代わりに既存のチェックアウトを更新します（git pull --ff-only）。

リモートのスクリプトを bash にパイプで渡すということは、取得時にその URL が配信する内容を信頼することを意味します。先に内容を確認したい場合は、次のようにします。

curl -fsSL https://raw.githubusercontent.com/motock/fagan/master/scripts/remote-install.sh -o remote-install.sh
less remote-install.sh   # or open it in an editor
bash remote-install.sh

どちらの場合も、表示されたインストールディレクトリ（デフォルトは ~/.fagan）に cd します。以下の手順 1～3 はすでに完了しているため、Claude Code を再起動してください（手順 5）。手動でクローンしたい場合は、代わりに以下の手順を使ってください。

これにより、MCP サーバーが登録され、最初のプランを最初から最後まで実行できるようになります。初回実行時にローカルモデルは必要ありません。何も設定されていない場合、ディスパッチとレビューは claude バックエンドにフォールバックし、Claude Code CLI をシェル経由で実行します。このフォールバックはあくまで開始時の設定であり、意図された設定ではありません。前述のコスト分担は、実装ロールを意図的にローカルモデルに割り当てて初めて実現します。そのため、付属のレジストリには独自の roles ブロックがありません。準備ができたら、以下のプロバイダーの選択と認証を参照してください。

# 1. Clone and install the Python environment
git clone https://github.com/motock/fagan.git
cd fagan
scripts/install.sh          # creates .venv, installs requirements.txt

# 2. Register the MCP server with Claude Code (adjust the path to where you cloned it)
claude mcp add -s user pipeline "$(pwd)/.venv/bin/python3" "$(pwd)/app/pipeline_mcp_server.py"

# 3. Copy the persona subagents and decision policy into place
#    (cp -n skips any file you already have — e.g. a customized code-reviewer.md —
#    instead of silently overwriting it; diff before removing -n if you do want the update)
mkdir -p ~/.claude/agents
cp -n agents/*.md ~/.claude/agents/
cp -n overlord-policy.md ~/.claude/overlord-policy.md

# 4. (Optional) Install the global rules bundle for your agent CLIs
#    scripts/install_global_rules.py --tools=claude,codex,opencode
#    Opt-in: nothing is written unless --tools is passed. It writes the bundle into
#    ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md and ~/.config/opencode/AGENTS.md, copies
#    the rule files into the sibling fagan-rules/ directory, and backs up an existing
#    file as <name>.fagan-bak-<UTC timestamp>. Re-running refreshes only the fenced
#    block between the fagan:begin and fagan:end markers.

# 5. Restart Claude Code (or start a new session) so it picks up the MCP server

scripts/install.sh は .venv を作成し、requirements.txt と requirements-dashboard.txt（ダッシュボードの fastapi／uvicorn 依存関係。毎回インストールされます。--dev でインストールする場合は、ダッシュボードの依存関係をすでに含む requirements-dev.txt を使用します）をインストールします。また、パイプラインがシェル経由で実行するツール（必須：git、gh、claude CLI。任意：ollama、docker）を確認し、利用できない場合も適切に縮退する旨を通知します。安全に再実行できます。MCP サーバーの登録、環境変数の設定、ペルソナサブエージェントのインストールは行いません。これらは上記の手順 2～3 で行います。claude バックエンドしか設定していない場合、ollama／docker がなくても想定どおりであり、エラーではありません。

パイプラインを動作させたいプロジェクトで Claude Code のセッションを開き、次の操作を行います。

1. product-analyst サブエージェントに目標をエピック／ストーリーにまとめてもらうか、スキーマに沿ってプランを自分で作成します。
2. そのプランと、対象プロジェクトを指す repo_root を指定して mcp__pipeline__save_plan（または ingest_plan）を実行します。このパイプラインのリポジトリではありません。
3. mcp__pipeline__list_ready_stories でブロックされていないストーリーを確認し、mcp__pipeline__dispatch_story で 1 つを取得して開始します。
4. ダッシュボードで進行状況を確認します。scripts/dashboard.sh start を実行し、http://localhost:8000 を開きます。
5. 無人で運用する場合はスケジューラーを実行し、手動で advance_pipeline を呼び出さなくても、準備ができたストーリーが進むようにします。 .venv/bin/python3 -m pipeline.scheduler_daemon（フォアグラウンドで実行するか、launchd／systemd／tmux の下で実行します。以下のスケジューラーを参照してください）。

ゲートを信頼できるようになるまで、1 つのプランを実行して確認する間は PIPELINE_AUTONOMY=dry-run（プランとログの記録のみ。ディスパッチもマージも行いません）から始めてください。自律性レベルを参照してください。

claude バックエンドのみを使用しますか？ PIPELINE_LOCAL_* と PIPELINE_BACKEND_*=ollama/lmstudio/mlx の各変数、および Ollama／MLX／LM Studio のセットアップは、ローカルモデルを使ったディスパッチにロールを割り当てる場合にのみ関係します。ただし、プロバイダーの選択自体は引き続き必須のセットアップ手順です（付属のレジストリでは何も割り当てられていません。以下のプロバイダーの選択と認証を参照してください）。また、claude の経路でも、初回ディスパッチの前に 2 つの認証が必要です。gh auth login（パイプラインは GitHub CLI を通じて PR を作成し、マージします）と、Claude Code CLI 自体のログインです。初日に実際に設定する価値のある少数の変数と、チューニング専用の約 100 個の変数については、最小限の設定を参照してください。

プロバイダーの選択と認証

プロバイダーの選択は、必須のセットアップ手順です。 同梱の model_registry.json では、プロバイダーごとに利用可能なモデルを意図的に宣言していますが、 roles によるルーティングは含まれていません。このプロジェクトは特定の プロバイダーに依存しないため、選択は運用者が行います。resolve_role では、以下の順に ロールごとのプロバイダーを選択します。

1. プランのロール設定 — プランのロールごとの provider／model が、 以下のすべての設定より優先されます。
2. レジストリファイル内の roles ブロック — ロールのルーティングに関する唯一の 信頼できる情報源です。詳細は以下を参照してください。
3. PIPELINE_BACKEND_<ROLE> 環境変数 — レジストリにそのロールの設定がない場合にのみ 参照されます（空の状態を補うため、新規クローンでも起動できます）。たとえば、 PIPELINE_BACKEND_DISPATCH=ollama を設定すると、dispatch ロールで Ollama を使用します。
4. 呼び出し元独自のフォールバック — dispatch／review では claude バックエンドです。

レジストリの JSON を手動で編集する代わりに、対話形式で選択するには、ピッカーを実行します。 .venv/bin/python scripts/choose_providers.py。9 つのロールを 1 つずつ確認し、各ロールの 現在のプロバイダー／モデルと、その設定元が表示されます。オプション番号を入力して切り替えられます。 9 つのロールはそれぞれ個別に設定され、変更内容は書き込まれる前にすべてレジストリと照合して 検証されます。いつでも安全に再実行できます。再実行すると現在のルーティングが読み込まれ、 Enter キーを押すとロールの既存の設定が維持されます。

どちらの選択方法でも、同じ 2 つのレジストリファイルを使用できます。

• PIPELINE_MODEL_REGISTRY_PATH を設定すると、任意のレジストリ JSON を パイプラインに指定できます。
• リポジトリのルートにある model_registry.local.json は、個人用レジストリの慣例的な ファイル名です。gitignore に含まれているため、ロールごとのルーティング設定は リポジトリに含まれません。PIPELINE_MODEL_REGISTRY_PATH でこのファイルを指定するか、 環境変数を設定したくない場合は、ローカルで model_registry.json に上書きコピーしてください。

roles ブロックでは、ロールごとにプロバイダーとわかりやすいモデル名を指定します。 わかりやすいモデル名は、同じファイル内のそのプロバイダーの models に存在している必要があり、 具体的なタグはそこから解決されます。誤記があると、暗黙にフォールバックするのではなく、 エラーが発生します。

認証マトリックス。 プロバイダーを選択すると、事前に用意する必要がある認証情報も決まります。 scripts/install_checks.py はこれらを確認し、可能な場合は unauthorized と報告します （対処方法：インストールではなくログイン）。

プロバイダー／ツール	必要な認証情報	認証の設定方法
git／gh	GitHub 認証（パイプラインは gh を通じて PR を作成し、マージします）	gh auth login
claude バックエンド	Claude Code CLI 自体のログイン	claude auth login（確認：claude auth status）
:cloud 付きの ollama タグ	ollama.com アカウントをローカルデーモンにサインイン	ollama signin
litellm バックエンド	ベンダーごとの API キー	docs/specs/LITELLM_PROVIDER.md を参照してください
デバイス上で実行する ollama／lmstudio／mlx タグ	追加の認証情報は不要	—

:cloud の行について：これらの呼び出しはローカルの ollama デーモンを通じて https://ollama.com にプロキシされ、デーモン自身の認証情報が送信されます。パイプラインは 独自の認証情報を送信しません。サインインが必要な ollama タグは :cloud タグのみです。 デバイス上だけで実行するタグは、デーモンが起動していれば追加の設定は必要ありません。

はじめに：操作手順

この操作手順は、設定済みのディスパッチプロバイダーを使用します — PIPELINE_BACKEND_DISPATCH（明示的に設定するか、ローカルレジストリに roles ブロックを追加してください。付属のレジストリにはルーティング設定がありません。上記の プロバイダーの選択と認可 を参照してください）。claude を設定している場合、ディスパッチとレビューは Claude Code CLI を呼び出します。ollama などのローカルプロバイダーを設定している場合は、代わりにそのローカルモデルで実行されます。

1. インストール — コマンドは 1 つだけです：scripts/install.sh（実行内容と実行しない内容については、上記のクイックスタートを参照してください）。
2. MCP サーバーとペルソナを登録 — 上記のクイックスタートの手順 2〜3（claude mcp add ... を実行し、agents/*.md と overlord ポリシーをコピー）を行い、その後 Claude Code を再起動します。
3. ダッシュボードを起動 — scripts/dashboard.sh start を実行し、http://localhost:8000 を開いて、ワークスペース選択画面から対象プロジェクトを選びます。
4. 小さな目標を分解 — product-analyst サブエージェント（またはダッシュボードの分解アクション）に、1 行の目標をエピック／ストーリーに分解するよう依頼します。次に、結果を mcp__pipeline__save_plan で保存し、repo_root フィールドがこのパイプラインリポジトリではなく、対象プロジェクトを指すようにします。
5. 最初の準備完了ストーリーをディスパッチ — mcp__pipeline__list_ready_stories を実行し、続いて最初のストーリーに対して mcp__pipeline__dispatch_story を実行します。ダッシュボードのカンバンボード上でストーリーが進んでいく様子を確認します。
6. マージを見届ける — PIPELINE_AUTONOMY=gated（デフォルト）では、レビューに合格したリスクが low のストーリーは、手動操作なしでマージされます。上記のクイックスタートで推奨しているとおり、まずは PIPELINE_AUTONOMY=dry-run から始めてください。マージ以外をすべて自動化したままにするには、PIPELINE_AUTO_MERGE=0 を設定します。この場合、マージは approve_merge または手動操作によってのみ行われます。
7. スクリプトを使う方法がお好みですか？ — .venv/bin/python scripts/smoke_getting_started.py を実行すると、実際のプランには一切触れないスクラッチ用の PLAN_DIR で、ダッシュボードを使わずに同じフローを最初から最後まで実行できます。このスモークテストはプロバイダーに依存しません。設定済みのディスパッチプロバイダー（PIPELINE_BACKEND_DISPATCH。デフォルトは claude）で実行され、解決されたプロバイダー、モデル、ソースを最初に表示するため、どのバックエンドを検証したかを常に確認できます。終了コード：0 は PASS（ストーリーが tests_passed に到達）、1 は解決されたプロバイダーが claude で claude CLI が見つからない場合、終了コード 2 は設定されたプロバイダーが空または認識されない場合（ローカルプロバイダーを拒否しているのではなく、設定エラーです）、3 は制限時間内にポーリングが完了しなかった場合、4 はストーリーが失敗した場合です。正直にお伝えすると、PASS になるかどうかは、設定されたモデルが実際にストーリーを完了できるかにかかっています。そのため、性能の低いローカルモデルでの失敗は、そのモデルの性能を反映するものであり、パイプラインの不具合ではありません。

ほかに起こり得る問題については、 信頼性と制限事項を参照してください。

コンパニオン MCP サーバー（overlord と acceptance-oracle のみ）

オーケストレーター全体を導入する準備はまだできていませんか？pipeline/companion_server.py は、より小規模な 2 つ目の MCP サーバー（pipeline-companion）です。パイプラインの残りの部分を導入しなくても単独で利用できる、次の 2 つの機能を公開します：escalate_decision（overlord の意思決定パス）と、acceptance-oracle のヘルパーである classify_oracle_outcome／acceptance_digests です。実装を重複させずに実際の pipeline.overlord と pipeline.oracle_gate モジュールをインポートするため、メインサーバーと同期した状態を保てます。メインサーバーと並べて、2 つ目の mcpServers エントリとして追加します：

{
  "mcpServers": {
    "pipeline": {
      "command": ".venv/bin/python3",
      "args": ["app/pipeline_mcp_server.py"]
    },
    "pipeline-companion": {
      "command": ".venv/bin/python3",
      "args": ["-m", "pipeline.companion_server"]
    }
  }
}

このサーバーが公開する、導入可能な仕様は docs/specs/ にあります： OVERLORD_POLICY_SPEC.md（overlord の意思決定パス）、 ACCEPTANCE_ORACLE_PATTERN.md（acceptance-oracle の評価パターン）、および DOCKER_SANDBOX.md（オプトイン方式の Docker サンドボックス動作）です。

スタンドアロンでの実行（ダッシュボード＋スケジューラー、MCP サーバーなし）

ダッシュボードでは、MCP ツールと同じ操作（プランの保存／取り込み、目標の分解、ストーリーのディスパッチ、進行、レビュー、マージの承認）を実行できるため、MCP サーバーを登録せずにパイプラインを実行できます。この同等性があるのは HTTP API であり、UI ではありません。ダッシュボード UI では、チャット（プランの作成を含む）、プラン、ストーリー、ジャーナル、ログの閲覧、ワークスペースの選択、ワークツリーのパッチのレビュー／適用フロー、ロール設定、保存済みプランの取り込みを直接利用できます。ディスパッチ、進行、レビュー、マージ承認には、スクリプトから利用できる UI のない API ルート（/api/plans/{plan_name}/stories/{story_key}/dispatch など）があります。スタンドアロンのフローでは、スケジューラーが想定された実行役です。ダッシュボードでプランを作成して取り込んだら、スケジューラーにストーリーのディスパッチ、進行、レビュー、準備が整ったストーリーのマージを自動で行わせます。サポートされている方法は、次のコマンドを 1 つ実行することです。

scripts/standalone-setup.sh up

up はスクラッチ用データディレクトリ（デフォルトは ~/pipeline-standalone）を用意し、絶対パスを使った共有オペレーター環境ファイルを書き込み、既存のヘルパースクリプトを介してダッシュボードとスケジューラーを起動します。その後、GET /api/health が空の config_mismatch と想定された plan_dir を返すまで、成功を報告しません。主なオプションは、--data-dir DIR（デフォルトは ~/pipeline-standalone）、--target-repo DIR（デフォルトはデータディレクトリ内のスクラッチリポジトリ）、--port PORT（デフォルトは 8001）、--autonomy MODE（デフォルトは dry-run）、および --repo-root と --force です。down は両方のプロセスを停止し、スクラッチデータはそのまま残します。status は解決済みのパスと両方のプロセスの状態を出力します。

2 つの長時間実行プロセスは、同じオペレーター環境ファイルを読み込みます。scripts/dashboard.sh と scripts/scheduler.sh は、まず .pipeline.env（Git で無視されます。.pipeline.env.example を参照）を読み込み、次に .dashboard.env（Git で無視されます。.dashboard.env.example を参照）を読み込みます。そのため、既存のダッシュボードのみのインストールでは、従来の最後に読み込まれた設定が優先されます。.dashboard.env も引き続き使用でき、重複する設定については .pipeline.env を上書きします。

ダッシュボードとスケジューラーは別々のプロセスであるため、両者の PLAN_DIR は一致している必要があります。スケジューラーは <plan_dir>/.scheduler_health.json に設定フィンガープリントを書き込み、/api/health は、ダッシュボードで解決された設定がそのフィンガープリントと異なるフィールドを config_mismatch に列挙して報告します。config_mismatch が空でない場合、UI とスケジューラーが異なるプランストアを使用しています。両方が同じ PLAN_DIR で起動されたことを確認してください（スタンドアロンスクリプトが 1 つの環境ファイルを書き込むのはこのためであり、config_mismatch が空でない場合は必ず失敗します）。

スタンドアロンモードでも、通常の前提条件が適用されます。PR／マージのフローには gh auth login（パイプラインは GitHub CLI を介して PR を作成し、マージします）が必要です。また、設定したバックエンドに応じたプロバイダー認証が必要です。上記のプロバイダーの選択と認証を参照してください。

ガイド付き設定（コマンド 1 つ）

scripts/install.sh は、scripts/configure.py を実行して終了します。このスクリプトは、すでに設定済みの内容を検出し、.pipeline.env、ロールのルーティング、そして（任意で）バックグラウンドサービスを設定します。標準入力と標準出力の両方が TTY の場合にのみプロンプトを表示します。--yes を指定した場合や、パイプでつないだインストール（curl ... | bash）では、安全なデフォルト値が適用され、プロンプトは表示されません。

何も書き込まずに実行計画を表示するには、--dry-run を指定します。すべてのフラグ、キー、デフォルト値については、docs/guided-setup.mdに記載されています。

コンポーネントの概要

構成要素	場所	役割
ペルソナサブエージェント	~/.claude/agents/*.md	エージェントが担うSDLCの役割
意思決定ポリシー	~/.claude/overlord-policy.md	オーバーロードの意思決定方法
パイプラインMCPサーバー	app/pipeline_mcp_server.py（起動用シム）→ pipeline/ パッケージ	すべてのパイプラインツールとオーケストレーション。pipeline/server.py がエントリーモジュールで、pipeline/*.py（ディスパッチ、レビュー、CI、進行、ストアなど）に分割されています
バックエンドの接続部	app/backend.py	役割ごとのドライバーのルーティング（claude / ollama / lmstudio / mlx / local）。単発実行、レビュー、ディスパッチ、リソースゲート
ローカルエージェントループ	scripts/local_agent.py	ローカルディスパッチ用のネイティブツール呼び出し書き込みループ（サブプロセス）
モニタリングダッシュボード	app/dashboard.py、static/	FastAPIによるステータス／ライフサイクルビューアー。スタンドアロンモード（上記の「スタンドアロンでの実行」を参照）では、保存、取り込み、ディスパッチ、レビュー、マージも直接実行します
インストール／依存関係	scripts/install.sh、requirements*.txt	venvと依存関係のセットアップ
テスト	tests/unit/（15,000件以上のテスト）	pytest。venv経由で実行
プラン／マニフェスト／ログ	~/.claude/plans/	プラン、マニフェスト、決定、通知
ワークツリー	~/.claude/worktrees/	ストーリーごとに分離されたブランチ
イシュートラッカー	Plane（外部、任意）	ストーリーの状態を同期します。未設定の場合は完全にスキップされます（信頼できる情報源はマニフェストです）

ダッシュボードのCommsビューでは、ブロックされている項目を確認したり、プランを作成したり、マージを承認したりできます。いずれもカンバンボードのボタンと同じ、ゲート付きAPI経由で処理されます。その他のスクリーンショット（ライブカンバンボードとワークスペースピッカー）はdocs/DEMO.mdにあります。

コアループを超えて

• Pythonだけではありません。 テスト、リンター、ビルドの各ゲートはビルドファイルから対象リポジトリのエコシステムを検出します。検出できないコマンドは、コミット済みの.fagan.jsonで宣言します。詳しくはテスト、リンター、ビルドのコマンドを参照してください。
• 通知。 すべてのパイプラインイベントは、プランごとの通知ログに記録されます。メールを有効にすると（PIPELINE_NOTIFY_EMAIL_ENABLED=1）、スケジューラーは未配信メッセージを次回の試行まで保持する送信キューを通じて、プランの完了、保留中のストーリー、ディスパッチ、テスト、エージェントの失敗を送信します。詳しくは通知を参照してください。
• ダッシュボードからレビュー。 各ストーリーのモーダルには、フォークポイントを基準としたワークツリーの読み取り専用差分（get_story_diffツールも同様）が表示されます。停滞したストーリーには、パッチのレビューと適用を通じて提案されたパッチを適用できます。また、プラン一覧はアクティブなリポジトリに絞り込まれます。
• プラン間の連携。 ストーリーは別のプランのストーリーを待機できます（blocked_by）。また、2つのプランで進行中のストーリーが同じファイルを編集すると、パイプラインが警告します。詳しくはプラン間の連携を参照してください。
• 人間の承認を必要とするマージ。 PIPELINE_AUTO_MERGE=0にすると、ディスパッチとレビューは自動で実行されますが、レビュー済みのPRはすべて、approve_mergeまたは手動でマージするまで保留されます。
• エージェントの実行場所。 オプトインで利用できるDockerサンドボックス、SSH経由のリモートディスパッチまたはレビュー、LiteLLMルーティングを使って、ホスト型ベンダーに接続できます。
• 停滞したストーリーへの対応。 スケジューラーは、エージェントから応答がなくなった進行中のストーリーにフラグを付けます（デフォルトは30分）。また、PIPELINE_AUTO_TRIAGE=1にすると、失敗または保留中のストーリーについてオーバーロードが判断します。モデルのランクを上げる、ストーリーを分割する、壊れた受け入れテスト用フィクスチャにパッチを当てる、またはユーザーの対応まで保留する、のいずれかを行います。pause_planを使うと、他のプランに影響を与えずに1つのプランを停止できます。

---

アーキテクチャ

 ┌────────────────────────────────────────────────────────────────────────┐
 │ Scheduler daemon (or a manual advance_pipeline call)                   │
 │ advance_pipeline(plan) — one idempotent tick                           │
 └────────────────────────────────────────────────────────┬───────────────┘
                          ready stories (deps satisfied)  │
                                                          ▼
 ┌───────────────┐  resolve backend +     ┌───────────────────────────────┐
 │ Plan/Manifest │  persona/model         │ Dispatch                      │
 │ (JSON, Plane) │───────────────────────►│  claude -p  OR  local loop    │
 └───────────────┘                        │  (tech-lead plans for local → │
                                          │   .agent_plan.md)             │
                                          └───────────────┬───────────────┘
                                                          ▼
                                          ┌───────────────────────────────┐
                                          │ Headless story agent, TDD-    │
                                          │ first, in an isolated git     │
                                          │ worktree                      │
                                          └───────────────┬───────────────┘
                                   local fail → escalate  │ tests +
                                      to claude (`auto`)  │ acceptance oracle
                                                          ▼
                                          ┌───────────────────────────────┐
                                          │ code-reviewer: VERDICT,       │
                                          │ opens a PR                    │
                                          └───────────────┬───────────────┘
                                                          ▼
      low    → decide silently            ┌───────────────────────────────┐
      medium → decide, notify the user    │ Overlord adjudicates risk     │──► decisions log
      high   → park, wait for a human     │ (blocked decisions, merge,    │    (audit trail)
                                          │  scope disputes)              │
                                          └───────────────┬───────────────┘
                                                          ▼ approved
                                          ┌───────────────────────────────┐
                                          │ Merge gate: rebase on master, │
                                          │ force-push, poll CI, re-run   │
                                          │ the suite on the rebased      │
                                          │ branch                        │
                                          └───────────────┬───────────────┘
                                                          ▼
                                                       master

ペルソナ（~/.claude/agents/）

各ペルソナは Claude Code のサブエージェントです。YAML フロントマター（name、description、model、任意の memory: user）とシステムプロンプト本文を含む Markdown ファイルです。パイプラインは本文を読み込み、それを役割としてヘッドレスエージェントをディスパッチします。

memory: user を指定すると、Claude を呼び出すたびにユーザーメモリディレクトリがシステムプロンプトに挿入されます。有用性の高いコンテキストですが、トークンを多く消費します。レビュー担当のペルソナ（code-reviewer、security-engineer）では、意図的にこれを省略しています。これらの役割は機械的なチェック（テストを実行し、差分を読み、VERDICT を出力すること）であり、必要な CLAUDE.md のルールはペルソナ本文に記載されています。また、約 132 KB のメモリ挿入を省くことで、レビュー呼び出しごとの入力トークンを約 30～40％削減できます。ディスパッチ担当とオーバーロード担当のペルソナでは、プロジェクトのコンテキストが役立ち、呼び出し頻度も低いため、これを保持しています。

ペルソナ	デフォルトモデル	担当
product-analyst	opus	目標を、受け入れ基準、依存関係、ストーリーごとの persona／model／risk を含むエピック／ストーリーに分解します
solution-architect	opus	一般的なシステム設計、技術選定、API 設計を担当します（モバイル関連は mobile-architect に委任します）
software-engineer	sonnet	モバイル以外の作業で、デフォルトの TDD 実装を担当します
security-engineer	opus	脅威モデリングとセキュリティレビューを担当します（OWASP、Secure by Design）
devops-release-engineer	sonnet	ビルド／CI、ブランチとワークツリーの整理、リリースを担当します
code-reviewer	sonnet	ブランチをレビューし、VERDICT を出力して、PR を作成します
tech-writer	haiku	外部から見える変更に関するドキュメントを作成します
overlord	sonnet	意思決定権者です（下記を参照）

既存のモバイル専門ペルソナ（mobile-architect、mobile-engineer、ux-mobile-principal、qa-test-engineer）に変更はなく、モバイル作業に使用します。

ペルソナの動作やデフォルトモデルを変更するには、該当する .md ファイルを編集します。フロントマターの model: 行は、ストーリーでモデルが指定されていない場合のフォールバックモデルです。

---

オーバーロードと意思決定ポリシー

オーバーロード（~/.claude/agents/overlord.md）は、ストーリーエージェントが行き詰まった場合、2 つのペルソナの意見が分かれた場合、またはゲートで裁定が必要な場合に、ユーザーに代わって判断します。~/.claude/overlord-policy.md（および任意でリポジトリごとに設定する <repo>/.overlord-policy.md のオーバーライド）に従います。

意思決定の段階：

1. 通常／可逆 → 通知せずに判断します（命名、内部構造、承認済みスタック内のライブラリ、リファクタリング）。
2. 非同期通知（risk: medium）→ 判断して作業を進め、ユーザーに通知します（新しい依存関係、スキーマ変更、後方互換性を損なわない API 変更）。
3. 保留して通知（risk: high）→ 無人状態で実行してはいけません。人間によるレビューのために保留し、通知します。不可逆な変更、セキュリティ／認証、金銭、本番環境の設定、または破壊的変更が対象です。ドライランおよびゲート付きモードでは人間の判断を待ちます。full ではオーバーロードが裁定し、事後監査用にその決定を記録します。

オーバーロードは、構造化された裁定（RULING／TIER／RISK／RATIONALE／NOTIFY_USER）を返します。この内容は解析され、監査記録としてプランの決定ログに書き込まれます。

---

参考資料

MCP ツールの完全なリファレンス、プラン／ストーリーの JSON スキーマ、役割ごとのプロバイダー／モデル設定、ガイド付き分解と TDD 分割の詳細、すべての PIPELINE_*／LOCAL_AGENT_* 環境変数、エンドツーエンドのワークフロー、安全制御、使用ゲート、開発／テスト手順については、REFERENCE.md を参照してください。

このリポジトリ自体をパイプラインで開発したエンドツーエンドの実例（インストールコマンド、実際に作成されたプルリクエスト、現時点でまだできないことについての率直な説明）については、docs/DEMO.md を参照してください。

リリースの作成方法については、docs/RELEASING.md を参照してください。

1 コマンドで行うガイド付きセットアップ（フラグ、設定キー、安全なデフォルト、トラブルシューティング）については、docs/guided-setup.md を参照してください。

前提条件

• Python 3.11+ とプロジェクトの仮想環境。CI では、プッシュのたびに Ubuntu で 3.11～3.14、macOS で 3.14 をテストします。
• git が PATH に設定されていること。
• Claude Code CLI（claude）。
• アクティブなフォージの CLI — PIPELINE_FORGE でコードホストを選択します（auto | github | gitlab、デフォルトは auto。origin リモートのホスト名から解決されます）。github には gh、gitlab には glab を使用します。不明な値を指定するとエラーになります。

スケジューラー

advance-scheduler は、定期的な launchd の起動ではなく、長時間稼働するデーモンとして動作します。launchd は KeepAlive によるクラッシュ時の再起動のみを担います。

環境変数

• PIPELINE_SCHEDULER_INTERVAL_S – デフォルトの調整スイープ間隔（デフォルトは 60 秒）。
• PIPELINE_SCHEDULER_HEALTH_PATH – デーモンが各反復でヘルス JSON を書き込む任意のパス。

お使いのマシン向けに launchd ファイルを生成する

コミット済みの launchd/*.plist ファイルと launchd/pipeline-logs.newsyslog.conf は参考用です。メンテナー固有の絶対パス（/Users/<name>/... 形式のホームディレクトリや、特定のモデルキャッシュパス）が含まれているため、別のマシンでは編集せずに使用できません。新規インストール時は、scripts/generate_launchd_plists.sh を使ってご自身で再生成してください（ガイド付きセットアップでは、バックグラウンドサービスを選択した場合にのみ生成されます）。このスクリプトは、次の 3 つのフラグに基づいて launchd/ 内のテンプレート（launchd/com.fagan.pipeline.*.plist.template）に値を設定します。

• --repo-root — 生成されたファイルが参照するパイプラインのチェックアウト先（デフォルト：スクリプトを含むリポジトリ）。
• --out-dir — 生成されたファイルの書き込み先（デフォルト： <repo-root>/launchd）。
• --mlx-model-path — mlx-supervisor plist に埋め込むローカル MLX モデルディレクトリ。フラグの代わりに MLX_MODEL_PATH 環境変数を設定することもできます。両方が指定された場合はフラグが優先されます。どちらも指定されていない場合、スクリプトは安全側に倒してエラーで終了します。

同じスクリプトは、launchd/pipeline-logs.newsyslog.conf.template から launchd/pipeline-logs.newsyslog.conf も生成します。この際、リポジトリのルートのみを置換します。

scripts/generate_launchd_plists.sh \
  --repo-root "$HOME/.claude/mcp-servers/pipeline" \
  --out-dir "$HOME/.claude/mcp-servers/pipeline/launchd" \
  --mlx-model-path "$HOME/.cache/qwen2.5_coder_14b_manual"

これらの launchd ファイルは macOS 専用です。［プラットフォームのサポート］(#platform-support)を参照してください。

Linux 向け systemd ユニットの生成

scripts/generate_systemd_units.sh は、systemd/*.template から、同等の systemd ユーザーユニットと logrotate ファイルを生成します。scripts/generate_launchd_plists.sh が launchd 用に行う処理と同様ですが、Apple Silicon 専用の MLX は対象外です。

scripts/generate_systemd_units.sh \
  --repo-root "$HOME/fagan" \
  --out-dir "$HOME/fagan/systemd"

ユーザーごとの systemd ユニットとしてインストールします（root 権限は不要です）。

mkdir -p ~/.config/systemd/user
cp systemd/com.fagan.pipeline.advance-scheduler.service ~/.config/systemd/user/
cp systemd/com.fagan.pipeline.usage-poller.service ~/.config/systemd/user/
cp systemd/com.fagan.pipeline.usage-poller.timer ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now com.fagan.pipeline.advance-scheduler.service
systemctl --user enable --now com.fagan.pipeline.usage-poller.timer
  # Optional: let these run even when you are not logged in
loginctl enable-linger "$USER"

ログローテーション（root 権限が必要、一度限り）：

sudo cp systemd/pipeline-logs.logrotate.conf /etc/logrotate.d/com.fagan.pipeline

信頼性と制限事項

このパイプラインは、実際の自律型コーディングループを実行します。特定の、文書化された形で失敗するため、大切なものに適用する前にお読みください。

• ローカル（Claude 以外の）モデルへのディスパッチが弱点です。 小規模で機械的に範囲を限定したストーリー（懸念事項が1つ、本番ファイルが2つ以下）ではうまく機能しますが、それより大きな作業では著しく性能が低下します。大きなファイルの編集、複数関数にまたがるストーリー、既存の長い関数内へのアンカー付き挿入では、ステップ上限によるタイムアウトや停止、古い行番号に基づく編集によるファイル破損が繰り返し発生します。この調査結果の根拠は、このリポジトリにある docs/plans/*.md と retros/*.md の実際のインシデント記録であり、宣伝文句ではありません。ローカルディスパッチに重要な作業を任せる前に、いくつかお読みください。PIPELINE_BACKEND_DISPATCH=auto は、苦戦しているローカルでの試行をループさせず、Claude にエスカレーションするために用意されています。
• 「月額20ドル」という表現は、ゲートの設計目標であり、まだベンチマークで実証された結果ではありません。 記録されている唯一のモデル比較の全体実行（tests/benchmark/FINDINGS.md）は、実行中にレート制限とクレジット切れの影響を受けたため、バックエンド間の成功率やコストを同条件で比較した結果はまだ公開されていません。そこにある最も明確な数値は限定的なものです。デバイス上の gpt-oss:20b で T1 タスクを2件実行し、マージ後のコードに対する独立オラクルの検証も通過して2件とも成功しましたが、各試行は1回のみです。これは傾向を示すものであり、品質比較ではありません。そこから数値を引用する前に、そのファイルを読んで、何が分かっていて何が分かっていないのかを正確に確認してください。
• テストスイートがすべて成功しても、変更が正確または完全である証明にはなりません。 実行担当（ローカルまたは Claude）は、自身のテストを成功させる最小限の差分に収束します。また、実装と同じバグを組み込んだ、内部的には整合する誤ったテストを書くこともあります。.claude/rules/code-review.md の "Merge-gate and AI-review lessons" セクションをご覧ください。そこにある教訓はすべて、仮定上の事例ではなく、実際にマージされたリグレッションから得られたものです。
• done とマークされたストーリーでも、タイトルが示す範囲をすべて実装した証明にはなりません。 「すべて移行する」や「X をすべて削除する」といったストーリーは、作業の一部しか完了していなくてもレビューに合格し、マージされることがあります。レビューではタイトルの主張ではなく、ストーリー自身のテストが評価されるためです。.claude/rules/agent-dispatch-story-sizing.md をご覧ください。
• オーバーロードの park-and-ping ティアは、提案ではなく実際の安全性の最低基準です。 リスクの高い判断（取り消せない操作、認証・セキュリティ、金銭、本番環境の設定、互換性を破る変更）は、dry-run と gated では人間の判断を待ちます。full ではオーバーロードがリスクの高いマージ保留の裁定を行い、事後監査用に判断を記録します。新しいデプロイは必ず PIPELINE_AUTONOMY=dry-run から始め、gated や full を信頼する前に判断ログを確認してください。
• これは保守担当者が1人の研究プロジェクトであり、SLA のある保守対象製品ではありません。 テストスイートと CI は実際のゲートとして機能しますが、荒削りな部分があること、また新たな失敗モードが見つかるたびに一覧が増えていくことを想定してください。

新たな失敗モードに遭遇したら、黙って回避策を講じるのではなく、文書化する価値があります（既存の形式については retros/ をご覧ください）。このプロジェクトの設計の価値は、失敗モードに名前を付け、ストーリーの範囲設定やレビューにフィードバックすることにあります。

ライセンス

Apache License, Version 2.0 の下でライセンスされています。詳しくは LICENSE と NOTICE をご覧ください。