@fitlab-ai/agent-infra 0.5.7 → 0.5.9

package/templates/.agents/rules/create-issue.github.en.md

@@ -0,0 +1,178 @@
+# Issue Creation
+
+After `create-task` writes the local `task.md`, follow this rule to cascade Issue creation. This rule is referenced internally by `create-task` SKILL.md only; do not invoke it standalone.
+
+## Boundary
+
+- Issue title and body must come from `task.md` only
+- Do not read `analysis.md`, `plan.md`, `implementation.md`, or any review artifact
+- Persistent outputs are limited to the remote Issue and the `issue_number` written back to `task.md`
+- If Issue creation fails, do not roll back `task.md`; the current task remains valid for the workflow, and the user can later manually fill `issue_number` so other skills' cascade sync takes over
+
+## Steps
+
+### 1. Verify Prerequisites
+
+- `.agents/workspace/active/{task-id}/task.md` must exist
+- Read `.agents/rules/issue-pr-commands.md` first and run its authentication and platform detection commands to confirm `gh auth status` and the current repository are usable
+- Read `.agents/rules/issue-sync.md` first and complete `upstream_repo`, `has_triage`, and `has_push` detection; reuse these variables for every later `gh issue` and repo-level `gh api` call
+- If `task.md` already has a non-empty, non-`N/A` `issue_number`, halt the cascade immediately: return "Task already linked to Issue #{n}, skipping creation" to `create-task` and let it decide how to continue
+
+### 2. Extract Task Information
+
+Pull the following from `task.md`:
+
+- Task title (the first `# ` heading, stripped of `任务：` / `Task:` prefixes)
+- The `## Description` / `## 描述` section
+- The `## Requirements` / `## 需求` section
+- frontmatter fields `type` and (optionally) `milestone`
+
+Build the Issue title:
+
+| task.md `type` | Conventional Commits type |
+|---|---|
+| `feature` | `feat` |
+| `bugfix`, `bug` | `fix` |
+| `refactor`, `refactoring` | `refactor` |
+| `docs`, `documentation` | `docs` |
+| `chore`, `task`, others | `chore` |
+
+Scope inference: read known module names from `.agents/.airc.json`'s `labels.in` field, then semantically match them against the task title and description; omit `scope` when there is no clear hit. Final title: `{cc_type}({scope}): {task_title}` or `{cc_type}: {task_title}` (preserve the task title verbatim — do not translate or rewrite).
+
+### 3. Build the Issue Body
+
+Issue Form detection: follow the "Issue Template Detection" section in `.agents/rules/issue-pr-commands.md` to scan `.github/ISSUE_TEMPLATE/*.yml` (excluding `config.yml`).
+
+#### Scenario A: A matching template was detected
+
+Pick the form whose `name` (or filename) best matches the task type (e.g., a task with `type: bugfix` prefers a form whose name contains `bug`); if no match, fall back to a generic form like `other.yml`; if none, take the first form in the directory.
+
+Populate the form by following the field-handling rules in `.agents/rules/issue-pr-commands.md` § "Issue Template Detection":
+
+- `textarea` / `input` fields: use `attributes.label` as a markdown heading and pull values from task.md
+- `markdown` fields: skip (these are description blurbs)
+- `dropdown` / `checkboxes` fields: skip
+
+Recommended field-to-source mapping:
+
+| Template field hint | Source in task.md |
+|---|---|
+| `summary`, `title` | task title |
+| `description`, `problem`, `what happened`, `issue-description`, `current-content` | task description |
+| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | requirements list (preserve checked / unchecked state as-is) |
+| Other `textarea` / `input` fields | task description, or `N/A` if missing |
+
+Whenever task.md does not provide a usable value, write `N/A`.
+
+#### Scenario B: No template, or template parsing failed
+
+Fall back to the default body:
+
+```markdown
+## Description
+
+{task description, or N/A if missing}
+
+## Requirements
+
+- [ ] {requirement-1}
+- [ ] {requirement-2}
+```
+
+If the requirements list is empty, write `N/A` in that section.
+
+### 4. Resolve labels / Issue Type / milestone
+
+#### labels (rough pass)
+
+- Call `gh api "repos/$upstream_repo/labels?per_page=100" --jq '.[].name'` to fetch the actual labels in the repo (cache as a set)
+- Pick the "expected type label" using the mapping below, keeping only those that exist in the repo set:
+
+  | task.md `type` | label |
+  |---|---|
+  | `bug`, `bugfix` | `type: bug` |
+  | `feature` | `type: feature` |
+  | `enhancement` | `type: enhancement` |
+  | `docs`, `documentation` | `type: documentation` |
+  | `dependency-upgrade` | `type: dependency-upgrade` |
+  | `task`, `chore` | `type: task` |
+  | `refactor`, `refactoring` | `type: enhancement` |
+  | others | skip |
+
+- `in:` labels (rough pass — when in doubt, leave it out): semantically match the task title and description against module names from `labels.in`; explicit mention or strong implication → add `in: {module}`; vague or uncertain → skip. `in:` labels also require the label to actually exist in the repo.
+
+If the final label set is empty, omit the `--label` argument.
+
+#### Issue Type fallback
+
+| task.md `type` | Issue Type |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring`, others | `Task` |
+
+When applying the Issue Type, follow the "Set Issue Type" command in `.agents/rules/issue-pr-commands.md`; first call `gh api orgs/{owner}/issue-types` to list the org's actually available Types, and only set the inferred value when it is present in that list. Failure to set is non-blocking.
+
+#### milestone
+
+Infer per `.agents/rules/milestone-inference.md` § "Stage 1: `create-task` (when the platform rule creates the Issue)". When the inference is empty or the repo lacks a matching milestone, omit the milestone.
+
+### 5. Call the GitHub CLI to Create the Issue
+
+Run the "Create Issue" command from `.agents/rules/issue-pr-commands.md`:
+
+```bash
+gh issue create -R "$upstream_repo" \
+  --title "{title}" \
+  --body "{body}" \
+  --assignee @me \
+  {label-args} \
+  {milestone-arg}
+```
+
+- `{label-args}` is expanded from the result of §4 into multiple `--label "..."`; if empty, omit the entire argument
+- `{milestone-arg}` is only expanded to `--milestone "..."` when `has_triage=true` and milestone is non-empty; otherwise omit
+- `--assignee @me` requires no permission probe; on failure, skip silently
+
+Permission downgrade follows `.agents/rules/issue-sync.md`: `has_triage=false` skips label / milestone settings; `has_push=false` skips Issue Type setting; the rest continues.
+
+After success, parse the Issue number from the output (match only the `https://.../issues/(\d+)` URL form; do not use a loose regex). If parsing fails, halt the cascade and propagate the error back to `create-task`.
+
+### 6. Set Issue Type (Optional)
+
+Execute only when `has_push=true` and the Issue Type inferred in §4 is in the org's actually available list:
+
+```bash
+gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
+  -f type="{issue-type}" --silent
+```
+
+Failure is non-blocking.
+
+### 7. Write Back task.md
+
+Update task.md:
+
+- Write `issue_number: {n}` into the frontmatter (replace if it exists; append at the end of the frontmatter otherwise)
+- Update `updated_at` to the current time (command: `date "+%Y-%m-%d %H:%M:%S%:z"`)
+- Append to the `## 活动日志` / `## Activity Log` section:
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Issue** by {agent} — Created GitHub Issue #{n}
+  ```
+
+### 8. Return the Result
+
+Hand the following back to the caller `create-task`:
+
+- Issue number `{n}`
+- Issue URL (prefer the URL printed by `gh issue create`; fall back to `https://github.com/$upstream_repo/issues/{n}`)
+- The labels / milestone / Issue Type that were actually applied
+
+`create-task` uses these to pick the "Scenario A: Issue created" output branch and continue with task comment sync and status label setup.
+
+## Error Handling
+
+- Auth failure / command unavailable: return a structured `{code: "AUTH_FAILED", message}` to `create-task`; do not modify task.md
+- Network timeout / DNS failure: `{code: "NETWORK", message}`
+- Template parsing failure, Issue number parsing failure, other anomalies: `{code: "VALIDATION", message}`
+- All failures keep task.md untouched; `create-task` takes the "Scenario C: failure fallback" output branch and prompts the user to retry manually or fill `issue_number` later

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

@@ -0,0 +1,178 @@
+# Issue 创建
+
+当 `create-task` 完成本地 `task.md` 落盘后，按本规则级联创建 Issue。本规则仅由 `create-task` SKILL.md 内部引用，不应独立调用。
+
+## 行为边界
+
+- Issue 标题和正文只能来自 `task.md`
+- 不读取 `analysis.md`、`plan.md`、`implementation.md` 或审查产物
+- 持久产物只有：远端 Issue + `task.md` 中回写的 `issue_number`
+- Issue 创建失败时不回滚 `task.md`；当前 task 仍可继续后续工作流，未来可由用户手动写入 `issue_number`，让其它技能的级联同步接管
+
+## 执行步骤
+
+### 1. 验证前置条件
+
+- `.agents/workspace/active/{task-id}/task.md` 必须存在
+- 先读取 `.agents/rules/issue-pr-commands.md`，按其中的认证与平台检测命令验证 `gh auth status` 和当前仓库可用
+- 先读取 `.agents/rules/issue-sync.md`，完成 `upstream_repo`、`has_triage`、`has_push` 检测；后续所有 `gh issue` 与 repo 级 `gh api` 调用都复用这些变量
+- 如果 `task.md` 中 `issue_number` 已存在且既不为空也不为 `N/A`，立即停止级联：返回"任务已绑定 Issue #{n}，跳过创建"信息给 `create-task`，由调用方决定如何继续
+
+### 2. 提取任务信息
+
+从 `task.md` 提取以下字段：
+
+- 任务标题（首个 `# ` 标题，去掉 `任务：` / `Task:` 前缀）
+- `## Description` / `## 描述` 段落
+- `## Requirements` / `## 需求` 段落
+- frontmatter 中的 `type` 与（可选的）`milestone`
+
+构造 Issue 标题：
+
+| task.md `type` | Conventional Commits type |
+|---|---|
+| `feature` | `feat` |
+| `bugfix`, `bug` | `fix` |
+| `refactor`, `refactoring` | `refactor` |
+| `docs`, `documentation` | `docs` |
+| `chore`, `task` 或其它 | `chore` |
+
+scope 推断：从 `.agents/.airc.json` 的 `labels.in` 字段读取已知模块名，再与任务标题/描述做语义匹配；没有清晰命中时省略 scope。最终标题：`{cc_type}({scope}): {task_title}` 或 `{cc_type}: {task_title}`（任务标题保留原文，不要翻译或改写）。
+
+### 3. 构建 Issue 正文
+
+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` 字段：跳过
+
+字段值映射（建议）：
+
+| 模板字段提示 | 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` |
+
+任何字段在 task.md 中找不到合适值时，写入 `N/A`。
+
+#### 场景 B：无模板或解析失败
+
+回退到默认正文：
+
+```markdown
+## Description
+
+{任务描述；缺失时填 N/A}
+
+## Requirements
+
+- [ ] {requirement-1}
+- [ ] {requirement-2}
+```
+
+需求列表为空时，整段写 `N/A`。
+
+### 4. 解析 labels / Issue Type / milestone
+
+#### labels（粗选）
+
+- 调用 `gh api "repos/$upstream_repo/labels?per_page=100" --jq '.[].name'` 获取仓库实际存在的 label 列表（缓存为 set）
+- 按以下映射挑出"应有的 type label"，仅保留仓库 set 中实际存在的：
+
+  | task.md `type` | label |
+  |---|---|
+  | `bug`, `bugfix` | `type: bug` |
+  | `feature` | `type: feature` |
+  | `enhancement` | `type: enhancement` |
+  | `docs`, `documentation` | `type: documentation` |
+  | `dependency-upgrade` | `type: dependency-upgrade` |
+  | `task`, `chore` | `type: task` |
+  | `refactor`, `refactoring` | `type: enhancement` |
+  | 其它 | 跳过 |
+
+- `in:` label（粗选，宁缺毋滥）：根据任务标题与描述对 `labels.in` 中的模块名做语义匹配；明确提及或强烈暗示 → 添加 `in: {module}`；模糊或不确定 → 不添加。`in:` label 同样要求仓库实际存在。
+
+最终 label 集合若为空，省略 `--label` 参数。
+
+#### Issue Type fallback
+
+| task.md `type` | Issue Type |
+|---|---|
+| `bug`, `bugfix` | `Bug` |
+| `feature`, `enhancement` | `Feature` |
+| `task`, `documentation`, `dependency-upgrade`, `chore`, `docs`, `refactor`, `refactoring` 及其它 | `Task` |
+
+实际设置时按 `.agents/rules/issue-pr-commands.md` 的 "设置 Issue Type" 命令；先调 `gh api orgs/{owner}/issue-types` 列出 org 实际可用的 Type，仅当推断值在列表中时才设置；设置失败不阻断流程。
+
+#### milestone
+
+按 `.agents/rules/milestone-inference.md` 的 "阶段 1：`create-task`（平台规则创建 Issue 时）" 规则推断；推断结果为空或仓库无对应 milestone 时省略。
+
+### 5. 调用 GitHub CLI 创建 Issue
+
+按 `.agents/rules/issue-pr-commands.md` 中的 "创建 Issue" 命令执行：
+
+```bash
+gh issue create -R "$upstream_repo" \
+  --title "{title}" \
+  --body "{body}" \
+  --assignee @me \
+  {label-args} \
+  {milestone-arg}
+```
+
+- `{label-args}` 由 §4 计算结果展开为多个 `--label "..."`；为空则整体省略
+- `{milestone-arg}` 仅当 `has_triage=true` 且 milestone 非空时展开为 `--milestone "..."`；否则整体省略
+- `--assignee @me` 不做权限预判，失败时静默跳过
+
+权限降级规则按 `.agents/rules/issue-sync.md`：`has_triage=false` 时跳过 label / milestone 设置；`has_push=false` 时跳过 Issue Type 设置；其余流程继续。
+
+创建成功后从输出中解析 Issue 编号（仅匹配 `https://.../issues/(\d+)` URL 形式，不要使用宽松正则）；解析失败时停止级联并把错误传回 `create-task`。
+
+### 6. 设置 Issue Type（可选）
+
+仅当 `has_push=true` 且 §4 推断的 Issue Type 在 org 实际可用列表中时执行：
+
+```bash
+gh api "repos/$upstream_repo/issues/{issue-number}" -X PATCH \
+  -f type="{issue-type}" --silent
+```
+
+设置失败不阻断流程。
+
+### 7. 回写 task.md
+
+更新 task.md：
+
+- 把 `issue_number: {n}` 写入 frontmatter（已存在则替换；不存在则在 frontmatter 末尾追加）
+- 更新 `updated_at` 为当前时间（命令：`date "+%Y-%m-%d %H:%M:%S%:z"`）
+- 在 `## 活动日志` / `## Activity Log` 段落追加：
+  ```
+  - {YYYY-MM-DD HH:mm:ss±HH:MM} — **Create Issue** by {agent} — Created GitHub Issue #{n}
+  ```
+
+### 8. 返回结果
+
+把以下信息回传给调用方 `create-task`：
+
+- Issue 编号 `{n}`
+- Issue URL（首选 `gh issue create` 输出中的 URL；缺失时拼 `https://github.com/$upstream_repo/issues/{n}`）
+- 实际应用的 labels / milestone / Issue Type
+
+`create-task` 据此选择"场景 A：已创建 Issue"输出分支并继续执行后续 task 评论同步与 status label 设置。
+
+## 错误处理
+
+- 认证失败 / 命令不可用：返回结构化错误 `{code: "AUTH_FAILED", message}` 给 `create-task`，不修改 task.md
+- 网络超时 / DNS 失败：`{code: "NETWORK", message}`
+- 模板解析失败、Issue 编号解析失败、其它异常：`{code: "VALIDATION", message}`
+- 任意失败均不回滚 task.md；`create-task` 走"场景 C 失败兜底"输出，提示用户手动重试或在事后写入 `issue_number`

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

@@ -0,0 +1,5 @@
+# Issue 创建
+
+当前代码平台未提供 Issue 创建规则。
+
+`create-task` 在本平台上会跳过级联创建 Issue 步骤；本地 `task.md` 仍然是有效产物。如果将来需要把任务绑定到一个 Issue，可手动在 `task.md` 中写入 `issue_number`，后续技能（`commit` / `refine-task` / `complete-task` 等）会按既有的级联同步规则自动接管 Issue 元数据更新。

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

@@ -22,6 +22,44 @@ Before any later `gh issue` or `gh api "repos/..."` call, follow `.agents/rules/
 - keep `gh pr *` commands on the current repository without adding `-R`
 - keep organization-scoped commands such as `gh api "orgs/{owner}/..."` unchanged
 
+## Issue Template Detection
+
+Detect GitHub Issue Forms with:
+
+```bash
+rg --files .github/ISSUE_TEMPLATE -g '*.yml' -g '!config.yml'
+```
+
+Read matching form files locally before creating the Issue. If the directory is missing or no form matches the task, use the caller's fallback body format.
+
+Typical candidate templates:
+- `bug_report.yml` for bug work
+- `question.yml` for question or investigation work
+- `feature_request.yml` for feature work
+- `documentation.yml` for documentation work
+- `other.yml` as the general fallback
+
+For GitHub Issue Forms, inspect the matched form's:
+- `name`
+- `type:`
+- `labels:`
+- `body:`
+
+Field handling rules:
+- `textarea` and `input`: use `attributes.label` as the markdown heading and fill values from task.md
+- `markdown`: skip template explanation prose
+- `dropdown` and `checkboxes`: skip
+- when task.md lacks a suitable value, write `N/A`
+
+Suggested field mapping:
+
+| Template field hint | task.md source |
+|---|---|
+| `summary`, `title` | task title |
+| `description`, `problem`, `what happened`, `issue-description`, `current-content` | task description |
+| `solution`, `requirements`, `steps`, `suggested-content`, `impact`, `context`, `alternatives`, `expected` | requirements list |
+| other `textarea` / `input` fields | task description, otherwise `N/A` |
+
 ## Read and Create Issues
 
 Read an Issue:
@@ -82,6 +120,28 @@ Read Issue comments or search for existing hidden markers:
 gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
 ```
 
+## PR Template and Metadata Helpers
+
+Read a repository PR template when present:
+
+```bash
+cat .github/PULL_REQUEST_TEMPLATE.md
+```
+
+Review recent merged PRs for style:
+
+```bash
+gh pr list --limit 3 --state merged --json number,title,body
+```
+
+Verify that standard type labels exist before PR metadata sync:
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+If the result is `0`, run `init-labels` before retrying PR metadata sync.
+
 ## Read and Create PRs
 
 Read a PR:

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

@@ -22,6 +22,44 @@ gh repo view --json nameWithOwner
 - `gh pr *` 命令保持作用于当前仓库，不额外加 `-R`
 - `gh api "orgs/{owner}/..."` 这类 org 级命令保持不变
 
+## Issue 模板检测
+
+使用以下命令检测 GitHub Issue Forms：
+
+```bash
+rg --files .github/ISSUE_TEMPLATE -g '*.yml' -g '!config.yml'
+```
+
+创建 Issue 前先读取匹配的 form 文件。目录不存在或没有匹配 form 时，使用调用方定义的 fallback 正文格式。
+
+常见候选模板：
+- `bug_report.yml`：bug 工作
+- `question.yml`：问题或排查工作
+- `feature_request.yml`：功能工作
+- `documentation.yml`：文档工作
+- `other.yml`：通用 fallback
+
+对 GitHub Issue Forms，检查匹配 form 的：
+- `name`
+- `type:`
+- `labels:`
+- `body:`
+
+字段处理规则：
+- `textarea` 和 `input`：使用 `attributes.label` 作为 markdown 标题，并从 task.md 填充值
+- `markdown`：跳过模板说明文案
+- `dropdown` 和 `checkboxes`：跳过
+- task.md 缺少合适值时，写入 `N/A`
+
+建议字段映射：
+
+| 模板字段提示 | 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` |
+
 ## Issue 读取与创建
 
 读取 Issue：
@@ -82,6 +120,28 @@ gh issue close {issue-number} -R "$upstream_repo" --reason "{reason}"
 gh api "repos/$upstream_repo/issues/{issue-number}/comments" --paginate
 ```
 
+## PR 模板与元数据辅助命令
+
+存在仓库 PR 模板时读取：
+
+```bash
+cat .github/PULL_REQUEST_TEMPLATE.md
+```
+
+参考最近合并的 PR 风格：
+
+```bash
+gh pr list --limit 3 --state merged --json number,title,body
+```
+
+PR 元数据同步前验证标准 type labels 是否存在：
+
+```bash
+gh label list --search "type:" --limit 1 --json name --jq 'length'
+```
+
+如果结果是 `0`，先运行 `init-labels`，再重试 PR 元数据同步。
+
 ## PR 读取与创建
 
 读取 PR：

package/templates/.agents/rules/issue-sync.en.md

@@ -1,5 +1,19 @@
 # Issue Sync
 
+## Marker Registry
+
+These hidden markers are the canonical registry for Issue synchronization:
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
+
 This code platform does not provide built-in issue synchronization.
 
 Issue metadata, labels, milestones, assignees, and comments are skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates and platform adapters. Continue writing local task artifacts normally.

package/templates/.agents/rules/issue-sync.github.en.md

@@ -1,5 +1,19 @@
 # Issue Sync Rules
 
+## Marker Registry
+
+These hidden markers are the canonical registry for Issue synchronization:
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Callers should refer to the marker key in skill prose and keep concrete marker strings in this rule or the platform adapter defaults.
+
 Read this file before a task skill updates a GitHub Issue.
 
 ## Upstream Repository Detection
@@ -101,7 +115,7 @@ If `gh` fails, skip and continue. Do not fail the skill.
 
 When a skill creates or imports an Issue, automatically add the current executor as assignee:
 
-- `create-issue`: use `--assignee @me` in `gh issue create` and include `-R "$upstream_repo"`
+- When the `create-task` platform rule triggers Issue creation: use `--assignee @me` in `gh issue create` and include `-R "$upstream_repo"`
 - `import-issue`: run `gh issue edit {issue-number} -R "$upstream_repo" --add-assignee @me 2>/dev/null || true` after import
 
 `@me` is resolved by `gh` CLI to the authenticated user. The operation is idempotent. If the command fails, skip it directly and do not provide a fallback path.

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

@@ -1,5 +1,19 @@
 # Issue 同步规则
 
+## Marker 注册表
+
+以下隐藏标记是 Issue 同步的唯一权威注册表：
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Skill 正文应引用 marker key，具体 marker 字符串只保留在本规则或平台适配器默认值中。
+
 在任务技能需要更新 GitHub Issue 时先读取本文件。
 
 ## Upstream 仓库检测
@@ -101,7 +115,7 @@ fi
 
 当技能创建或导入 Issue 时，自动将当前执行者添加为 assignee：
 
-- `create-issue`：在 `gh issue create` 命令中使用 `--assignee @me` 参数，并附带 `-R "$upstream_repo"`
+- `create-task` 的平台规则触发 Issue 创建时：在 `gh issue create` 命令中使用 `--assignee @me` 参数，并附带 `-R "$upstream_repo"`
 - `import-issue`：导入后执行 `gh issue edit {issue-number} -R "$upstream_repo" --add-assignee @me 2>/dev/null || true`
 
 `@me` 由 `gh` CLI 自动解析为当前认证用户。此操作是幂等的（重复添加不会报错）。如果命令失败（如权限不足），直接跳过，不做任何替代。

package/templates/.agents/rules/issue-sync.zh-CN.md

@@ -1,5 +1,19 @@
 # Issue 同步
 
+## Marker 注册表
+
+以下隐藏标记是 Issue 同步的唯一权威注册表：
+
+| Key | Marker |
+|---|---|
+| `task` | `<!-- sync-issue:{task-id}:task -->` |
+| `artifact` | `<!-- sync-issue:{task-id}:{artifact-stem} -->` |
+| `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
+| `summary` | `<!-- sync-issue:{task-id}:summary -->` |
+| `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+
+Skill 正文应引用 marker key，具体 marker 字符串只保留在本规则或平台适配器默认值中。
+
 当前代码平台未内置 Issue 同步支持。
 
 自定义平台会跳过 Issue 元数据、标签、里程碑、负责人和评论同步，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板和平台适配器。请继续正常写入本地任务产物。

package/templates/.agents/rules/label-milestone-setup.github.en.md

@@ -43,6 +43,16 @@ Update a milestone:
 gh api "repos/$repo/milestones/{number}" -X PATCH -f state="{state}" -f description="{description}"
 ```
 
+## Error Prompt Templates
+
+Use these normalized prompts when the GitHub setup scripts fail:
+
+| Condition | Prompt |
+|---|---|
+| CLI missing | GitHub CLI (`gh`) is not installed |
+| Authentication failed | `GitHub CLI is not authenticated` |
+| API rate limit | `GitHub API rate limit reached, please retry later` |
+
 ## Constraints
 
 - use label names as the idempotency key

package/templates/.agents/rules/label-milestone-setup.github.zh-CN.md

@@ -43,6 +43,16 @@ gh api "repos/$repo/milestones" -f title="{title}" -f description="{description}
 gh api "repos/$repo/milestones/{number}" -X PATCH -f state="{state}" -f description="{description}"
 ```
 
+## 错误提示模板
+
+GitHub 初始化脚本失败时使用以下标准提示：
+
+| 条件 | 提示 |
+|---|---|
+| CLI 缺失 | GitHub CLI (`gh`) is not installed |
+| 认证失败 | `GitHub CLI is not authenticated` |
+| API 限流 | `GitHub API rate limit reached, please retry later` |
+
 ## 约束
 
 - label 以名称作为幂等键

package/templates/.agents/rules/milestone-inference.github.en.md

@@ -1,6 +1,6 @@
 # Milestone Inference Rules
 
-Read this file before `create-issue`, `implement-task`, or `create-pr` handles a milestone.
+Read this file before the `create-task` platform rule, `implement-task`, or `create-pr` handles a milestone.
 
 ## General Principles
 
@@ -21,7 +21,7 @@ git branch -r | grep -v 'HEAD' | grep -E 'origin/[0-9]+\.[0-9]+\.x$'
 - Any output: multi-version branch mode
 - No output: trunk mode
 
-## Phase 1: `create-issue`
+## Phase 1: `create-task` (when the platform rule creates an Issue)
 
 Goal: choose a coarse-grained release line when the Issue is created.