@fitlab-ai/agent-infra 0.6.4 → 0.7.0

package/templates/.agents/skills/{refine-task → review-plan}/config/verify.zh-CN.json

@@ -1,5 +1,5 @@
 {
-  "skill": "refine-task",
+  "skill": "review-plan",
   "checks": {
     "task-meta": {
       "required_fields": [
@@ -12,35 +12,39 @@
         "agent_infra_version",
         "current_step",
         "assigned_to"
-      ]
+      ],
+      "expected_step": "technical-design-review"
     },
     "artifact": {
-      "file_pattern": "refinement.md|refinement-r{N}.md",
+      "file_pattern": "review-plan.md|review-plan-r{N}.md",
       "required_sections": [
-        "审查反馈处理",
-        "修复后的测试结果",
+        "审查摘要",
+        "问题清单",
+        "环境性遗留",
+        "结论与建议",
         "状态核对",
         "证据原文"
       ],
-      "freshness_minutes": 30,
       "required_patterns": [
+        "^### 审查决定$",
         "^\\$ "
-      ]
+      ],
+      "freshness_minutes": 30
     },
     "activity-log": {
-      "expected_action_pattern": "Refinement \\(Round \\d+, for .+\\)",
+      "expected_action_pattern": "Plan Review \\(Round \\d+\\)",
       "freshness_minutes": 30
     },
     "platform-sync": {
       "when": "issue_number_exists",
-      "expected_status_label": "status: in-progress",
+      "expected_status_label": "status: pending-design-work",
       "expected_comment_marker": "<!-- sync-issue:{task-id}:{artifact-stem} -->",
       "verify_comment_content": true,
       "verify_task_comment_content": true,
       "verify_issue_type": true,
       "verify_issue_fields": false,
       "verify_milestone": true,
-      "expected_status_label_key": "inProgress",
+      "expected_status_label_key": "pendingDesignWork",
       "expected_comment_marker_key": "artifact"
     }
   }

package/templates/.agents/skills/review-plan/reference/output-templates.en.md

@@ -0,0 +1,87 @@
+# Review Output Templates
+
+Read this file before presenting the final review result to the user.
+
+## Select exactly one output scenario
+
+Evaluate in this order (**env-blocked count does not participate in selection**):
+1. If `Blocker = 0`, `Major = 0`, and `Minor = 0`, use Scenario A, regardless of env-blocked count
+2. If `Blocker = 0` and (`Major > 0` or `Minor > 0`), use Scenario B
+3. If `Blocker > 0` and the issues can be handled by one focused revision, use Scenario C
+4. If the technical plan needs major redesign, broad rewriting, or a restart, use Scenario D
+
+Rules:
+- Do not skip scenario selection
+- Do not mix text from multiple scenarios
+- If `Blocker > 0`, never use an approved template
+- Never count env-blocked items as blocker / major / minor or use them to trigger Scenario B/C/D
+- The selected scenario must include all TUI command formats
+
+### Scenario A: Approved with no findings
+
+```text
+Task {task-id} technical plan review completed. Verdict: approved.
+- Blockers: 0 | Major issues: 0 | Minor issues: 0[ | Environment-blocked: {n} (outside AI fix scope)]
+[- Review report: .agents/workspace/active/{task-id}/{review-artifact}]
+
+Next step - write code:
+  - Claude Code / OpenCode: /code-task {task-id}
+  - Gemini CLI: /agent-infra:code-task {task-id}
+  - Codex CLI: $code-task {task-id}
+
+[When env-blocked > 0, append:]
+Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
+```
+
+### Scenario B: Approved with findings
+
+```text
+Task {task-id} technical plan review completed. Verdict: approved.
+- Blockers: 0 | Major issues: {n} | Minor issues: {n}[ | Environment-blocked: {n} (outside AI fix scope)]
+- Review report: .agents/workspace/active/{task-id}/{review-artifact}
+
+Next step - revise plan before coding (recommended):
+  - Claude Code / OpenCode: /plan-task {task-id}
+  - Gemini CLI: /agent-infra:plan-task {task-id}
+  - Codex CLI: $plan-task {task-id}
+
+Or proceed directly to coding:
+  - Claude Code / OpenCode: /code-task {task-id}
+  - Gemini CLI: /agent-infra:code-task {task-id}
+  - Codex CLI: $code-task {task-id}
+
+[When env-blocked > 0, append:]
+Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
+```
+
+### Scenario C: Changes requested
+
+```text
+Task {task-id} technical plan review completed. Verdict: changes requested.
+- Blockers: {n} | Major issues: {n} | Minor issues: {n}[ | Environment-blocked: {n} (outside AI fix scope)]
+- Review report: .agents/workspace/active/{task-id}/{review-artifact}
+
+Next step - revise technical plan:
+  - Claude Code / OpenCode: /plan-task {task-id}
+  - Gemini CLI: /agent-infra:plan-task {task-id}
+  - Codex CLI: $plan-task {task-id}
+
+[When env-blocked > 0, append:]
+Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
+```
+
+### Scenario D: Rejected
+
+```text
+Task {task-id} technical plan review completed. Verdict: rejected, redesign required.
+- Blockers: {n} | Major issues: {n} | Minor issues: {n}[ | Environment-blocked: {n} (outside AI fix scope)]
+- Review report: .agents/workspace/active/{task-id}/{review-artifact}
+
+Next step - redesign:
+  - Claude Code / OpenCode: /plan-task {task-id}
+  - Gemini CLI: /agent-infra:plan-task {task-id}
+  - Codex CLI: $plan-task {task-id}
+
+[When env-blocked > 0, append:]
+Reminder: env-blocked items belong in the PR description manual verification checklist and should not trigger /plan-task.
+```

package/templates/.agents/skills/review-plan/reference/output-templates.zh-CN.md

@@ -0,0 +1,87 @@
+# 审查输出模板
+
+在向用户汇报最终审查结论之前先读取本文件。
+
+## 选择唯一输出场景
+
+按以下顺序判断（**注意：env-blocked 数量不参与判断**）：
+1. 如果 `Blocker = 0` 且 `Major = 0` 且 `Minor = 0`，使用场景 A（不管 env-blocked 是否 > 0）
+2. 如果 `Blocker = 0` 且（`Major > 0` 或 `Minor > 0`），使用场景 B
+3. 如果 `Blocker > 0`，且问题可以通过一次聚焦修复解决，使用场景 C
+4. 如果技术方案需要重大重构、大范围重写或整体重来，使用场景 D
+
+禁止规则：
+- 不要跳过场景判断步骤
+- 不要混用不同场景的文案
+- 只要 `Blocker > 0`，就绝对不能输出通过模板
+- env-blocked 项绝对不能被计入 blocker / major / minor 计数，也不能用作触发场景 B/C/D 的依据
+- 所选场景中必须包含所有 TUI 命令格式
+
+### 场景 A：通过且无问题
+
+```text
+任务 {task-id} 技术方案审查完成。结论：通过。
+- 阻塞项：0 | 主要问题：0 | 次要问题：0[ | 环境性遗留：{n}（不在 AI 修复范围）]
+[- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}]
+
+下一步 - 编写代码：
+  - Claude Code / OpenCode：/code-task {task-id}
+  - Gemini CLI：/agent-infra:code-task {task-id}
+  - Codex CLI：$code-task {task-id}
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
+```
+
+### 场景 B：通过但有问题
+
+```text
+任务 {task-id} 技术方案审查完成。结论：通过。
+- 阻塞项：0 | 主要问题：{n} | 次要问题：{n}[ | 环境性遗留：{n}（不在 AI 修复范围）]
+- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
+
+下一步 - 修订方案后编码（推荐）：
+  - Claude Code / OpenCode：/plan-task {task-id}
+  - Gemini CLI：/agent-infra:plan-task {task-id}
+  - Codex CLI：$plan-task {task-id}
+
+或直接进入编码：
+  - Claude Code / OpenCode：/code-task {task-id}
+  - Gemini CLI：/agent-infra:code-task {task-id}
+  - Codex CLI：$code-task {task-id}
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
+```
+
+### 场景 C：需要修改
+
+```text
+任务 {task-id} 技术方案审查完成。结论：需要修改。
+- 阻塞项：{n} | 主要问题：{n} | 次要问题：{n}[ | 环境性遗留：{n}（不在 AI 修复范围）]
+- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
+
+下一步 - 修订技术方案：
+  - Claude Code / OpenCode：/plan-task {task-id}
+  - Gemini CLI：/agent-infra:plan-task {task-id}
+  - Codex CLI：$plan-task {task-id}
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
+```
+
+### 场景 D：拒绝
+
+```text
+任务 {task-id} 技术方案审查完成。结论：拒绝，需要重新设计。
+- 阻塞项：{n} | 主要问题：{n} | 次要问题：{n}[ | 环境性遗留：{n}（不在 AI 修复范围）]
+- 审查报告：.agents/workspace/active/{task-id}/{review-artifact}
+
+下一步 - 重新设计：
+  - Claude Code / OpenCode：/plan-task {task-id}
+  - Gemini CLI：/agent-infra:plan-task {task-id}
+  - Codex CLI：$plan-task {task-id}
+
+[当 env-blocked > 0 时，在最后附加一行：]
+提醒：env-blocked 项需在 PR description 的「待人工验证」清单中承接，不应触发 /plan-task。
+```

package/templates/.agents/skills/review-plan/reference/report-template.en.md

@@ -0,0 +1,90 @@
+# Review Report Template
+
+Use this template when writing `review-plan.md` or `review-plan-r{N}.md`.
+
+## Output Template
+
+```markdown
+# Technical Plan Review Report
+
+- **Review Round**: Round {review-round}
+- **Artifact File**: `{review-artifact}`
+- **Review Input**:
+  - `{plan-artifact}`
+
+## State Check
+
+> Paste the raw state-check command output; each command starts with `$ `.
+
+## Review Summary
+
+- **Reviewer**: {reviewer-name}
+- **Review Time**: {timestamp}
+- **Scope**: {file-count and major modules}
+- **Overall Verdict**: {Approved / Changes Requested / Rejected}
+- **Findings (AI-actionable)**: 0 blockers, 0 majors, 0 minors / **env-blocked**: 0
+
+## Findings
+
+### Blockers (must fix)
+
+#### 1. {Issue title}
+**File**: `{file-path}:{line-number}`
+**Description**: {details}
+**Suggested Fix**: {fix suggestion}
+
+### Major Issues (should fix)
+
+#### 1. {Issue title}
+**File**: `{file-path}:{line-number}`
+**Description**: {details}
+**Suggested Fix**: {fix suggestion}
+
+### Minor Issues (optional improvements)
+
+#### 1. {Improvement point}
+**File**: `{file-path}:{line-number}`
+**Suggestion**: {improvement suggestion}
+
+## Environment-Blocked Findings
+
+> Items the AI agent cannot close in the current execution environment; they do not participate in the next plan round. Maintainers carry them in the PR description as a "manual verification required" checklist.
+
+#### 1. {environment-blocked finding title}
+**File**: `{file-path}:{line-number}` (if applicable)
+**Description**: {details}
+**Required Environment**: {e.g. Docker sandbox / macOS host / privileged root / third-party account}
+**Manual Verification Steps**: {steps for the human verifier}
+
+> If this round has no env-blocked findings, keep the section heading and write "None".
+
+
+## Evidence
+
+> Pair each "I verified X" claim with the corresponding raw tool output; the gate only checks that this section exists and at least one `$ ` line is present.
+
+- Claim: {verified claim}
+```text
+$ {command}
+{raw output}
+```
+
+## Highlights
+
+- {what went well}
+
+## Alignment with Plan
+
+- [ ] Implementation matches the technical plan
+- [ ] No unintended scope expansion
+
+## Conclusion and Recommendation
+
+### Approval Decision
+- [ ] Approved
+- [ ] Changes Requested
+- [ ] Rejected
+
+### Next Steps
+{recommended next step}
+```

package/templates/.agents/skills/{review-task → review-plan}/reference/report-template.zh-CN.md

@@ -1,6 +1,6 @@
 # 审查报告模板
 
-编写 `review.md` 或 `review-r{N}.md` 时使用本模板。
+编写 `review-plan.md` 或 `review-plan-r{N}.md` 时使用本模板。
 
 ## 输出模板
 
@@ -10,8 +10,8 @@
 - **审查轮次**：第 {review-round} 轮
 - **产物文件**：`{review-artifact}`
 - **审查输入**：
-  - `{implementation-artifact}`
-  - `{refinement-artifact}`（如存在）
+  - `{code-artifact}`
+  - `{code-artifact}`（如存在）
 
 ## 状态核对
 

package/templates/.agents/skills/review-plan/reference/review-criteria.en.md

@@ -0,0 +1,47 @@
+# Review Criteria
+
+Read this file before reviewing technical plan artifacts or classifying finding severity.
+
+## Technical Plan Review
+
+Follow the `design-review` step in `.agents/workflows/feature-development.yaml`.
+
+**Required review areas**:
+- [ ] The plan covers the approved requirement analysis
+- [ ] Implementation steps are concrete, ordered, and verifiable
+- [ ] Architecture boundaries, data flow, and interface changes are clear
+- [ ] Test strategy covers critical paths, regression risks, and edge cases
+- [ ] Risks, migration, rollback, or compatibility handling are sufficient
+- [ ] The plan avoids over-design and unrelated scope expansion
+
+**Common anti-examples**:
+- Saying "modify related code" without executable steps and verification points
+- Ignoring risks or constraints listed in the analysis
+- Introducing unnecessary abstractions, configuration, or frameworks for a single-use requirement
+
+## Common Review Principles
+
+1. **Strict but fair**: identify issues and acknowledge solid work
+2. **Specific**: cite exact file paths and line numbers
+3. **Actionable**: suggest a concrete fix
+4. **Severity-based**: clearly distinguish blockers, major issues, and minor issues
+
+## Environment-Blocked Classification
+
+Some findings cannot be closed by an AI agent in the current execution environment, for example:
+
+- Missing Docker / sandbox access for end-to-end validation
+- Missing a specific OS for macOS-only behavior
+- Missing third-party accounts / OAuth
+- Missing privileged operations such as root, sudo, or special network access
+
+**Decision tree**: "Can the AI agent close this item independently without changing the environment?"
+- Yes -> blocker / major / minor, based on risk
+- No -> **env-blocked** (a meta-category, not part of severity ordering)
+
+Where env-blocked items go:
+- Record them in an independent review report section named "Environment-Blocked Findings"
+- Include them at the end of the numeric summary, for example `(+ 1 env-blocked)`
+- Do **not** include them in the code-task fix loop; maintainers carry them in the PR description under manual verification
+
+Also inspect the latest technical plan artifact, latest requirement-analysis review artifact, and `task.md` Activity Log so the report reflects the full design context.

package/templates/.agents/skills/review-plan/reference/review-criteria.zh-CN.md

@@ -0,0 +1,47 @@
+# 审查标准
+
+在审查技术方案或划分问题严重程度之前先读取本文件。
+
+## 执行技术方案审查
+
+遵循 `.agents/workflows/feature-development.yaml` 中的 `design-review` 步骤。
+
+**必查范围**：
+- [ ] 方案是否覆盖已批准的需求分析
+- [ ] 实现步骤是否具体、顺序合理且可验证
+- [ ] 架构边界、数据流和接口变化是否清晰
+- [ ] 测试策略是否覆盖关键路径、回归风险和边界情况
+- [ ] 风险、迁移、回滚或兼容性处理是否充分
+- [ ] 方案是否避免过度设计和无关扩张
+
+**常见反例**：
+- 方案只写“修改相关代码”，没有可执行步骤和验证点
+- 设计没有回应分析中列出的风险或约束
+- 为单次需求引入不必要的新抽象、配置或框架
+
+## 通用审查原则
+
+1. **严格但公正**：既要指出问题，也要承认做得好的部分
+2. **具体**：引用准确的文件路径和行号
+3. **可执行**：给出明确可落地的修复建议
+4. **按严重程度分类**：明确区分 blocker、major 和 minor
+
+## 环境性遗留分类
+
+某些发现项是 AI agent 在本执行环境**无法闭环**的，例如：
+
+- 缺 Docker / 沙箱而无法跑端到端验证
+- 缺特定 OS（macOS-only 行为）
+- 缺第三方账号 / OAuth
+- 缺特权操作（root、sudo、特殊网络）
+
+**分类决策树**：「AI agent 能否在不改环境的前提下独立闭环这一项？」
+- 是 -> blocker / major / minor 之一（按风险定档）
+- 否 -> **env-blocked**（元类目，不参与严重程度排序）
+
+env-blocked 项的去向：
+- 写入 review 报告独立段落「环境性遗留」
+- 在数字摘要末尾附带显示（如 `(+ 1 env-blocked)`）
+- **不**进入 code-task 修复循环；维护者在 PR description 中以「待人工验证」清单形式承接
+
+同时检查最新技术方案产物、最新需求分析审查产物和 `task.md` Activity Log，确保报告反映完整的设计上下文。

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

@@ -35,7 +35,7 @@ This project uses three test layers as an optional optimization; if the test sui
 ```
 
 Use for:
-- implement-task / refine-task inner loops
+- code-task inner loops
 - save-and-run / frequent feedback
 - project structure, configuration, and template contract checks
 
@@ -50,7 +50,7 @@ Use for:
 
 Use for:
 - pre-commit hook (automatic)
-- final verification before writing implementation.md / refinement.md
+- final verification before writing code.md / code-r{N}.md
 - local gate before pushing a PR
 
 ### full (complete test suite)

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

@@ -1,74 +1,56 @@
 ---
 name: test
-description: "执行项目完整测试流程"
+description: >
+  执行项目完整测试流程（编译检查 + 单元测试）。
+  当用户要求运行测试或验证代码质量时触发。
 ---
 
 # 执行测试
 
 执行项目的完整测试流程，包括编译检查和单元测试。
 
-<!-- TODO: 将以下命令替换为你的项目实际命令 -->
-
 ## 1. 编译 / 类型检查
 
-```bash
-# TODO: 替换为你的项目编译命令
-# npx tsc --noEmit       (TypeScript)
-# mvn compile             (Maven)
-# go build ./...          (Go)
-# make build              (通用)
-```
-
-确认无编译错误。
+本项目由 Node.js CLI 和模板文件组成，无需编译。跳过此步骤。
 
 ## 2. 运行单元测试（按层级选择）
 
-本项目把测试分为三层（可选优化）；如果项目测试规模较小，可以全部映射到同一个完整测试命令。
+本项目把测试分为三层，按场景选择运行命令；新增测试文件默认归入 **full**，确认足够快且足够核心后，再上调到 core 或 smoke。
 
 ### smoke（目标 <5s）
 
 ```bash
-# TODO: 替换为本项目的 smoke 子集命令
-# npm run test:smoke       (Node.js)
-# pytest -m "not slow"     (Python)
-# go test -short ./...     (Go)
+npm run test:smoke
 ```
 
 适用场景：
-- implement-task / refine-task 内循环
+- code-task 内循环
 - 保存即跑 / 频繁反馈
 - 仅断言项目结构、配置、模板契约
 
 ### core（目标 <15s）
 
 ```bash
-# TODO: 替换为本项目的 core 子集命令
-# npm run test:core        (Node.js)
-# pytest -m "not contract" (Python)
-# go test ./...            (Go)
+npm run test:core
 ```
 
 适用场景：
 - pre-commit hook（自动调用）
-- 写 implementation.md / refinement.md 报告前的最终验证
+- 写 code.md / code-r{N}.md 报告前的最终验证
 - 推送 PR 前的本地把关
 
-### full（完整测试）
+### full（目标 <60s）
 
 ```bash
-# TODO: 替换为本项目的完整测试命令
-# npm test                 (Node.js)
-# mvn test                 (Maven)
-# pytest                   (Python)
-# go test ./...            (Go)
+npm test
 ```
 
 适用场景：
 - release / tag 前
-- CI
+- CI（unit-tests.yml）
 - main 合并前的最终把关
 
-如果项目暂不分层，smoke / core / full 可以全部映射到同一个完整测试命令；分层是反馈速度优化项，不是使用协作工作流的前置条件。
+full 层运行全部项目测试。`npm test` 使用通配匹配项目测试文件，**新增的测试文件会自动归入 full**，这是安全网。
 
 ## 3. 输出结果
 

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -23,6 +23,7 @@ const DEFAULTS = {
   "platform": {
     "type": "github"
   },
+  "requiresPullRequest": true,
   "sandbox": {
     "engine": null,
     "runtimes": [

package/templates/.agents/templates/task.en.md

@@ -11,7 +11,7 @@ priority:                       # Optional Issue field: Urgent | High | Medium |
 effort:                         # Optional Issue field: High | Medium | Low
 start_date:                     # Optional Issue field for Feature: YYYY-MM-DD
 target_date:                    # Optional Issue field for Feature: YYYY-MM-DD
-current_step: analysis         # analysis | design | implementation | review | fix | commit
+current_step: requirement-analysis # requirement-analysis | requirement-analysis-review | technical-design | technical-design-review | code | code-review | completed
 assigned_to:                   # claude | codex | gemini | opencode | human
 ---
 
@@ -46,11 +46,11 @@ assigned_to:                   # claude | codex | gemini | opencode | human
 
 ## Implementation Notes
 
-[Notes from the implementation phase. Decisions made, trade-offs, deviations from design.]
+[Notes from the code phase. Decisions made, trade-offs, deviations from design.]
 
 ## Review Feedback
 
-<!-- Populated by review-task -->
+<!-- Populated by review-* -->
 
 ## Activity Log
 

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

@@ -11,7 +11,7 @@ priority:                       # 可选 Issue 字段：Urgent | High | Medium |
 effort:                         # 可选 Issue 字段：High | Medium | Low
 start_date:                     # Feature 可选 Issue 字段：YYYY-MM-DD
 target_date:                    # Feature 可选 Issue 字段：YYYY-MM-DD
-current_step: analysis         # analysis | design | implementation | review | fix | commit
+current_step: requirement-analysis # requirement-analysis | requirement-analysis-review | technical-design | technical-design-review | code | code-review | completed
 assigned_to:                   # claude | codex | gemini | opencode | human
 ---
 
@@ -50,7 +50,7 @@ assigned_to:                   # claude | codex | gemini | opencode | human
 
 ## 审查反馈
 
-<!-- 由 review-task 填写 -->
+<!-- 由 review-* 填写 -->
 
 ## 活动日志