@fitlab-ai/agent-infra 0.7.1 → 0.7.3

package/templates/.agents/skills/watch-pr/SKILL.zh-CN.md

@@ -0,0 +1,131 @@
+---
+name: watch-pr
+description: "监控 PR 的 required checks 并在失败时自愈"
+---
+
+# 监控 Pull Request
+
+在 `create-pr` 之后持续监控 PR 的 required CI checks：全绿则引导合入，required check 失败则自动拉日志、本地修复并推送、重新轮询；达修复上限或属非代码层/不可定位失败则停止并向用户求助。平台专属命令集中在 `.agents/rules/pr-checks-commands.md`，本技能正文保持平台无关。
+
+## 行为边界 / 关键规则
+
+- 仅监控 + 自愈当前 PR 的 required checks；不做与失败 check 无关的改动。
+- 自愈会修改业务代码并 `git push` 到 PR 分支，但**推送前必须本地跑通相关测试**；修复尝试有硬上限（默认 2）；仅对可定位的代码层失败（lint / format / test / 类型 / 构建）自愈，非代码层（网络 / 权限 / 外部服务 / flaky）一律转求助出口。
+- 求助出口是「产出后停止」语义：停止本轮、输出阻塞说明、等待用户主动触发，**不**中途提问。
+- 裸数字 / `#NN` / `TASK-id` 入参一律按任务短号解析（见 `.agents/rules/task-short-id.md`）；PR 号只走 `--pr <number>` / PR URL / 省略（当前分支），不复用裸数字语法。
+- 执行本技能（任务锚定路径）后，必须更新 task.md。
+
+版本戳规则：创建或更新 `task.md` frontmatter 时，先读取 `.agents/rules/version-stamp.md`，并写入或刷新 `agent_infra_version`。
+
+## 任务入参短号别名
+
+> 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
+
+## 执行步骤
+
+### 1. 解析入参
+
+按以下确定性分支解析出目标 PR 号 `{pr#}` 与可选 `{task-id}`：
+
+- 场景 A（省略入参）：按 `.agents/rules/pr-checks-commands.md` 取当前分支的 PR 号；随后按下方「反查任务」确定 `{task-id}`。
+- 场景 B（`#NN` / 裸数字 / `TASK-id`，**任务锚定主路径**）：匹配 `^[#]?[0-9]+$` 时按「任务入参短号别名」解析为完整 `{task-id}`（解析失败直接透传退出码，不重写错误处理）；`TASK-id` 直接采用。读 `.agents/workspace/active/{task-id}/task.md` 取 `pr_number` 作为 `{pr#}`；`pr_number` 为空时按「错误处理」提示先 `create-pr`，停止。
+- 场景 C（`--pr <number>` 或 PR URL）：直接取该 PR 号为 `{pr#}`；随后按「反查任务」确定 `{task-id}`。
+- 反查任务（场景 A / C）：在 `.agents/workspace/active/*/task.md` 中查找 `pr_number == {pr#}` 的任务；命中则取该 `{task-id}`（任务锚定）；未命中则进入「仅监控」降级路径（无 `{task-id}`，跳过步骤 5/6）。
+
+### 2. 监控 required checks
+
+执行此步骤前，先读取 `reference/monitor-and-heal.md` 与 `.agents/rules/pr-checks-commands.md`。
+
+按 `.agents/rules/pr-checks-commands.md` 的监控命令对 `{pr#}` 的 required checks 轮询（含总时长上限，默认 30 分钟），按 `reference/monitor-and-heal.md` 的「结果分类」分为「全绿」/「失败」/「挂起」三个场景，分别进入步骤 7 全绿出口、步骤 3 自愈、或步骤 4 求助。
+
+### 3. 失败自愈循环
+
+执行此步骤前，先读取 `reference/monitor-and-heal.md` 的「自愈决策树」与 `.agents/rules/pr-checks-commands.md` 的「解析失败 run id 并拉日志」。
+
+对失败 check：先按规则确定性解析其失败 run 并拉取失败日志、判定失败类别；仅当属可定位的代码层失败时，本地最小化修复、运行对应测试通过后**暂存并提交本次修复再推送**（`git add` 仅相关文件 → 按 `.agents/rules/commit-and-pr.md` `git commit` → `git push` 到当前 PR 分支，并记录 commit SHA），再回到步骤 2 重新监控。修复尝试计数，达硬上限（默认 2）或 run 不可定位 → 转步骤 4。
+
+### 4. 求助出口（产出后停止）
+
+当自愈达上限、失败属非代码层、run id 不可定位、或步骤 2 挂起超时时，停止本轮并向用户汇总：阻塞原因、已尝试的修复（含每次修复 commit）、相关失败 job 与 run/log 链接（报告结构见 `reference/monitor-and-heal.md` 的「求助报告模板」）。**不**渲染下一步命令，等待用户裁定。随后在任务锚定路径下执行步骤 5/6 记录本轮结果。
+
+### 5. 更新任务状态
+
+> 仅任务锚定路径执行；「仅监控」降级路径跳过本步骤与步骤 6。
+
+获取当前时间：
+
+```bash
+date "+%Y-%m-%d %H:%M:%S%:z"
+```
+
+更新 `.agents/workspace/active/{task-id}/task.md`：
+- `assigned_to`：{当前代理}
+- `updated_at`：{当前时间}
+- `agent_infra_version`：按 `.agents/rules/version-stamp.md` 取值
+- **不改** `pr_status`（保持 `created`）与 `current_step`
+- **追加**到 `## 活动日志`（不要覆盖之前的记录；`{N}` = 本任务已有 Watch PR 条目数 + 1）：
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Watch PR (Round {N})** by {agent} — {全绿：all required checks green / 阻塞：blocked: {简述}}
+  ```
+
+### 6. 完成校验
+
+> 仅任务锚定路径执行。
+
+运行完成校验：
+
+```bash
+node .agents/scripts/validate-artifact.js gate watch-pr .agents/workspace/active/{task-id} --format text
+```
+
+处理结果：
+- 退出码 0（全部通过）-> 继续到「告知用户」步骤
+- 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
+- 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入
+
+将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
+
+### 7. 告知用户
+
+> 任务锚定路径仅在校验通过后执行本步骤。
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+按场景输出：
+- 「全绿」+ 任务锚定：说明所有 required checks 已通过、PR 可合入，并按下方模板渲染下一步（`{task-ref}` 替换为短号）：
+
+  ```
+  下一步 - 完成并归档任务：
+    - Claude Code / OpenCode：/complete-task {task-ref}
+    - Gemini CLI：/agent-infra:complete-task {task-ref}
+    - Codex CLI：$complete-task {task-ref}
+  ```
+
+- 「全绿」+ 仅监控降级：说明 PR 可合入；本次无关联任务，请对相应任务运行 `complete-task`（无 `{task-ref}` 可渲染时不强行输出短号命令块）。
+- 「阻塞」：仅输出步骤 4 的阻塞说明，不推荐下一步命令。
+
+## 完成检查清单
+
+- [ ] 解析出目标 PR（及可能的任务上下文）
+- [ ] 完成 required checks 监控，得到全绿 / 阻塞结论
+- [ ] 自愈仅限可定位的代码层失败，且推送前本地测试通过、未超修复上限
+- [ ] 任务锚定路径：更新了 task.md 并追加 Watch PR 的 Activity Log
+- [ ] 任务锚定路径：完成校验通过
+- [ ] 向用户展示了所有 TUI 格式的下一步命令（全绿出口；阻塞出口不渲染下一步）
+
+## 停止
+
+完成检查清单后立即停止。全绿出口等待用户运行 `complete-task`；阻塞出口等待用户裁定。
+
+## 注意事项
+
+1. **前置条件**：PR 已存在（由 `create-pr` 创建或显式 `--pr` / 当前分支可定位）。
+2. **裸数字恒为任务短号**：不要把裸数字当作 PR 号；PR 号用 `--pr <number>`。
+3. **自愈安全**：推送前必须本地测试通过；非代码层 / 不可定位失败一律求助，不盲目重试。
+4. **可多次运行**：watch-pr 可在一次任务生命周期多次运行，Round 计数按已有 Watch PR Activity Log 条目数递增。
+
+## 错误处理
+
+- 无法定位 PR（任务短号命中但 task.md 无 `pr_number`，且未传 `--pr`、当前分支也无 PR）：提示「请先运行 `create-pr`，或用 `--pr <number>` 指定 PR」，停止。
+- 平台 CLI 未认证或 API 不可用：提示需人工介入，停止。
+- 短号解析失败：透传 `task-short-id.js` 的退出码与错误信息，不重写。

package/templates/.agents/skills/watch-pr/config/verify.json

@@ -0,0 +1,22 @@
+{
+  "skill": "watch-pr",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "agent_infra_version",
+        "current_step",
+        "assigned_to"
+      ]
+    },
+    "activity-log": {
+      "expected_action_pattern": "(Watch PR|Watching PR) \\(Round \\d+\\)",
+      "freshness_minutes": 30
+    }
+  }
+}

package/templates/.agents/skills/watch-pr/reference/monitor-and-heal.en.md

@@ -0,0 +1,43 @@
+# Monitoring & Self-Heal Details
+
+Platform-agnostic decision logic for `watch-pr` steps 2/3/4. The concrete platform commands (watch, resolve a failing run, pull logs, read the PR number) live in `.agents/rules/pr-checks-commands.md`; this file only describes platform-independent classification and decisions.
+
+## Outcome Classification
+
+After running the watch command from `.agents/rules/pr-checks-commands.md`, classify by its exit code into three buckets:
+
+- All required checks passed → "all green" (SKILL step 7 green exit).
+- At least one failed / errored → "failure" (SKILL step 3 self-heal).
+- Still pending or the overall time cap was reached → "pending" (SKILL step 4 help exit).
+
+## Self-Heal Decision Tree
+
+For each failing check, decide "self-heal" vs "ask for help" in this order:
+
+1. **Can the corresponding CI run be located** (per the rule's "Resolve a failing run id")? No → ask for help.
+2. **Which layer is the failure?**
+   - Code layer (self-healable): lint / format / type check / unit or integration test assertions / build-compile errors — locatable to a specific file and cause in this repo from the logs.
+   - Non-code layer (not self-healable): network flakiness, permissions / tokens, external service outages, dependency-source failures, obvious flakiness (a re-run might go green but it was not introduced by this change) → ask for help.
+3. **Has the fix cap been reached** (default 2 push-fixes)? Yes → ask for help.
+4. When "locatable + code layer + under cap" holds, perform one self-heal:
+   - Before fixing, run `git status -s` to record the working tree and ensure only changes related to this failure are included.
+   - Locate and make a minimal fix per the logs (touch only code / tests / config related to that failure).
+   - Run the relevant tests: prefer the local command for the failing job; fall back to `npm run test:core` repo-wide. **Do not commit or push before tests pass.**
+   - After tests pass, publish the fix: per `.agents/rules/commit-and-pr.md` stage only the related files (`git add <paths>`, avoid `git add -A` pulling in unrelated changes) → create the fix commit (`git commit`) → `git push` to the current PR branch.
+   - Record the fix commit SHA, increment the fix count, and return to SKILL step 2 to re-watch.
+   - Never make unrelated "drive-by" optimizations; never loosen / skip the failing assertion to "make it green".
+
+## Help Report Template
+
+When entering the help exit, output the following fixed structure to the user (not written to any artifact file):
+
+```
+PR #{pr#} monitoring is blocked; manual intervention needed.
+
+Blocker: {non-code layer / fix cap reached / run unlocatable / poll timeout}
+Failing check: {name} (workflow: {workflow})
+Failing run / logs: {run/job link}
+Fixes attempted ({k} total):
+  - {commit summary}: {change summary} → still failing after re-watch
+Suggestion: {upgrade platform CLI / check permissions / re-run external dependency / inspect logs manually, etc.}
+```

package/templates/.agents/skills/watch-pr/reference/monitor-and-heal.zh-CN.md

@@ -0,0 +1,43 @@
+# 监控与自愈细则
+
+`watch-pr` 步骤 2/3/4 的平台无关判定逻辑。具体平台命令（监控、解析失败 run、拉日志、读取 PR 号）见 `.agents/rules/pr-checks-commands.md`；本文件只描述与平台无关的分类与决策。
+
+## 结果分类
+
+按 `.agents/rules/pr-checks-commands.md` 的监控命令执行后，依其退出码归为三类：
+
+- 全部 required checks 通过 → 「全绿」（SKILL 步骤 7 全绿出口）。
+- 至少一个失败 / 出错 → 「失败」（SKILL 步骤 3 自愈）。
+- 仍有 pending 或达到总时长上限 → 「挂起」（SKILL 步骤 4 求助）。
+
+## 自愈决策树
+
+对每个失败 check，按下列顺序判定「自愈」还是「求助」：
+
+1. **能否定位到对应的 CI run**（按规则的「解析失败 run id」）？否 → 求助。
+2. **失败属于哪一层**？
+   - 代码层（可自愈）：lint / format / 类型检查 / 单元或集成测试断言 / 构建编译错误等，能从日志定位到本仓库具体文件与原因。
+   - 非代码层（不可自愈）：网络抖动、权限 / 令牌、外部服务不可用、依赖源故障、明显的 flaky（重跑可能变绿但非本次改动引入）→ 求助。
+3. **是否已达修复上限**（默认 2 次推送修复）？是 → 求助。
+4. 满足「可定位 + 代码层 + 未达上限」时执行一次自愈：
+   - 自愈前先 `git status -s` 记录当前工作树，确保后续只纳入与本次失败相关的改动。
+   - 在本地按日志定位并最小化修复（只动与该失败相关的代码 / 测试 / 配置）。
+   - 运行对应测试：优先失败 job 对应的本地命令；仓库统一回退 `npm run test:core`。**测试通过前不得提交或推送。**
+   - 测试通过后发布修复：按 `.agents/rules/commit-and-pr.md` 仅暂存本次相关文件（`git add <相关路径>`，避免 `git add -A` 卷入无关改动）→ 创建修复 commit（`git commit`）→ `git push` 到当前 PR 分支。
+   - 记录本次修复的 commit SHA，修复计数 +1，回到 SKILL 步骤 2 重新监控。
+   - 绝不执行与失败无关的「顺手优化」；不放宽 / 跳过失败的断言来「修绿」。
+
+## 求助报告模板
+
+进入求助出口时，向用户输出以下固定结构（不写入产物文件）：
+
+```
+PR #{pr#} 监控阻塞，需人工介入。
+
+阻塞原因：{非代码层 / 达修复上限 / run 不可定位 / 轮询超时}
+失败 check：{name}（workflow：{workflow}）
+失败 run / 日志：{run/job 链接}
+已尝试的修复（共 {k} 次）：
+  - {commit 简述}：{改动概述} → 重新监控后仍失败
+建议：{升级平台 CLI / 检查权限 / 重跑外部依赖 / 人工查看日志 等}
+```

package/templates/.agents/templates/task.en.md

@@ -7,13 +7,13 @@ status: open                   # open | in-progress | review | blocked | complet
 created_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 updated_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 agent_infra_version: v0.0.0    # Current agent-infra version; refreshed by workflow commands
-short_id:                       # Allocated by create-task / import-* in active window; kept as historical value after archival
 priority:                       # Optional Issue field: Urgent | High | Medium | Low
 effort:                         # Optional Issue field: High | Medium | Low
 start_date:                     # Optional Issue field for Feature: YYYY-MM-DD
 target_date:                    # Optional Issue field for Feature: YYYY-MM-DD
 current_step: requirement-analysis # requirement-analysis | requirement-analysis-review | technical-design | technical-design-review | code | code-review | completed
 assigned_to:                   # claude | codex | gemini | opencode | human
+pr_status: pending             # PR status: pending (default) | created (PR created) | skipped (explicitly skipped)
 ---
 
 # Task: [Title]

package/templates/.agents/templates/task.zh-CN.md

@@ -7,13 +7,13 @@ status: open                   # open | in-progress | review | blocked | complet
 created_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 updated_at: YYYY-MM-DDTHH:mm:ss±HH:MM
 agent_infra_version: v0.0.0    # 当前 agent-infra 版本；由工作流命令刷新
-short_id:                       # 由 create-task / import-* 在 active 期内写入；归档后保留历史值
 priority:                       # 可选 Issue 字段：Urgent | High | Medium | Low
 effort:                         # 可选 Issue 字段：High | Medium | Low
 start_date:                     # Feature 可选 Issue 字段：YYYY-MM-DD
 target_date:                    # Feature 可选 Issue 字段：YYYY-MM-DD
 current_step: requirement-analysis # requirement-analysis | requirement-analysis-review | technical-design | technical-design-review | code | code-review | completed
 assigned_to:                   # claude | codex | gemini | opencode | human
+pr_status: pending             # PR 状态：pending（默认）| created（已创建 PR）| skipped（显式跳过）
 ---
 
 # 任务：[标题]

package/templates/.agents/workflows/bug-fix.en.yaml

@@ -1,8 +1,10 @@
 # Bug-fix workflow
 # Use this workflow when fixing a defect.
 #
-# Note: a step's `pr_tasks` list is counted toward workflow progress only when
-# `.agents/.airc.json:requiresPullRequest !== false` (see .agents/skills/complete-task/SKILL.md).
+# Note: whether a step's `pr_tasks` list counts toward workflow progress follows the "PR path" rule:
+# `.agents/.airc.json:prFlow="required"` always counts; `prFlow="disabled"` never counts;
+# when the field is absent, exclude only if task.md's `pr_status=skipped`, otherwise count
+# (see .agents/skills/complete-task/SKILL.md).
 
 name: bug-fix
 description: Workflow for diagnosing and fixing a defect.
@@ -139,7 +141,7 @@ steps:
           rule: "Read the highest-round plan review artifact and confirm feedback is approved or handled"
         - name: review-code
           pattern: "review-code.md | review-code-r{N}.md"
-          rule: "In fix mode, read the highest-round code review artifact and verify it matches the latest Code Review entry in task.md Activity Log"
+          rule: "In fix mode, read the highest-round code review artifact and verify it matches the latest Review Code entry in task.md Activity Log"
       outputs:
         - name: code
           pattern: "code.md | code-r{N}.md"
@@ -176,7 +178,7 @@ steps:
       - Findings list, if any
 
   - name: commit
-    description: Finalize the defect fix and create a pull request (the PR portion runs only when the project enables the PR flow).
+    description: Finalize the defect fix and create a pull request (the PR portion runs only on the PR path).
     recommended_agents:
       - claude
       - human
@@ -192,4 +194,4 @@ steps:
       - Task workspace
     outputs:
       - Completed task workspace under .agents/workspace/completed/
-      - Pull request (only when the project enables the PR flow)
+      - Pull request (only on the PR path)

package/templates/.agents/workflows/bug-fix.zh-CN.yaml

@@ -1,8 +1,9 @@
 # 缺陷修复工作流
 # 修复缺陷时使用此工作流。
 #
-# 注：步骤中的 `pr_tasks` 列表仅在 `.agents/.airc.json:requiresPullRequest !== false` 时
-# 被计入工作流进度判定（详见 .agents/skills/complete-task/SKILL.md）。
+# 注：步骤中的 `pr_tasks` 列表按「走 PR 路径」判定是否计入工作流进度：
+# `.agents/.airc.json:prFlow="required"` 始终计入；`prFlow="disabled"` 不计入；
+# 字段缺省时仅当 task.md 的 `pr_status=skipped` 排除，否则计入（详见 .agents/skills/complete-task/SKILL.md）。
 
 name: bug-fix
 description: 诊断和修复缺陷的工作流。
@@ -139,7 +140,7 @@ steps:
           rule: "读取最高轮次的方案审查产物，确认方案已获通过或已处理反馈"
         - name: review-code
           pattern: "review-code.md | review-code-r{N}.md"
-          rule: "修复模式读取最高轮次的代码审查产物，并校验其与 task.md Activity Log 中最近一条 Code Review 记录一致"
+          rule: "修复模式读取最高轮次的代码审查产物，并校验其与 task.md Activity Log 中最近一条 Review Code 记录一致"
       outputs:
         - name: code
           pattern: "code.md | code-r{N}.md"
@@ -176,7 +177,7 @@ steps:
       - 问题列表（如有）
 
   - name: commit
-    description: 最终确认缺陷修复并创建拉取请求（PR 部分仅在项目启用 PR 流程时执行）。
+    description: 最终确认缺陷修复并创建拉取请求（PR 部分仅在走 PR 路径时执行）。
     recommended_agents:
       - claude
       - human
@@ -192,4 +193,4 @@ steps:
       - 任务文件
     outputs:
       - 已完成的任务文件（位于 .agents/workspace/completed/）
-      - 拉取请求（仅项目启用 PR 流程时）
+      - 拉取请求（仅走 PR 路径时）

package/templates/.agents/workflows/feature-development.en.yaml

@@ -1,8 +1,10 @@
 # Feature development workflow
 # Use this workflow when implementing a new feature.
 #
-# Note: a step's `pr_tasks` list is counted toward workflow progress only when
-# `.agents/.airc.json:requiresPullRequest !== false` (see .agents/skills/complete-task/SKILL.md).
+# Note: whether a step's `pr_tasks` list counts toward workflow progress follows the "PR path" rule:
+# `.agents/.airc.json:prFlow="required"` always counts; `prFlow="disabled"` never counts;
+# when the field is absent, exclude only if task.md's `pr_status=skipped`, otherwise count
+# (see .agents/skills/complete-task/SKILL.md).
 
 name: feature-development
 description: End-to-end workflow for developing a new feature.
@@ -139,7 +141,7 @@ steps:
           rule: "Read the highest-round plan review artifact and confirm feedback is approved or handled"
         - name: review-code
           pattern: "review-code.md | review-code-r{N}.md"
-          rule: "In fix mode, read the highest-round code review artifact and verify it matches the latest Code Review entry in task.md Activity Log"
+          rule: "In fix mode, read the highest-round code review artifact and verify it matches the latest Review Code entry in task.md Activity Log"
       outputs:
         - name: code
           pattern: "code.md | code-r{N}.md"
@@ -176,7 +178,7 @@ steps:
       - Findings to fix
 
   - name: commit
-    description: Finalize changes and create a pull request (the PR portion runs only when the project enables the PR flow).
+    description: Finalize changes and create a pull request (the PR portion runs only on the PR path).
     recommended_agents:
       - claude
       - human
@@ -192,4 +194,4 @@ steps:
       - Task workspace
     outputs:
       - Completed task workspace under .agents/workspace/completed/
-      - Pull request (only when the project enables the PR flow)
+      - Pull request (only on the PR path)

package/templates/.agents/workflows/feature-development.zh-CN.yaml

@@ -1,8 +1,9 @@
 # 功能开发工作流
 # 实现新功能时使用此工作流。
 #
-# 注：步骤中的 `pr_tasks` 列表仅在 `.agents/.airc.json:requiresPullRequest !== false` 时
-# 被计入工作流进度判定（详见 .agents/skills/complete-task/SKILL.md）。
+# 注：步骤中的 `pr_tasks` 列表按「走 PR 路径」判定是否计入工作流进度：
+# `.agents/.airc.json:prFlow="required"` 始终计入；`prFlow="disabled"` 不计入；
+# 字段缺省时仅当 task.md 的 `pr_status=skipped` 排除，否则计入（详见 .agents/skills/complete-task/SKILL.md）。
 
 name: feature-development
 description: 开发新功能的端到端工作流。
@@ -139,7 +140,7 @@ steps:
           rule: "读取最高轮次的方案审查产物，确认方案已获通过或已处理反馈"
         - name: review-code
           pattern: "review-code.md | review-code-r{N}.md"
-          rule: "修复模式读取最高轮次的代码审查产物，并校验其与 task.md Activity Log 中最近一条 Code Review 记录一致"
+          rule: "修复模式读取最高轮次的代码审查产物，并校验其与 task.md Activity Log 中最近一条 Review Code 记录一致"
       outputs:
         - name: code
           pattern: "code.md | code-r{N}.md"
@@ -176,7 +177,7 @@ steps:
       - 待修复问题列表
 
   - name: commit
-    description: 最终确认变更并创建拉取请求（PR 部分仅在项目启用 PR 流程时执行）。
+    description: 最终确认变更并创建拉取请求（PR 部分仅在走 PR 路径时执行）。
     recommended_agents:
       - claude
       - human
@@ -192,4 +193,4 @@ steps:
       - 任务文件
     outputs:
       - 已完成的任务文件（位于 .agents/workspace/completed/）
-      - 拉取请求（仅项目启用 PR 流程时）
+      - 拉取请求（仅走 PR 路径时）

package/templates/.agents/workflows/refactoring.en.yaml

@@ -1,8 +1,10 @@
 # Refactoring workflow
 # Use this workflow for code refactoring tasks.
 #
-# Note: a step's `pr_tasks` list is counted toward workflow progress only when
-# `.agents/.airc.json:requiresPullRequest !== false` (see .agents/skills/complete-task/SKILL.md).
+# Note: whether a step's `pr_tasks` list counts toward workflow progress follows the "PR path" rule:
+# `.agents/.airc.json:prFlow="required"` always counts; `prFlow="disabled"` never counts;
+# when the field is absent, exclude only if task.md's `pr_status=skipped`, otherwise count
+# (see .agents/skills/complete-task/SKILL.md).
 
 name: refactoring
 description: Safe and structured workflow for code refactoring.
@@ -141,7 +143,7 @@ steps:
           rule: "Read the highest-round plan review artifact and confirm feedback is approved or handled"
         - name: review-code
           pattern: "review-code.md | review-code-r{N}.md"
-          rule: "In fix mode, read the highest-round code review artifact and verify it matches the latest Code Review entry in task.md Activity Log"
+          rule: "In fix mode, read the highest-round code review artifact and verify it matches the latest Review Code entry in task.md Activity Log"
       outputs:
         - name: code
           pattern: "code.md | code-r{N}.md"
@@ -180,7 +182,7 @@ steps:
       - Findings list, if any
 
   - name: commit
-    description: Finalize the refactoring and create a pull request (the PR portion runs only when the project enables the PR flow).
+    description: Finalize the refactoring and create a pull request (the PR portion runs only on the PR path).
     recommended_agents:
       - claude
       - human
@@ -196,4 +198,4 @@ steps:
       - Task workspace
     outputs:
       - Completed task workspace under .agents/workspace/completed/
-      - Pull request (only when the project enables the PR flow)
+      - Pull request (only on the PR path)

package/templates/.agents/workflows/refactoring.zh-CN.yaml

@@ -1,8 +1,9 @@
 # 重构工作流
 # 代码重构任务时使用此工作流。
 #
-# 注：步骤中的 `pr_tasks` 列表仅在 `.agents/.airc.json:requiresPullRequest !== false` 时
-# 被计入工作流进度判定（详见 .agents/skills/complete-task/SKILL.md）。
+# 注：步骤中的 `pr_tasks` 列表按「走 PR 路径」判定是否计入工作流进度：
+# `.agents/.airc.json:prFlow="required"` 始终计入；`prFlow="disabled"` 不计入；
+# 字段缺省时仅当 task.md 的 `pr_status=skipped` 排除，否则计入（详见 .agents/skills/complete-task/SKILL.md）。
 
 name: refactoring
 description: 安全且结构化的代码重构工作流。
@@ -141,7 +142,7 @@ steps:
           rule: "读取最高轮次的方案审查产物，确认方案已获通过或已处理反馈"
         - name: review-code
           pattern: "review-code.md | review-code-r{N}.md"
-          rule: "修复模式读取最高轮次的代码审查产物，并校验其与 task.md Activity Log 中最近一条 Code Review 记录一致"
+          rule: "修复模式读取最高轮次的代码审查产物，并校验其与 task.md Activity Log 中最近一条 Review Code 记录一致"
       outputs:
         - name: code
           pattern: "code.md | code-r{N}.md"
@@ -180,7 +181,7 @@ steps:
       - 问题列表（如有）
 
   - name: commit
-    description: 最终确认重构并创建拉取请求（PR 部分仅在项目启用 PR 流程时执行）。
+    description: 最终确认重构并创建拉取请求（PR 部分仅在走 PR 路径时执行）。
     recommended_agents:
       - claude
       - human
@@ -196,4 +197,4 @@ steps:
       - 任务文件
     outputs:
       - 已完成的任务文件（位于 .agents/workspace/completed/）
-      - 拉取请求（仅项目启用 PR 流程时）
+      - 拉取请求（仅走 PR 路径时）

package/templates/.claude/commands/watch-pr.en.md

@@ -0,0 +1,8 @@
+---
+description: "Watch a PR's required checks and self-heal on failure"
+usage: "/watch-pr [task-id | --pr <number>]"
+---
+
+Read and execute the watch-pr skill from `.agents/skills/watch-pr/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.claude/commands/watch-pr.zh-CN.md

@@ -0,0 +1,8 @@
+---
+description: "监控 PR 的 required checks 并在失败时自愈"
+usage: "/watch-pr [task-id | --pr <number>]"
+---
+
+读取并执行 `.agents/skills/watch-pr/SKILL.md` 中的 watch-pr 技能。
+
+严格按照技能中定义的所有步骤执行。

package/templates/.claude/settings.json

@@ -29,6 +29,17 @@
           }
         ]
       }
+    ],
+    "StopFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "sh \"$(git rev-parse --show-toplevel)/.agents/hooks/auto-resume.sh\""
+          }
+        ]
+      }
     ]
   }
 }

package/templates/.gemini/commands/_project_/watch-pr.en.toml

@@ -0,0 +1,8 @@
+description = "Watch a PR's required checks and self-heal on failure"
+prompt = """
+Watch PR checks: {{args}}
+
+Read and execute the watch-pr skill from `.agents/skills/watch-pr/SKILL.md`.
+
+Follow all steps defined in the skill exactly.
+"""

package/templates/.gemini/commands/_project_/watch-pr.zh-CN.toml

@@ -0,0 +1,8 @@
+description = "监控 PR 的 required checks 并在失败时自愈"
+prompt = """
+监控 PR 检查：{{args}}
+
+读取并执行 `.agents/skills/watch-pr/SKILL.md` 中的 watch-pr 技能。
+
+严格按照技能中定义的所有步骤执行。
+"""

package/templates/.opencode/commands/watch-pr.en.md

@@ -0,0 +1,11 @@
+---
+description: "Watch a PR's required checks and self-heal on failure"
+agent: general
+subtask: false
+---
+
+Watch PR checks: $ARGUMENTS
+
+Read and execute the watch-pr skill from `.agents/skills/watch-pr/SKILL.md`.
+
+Follow all steps defined in the skill exactly.

package/templates/.opencode/commands/watch-pr.zh-CN.md

@@ -0,0 +1,11 @@
+---
+description: "监控 PR 的 required checks 并在失败时自愈"
+agent: general
+subtask: false
+---
+
+监控 PR 检查：$ARGUMENTS
+
+读取并执行 `.agents/skills/watch-pr/SKILL.md` 中的 watch-pr 技能。
+
+严格按照技能中定义的所有步骤执行。