@fitlab-ai/agent-infra 0.3.0

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

@@ -0,0 +1,142 @@
+---
+name: sync-pr
+description: >
+  将任务处理进度同步到对应的 Pull Request 评论。
+  当用户要求同步进度到 PR 时触发。参数：task-id。
+---
+
+# 同步进度到 PR
+
+将任务处理进度同步到关联的 Pull Request。参数：task-id。
+
+## 执行流程
+
+### 1. 验证任务存在
+
+按优先顺序搜索任务：
+- `.agent-workspace/active/{task-id}/task.md`
+- `.agent-workspace/completed/{task-id}/task.md`
+- `.agent-workspace/blocked/{task-id}/task.md`
+
+注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
+
+### 2. 读取任务信息
+
+从 task.md 中提取：
+- `pr_number`（必需 —— 如果缺失，提示用户）
+- 任务标题、描述、状态
+- `current_step`、`created_at`、`updated_at`
+- `issue_number`（如适用）
+
+### 3. 读取上下文文件
+
+检查并读取（如存在）：
+- 最高轮次的 `analysis.md` / `analysis-r{N}.md` - 需求分析
+- 最高轮次的 `plan.md` / `plan-r{N}.md` - 技术方案
+- `implementation.md`、`implementation-r{N}.md` - 实现报告
+- `refinement.md`、`refinement-r{N}.md` - 修复报告
+- `review.md`、`review-r{N}.md` - 审查报告
+
+### 4. 生成进度摘要
+
+生成面向**代码审查者**的清晰进度摘要：
+
+```markdown
+## 开发进度更新
+
+**任务 ID**：{task-id}
+**更新时间**：{当前时间}
+**状态**：{状态描述}
+
+### 已完成步骤
+
+- [x] 需求分析 - {完成时间}
+  - {1-2 个关键要点}
+- [x] 技术设计 - {完成时间}
+  - {关键决策}
+- [x] 实现 - {完成时间}
+  - 修改文件数：{数量}
+  - 新增测试数：{数量}
+- [ ] 代码审查（进行中）
+- [ ] 最终合并
+
+### 当前进度
+
+{当前步骤的详细描述}
+
+### 下一步
+
+{接下来需要做什么}
+
+### 技术亮点
+
+{供审查者参考的关键技术决策和实现细节}
+
+### 相关文档
+
+- 任务：`.agent-workspace/{status}/{task-id}/task.md`
+- 分析：`.agent-workspace/{status}/{task-id}/{analysis-artifact}`
+- 方案：`.agent-workspace/{status}/{task-id}/{plan-artifact}`
+- 实现：`.agent-workspace/{status}/{task-id}/{implementation-artifact}`
+- 修复：`.agent-workspace/{status}/{task-id}/{refinement-artifact}`（如存在）
+
+---
+*由 AI 自动生成 - [任务管理](.agents/README.md)*
+```
+
+**摘要原则**：
+- **面向审查者**：突出技术决策和实现细节
+- **简洁**：每个阶段仅提取关键要点
+- **逻辑清晰**：按时间顺序呈现进度
+- **便于审查**：解释关键变更的原因
+
+### 5. 发布到 PR
+
+```bash
+gh pr comment {pr-number} --body "$(cat <<'EOF'
+{生成的摘要}
+EOF
+)"
+```
+
+### 6. 更新任务状态
+
+获取当前时间：
+
+```bash
+date "+%Y-%m-%d %H:%M:%S"
+```
+
+在 task.md 中添加或更新 `last_synced_to_pr_at` 字段为 `{当前时间}`。
+- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
+  ```
+  - {yyyy-MM-dd HH:mm:ss} — **Sync to PR** by {agent} — Progress synced to PR #{pr-number}
+  ```
+
+### 7. 告知用户
+
+```
+进度已同步到 PR #{pr-number}。
+
+已同步内容：
+- 已完成步骤：{数量}
+- 当前状态：{状态}
+- 下一步：{描述}
+
+查看：https://github.com/{owner}/{repo}/pull/{pr-number}
+```
+
+## 注意事项
+
+1. **需要 PR 编号**：任务的 task.md 中必须有 `pr_number`。如果缺失，提示用户。
+2. **受众**：`sync-pr` 技能面向代码审查者；`sync-issue` 技能面向利益相关者。关注点不同。
+3. **同步时机**：在完成重要阶段后同步，而不是每个小变更后都同步。
+4. **避免刷屏**：不要同步过于频繁 —— 合并更新内容。
+
+## 错误处理
+
+- 任务未找到：提示 "Task {task-id} not found"
+- 缺少 PR 编号：提示 "Task has no pr_number field"
+- PR 未找到：提示 "PR #{number} not found"
+- PR 已关闭：提示 "PR #{number} is already closed"
+- gh 认证失败：提示 "Please check GitHub CLI authentication"

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

@@ -0,0 +1,61 @@
+---
+name: test
+description: >
+  Execute the project's full test workflow (compilation check + unit tests).
+  Triggered when the user requests running tests or verifying code quality.
+---
+
+# Run Tests
+
+Execute the project's full test workflow including compilation checks and unit tests.
+
+<!-- TODO: Replace the commands below with your project's actual commands -->
+
+## 1. Compilation / Type Check
+
+```bash
+# TODO: Replace with your project's compilation command
+# npx tsc --noEmit       (TypeScript)
+# mvn compile             (Maven)
+# go build ./...          (Go)
+# make build              (generic)
+```
+
+Confirm no compilation errors.
+
+## 2. Run All Unit Tests
+
+```bash
+# TODO: Replace with your project's test command
+# npm test                (Node.js)
+# mvn test                (Maven)
+# pytest                  (Python)
+# go test ./...           (Go)
+```
+
+## 3. Output Results
+
+Report test result summary:
+- Total tests run
+- Passing count
+- Failing count (with details for each failure)
+- Test coverage (if configured)
+
+## Failure Handling
+
+If tests fail:
+- Output failure details and suggested fix direction
+- Do NOT auto-fix code - wait for user decision
+
+## Next Steps
+
+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.
+
+```
+Next step - commit changes:
+  - Claude Code / OpenCode: /commit
+  - Gemini CLI: /{{project}}:commit
+  - Codex CLI: $commit
+```

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

@@ -0,0 +1,61 @@
+---
+name: test
+description: >
+  执行项目完整测试流程（编译检查 + 单元测试）。
+  当用户要求运行测试或验证代码质量时触发。
+---
+
+# 执行测试
+
+执行项目的完整测试流程，包括编译检查和单元测试。
+
+<!-- TODO: 将以下命令替换为你的项目实际命令 -->
+
+## 1. 编译 / 类型检查
+
+```bash
+# TODO: 替换为你的项目编译命令
+# npx tsc --noEmit       (TypeScript)
+# mvn compile             (Maven)
+# go build ./...          (Go)
+# make build              (通用)
+```
+
+确认无编译错误。
+
+## 2. 运行所有单元测试
+
+```bash
+# TODO: 替换为你的项目测试命令
+# npm test                (Node.js)
+# mvn test                (Maven)
+# pytest                  (Python)
+# go test ./...           (Go)
+```
+
+## 3. 输出结果
+
+报告测试结果摘要：
+- 运行的总测试数
+- 通过数量
+- 失败数量（包含每个失败的详情）
+- 测试覆盖率（如已配置）
+
+## 失败处理
+
+如果测试失败：
+- 输出失败详情和建议的修复方向
+- 不要自动修复代码 —— 等待用户决定
+
+## 后续步骤
+
+测试通过后，建议提交变更：
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+```
+下一步 - 提交代码：
+  - Claude Code / OpenCode：/commit
+  - Gemini CLI：/{{project}}:commit
+  - Codex CLI：$commit
+```

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

@@ -0,0 +1,70 @@
+---
+name: test-integration
+description: >
+  Execute the project's integration test workflow.
+  Triggered when the user requests running integration tests
+  or end-to-end verification.
+---
+
+# Run Integration Tests
+
+Execute the project's integration test workflow for end-to-end verification.
+
+<!-- TODO: Replace the commands below with your project's actual commands -->
+
+## 1. Verify Build Artifacts
+
+Ensure the project has been built before running integration tests.
+
+```bash
+# TODO: Replace with your project's build verification
+# ls build/              (check build output exists)
+# npm run build          (Node.js)
+# mvn package -DskipTests  (Maven)
+```
+
+If build artifacts don't exist, prompt user to run the test skill first.
+
+## 2. Run Integration Tests
+
+```bash
+# TODO: Replace with your project's integration test command
+# npm run test:integration    (Node.js)
+# mvn verify                  (Maven)
+# pytest tests/integration/   (Python)
+# go test -tags=integration ./...  (Go)
+```
+
+## 3. Output Results
+
+Report results:
+- Tests run / passed / failed
+- Environment issues (if any)
+- Failure details (if any)
+
+## Failure Handling
+
+If tests fail:
+- Output failure details
+- Check for environment issues (ports in use, services not running, etc.)
+- Do NOT auto-fix - wait for user decision
+
+## Next Steps
+
+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.
+
+```
+Next step - commit changes:
+  - Claude Code / OpenCode: /commit
+  - Gemini CLI: /{{project}}:commit
+  - Codex CLI: $commit
+```
+
+## Notes
+
+1. **Prerequisites**: Usually requires a successful build first (run the test skill)
+2. **Environment**: Integration tests may require external services (databases, APIs, etc.)
+3. **Timeouts**: Integration tests typically take longer; be patient
+4. **Cleanup**: Ensure test environment is cleaned up after tests complete

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

@@ -0,0 +1,69 @@
+---
+name: test-integration
+description: >
+  执行项目集成测试流程。
+  当用户要求运行集成测试或端到端验证时触发。
+---
+
+# 运行集成测试
+
+执行项目的集成测试流程，进行端到端验证。
+
+<!-- TODO: 将以下命令替换为你的项目实际命令 -->
+
+## 1. 验证构建产物
+
+在运行集成测试前确保项目已构建。
+
+```bash
+# TODO: 替换为你的项目构建验证命令
+# ls build/              (检查构建输出是否存在)
+# npm run build          (Node.js)
+# mvn package -DskipTests  (Maven)
+```
+
+如果构建产物不存在，提示用户先执行 test 技能。
+
+## 2. 运行集成测试
+
+```bash
+# TODO: 替换为你的项目集成测试命令
+# npm run test:integration    (Node.js)
+# mvn verify                  (Maven)
+# pytest tests/integration/   (Python)
+# go test -tags=integration ./...  (Go)
+```
+
+## 3. 输出结果
+
+报告结果：
+- 运行/通过/失败的测试数
+- 环境问题（如有）
+- 失败详情（如有）
+
+## 失败处理
+
+如果测试失败：
+- 输出失败详情
+- 检查环境问题（端口占用、服务未运行等）
+- 不要自动修复 —— 等待用户决定
+
+## 后续步骤
+
+测试通过后，建议提交变更：
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+```
+下一步 - 提交代码：
+  - Claude Code / OpenCode：/commit
+  - Gemini CLI：/{{project}}:commit
+  - Codex CLI：$commit
+```
+
+## 注意事项
+
+1. **前置条件**：通常需要先成功构建（执行 test 技能）
+2. **环境**：集成测试可能需要外部服务（数据库、API 等）
+3. **超时**：集成测试通常耗时较长；请耐心等待
+4. **清理**：确保测试完成后清理测试环境

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

@@ -0,0 +1,136 @@
+---
+name: update-agent-infra
+description: >
+  Update the current project's AI collaboration infrastructure
+  and project governance to match the latest agent-infra
+  templates. Intelligently merges template changes while
+  preserving project-specific customizations.
+---
+
+# Update Project
+
+## Execution constraints
+
+1. **Script-driven deterministic steps**: managed / ejected file processing,
+   registry sync, and config updates are ALL handled by `sync-templates.js`.
+   Never process these files manually one by one.
+   The script guarantees atomicity and idempotency.
+
+2. **No subagent delegation**: Phase B (merged file intelligent merging) MUST
+   be executed directly in the main conversation. Never delegate to subagents.
+   Subagents have limited context and frequently misjudge file content equality.
+
+## Phase A: Run sync script (deterministic)
+
+Execute the following command to handle all deterministic steps at once:
+
+```bash
+node .agents/skills/update-agent-infra/scripts/sync-templates.js
+```
+
+The script reads `.airc.json` (including `templateSource`, default `templates/`) and automatically performs:
+- git pull to fetch latest templates
+- File registry sync (`defaults.json` → `.airc.json`)
+- All managed files (language selection → exclude merged/ejected → placeholder rendering → overwrite)
+- Ejected files (create only on first install)
+- `.airc.json` update (`templateVersion`, file lists)
+
+The script outputs JSON to stdout. Parse and record the report.
+
+**Key fields**:
+- `error`: error message (if non-empty, stop and report)
+- `templateVersion`: current template source version
+- `templateRoot`: absolute path to the template file root directory
+- `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)
+- `registryAdded`: newly added file registry entries
+- `selfUpdate`: whether this is a self-update scenario
+- `configUpdated`: whether `.airc.json` was updated
+
+## Phase B: Process merged files (AI intelligent merge)
+
+Process each item in the report's `merged.pending` list:
+
+1. Read the template file from `<templateRoot>/<template>`
+2. Render placeholders: replace double-brace `project` and `org` placeholders with actual values from .airc.json
+3. Read the current local file (`<project-root>/<target>`)
+
+**If the local file does not exist** (first-time setup), write the rendered
+template directly and skip merge.
+
+If the local file exists, execute the following merge algorithm:
+
+### B.1 Use template as the base
+
+Use the rendered new template as the output base. The template represents
+best practices; its structure and content are authoritative.
+
+### B.2 Extract deltas from local file
+
+Scan the local file for content that goes beyond the template (user deltas):
+- **Filled TODOs**: Template TODO placeholders replaced with actual content
+- **Added sections**: Content in local file that does not exist in template
+- **Extended content**: Supplementary details added to existing template sections
+
+### B.3 Merge deltas into template
+
+Insert extracted deltas into appropriate positions in the new template:
+- Filled TODOs → replace the corresponding TODO placeholder
+- Added sections → insert at the most relevant location
+- Extended content → merge into the corresponding section
+
+### B.4 Full read-through
+
+Review the merged file for logical completeness. Verify:
+- Deltas are placed correctly
+- No duplicate content
+- Document structure is coherent
+
+### B.5 Conflict handling
+
+When user-modified content conflicts with new template content:
+- Keep the template version (template authority principle)
+- Flag the conflict in the report so the user can confirm
+
+### B.6 Remaining TODOs
+
+After merge, if template TODOs remain unfilled by local file content,
+flag them in the report for the user.
+
+## Phase C: Verify and output report
+
+**Direction check**: Spot-check with `git diff` that the change direction
+is correct (correct: new template content → local; wrong: reverting rendered
+content back to placeholders). If wrong-direction changes are found,
+pause and investigate.
+
+### Self-update detection
+
+Check whether `git diff` includes changes to
+`.agents/skills/update-agent-infra/SKILL.md`.
+If this file was modified during the current update, append the following
+warning to the end of the report:
+
+```
+⚠ The update-agent-infra skill itself was updated.
+  Please run /update-agent-infra again to ensure all new logic takes effect.
+```
+
+> **Rationale**: The current execution used the old skill logic; the new version
+> may contain additional processing steps. Running again ensures the new logic
+> is fully applied.
+> Alternatively, users can run `ai update` before executing the skill to
+> pre-update the seed files and avoid the need for a second run.
+
+### Output report
+
+Based on the script report and merged results, output a complete update report including:
+- Template version change
+- File registry additions
+- Managed file change details (updated, created, skipped merged files)
+- Merged file results (conflicts, remaining TODOs)
+- Ejected file processing
+- Self-update detection result
+
+Output the report, then **STOP** — do not make other changes to the project.

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

@@ -0,0 +1,124 @@
+---
+name: update-agent-infra
+description: >
+  更新当前项目的 AI 协作基础设施和项目治理配置，使其与最新的 agent-infra 模板保持一致。
+  智能合并模板变更，同时保留项目特定的定制内容。
+---
+
+# 更新项目
+
+## 执行约束
+
+1. **确定性步骤脚本化**：managed / ejected 文件处理、注册表同步、配置更新
+   全部由 `sync-templates.js` 脚本执行，不得逐文件手工处理。
+   脚本保证原子性和幂等性。
+
+2. **禁止委托子代理**：阶段 B（merged 文件智能合并）必须在主会话中直接执行，
+   不得委托给子代理。子代理上下文有限，容易误判文件内容。
+
+## 阶段 A：运行同步脚本（确定性）
+
+执行以下命令，一次性处理所有确定性步骤：
+
+```bash
+node .agents/skills/update-agent-infra/scripts/sync-templates.js
+```
+
+脚本读取 `.airc.json`（含 `templateSource`，默认 `templates/`），自动完成：
+- git pull 拉取最新模板
+- 同步文件注册表（`defaults.json` → `.airc.json`）
+- 处理所有 managed 文件（语言选择 → 排除 merged/ejected → 占位符渲染 → 覆盖写入）
+- 处理 ejected 文件（仅首次安装时创建）
+- 更新 `.airc.json`（`templateVersion`、文件列表）
+
+脚本输出 JSON 到 stdout，解析并记录报告内容。
+
+**关键字段**：
+- `error`：错误信息（如非空则停止并报告）
+- `templateVersion`：模板源当前版本
+- `templateRoot`：模板文件根目录绝对路径
+- `managed.written` / `managed.created`：已更新/新建的 managed 文件
+- `merged.pending`：需要 AI 处理的 merged 文件列表
+  - 每项包含 `target`（项目中的目标路径）和 `template`（模板根目录下的相对路径）
+- `registryAdded`：新增的文件注册条目
+- `selfUpdate`：是否为自更新模式
+- `configUpdated`：`.airc.json` 是否已更新
+
+## 阶段 B：处理 merged 文件（AI 智能合并）
+
+根据报告中 `merged.pending` 列表，逐个文件处理。对于每个条目：
+
+1. 从 `<templateRoot>/<template>` 读取模板文件
+2. 渲染占位符：将双花括号包裹的 `project` 和 `org` 占位符替换为 .airc.json 中的实际值
+3. 读取本地当前文件（`<项目根>/<target>`）
+
+**如果本地文件不存在**（首次安装），直接写入渲染后的模板，跳过合并。
+
+如果本地文件存在，执行以下合并算法：
+
+### B.1 以模板为基底
+
+使用渲染后的新模板作为输出的基底。模板代表最佳实践，其结构和内容具有权威性。
+
+### B.2 从本地文件萃取增量
+
+扫描本地文件，找出比模板内容"多"的部分（用户增量）：
+- **已填充的 TODO**：模板中的 TODO 占位符在本地文件中被替换为实际内容
+- **新增段落/章节**：本地文件中存在但模板中不存在的内容
+- **扩展内容**：对模板现有内容的补充说明
+
+### B.3 合入新模板
+
+将萃取的增量合入新模板的适当位置：
+- 已填充的 TODO → 替换对应的 TODO 占位符
+- 新增段落 → 插入最相关的位置
+- 扩展内容 → 合入对应章节
+
+### B.4 通读验证
+
+整体检查合并后文件的逻辑完整性，确保：
+- 增量合入位置正确
+- 无重复内容
+- 文档结构连贯
+
+### B.5 冲突处理
+
+当本地文件修改过的内容与模板新内容冲突时：
+- 保留模板版本（模板权威性原则）
+- 在报告中提示用户该冲突，以便用户确认
+
+### B.6 残余 TODO 提示
+
+合并完成后，如果仍有模板 TODO 未被本地文件的内容填充，在报告中提示用户。
+
+## 阶段 C：验证与输出报告
+
+**方向检查**：用 `git diff` 抽查变更方向是否正确。
+正确方向：模板新内容 → 本地；错误方向：将已渲染内容退化回占位符。
+如果发现错误方向的变更，暂停并排查原因。
+
+### 自身更新检测
+
+检查 `git diff` 中是否包含 `.agents/skills/update-agent-infra/SKILL.md` 的变更。
+如果该文件在本次更新中被修改，在报告末尾输出以下警告：
+
+```
+⚠ update-agent-infra 技能自身已更新。
+  建议再次执行 /update-agent-infra 以确保所有新逻辑生效。
+```
+
+> **原因**：本次执行使用的是旧版技能逻辑，新版技能可能包含额外的处理步骤。
+> 再次执行可确保新逻辑完整应用。
+> 用户也可以在执行前先运行 `ai update` 来预先更新技能文件，避免需要两次执行。
+
+### 输出报告
+
+基于脚本报告和 merged 合并结果，输出完整的更新报告，包括：
+- 模板版本变更
+- 文件注册表新增条目
+- managed 文件变更明细（已更新、新建、跳过的 merged 文件）
+- merged 文件合并结果（冲突、残余 TODO）
+- ejected 文件处理
+- 自身更新检测结果
+
+输出报告后**停止**，不要对项目做其他更改。

package/templates/.agents/skills/update-agent-infra/scripts/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}