@fitlab-ai/agent-infra 0.5.5 → 0.5.7

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

@@ -0,0 +1,95 @@
+---
+name: post-release
+description: "Run post-release follow-up tasks"
+---
+
+# Post-release Tasks
+
+Run the standard follow-up workflow after a release tag has been pushed.
+
+## Execution Flow
+
+### 1. Detect the Latest Released Version
+
+```bash
+git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1
+```
+
+- Detect the latest `vX.Y.Z` tag, then strip the `v` prefix when you need the version number in later steps
+- If no tag is found, error: "No released version tag found. Please create and push a release tag first."
+
+### 2. Verify Clean Workspace
+
+```bash
+git status --short
+```
+
+- If there are uncommitted changes, error: "Workspace has uncommitted changes. Please commit or stash first."
+
+### 3. Prepare the Next Development Version
+
+<!-- TODO: Replace this step with your project's version bump command -->
+
+```bash
+# TODO: Replace with your project's post-release version bump command
+# npm version prerelease --preid=alpha --no-git-tag-version
+```
+
+- Update lockfiles or generated version metadata if your project needs them
+- Keep all version references in sync after the bump
+
+### 4. Rebuild Generated Artifacts
+
+<!-- TODO: Replace this step with your project's rebuild command -->
+
+```bash
+# TODO: Replace with your project's artifact rebuild command
+```
+
+- Rebuild any generated files, embedded assets, or inline templates affected by the new version
+- If your project has no generated artifacts, remove this step in the project-specific copy
+
+### 5. Run Other Post-release Tasks (Optional)
+
+<!-- TODO: Add project-specific follow-up tasks such as demo capture, docs publishing, or downstream notifications -->
+
+- Examples: record a terminal demo, refresh a docs site, notify downstream teams, update release dashboards
+- If there are no extra tasks, remove this step in the project-specific copy
+
+### 6. Create the Follow-up Commit
+
+```bash
+git add -A
+git commit -m "chore: prepare next dev iteration after v{released-version}"
+```
+
+### 7. Output Summary
+
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
+
+```
+Post-release tasks completed.
+
+Summary:
+- Released version: {released-version}
+- Next development version: {new-version}
+- Extra tasks completed: {summary}
+
+Next step (manual):
+- Push branch: git push origin {current-branch}
+```
+
+## Notes
+
+1. **No arguments**: Detect the released version from the latest tag instead of asking the user to repeat it
+2. **Clean workspace required**: Avoid mixing unrelated edits into the post-release commit
+3. **Project-specific customization**: Replace the TODO steps with the commands your project actually needs
+4. **Local-only workflow**: This skill prepares local changes and does not push automatically
+
+## Error Handling
+
+- No release tag found: Prompt the user to finish the release first
+- Dirty workspace: Prompt the user to commit or stash changes
+- Version bump failed: Display the command error and stop
+- Artifact rebuild failed: Display the build error and stop
+- Git commit failed: Display the error and leave the workspace intact for manual recovery

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

@@ -0,0 +1,95 @@
+---
+name: post-release
+description: "执行版本发布后的后处理工作"
+---
+
+# 发布后处理
+
+在版本标签推送完成后，执行标准化的发布后收尾流程。
+
+## 执行流程
+
+### 1. 检测最新发布版本
+
+```bash
+git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1
+```
+
+- 检测最新 `vX.Y.Z` 标签，并在后续步骤中去除 `v` 前缀得到版本号
+- 如果没有找到标签，报错："No released version tag found. Please create and push a release tag first."
+
+### 2. 验证工作区干净
+
+```bash
+git status --short
+```
+
+- 如果存在未提交变更，报错："Workspace has uncommitted changes. Please commit or stash first."
+
+### 3. 准备下一个开发版本
+
+<!-- TODO: 将此步骤替换为你的项目版本 bump 命令 -->
+
+```bash
+# TODO: 替换为你的项目发布后版本 bump 命令
+# npm version prerelease --preid=alpha --no-git-tag-version
+```
+
+- 如果项目需要，记得同步锁文件或其他版本元数据
+- 版本 bump 后保持所有版本引用一致
+
+### 4. 重新生成构建产物
+
+<!-- TODO: 将此步骤替换为你的项目产物重建命令 -->
+
+```bash
+# TODO: 替换为你的项目产物重建命令
+```
+
+- 重建所有受新版本号影响的生成文件、内嵌产物或内联模板
+- 如果项目没有生成产物，请在项目特化版本中删除此步骤
+
+### 5. 执行其他发布后任务（可选）
+
+<!-- TODO: 添加项目特定的发布后任务，例如录制演示、发布文档站或通知下游 -->
+
+- 示例：录制终端演示、刷新文档站、通知下游团队、更新发布面板
+- 如果没有额外任务，请在项目特化版本中删除此步骤
+
+### 6. 创建后处理提交
+
+```bash
+git add -A
+git commit -m "chore: prepare next dev iteration after v{released-version}"
+```
+
+### 7. 输出摘要
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
+
+```
+发布后处理已完成。
+
+结果摘要：
+- 已发布版本：{released-version}
+- 新开发版本：{new-version}
+- 额外任务完成情况：{summary}
+
+下一步（手动执行）：
+- 推送分支：git push origin {current-branch}
+```
+
+## 注意事项
+
+1. **无参数设计**：从最新标签自动检测已发布版本，不要求用户重复输入
+2. **需要干净工作区**：避免把无关改动带入发布后提交
+3. **项目定制**：将带 TODO 的步骤替换为你的项目实际命令
+4. **仅本地执行**：本技能只准备本地变更，不自动推送
+
+## 错误处理
+
+- 未找到发布标签：提示用户先完成发布
+- 工作区不干净：提示先提交或暂存
+- 版本 bump 失败：显示命令错误并停止
+- 产物重建失败：显示构建错误并停止
+- Git 提交失败：显示错误并保留当前工作区供人工处理

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

@@ -62,8 +62,8 @@ Update task.md:
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
 - Read `.agents/rules/issue-sync.md` before syncing, and complete upstream repository detection plus permission detection
 - Set `status: in-progress` by following issue-sync.md
-- Publish the `{refinement-artifact}` comment
 - Create or update the `<!-- sync-issue:{task-id}:task -->` comment (follow the task.md comment sync rule in issue-sync.md)
+- Publish the `{refinement-artifact}` comment
 
 ### 7. Verification Gate
 
@@ -84,7 +84,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > 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.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 After summarizing the fixes, present the next step:
 

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

@@ -62,8 +62,8 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
 - 执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测
 - 按 issue-sync.md 设置 `status: in-progress`
-- 发布 `{refinement-artifact}` 评论
 - 创建或更新 `<!-- sync-issue:{task-id}:task -->` 评论（按 issue-sync.md 的 task.md 评论同步规则）
+- 发布 `{refinement-artifact}` 评论
 
 ### 7. 完成校验
 
@@ -84,7 +84,7 @@ node .agents/scripts/validate-artifact.js gate refine-task .agents/workspace/act
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 输出修复摘要后，展示下一步：
 

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

@@ -62,7 +62,7 @@ Title changes require write permission. Follow the permission-degradation rules
 
 ### 5. Inform User
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 If the skill updated an Issue title, explain that no extra sync command is required; continue with the workflow skill that matches the task's current stage.
 

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

@@ -62,7 +62,7 @@ Issue/PR #{id} 分析结果：
 
 ### 5. 告知用户
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 如果修改了 Issue 标题，提示无需额外同步命令；后续按任务当前阶段继续执行对应工作流技能。
 

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

@@ -122,7 +122,7 @@ The script is responsible for:
 
 ### 9. Output Summary
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 ```
 Release v{version} prepared.
@@ -146,6 +146,11 @@ Next steps (manual):
    - Claude Code / OpenCode: /create-release-note {version}
    - Gemini CLI: /{{project}}:create-release-note {version}
    - Codex CLI: $create-release-note {version}
+
+4. (Optional) Run post-release follow-up tasks:
+   - Claude Code / OpenCode: /post-release
+   - Gemini CLI: /{{project}}:post-release
+   - Codex CLI: $post-release
 ```
 
 ### Rollback Instructions

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

@@ -122,7 +122,7 @@ bash .agents/skills/release/scripts/manage-milestones.sh "$MAJOR" "$MINOR" "$PAT
 
 ### 9. 输出摘要
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ```
 版本 v{version} 已准备好发布。
@@ -146,6 +146,11 @@ bash .agents/skills/release/scripts/manage-milestones.sh "$MAJOR" "$MINOR" "$PAT
    - Claude Code / OpenCode：/create-release-note {version}
    - Gemini CLI：/{{project}}:create-release-note {version}
    - Codex CLI：$create-release-note {version}
+
+4.（可选）执行发布后处理：
+   - Claude Code / OpenCode：/post-release
+   - Gemini CLI：/{{project}}:post-release
+   - Codex CLI：$post-release
 ```
 
 ### 回滚说明

package/templates/.agents/skills/release/scripts/manage-milestones.sh

@@ -0,0 +1,6 @@
+#!/bin/sh
+
+set -e
+
+echo "Release milestone management skipped: this code platform does not provide a built-in milestone adapter." >&2
+exit 0

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

@@ -113,7 +113,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > 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.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 Output format:
 
@@ -137,7 +137,7 @@ Next step - check task status:
 - [ ] Restored `task.md` and every available artifact file
 - [ ] Updated the restored task.md
 - [ ] Ran and passed the verification gate
-- [ ] Showed the next-step commands in every TUI format
+- [ ] Showed the next-step commands in every TUI format, including any custom TUIs
 
 ## STOP
 

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

@@ -113,7 +113,7 @@ node .agents/scripts/validate-artifact.js gate restore-task .agents/workspace/ac
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 输出格式：
 
@@ -137,7 +137,7 @@ node .agents/scripts/validate-artifact.js gate restore-task .agents/workspace/ac
 - [ ] 已还原 `task.md` 和所有可用产物文件
 - [ ] 已更新恢复后的 task.md
 - [ ] 已运行并通过完成校验
-- [ ] 已向用户展示所有 TUI 格式的下一步命令
+- [ ] 已向用户展示所有 TUI 格式的下一步命令（含自定义 TUI）
 
 ## 停止
 

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

@@ -56,8 +56,8 @@ Update task.md and append:
 If task.md contains a valid `issue_number`, perform these sync actions (skip and continue on any failure):
 - Read `.agents/rules/issue-sync.md` before syncing, and complete upstream repository detection plus permission detection
 - Set `status: in-progress` by following issue-sync.md
-- Publish the `{review-artifact}` comment
 - Create or update the `<!-- sync-issue:{task-id}:task -->` comment (follow the task.md comment sync rule in issue-sync.md)
+- Publish the `{review-artifact}` comment
 
 ### 7. Verification Gate
 
@@ -86,7 +86,7 @@ Choose exactly one branch based on the findings:
 
 > The full four-branch output templates, selection rules, and prohibition clauses live in `reference/output-templates.md`. Read `reference/output-templates.md` before reporting the review result.
 
-Include all TUI command formats in the next-step output.
+Include all TUI command formats in the next-step output. 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).
 
 ## Completion Checklist
 
@@ -94,7 +94,7 @@ Include all TUI command formats in the next-step output.
 - [ ] Created `{review-artifact}`
 - [ ] Updated task.md and appended the Activity Log entry
 - [ ] Chose exactly one verdict branch in the user output
-- [ ] Informed the user of the next step (must include all TUI command formats; do not filter)
+- [ ] Informed the user of the next step (must include all TUI command formats, including any custom TUIs; do not filter)
 
 ## Notes
 

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

@@ -56,8 +56,8 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
 - 执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测
 - 按 issue-sync.md 设置 `status: in-progress`
-- 发布 `{review-artifact}` 评论
 - 创建或更新 `<!-- sync-issue:{task-id}:task -->` 评论（按 issue-sync.md 的 task.md 评论同步规则）
+- 发布 `{review-artifact}` 评论
 
 ### 7. 完成校验
 
@@ -86,7 +86,7 @@ node .agents/scripts/validate-artifact.js gate review-task .agents/workspace/act
 
 > 完整的 4 分支输出模板、判断规则和禁止条款见 `reference/output-templates.md`。向用户汇报审查结论前先读取 `reference/output-templates.md`。
 
-向用户展示下一步时，必须包含所有 TUI 命令格式。
+向用户展示下一步时，必须包含所有 TUI 命令格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ## 完成检查清单
 
@@ -94,7 +94,7 @@ node .agents/scripts/validate-artifact.js gate review-task .agents/workspace/act
 - [ ] 已创建 `{review-artifact}`
 - [ ] 已更新 task.md 并追加 Activity Log
 - [ ] 用户输出中只选择了一个审查结论分支
-- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，不要筛选）
+- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，含自定义 TUI，不要筛选）
 
 ## 注意事项
 

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

@@ -49,7 +49,7 @@ If tests fail:
 
 After tests pass, suggest committing the changes:
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 ```
 Next step - commit changes:

package/templates/.agents/skills/test/SKILL.zh-CN.md

@@ -49,7 +49,7 @@ description: "执行项目完整测试流程"
 
 测试通过后，建议提交变更：
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ```
 下一步 - 提交代码：

package/templates/.agents/skills/test-integration/SKILL.en.md

@@ -50,7 +50,7 @@ If tests fail:
 
 After tests pass, suggest committing the changes:
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 ```
 Next step - commit changes:

package/templates/.agents/skills/test-integration/SKILL.zh-CN.md

@@ -50,7 +50,7 @@ description: "执行项目集成测试流程"
 
 测试通过后，建议提交变更：
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ```
 下一步 - 提交代码：

package/templates/.agents/skills/update-agent-infra/SKILL.en.md

@@ -24,7 +24,11 @@ Execute the following command to handle all deterministic steps at once:
 node .agents/skills/update-agent-infra/scripts/sync-templates.js
 ```
 
-The script reads `.agents/.airc.json`, automatically locates the installed `@fitlab-ai/agent-infra/templates/` directory via npm, and performs:
+The script reads `.agents/.airc.json` and automatically locates the installed
+`@fitlab-ai/agent-infra/templates/` directory via npm. Before syncing, it merges
+external template sources from `templates.sources`; built-in templates win over
+same-path external files, and later external sources win over earlier external
+sources. Conflicts are recorded in the report. The script then performs:
 - detect the template source version
 - File registry sync (`defaults.json` → `.agents/.airc.json`)
 - All managed files (language selection → exclude merged/ejected → placeholder rendering → overwrite)
@@ -37,6 +41,9 @@ The script outputs JSON to stdout. Parse and record the report.
 - `error`: error message (if non-empty, stop and report)
 - `templateVersion`: current template source version
 - `templateRoot`: absolute path to the template file root directory
+- `templateSources.conflicts`: external template source conflicts; explicitly
+  list these in the report so users know which files were ignored because a
+  built-in template or later external source won
 - `managed.written` / `managed.created`: updated / newly created managed files
 - `merged.pending`: list of merged files for AI to process
   - Each item has `target` (project-relative path) and `template` (template-root-relative path)
@@ -124,6 +131,7 @@ warning to the end of the report:
 Based on the script report and merged results, output a complete update report including:
 - Template version change
 - File registry additions
+- External template source conflicts, when `templateSources.conflicts` is non-empty
 - Managed file change details (updated, created, skipped merged files)
 - Merged file results (conflicts, remaining TODOs)
 - Ejected file processing
@@ -131,7 +139,7 @@ Based on the script report and merged results, output a complete update report i
 
 If there are changes to submit, add:
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for 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).
 
 ```
 Next step - commit changes:

package/templates/.agents/skills/update-agent-infra/SKILL.zh-CN.md

@@ -22,7 +22,7 @@ description: "更新项目 AI 协作配置"
 node .agents/skills/update-agent-infra/scripts/sync-templates.js
 ```
 
-脚本读取 `.agents/.airc.json`，并通过 npm 自动定位已安装的 `@fitlab-ai/agent-infra/templates/` 目录，然后自动完成：
+脚本读取 `.agents/.airc.json`，并通过 npm 自动定位已安装的 `@fitlab-ai/agent-infra/templates/` 目录。同步前会合并 `templates.sources` 中配置的外部模板源；相同文件以内置模板为准，多个外部源之间后者覆盖前者，冲突会写入报告。然后自动完成：
 - 检测模板源版本
 - 同步文件注册表（`defaults.json` → `.agents/.airc.json`）
 - 处理所有 managed 文件（语言选择 → 排除 merged/ejected → 占位符渲染 → 覆盖写入）
@@ -35,6 +35,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 - `error`：错误信息（如非空则停止并报告）
 - `templateVersion`：模板源当前版本
 - `templateRoot`：模板文件根目录绝对路径
+- `templateSources.conflicts`：外部模板源冲突列表；报告中必须显式展示，说明哪些文件因内置模板或后续外部源获胜而被忽略
 - `managed.written` / `managed.created`：已更新/新建的 managed 文件
 - `merged.pending`：需要 AI 处理的 merged 文件列表
   - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
@@ -114,6 +115,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 基于脚本报告和 merged 合并结果，输出完整的更新报告，包括：
 - 模板版本变更
 - 文件注册表新增条目
+- 外部模板源冲突（如 `templateSources.conflicts` 非空，必须逐项列出）
 - managed 文件变更明细（已更新、新建、跳过的 merged 文件）
 - merged 文件合并结果（冲突、残余 TODO）
 - ejected 文件处理
@@ -121,7 +123,7 @@ node .agents/skills/update-agent-infra/scripts/sync-templates.js
 
 如有变更需要提交，追加：
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。
 
 ```
 下一步 - 提交代码：