@fitlab-ai/agent-infra 0.7.6 → 0.7.7

package/templates/.agents/rules/create-issue.github.zh-CN.md

@@ -22,11 +22,11 @@
 
 从 `task.md` 提取以下字段：
 
-- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）
-- `## Description` / `## 描述` 段落
-- `## Requirements` / `## 需求` 段落
+- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）—— 用于构造 Issue 标题
 - frontmatter 中的 `type` 与（可选的）`milestone`
 
+> Issue **正文**不在此处手工提取。正文由 §3 调用 `ai task issue-body` 命令从 `## 描述` / `## 需求` 段确定性生成，调用方不得自行拼装。
+
 构造 Issue 标题：
 
 | task.md `type` | Conventional Commits type |
@@ -41,45 +41,35 @@ scope 推断：从 `.agents/.airc.json` 的 `labels.in` 字段读取已知模块
 
 ### 3. 构建 Issue 正文
 
+> **机械化边界（必须遵守）**：Issue 正文一律由 `ai task issue-body` 命令确定性生成；调用方只把命令 stdout 作为 `gh issue create` 的 `--body-file` 传入，**不得**自行拼装、改写或截断正文。命令只输出 task 标题 / `## 描述` / `## 需求` 对应内容，task.md 其余脚手架段落永不进入 body。
+
 Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板检测" 规则扫描 `.github/ISSUE_TEMPLATE/*.yml`（排除 `config.yml`）。
 
 #### 场景 A：检测到匹配模板
 
 按模板顶层 `name` 与任务类型挑选最匹配的 form（如任务 `type: bugfix` 优先选名称含 `bug` 的模板）；找不到匹配时，回退到通用 form（如 `other.yml`），仍找不到时取目录中第一个 form。
 
-按 `.agents/rules/issue-pr-commands.md` 中 "Issue 模板检测" 章节的字段处理规则填充 form：
-
-- `textarea` / `input` 字段：使用 `attributes.label` 作为 markdown 标题，从 task.md 取值
-- `markdown` 字段：跳过（说明文案）
-- `dropdown` / `checkboxes` 字段：跳过
+确定模板文件 `{form-path}` 后，由命令按该 Issue Form 渲染最终正文，并写入正文文件 `{body-file}` 供 §5 使用：
 
-字段值映射（建议）：
-
-| 模板字段提示 | task.md 来源 |
-|---|---|
-| `summary`, `title` | 任务标题 |
-| `description`, `problem`, `what happened`, `issue-description`, `current-content` | 任务描述 |
-| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | 需求列表（已勾选与未勾选混合，原样保留） |
-| 其它 `textarea` / `input` 字段 | 任务描述；缺失时填 `N/A` |
+```bash
+ai task issue-body {task-id} --template "{form-path}" > "{body-file}"
+```
 
-任何字段在 task.md 中找不到合适值时，写入 `N/A`。
+命令跳过 `markdown` / `dropdown` / `checkboxes` 字段，对 `input` / `textarea` 字段以 `attributes.label` 作标题、按字段 `id` 确定性填入 task 标题 / 描述 / 需求，无可靠映射源的字段填 `N/A`（字段映射表是命令内的单一真源，不在本规则重述）。命令退出码非 0（文件缺失 / 非法 YAML / 无 `body`）时，改用场景 B 命令重新生成 `{body-file}`。
 
 #### 场景 B：无模板或解析失败
 
-回退到默认正文：
-
-```markdown
-## Description
+由命令输出默认正文（仅 `## 描述` + `## 需求`，复选框逐字保留，缺失段落填 `N/A`），写入 `{body-file}`：
 
-{任务描述；缺失时填 N/A}
+```bash
+ai task issue-body {task-id} > "{body-file}"
+```
 
-## Requirements
+#### 红线：禁止把整份 task.md 当 body
 
-- [ ] {requirement-1}
-- [ ] {requirement-2}
-```
+无论场景 A / B，body 只能来自 `ai task issue-body` 的 stdout，**只含 描述 + 需求两段内容**（场景 A 为按模板字段映射后的等价内容）。
 
-需求列表为空时，整段写 `N/A`。
+错误示范（❌ 禁止）：把含 `## 分析` / `## 设计` / `## 实现备注` / `## 审查反馈` / `## 审查分歧账本` / `## 人工裁决` / `## 活动日志` / `## 完成检查清单` 等脚手架段落、以及 `#XXX` 占位的整份 task.md 直接作为 Issue body。这些段落只走 `sync-issue:{task-id}:task` 评论，绝不进 body。
 
 ### 4. 解析 labels / Issue Type / milestone
 
@@ -137,17 +127,18 @@ Issue 模板检测：按 `.agents/rules/issue-pr-commands.md` 的 "Issue 模板
 
 ### 5. 调用 GitHub CLI 创建 Issue
 
-按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行：
+按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行；正文统一用 §3 生成的 `{body-file}`，覆盖通用命令的 `--body`：
 
 ```bash
 gh issue create -R "$upstream_repo" \
   --title "{title}" \
-  --body "{body}" \
+  --body-file "{body-file}" \
   --assignee @me \
   {label-args} \
   {milestone-arg}
 ```
 
+- `{body-file}` 为 §3 由 `ai task issue-body` 生成的正文文件；**不得**改用 `--body` 自行拼装正文
 - `{label-args}` 由 §4 计算结果展开为多个 `--label "..."`；为空则整体省略
 - `{milestone-arg}` 仅当 `has_triage=true` 且 milestone 非空时展开为 `--milestone "..."`；否则整体省略
 - `--assignee @me` 不做权限预判，失败时静默跳过

package/templates/.agents/rules/issue-pr-commands.github.en.md

@@ -186,6 +186,12 @@ List PRs:
 gh pr list --state {state} --base {base-branch} --json number,title,url,headRefName,baseRefName
 ```
 
+Find the open PR whose head is the current branch (used by the `commit` push wrap-up):
+
+```bash
+gh pr list --head "{branch}" --state open --json number,url --jq '.[0].url // empty'
+```
+
 Create a PR:
 
 ```bash

package/templates/.agents/rules/issue-pr-commands.github.zh-CN.md

@@ -186,6 +186,12 @@ gh pr view {pr-number} --json number,title,body,labels,state,milestone,url,files
 gh pr list --state {state} --base {base-branch} --json number,title,url,headRefName,baseRefName
 ```
 
+按 head 分支查询当前分支是否存在开放 PR（`commit` 推送收尾用）：
+
+```bash
+gh pr list --head "{branch}" --state open --json number,url --jq '.[0].url // empty'
+```
+
 创建 PR：
 
 ```bash

package/templates/.agents/rules/next-step-output.en.md

@@ -1,9 +1,10 @@
 # Next-Step Output Rule
 
-This file defines two **independent** rules for a skill's "notify-user / Next steps" output; read this file before rendering the final output and apply both:
+This file defines three **independent** rules for a skill's "notify-user / Next steps" output (the 3rd applies to review-* only); read this file before rendering the final output and apply whichever rules apply:
 
 1. **Next-step output structure**: how "Next steps" commands and the "Task info" block present the task ID (placeholders / short-id lookup / fallback).
 2. **Agent output trailing line (Completed at)**: the **very last line** of user-facing output, **independent of the "Next steps" block**, applying to normal / error / early-return paths alike.
+3. **Pending human-decision pre-block**: applies only to `review-analysis` / `review-plan` / `review-code` when this stage has pending rulings (`{h} > 0`) — expand the pending items before the "Next steps" commands and prompt to resolve them first.
 
 ## Placeholder semantics
 
@@ -60,3 +61,27 @@ Completed at: YYYY-MM-DD HH:mm:ss
 - Value command (local timezone, no offset): `date "+%Y-%m-%d %H:%M:%S"`
 - Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the env-blocked reminder), the completion line goes after that reminder.
 - This line is for terminal scanning only; it is never written to any artifact file or Issue/PR comment. The single source of truth for completion time remains the Activity Log in task.md.
+
+## Pending human-decision pre-block (review-* only, when {h} > 0)
+
+This section is a **third standalone rule, co-equal with the two above**, used only by the "notify-user / report conclusion" step of `review-analysis` / `review-plan` / `review-code`.
+
+`{h}` has the same meaning as the count line in each review skill's `reference/output-templates.md`: the number of rows in task.md `## 审查分歧账本` (Review Disagreement Ledger) for **this stage** (`stage ∈ {analysis|plan|code}`) whose `status = needs-human-decision` — **pending items only, excluding rows already `human-decided`**.
+
+- **`{h} = 0`**: do not emit this block; render "Next steps" exactly as the selected output-templates scenario.
+- **`{h} > 0`**: insert the block below **before** the selected scenario's "Next steps - <stage>" commands; the next-stage commands are still listed after the block.
+
+```text
+⚠️ Pending human decisions ({h}) — please rule on each before continuing to the next stage:
+  - {ledger-id} ({stage}/{severity}): {summary}
+    Location: the matching row in task.md `## 审查分歧账本` · Evidence: {evidence}
+  …(one entry per status=needs-human-decision row of this stage in task.md `## 审查分歧账本`)
+
+To resolve:
+  1. In the task.md `## 人工裁决` section, record your ruling and rationale for each item above.
+  2. Flip the status of the matching row in `## 审查分歧账本` from `needs-human-decision` to `human-decided`.
+
+Note: until all those rows are flipped to `human-decided`, running the next-stage command directly will be blocked by gates such as complete-task (`needs-human-decision` is non-terminal). The next-stage commands are still listed below for use after the decisions are made.
+```
+
+Field values: `{ledger-id}` / `{stage}` / `{severity}` / `{evidence}` come from the same-named columns of the matching `## 审查分歧账本` row; `{summary}` comes from the artifact anchor referenced by `{evidence}` (e.g. the decision title at `plan.md#HD-1`), falling back to a one-line summary of the finding when no anchor title exists.

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -1,9 +1,10 @@
 # 下一步输出规则
 
-本文件定义 skill「告知用户 / 下一步」输出的两类**相互独立**的规则；渲染最终输出前先读取本文件并同时落实两者：
+本文件定义 skill「告知用户 / 下一步」输出的三类**相互独立**的规则（第 3 类仅 review-* 适用）；渲染最终输出前先读取本文件并落实其中适用的规则：
 
 1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
 2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
+3. **人工裁决待办前置块**：仅 `review-analysis` / `review-plan` / `review-code`，且本阶段存在待裁决项（`{h} > 0`）时适用——在「下一步」命令前展开待裁决项并提示先完成裁决。
 
 ## 占位符语义
 
@@ -60,3 +61,27 @@ Completed at: YYYY-MM-DD HH:mm:ss
 - 取值命令（本地时区、不带偏移）：`date "+%Y-%m-%d %H:%M:%S"`
 - 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 env-blocked 提醒），收尾行排在该提醒行之后。
 - 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。
+
+## 人工裁决待办前置块（review-* 专用，{h} > 0 时）
+
+本节是与上面两类规则**并列的第三类独立规则**，仅 `review-analysis` / `review-plan` / `review-code` 的「向用户汇报结论」步骤使用。
+
+`{h}` 含义与各 review 技能 `reference/output-templates.md` 计数行一致：task.md `## 审查分歧账本` 中**本阶段**（`stage ∈ {analysis|plan|code}`）`status = needs-human-decision` 的行数——**只含待裁决项，不含已 `human-decided`**。
+
+- **`{h} = 0`**：不输出本块，「下一步」按 output-templates 选定场景原样渲染。
+- **`{h} > 0`**：在选定场景的「下一步 - <阶段>」命令**之前**插入下面的块；下一阶段命令仍照常列在块之后。
+
+```text
+⚠️ 待人工裁决（{h} 项）—— 请先逐项裁决，再继续下一阶段：
+  - {ledger-id}（{stage}/{severity}）：{摘要}
+    位置：task.md `## 审查分歧账本` 对应行 · 证据：{evidence}
+  …（task.md `## 审查分歧账本` 中本阶段每个 status=needs-human-decision 行一条）
+
+完成裁决：
+  1. 在 task.md `## 人工裁决` 段，逐项记录你对上述裁决项的裁定与理由。
+  2. 把 `## 审查分歧账本` 中对应行的 status 由 `needs-human-decision` 翻为 `human-decided`。
+
+说明：在上述行全部翻为 `human-decided` 之前，直接执行下一阶段命令会被 complete-task 等 gate 拦截（`needs-human-decision` 为非终态）。下一阶段命令仍列在下方，供裁决完成后使用。
+```
+
+字段取值：`{ledger-id}` / `{stage}` / `{severity}` / `{evidence}` 直接取自 `## 审查分歧账本` 对应行的同名列；`{摘要}` 取自 `{evidence}` 指向的产物锚点条目（如 `plan.md#HD-1` 的决策标题），无锚点标题时用该 finding 的一句话概述。

package/templates/.agents/rules/task-management.en.md

@@ -52,6 +52,8 @@ Map user intent to the corresponding workflow command:
 
 **Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.
 
+**Human counts** (`ai task log`): review step rows fold two human counts into the NOTE verdict text, comma-separated, right after `blockers/major/minor`, localized to the task language (English `Manual-verify: {e}, Human-decision: {h}`; Chinese `人工校验点：{e}, 人工裁决：{h}`). `Human-decision` (`{h}`) maps canonical step prefixes (`Review Analysis` / `Review Plan` / `Review Code`) to `analysis` / `plan` / `code`, then counts current rows in `## Review Disagreement Ledger` / `## 审查分歧账本` for that stage with `status ∈ {needs-human-decision, human-decided}`. `Manual-verify` (`{e}`) parses `(+ {n} env-blocked)` from the review done note (de-duplicated from the display), defaulting to `0`. Non-review rows carry no human counts.
+
 **Gate** (`checkActivityLog`): when computing the "latest action / freshness" it skips `[started]` lines (ascending-order and format checks still cover every line), so a started marker never satisfies a skill's `expected_action_pattern`.
 
 **Skills that write started**: every workflow skill that **appends entries to a task's `## Activity Log`** writes started, so the STARTED column stays uniformly complete across the whole `ai task log` table. Two forms, depending on whether task.md already exists:

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

@@ -56,6 +56,8 @@
 
 **配对与渲染**（`ai task log`）：按 `{基名}` 把 started 与其后最近的同名 done 配成一行（同基名多次执行按时间升序 FIFO 配对）。STARTED 列显示 started 时间、DONE 列显示 done 时间；只有 started 无 done = 进行中（DONE 显示 `(in progress)`）；只有 done 无 started（历史日志）= 单态完成行。三种形态都合法、不报错。
 
+**人工计数**（`ai task log`）：审查步骤行把两项人工计数并入 NOTE 的 verdict 文本，逗号分隔、紧随 `blockers/major/minor`，按 task 语言本地化（中文 `人工校验点：{e}, 人工裁决：{h}`；英文 `Manual-verify: {e}, Human-decision: {h}`）。`人工裁决`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`人工校验点`（`{e}`）解析 review done note 中的 `(+ {n} env-blocked)`（解析后从展示中去重），缺失为 `0`。非审查步骤不附加人工计数。
+
 **gate**（`checkActivityLog`）：计算「最新 action / freshness」时跳过 `[started]` 行（升序与格式校验仍覆盖全部行），故 started 标记不会污染各 SKILL 的 `expected_action_pattern`。
 
 **写 started 的 SKILL**：所有**会向某个任务的 `## 活动日志` 追加条目**的工作流 SKILL 都写 started，保证 `ai task log` 整张表的 STARTED 列一致完整。两种写法按技能是否已有 task.md 区分：

package/templates/.agents/skills/analyze-task/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: analyze-task
-description: "Analyze a task and produce a requirements document"
+description: >
+  Analyze a task and produce a requirements document.
+  Use when you need to understand a task's requirements, scope, and risks before designing a solution.
 ---
 
 # Analyze Task

package/templates/.agents/skills/analyze-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: analyze-task
-description: "分析任务并输出需求分析文档"
+description: >
+  分析任务并输出需求分析文档。
+  当需要在动手设计前厘清某个任务的需求、影响范围与风险时使用。
 ---
 
 # 分析任务

package/templates/.agents/skills/archive-tasks/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: archive-tasks
-description: "Archive completed tasks into a date-organized workspace directory"
+description: >
+  Archive completed tasks into a date-organized workspace directory.
+  Use when completed tasks have accumulated and you want to tidy them into the date-organized archive.
 ---
 
 # Archive Completed Tasks

package/templates/.agents/skills/archive-tasks/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: archive-tasks
-description: "归档已完成任务到按日期组织的目录"
+description: >
+  归档已完成任务到按日期组织的目录。
+  当已完成任务在 completed 目录堆积、需要整理归档时使用。
 ---
 
 # 归档已完成任务

package/templates/.agents/skills/block-task/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: block-task
-description: "Mark a task as blocked and record the reason"
+description: >
+  Mark a task as blocked and record the reason.
+  Use when a task cannot proceed because of an external blocker and you need to park it with a reason.
 ---
 
 # Block Task

package/templates/.agents/skills/block-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: block-task
-description: "标记任务为阻塞状态并记录原因"
+description: >
+  标记任务为阻塞状态并记录原因。
+  当任务因外部阻塞无法推进、需要挂起并记录原因时使用。
 ---
 
 # 标记任务阻塞

package/templates/.agents/skills/cancel-task/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: cancel-task
-description: "Cancel an unneeded task and move it"
+description: >
+  Cancel an unneeded task and move it.
+  Use when a task is no longer needed and should be dropped from active work.
 ---
 
 # Cancel Task

package/templates/.agents/skills/cancel-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: cancel-task
-description: "取消不再需要的任务并转移"
+description: >
+  取消不再需要的任务并转移。
+  当某个任务不再需要、应从 active 工作中撤下时使用。
 ---
 
 # 取消任务

package/templates/.agents/skills/check-task/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: check-task
-description: "Check a task's current status and progress"
+description: >
+  Check a task's current status and progress.
+  Use when you want a quick view of a task's current status and progress.
 ---
 
 # Check Task Status
@@ -8,7 +10,7 @@ description: "Check a task's current status and progress"
 ## Boundary / Critical Rules
 
 - This skill is **read-only** -- do not modify any files
-- Always check the active, blocked, and completed directories
+- Mechanical facts (frontmatter metadata, artifact grouping, git/platform state, and locating the task across the active, blocked, and completed directories) are delegated to the deterministic `ai task status` command. This skill only adds the semantic layer the CLI cannot produce: workflow-stage interpretation, review-verdict parsing, and the next-step recommendation.
 
 ## Task id short ref
 
@@ -16,96 +18,43 @@ description: "Check a task's current status and progress"
 
 ## Steps
 
-### 1. Locate Task
+### 1. Gather Facts via `ai task status`
 
-Search for the task in this priority order:
-1. `.agents/workspace/active/{task-id}/task.md`
-2. `.agents/workspace/blocked/{task-id}/task.md`
-3. `.agents/workspace/completed/{task-id}/task.md`
+Run the deterministic CLI to collect every mechanical fact, and use its stdout as the factual base of your report:
 
-Note: `{task-id}` format is `TASK-{yyyyMMdd-HHmmss}`, for example `TASK-20260306-143022`
-
-If the task is not found in any directory, prompt "Task {task-id} not found".
-
-### 2. Read Task Metadata
+```bash
+ai task status {task-id}
+```
 
-Extract from `task.md`:
-- `id`, `title`, `type`, `status`, `workflow`
-- `current_step`, `assigned_to`
-- `created_at`, `updated_at`
-- `issue_number`, `pr_number` (if applicable)
+The command resolves the task across the active, blocked, and completed directories and prints five sections: the task header (`id`, short id, title), `Metadata` (frontmatter fields), `Artifacts` (files grouped by workflow stage), `Git` (branch match, uncommitted count, ahead/behind), and `Platform` (Issue/PR state). Treat that output as authoritative -- do not re-derive any of it by hand.
 
-### 3. Inspect Context Files
+Fallbacks:
+- If the command is unavailable (e.g. `ai` is not on PATH or `dist/` is not built) or exits non-zero, fall back to a degraded read: show the `task.md` frontmatter and `ls` the task directory, and tell the user the output is degraded (suggest building or installing the CLI, e.g. `ai init`).
+- If the task is not found in any directory, prompt "Task {task-id} not found".
 
-Scan and record the existence, round, and status of these artifact types:
-- `analysis.md`, `analysis-r{N}.md` - Requirement analysis
-- `plan.md`, `plan-r{N}.md` - Technical plan
-- `code.md`, `code-r2.md`, ... - Code reports
-- `review-analysis.md`, `review-analysis-r{N}.md` - Requirement analysis review reports
-- `review-plan.md`, `review-plan-r{N}.md` - Technical plan review reports
-- `review-code.md`, `review-code-r{N}.md` - Code review reports
+### 2. Interpret Workflow Stage & Review Verdicts
 
-For versioned artifacts (`analysis`, `review-analysis`, `plan`, `review-plan`, `code`, `review-code`):
-- Scan all versioned files of the same artifact type in the task directory
-- Record the latest round, latest file path, and total number of rounds for each artifact type
-- If the latest round is recorded in `task.md` Activity Log, cross-check it against the actual file when possible
+This is the semantic layer the CLI does not produce. Using the `Artifacts` groups from step 1 and the Activity Log in `task.md`:
 
-### 4. Output Status Report
+- Map each workflow stage to a status indicator plus its latest artifact and round:
+  - `[done]` - step completed
+  - `[current]` - currently in progress
+  - `[pending]` - not started yet
+  - `[blocked]` - blocked
+  - `[skipped]` - skipped
+- For the latest review artifact of each stage (`review-analysis`, `review-plan`, `review-code`), read the report body and parse its conclusion: the overall verdict (Approved / Changes Requested / Rejected) and the blocker / major / minor counts. The CLI does not parse review bodies, so this reading is required to choose the next action in step 3.
 
-Format the status report with a clear structure and status indicators:
+Present the workflow progress as an overlay on top of the CLI output, marking the latest round and the parsed review verdict, for example:
 
 ```
-Task status: {task-id} (short id {task-ref})
-=======================
-
-Basic info:
-- Title: {title}
-- Type: {type}
-- Status: {status}
-- Workflow: {workflow}
-- Assigned to: {assigned_to}
-- Created at: {created_at}
-- Updated at: {updated_at}
-
 Workflow progress:
-  [done]       Requirement Analysis  analysis-r2.md (Round 2, latest)
-  [done]       Analysis Review       review-analysis.md (Round 1, latest)
-  [done]       Technical Design      plan.md (Round 1)
-  [done]       Plan Review           review-plan.md (Round 1, latest)
-  [current]    Code                  code.md (Round 1)
-  [pending]    Code Review           review-code.md (Round 1 will be created next)
-  [pending]    Final Commit
-
-Context files:
-- analysis.md:           Exists (Round 1)
-- analysis-r2.md:        Exists (Round 2, latest)
-- review-analysis.md:    Exists (Round 1, latest)
-- plan.md:               Exists (Round 1, latest)
-- review-plan.md:        Exists (Round 1, latest)
-- code.md:               Exists (Round 1, latest)
-- review-code.md:        Not started
-
-If multiple rounds exist, show all rounds and mark the latest, for example:
-- plan.md:             Exists (Round 1)
-- plan-r2.md:          Exists (Round 2, latest)
-- review-plan.md:      Exists (Round 1)
-- code.md:             Exists (Round 1)
-- code-r2.md:          Exists (Round 2, latest)
-- review-code.md:      Exists (Round 1)
-- review-code-r2.md:   Exists (Round 2, latest)
-
-Next step:
-  Complete implementation, then run code review
+  [done]       Requirement Analysis  analysis.md (Round 1, latest)
+  [done]       Analysis Review       review-analysis.md (Round 1, latest, Approved)
+  [current]    Technical Design      plan.md (Round 1)
+  [pending]    Plan Review
 ```
 
-**Status indicators**:
-- `[done]` - Step completed
-- `[current]` - Currently in progress
-- `[pending]` - Not started yet
-- `[blocked]` - Blocked
-- `[skipped]` - Skipped
-
-### 5. Recommend Next Action
+### 3. Recommend Next Action
 
 Recommend the appropriate next skill based on the current workflow state. You must show command formats for all TUI columns in the table below, not just the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name).
 
@@ -144,6 +93,6 @@ Recommend the appropriate next skill based on the current workflow state. You mu
 ## Notes
 
 1. **Read-only**: This skill only reads and reports -- it does not modify files
-2. **Multi-directory search**: Always check active, blocked, and completed
+2. **CLI delegation**: mechanical facts (metadata, artifact grouping, git/platform state, multi-directory location) come from `ai task status`; this skill adds the semantic interpretation on top
 3. **Quick reference**: Use this skill any time you need to see where a task is in the workflow
-4. **Versioned artifacts**: `analysis`, `review-analysis`, `plan`, `review-plan`, `code`, and `review-code` must all report the actual round, not only the base filename
+4. **Versioned artifacts**: `ai task status` groups the actual artifact rounds; the semantic layer must still report the latest review verdict for `review-analysis`, `review-plan`, and `review-code`

package/templates/.agents/skills/check-task/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: check-task
-description: "查看任务的当前状态和进度"
+description: >
+  查看任务的当前状态和进度。
+  当想快速查看某个任务当前状态与进度时使用。
 ---
 
 # 查看任务状态
@@ -8,103 +10,51 @@ description: "查看任务的当前状态和进度"
 ## 行为边界 / 关键规则
 
 - 本技能是**只读**操作 —— 不修改任何文件
-- 始终检查 active、blocked 和 completed 目录
+- 机械数据（frontmatter 元数据、产物分组、Git/Platform 状态，以及跨 active、blocked、completed 三目录定位任务）一律委托给确定性的 `ai task status` 命令。本技能只负责 CLI 无法产出的语义层：工作流阶段解读、审查结论解析、下一步建议。
 
 ## 任务入参短号别名
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
 ## 执行步骤
-### 1. 查找任务
 
-按以下优先顺序搜索任务：
-1. `.agents/workspace/active/{task-id}/task.md`
-2. `.agents/workspace/blocked/{task-id}/task.md`
-3. `.agents/workspace/completed/{task-id}/task.md`
+### 1. 通过 `ai task status` 收集事实
 
-注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
+运行确定性 CLI 收集全部机械数据，并以其 stdout 作为状态报告的事实基底：
 
-如果在任何目录中都未找到，提示 "Task {task-id} not found"。
-
-### 2. 读取任务元数据
+```bash
+ai task status {task-id}
+```
 
-从 `task.md` 中提取：
-- `id`、`title`、`type`、`status`、`workflow`
-- `current_step`、`assigned_to`
-- `created_at`、`updated_at`
-- `issue_number`、`pr_number`（如适用）
+该命令会跨 active、blocked、completed 三目录解析任务，并输出五段：任务头（`id`、短号、标题）、`Metadata`（frontmatter 字段）、`Artifacts`（按工作流阶段分组的产物）、`Git`（分支匹配、未提交数、ahead/behind）、`Platform`（Issue/PR 状态）。把该输出视为权威事实 —— 不要再手工复述其中任何内容。
 
-### 3. 检查上下文文件
+降级处理：
+- 若命令不可用（如 `ai` 不在 PATH 或 `dist/` 未构建）或非零退出，回退到降级读取：展示 `task.md` frontmatter 并 `ls` 任务目录，同时告知用户本次为降级输出（建议先构建或安装 CLI，如 `ai init`）。
+- 若在任何目录都未找到任务，提示 "Task {task-id} not found"。
 
-按产物类型扫描并记录以下文件的存在、轮次和状态：
-- `analysis.md`、`analysis-r{N}.md` - 需求分析
-- `plan.md`、`plan-r{N}.md` - 技术方案
-- `code.md`、`code-r2.md`、... - 实现报告
-- `review-analysis.md`、`review-analysis-r{N}.md` - 需求分析审查报告
-- `review-plan.md`、`review-plan-r{N}.md` - 技术方案审查报告
-- `review-code.md`、`review-code-r{N}.md` - 代码审查报告
+### 2. 解读工作流阶段与审查结论
 
-对于版本化产物（`analysis`、`review-analysis`、`plan`、`review-plan`、`code`、`review-code`）：
-- 扫描任务目录中的所有同类版本化文件
-- 记录每类产物的最新轮次、最新文件路径和总轮次数
-- 如果 `task.md` 的 Activity Log 记录了最新轮次，优先核对其与实际文件是否一致
+这是 CLI 不产出的语义层。基于步骤 1 的 `Artifacts` 分组与 `task.md` 的活动日志：
 
-### 4. 输出状态报告
+- 把每个工作流阶段映射为状态指示器，并标注其最新产物与轮次：
+  - `[done]` - 步骤已完成
+  - `[current]` - 当前进行中
+  - `[pending]` - 尚未开始
+  - `[blocked]` - 被阻塞
+  - `[skipped]` - 已跳过
+- 对各阶段最新的审查产物（`review-analysis`、`review-plan`、`review-code`），读取报告正文并解析结论：总体结论（通过 / 需要修改 / 拒绝）与阻塞项 / 主要问题 / 次要问题计数。CLI 不解析审查正文，因此这一步是步骤 3 选择下一步操作的必要输入。
 
-以清晰的结构和状态指示器格式化输出：
+把工作流进度作为 CLI 输出之上的叠加层呈现，标注最新轮次与解析出的审查结论，例如：
 
 ```
-任务状态：{task-id}（短号 {task-ref}）
-=======================
-
-基本信息：
-- 标题：{title}
-- 类型：{type}
-- 状态：{status}
-- 工作流：{workflow}
-- 分配给：{assigned_to}
-- 创建时间：{created_at}
-- 更新时间：{updated_at}
-
 工作流进度：
-  [已完成]    需求分析        analysis-r2.md (Round 2, latest)
-  [已完成]    需求分析审查    review-analysis.md (Round 1, latest)
-  [已完成]    技术设计        plan.md (Round 1)
-  [已完成]    技术方案审查    review-plan.md (Round 1, latest)
-  [进行中]    实现            code.md (Round 1)
-  [待处理]    代码审查        review-code.md (Round 1 will be created next)
-  [待处理]    最终提交
-
-上下文文件：
-- analysis.md：           已存在 (Round 1)
-- analysis-r2.md：        已存在 (Round 2, latest)
-- review-analysis.md：    已存在 (Round 1, latest)
-- plan.md：               已存在 (Round 1, latest)
-- review-plan.md：        已存在 (Round 1, latest)
-- code.md：               已存在 (Round 1, latest)
-- review-code.md：        未开始
-
-如果存在多轮产物，显示所有轮次，并标记最新版本，例如：
-- plan.md：             已存在 (Round 1)
-- plan-r2.md：          已存在 (Round 2, latest)
-- review-plan.md：      已存在 (Round 1)
-- code.md：             已存在 (Round 1)
-- code-r2.md：          已存在 (Round 2, latest)
-- review-code.md：      已存在 (Round 1)
-- review-code-r2.md：   已存在 (Round 2, latest)
-
-下一步：
-  完成实现，然后执行代码审查
+  [done]       需求分析        analysis.md (Round 1, latest)
+  [done]       需求分析审查    review-analysis.md (Round 1, latest, 通过)
+  [current]    技术设计        plan.md (Round 1)
+  [pending]    技术方案审查
 ```
 
-**状态指示器**：
-- `[done]` - 步骤已完成
-- `[current]` - 当前进行中
-- `[pending]` - 尚未开始
-- `[blocked]` - 被阻塞
-- `[skipped]` - 已跳过
-
-### 5. 建议下一步操作
+### 3. 建议下一步操作
 
 根据当前工作流状态，建议合适的下一个技能。必须展示下表中所有 TUI 列的命令格式，不要只展示当前 AI 代理对应的列。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）：
 
@@ -143,6 +93,6 @@ description: "查看任务的当前状态和进度"
 ## 注意事项
 
 1. **只读**：本技能仅读取和报告 —— 不修改任何文件
-2. **多目录搜索**：始终检查 active、blocked 和 completed 目录
+2. **CLI 委托**：机械数据（元数据、产物分组、Git/Platform 状态、多目录定位）来自 `ai task status`；本技能在其之上叠加语义解读
 3. **快速参考**：随时可以使用本技能检查任务在工作流中的位置
-4. **版本化产物**：`analysis`、`review-analysis`、`plan`、`review-plan`、`code`、`review-code` 都需要报告实际轮次，而不是只报告固定文件名
+4. **版本化产物**：`ai task status` 已按实际轮次分组产物；语义层仍需报告 `review-analysis`、`review-plan`、`review-code` 的最新审查结论

package/templates/.agents/skills/close-codescan/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: close-codescan
-description: "Close a Code Scanning alert with a documented reason"
+description: >
+  Close a Code Scanning alert with a documented reason.
+  Use when a Code Scanning alert has been handled or dismissed and needs closing with a reason.
 ---
 
 # Dismiss Code Scanning Alert

package/templates/.agents/skills/close-codescan/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: close-codescan
-description: "关闭 Code Scanning 告警并记录理由"
+description: >
+  关闭 Code Scanning 告警并记录理由。
+  当某条 Code Scanning 告警已处理或需按理由关闭时使用。
 ---
 
 # 关闭 Code Scanning 告警