@fitlab-ai/agent-infra 0.4.0 → 0.4.2

package/templates/.agents/README.zh-CN.md

@@ -1,6 +1,6 @@
 # 多 AI 协作指南
 
-本项目支持多个 AI 编程助手协同工作，包括 Claude Code、OpenAI Codex CLI、Gemini CLI、Cursor 等。
+本项目支持多个 AI 编程助手协同工作，包括 Claude Code、OpenAI Codex CLI、Gemini CLI、OpenCode 等。
 
 ## 双配置架构
 
@@ -8,10 +8,10 @@
 
 | AI 工具 | 主要配置 | 备选配置 |
 |---------|---------|---------|
-| Claude Code | `.claude/`（CLAUDE.md、commands/、settings/） | - |
+| Claude Code | `.claude/`（CLAUDE.md、commands/、settings.json） | - |
 | OpenAI Codex CLI | `AGENTS.md` | - |
 | Gemini CLI | `AGENTS.md` | - |
-| Cursor | `.cursorrules` 或 `.cursor/rules/` | `AGENTS.md` |
+| OpenCode | `AGENTS.md` | - |
 | 其他 AI 工具 | `AGENTS.md` | 项目 README |
 
 - **Claude Code** 使用专属的 `.claude/` 目录存放项目指令、斜杠命令和设置。
@@ -23,10 +23,8 @@
 
 ```
 .agents/                        # AI 协作配置（版本控制）
-  README.md                     # 本文件（英文）
-  README.zh-CN.md               # 中文版本
+  README.md                     # 协作指南
   QUICKSTART.md                 # 快速入门指南
-  QUICKSTART.zh-CN.md           # 快速入门指南（中文）
   templates/                    # 任务和文档模板
     task.md                     # 任务模板
     handoff.md                  # AI 间交接模板
@@ -36,28 +34,28 @@
     bug-fix.yaml                # 缺陷修复工作流
     code-review.yaml            # 代码审查工作流
     refactoring.yaml            # 重构工作流
-
-.agents/workspace/         # 运行时工作区（已被 git ignore）
-  active/                       # 当前活跃任务
-  blocked/                      # 被阻塞的任务
-  completed/                    # 已完成的任务
-  logs/                         # 协作日志
+  workspace/                    # 运行时工作区（已被 git ignore）
+    active/                     # 当前活跃任务
+    blocked/                    # 被阻塞的任务
+    completed/                  # 已完成的任务
+    logs/                       # 协作日志
 
 .claude/                        # Claude Code 专属配置
   CLAUDE.md                     # Claude 项目指令
   commands/                     # 斜杠命令
-  settings/                     # Claude 设置
+  settings.json                 # Claude 设置
 ```
 
 ## 协作模型
 
 多 AI 协作遵循结构化工作流：
 
-```
-1. 分析    -->  2. 设计    -->  3. 实现
-                                    |
-6. 提交  <--  5. 修复问题  <--  4. 审查
-```
+1. 分析
+2. 设计
+3. 实现
+4. 审查
+5. 修复问题
+6. 提交
 
 ### 阶段详情
 
@@ -76,26 +74,26 @@
 
 每个 AI 工具有不同的优势，请据此分配任务：
 
-| 能力 | Claude Code | Codex CLI | Gemini CLI | Cursor |
-|-----|-------------|-----------|------------|--------|
+| 能力 | Claude Code | Codex CLI | Gemini CLI | OpenCode |
+|-----|-------------|-----------|------------|----------|
 | 代码库分析 | 优秀 | 良好 | 优秀 | 良好 |
-| 代码审查 | 优秀 | 良好 | 良好 | 一般 |
+| 代码审查 | 优秀 | 良好 | 良好 | 良好 |
 | 代码实现 | 良好 | 优秀 | 良好 | 优秀 |
-| 大上下文处理 | 良好 | 一般 | 优秀 | 良好 |
-| 重构 | 良好 | 良好 | 良好 | 优秀 |
-| 文档编写 | 优秀 | 良好 | 良好 | 一般 |
+| 大上下文处理 | 良好 | 一般 | 优秀 | 一般 |
+| 重构 | 良好 | 良好 | 良好 | 良好 |
+| 文档编写 | 优秀 | 良好 | 良好 | 良好 |
 
 ### 推荐分配
 
 - **分析和审查** - Claude Code（推理能力强，探索全面）
-- **代码实现** - Codex CLI 或 Cursor（代码生成快，内联编辑）
+- **代码实现** - Codex CLI 或 OpenCode（代码生成快，命令式工作流顺手）
 - **大上下文任务** - Gemini CLI（大上下文窗口，适合跨文件分析）
-- **快速编辑** - Cursor（IDE 集成，快速迭代）
+- **命令式迭代** - OpenCode（适合按工作流连续推进）
 
 ## 快速入门
 
-1. **阅读快速入门指南**：参见 `QUICKSTART.zh-CN.md` 获取分步说明。
-2. **创建任务**：将 `.agents/templates/task.zh-CN.md` 复制到 `.agents/workspace/active/`。
+1. **阅读快速入门指南**：参见 `QUICKSTART.md` 获取分步说明。
+2. **创建任务**：将 `.agents/templates/task.md` 复制到 `.agents/workspace/active/`。
 3. **分配给 AI**：更新任务元数据中的 `assigned_to` 字段。
 4. **执行工作流**：按照 `.agents/workflows/` 中相应的工作流执行。
 5. **交接**：切换 AI 时，从模板创建交接文档。
@@ -118,10 +116,18 @@
 
 1. 顶级步骤使用连续整数：`1.`、`2.`、`3.`。
 2. 只有父步骤下的从属动作才使用子步骤：`1.1`、`1.2`、`2.1`。
-3. 同一步中的分支、条件或多种可能性使用 `a`、`b`、`c` 标记。
+3. 同一步中的从属选项、条件分支或并列可能性使用 `a`、`b`、`c` 标记；仅用于步骤内部的子项展开，不用于命名独立的决策路径或输出模板。
 4. 不要使用 `1.5`、`2.5` 这类中间编号；如新增独立步骤，应整体顺延后续编号。
 5. 调整编号时，必须同步更新文中的步骤引用，确保说明、命令和检查点一致。
 6. 长 bash 脚本应从 SKILL.md 提取到同级 `scripts/` 目录中，SKILL.md 只保留单行调用（如 `bash .agents/skills/<skill>/scripts/<script>.sh`）和对脚本职责的概要说明。
+7. 在 SKILL.md 及其 `reference/` 模板中，如需为独立的条件分流、决策路径或输出模板命名，统一使用“场景”命名（例如使用“场景 A”）。
+
+### SKILL.md 体积控制
+
+- SKILL.md 正文控制在约 500 tokens（约 80 行 / 2KB）以内。
+- 超过阈值的内容拆分到同级 `reference/` 目录。
+- 骨架中使用明确导航，例如：`执行此步骤前，先读取 reference/xxx.md。`
+- 长脚本继续放在 `scripts/` 目录，优先执行脚本而不是内联大段 bash。
 
 ## 常见问题
 

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

@@ -1,9 +1,6 @@
 ---
 name: analyze-task
-description: >
-  Analyze an existing task and output a requirements analysis document,
-  supporting multi-round artifacts (`analysis.md` / `analysis-r{N}.md`).
-  Triggered when the user asks to analyze a task. Argument: task-id.
+description: "Analyze a task and produce a requirements document"
 ---
 
 # Analyze Task

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

@@ -1,8 +1,6 @@
 ---
 name: analyze-task
-description: >
-  分析已有任务并输出需求分析文档，支持多轮分析产物（analysis.md / analysis-r{N}.md）。
-  当用户要求分析某个任务时触发。参数：task-id。
+description: "分析任务并输出需求分析文档"
 ---
 
 # 分析任务

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

@@ -1,10 +1,6 @@
 ---
 name: block-task
-description: >
-  Mark a task as blocked and record the blocking reason, moving it from
-  the active directory to the blocked directory. Use when a task cannot
-  proceed due to technical problems, unclear requirements, missing resources,
-  or pending decisions. Arguments: task-id, optional blocking reason.
+description: "Mark a task as blocked and record the reason"
 ---
 
 # Block Task

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

@@ -1,9 +1,6 @@
 ---
 name: block-task
-description: >
-  标记任务为阻塞状态并记录阻塞原因，将其从 active 目录移动到 blocked 目录。
-  当任务因技术问题、需求不清晰、缺少资源或待定决策而无法继续时使用。
-  参数：task-id，可选的阻塞原因。
+description: "标记任务为阻塞状态并记录原因"
 ---
 
 # 标记任务阻塞

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

@@ -1,10 +1,6 @@
 ---
 name: check-task
-description: >
-  Check a task's current status, workflow progress, and context files. This is a
-  read-only operation that reports the task status and recommends appropriate
-  next steps. Triggered when the user asks to inspect task status. Argument:
-  task-id.
+description: "Check a task's current status and progress"
 ---
 
 # Check Task Status

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

@@ -1,8 +1,6 @@
 ---
 name: check-task
-description: >
-  查看任务的当前状态、工作流进度和上下文文件。这是只读操作，报告任务状态并建议
-  适当的下一步操作。当用户要求查看任务状态时触发。参数：task-id。
+description: "查看任务的当前状态和进度"
 ---
 
 # 查看任务状态

package/templates/.agents/skills/close-codescan/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: close-codescan
-description: >
-  Dismiss a Code Scanning (CodeQL) alert with a documented justification.
-  Triggered when the user asks to dismiss a Code Scanning alert.
-  Argument: alert number.
+description: "Close a Code Scanning alert with a documented reason"
 ---
 
 # Dismiss Code Scanning Alert

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

@@ -1,8 +1,6 @@
 ---
 name: close-codescan
-description: >
-  关闭 Code Scanning（CodeQL）告警并提供有据可查的理由。
-  当用户要求关闭 Code Scanning 告警时触发。参数：告警编号。
+description: "关闭 Code Scanning 告警并记录理由"
 ---
 
 # 关闭 Code Scanning 告警

package/templates/.agents/skills/close-dependabot/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: close-dependabot
-description: >
-  Dismiss a Dependabot security alert with a documented justification.
-  Triggered when the user asks to dismiss a Dependabot alert.
-  Argument: alert number.
+description: "Close a Dependabot alert with a documented reason"
 ---
 
 # Dismiss Dependabot Alert

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

@@ -1,8 +1,6 @@
 ---
 name: close-dependabot
-description: >
-  关闭 Dependabot 安全告警并提供有据可查的理由。
-  当用户要求关闭 Dependabot 告警时触发。参数：告警编号。
+description: "关闭 Dependabot 安全告警并记录理由"
 ---
 
 # 关闭 Dependabot 告警

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

@@ -1,139 +1,40 @@
 ---
 name: commit
-description: >
-  Commit current changes to Git, including copyright header year
-  check and task status update. Triggered when the user requests
-  a code commit or save changes.
+description: "Commit the current changes to Git"
 ---
 
 # Commit Changes
 
-Commit current changes to Git.
+Create a Git commit without overwriting user work and update the related task state when needed.
 
-## Step 0: Check Local Modifications (CRITICAL)
+## 1. Check Local Modifications (CRITICAL)
 
-**Mandatory**: Before any edits, you **must** check the user's local modifications to avoid overwriting their work.
+Before any edit, inspect:
 
 ```bash
 git status --short
 git diff
 ```
 
-**Rules**:
-1. **Read `git diff` output carefully** - understand what the user has already changed
-2. **Make incremental edits** on top of user modifications - do not overwrite their implementation
-3. **If your planned edits conflict** with user modifications, ask the user first:
-   ```
-   This file has local modifications:
-   - Your changes: [describe user's changes]
-   - My planned changes: [describe planned changes]
-   Please confirm how to proceed.
-   ```
-4. **Do NOT** rewrite code the user has already implemented
-5. **Do NOT** add "improvements" the user didn't ask for
+Respect existing user changes. If your planned edit conflicts with them, stop and ask before proceeding.
 
-## Step 1: Update Copyright Header Years (CRITICAL)
+## 2. Update Copyright Headers
 
-**Mandatory**: Before committing, check and update copyright headers in all modified files.
+Use the current year dynamically and only update files that are already modified.
 
-### Get Current Year
+> The full copyright workflow lives in `reference/copyright-check.md`. Read `reference/copyright-check.md` before editing any header.
 
-```bash
-date +%Y
-```
-
-**Never hardcode the year.**
-
-### Check Modified Files
-
-```bash
-git status --short
-```
-
-### For Each Modified File
-
-Check if the file has a copyright header:
-```bash
-grep "Copyright.*[0-9]\{4\}" <modified_file>
-```
-
-If it has a copyright header and the year is not current, update the year.
-
-**Common formats**:
-- `Copyright (C) 2024-2025` -> `Copyright (C) 2024-{CURRENT_YEAR}`
-- `Copyright (C) 2024` -> `Copyright (C) 2024-{CURRENT_YEAR}`
-- `Copyright (C) 2025` -> `Copyright (C) {CURRENT_YEAR}` (if already current)
-
-### Copyright Checklist
-
-Before executing `git commit`:
-- [ ] Used `date +%Y` to dynamically get the current year
-- [ ] Checked all files about to be committed
-- [ ] Updated copyright year in all files that have copyright headers
-- [ ] **Never** hardcoded the year
-- [ ] **Only** updated modified files, not the entire project
-
-## Step 2: Analyze Changes and Generate Commit Message
-
-```bash
-git status
-git diff
-git log --oneline -5
-```
-
-Generate commit message in Conventional Commits format:
-- `<type>(<scope>): <subject>` (English imperative mood, max 50 chars)
-- Body: 2-4 bullet points explaining what and why
-- Signature block:
-  - `Co-Authored-By: {Your Model Name} <noreply@provider.com>`
-  - If task-related, append extra `Co-Authored-By` lines for other contributing agents
-
-### Multi-Agent Co-Authorship (If Task-Related)
-
-If the commit belongs to an active task and `.agents/workspace/active/{task-id}/task.md` exists:
-
-1. Read the `## Activity Log` section from `task.md`.
-2. Extract all unique agent names from entries matching `by {agent}`. A loose pattern such as `by (\S+)` is acceptable.
-3. Exclude `human` because the Git author is already the human user.
-4. Map each agent to a `Co-Authored-By` line:
-
-| Agent | Signature |
-|-------|-----------|
-| `claude` | `Co-Authored-By: Claude <noreply@anthropic.com>` |
-| `codex` | `Co-Authored-By: Codex <noreply@openai.com>` |
-| `gemini` | `Co-Authored-By: Gemini <noreply@google.com>` |
-| `opencode` | `Co-Authored-By: OpenCode <noreply@opencode.ai>` |
-
-5. Build the signature block with these rules:
-   - Keep the current executing agent's signature in its original position.
-   - Append other unique participating agents as additional `Co-Authored-By` lines.
-   - Do not duplicate the current agent if it already appears in `Activity Log`.
-   - For unknown agent names, use `Co-Authored-By: {Agent} <noreply@unknown>`.
-
-If the commit is not task-related, keep the existing single-signature behavior.
-
-## Step 3: Create Commit
+## 3. Build the Commit Message
 
-```bash
-git add <specific-files>
-git commit -m "$(cat <<'EOF'
-<type>(<scope>): <subject>
+Review status, diff, and recent history, then prepare a Conventional Commit with the correct co-author lines.
 
-- <bullet point 1>
-- <bullet point 2>
+> Commit message rules, examples, and multi-agent co-authorship details live in `reference/commit-message.md`. Read `reference/commit-message.md` before writing the commit.
 
-Co-Authored-By: {Your Model Name} <noreply@provider.com>
-<additional Co-Authored-By lines for other task participants, if any>
-EOF
-)"
-```
+## 4. Create the Commit
 
-**Important**:
-- Add specific files by name - do NOT use `git add -A` or `git add .`
-- Do NOT commit files that may contain secrets (.env, credentials, keys)
-- For task-related commits, keep the current agent first and append the extra lines generated above
+Stage specific files only and run `git commit` with the prepared message.
 
-## Step 4: Update Task Status (If Task-Related)
+## 5. Update Task Status When Applicable
 
 Get the current time:
 
@@ -141,93 +42,20 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S"
 ```
 
-After committing, update task status based on the situation:
-
-For all cases below, **append** to `## Activity Log` in task.md (do NOT overwrite previous entries):
-```
-- {yyyy-MM-dd HH:mm:ss} — **Commit** by {agent} — {commit hash short} {commit subject}
-```
-
-> **⚠️ Situation Check — you must inspect task state first, then choose exactly one matching case below:**
->
-> - Check `task.md` for `current_step`, workflow progress, and the latest `## Activity Log` entry
-> - Check whether the latest `review.md` / `review-r{N}.md` exists and whether the latest review passed with no issues
-> - Check whether any follow-up repair, review, or PR creation step is still pending
->
-> | Decision basis | Required case |
-> |---------------|---------------|
-> | All workflow steps complete + latest review passed with no issues + all tests pass | Case 1: Final Commit |
-> | There are still incomplete steps, unresolved fixes, or waiting actions | Case 2: More Work Needed |
-> | The purpose of this commit is to send the implementation/refinement into code review | Case 3: Ready for Review |
-> | Code is committed, review is done, and the next action should be PR creation | Case 4: Ready for PR |
->
-> **Do not mix multiple cases. You must decide first, then output the single matching next step.**
-
-### Case 1: Final Commit (Trigger: all work is done and the next step is task archival)
-
-If this is the last commit and all work is done:
-
-Prerequisites:
-- [ ] All code committed
-- [ ] All tests pass
-- [ ] Code review passed
-- [ ] All workflow steps complete
-
-Suggest next step:
-
-> **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 - complete and archive the task:
-  - Claude Code / OpenCode: /complete-task {task-id}
-  - Gemini CLI: /{{project}}:complete-task {task-id}
-  - Codex CLI: $complete-task {task-id}
-```
-
-### Case 2: More Work Needed (Trigger: incomplete steps, unresolved issues, or pending collaboration remain)
+> The full four-case status matrix, prerequisite checks, and multi-TUI next-step commands live in `reference/task-status-update.md`. Read `reference/task-status-update.md` before updating task state.
 
-If there's follow-up work (awaiting review, more fixes needed):
-- Update `task.md`: set `updated_at` to current time
-- Record this commit's content and next steps in task.md
+Append the Commit Activity Log entry and choose exactly one next-step case:
+- final commit -> `complete-task {task-id}`
+- more work remains -> update task.md and stop
+- ready for review -> `review-task {task-id}`
+- ready for PR -> `create-pr`
 
-### Case 3: Ready for Review (Trigger: the next action should be `review-task`)
-
-If the commit is ready for code review:
-- Update `task.md`: set `current_step` to `code-review`
-- Update `task.md`: set `updated_at` to current time
-- Mark implementation step as complete in workflow progress
-
-Suggest next step:
-
-> **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 - code review:
-  - Claude Code / OpenCode: /review-task {task-id}
-  - Gemini CLI: /{{project}}:review-task {task-id}
-  - Codex CLI: $review-task {task-id}
-```
-
-### Case 4: Ready for PR (Trigger: the next action should be `create-pr`)
-
-If the commit should become a Pull Request:
-- Update `task.md`: set `updated_at` to current time
-- Record PR plan in task.md
-
-Suggest next step:
+## Notes
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+- Never commit secrets such as `.env`, credentials, or keys
+- Keep the current agent first in the co-author block
+- Do not use `git add -A` or `git add .`
 
-```
-Next step - create a Pull Request:
-  - Claude Code / OpenCode: /create-pr
-  - Gemini CLI: /{{project}}:create-pr
-  - Codex CLI: $create-pr
-```
-
-## Notes
+## Error Handling
 
-- Do NOT commit files containing sensitive information (.env, credentials, etc.)
-- Ensure commit messages clearly describe the changes
-- Follow the project's Conventional Commits conventions
-- If task status update fails, warn the user but do not block the commit
+- If the task status update fails, warn the user but do not block the commit