@fitlab-ai/agent-infra 0.4.1 → 0.4.3

package/templates/.agents/skills/import-issue/config/verify.json

@@ -0,0 +1,27 @@
+{
+  "skill": "import-issue",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "current_step",
+        "assigned_to"
+      ],
+      "expected_step": "requirement-analysis",
+      "require_issue_number": true
+    },
+    "activity-log": {
+      "expected_action_pattern": "Import Issue",
+      "freshness_minutes": 30
+    },
+    "github-sync": {
+      "when": "issue_number_exists",
+      "issue_must_exist": true
+    }
+  }
+}

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

@@ -29,8 +29,6 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 The script is responsible for:
 - Capturing the current label snapshot before making changes
 - Creating or updating the standard label set with `gh label create --force`
-- Auto-detecting top-level directories and creating one `in:` label per valid directory
-- Falling back to `in: core` when no eligible directory is detected
 - Reporting unmatched GitHub default labels such as `question` and `wontfix`
 - Printing the final execution summary
 
@@ -50,25 +48,57 @@ The script manages these common label families:
 | `status:` | Yes | — | PRs already have their own state flow (Open/Draft/Merged/Closed); Issues use `status:` labels for project tracking |
 | `in:` | Yes | Yes | Both Issues and PRs need module-based filtering |
 
-### 4. Scope discovery rules
+### 4. Configure the `in:` Label Mapping
 
-Directory-derived labels follow these rules:
-- Detect top-level project directories only
-- Skip hidden directories and common generated folders
-- Create `in: core` only when no valid directory remains
-- Do not create any `theme:` labels in this skill
+Check whether `.agents/.airc.json` already contains a `labels.in` field.
+
+#### 4.1 Existing mapping
+
+Show the current mapping and ask whether it should be updated.
+- if no: continue to step 4.3
+- if yes: continue to step 4.2
+
+#### 4.2 Missing mapping or user-requested update
+
+1. Scan top-level project directories while excluding hidden and generated folders.
+2. Analyze the directory contents and suggest meaningful module groupings.
+3. Show the proposed `in:` label mapping and refine it through the user's natural-language feedback.
+4. If the user declines configuration, generate a 1:1 fallback mapping for each top-level directory (`{dir}/`).
+
+#### 4.3 Write the mapping and create labels
+
+1. Write the final mapping to `.agents/.airc.json` under `labels.in`.
+2. Create one `in: {key}` label for each mapping key:
+   ```bash
+   gh label create "in: {key}" --color EBF8DF --description "Module: {key}" --force
+   ```
+3. After user confirmation, delete stale `in:` labels that are no longer present in the final mapping.
 
 ### 5. Output and behavior guarantees
 
 The summary must include:
 - Number of common labels created or updated
-- Number of `in:` labels created or updated
+- The written `labels.in` mapping
+- The number of `in:` labels derived from the mapping keys
 - Confirmation that exact-match GitHub defaults were overwritten
 - Any unmatched GitHub default labels still present
 
 Operational notes:
 - The operation is idempotent because every label uses `gh label create --force`.
-- If the detected `in:` labels need refinement, adjust them manually after initialization.
+- `in:` labels are managed by the AI-guided step together with the `.airc.json` mapping.
+
+### 6. 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.
+
+After summarizing the label initialization, show:
+
+```
+Next step - initialize milestones (optional):
+  - Claude Code / OpenCode: /init-milestones
+  - Gemini CLI: /{{project}}:init-milestones
+  - Codex CLI: $init-milestones
+```
 
 ## Error Handling
 

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

@@ -29,8 +29,6 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 脚本负责：
 - 在修改前保存当前 label 快照
 - 使用 `gh label create --force` 创建或更新标准 label 集合
-- 自动探测顶层目录，并为有效目录创建对应的 `in:` label
-- 在没有可用目录时回退到 `in: core`
 - 提示仍然存在的 GitHub 默认 labels，例如 `question` 和 `wontfix`
 - 输出最终执行摘要
 
@@ -50,25 +48,57 @@ bash .agents/skills/init-labels/scripts/init-labels.sh
 | `status:` | Yes | — | PR 有自身状态流转（Open/Draft/Merged/Closed）；Issue 使用 `status:` label 标记项目管理状态 |
 | `in:` | Yes | Yes | Issue 和 PR 均需按模块筛选 |
 
-### 4. 范围探测规则
+### 4. 配置 `in:` label 映射
 
-目录派生 label 遵循以下规则：
-- 只探测项目顶层目录
-- 排除隐藏目录和常见构建/缓存目录
-- 仅当没有有效目录时才创建 `in: core`
-- 本技能不创建任何 `theme:` labels
+检查 `.agents/.airc.json` 中是否已有 `labels.in` 字段。
+
+#### 4.1 已有映射
+
+展示当前映射，询问用户是否需要更新。
+- 不需要：跳到步骤 4.3
+- 需要：按步骤 4.2 处理
+
+#### 4.2 无映射或用户要求更新
+
+1. 扫描项目顶层目录，排除隐藏目录和常见构建目录。
+2. 分析目录内容，给出有意义的模块分组建议。
+3. 向用户展示建议的 `in:` label 映射，并根据自然语言反馈迭代调整。
+4. 如果用户拒绝配置，则为每个顶层目录生成 1:1 默认映射（`{dir}/`）。
+
+#### 4.3 写入配置并创建 label
+
+1. 将最终映射写入 `.agents/.airc.json` 的 `labels.in` 字段。
+2. 为每个映射 key 创建 `in: {key}` label：
+   ```bash
+   gh label create "in: {key}" --color EBF8DF --description "Module: {key}" --force
+   ```
+3. 询问用户确认后，清理不在最终映射中的旧 `in:` label。
 
 ### 5. 输出与行为保证
 
 摘要必须包含：
 - 创建或更新的通用 labels 数量
-- 创建或更新的 `in:` labels 数量
+- 写入的 `labels.in` 映射结果
+- 按映射 key 计算的 `in:` labels 数量
 - 名称完全匹配的 GitHub 默认 labels 已被覆盖的说明
 - 仍然存在的未匹配 GitHub 默认 labels
 
 执行说明：
 - 整个操作具备幂等性，因为每个 label 都使用 `gh label create --force`。
-- 如果自动探测出的 `in:` labels 需要细化，请在初始化后手动调整。
+- `in:` labels 由 AI 引导步骤和 `.airc.json` 映射统一管理。
+
+### 6. 告知用户
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+输出 labels 初始化摘要后，提示：
+
+```
+下一步 - 初始化 Milestones（可选）：
+  - Claude Code / OpenCode：/init-milestones
+  - Gemini CLI：/agent-infra:init-milestones
+  - Codex CLI：$init-milestones
+```
 
 ## 错误处理
 

package/templates/.agents/skills/init-labels/scripts/init-labels.sh

@@ -58,25 +58,6 @@ while IFS="$(printf '\t')" read -r name color description; do
   gh label create "$name" --color "$color" --description "$description" --force
 done < "$tmpdir/common.tsv"
 
-project_dirs=$(
-  find . -mindepth 1 -maxdepth 1 -type d ! -name '.*' |
-  sed 's#^\./##' |
-  grep -Ev '^(node_modules|vendor|dist|build|out|target|tmp|temp|log|logs|coverage|__pycache__)$' |
-  sort -u
-)
-
-if [ -z "$project_dirs" ]; then
-  project_dirs="core"
-fi
-
-printf '%s\n' "$project_dirs" | while IFS= read -r dir; do
-  [ -n "$dir" ] || continue
-  gh label create "in: $dir" \
-    --color EBF8DF \
-    --description "Issues in $dir" \
-    --force
-done
-
 gh label list --limit 200 --json name --jq '.[].name' > "$tmpdir/final-names.txt"
 cp "$tmpdir/final-names.txt" "$tmpdir/final.txt"
 
@@ -88,13 +69,11 @@ for label in bug documentation duplicate enhancement invalid question wontfix; d
 done
 
 common_count="$(wc -l < "$tmpdir/common.tsv" | tr -d ' ')"
-in_count="$(printf '%s\n' "$project_dirs" | sed '/^$/d' | wc -l | tr -d ' ')"
 
 echo "GitHub Labels initialized."
 echo
 echo "Summary:"
 echo "- Common labels created or updated: $common_count"
-echo "- in: labels created or updated: $in_count"
 echo "- Exact-match GitHub defaults overwritten: good first issue, help wanted"
 
 if [ -s "$tmpdir/unmatched-defaults.txt" ]; then
@@ -108,4 +87,4 @@ echo
 echo "Notes:"
 echo "- theme: labels were intentionally not created."
 echo "- The operation is idempotent because every label uses gh label create --force."
-echo "- If the detected in: labels need refinement, adjust them manually after initialization."
+echo "- in: labels are managed by the AI-guided step in the SKILL."

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

@@ -61,6 +61,19 @@ Operational notes:
 - Historical `X.Y.Z` tags create `X.Y.x` milestones as open and `X.Y.Z` milestones as closed.
 - Repositories with many tags may hit the GitHub API rate limit.
 
+### 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.
+
+After summarizing the milestone initialization, show:
+
+```
+Next step - initialize labels (optional):
+  - Claude Code / OpenCode: /init-labels
+  - Gemini CLI: /{{project}}:init-labels
+  - Codex CLI: $init-labels
+```
+
 ## Error Handling
 
 - `gh` not found: prompt "GitHub CLI (`gh`) is not installed"

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

@@ -61,6 +61,19 @@ bash .agents/skills/init-milestones/scripts/init-milestones.sh "$ARGUMENTS"
 - 历史 `X.Y.Z` tag 会生成开启状态的 `X.Y.x` 和关闭状态的 `X.Y.Z`。
 - 标签较多的仓库可能触发 GitHub API rate limit。
 
+### 5. 告知用户
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+输出 milestones 初始化摘要后，提示：
+
+```
+下一步 - 初始化 Labels（可选）：
+  - Claude Code / OpenCode：/init-labels
+  - Gemini CLI：/agent-infra:init-labels
+  - Codex CLI：$init-labels
+```
+
 ## 错误处理
 
 - 未找到 `gh`：提示 "GitHub CLI (`gh`) is not installed"

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

@@ -66,10 +66,11 @@ Follow the `technical-design` step in `.agents/workflows/feature-development.yam
 - [ ] Assess impact and risks
 
 **Design principles**:
-1. **Simplicity**: prefer the simplest approach that satisfies the requirement
-2. **Consistency**: follow existing code patterns and conventions
-3. **Testability**: design for straightforward testing
-4. **Reversibility**: prefer changes that are easy to roll back
+1. **Architectural soundness**: choose the structurally correct approach; diff size is not the primary criterion. Do not pile changes onto an unsound structure just to keep the diff small
+2. **Simplicity**: given a sound architecture, prefer the simplest approach and avoid over-engineering
+3. **Consistency**: follow existing code patterns and conventions
+4. **Testability**: design for straightforward testing
+5. **Reversibility**: prefer changes that are easy to roll back
 
 ### 6. Output Plan Document
 
@@ -95,7 +96,30 @@ Update `.agents/workspace/active/{task-id}/task.md`:
   - {yyyy-MM-dd HH:mm:ss} — **Technical Design (Round {N})** by {agent} — Plan completed, awaiting human review → {artifact-filename}
   ```
 
-### 8. Inform User
+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
+- Set `status: pending-design-work`
+- Publish the `{plan-artifact}` comment
+- Create or update the `<!-- sync-issue:{task-id}:task -->` comment (follow the task.md comment sync rule in issue-sync.md)
+
+### 8. Verification Gate
+
+Run the verification gate to confirm the task artifact and sync state are valid:
+
+```bash
+node .agents/scripts/validate-artifact.js gate plan-task .agents/workspace/active/{task-id} {plan-artifact} --format text
+```
+
+Handle the result as follows:
+- exit code 0 (all checks passed) -> continue to the "Inform User" step
+- exit code 1 (validation failed) -> fix the reported issues and run the gate again
+- exit code 2 (network blocked) -> stop and tell the user that human intervention is required
+
+Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
+
+### 9. Inform User
+
+> 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.
 
@@ -122,76 +146,6 @@ Next step - implement the task:
   - Codex CLI: $implement-task {task-id}
 ```
 
-## Output Template
-
-```markdown
-# Technical Plan
-
-- **Plan round**: Round {plan-round}
-- **Artifact file**: `{plan-artifact}`
-
-## Problem Understanding
-{Summarize the problem to solve and the key constraints}
-
-## Constraints
-- {Constraint 1}
-- {Constraint 2}
-
-## Option Comparison
-
-### Option A: {Name}
-- **Approach**: {Description}
-- **Pros**: {Advantages}
-- **Cons**: {Drawbacks}
-
-### Option B: {Name}
-- **Approach**: {Description}
-- **Pros**: {Advantages}
-- **Cons**: {Drawbacks}
-
-### Decision
-{Which option was chosen and why}
-
-## Technical Approach
-{Detailed description of the selected approach}
-
-## Implementation Steps
-
-### Step 1: {Title}
-- **File**: `{file-path}`
-- **Action**: {What to do}
-- **Details**: {Specific details}
-
-### Step 2: {Title}
-...
-
-## File List
-
-### New Files
-- `{file-path}` - {Purpose}
-
-### Modified Files
-- `{file-path}` - {Planned changes}
-
-## Verification Strategy
-
-### Unit Tests
-- {Test case 1}
-- {Test case 2}
-
-### Manual Validation
-- {Validation step}
-
-## Impact Assessment
-- Breaking change: {Yes/No - details}
-- Performance impact: {Assessment}
-- Security considerations: {Assessment}
-
-## Risk Control
-- {Risk 1}: {Mitigation}
-- {Risk 2}: {Mitigation}
-```
-
 ## Completion Checklist
 
 - [ ] Read and understood the requirements analysis

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

@@ -66,10 +66,11 @@ description: "为任务设计技术方案和实施计划"
 - [ ] 评估方案的影响和风险
 
 **设计原则**：
-1. **简洁性**：优先选择满足需求的最简方案
-2. **一致性**：遵循现有代码模式和规范
-3. **可测试性**：设计易于测试的方案
-4. **可逆性**：优先选择易于回退的变更
+1. **架构合理性**：选择结构正确的方案，改动大小不是首要依据。不要为了减少 diff 而在不合理的结构上叠加
+2. **简洁性**：在架构合理的前提下，优先选择最简方案，避免过度设计
+3. **一致性**：遵循现有代码模式和规范
+4. **可测试性**：设计易于测试的方案
+5. **可逆性**：优先选择易于回退的变更
 
 ### 6. 输出计划文档
 
@@ -95,7 +96,30 @@ date "+%Y-%m-%d %H:%M:%S"
   - {yyyy-MM-dd HH:mm:ss} — **Technical Design (Round {N})** by {agent} — Plan completed, awaiting human review → {artifact-filename}
   ```
 
-### 8. 告知用户
+如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
+- 执行前先读取 `.agents/rules/issue-sync.md`
+- 设置 `status: pending-design-work`
+- 发布 `{plan-artifact}` 评论
+- 创建或更新 `<!-- sync-issue:{task-id}:task -->` 评论（按 issue-sync.md 的 task.md 评论同步规则）
+
+### 8. 完成校验
+
+运行完成校验，确认任务产物和同步状态符合规范：
+
+```bash
+node .agents/scripts/validate-artifact.js gate plan-task .agents/workspace/active/{task-id} {plan-artifact} --format text
+```
+
+处理结果：
+- 退出码 0（全部通过）-> 继续到「告知用户」步骤
+- 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
+- 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入
+
+将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
+
+### 9. 告知用户
+
+> 仅在校验通过后执行本步骤。
 
 > **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
 
@@ -122,76 +146,6 @@ date "+%Y-%m-%d %H:%M:%S"
   - Codex CLI：$implement-task {task-id}
 ```
 
-## 输出模板
-
-```markdown
-# 技术方案
-
-- **方案轮次**：Round {plan-round}
-- **产物文件**：`{plan-artifact}`
-
-## 问题理解
-{总结需要解决的问题和关键约束}
-
-## 约束条件
-- {约束 1}
-- {约束 2}
-
-## 方案对比
-
-### 方案 A：{名称}
-- **方法**：{描述}
-- **优点**：{优势}
-- **缺点**：{劣势}
-
-### 方案 B：{名称}
-- **方法**：{描述}
-- **优点**：{优势}
-- **缺点**：{劣势}
-
-### 决策
-{选择哪个方案以及原因}
-
-## 技术方法
-{所选方案的详细描述}
-
-## 实施步骤
-
-### 步骤 1：{标题}
-- **文件**：`{file-path}`
-- **操作**：{要做什么}
-- **详情**：{具体细节}
-
-### 步骤 2：{标题}
-...
-
-## 文件清单
-
-### 新建文件
-- `{file-path}` - {用途}
-
-### 修改文件
-- `{file-path}` - {修改内容}
-
-## 验证策略
-
-### 单元测试
-- {测试用例 1}
-- {测试用例 2}
-
-### 手动验证
-- {验证步骤}
-
-## 影响评估
-- 破坏性变更：{是/否 - 详情}
-- 性能影响：{评估}
-- 安全考量：{评估}
-
-## 风险控制
-- {风险 1}：{缓解措施}
-- {风险 2}：{缓解措施}
-```
-
 ## 完成检查清单
 
 - [ ] 阅读并理解了需求分析

package/templates/.agents/skills/plan-task/config/verify.json

@@ -0,0 +1,42 @@
+{
+  "skill": "plan-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "current_step",
+        "assigned_to"
+      ],
+      "expected_step": "technical-design"
+    },
+    "artifact": {
+      "file_pattern": "plan.md|plan-r{N}.md",
+      "required_sections": [
+        "问题理解",
+        "约束条件",
+        "方案对比",
+        "技术方法",
+        "实施步骤",
+        "文件清单",
+        "验证策略"
+      ],
+      "freshness_minutes": 30
+    },
+    "activity-log": {
+      "expected_action_pattern": "Technical Design \\(Round \\d+\\)",
+      "freshness_minutes": 30
+    },
+    "github-sync": {
+      "when": "issue_number_exists",
+      "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
+    }
+  }
+}

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

@@ -54,12 +54,59 @@ Get the current time:
 date "+%Y-%m-%d %H:%M:%S"
 ```
 
-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}`
+Update task.md:
+- review the `## Requirements` section and only change items from `- [ ]` to `- [x]` when they are newly satisfied by this round's fixes and passing tests
+- 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}`
 
-### 7. Inform User
+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
+- Set `status: in-progress`
+- Refine `in:` labels from the branch diff by following `.agents/rules/issue-sync.md` (add/remove when a mapping exists, add-only when it does not)
+- Sync checked `## Requirements` items to the Issue body
+- 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)
 
-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.
+### 7. Verification Gate
+
+Run the verification gate to confirm the task artifact and sync state are valid:
+
+```bash
+node .agents/scripts/validate-artifact.js gate refine-task .agents/workspace/active/{task-id} {refinement-artifact} --format text
+```
+
+Handle the result as follows:
+- exit code 0 (all checks passed) -> continue to the "Inform User" step
+- exit code 1 (validation failed) -> fix the reported issues and run the gate again
+- exit code 2 (network blocked) -> stop and tell the user that human intervention is required
+
+Keep the gate output in your reply as fresh evidence. Do not claim completion without output from this run.
+
+### 8. Inform User
+
+> 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.
+
+After summarizing the fixes, choose the next step based on severity:
+
+If the round fixed any Blocker or Major issues (recommended):
+
+```
+Next step - code review:
+  - Claude Code / OpenCode: /review-task {task-id}
+  - Gemini CLI: /{{project}}:review-task {task-id}
+  - Codex CLI: $review-task {task-id}
+```
+
+If the round fixed Minor issues only (low risk):
+
+```
+Next step - commit changes:
+  - Claude Code / OpenCode: /commit
+  - Gemini CLI: /{{project}}:commit
+  - Codex CLI: $commit
+```
 
 ## Completion Checklist