@fitlab-ai/agent-infra 0.4.0 → 0.4.1

package/templates/.agents/skills/implement-task/reference/implementation-rules.md

@@ -0,0 +1,58 @@
+# Implementation Rules
+
+Read this file before coding or interpreting test failures.
+
+## Execute Code Implementation
+
+Follow the `implementation` step in `.agents/workflows/feature-development.yaml`.
+
+**Required tasks**:
+- [ ] implement the feature code according to the plan
+- [ ] write comprehensive unit tests
+- [ ] run tests locally to validate the feature
+- [ ] update related documentation and comments
+- [ ] follow project coding standards
+
+**Implementation principles**:
+1. **Follow the plan strictly**: do not deviate from the technical plan
+2. **Work step by step**: execute the planned sequence
+3. **Keep testing continuously**: re-run tests as work progresses
+4. **Keep it simple**: do not add unplanned features
+
+## Run Test Verification
+
+Run the project test command. Refer to the `test` skill for project-specific commands.
+
+```bash
+# See .agents/skills/test/SKILL.md for the project's test command
+# Common patterns:
+# npm test          (Node.js)
+# mvn test          (Maven)
+# pytest            (Python)
+# go test ./...     (Go)
+```
+
+If tests fail:
+- analyze the failure first and prioritize fixing issues introduced by this implementation
+- re-run tests after each fix until they pass, or confirm that the problem is an external blocker
+- only stop without producing the implementation artifact when the failure is caused by an external blocker, missing environment, or unclear requirement that cannot be resolved inside the task
+
+Two-way failure handling:
+1. implementation-caused failures:
+   - fix the code, tests, docs, or fixtures introduced by this implementation
+   - re-run the test command after each fix
+   - continue until all required tests pass
+2. external blockers:
+   - confirm the failure comes from missing environment, unrelated upstream breakage, or unclear requirements outside this task
+   - stop without creating `implementation.md` / `implementation-r{N}.md`
+   - do not mark implementation complete in `task.md`
+   - do not output the normal success/next-step template
+
+## Notes
+
+1. **Prerequisite**: the approved technical plan must exist (`plan.md` or `plan-r{N}.md`)
+2. **No auto-commit**: do not run `git commit` or `git add`
+3. **Test quality**: new tests must validate meaningful business logic
+4. **Code quality**: follow project coding conventions
+5. **Plan deviation**: record any deviation in the implementation report
+6. **Versioning**: Round 1 uses `implementation.md`; later rounds use `implementation-r{N}.md`

package/templates/.agents/skills/implement-task/reference/implementation-rules.zh-CN.md

@@ -0,0 +1,58 @@
+# 实现规则
+
+在编写代码或判断测试失败原因之前先读取本文件。
+
+## 执行代码实现
+
+遵循 `.agents/workflows/feature-development.yaml` 中的 `implementation` 步骤。
+
+**必做任务**：
+- [ ] 按计划实现功能代码
+- [ ] 编写完整的单元测试
+- [ ] 在本地运行测试验证功能
+- [ ] 更新相关文档和注释
+- [ ] 遵守项目编码规范
+
+**实现原则**：
+1. **严格遵循方案**：不要偏离技术方案
+2. **按步骤推进**：按计划顺序执行
+3. **持续测试**：实现过程中持续重新运行测试
+4. **保持简单**：不要加入未计划的功能
+
+## 运行测试验证
+
+运行项目测试命令。项目特定命令请参考 `test` skill。
+
+```bash
+# 参考 .agents/skills/test/SKILL.md 中的项目测试命令
+# 常见模式：
+# npm test          (Node.js)
+# mvn test          (Maven)
+# pytest            (Python)
+# go test ./...     (Go)
+```
+
+如果测试失败：
+- 先分析失败原因，并优先修复由本次实现引入的问题
+- 每次修复后重新运行测试，直到通过，或者确认问题属于外部阻塞
+- 只有当失败由外部阻塞、环境缺失或当前任务内无法澄清的需求问题导致时，才允许在不生成实现产物的情况下停止
+
+双分支失败处理：
+1. 本次实现引入的失败：
+   - 修复由本次实现引入的代码、测试、文档或 fixture 问题
+   - 每次修复后重新运行测试命令
+   - 持续处理直到所有必需测试通过
+2. 外部阻塞：
+   - 确认失败来自缺失环境、无关的上游损坏，或任务范围外的需求不明确
+   - 停止，并且不要创建 `implementation.md` / `implementation-r{N}.md`
+   - 不要在 `task.md` 中把实现标记为完成
+   - 不要输出正常的成功/下一步模板
+
+## 注意事项
+
+1. **前置条件**：必须存在已批准的技术方案（`plan.md` 或 `plan-r{N}.md`）
+2. **禁止自动提交**：不要执行 `git commit` 或 `git add`
+3. **测试质量**：新增测试必须验证有意义的业务逻辑
+4. **代码质量**：遵循项目编码规范
+5. **方案偏离**：任何偏离都要记录到实现报告中
+6. **版本命名**：Round 1 使用 `implementation.md`，后续轮次使用 `implementation-r{N}.md`

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

@@ -0,0 +1,63 @@
+# Implementation Report Template
+
+Use this structure when creating `implementation.md` or `implementation-r{N}.md`.
+
+## Output Template
+
+```markdown
+# Implementation Report
+
+- **Implementation Round**: Round {implementation-round}
+- **Artifact File**: `{implementation-artifact}`
+
+## Modified Files
+
+### New Files
+- `{file-path}` - {description}
+
+### Modified Files
+- `{file-path}` - {change summary}
+
+## Key Code Explanation
+
+### {Module/Feature Name}
+**File**: `{file-path}:{line-number}`
+
+**Implementation Logic**:
+{important logic summary}
+
+**Key Code**:
+```{language}
+{key-code-snippet}
+```
+
+## Test Results
+
+### Unit Tests
+- Test file: `{test-file-path}`
+- Test case count: {count}
+- Pass rate: {percentage}
+
+**Test Output**:
+```
+{test-run-output}
+```
+
+## Differences from Plan
+
+{describe any deviation from the approved plan}
+
+## Items for Review
+
+**Focus areas for reviewers**:
+- {item 1}
+- {item 2}
+
+## Known Issues
+
+{known issues or follow-up ideas}
+
+## Next Steps
+
+{recommended follow-up}
+```

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

@@ -0,0 +1,63 @@
+# 实现报告模板
+
+创建 `implementation.md` 或 `implementation-r{N}.md` 时，使用以下结构。
+
+## 输出模板
+
+```markdown
+# 实现报告
+
+- **实现轮次**: Round {implementation-round}
+- **产物文件**: `{implementation-artifact}`
+
+## 变更文件
+
+### 新建文件
+- `{file-path}` - {description}
+
+### 修改文件
+- `{file-path}` - {change summary}
+
+## 关键代码说明
+
+### {模块/功能名称}
+**文件**: `{file-path}:{line-number}`
+
+**实现逻辑**:
+{important logic summary}
+
+**关键代码**:
+```{language}
+{key-code-snippet}
+```
+
+## 测试结果
+
+### 单元测试
+- 测试文件: `{test-file-path}`
+- 测试用例数: {count}
+- 通过率: {percentage}
+
+**测试输出**:
+```
+{test-run-output}
+```
+
+## 与方案的差异
+
+{describe any deviation from the approved plan}
+
+## 供审查关注的内容
+
+**建议审查者重点关注**:
+- {item 1}
+- {item 2}
+
+## 已知问题
+
+{known issues or follow-up ideas}
+
+## 下一步
+
+{recommended follow-up}
+```

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

@@ -1,9 +1,6 @@
 ---
 name: import-codescan
-description: >
-  Import a Code Scanning (CodeQL) alert and create a remediation task.
-  Triggered when the user asks to import a Code Scanning alert.
-  Argument: alert number.
+description: "Import a Code Scanning alert and create a remediation task"
 ---
 
 # Import Code Scanning Alert

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

@@ -1,8 +1,6 @@
 ---
 name: import-codescan
-description: >
-  导入 Code Scanning（CodeQL）告警并创建修复任务。
-  当用户要求导入 Code Scanning 告警时触发。参数：告警编号。
+description: "导入 Code Scanning 告警并创建修复任务"
 ---
 
 # 导入 Code Scanning 告警

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

@@ -1,9 +1,6 @@
 ---
 name: import-dependabot
-description: >
-  Import a Dependabot security alert and create a remediation task.
-  Triggered when the user asks to import a Dependabot alert.
-  Argument: alert number.
+description: "Import a Dependabot alert and create a remediation task"
 ---
 
 # Import Dependabot Security Alert

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

@@ -1,8 +1,6 @@
 ---
 name: import-dependabot
-description: >
-  导入 Dependabot 安全告警并创建修复任务。
-  当用户要求导入 Dependabot 告警时触发。参数：告警编号。
+description: "导入 Dependabot 安全告警并创建修复任务"
 ---
 
 # 导入 Dependabot 安全告警

package/templates/.agents/skills/import-issue/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: import-issue
-description: >
-  Import from a GitHub Issue and create a task file.
-  Triggered when the user asks to import an Issue. Argument: issue number.
+description: "Import a GitHub Issue and create a task"
 ---
 
 # Import Issue

package/templates/.agents/skills/import-issue/SKILL.zh-CN.md

@@ -1,8 +1,6 @@
 ---
 name: import-issue
-description: >
-  从 GitHub Issue 导入并创建任务文件。
-  当用户要求导入某个 Issue 时触发。参数：issue 编号。
+description: "从 GitHub Issue 导入并创建任务"
 ---
 
 # 导入 Issue

package/templates/.agents/skills/init-labels/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: init-labels
-description: >
-  Initialize the repository's standard GitHub Labels taxonomy in one pass.
-  Create the common labels, auto-detect `in:` labels from the project structure,
-  do not create `theme:` labels, overwrite exact-match GitHub defaults, and report unmatched defaults.
+description: "Initialize the repository's standard GitHub Labels taxonomy"
 ---
 
 # Initialize GitHub Labels

package/templates/.agents/skills/init-labels/SKILL.zh-CN.md

@@ -1,9 +1,6 @@
 ---
 name: init-labels
-description: >
-  一次性初始化仓库的标准 GitHub Labels 体系。
-  创建通用 labels、基于项目目录结构自动探测 `in:` labels、
-  不创建 `theme:` labels、覆盖名称完全匹配的 GitHub 默认 labels，并提示未覆盖的默认 labels。
+description: "初始化仓库的 GitHub Labels 体系"
 ---
 
 # 初始化 GitHub Labels

package/templates/.agents/skills/init-milestones/SKILL.md

@@ -1,8 +1,6 @@
 ---
 name: init-milestones
-description: >
-  Initialize the repository's standard GitHub Milestones taxonomy in one pass.
-  Create General Backlog, the initial milestones derived from the current version baseline, and optionally backfill historical milestones.
+description: "Initialize the repository's standard GitHub Milestones taxonomy"
 ---
 
 # Initialize GitHub Milestones

package/templates/.agents/skills/init-milestones/SKILL.zh-CN.md

@@ -1,8 +1,6 @@
 ---
 name: init-milestones
-description: >
-  一次性初始化仓库的标准 GitHub Milestones 体系。
-  创建 General Backlog、基于当前版本的初始里程碑，并可选补齐历史版本里程碑。
+description: "初始化仓库的 GitHub Milestones 体系"
 ---
 
 # 初始化 GitHub Milestones

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

@@ -1,10 +1,6 @@
 ---
 name: plan-task
-description: >
-  Design a technical plan for a task and output a detailed implementation
-  plan. Triggered when the user asks for a design or technical plan after
-  requirements analysis is complete. This is a mandatory human review
-  checkpoint. Argument: task-id.
+description: "Design a technical plan for a task"
 ---
 
 # Design Technical Plan

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

@@ -1,8 +1,6 @@
 ---
 name: plan-task
-description: >
-  为任务设计技术方案并输出详细的实施计划。当用户要求为已完成需求分析的任务设计方案或技术计划时触发。
-  这是一个强制性的人工审查检查点。参数：task-id。
+description: "为任务设计技术方案和实施计划"
 ---
 
 # 设计技术方案

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

@@ -1,94 +1,52 @@
 ---
 name: refine-task
-description: >
-  Process code review feedback and fix the issues found in review. Fix items by
-  priority (Blocker -> Major -> Minor). Only handle issues explicitly marked in
-  the review; do not add unrelated changes. Triggered when the user asks to fix
-  review findings. Argument: task-id.
+description: "Handle code review feedback and fix issues"
 ---
 
-# Refine Review Findings
+# Refine Task
+
+Fix review findings and produce `refinement.md` or `refinement-r{N}.md`.
 
 ## Boundary / Critical Rules
 
-- Only fix issues that were explicitly identified in review -- do not add unrelated changes or extra "improvements"
-- Do NOT auto-commit. Never execute `git commit` or `git add`
-- After executing this skill, you **must** immediately update task status in task.md
+- Fix only the issues documented in review artifacts
+- Never auto-run `git add` or `git commit`
+- After executing this skill, you **must** immediately update task.md
 
 ## Steps
 
 ### 1. Verify Prerequisites
 
-Check required files:
-- `.agents/workspace/active/{task-id}/task.md` - Task file
-- At least one review artifact: `review.md` or `review-r{N}.md`
-
-Note: `{task-id}` format is `TASK-{yyyyMMdd-HHmmss}`, for example `TASK-20260306-143022`
-
-If `task.md` is missing or there is no review artifact, prompt the user to complete the prerequisite step first.
+Require:
+- `.agents/workspace/active/{task-id}/task.md`
+- at least one review artifact: `review.md` or `review-r{N}.md`
 
-Then perform this discovery and validation:
-1. Scan review artifact files in the task directory (`review.md`, `review-r{N}.md`)
-2. Use the highest-round review artifact as the input for this refinement round and record it as `{review-artifact}`
-3. Scan refinement artifact files (`refinement.md`, `refinement-r{N}.md`) and determine the current refinement artifact:
-   - If neither `refinement.md` nor `refinement-r*.md` exists -> this is Round 1 and must create `refinement.md`
-   - If `refinement.md` exists and no `refinement-r*.md` exists -> this is Round 2 and must create `refinement-r2.md`
-   - If `refinement-r{N}.md` exists -> this is Round N+1 and must create `refinement-r{N+1}.md`
-   - Record `{refinement-round}` and `{refinement-artifact}`
-4. Scan implementation report files (`implementation.md`, `implementation-r{N}.md`) and use the highest-round artifact as the implementation context `{implementation-artifact}`
-   - Record `{implementation-artifact}`
-5. **Consistency check**: verify that the most recent Code Review entry in `task.md` `## Activity Log` matches the round number and filename of the latest review artifact found in Step 2
+During prerequisite discovery, record `{review-artifact}`, `{refinement-round}`, `{refinement-artifact}`, and Record `{implementation-artifact}` from the latest implementation report.
 
-If the Activity Log entry does not match the actual file, stop immediately and prompt:
+Also validate the latest Code Review entry in Activity Log. If it points to a missing file, stop with:
 `Review artifact mismatch: Activity Log references {expected} but file not found. Please verify the review artifact exists.`
 
 ### 2. Read Review and Implementation Context
 
-Carefully read the latest review artifact `{review-artifact}` and implementation artifact `{implementation-artifact}` identified in Step 1 to understand:
-- All blockers (must fix)
-- All major issues (should fix)
-- Minor issues (optional improvements)
-- Reviewer recommendations and suggestions
-- The context of the current implementation and previous refinements
-
-### 3. Plan the Fixes
-
-Classify and prioritize:
-1. **Blockers first**: all blockers must be resolved
-2. **Then major issues**: handle all major issues
-3. **Finally minor issues**: fix if appropriate (optional)
+Read the latest `{review-artifact}` and `{implementation-artifact}` before editing any code.
 
-For each issue, determine:
-- Which files need to be modified
-- What exact change is required
-- How to verify the fix
+### 3. Plan and Apply the Fixes
 
-### 4. Execute the Fixes
+Prioritize Blocker -> Major -> Minor and keep changes tightly scoped.
 
-Fix issues in priority order:
+> The detailed fix workflow, repair order, and verification loop live in `reference/fix-workflow.md`. Read `reference/fix-workflow.md` before making changes.
 
-**For each fix**:
-1. Read the affected file
-2. Apply the fix
-3. Verify that the change resolves the review finding
-4. Run relevant tests
+### 4. Run Test Verification
 
-**Refinement principles**:
-- Only fix marked review issues -- do not add unrelated changes
-- Do not add extra "improvements" beyond the scope of the review
-- Keep the changes minimal and focused
+Run the project test command after the fixes and keep the repair cycle focused on the documented findings.
 
-### 5. Run Test Verification
-
-Execute the project's test command. Reference the `test` skill for the project-specific test command.
-
-Ensure all tests still pass after the fixes.
-
-### 6. Create Refinement Report
+### 5. Write the Refinement Report
 
 Create `.agents/workspace/active/{task-id}/{refinement-artifact}`.
 
-### 7. Update Task Status
+> The report structure and example sections live in `reference/report-template.md`. Read `reference/report-template.md` before writing the report.
+
+### 6. Update Task Status
 
 Get the current time:
 
@@ -96,115 +54,33 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S"
 ```
 
-Update `.agents/workspace/active/{task-id}/task.md`:
-- `current_step`: refinement
-- `assigned_to`: {current AI agent}
-- `updated_at`: {current time}
-- Record the refinement artifact for this round: `{refinement-artifact}` (Round `{refinement-round}`)
-- **Append** to `## Activity Log` (do NOT overwrite previous entries):
-  ```
-  - {yyyy-MM-dd HH:mm:ss} — **Refinement (Round {N}, for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues → {refinement-artifact}
-  ```
-
-### 8. 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.
-
-> **⚠️ CONDITION CHECK — before showing the two next steps below, you must judge the result of this refinement round first:**
->
-> - If this round fixed any `Blocker` or `Major` issue, or the changes touched core logic or test scope broadly, **default recommendation** is "Run review again"
-> - If this round fixed only `Minor` issues and the change scope is small and low-risk, "Commit directly" may be offered as an option
-> - If any `Blocker` or `Major` issue remains unresolved, **do not** imply that direct commit is acceptable; explicitly tell the user to continue fixing or re-run review
->
-> **Do not present "Commit directly" as the default path unless you are sure no high-risk issue remains.**
-
-Output format:
-```
-Refinement complete for task {task-id}.
-
-Fix summary:
-- Blockers fixed: {count}/{total}
-- Major issues fixed: {count}/{total}
-- Minor issues fixed: {count}/{total}
-- All tests passing: {yes/no}
-- Review input: {review-artifact}
-- Refinement artifact: {refinement-artifact}
-
-Next step - re-review or commit:
-- Run review again (default recommendation; prioritize this after Blocker/Major fixes):
-  - Claude Code / OpenCode: /review-task {task-id}
-  - Gemini CLI: /{{project}}:review-task {task-id}
-  - Codex CLI: $review-task {task-id}
-- Commit directly (only when only Minor issues were fixed and risk is low):
-  - Claude Code / OpenCode: /commit
-  - Gemini CLI: /{{project}}:commit
-  - Codex CLI: $commit
-```
-
-## Output Template
-
-```markdown
-# Refinement Report
-
-- **Refinement round**: Round {refinement-round}
-- **Artifact file**: `{refinement-artifact}`
-- **Review input**: `{review-artifact}`
-- **Implementation context**: `{implementation-artifact}`
-
-### Review Feedback Handling
+Update task.md and append:
+`- {yyyy-MM-dd HH:mm:ss} — **Refinement (Round {N}, for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues → {refinement-artifact}`
 
-#### Blocker Fixes
-1. **{Issue title}** (from {review-artifact})
-   - **Fix**: {What changed}
-   - **File**: `{file-path}:{line-number}`
-   - **Validation**: {How it was verified}
+### 7. Inform User
 
-#### Major Issue Fixes
-1. **{Issue title}** (from {review-artifact})
-   - **Fix**: {What changed}
-   - **File**: `{file-path}:{line-number}`
-
-#### Minor Issue Handling
-1. **{Issue title}** (from {review-artifact})
-   - **Fix**: {What changed}
-
-#### Unresolved Issues
-- {Issue}: {Reason it was not handled, for example disagreement with the review suggestion}
-
-### Test Results After Refinement
-- All tests passing: {yes/no}
-- Test output: {Summary}
-```
+Recommend re-review by default when Blocker or Major issues were fixed. Only present direct commit as a low-risk option when the changes are truly minor.
 
 ## Completion Checklist
 
-- [ ] Read and understood all review findings
-- [ ] Fixed all blockers
-- [ ] Fixed all major issues
-- [ ] Addressed minor issues when appropriate
-- [ ] All tests pass after the fixes
-- [ ] Created refinement report `{refinement-artifact}`
-- [ ] Updated task status in task.md
-- [ ] Appended an Activity Log entry to task.md
-- [ ] Informed the user of the next step (must include all TUI command formats without filtering)
+- [ ] Read the latest review and implementation context
+- [ ] Fixed all required Blocker and Major findings
+- [ ] Wrote `{refinement-artifact}`
+- [ ] Updated task.md and appended the Activity Log entry
+- [ ] Recommended the correct next step based on residual risk
 
 ## Notes
 
-1. **Prerequisite**: A review report must exist (`review.md` or `review-r{N}.md`)
-2. **No auto-commit**: Do NOT execute `git commit`. Remind the user to commit manually
-3. **Scope discipline**: Only fix issues marked in review -- do not add extra changes
-4. **Disagreement**: If you disagree with a review finding, record your reasoning in "Unresolved Issues"
-5. **Re-review**: After fixing blockers, re-run `review-task` to validate the result
-6. **Consistency requirement**: The latest review artifact, Activity Log entry, and refinement report title must all reference the same review round
-7. **Versioning rule**: First refinement uses `refinement.md`; later rounds use `refinement-r{N}.md`
+- Round 1 uses `refinement.md`; later rounds use `refinement-r{N}.md`
+- Record any disagreement with a review comment under unresolved issues in the report
+- Do not expand scope beyond the review findings
 
 ## STOP
 
-After completing the checklist, **stop immediately**. Wait for the user to review the fixes and decide whether to run review again or commit.
+Stop after the checklist is complete.
 
 ## Error Handling
 
-- Task not found: Prompt "Task {task-id} not found"
-- Missing review report: Prompt "Review report not found, please run the review-task skill first"
-- Review artifact mismatch: Prompt "Review artifact mismatch: Activity Log references {expected} but file not found. Please verify the review artifact exists."
-- Test failure after fixes: Output the test errors and ask the user how to proceed
+- Task not found: `Task {task-id} not found`
+- Missing review report: `Review report not found, please run the review-task skill first`
+- Review artifact mismatch: `Review artifact mismatch: Activity Log references {expected} but file not found. Please verify the review artifact exists.`