@fitlab-ai/agent-infra 0.3.0

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

@@ -0,0 +1,169 @@
+#!/bin/sh
+
+set -e
+
+arguments=""
+if [ "$#" -gt 0 ]; then
+  arguments="$*"
+fi
+
+if ! command -v gh >/dev/null 2>&1; then
+  echo "GitHub CLI (\`gh\`) is not installed"
+  exit 1
+fi
+
+if ! gh auth token >/dev/null 2>&1; then
+  echo "GitHub CLI is not authenticated"
+  exit 1
+fi
+
+if ! gh repo view --json nameWithOwner >/dev/null 2>&1; then
+  echo "Unable to access the current repository with gh"
+  exit 1
+fi
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT HUP INT TERM
+
+history_mode="false"
+
+case " $arguments " in
+  *" --history "*) history_mode="true" ;;
+esac
+
+echo "History mode: $history_mode"
+
+current_version=""
+latest_tag="$(git tag --list 'v*' --sort=-v:refname | head -1)"
+
+if [ -n "$latest_tag" ]; then
+  current_version="${latest_tag#v}"
+elif [ -f package.json ]; then
+  current_version="$(node -p "const version = require('./package.json').version || ''; version.replace(/^v/, '').replace(/-.*/, '')")"
+fi
+
+if [ -z "$current_version" ]; then
+  current_version="0.1.0"
+fi
+
+major="${current_version%%.*}"
+rest="${current_version#*.}"
+minor="${rest%%.*}"
+patch="${rest#*.}"
+patch="${patch%%[^0-9]*}"
+
+if ! printf '%s %s %s\n' "$major" "$minor" "$patch" | grep -Eq '^[0-9]+ [0-9]+ [0-9]+$'; then
+  echo "Unable to determine current version baseline"
+  exit 1
+fi
+
+line_milestone="$major.$minor.x"
+next_version="$major.$minor.$((patch + 1))"
+
+echo "Detected version baseline: $current_version"
+echo "Line milestone: $line_milestone"
+echo "Next version milestone: $next_version"
+
+repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
+
+gh api "repos/$repo/milestones?state=all" --paginate \
+  --jq '.[] | [.title, .state] | @tsv' > "$tmpdir/existing.tsv"
+
+cut -f1 "$tmpdir/existing.tsv" > "$tmpdir/existing-titles.txt"
+echo "Existing milestones:"
+cat "$tmpdir/existing.tsv"
+
+cat <<EOF > "$tmpdir/desired.tsv"
+General Backlog	All unsorted backlogged tasks may be completed in a future version.	open
+$line_milestone	Issues that we want to resolve in $major.$minor line.	open
+$next_version	Issues that we want to release in v$next_version.	open
+EOF
+
+if [ "$history_mode" = "true" ]; then
+  git tag --list 'v*' --sort=v:refname > "$tmpdir/history-tags.txt"
+
+  if [ ! -s "$tmpdir/history-tags.txt" ]; then
+    echo "No history tags found matching v*; only standard milestones will be created."
+  else
+    while IFS= read -r tag; do
+      [ -n "$tag" ] || continue
+
+      ver="${tag#v}"
+      h_major="${ver%%.*}"
+      h_rest="${ver#*.}"
+      h_minor="${h_rest%%.*}"
+      h_patch="${h_rest#*.}"
+      h_patch="${h_patch%%[^0-9]*}"
+
+      if ! printf '%s %s %s\n' "$h_major" "$h_minor" "$h_patch" | grep -Eq '^[0-9]+ [0-9]+ [0-9]+$'; then
+        echo "Skip non-semver tag: $tag"
+        continue
+      fi
+
+      printf '%s\t%s\t%s\n' \
+        "$h_major.$h_minor.x" \
+        "Issues that we want to resolve in $h_major.$h_minor line." \
+        "open" >> "$tmpdir/desired.tsv"
+
+      printf '%s\t%s\t%s\n' \
+        "$h_major.$h_minor.$h_patch" \
+        "Issues that we want to release in v$h_major.$h_minor.$h_patch." \
+        "closed" >> "$tmpdir/desired.tsv"
+    done < "$tmpdir/history-tags.txt"
+  fi
+fi
+
+: > "$tmpdir/created.txt"
+: > "$tmpdir/skipped.txt"
+
+while IFS="$(printf '\t')" read -r title description state; do
+  [ -n "$title" ] || continue
+  state="${state:-open}"
+
+  if grep -Fqx "$title" "$tmpdir/existing-titles.txt"; then
+    printf '%s\n' "$title" >> "$tmpdir/skipped.txt"
+    echo "Skip existing milestone: $title"
+    continue
+  fi
+
+  gh api "repos/$repo/milestones" \
+    -f title="$title" \
+    -f description="$description" \
+    -f state="$state" >/dev/null
+
+  printf '%s\n' "$title" >> "$tmpdir/created.txt"
+  printf '%s\n' "$title" >> "$tmpdir/existing-titles.txt"
+  echo "Created milestone: $title ($state)"
+done < "$tmpdir/desired.tsv"
+
+created_count="$(wc -l < "$tmpdir/created.txt" | tr -d ' ')"
+skipped_count="$(wc -l < "$tmpdir/skipped.txt" | tr -d ' ')"
+
+echo "GitHub Milestones initialized."
+echo
+echo "Summary:"
+echo "- Version baseline: $current_version"
+echo "- History mode: $history_mode"
+echo "- Created milestones: $created_count"
+echo "- Skipped existing milestones: $skipped_count"
+
+if [ -s "$tmpdir/created.txt" ]; then
+  echo "- Newly created:"
+  sed 's/^/  - /' "$tmpdir/created.txt"
+fi
+
+if [ -s "$tmpdir/skipped.txt" ]; then
+  echo "- Already present:"
+  sed 's/^/  - /' "$tmpdir/skipped.txt"
+fi
+
+echo
+echo "Notes:"
+echo "- Milestone titles are treated as the idempotency key."
+echo "- General Backlog is the fallback milestone for unsorted work."
+echo "- Without --history, version milestones are created only for the next patch release."
+
+if [ "$history_mode" = "true" ]; then
+  echo "- Historical X.Y.Z tags create X.Y.x milestones as open and X.Y.Z milestones as closed."
+  echo "- Repositories with many tags may hit the GitHub API rate limit."
+fi

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

@@ -0,0 +1,225 @@
+---
+name: plan-task
+description: >
+  为任务设计技术方案并输出详细的实施计划。当用户要求为已完成需求分析的任务设计方案或技术计划时触发。
+  这是一个强制性的人工审查检查点。参数：task-id。
+---
+
+# 设计技术方案
+
+## 行为边界 / 关键规则
+
+- 本技能仅产出技术方案文档（`plan.md` 或 `plan-r{N}.md`）—— 不修改任何业务代码
+- 这是一个**强制性的人工审查检查点** —— 不要自动进入实现阶段
+- 执行本技能后，你**必须**立即更新 task.md 中的任务状态
+
+## 执行步骤
+
+### 1. 验证前置条件
+
+检查必要文件：
+- `.agent-workspace/active/{task-id}/task.md` - 任务文件
+- 至少一个分析产物：`analysis.md` 或 `analysis-r{N}.md`
+
+注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
+
+如果任一文件缺失，提示用户先完成前置步骤。
+
+### 2. 确定方案轮次
+
+扫描 `.agent-workspace/active/{task-id}/` 目录中的方案产物文件：
+- 如果不存在 `plan.md` 且不存在 `plan-r*.md` → 本轮为第 1 轮，产出 `plan.md`
+- 如果存在 `plan.md` 且不存在 `plan-r*.md` → 本轮为第 2 轮，产出 `plan-r2.md`
+- 如果存在 `plan-r{N}.md` → 本轮为第 N+1 轮，产出 `plan-r{N+1}.md`
+
+记录：
+- `{plan-round}`：本轮方案轮次
+- `{plan-artifact}`：本轮方案产物文件名
+
+### 3. 阅读需求分析
+
+扫描任务目录中的分析产物文件（`analysis.md`、`analysis-r{N}.md`）：
+- 如果存在 `analysis-r{N}.md`，读取最高 N 的文件
+- 否则读取 `analysis.md`
+以理解：
+- 需求及其背景
+- 相关文件和代码结构
+- 影响范围和依赖关系
+- 已识别的技术风险
+- 工作量和复杂度评估
+
+### 4. 理解问题
+
+- 阅读分析中识别的相关源码文件
+- 理解当前架构和模式
+- 识别约束条件（向后兼容性、性能等）
+- 考虑边界情况和错误场景
+
+### 5. 设计技术方案
+
+遵循 `.agents/workflows/feature-development.yaml` 中的 `technical-design` 步骤：
+
+**必要任务**：
+- [ ] 定义技术方法和理由
+- [ ] 考虑备选方案并说明权衡
+- [ ] 按顺序详细列出实施步骤
+- [ ] 列出所有需要创建/修改的文件
+- [ ] 定义验证策略（测试、手动检查）
+- [ ] 评估方案的影响和风险
+
+**设计原则**：
+1. **简洁性**：优先选择满足需求的最简方案
+2. **一致性**：遵循现有代码模式和规范
+3. **可测试性**：设计易于测试的方案
+4. **可逆性**：优先选择易于回退的变更
+
+### 6. 输出计划文档
+
+创建 `.agent-workspace/active/{task-id}/{plan-artifact}`。
+
+### 7. 更新任务状态
+
+获取当前时间：
+
+```bash
+date "+%Y-%m-%d %H:%M:%S"
+```
+
+更新 `.agent-workspace/active/{task-id}/task.md`：
+- `current_step`：technical-design
+- `assigned_to`：{当前 AI 代理}
+- `updated_at`：{当前时间}
+- 记录本轮方案产物：`{plan-artifact}`（Round `{plan-round}`）
+- 如任务模板包含 `## 设计` 段落，更新为指向 `{plan-artifact}` 的链接
+- 在工作流进度中标记 technical-design 为已完成，并注明实际轮次（如果任务模板支持）
+- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
+  ```
+  - {yyyy-MM-dd HH:mm:ss} — **Technical Design (Round {N})** by {agent} — Plan completed, awaiting human review → {artifact-filename}
+  ```
+
+### 8. 告知用户
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+输出格式：
+```
+任务 {task-id} 技术方案完成。
+
+方案概要：
+- 轮次：Round {plan-round}
+- 方法：{简要描述}
+- 需修改文件：{数量}
+- 需新建文件：{数量}
+- 预估复杂度：{评估}
+
+产出文件：
+- 技术方案：.agent-workspace/active/{task-id}/{plan-artifact}
+
+重要：人工审查检查点。
+请在继续实现之前审查技术方案。
+
+下一步 - 实施任务：
+  - Claude Code / OpenCode：/implement-task {task-id}
+  - Gemini CLI：/agent-infra:implement-task {task-id}
+  - 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}：{缓解措施}
+```
+
+## 完成检查清单
+
+- [ ] 阅读并理解了需求分析
+- [ ] 考虑了备选方案
+- [ ] 创建了计划文档 `.agent-workspace/active/{task-id}/{plan-artifact}`
+- [ ] 更新了 task.md 中的 `current_step` 为 technical-design
+- [ ] 更新了 task.md 中的 `updated_at` 为当前时间
+- [ ] 在 task.md 中记录了 `{plan-artifact}` 为已完成产物
+- [ ] 在工作流进度中标记了 technical-design 为已完成
+- [ ] 追加了 Activity Log 条目到 task.md
+- [ ] 告知了用户这是人工审查检查点
+- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，不要筛选）
+
+## 停止
+
+完成检查清单后，**立即停止**。
+这是一个**强制性的人工审查检查点** —— 用户必须审查并批准计划后才能继续实现。
+
+## 注意事项
+
+1. **前置条件**：必须已完成至少一轮需求分析（`analysis.md` 或 `analysis-r{N}.md` 存在）
+2. **人工审查**：这是强制性检查点 —— 不要自动进入实现阶段
+3. **计划质量**：计划应足够具体，使另一个 AI 代理无需额外上下文即可实现
+4. **版本化规则**：首轮方案使用 `plan.md`；后续修订使用 `plan-r{N}.md`
+
+## 错误处理
+
+- 任务未找到：提示 "Task {task-id} not found, please check the task ID"
+- 缺少分析：提示 "Analysis not found, please run the analyze-task skill first"

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

@@ -0,0 +1,225 @@
+---
+name: plan-task
+description: >
+  为任务设计技术方案并输出详细的实施计划。当用户要求为已完成需求分析的任务设计方案或技术计划时触发。
+  这是一个强制性的人工审查检查点。参数：task-id。
+---
+
+# 设计技术方案
+
+## 行为边界 / 关键规则
+
+- 本技能仅产出技术方案文档（`plan.md` 或 `plan-r{N}.md`）—— 不修改任何业务代码
+- 这是一个**强制性的人工审查检查点** —— 不要自动进入实现阶段
+- 执行本技能后，你**必须**立即更新 task.md 中的任务状态
+
+## 执行步骤
+
+### 1. 验证前置条件
+
+检查必要文件：
+- `.agent-workspace/active/{task-id}/task.md` - 任务文件
+- 至少一个分析产物：`analysis.md` 或 `analysis-r{N}.md`
+
+注意：`{task-id}` 格式为 `TASK-{yyyyMMdd-HHmmss}`，例如 `TASK-20260306-143022`
+
+如果任一文件缺失，提示用户先完成前置步骤。
+
+### 2. 确定方案轮次
+
+扫描 `.agent-workspace/active/{task-id}/` 目录中的方案产物文件：
+- 如果不存在 `plan.md` 且不存在 `plan-r*.md` → 本轮为第 1 轮，产出 `plan.md`
+- 如果存在 `plan.md` 且不存在 `plan-r*.md` → 本轮为第 2 轮，产出 `plan-r2.md`
+- 如果存在 `plan-r{N}.md` → 本轮为第 N+1 轮，产出 `plan-r{N+1}.md`
+
+记录：
+- `{plan-round}`：本轮方案轮次
+- `{plan-artifact}`：本轮方案产物文件名
+
+### 3. 阅读需求分析
+
+扫描任务目录中的分析产物文件（`analysis.md`、`analysis-r{N}.md`）：
+- 如果存在 `analysis-r{N}.md`，读取最高 N 的文件
+- 否则读取 `analysis.md`
+以理解：
+- 需求及其背景
+- 相关文件和代码结构
+- 影响范围和依赖关系
+- 已识别的技术风险
+- 工作量和复杂度评估
+
+### 4. 理解问题
+
+- 阅读分析中识别的相关源码文件
+- 理解当前架构和模式
+- 识别约束条件（向后兼容性、性能等）
+- 考虑边界情况和错误场景
+
+### 5. 设计技术方案
+
+遵循 `.agents/workflows/feature-development.yaml` 中的 `technical-design` 步骤：
+
+**必要任务**：
+- [ ] 定义技术方法和理由
+- [ ] 考虑备选方案并说明权衡
+- [ ] 按顺序详细列出实施步骤
+- [ ] 列出所有需要创建/修改的文件
+- [ ] 定义验证策略（测试、手动检查）
+- [ ] 评估方案的影响和风险
+
+**设计原则**：
+1. **简洁性**：优先选择满足需求的最简方案
+2. **一致性**：遵循现有代码模式和规范
+3. **可测试性**：设计易于测试的方案
+4. **可逆性**：优先选择易于回退的变更
+
+### 6. 输出计划文档
+
+创建 `.agent-workspace/active/{task-id}/{plan-artifact}`。
+
+### 7. 更新任务状态
+
+获取当前时间：
+
+```bash
+date "+%Y-%m-%d %H:%M:%S"
+```
+
+更新 `.agent-workspace/active/{task-id}/task.md`：
+- `current_step`：technical-design
+- `assigned_to`：{当前 AI 代理}
+- `updated_at`：{当前时间}
+- 记录本轮方案产物：`{plan-artifact}`（Round `{plan-round}`）
+- 如任务模板包含 `## 设计` 段落，更新为指向 `{plan-artifact}` 的链接
+- 在工作流进度中标记 technical-design 为已完成，并注明实际轮次（如果任务模板支持）
+- **追加**到 `## Activity Log`（不要覆盖之前的记录）：
+  ```
+  - {yyyy-MM-dd HH:mm:ss} — **Technical Design (Round {N})** by {agent} — Plan completed, awaiting human review → {artifact-filename}
+  ```
+
+### 8. 告知用户
+
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
+
+输出格式：
+```
+任务 {task-id} 技术方案完成。
+
+方案概要：
+- 轮次：Round {plan-round}
+- 方法：{简要描述}
+- 需修改文件：{数量}
+- 需新建文件：{数量}
+- 预估复杂度：{评估}
+
+产出文件：
+- 技术方案：.agent-workspace/active/{task-id}/{plan-artifact}
+
+重要：人工审查检查点。
+请在继续实现之前审查技术方案。
+
+下一步 - 实施任务：
+  - Claude Code / OpenCode：/implement-task {task-id}
+  - Gemini CLI：/agent-infra:implement-task {task-id}
+  - 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}：{缓解措施}
+```
+
+## 完成检查清单
+
+- [ ] 阅读并理解了需求分析
+- [ ] 考虑了备选方案
+- [ ] 创建了计划文档 `.agent-workspace/active/{task-id}/{plan-artifact}`
+- [ ] 更新了 task.md 中的 `current_step` 为 technical-design
+- [ ] 更新了 task.md 中的 `updated_at` 为当前时间
+- [ ] 在 task.md 中记录了 `{plan-artifact}` 为已完成产物
+- [ ] 在工作流进度中标记了 technical-design 为已完成
+- [ ] 追加了 Activity Log 条目到 task.md
+- [ ] 告知了用户这是人工审查检查点
+- [ ] 告知了用户下一步（必须展示所有 TUI 的命令格式，不要筛选）
+
+## 停止
+
+完成检查清单后，**立即停止**。
+这是一个**强制性的人工审查检查点** —— 用户必须审查并批准计划后才能继续实现。
+
+## 注意事项
+
+1. **前置条件**：必须已完成至少一轮需求分析（`analysis.md` 或 `analysis-r{N}.md` 存在）
+2. **人工审查**：这是强制性检查点 —— 不要自动进入实现阶段
+3. **计划质量**：计划应足够具体，使另一个 AI 代理无需额外上下文即可实现
+4. **版本化规则**：首轮方案使用 `plan.md`；后续修订使用 `plan-r{N}.md`
+
+## 错误处理
+
+- 任务未找到：提示 "Task {task-id} not found, please check the task ID"
+- 缺少分析：提示 "Analysis not found, please run the analyze-task skill first"