@fitlab-ai/agent-infra 0.7.5 → 0.7.7

package/templates/.agents/skills/create-pr/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: create-pr
-description: "Create a Pull Request to a target branch"
+description: >
+  Create a Pull Request to a target branch.
+  Use when changes are committed and you need to open a Pull Request for review.
 ---
 
 # Create Pull Request
@@ -15,6 +17,16 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
+## Step Start: Write the started Marker
+
+After the pre-flight gate and prerequisites pass and before this step's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`). Only write it when an associated `{task-id}` / task.md exists:
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create PR [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written on completion onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Execution Flow
 
 ### Pre-gate: Project-level PR Flow Check
@@ -128,7 +140,16 @@ Next step - Watch PR checks (auto self-heal until required checks are green):
   - Codex CLI: $watch-pr {task-ref}
 ```
 
-Once green, `watch-pr` then guides toward `complete-task {task-ref}`.
+Alternatively, to skip CI monitoring and archive the task right away, use `complete-task` instead:
+
+```
+Next step (alternative) - Skip monitoring and archive the task directly:
+  - Claude Code / OpenCode: /complete-task {task-ref}
+  - Gemini CLI: /agent-infra:complete-task {task-ref}
+  - Codex CLI: $complete-task {task-ref}
+```
+
+`watch-pr` is the primary path; once checks are green it guides you toward `complete-task {task-ref}`. Run the `complete-task` block above directly only when you intend to skip monitoring — the two are not equivalent.
 
 ## Notes
 

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

@@ -1,6 +1,8 @@
 ---
 name: create-pr
-description: "创建 Pull Request 到目标分支"
+description: >
+  创建 Pull Request 到目标分支。
+  当变更已提交、需要发起 Pull Request 评审时使用。
 ---
 
 # 创建 Pull Request
@@ -15,6 +17,16 @@ description: "创建 Pull Request 到目标分支"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+通过前置门控、确认前置条件后、本步骤第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）。仅当存在关联 `{task-id}` / task.md 时写入：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create PR [started]** by {agent} — started
+```
+
+`ai task log` 会把它与完成时写入的 done 条目配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行流程
 
 ### 前置门控：项目级 PR 流程检查
@@ -128,7 +140,16 @@ node .agents/scripts/validate-artifact.js gate create-pr .agents/workspace/activ
   - Codex CLI：$watch-pr {task-ref}
 ```
 
-`watch-pr` 全绿后会再引导 `complete-task {task-ref}`。
+或者，若想跳过 CI 监控、直接归档任务，改用 `complete-task`：
+
+```
+下一步（备选）- 跳过监控、直接归档任务：
+  - Claude Code / OpenCode：/complete-task {task-ref}
+  - Gemini CLI：/agent-infra:complete-task {task-ref}
+  - Codex CLI：$complete-task {task-ref}
+```
+
+`watch-pr` 为主路径，全绿后会再引导 `complete-task {task-ref}`；上面的 `complete-task` 备选块仅用于跳过 CI 监控、直接归档——两者并不等价。
 
 ## 注意事项
 

package/templates/.agents/skills/create-release-note/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: create-release-note
-description: "Generate release notes from PRs and commits"
+description: >
+  Generate release notes from PRs and commits.
+  Use when preparing a release and you need notes compiled from PRs and commits.
 ---
 
 # Create Release Notes
@@ -160,7 +162,21 @@ Ask:
 
 ### 9. Publish the Release Notes (If Confirmed)
 
-Write the notes by following the "Publish the Release Notes" command in `.agents/rules/release-commands.md` (it updates the Release already created and published by the release workflow, falling back to creating it if missing).
+9.1 Write the generated notes to a temp file **outside the working tree** so no uncommitted artifact is left behind in the repo (do not write into `.agents/workspace/` or any version-controlled directory):
+
+```bash
+NOTES_FILE="$(mktemp "${TMPDIR:-/tmp}/agent-infra-release-notes.XXXXXX")"
+```
+
+Write the notes content to `$NOTES_FILE`.
+
+9.2 Publish by following the "Publish the Release Notes" command in `.agents/rules/release-commands.md` (use `$NOTES_FILE` for `{notes-file}`; it updates the Release already created and published by the release workflow, falling back to creating it if missing).
+
+9.3 Remove the temp file whether publishing succeeds or fails:
+
+```bash
+rm -f "$NOTES_FILE"
+```
 
 Output:
 ```
@@ -179,6 +195,7 @@ The notes have been written to the Release. Edit further at the URL above if nee
 2. **Tags must exist**: Run the release skill first to create tags
 3. **Release auto-published**: the `v{version}` Release is created and published by the release workflow (the upload target for Homebrew bottles); this skill writes/refreshes the notes on that Release
 4. **Classification accuracy**: Auto-classification is based on title/scope/files; complex PRs may need manual adjustment
+5. **No leftover artifacts**: Always write notes to a temp file outside the working tree (`mktemp`) and delete it after publishing; never write into the repo directory
 
 ## Error Handling
 

package/templates/.agents/skills/create-release-note/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: create-release-note
-description: "从 PR 和 commit 生成版本发布说明"
+description: >
+  从 PR 和 commit 生成版本发布说明。
+  当准备发版、需要从 PR 与 commit 汇总发布说明时使用。
 ---
 
 # 创建发布说明
@@ -160,7 +162,21 @@ git log v<prev-version>..v<version> \
 
 ### 9. 发布 Release notes（如确认）
 
-按 `.agents/rules/release-commands.md` 的「发布 Release notes」命令执行（写入已由 release 工作流自动创建/发布的 Release；不存在时兜底创建）。
+9.1 把生成的 notes 写入**工作树之外**的临时文件，避免在仓库残留未提交产物（不要写入 `.agents/workspace/` 或任何受版本控制的目录）：
+
+```bash
+NOTES_FILE="$(mktemp "${TMPDIR:-/tmp}/agent-infra-release-notes.XXXXXX")"
+```
+
+把 notes 内容写入 `$NOTES_FILE`。
+
+9.2 按 `.agents/rules/release-commands.md` 的「发布 Release notes」命令执行（命令中的 `{notes-file}` 用 `$NOTES_FILE`；写入已由 release 工作流自动创建/发布的 Release，不存在时兜底创建）。
+
+9.3 无论发布成功或失败，都删除临时文件：
+
+```bash
+rm -f "$NOTES_FILE"
+```
 
 输出：
 ```
@@ -179,6 +195,7 @@ Release notes 已更新。
 2. **标签必须存在**：先执行 release 技能创建标签
 3. **Release 已自动发布**：`v{version}` 的 Release 由 release 工作流自动创建并发布（给 Homebrew bottle 提供上传落点）；本技能往该 Release 写入/刷新 notes
 4. **分类准确性**：自动分类基于标题/scope/文件；复杂的 PR 可能需要手动调整
+5. **不留残留产物**：notes 一律写入工作树之外的临时文件（`mktemp`）并在发布后删除，禁止写入仓库目录
 
 ## 错误处理
 

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

@@ -1,6 +1,8 @@
 ---
 name: create-task
-description: "Create a task from a natural-language description"
+description: >
+  Create a task from a natural-language description.
+  Use when you want to turn a free-form idea or request into a tracked task.
 ---
 
 # Create Task
@@ -26,6 +28,17 @@ Version stamp rule: when creating or updating `task.md` frontmatter, read `.agen
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
+## Step Start: Capture the Start Time
+
+This skill **creates** task.md, so there is no file to write at the start. Capture `started_at` in memory before running (`date "+%Y-%m-%d %H:%M:%S%:z"`); when writing the Activity Log at the end, **append both lines at once** — the started line uses `started_at`, the done line uses the completion time, both sharing the base action (started line action gets a ` [started]` suffix, note `started`):
+
+```
+- {started_at} — **Create Task [started]** by {agent} — started
+- {done_at} — **Create Task** by {agent} — {completion summary}
+```
+
+`ai task log` pairs the two by base action onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Steps
 
 ### 1. Parse the User Description

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

@@ -1,6 +1,8 @@
 ---
 name: create-task
-description: "根据自然语言描述创建任务"
+description: >
+  根据自然语言描述创建任务。
+  当想把一段自然语言的想法或需求落为受跟踪的任务时使用。
 ---
 
 # 创建任务
@@ -26,6 +28,17 @@ description: "根据自然语言描述创建任务"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：记录开始时间
+
+本技能会**创建** task.md，开始时尚无文件可写。先在内存记录开始时间 `started_at`（`date "+%Y-%m-%d %H:%M:%S%:z"`）；在最后写活动日志时**一次性补两条**——started 行用 `started_at`、done 行用完成时间，二者同基名（started 行 action 加 ` [started]` 后缀、note 用 `started`）：
+
+```
+- {started_at} — **Create Task [started]** by {agent} — started
+- {done_at} — **Create Task** by {agent} — {完成说明}
+```
+
+`ai task log` 会按基名把两条配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 解析用户描述
 
@@ -172,7 +185,7 @@ node .agents/scripts/validate-artifact.js gate create-task .agents/workspace/act
 
 下一步 - 执行需求分析：
   - Claude Code / OpenCode：/analyze-task {task-ref}
-  - Gemini CLI：/{{project}}:analyze-task {task-ref}
+  - Gemini CLI：/agent-infra:analyze-task {task-ref}
   - Codex CLI：$analyze-task {task-ref}
 ```
 
@@ -191,7 +204,7 @@ node .agents/scripts/validate-artifact.js gate create-task .agents/workspace/act
 
 下一步 - 执行需求分析：
   - Claude Code / OpenCode：/analyze-task {task-ref}
-  - Gemini CLI：/{{project}}:analyze-task {task-ref}
+  - Gemini CLI：/agent-infra:analyze-task {task-ref}
   - Codex CLI：$analyze-task {task-ref}
 ```
 
@@ -215,7 +228,7 @@ Issue 创建失败：
 
 下一步 - 执行需求分析：
   - Claude Code / OpenCode：/analyze-task {task-ref}
-  - Gemini CLI：/{{project}}:analyze-task {task-ref}
+  - Gemini CLI：/agent-infra:analyze-task {task-ref}
   - Codex CLI：$analyze-task {task-ref}
 
 后续如需平台同步：修复认证/网络/模板问题后，可按 `.agents/rules/create-issue.md` 对当前任务手动执行一次 Issue 创建；或手动创建/查找 Issue，并把 `issue_number` 写入 task.md，后续技能会接管级联同步。

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

@@ -1,6 +1,8 @@
 ---
 name: import-codescan
-description: "Import a Code Scanning alert and create a remediation task"
+description: >
+  Import a Code Scanning alert and create a remediation task.
+  Use when a Code Scanning alert needs to become a tracked remediation task.
 ---
 
 # Import Code Scanning Alert
@@ -17,6 +19,17 @@ Import the specified Code Scanning (CodeQL) alert and create a remediation task.
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
+## Step Start: Capture the Start Time
+
+This skill **creates** task.md, so there is no file to write at the start. Capture `started_at` in memory before running (`date "+%Y-%m-%d %H:%M:%S%:z"`); when writing the Activity Log at the end, **append both lines at once** — the started line uses `started_at`, the done line uses the completion time, both sharing the base action (started line action gets a ` [started]` suffix, note `started`):
+
+```
+- {started_at} — **Import Codescan [started]** by {agent} — started
+- {done_at} — **Import Codescan** by {agent} — {completion summary}
+```
+
+`ai task log` pairs the two by base action onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Execution Flow
 
 ### 1. Retrieve Alert Information

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

@@ -1,6 +1,8 @@
 ---
 name: import-codescan
-description: "导入 Code Scanning 告警并创建修复任务"
+description: >
+  导入 Code Scanning 告警并创建修复任务。
+  当某条 Code Scanning 告警需要转为受跟踪的修复任务时使用。
 ---
 
 # 导入 Code Scanning 告警
@@ -17,6 +19,17 @@ description: "导入 Code Scanning 告警并创建修复任务"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：记录开始时间
+
+本技能会**创建** task.md，开始时尚无文件可写。先在内存记录开始时间 `started_at`（`date "+%Y-%m-%d %H:%M:%S%:z"`）；在最后写活动日志时**一次性补两条**——started 行用 `started_at`、done 行用完成时间，二者同基名（started 行 action 加 ` [started]` 后缀、note 用 `started`）：
+
+```
+- {started_at} — **Import Codescan [started]** by {agent} — started
+- {done_at} — **Import Codescan** by {agent} — {完成说明}
+```
+
+`ai task log` 会按基名把两条配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行流程
 
 ### 1. 获取告警信息

package/templates/.agents/skills/import-dependabot/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: import-dependabot
-description: "Import a Dependabot alert and create a remediation task"
+description: >
+  Import a Dependabot alert and create a remediation task.
+  Use when a Dependabot alert needs to become a tracked remediation task.
 ---
 
 # Import Dependabot Security Alert
@@ -17,6 +19,17 @@ Import the specified Dependabot security alert and create a remediation task.
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
+## Step Start: Capture the Start Time
+
+This skill **creates** task.md, so there is no file to write at the start. Capture `started_at` in memory before running (`date "+%Y-%m-%d %H:%M:%S%:z"`); when writing the Activity Log at the end, **append both lines at once** — the started line uses `started_at`, the done line uses the completion time, both sharing the base action (started line action gets a ` [started]` suffix, note `started`):
+
+```
+- {started_at} — **Import Dependabot [started]** by {agent} — started
+- {done_at} — **Import Dependabot** by {agent} — {completion summary}
+```
+
+`ai task log` pairs the two by base action onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Execution Flow
 
 ### 1. Retrieve Alert Information

package/templates/.agents/skills/import-dependabot/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: import-dependabot
-description: "导入 Dependabot 安全告警并创建修复任务"
+description: >
+  导入 Dependabot 安全告警并创建修复任务。
+  当某条 Dependabot 安全告警需要转为受跟踪的修复任务时使用。
 ---
 
 # 导入 Dependabot 安全告警
@@ -17,6 +19,17 @@ description: "导入 Dependabot 安全告警并创建修复任务"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：记录开始时间
+
+本技能会**创建** task.md，开始时尚无文件可写。先在内存记录开始时间 `started_at`（`date "+%Y-%m-%d %H:%M:%S%:z"`）；在最后写活动日志时**一次性补两条**——started 行用 `started_at`、done 行用完成时间，二者同基名（started 行 action 加 ` [started]` 后缀、note 用 `started`）：
+
+```
+- {started_at} — **Import Dependabot [started]** by {agent} — started
+- {done_at} — **Import Dependabot** by {agent} — {完成说明}
+```
+
+`ai task log` 会按基名把两条配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行流程
 
 ### 1. 获取告警信息

package/templates/.agents/skills/import-issue/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: import-issue
-description: "Import an Issue and create a task"
+description: >
+  Import an Issue and create a task.
+  Use when you want to start work from an existing Issue and track it locally.
 ---
 
 # Import Issue
@@ -17,6 +19,22 @@ Import the specified Issue and create a task. Argument: issue number.
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
+## Step Start: Capture the Start Time
+
+This skill **creates** task.md, so there is no file to write at the start. Capture `started_at` in memory before running (`date "+%Y-%m-%d %H:%M:%S%:z"`); when writing the Activity Log at the end, **append both lines at once** — the started line uses `started_at`, the done line uses the completion time, both sharing the base action (started line action gets a ` [started]` suffix, note `started`). The base action must match the actual import scenario:
+
+```
+# Scenario B: new Issue import
+- {started_at} — **Import Issue [started]** by {agent} — started
+- {done_at} — **Import Issue** by {agent} — {completion summary}
+
+# Scenario C: recovery from historical Issue comments
+- {started_at} — **Import Issue (Recovered) [started]** by {agent} — started
+- {done_at} — **Import Issue (Recovered)** by {agent} — {completion summary}
+```
+
+`ai task log` pairs the two by base action onto one row (in progress → done). See the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Execution Flow
 
 ### 1. Retrieve Issue Information
@@ -24,7 +42,22 @@ Import the specified Issue and create a task. Argument: issue number.
 Read `.agents/rules/issue-pr-commands.md` first, follow its prerequisite steps to complete authentication and code-hosting platform detection, then load the Issue data with its "Read an Issue" command.
 
 Extract: issue number, title, description, and labels.
-Use the Issue title as-is for the task title (preserve the Issue's original language).
+
+Derive the task title from the Issue title by stripping an optional single leading Conventional Commits prefix, following the contract below; preserve the rest of the description verbatim and in its original language. This fenced contract is the authoritative, language-neutral rule — keep it byte-for-byte identical across every `import-issue` variant:
+
+```
+# title-derivation-contract
+strip-prefix: type(scope):
+prefix-types: feat fix docs style refactor perf test build ci chore revert
+single-layer-only: true
+preserve-body-colon: true
+keep-when-no-prefix: true
+example-strip: "feat(meta): create-pr summary" => "create-pr summary"
+example-keep: "修复某问题" => "修复某问题"
+example-single-layer: "feat: add A: B" => "add A: B"
+```
+
+Strip only the first layer, and only when the leading token is a `prefix-types` value optionally followed by `(scope)` and a `!`, then `:` and at least one space; a colon inside the description is never a prefix.
 
 ### 2. Check for an Existing Task
 

package/templates/.agents/skills/import-issue/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: import-issue
-description: "从 Issue 导入并创建任务"
+description: >
+  从 Issue 导入并创建任务。
+  当想从既有 Issue 开工并在本地跟踪时使用。
 ---
 
 # 导入 Issue
@@ -17,6 +19,22 @@ description: "从 Issue 导入并创建任务"
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：记录开始时间
+
+本技能会**创建** task.md，开始时尚无文件可写。先在内存记录开始时间 `started_at`（`date "+%Y-%m-%d %H:%M:%S%:z"`）；在最后写活动日志时**一次性补两条**——started 行用 `started_at`、done 行用完成时间，二者同基名（started 行 action 加 ` [started]` 后缀、note 用 `started`）。基名必须跟实际导入场景一致：
+
+```
+# 场景 B：新 Issue 导入
+- {started_at} — **Import Issue [started]** by {agent} — started
+- {done_at} — **Import Issue** by {agent} — {完成说明}
+
+# 场景 C：从历史 Issue 评论恢复
+- {started_at} — **Import Issue (Recovered) [started]** by {agent} — started
+- {done_at} — **Import Issue (Recovered)** by {agent} — {完成说明}
+```
+
+`ai task log` 会按基名把两条配对成一行（进行中 → 已完成）。约定见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行流程
 
 ### 1. 获取 Issue 信息
@@ -24,7 +42,22 @@ description: "从 Issue 导入并创建任务"
 执行前先读取 `.agents/rules/issue-pr-commands.md`，并按其中的前置步骤完成认证和代码托管平台检测；随后按其中的 “读取 Issue” 命令获取 Issue 信息。
 
 提取：issue 编号、标题、描述、标签。
-任务标题直接使用 Issue 的原始标题（保持 Issue 标题的原始语言）。
+
+从 Issue 标题派生任务标题：按下方契约剥掉可选的单层前导 Conventional Commits 前缀，其余描述原文与原始语言保持不变。下方 fenced 契约是权威的、与语言无关的规则——在所有 `import-issue` 变体中保持逐字节一致：
+
+```
+# title-derivation-contract
+strip-prefix: type(scope):
+prefix-types: feat fix docs style refactor perf test build ci chore revert
+single-layer-only: true
+preserve-body-colon: true
+keep-when-no-prefix: true
+example-strip: "feat(meta): create-pr summary" => "create-pr summary"
+example-keep: "修复某问题" => "修复某问题"
+example-single-layer: "feat: add A: B" => "add A: B"
+```
+
+只剥第一层前缀，且仅当前导 token 是 `prefix-types` 之一、其后可带 `(scope)` 与 `!`，再接 `:` 和至少一个空格；描述正文中的冒号永远不算前缀。
 
 ### 2. 检查已有任务
 

package/templates/.agents/skills/init-labels/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: init-labels
-description: "Initialize the repository's standard labels taxonomy"
+description: >
+  Initialize the repository's standard labels taxonomy.
+  Use when setting up a repository and you need the standard label taxonomy created.
 ---
 
 # Initialize labels

package/templates/.agents/skills/init-labels/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: init-labels
-description: "初始化仓库的 labels 体系"
+description: >
+  初始化仓库的 labels 体系。
+  当初始化仓库、需要创建标准 label 体系时使用。
 ---
 
 # 初始化 labels

package/templates/.agents/skills/init-milestones/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: init-milestones
-description: "Initialize the repository's standard milestones taxonomy"
+description: >
+  Initialize the repository's standard milestones taxonomy.
+  Use when setting up a repository and you need the standard milestone taxonomy created.
 ---
 
 # Initialize milestones

package/templates/.agents/skills/init-milestones/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: init-milestones
-description: "初始化仓库的 milestones 体系"
+description: >
+  初始化仓库的 milestones 体系。
+  当初始化仓库、需要创建标准 milestone 体系时使用。
 ---
 
 # 初始化 milestones

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

@@ -1,6 +1,8 @@
 ---
 name: plan-task
-description: "Design a technical plan for a task"
+description: >
+  Design a technical plan for a task.
+  Use when a requirement is understood and you need a technical design before coding.
 ---
 
 # Design Technical Plan
@@ -31,6 +33,16 @@ Before the state check is complete, do not make external-state assertions such a
 
 > If `{task-id}` matches `^[#]?[0-9]+$` (bare numeric or `#`-prefixed), follow the "SKILL parameter resolver" section of `.agents/rules/task-short-id.md`; treat `{task-id}` as the resolved full `TASK-YYYYMMDD-HHMMSS` form for every downstream command.
 
+## Step Start: Write the started Marker
+
+After prerequisites pass and before this round's first artifact action, append a started marker to task.md `## Activity Log` (same base action as this round's done entry plus a ` [started]` suffix, note `started`):
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Plan Task (Round {N}) [started]** by {agent} — started
+```
+
+`ai task log` pairs it with the done entry written on completion (step 7) onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`.
+
 ## Steps
 
 ### 1. Verify Prerequisites
@@ -87,6 +99,8 @@ Follow the `technical-design` step in `.agents/workflows/feature-development.yam
 - [ ] Define the verification strategy (tests, manual checks)
 - [ ] Assess impact and risks
 
+When this round introduces a new key design decision, record it under `## Open Questions` according to `.agents/rules/no-mid-flow-questions.md` and write the matching `HD-` ledger row.
+
 **Design principles**:
 1. **Architectural soundness**: choose the structurally correct approach; diff size is not the primary criterion. Do not pile changes onto an unsound structure just to keep the diff small
 2. **Simplicity**: given a sound architecture, prefer the simplest approach and avoid over-engineering

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

@@ -1,6 +1,8 @@
 ---
 name: plan-task
-description: "为任务设计技术方案和实施计划"
+description: >
+  为任务设计技术方案和实施计划。
+  当需求已明确、需要在编码前形成技术方案时使用。
 ---
 
 # 设计技术方案
@@ -31,6 +33,16 @@ tail .agents/workspace/active/{task-id}/task.md
 
 > 如果 `{task-id}` 入参匹配 `^[#]?[0-9]+$`（裸数字或带 `#` 前缀），先读取 `.agents/rules/task-short-id.md` 的「SKILL 入参解析」段执行解析；后续命令视 `{task-id}` 为解析后的全长 `TASK-YYYYMMDD-HHMMSS` 形式。
 
+## 步骤开始：写入 started 标记
+
+确认前置条件后、本轮第一个产出动作之前，向 task.md `## 活动日志` 追加一条 started 标记（与本轮 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
+
+```
+- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Plan Task (Round {N}) [started]** by {agent} — started
+```
+
+`ai task log` 会把它与步骤完成时（步骤 7）写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。
+
 ## 执行步骤
 ### 1. 验证前置条件
 
@@ -86,6 +98,8 @@ tail .agents/workspace/active/{task-id}/task.md
 - [ ] 定义验证策略（测试、手动检查）
 - [ ] 评估方案的影响和风险
 
+遇到本轮新增的关键设计决策时，按 `.agents/rules/no-mid-flow-questions.md` 判据写入 `## 未决问题`，并回写 `HD-` 账本行。
+
 **设计原则**：
 1. **架构合理性**：选择结构正确的方案，改动大小不是首要依据。不要为了减少 diff 而在不合理的结构上叠加
 2. **简洁性**：在架构合理的前提下，优先选择最简方案，避免过度设计

package/templates/.agents/skills/post-release/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: post-release
-description: "Run post-release follow-up tasks"
+description: >
+  Run post-release follow-up tasks.
+  Use when a release has shipped and follow-up housekeeping is needed.
 ---
 
 # Post-release Tasks

package/templates/.agents/skills/post-release/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: post-release
-description: "执行版本发布后的后处理工作"
+description: >
+  执行版本发布后的后处理工作。
+  当版本已发布、需要执行发版后的收尾工作时使用。
 ---
 
 # 发布后处理

package/templates/.agents/skills/refine-title/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: refine-title
-description: "Rewrite an Issue or PR title in Conventional Commits format"
+description: >
+  Rewrite an Issue or PR title in Conventional Commits format.
+  Use when an Issue or PR title needs rewriting into Conventional Commits format.
 ---
 
 # Refine Title

package/templates/.agents/skills/refine-title/SKILL.zh-CN.md

@@ -1,6 +1,8 @@
 ---
 name: refine-title
-description: "重构 Issue/PR 标题为 Conventional Commits 格式"
+description: >
+  重构 Issue/PR 标题为 Conventional Commits 格式。
+  当某个 Issue/PR 标题需要改写为 Conventional Commits 格式时使用。
 ---
 
 # 重构标题

package/templates/.agents/skills/release/SKILL.en.md

@@ -1,6 +1,8 @@
 ---
 name: release
-description: "Run the version release workflow"
+description: >
+  Run the version release workflow.
+  Use when you are ready to cut and publish a new version.
 ---
 
 # Version Release