@fitlab-ai/agent-infra 0.4.2 → 0.4.4

package/templates/.agents/skills/{sync-pr → create-pr}/reference/comment-publish.md

@@ -1,6 +1,6 @@
 # PR Summary Comment Publication
 
-Read this file before creating or updating the single reviewer-facing PR summary comment.
+Read this file before creating or updating the single reviewer-facing PR summary comment from `create-pr`.
 
 ## Create or Update the Single Idempotent Review Summary
 
@@ -54,7 +54,8 @@ Suggested summary body:
 <!-- sync-pr:{task-id}:summary -->
 ## Review Summary
 
-**Task**: {task-id}
+> **{agent}** · {task-id}
+
 **Updated At**: {current-time}
 
 ### Key Technical Decisions
@@ -73,10 +74,9 @@ Suggested summary body:
 - {test-summary}
 
 ---
-*Generated by AI · Internal tracking: {task-id}*
+*Generated by {agent} · Internal tracking: {task-id}*
 ```
 
-## Update Task Status
+## Return the Result
 
-Append:
-`- {yyyy-MM-dd HH:mm:ss} — **Sync to PR** by {agent} — PR metadata synced, summary {created|updated|skipped} on PR #{pr-number}`
+Return the summary outcome as `summary created`, `summary updated`, or `summary skipped` so `create-pr` can reuse it in user output and the PR Created Activity Log.

package/templates/.agents/skills/{sync-pr → create-pr}/reference/comment-publish.zh-CN.md

@@ -1,6 +1,6 @@
 # PR 摘要评论发布
 
-在创建或更新面向 reviewer 的唯一 PR 摘要评论之前先读取本文件。
+在 `create-pr` 中创建或更新面向 reviewer 的唯一 PR 摘要评论之前先读取本文件。
 
 ## 创建或更新唯一且幂等的审查摘要
 
@@ -54,7 +54,8 @@ EOF
 <!-- sync-pr:{task-id}:summary -->
 ## 审查摘要
 
-**任务**：{task-id}
+> **{agent}** · {task-id}
+
 **更新时间**：{当前时间}
 
 ### 关键技术决策
@@ -73,10 +74,9 @@ EOF
 - {test-summary}
 
 ---
-*由 AI 自动生成 · 内部追踪：{task-id}*
+*由 {agent} 自动生成 · 内部追踪：{task-id}*
 ```
 
-## 更新任务状态
+## 结果回传
 
-追加：
-`- {yyyy-MM-dd HH:mm:ss} — **Sync to PR** by {agent} — PR metadata synced, summary {created|updated|skipped} on PR #{pr-number}`
+将摘要结果整理为 `summary created`、`summary updated` 或 `summary skipped`，供 `create-pr` 在用户输出和 PR Created Activity Log 中复用。

package/templates/.agents/skills/create-pr/reference/pr-body-template.md

@@ -50,14 +50,19 @@ Metadata sync order:
 1. query Issue labels and milestone best-effort with `gh issue view {issue-number} --json labels,milestone`
 2. add the mapped type label with `gh pr edit {pr-number} --add-label "{type-label}"`
 3. inherit non-`type:` and non-`status:` Issue labels with repeated `gh pr edit ... --add-label`
-4. add relevant `in: {module}` labels without removing existing ones
-5. resolve milestone in order: PR -> task.md -> Issue -> branch/tag inference -> `General Backlog`
+4. refine the PR `in:` labels by following `.agents/rules/issue-sync.md`, and keep the linked Issue `in:` labels in sync with the same result
+5. handle the milestone by following "Phase 3: `create-pr`" in `.agents/rules/milestone-inference.md`, reusing the Issue milestone directly
 6. ensure the PR body contains `Closes #{issue-number}` or an equivalent closing keyword
 
+Milestone rule:
+- Follow "Phase 3: `create-pr`" in `.agents/rules/milestone-inference.md`
+- Reuse the linked Issue milestone directly instead of inferring a new PR milestone
+
 ## Create the PR
 
 - Extract `issue_number` from task.md when this work belongs to an active task
 - If `issue_number` exists, query the Issue best-effort with `gh issue view {issue-number} --json number,title --jq '.number'`
+- Before calling `gh pr create`, check whether the current branch already has a PR. If it does, report the PR URL and state, then stop without repeating metadata sync or summary publication
 - Use HEREDOC to pass the PR body
 - Replace `{$IssueNumber}` in the template when present
 - End the PR body with `Generated with AI assistance`
@@ -71,14 +76,10 @@ EOF
 )"
 ```
 
-Final user output should include both follow-up paths in order:
+Final user output should include this follow-up path:
 
 ```text
 Next steps:
-  - optional reviewer summary sync:
-    - Claude Code / OpenCode: /sync-pr {task-id}
-    - Gemini CLI: /agent-infra:sync-pr {task-id}
-    - Codex CLI: $sync-pr {task-id}
   - complete the task after the workflow truly finishes:
     - Claude Code / OpenCode: /complete-task {task-id}
     - Gemini CLI: /agent-infra:complete-task {task-id}

package/templates/.agents/skills/create-pr/reference/pr-body-template.zh-CN.md

@@ -50,14 +50,19 @@ Type label 映射：
 1. 用 `gh issue view {issue-number} --json labels,milestone` 尽力查询 Issue 的 labels 和 milestone
 2. 用 `gh pr edit {pr-number} --add-label "{type-label}"` 添加映射后的 type label
 3. 用重复的 `gh pr edit ... --add-label` 继承非 `type:`、非 `status:` 的 Issue labels
-4. 添加相关的 `in: {module}` label，但不要移除已有 label
-5. 按 `PR -> task.md -> Issue -> branch/tag inference -> General Backlog` 的顺序解析 milestone
+4. 按 `.agents/rules/issue-sync.md` 的 `in:` label 同步规则精修 PR 的 `in:` label，同时同步更新关联 Issue 的 `in:` label 保持一致
+5. 按 `.agents/rules/milestone-inference.md` 的「阶段 3：`create-pr`」处理 milestone，直接复用 Issue milestone
 6. 确保 PR 正文包含 `Closes #{issue-number}` 或等价的 closing keyword
 
+Milestone 规则：
+- 按 `.agents/rules/milestone-inference.md` 的「阶段 3：`create-pr`」处理
+- PR 直接复用 Issue milestone，不再独立推断
+
 ## 创建 PR
 
 - 当当前工作属于活动任务时，从 task.md 中提取 `issue_number`
 - 如果存在 `issue_number`，用 `gh issue view {issue-number} --json number,title --jq '.number'` 尽力查询对应 Issue
+- 在调用 `gh pr create` 前，先检查当前分支是否已经存在 PR；如果已存在，直接告知用户 PR URL 和状态并结束，不要重复同步元数据或摘要
 - 使用 HEREDOC 传递 PR 正文
 - 如果模板中存在 `{$IssueNumber}`，替换它
 - PR 正文结尾必须带上 `Generated with AI assistance`
@@ -71,14 +76,10 @@ EOF
 )"
 ```
 
-最终用户输出必须按顺序包含这两类后续动作：
+最终用户输出必须按顺序包含以下后续动作：
 
 ```text
 下一步：
-  - 可选：同步 reviewer 摘要：
-    - Claude Code / OpenCode: /sync-pr {task-id}
-    - Gemini CLI: /agent-infra:sync-pr {task-id}
-    - Codex CLI: $sync-pr {task-id}
   - 工作流真正结束后完成任务：
     - Claude Code / OpenCode: /complete-task {task-id}
     - Gemini CLI: /agent-infra:complete-task {task-id}

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

@@ -24,7 +24,7 @@ After executing this skill, you **must** immediately update task status in task.
 ### 1. Parse the User Description
 
 Extract from the natural-language description:
-- **Task title**: a concise title (maximum 50 characters), in the same language as the user's description
+- **Task title**: a concise title (maximum 50 characters), in the same language as the user's description - do not translate it to English or apply Conventional Commits formatting
 - **Task type**: `feature` | `bugfix` | `refactor` | `docs` | `chore` (infer from the description)
 - **Workflow**: `feature-development` | `bug-fix` | `refactoring` (infer from the type)
 - **Detailed description**: the cleaned-up original user request
@@ -92,7 +92,24 @@ Update `.agents/workspace/active/{task-id}/task.md`:
   - {yyyy-MM-dd HH:mm:ss} — **Task Created** by {agent} — Task created from description
   ```
 
-### 4. Inform User
+### 4. Verification Gate
+
+Run the verification gate to confirm the task artifact and sync state are valid:
+
+```bash
+node .agents/scripts/validate-artifact.js gate create-task .agents/workspace/active/{task-id} --format text
+```
+
+Handle the result as follows:
+- exit code 0 (all checks passed) -> continue to the "Inform User" step
+- exit code 1 (validation failed) -> fix the reported issues and run the gate again
+- exit code 2 (network blocked) -> stop and tell the user that human intervention is required
+
+Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
+
+### 5. Inform User
+
+> Execute this step only after the verification gate passes.
 
 > **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
 
@@ -113,6 +130,11 @@ Next step - run requirements analysis:
   - Claude Code / OpenCode: /analyze-task {task-id}
   - Gemini CLI: /{{project}}:analyze-task {task-id}
   - Codex CLI: $analyze-task {task-id}
+
+Or create a GitHub Issue first:
+  - Claude Code / OpenCode: /create-issue {task-id}
+  - Gemini CLI: /{{project}}:create-issue {task-id}
+  - Codex CLI: $create-issue {task-id}
 ```
 
 ## Completion Checklist
@@ -134,7 +156,7 @@ Wait for the user to run the `analyze-task` skill.
 
 1. **Clarity**: if the user description is vague or missing key information, ask for clarification first
 2. **Difference from `import-issue`**: `import-issue` imports from a GitHub Issue; `create-task` creates from a free-form description
-3. **Workflow order**: after creating a task, `analyze-task` must run before `plan-task`
+3. **Workflow order**: after creating a task, typically run `analyze-task` before `plan-task`; if you need GitHub tracking first, you may run `create-issue` first
 
 ## Error Handling
 

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

@@ -24,7 +24,7 @@ description: "根据自然语言描述创建任务"
 ### 1. 解析用户描述
 
 从自然语言描述中提取：
-- **任务标题**：简洁标题（最多 50 个字符），使用与用户描述相同的语言
+- **任务标题**：简洁标题（最多 50 个字符），使用中文——不要翻译为英文，不要套用 Conventional Commits 格式
 - **任务类型**：`feature` | `bugfix` | `refactor` | `docs` | `chore`（从描述推断）
 - **工作流**：`feature-development` | `bug-fix` | `refactoring`（从类型推断）
 - **详细描述**：整理后的用户原始描述
@@ -92,7 +92,24 @@ date "+%Y-%m-%d %H:%M:%S"
   - {yyyy-MM-dd HH:mm:ss} — **Task Created** by {agent} — Task created from description
   ```
 
-### 4. 告知用户
+### 4. 完成校验
+
+运行完成校验，确认任务产物和同步状态符合规范：
+
+```bash
+node .agents/scripts/validate-artifact.js gate create-task .agents/workspace/active/{task-id} --format text
+```
+
+处理结果：
+- 退出码 0（全部通过）-> 继续到「告知用户」步骤
+- 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
+- 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入
+
+将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
+
+### 5. 告知用户
+
+> 仅在校验通过后执行本步骤。
 
 > **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
 
@@ -113,6 +130,11 @@ date "+%Y-%m-%d %H:%M:%S"
   - Claude Code / OpenCode：/analyze-task {task-id}
   - Gemini CLI：/agent-infra:analyze-task {task-id}
   - Codex CLI：$analyze-task {task-id}
+
+或先创建 GitHub Issue：
+  - Claude Code / OpenCode：/create-issue {task-id}
+  - Gemini CLI：/agent-infra:create-issue {task-id}
+  - Codex CLI：$create-issue {task-id}
 ```
 
 ## 完成检查清单
@@ -134,7 +156,7 @@ date "+%Y-%m-%d %H:%M:%S"
 
 1. **清晰度**：如果用户描述模糊或缺少关键信息，先要求澄清
 2. **与 import-issue 的区别**：`import-issue` 从 GitHub Issue 导入任务；`create-task` 从自由描述创建
-3. **工作流顺序**：创建任务后，必须先执行 `analyze-task`，再进入 `plan-task`
+3. **工作流顺序**：创建任务后，通常先执行 `analyze-task` 再进入 `plan-task`；如需先建立 GitHub 跟踪，也可先执行 `create-issue`
 
 ## 错误处理
 

package/templates/.agents/skills/create-task/config/verify.json

@@ -0,0 +1,24 @@
+{
+  "skill": "create-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "current_step",
+        "assigned_to"
+      ],
+      "expected_step": "requirement-analysis",
+      "expected_status": "active"
+    },
+    "activity-log": {
+      "expected_action_pattern": "Task Created",
+      "freshness_minutes": 30
+    },
+    "github-sync": null
+  }
+}

package/templates/.agents/skills/implement-task/SKILL.md

@@ -24,7 +24,24 @@ Check these files first:
 
 If either file is missing, stop and ask the user to complete the prerequisite step.
 
-### 2. Determine the Input Plan and Implementation Round
+### 2. Ensure the Task Branch
+
+Read the branch field in `## Context` from `task.md` and check whether the current Git branch matches it.
+
+- if a task branch is already recorded, switch to it when the current branch does not match
+- if no branch is recorded, check whether the current branch follows the naming convention and belongs to this task
+  - if yes: record the current branch and continue
+  - if no: create and switch to a new task branch that follows the naming rule
+
+After this step, write the final branch name back to `task.md`.
+
+> Branch naming rules, Git commands, and edge-case handling live in `reference/branch-management.md`. Read `reference/branch-management.md` before executing this step.
+
+### 3. Narrow the Milestone
+
+If task.md contains a valid `issue_number`, read `.agents/rules/milestone-inference.md` and follow "Phase 2: `implement-task`" to narrow the Issue milestone before implementation starts.
+
+### 4. Determine the Input Plan and Implementation Round
 
 Scan `.agents/workspace/active/{task-id}/` and record:
 - the highest-round plan file as `{plan-artifact}`
@@ -33,7 +50,7 @@ Scan `.agents/workspace/active/{task-id}/` and record:
 
 If any `plan-r{N}.md` exists, read the highest-round plan file. Otherwise read `plan.md`.
 
-### 3. Read the Technical Plan
+### 5. Read the Technical Plan
 
 Read `{plan-artifact}` carefully and extract:
 - implementation steps
@@ -41,25 +58,25 @@ Read `{plan-artifact}` carefully and extract:
 - test strategy
 - constraints, risks, and any approved tradeoffs
 
-### 4. Implement the Code
+### 6. Implement the Code
 
 Follow `.agents/workflows/feature-development.yaml` and the plan in order.
 
 > Detailed implementation rules, testing discipline, and deviation handling live in `reference/implementation-rules.md`. Read `reference/implementation-rules.md` before executing this step.
 
-### 5. Run Test Verification
+### 7. Run Test Verification
 
 Use the project test command from the `test` skill and keep iterating until all required tests pass.
 
 If tests fail, Attempt to fix the issue and re-run tests first. Only stop when you confirm an external blocker, missing environment, or unclear requirement that is out of scope for the task.
 
-### 6. Write the Implementation Report
+### 8. Write the Implementation Report
 
 Create `.agents/workspace/active/{task-id}/{implementation-artifact}`.
 
 > Report structure, required sections, and the full template live in `reference/report-template.md`. Read `reference/report-template.md` before writing the report.
 
-### 7. Update Task Status
+### 9. Update Task Status
 
 Get the current time:
 
@@ -76,9 +93,31 @@ Update `.agents/workspace/active/{task-id}/task.md`:
 - append:
   `- {yyyy-MM-dd HH:mm:ss} — **Implementation (Round {N})** by {agent} — Code implemented, {n} files modified, {n} tests passed → {implementation-artifact}`
 
-### 8. Inform the User
+If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure; read `.agents/rules/issue-sync.md` first):
+- Set `status: in-progress` and refine `in:` labels from the branch diff by following `.agents/rules/issue-sync.md` (add/remove when a mapping exists, add-only when it does not)
+- Sync checked `## Requirements` items to the Issue body and publish the `{implementation-artifact}` comment
+- Create or update the `<!-- sync-issue:{task-id}:task -->` comment (follow the task.md comment sync rule in issue-sync.md)
+
+### 10. Verification Gate
+
+Run the verification gate to confirm the task artifact and sync state are valid:
+
+```bash
+node .agents/scripts/validate-artifact.js gate implement-task .agents/workspace/active/{task-id} {implementation-artifact} --format text
+```
+
+Handle the result as follows:
+- exit code 0 (all checks passed) -> continue to the "Inform User" step
+- exit code 1 (validation failed) -> fix the reported issues and run the gate again
+- exit code 2 (network blocked) -> stop and tell the user that human intervention is required
+
+Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
+
+### 11. Inform User
+
+> Execute this step only after the verification gate passes.
 
-Output the implementation summary and include all TUI command variants for the next review step.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. Use the output template in `reference/output-template.md`.
 
 ## Completion Checklist
 

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

@@ -24,7 +24,24 @@ description: "根据技术方案实施任务并输出报告"
 
 如果缺少任一文件，立即停止并提示用户先完成前置步骤。
 
-### 2. 确定输入方案与实现轮次
+### 2. 确保任务分支
+
+先读取 `task.md` 中 `## 上下文` 的分支字段，并检查当前 Git 分支是否匹配。
+
+- 已记录任务分支：当前分支不匹配时切换到该分支
+- 未记录任务分支：判断当前分支是否符合命名规范且属于当前任务
+  - 符合：记录当前分支并继续
+  - 不符合：按规范创建并切换到新的任务分支
+
+完成后，把最终使用的分支名回写到 `task.md`。
+
+> 分支命名规则、Git 命令和边界处理见 `reference/branch-management.md`。执行此步骤前，先读取 `reference/branch-management.md`。
+
+### 3. 收窄里程碑
+
+如果 task.md 中存在有效的 `issue_number`，按 `.agents/rules/milestone-inference.md` 的「阶段 2：`implement-task`」收窄 Issue milestone。执行前先读取该文件。
+
+### 4. 确定输入方案与实现轮次
 
 扫描 `.agents/workspace/active/{task-id}/` 并记录：
 - 最高轮次的方案文件为 `{plan-artifact}`
@@ -33,7 +50,7 @@ description: "根据技术方案实施任务并输出报告"
 
 如果存在 `plan-r{N}.md`，读取最高轮次的方案文件；否则读取 `plan.md`。
 
-### 3. 阅读技术方案
+### 5. 阅读技术方案
 
 仔细阅读 `{plan-artifact}`，提取：
 - 实施步骤
@@ -41,25 +58,25 @@ description: "根据技术方案实施任务并输出报告"
 - 测试策略
 - 约束、风险与已批准的取舍
 
-### 4. 执行代码实现
+### 6. 执行代码实现
 
 按照 `.agents/workflows/feature-development.yaml` 和方案顺序实施。
 
 > 详细实现规则、测试纪律和偏离处理见 `reference/implementation-rules.md`。执行此步骤前，先读取 `reference/implementation-rules.md`。
 
-### 5. 运行测试验证
+### 7. 运行测试验证
 
 使用 `test` 技能中的项目测试命令，直到所有必需测试通过。
 
 如果测试失败，先尝试修复并重新运行测试。只有在确认存在外部阻塞、环境缺失或需求不明确且超出任务范围时，才可以停止。
 
-### 6. 编写实现报告
+### 8. 编写实现报告
 
 创建 `.agents/workspace/active/{task-id}/{implementation-artifact}`。
 
 > 报告结构、必填章节和完整模板见 `reference/report-template.md`。写报告前先读取 `reference/report-template.md`。
 
-### 7. 更新任务状态
+### 9. 更新任务状态
 
 获取当前时间：
 
@@ -76,9 +93,31 @@ date "+%Y-%m-%d %H:%M:%S"
 - 追加：
   `- {yyyy-MM-dd HH:mm:ss} — **Implementation (Round {N})** by {agent} — Code implemented, {n} files modified, {n} tests passed → {implementation-artifact}`
 
-### 8. 告知用户
+如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续；执行前先读取 `.agents/rules/issue-sync.md`）：
+- 设置 `status: in-progress`，并按 `.agents/rules/issue-sync.md` 的 `in:` label 同步规则，基于分支改动精修 `in:` label（有映射时可增可删，无映射时仅补充）
+- 同步 `## 需求` 中已勾选项到 Issue body，并发布 `{implementation-artifact}` 评论
+- 创建或更新 `<!-- sync-issue:{task-id}:task -->` 评论（按 issue-sync.md 的 task.md 评论同步规则）
+
+### 10. 完成校验
+
+运行完成校验，确认任务产物和同步状态符合规范：
+
+```bash
+node .agents/scripts/validate-artifact.js gate implement-task .agents/workspace/active/{task-id} {implementation-artifact} --format text
+```
+
+处理结果：
+- 退出码 0（全部通过）-> 继续到「告知用户」步骤
+- 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
+- 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入
+
+将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
+
+### 11. 告知用户
+
+> 仅在校验通过后执行本步骤。
 
-输出实现摘要，并完整展示下一步代码审查的所有 TUI 命令格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。输出格式见 `reference/output-template.md`。
 
 ## 完成检查清单
 

package/templates/.agents/skills/implement-task/config/verify.json

@@ -0,0 +1,43 @@
+{
+  "skill": "implement-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "current_step",
+        "assigned_to"
+      ],
+      "expected_step": "implementation"
+    },
+    "artifact": {
+      "file_pattern": "implementation.md|implementation-r{N}.md",
+      "required_sections": [
+        "变更文件",
+        "关键代码说明",
+        "测试结果",
+        "与方案的差异",
+        "供审查关注的内容"
+      ],
+      "freshness_minutes": 30
+    },
+    "activity-log": {
+      "expected_action_pattern": "Implementation \\(Round \\d+\\)",
+      "freshness_minutes": 30
+    },
+    "github-sync": {
+      "when": "issue_number_exists",
+      "expected_status_label": "status: in-progress",
+      "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->",
+      "verify_comment_content": true,
+      "verify_task_comment_content": true,
+      "sync_checked_requirements": true,
+      "verify_issue_type": true,
+      "verify_milestone": true
+    }
+  }
+}

package/templates/.agents/skills/implement-task/reference/branch-management.md

@@ -0,0 +1,48 @@
+# Branch Management
+
+Read this file before ensuring the task branch.
+
+## Branch Naming Rule
+
+- Format: `{{project}}-{type}-{slug}`
+- project prefix: read the `project` field from `.agents/.airc.json`
+- `{type}`: read the `type` field from the task frontmatter
+- `{slug}`: derive a 3-6 word English kebab-case phrase from the task title
+
+## Branch Detection Flow
+
+Read these inputs first:
+- the `- **Branch**:` field under `## Context` in `task.md`
+- the current branch from `git branch --show-current`
+
+A recorded branch is valid when it has a non-empty value other than `TBD`, `to be created`, or `N/A`.
+
+Scenario A: `task.md` already records the task branch
+- if the current branch matches, continue
+- if it does not match, follow the "Create and Switch Commands" section below to switch to the recorded branch
+
+Scenario B: `task.md` has no task branch recorded
+- check whether the current branch follows the project naming convention (`{{project}}-{type}-{slug}`) and semantically belongs to this task
+- if yes: write the current branch name back to `task.md` and continue
+- if no: generate a new task branch name, create and switch using the "Create and Switch Commands" section below, then write it back to `task.md`
+
+## Create and Switch Commands
+
+Check branches in this order:
+
+```bash
+git branch --list {branch-name}
+git ls-remote --heads origin {branch-name}
+```
+
+- local branch exists: `git switch {branch-name}`
+- only remote branch exists: `git switch --track origin/{branch-name}`
+- neither exists: `git switch -c {branch-name}`
+
+If switching fails, stop and ask the user to resolve the branch or working tree conflict first.
+
+## task.md Write-back
+
+- update `- **Branch**: {branch-name}` under `## Context`
+- do not modify the other context fields
+- preserve the recorded branch value when updating task status later

package/templates/.agents/skills/implement-task/reference/branch-management.zh-CN.md

@@ -0,0 +1,49 @@
+# 分支管理
+
+在确保任务分支之前先读取本文件。
+
+## 分支名规则
+
+- 格式：`{{project}}-{type}-{slug}`
+- 项目前缀：读取 `.agents/.airc.json` 中的 `project`
+- `{type}`：读取 `task.md` frontmatter 中的 `type`
+- `{slug}`：根据任务标题提取 3-6 个英文关键词，转为 kebab-case
+
+## 分支检测流程
+
+先读取：
+- `task.md` 中 `## 上下文` 下的 `- **分支**：`
+- 当前分支：`git branch --show-current`
+
+有效已记录分支：
+- 有值，且不是 `待定`、`待创建`、`N/A` 或空字符串
+
+场景 A：`task.md` 已记录任务分支
+- 当前分支与记录值一致：直接继续
+- 当前分支不一致：按下方”创建与切换命令”章节切换到已记录分支
+
+场景 B：`task.md` 未记录任务分支
+- 判断当前分支是否符合项目分支命名规范（`{{project}}-{type}-{slug}`）且语义上属于当前任务
+- 符合：将当前分支名回写到 `task.md`，继续
+- 不符合：生成新的任务分支名，按下方”创建与切换命令”章节创建并切换，回写到 `task.md`
+
+## 创建与切换命令
+
+按以下顺序处理：
+
+```bash
+git branch --list {branch-name}
+git ls-remote --heads origin {branch-name}
+```
+
+- 本地分支已存在：`git switch {branch-name}`
+- 仅远程分支存在：`git switch --track origin/{branch-name}`
+- 本地和远程都不存在：`git switch -c {branch-name}`
+
+如果切换失败，立即停止并提示用户先处理工作区冲突或未解决的分支问题。
+
+## task.md 回写要求
+
+- 更新 `## 上下文` 中的 `- **分支**：{branch-name}`
+- 不修改其他上下文字段
+- 若本步骤已回写 `task.md`，后续更新任务状态时保留该分支值

package/templates/.agents/skills/implement-task/reference/output-template.md

@@ -0,0 +1,20 @@
+# Output Template
+
+When reporting that implementation is complete, use the following standard format:
+
+```text
+Task {task-id} implementation complete.
+
+Summary:
+- Implementation round: Round {implementation-round}
+- Files modified: {count}
+- All tests passed: {yes/no}
+
+Output files:
+- Implementation report: .agents/workspace/active/{task-id}/{implementation-artifact}
+
+Next step - code review:
+  - Claude Code / OpenCode: /review-task {task-id}
+  - Gemini CLI: /{{project}}:review-task {task-id}
+  - Codex CLI: $review-task {task-id}
+```

package/templates/.agents/skills/implement-task/reference/output-template.zh-CN.md

@@ -0,0 +1,20 @@
+# 输出模板
+
+向用户汇报实现完成时，使用以下标准格式：
+
+```text
+任务 {task-id} 实现完成。
+
+摘要：
+- 实现轮次：Round {implementation-round}
+- 修改文件：{数量}
+- 所有测试通过：{是/否}
+
+产出文件：
+- 实现报告：.agents/workspace/active/{task-id}/{implementation-artifact}
+
+下一步 - 代码审查：
+  - Claude Code / OpenCode：/review-task {task-id}
+  - Gemini CLI：/{{project}}:review-task {task-id}
+  - Codex CLI：$review-task {task-id}
+```