shepherd

Name: shepherd
Author: lvlup-sw

github.com/lvlup-sw開発22216 回インストール2 日前に更新

リポジトリ

shepherd について

shepherdは、公開済みPRのCIチェックとレビュー指摘を解消するまで反復処理するスキルです。Exarchos MCPアクションでPRスタックを評価・修正し、synthesizeフェーズ内で進捗を追跡します。

主な機能

01CIとレビューの一括評価
02PRの修正と再提出
03行内コメントとレビュー指摘への対応
04反復状況と品質シグナルの追跡

活用シーン

01公開済みPRのCI状況の監視
02変更要求や行内フィードバックの解消
03PRスタックの承認準備

MCP 対応

VCS操作にExarchos MCPアクションを使い、PRの評価、コメント、マージなどを行います。GitHub、GitLab、Azure DevOpsへの振り分けに対応します。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/lvlup-sw/exarchos --skill shepherd

インストール後、Claude Code で/shepherdを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/

assess-checklist.md

escalation-criteria.md

fix-strategies.md

gate-event-emission.md

shepherd-event-schemas.md

詳細

Shepherd スキル

VCS プロバイダー

このスキルでは、Exarchos MCP アクション（check_ci、list_prs、merge_pr、get_pr_comments、add_pr_comment など）を通じて VCS 操作を行います。これらのアクションは、適切な VCS プロバイダー（GitHub、GitLab、Azure DevOps）を自動で検出し、処理を振り分けます。 gh／glab／az コマンドは不要です。MCP サーバーがプロバイダーへの振り分けを処理します。

ここで呼び出す merge_pr は、リモート PR のマージプリミティブ（synthesize フェーズ）です。upstream の merge-pending サブステートで実行される統合マージとは異なります。後者では、serialize_merge（@skills/merge-orchestrator/SKILL.md）が統合マージの経路です。これはシングルライターリースを保持し、ローカルの git merge を構成します（生の merge_orchestrate は、その構成済み実行器／非統合経路です）。このスキルが serialize_merge または merge_orchestrate を呼び出すことはありません。

公開済み PR を CI チェックとコードレビューに通し、マージ可能な状態に導く反復ループです。すべての PR の健全性チェックに assess_stack 複合アクションを使用し、失敗を修正してフィードバックに対応し、スタックがグリーンになるまで続けます。

注： Shepherd は独立した HSM フェーズではありません。synthesize フェーズ内のループとして動作します。Shepherd の反復サイクル全体を通して、ワークフローのフェーズは synthesize のままです。イベント（shepherd.iteration、ci.status）と shepherd_status ビューが、フェーズ遷移を必要とせずにループの進行状況を追跡します。

ワークフロー内での位置：

synthesize → shepherd (assess → fix → resubmit → loop) → cleanup
              ^^^^^^^^^ runs within synthesize phase

デフォルトの目標

デフォルトでは、Shepherd は PR に寄せられたすべてのフィードバックへの対応を目指します。呼び出し時に「すべてのフィードバックに対応」と付け加える必要はありません。オプトインではなく、デフォルトだからです。各反復では、次の3つのフィードバック経路すべてで未対応項目をゼロにすることを目指します。

CI／チェック — 失敗中または保留中のチェックをすべて修正または解決します。
正式なレビュー — CHANGES_REQUESTED のレビューすべてに対応します。
インラインコメント — 重大度に関係なく、すべてのインラインレビューコメント（人間、CodeRabbit、Sentry、ボット）に修正および／または返信を行います。軽微なコメントや細かな指摘もフィードバックです。対応するか、意図的に対応しない理由を説明する返信をしてください。人間が PR を確認したときに、すべてのスレッドに返信がある状態を目指します。

assess_stack は助言を行います。computeRecommendation が fix-and-resubmit を強制するのは重大または主要な項目だけなので、軽微な comment-reply 項目が残っていても request-approval を返す場合があります。これをスキップしてよいという意味に受け取らないでください。承認を依頼するのは、すべての comment-reply アクション項目に対応（修正または返信）してからにしてください。「すべてのフィードバックに対応する」ことは、常に適用されるデフォルトです。

パイプラインの整理

パイプラインに古いワークフロー（7日間を超えて非アクティブ）が蓄積した場合、新しい shepherd サイクルを開始する前に @skills/prune/SKILL.md を実行して、放棄されたワークフローを一括キャンセルします。exarchos:exarchos_view({ action: "pipeline", scope: "all" }) で古いワークフローを特定します。デフォルトビューは呼び出し元のリポジトリにスコープされ、リポジトリの識別情報が記録される前に開始されたワークフロー、つまりこのクリーンアップの対象となる古い行を非表示にします。保護措置により、オープン中の PR があるワークフローや最近コミットがあるワークフローはスキップされるため、アクティブな Shepherd の対象が影響を受けることはありません。パイプラインを整理すると、Shepherd の反復レポートが読みやすくなり、古い件数ビューのノイズも減ります。

トリガー

次の場合に有効化します。

ユーザーが shepherd を実行する、または「shepherd」「PR の面倒を見て」「CI を確認して」と言う
PR が公開され、CI／レビューの関門を通過するまで監視する必要がある
synthesize が完了し、PR がキューに登録された後

前提条件

PR が公開済みのアクティブなワークフロー（synthesis.prUrl または artifacts.pr に PR URL がある）
PR が作成され、プッシュ済み（create_pr がすでに実行されている）
VCS 操作用の Exarchos MCP ツールが利用可能

プロセス

ランブック： シェパードの各イテレーションでは、シェパード・イテレーションのランブックに従います。 exarchos_orchestrate({ action: "runbook", id: "shepherd-iteration" }) ランブックを利用できない場合は、describe を使用してアクションスキーマを取得します：exarchos_orchestrate({ action: "describe", actions: ["assess_stack"] })

すべての PR が健全になるか、エスカレーション基準を満たすまで、シェパードのループを繰り返します。デフォルトは 5 イテレーションです。

ステップ 0 — 品質シグナルの把握

各イテレーションの開始時に、品質に関するヒントを取得して評価に反映します。

exarchos:exarchos_view({ action: "code_quality", workflowId: "<featureId>" })

regressions が空でない場合は、ステータスレポートに回帰の情報を含めます
いずれかのヒントの confidenceLevel: 'actionable' の場合は、イテレーションの概要に suggestedAction を示します
いずれかのスキルで gatePassRate < 0.80 の場合は、品質の低下傾向を指摘します

このステップにより、個々の PR をポーリングする前に、蓄積された品質情報に基づいてエージェントが対応できます。

ステップ 1 — 評価

assess_stack 複合アクションを実行して、すべての PR の項目をまとめて確認します。

exarchos:exarchos_orchestrate({
  action: "assess_stack",
  featureId: "<id>",
  prNumbers: [123, 124, 125]
})

複合アクションでは、内部で以下を処理します。

すべての PR の CI ステータス確認
正式なレビュー状況（APPROVED / CHANGES_REQUESTED）
インラインレビューコメントのポーリングとスレッドの解決（Sentry、CodeRabbit、人間）
スタックの健全性確認
イベントの発行：CI チェックごとの ci.check_observed イベント（CodeQualityView に反映）と、PR ごとの ci.status イベント（ShepherdStatusView に反映）。イベント形式については references/gate-event-emission.md を参照してください。

返された actionItems と recommendation を確認します。

推奨事項	アクション
`request-approval`	すべての `comment-reply` 項目に対応済みの場合に限り、ステップ 4 に進みます。未対応のインラインコメントがある場合は `fix-and-resubmit` として扱い、先に対応します（デフォルトの目標を参照）。
`fix-and-resubmit`	ステップ 2 に進みます
`wait`	ユーザーに通知し、一時停止して、時間を置いてから再評価します
`escalate`	`references/escalation-criteria.md` を参照してください

ステップ 2 — 修正

すべての変更を不変条件カタログ（評価時の制約）に照らしてください。 コード修正を作成する前に、.exarchos/invariants.md（cost-of-load: always-load とマークされた項目）を読み込み、修正で維持する必要がある不変条件を示す Constraints セクションを提示してから、提案する変更をそれぞれ不変条件に照らして検証してください。これは shepherd の評価時における、ideate の Phase 0 に相当するもので、選択ルールとカタログ登録のゲーティングに関する唯一の共有情報源である @skills/ideate/references/constraint-anchoring.md を使用します。カタログ登録がゲート条件です： .exarchos.yml: invariants.catalogs にカタログが登録されていない場合、Constraints セクションを提示せず、そのまま修正してください。これにより、「変更を評価するときは .exarchos/invariants.md を適用する」ことがデフォルトになり、実行のたびに要求する必要はありません。

個々のアクションアイテムを処理する前に、ループ内でインライン修正するものと委任するものを判断できるよう、分類してください。評価の actionItems に対して classify_review_items を呼び出します（コメント返信のサブセットはファイルごとに分類され、CI 修正とレビュー対応のアイテムは変更せずにそのまま渡されます）。

exarchos:exarchos_orchestrate({
  action: "classify_review_items",
  featureId: "<id>",
  actionItems: <actionItems from assess_stack>
})

結果では、グループごとに recommendation を持つ groups: ClassificationGroup[] が返されます。direct（インラインで対応）、delegate-fixer（バッチ処理や重大度 HIGH の作業をフィクサーサブエージェントに委任）、delegate-scaffolder（ドキュメントの軽微な修正を安価なサブエージェントに委任）のいずれかです。グループを順番に処理し、それぞれの戦略を適用してから、問題の種類ごとの詳しい手順について references/fix-strategies.md を参照してください。

修正イベントのプロトコル（FLYWHEEL）：

修正を適用する前に、remediation.attempted を出力します。

exarchos:exarchos_event({
  action: "append",
  stream: "<featureId>",
  event: {
    type: "remediation.attempted",
    data: { taskId: "<taskId>", skill: "shepherd", gateName: "<failing-gate>", attemptNumber: <N>, strategy: "direct-fix" }
  }
})

修正を適用します（CI の失敗、レビューコメントへの返信、スタックの再配置）。

次の評価で修正によりゲートが解消されたことを確認した後、remediation.succeeded を出力します。

exarchos:exarchos_event({
  action: "append",
  stream: "<featureId>",
  event: {
    type: "remediation.succeeded",
    data: { taskId: "<taskId>", skill: "shepherd", gateName: "<gate>", totalAttempts: <N>, finalStrategy: "direct-fix" }
  }
})

これらのイベントは、CodeQualityView の selfCorrectionRate および avgRemediationAttempts メトリクスに反映されます。

アクションアイテムの種類：

種類	戦略
`ci-fix`	ログを読み、ローカルで再現し、修正して、スタックブランチにコミットします
`comment-reply`	`actionItem.reviewer`、`normalizedSeverity`、`file`、`line`、および `raw`（元のコメント全文）を使用して返信を作成します。`servers/exarchos-mcp/src/review/providers/` 配下のプロバイダーアダプターが入力フィールドを設定するため、手動で重大度の階層を解析する必要はありません。投稿： PR レベルの概要コメントとスレッドごとのインライン返信は、どちらもプロバイダーに依存しない `add_pr_comment` オーケストレーションアクションを使用します。返信を特定のインラインスレッドに送るには `threadId` を渡します（`VcsProvider.addReply` 経由）。インラインスレッドへの返信は GitHub でサポートされています。GitLab と Azure DevOps は、「未対応」を明示する機能シグナルを返します。
`review-address`	CHANGES_REQUESTED に対するコードを修正し、各スレッドに返信します
`restack`	`git rebase origin/<base>` を実行し、`exarchos_orchestrate({ action: "list_prs" })` で確認します
`escalate`	`references/escalation-criteria.md` を参照します

すべてのインラインレビューコメントに返信する必要があります。PR を確認する人が、すべてのスレッドに返信があることを確認できるようにするのが目標です。

ステップ 3 — 再提出

修正を適用した後、スタックを再提出します。

git push --force-with-lease

必要に応じて自動マージを再度有効にします。

exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })

次の反復のためにステップ 1 に戻ります。反復回数を上限（デフォルトは 5）と照らして記録します。request-approval に到達する前に上限に達した場合は、references/escalation-criteria.md に従ってエスカレーションします。

ステップ 4 — 承認をリクエストする

assess_stack が recommendation: 'request-approval' を返した場合（すべてのチェックがグリーンで、すべてのコメントに対応済み）：

ガード： 承認をリクエストする前に、残っている comment-reply アクション項目がないことを確認してください。デフォルトの目標に従い、軽微なものや些細なものも含め、すべてのインラインコメントに先に対応する必要があります。残っている項目がある場合は、承認をリクエストせずにステップ 2 に戻ってください。

不変条件への準拠に関するポインター（カタログ登録を条件とし、マージ前に実施）： カタログが .exarchos.yml: invariants.catalogs に登録されている場合は、承認／マージをリクエストする前に、PR の差分に対してレビュー段階の check_invariant_conformance アクションを実行してください。これにより、マージゲートで読み取るアーキテクチャ上の不変条件が、これから取り込まれる差分と一致します。これはポインター／利用手段であり、厳格なゲートではありません。このアクションは非ブロッキング（gate: { blocking: false }）であり、準拠に関する所見を提示してレビューの判定に反映できるようにしますが、マージを停止するものではありません。これは設計時の Constraints セクションではありません（shepherd は設計時ではなく、synthesize／merge で実行されます）。ステップ 2 の Constraints による基準設定は修正の構成を対象とし、このポインターはレビュー／マージゲートにおける差分と不変条件の照合を対象とします。カタログが登録されていない場合は、このステップをスキップしてください。
exarchos:exarchos_orchestrate({
  action: "check_invariant_conformance",
  featureId: "<id>",
  phase: "review",
  diff: "<PR diff>"
})

GitHub MCP を使ってレビューをリクエストします：
```
mcp__plugin_github_github__update_pull_request({
  owner: "<owner>", repo: "<repo>", pullNumber: <number>,
  reviewers: ["<approver>"]
})
```
フォールバック（MCP トークンに書き込みスコープがない場合）：gh pr edit <number> --add-reviewer <approver>

ユーザーに報告します：

## Ready for Approval

All CI checks pass. All review comments addressed.
Approval requested from: <approvers>

PRs:
- #123: <url>
- #124: <url>

Run `cleanup` after merge completes.

状態管理

ワークフローの状態を通じて shepherd の進捗を追跡します：

初期化：

exarchos:exarchos_workflow({
  action: "update",
  featureId: "<id>",
  updates: {
    "shepherd": {
      "startedAt": "<ISO8601>",
      "currentIteration": 0,
      "maxIterations": 5,
      "approvalRequested": false
    }
  }
})

各イテレーション後： currentIteration を更新し、評価の概要と実行したアクションを記録します。承認時には、タイムスタンプと承認者のリストを指定して approvalRequested: true に設定します。

フェーズの遷移とガード

遷移テーブルの全容については、@skills/checkpoint/references/phase-transitions.md を参照してください。

shepherd スキルは synthesize フェーズ内で動作し、フェーズ遷移を直接進めることはありません。

スキーマの確認

パラメータのスキーマには exarchos_workflow({ action: "describe", actions: ["update", "init"] }) を、フェーズ遷移、ガード、プレイブックのガイダンスには exarchos_workflow({ action: "describe", playbook: "feature" }) を使用します。イベントを発行する前に、イベントデータのスキーマを確認するには exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status", "remediation.attempted"] }) を使用します。

イベントの発行

shepherd イベントを発行する前に、完全な Zod スキーマ、型の制約、ペイロードの例について references/shepherd-event-schemas.md を参照してください。実行時に必須フィールドを確認するには、exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status"] }) を使用します。

イベント	タイミング	目的
`shepherd.started`	スキルの開始時（`assess_stack` が発行）	監査証跡
`shepherd.iteration`	各評価サイクルの後	進捗の追跡
`ci.check_observed`	CI チェックごと（`assess_stack` が発行）	CodeQualityView — スキルごとの合格率
`ci.status`	CI チェック結果ごと	ShepherdStatusView — PR の健全性の追跡
`remediation.attempted`	修正の適用前	selfCorrectionRate メトリクス
`remediation.succeeded`	修正の確認後	avgRemediationAttempts メトリクス
`shepherd.approval_requested`	レビューのリクエスト時	監査証跡
`shepherd.completed`	マージの検出時（`assess_stack` が発行）	監査証跡

ドメイン知識

詳細なガイダンスについては、以下の資料を参照してください。

references/fix-strategies.md — 問題の種類ごとの修正アプローチ、応答テンプレート、修正イベントの発行に関する詳細
references/escalation-criteria.md — イテレーションを停止してユーザーにエスカレーションするタイミング
references/gate-event-emission.md — assess_stack が発行する ci.check_observed のイベント形式
references/shepherd-event-schemas.md — 4 つすべての shepherd ライフサイクルイベントの Zod 準拠スキーマ全体

意思決定ランブック

イテレーションの上限に達した場合、または CI が繰り返し失敗する場合は、エスカレーションランブックを参照してください。 exarchos_orchestrate({ action: "runbook", id: "shepherd-escalation" })

このランブックでは、イテレーション回数、CI の安定性、レビュー状況に基づいて、イテレーションを続けるか、ユーザーにエスカレーションするか、shepherd ループを中止するかを判断するための構造化された基準が示されています。

アンチパターン

しないこと	代わりにすること
CI やレビューを直接ポーリングする	`assess_stack` 複合アクションを使用する
CI が失敗している状態で強制マージする	まず失敗を修正する
インラインコメントを無視する	返信してすべてのスレッドに対応する
`assess_stack` が `request-approval` と判定したため、軽微なコメントや細かな指摘を無視する	まずすべての `comment-reply` 項目に対応する — 推奨はあくまで助言です（デフォルトの目標を参照）
不変条件を確認せずに修正内容を作成する	各変更を `.exarchos/invariants.md` に基づける（ステップ 2、カタログ登録がゲート条件）
カタログが登録されているのに、不変条件との照合を差分で確認せずにマージする	承認／マージの前に、PR の差分に対して `check_invariant_conformance` を実行する（ステップ 4 の参照先、カタログ登録がゲート条件、非ブロッキング）
無期限にループする	イテレーションの上限を守り、エスカレーションする
修正イベントを省略する	修正のたびに `remediation.attempted` / `remediation.succeeded` を発行する
`main` に直接プッシュする	すべての修正はスタックブランチを経由する

遷移

承認が得られて PR がマージされたら、cleanup を実行してワークフローを完了状態にします。

Markdown 対応

ログインしてコメント

基本情報

作者: lvlup-sw
リポジトリ: lvlup-sw/exarchos
カテゴリ: 開発
インストール数: 216
GitHub スター: 22

問題を報告