shepherd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shepherd Skill

Shepherd技能

VCS Provider

VCS提供商

This skill uses VCS operations through Exarchos MCP actions (

check_ci

list_prs

merge_pr

get_pr_comments

add_pr_comment

, etc.). These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps). No

gh

glab

az

commands needed — the MCP server handles provider dispatch.

The
merge_pr
invoked here is the remote PR merge primitive (synthesize-phase). It is distinct from
merge_orchestrate
(
@skills/merge-orchestrator/SKILL.md
), which is the local
git merge
orchestrator used during the upstream
merge-pending
substate. This skill never invokes
merge_orchestrate
.

Iterative loop that shepherds published PRs through CI checks and code reviews to merge readiness. Uses the

assess_stack

composite action for all PR health checks, fixing failures and addressing feedback until the stack is green.

Note: Shepherd is not a separate HSM phase. It operates as a loop within the
synthesize
phase. The workflow phase remains
synthesize
throughout the shepherd iteration cycle. Events (
shepherd.iteration
,
ci.status
) and the
shepherd_status
view track loop progress without requiring a phase transition.

Position in workflow:

text

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

本技能通过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阶段）。它与
merge_orchestrate
（
@skills/merge-orchestrator/SKILL.md
）不同，后者是上游
merge-pending
子状态中使用的本地
git merge
编排器。本技能绝不会调用
merge_orchestrate
。

以迭代循环方式引导已发布的PR通过CI检查和代码评审，直至达到可合并状态。使用

assess_stack

复合操作进行所有PR健康检查，修复问题并处理反馈，直至所有检查通过。

注意： Shepherd并非独立的HSM阶段。它在
synthesize
阶段内以循环方式运行。在整个Shepherd迭代周期中，工作流阶段始终为
synthesize
。事件（
shepherd.iteration
、
ci.status
）和
shepherd_status
视图会跟踪循环进度，无需进行阶段切换。

在工作流中的位置：

text

/synthesize → /shepherd (评估 → 修复 → 重新提交 → 循环) → /cleanup
              ^^^^^^^^^ 在synthesize阶段内运行

Pipeline Hygiene

流水线维护

When

mcp__exarchos__exarchos_view pipeline

accumulates stale workflows (inactive > 7 days), run

@skills/prune-workflows/SKILL.md

to bulk-cancel abandoned workflows before starting a new shepherd cycle. Safeguards skip workflows with open PRs or recent commits, so active shepherd targets are never touched. A clean pipeline makes shepherd iteration reporting easier to read and reduces noise in the stale-count view.

当

mcp__exarchos__exarchos_view pipeline

累积了过时工作流（超过7天未活跃）时，在启动新的Shepherd循环前运行

@skills/prune-workflows/SKILL.md

批量取消已废弃的工作流。保护机制会跳过包含开放PR或近期提交的工作流，因此绝不会触及活跃的Shepherd目标。干净的流水线能让Shepherd迭代报告更易阅读，并减少过时计数视图中的干扰信息。

Triggers

触发条件

Activate when:

User runs
```
/shepherd
```
or says "shepherd", "tend PRs", "check CI"
PRs are published and need monitoring through the CI/review gauntlet
After
```
/synthesize
```
completes and PRs are enqueued

满足以下条件时激活：

用户运行
```
/shepherd
```
或输入"shepherd"、"tend PRs"、"check CI"
PR已发布，需要监控其通过CI/评审的全过程
```
/synthesize
```
完成且PR已进入队列后

Prerequisites

前置条件

Active workflow with PRs published (PR URLs in
```
synthesis.prUrl
```
or
```
artifacts.pr
```
)
PRs created and pushed (
```
create_pr
```
already ran)
Exarchos MCP tools available for VCS operations

存在包含已发布PR的活跃工作流（PR URL存储在
```
synthesis.prUrl
```
或
```
artifacts.pr
```
中）
PR已创建并推送（
```
create_pr
```
已执行）
可使用Exarchos MCP工具进行VCS操作

Process

流程

Runbook: Each shepherd iteration follows the shepherd-iteration runbook:
exarchos_orchestrate({ action: "runbook", id: "shepherd-iteration" })
If runbook unavailable, use
describe
to retrieve action schemas:
exarchos_orchestrate({ action: "describe", actions: ["assess_stack"] })

The shepherd loop repeats until all PRs are healthy or escalation criteria are met. Default: 5 iterations.

运行手册： 每次Shepherd迭代遵循shepherd-iteration运行手册：
exarchos_orchestrate({ action: "runbook", id: "shepherd-iteration" })
如果运行手册不可用，使用
describe
获取操作 schema：
exarchos_orchestrate({ action: "describe", actions: ["assess_stack"] })

Shepherd循环会重复执行，直到所有PR健康达标或达到升级标准。默认迭代次数为5次。

Step 0 — Surface Quality Signals

步骤0 — 提取质量信号

At the start of each iteration, query quality hints to inform the assessment:

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

If
```
regressions
```
is non-empty, include regression context in the status report
If any hint has
```
confidenceLevel: 'actionable'
```
, surface the
```
suggestedAction
```
in the iteration summary
If
```
gatePassRate < 0.80
```
for any skill, flag degrading quality trends

This step ensures the agent acts on accumulated quality intelligence before polling individual PRs.

在每次迭代开始时，查询质量提示信息以辅助评估：

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

如果
```
regressions
```
非空，在状态报告中包含回归上下文
如果任何提示的
```
confidenceLevel
```
为'actionable'，在迭代摘要中展示
```
suggestedAction
```
如果任一技能的
```
gatePassRate < 0.80
```
，标记质量下降趋势

此步骤确保Agent在轮询单个PR之前，先基于累积的质量智能采取行动。

Step 1 — Assess

步骤1 — 评估

Invoke the

assess_stack

composite action to check all PR dimensions at once:

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

The composite action internally handles:

CI status checking for all PRs
Formal review status (APPROVED / CHANGES_REQUESTED)
Inline review comment polling and thread resolution (Sentry, CodeRabbit, humans)
Stack health verification
Event emission:
```
gate.executed
```
events per CI check (feeds CodeQualityView) and
```
ci.status
```
events per PR (feeds ShepherdStatusView). See
```
references/gate-event-emission.md
```
for the event format.

Review the returned

actionItems

and

recommendation

Recommendation	Action
`request-approval`	Skip to Step 4
`fix-and-resubmit`	Proceed to Step 2
`wait`	Inform user, pause, re-assess after delay
`escalate`	See `references/escalation-criteria.md`

调用

assess_stack

复合操作，一次性检查所有PR的各项维度：

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

该复合操作内部会处理：

所有PR的CI状态检查
正式评审状态（APPROVED / CHANGES_REQUESTED）
内联评审评论轮询和线程解决（Sentry、CodeRabbit、人工评审）
堆栈健康验证
事件发送：每个CI检查发送
```
gate.executed
```
事件（供CodeQualityView使用），每个PR发送
```
ci.status
```
事件（供ShepherdStatusView使用）。事件格式详见
```
references/gate-event-emission.md
```
。

查看返回的

actionItems

和

recommendation

：

建议	操作
`request-approval`	跳至步骤4
`fix-and-resubmit`	进入步骤2
`wait`	通知用户，暂停，延迟后重新评估
`escalate`	查看 `references/escalation-criteria.md`

Step 2 — Fix

步骤2 — 修复

Before iterating over individual action items, classify them so the loop knows which to fix inline vs. delegate. Call

classify_review_items

on the assessment's

actionItems

(the comment-reply subset is what the classifier groups by file; CI-fix and review-address items are passed through unchanged):

typescript

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

The result returns

groups: ClassificationGroup[]

with a

recommendation

per group:

direct

(handle inline),

delegate-fixer

(spawn the fixer subagent for batched/HIGH-severity work), or

delegate-scaffolder

(cheap subagent for doc nits). Iterate the groups in order, applying per-group strategy, then consult

references/fix-strategies.md

for detailed per-issue-type instructions.

Remediation event protocol (FLYWHEEL):

BEFORE applying a fix, emit

remediation.attempted

typescript

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

Apply the fix (CI failure, review comment response, stack restack).

AFTER the next assess confirms the fix resolved the gate, emit

remediation.succeeded

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

These events feed

selfCorrectionRate

and

avgRemediationAttempts

metrics in CodeQualityView.

Action item types:

Type	Strategy
`ci-fix`	Read logs, reproduce locally, fix, commit to stack branch
`comment-reply`	Use `actionItem.reviewer` , `normalizedSeverity` , `file` , `line` , and `raw` (full original comment) to compose a response. Provider adapters under `servers/exarchos-mcp/src/review/providers/` populate the input fields per #1159 — no manual tier parsing needed. Posting: PR-level summary comments use the provider-agnostic `add_pr_comment` orchestrate action; per-thread inline replies currently require the platform-specific MCP (e.g. `mcp__plugin_github_github__add_reply_to_pull_request_comment` for GitHub) until `VcsProvider` gains a thread-reply primitive — see #1165 for tracking.
`review-address`	Fix code for CHANGES_REQUESTED, reply to each thread
`restack`	Run `git rebase origin/<base>` , verify with `exarchos_orchestrate({ action: "list_prs" })`
`escalate`	Consult `references/escalation-criteria.md`

Every inline review comment must get a reply. The goal is that a human scanning the PR sees every thread has a response.

在逐个处理操作项之前，先对其进行分类，以便循环知道哪些需要直接处理，哪些需要委派。对评估得到的

actionItems

调用

classify_review_items

（分类器会按文件对评论回复子集进行分组；CI修复和评审处理项会直接传递）：

typescript

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

结果会返回

groups: ClassificationGroup[]

，每个分组带有对应的

recommendation

：

direct

（直接处理）、

delegate-fixer

（启动修复子Agent处理批量/高严重性工作）或

delegate-scaffolder

（使用轻量Agent处理文档小问题）。按顺序遍历分组，应用分组策略，然后参考

references/fix-strategies.md

获取针对不同问题类型的详细处理说明。

修复事件协议（FLYWHEEL）：

应用修复前，发送

remediation.attempted

事件：

typescript

mcp__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

事件：

mcp__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/` 下的提供商适配器会根据#1159填充输入字段——无需手动解析层级。发布： PR级摘要评论使用与提供商无关的 `add_pr_comment` 编排操作；当前线程内联回复需要特定平台的MCP（例如GitHub使用 `mcp__plugin_github_github__add_reply_to_pull_request_comment` ），直到 `VcsProvider` 添加线程回复原语——跟踪进度见#1165。
`review-address`	针对CHANGES_REQUESTED修复代码，回复每个线程
`restack`	运行 `git rebase origin/<base>` ，使用 `exarchos_orchestrate({ action: "list_prs" })` 验证
`escalate`	参考 `references/escalation-criteria.md`

每条内联评审评论都必须回复。目标是让查看PR的人员看到所有线程都有回应。

Step 3 — Resubmit

步骤3 — 重新提交

After fixes are applied, resubmit the stack:

bash

git push --force-with-lease

Re-enable auto-merge if needed:

typescript

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

Return to Step 1 for the next iteration. Track iteration count against the limit (default 5). If the limit is reached without reaching

request-approval

, escalate per

references/escalation-criteria.md

修复完成后，重新提交堆栈：

bash

git push --force-with-lease

如有需要，重新启用自动合并：

typescript

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

返回步骤1进行下一次迭代。跟踪迭代次数是否达到限制（默认5次）。如果达到限制仍未进入

request-approval

状态，按照

references/escalation-criteria.md

进行升级处理。

Step 4 — Request Approval

步骤4 — 请求审批

When

assess_stack

returns

recommendation: 'request-approval'

(all checks green, all comments addressed):

Request review via GitHub MCP:

mcp__plugin_github_github__update_pull_request({
  owner: "<owner>", repo: "<repo>", pullNumber: <number>,
  reviewers: ["<approver>"]
})

Fallback (if MCP token lacks write scope):

gh pr edit <number> --add-reviewer <approver>

Report to user:

markdown

## 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.

当

assess_stack

recommendation: 'request-approval'

（所有检查通过，所有评论已处理）时：

通过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>

向用户报告：

markdown

## 已准备好审批

所有CI检查通过。所有评审评论已处理。
已向以下人员请求审批：<approvers>

PR列表：
- #123: <url>
- #124: <url>

合并完成后运行`/cleanup`。

State Management

状态管理

Track shepherd progress via workflow state:

Initialize:

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

After each iteration: Update

currentIteration

, record assessment summary and actions taken. On approval: set

approvalRequested: true

with timestamp and approver list.

通过工作流状态跟踪Shepherd进度：

初始化：

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

每次迭代后： 更新

currentIteration

，记录评估摘要和已执行的操作。请求审批时：设置

approvalRequested: true

并记录时间戳和审批人列表。

Phase Transitions and Guards

阶段切换与防护

For the full transition table, consult

@skills/workflow-state/references/phase-transitions.md

The shepherd skill operates within the

synthesize

phase and does not drive phase transitions directly.

完整的切换表请参考

@skills/workflow-state/references/phase-transitions.md

。

Shepherd技能在

synthesize

阶段内运行，不会直接触发阶段切换。

Schema Discovery

Schema发现

Use

exarchos_workflow({ action: "describe", actions: ["set", "init"] })

for parameter schemas and

exarchos_workflow({ action: "describe", playbook: "feature" })

for phase transitions, guards, and playbook guidance. Use

exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status", "remediation.attempted"] })

for event data schemas before emitting events.

使用

exarchos_workflow({ action: "describe", actions: ["set", "init"] })

获取参数schema，使用

exarchos_workflow({ action: "describe", playbook: "feature" })

获取阶段切换、防护和工作手册指南。发送事件前，使用

exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status", "remediation.attempted"] })

获取事件数据schema。

Event Emission

事件发送

Before emitting any shepherd events, consult

references/shepherd-event-schemas.md

for full Zod schemas, type constraints, and example payloads. Use

exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status"] })

to discover required fields at runtime.

Event	When	Purpose
`shepherd.started`	On skill start (emitted by `assess_stack` )	Audit trail
`shepherd.iteration`	After each assess cycle	Track progress
`gate.executed`	Per CI check (emitted by `assess_stack` )	CodeQualityView -- gate pass rates
`ci.status`	Per CI check result	ShepherdStatusView -- PR health tracking
`remediation.attempted`	Before applying a fix	selfCorrectionRate metric
`remediation.succeeded`	After fix confirmed	avgRemediationAttempts metric
`shepherd.approval_requested`	On requesting review	Audit trail
`shepherd.completed`	On merge detected (emitted by `assess_stack` )	Audit trail

发送任何Shepherd事件前，请参考

references/shepherd-event-schemas.md

获取完整的Zod schema、类型约束和示例负载。运行时可使用

exarchos_event({ action: "describe", eventTypes: ["shepherd.iteration", "ci.status"] })

发现必填字段。

事件	发送时机	用途
`shepherd.started`	技能启动时（由 `assess_stack` 发送）	审计追踪
`shepherd.iteration`	每次评估周期后	跟踪进度
`gate.executed`	每个CI检查完成时（由 `assess_stack` 发送）	CodeQualityView——检查通过率
`ci.status`	每个CI检查结果生成时	ShepherdStatusView——PR健康跟踪
`remediation.attempted`	应用修复前	selfCorrectionRate指标
`remediation.succeeded`	修复确认后	avgRemediationAttempts指标
`shepherd.approval_requested`	请求评审时	审计追踪
`shepherd.completed`	检测到合并时（由 `assess_stack` 发送）	审计追踪

Domain Knowledge

领域知识

Consult these references for detailed guidance:

```
references/fix-strategies.md
```
— Fix approaches per issue type, response templates, remediation event emission details
```
references/escalation-criteria.md
```
— When to stop iterating and escalate to the user

references/gate-event-emission.md

— Event format for

gate.executed

(now emitted by

assess_stack

)

```
references/shepherd-event-schemas.md
```
— Full Zod-aligned schemas for all four shepherd lifecycle events

如需详细指导，请参考以下文档：

```
references/fix-strategies.md
```
— 不同问题类型的修复方法、回复模板、修复事件发送细节
```
references/escalation-criteria.md
```
— 何时停止迭代并向用户升级问题

references/gate-event-emission.md

—

gate.executed

事件格式（现由

assess_stack

发送）

```
references/shepherd-event-schemas.md
```
— 所有四个Shepherd生命周期事件的完整Zod对齐schema

Decision Runbooks

决策运行手册

When iteration limits are reached or CI repeatedly fails, consult the escalation runbook:

exarchos_orchestrate({ action: "runbook", id: "shepherd-escalation" })

This runbook provides structured criteria for deciding whether to keep iterating, escalate to the user, or abort the shepherd loop based on iteration count, CI stability, and review status.

当达到迭代限制或CI反复失败时，参考升级运行手册：

exarchos_orchestrate({ action: "runbook", id: "shepherd-escalation" })

本运行手册提供结构化标准，用于决定是继续迭代、向用户升级问题还是终止Shepherd循环，决策依据包括迭代次数、CI稳定性和评审状态。

Anti-Patterns

反模式

Don't	Do Instead
Poll CI/reviews directly	Use `assess_stack` composite action
Force-merge with failing CI	Fix the failures first
Ignore inline comments	Address every thread with a reply
Loop indefinitely	Respect iteration limits, escalate
Skip remediation events	Emit `remediation.attempted` / `remediation.succeeded` for every fix
Push directly to main	All fixes go through stack branches

禁止操作	正确做法
直接轮询CI/评审	使用 `assess_stack` 复合操作
CI失败时强制合并	先修复问题
忽略内联评论	回复每个线程
无限循环	遵守迭代限制，及时升级
跳过修复事件	每次修复都发送 `remediation.attempted` / `remediation.succeeded` 事件
直接推送到主分支	所有修复都通过堆栈分支提交

Transition

后续操作

After approval is granted and PRs merge, run

/cleanup

to resolve the workflow to completed state.

审批通过且PR合并后，运行

/cleanup

将工作流标记为完成状态。