@fitlab-ai/agent-infra 0.4.1 → 0.4.3

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

@@ -118,7 +118,30 @@ Update `.agents/workspace/active/{task-id}/task.md`:
   - {yyyy-MM-dd HH:mm:ss} — **Requirement Analysis (Round {N})** by {agent} — Analysis completed → {analysis-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: pending-design-work`
+- Publish the `{analysis-artifact}` comment
+- Create or update the `<!-- sync-issue:{task-id}:task -->` comment (follow the task.md comment sync rule in issue-sync.md)
+
+### 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 analyze-task .agents/workspace/active/{task-id} {analysis-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.
 

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

@@ -118,7 +118,30 @@ date "+%Y-%m-%d %H:%M:%S"
   - {yyyy-MM-dd HH:mm:ss} — **Requirement Analysis (Round {N})** by {agent} — Analysis completed → {analysis-artifact}
   ```
 
-### 7. 告知用户
+如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续）：
+- 执行前先读取 `.agents/rules/issue-sync.md`
+- 设置 `status: pending-design-work`
+- 发布 `{analysis-artifact}` 评论
+- 创建或更新 `<!-- sync-issue:{task-id}:task -->` 评论（按 issue-sync.md 的 task.md 评论同步规则）
+
+### 7. 完成校验
+
+运行完成校验，确认任务产物和同步状态符合规范：
+
+```bash
+node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/active/{task-id} {analysis-artifact} --format text
+```
+
+处理结果：
+- 退出码 0（全部通过）-> 继续到「告知用户」步骤
+- 退出码 1（校验失败）-> 根据输出修复问题后重新运行校验
+- 退出码 2（网络中断）-> 停止执行并告知用户需要人工介入
+
+将校验输出保留在回复中作为当次验证输出。没有当次校验输出，不得声明完成。
+
+### 8. 告知用户
+
+> 仅在校验通过后执行本步骤。
 
 > **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。
 

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

@@ -0,0 +1,41 @@
+{
+  "skill": "analyze-task",
+  "checks": {
+    "task-meta": {
+      "required_fields": [
+        "id",
+        "type",
+        "workflow",
+        "status",
+        "created_at",
+        "updated_at",
+        "current_step",
+        "assigned_to"
+      ],
+      "expected_step": "requirement-analysis"
+    },
+    "artifact": {
+      "file_pattern": "analysis.md|analysis-r{N}.md",
+      "required_sections": [
+        "需求来源",
+        "需求理解",
+        "相关文件",
+        "影响评估",
+        "技术风险",
+        "工作量和复杂度评估"
+      ],
+      "freshness_minutes": 30
+    },
+    "activity-log": {
+      "expected_action_pattern": "Requirement Analysis \\(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/archive-tasks/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: archive-tasks
+description: "Archive completed tasks into a date-organized workspace directory"
+---
+
+# Archive Completed Tasks
+
+Move completed tasks from `.agents/workspace/completed/` into `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/` and rebuild the archive index `manifest.md`.
+
+## Execution Flow
+
+### 1. Verify the environment
+
+Confirm that `.agents/workspace/completed/` exists, then choose one of these four invocation modes:
+- no arguments: archive every completed task
+- `--days N`: keep the most recent `N` days and archive older tasks
+- `--before YYYY-MM-DD`: archive only tasks completed before the given date
+- `TASK-ID...`: archive only the selected tasks
+
+### 2. Run the archive script
+
+Execute:
+
+```bash
+bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before YYYY-MM-DD | TASK-ID...]
+```
+
+The script is responsible for:
+- reading `completed_at` from `task.md` frontmatter and falling back to `updated_at`
+- moving task directories directly into `YYYY/MM/DD/TASK-xxx/` without compression
+- skipping already archived, missing, or malformed tasks
+- rebuilding `.agents/workspace/archive/manifest.md` from all archived tasks
+- printing an archive and skip summary
+
+### 3. Inform the user
+
+Report:
+- how many tasks were archived
+- how many tasks were skipped and why
+- the path to `manifest.md`

package/templates/.agents/skills/archive-tasks/SKILL.zh-CN.md

@@ -0,0 +1,40 @@
+---
+name: archive-tasks
+description: "归档已完成任务到按日期组织的目录"
+---
+
+# 归档已完成任务
+
+将 `.agents/workspace/completed/` 中的已完成任务移动到 `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/`，并重建归档索引 `manifest.md`。
+
+## 执行流程
+
+### 1. 验证环境
+
+确认 `.agents/workspace/completed/` 存在，并根据用户输入选择以下四种调用方式之一：
+- 无参数：归档全部已完成任务
+- `--days N`：保留最近 `N` 天，仅归档更早的任务
+- `--before YYYY-MM-DD`：仅归档指定日期之前的任务
+- `TASK-ID...`：仅归档指定任务
+
+### 2. 运行归档脚本
+
+执行以下命令：
+
+```bash
+bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before YYYY-MM-DD | TASK-ID...]
+```
+
+脚本负责：
+- 解析 `task.md` frontmatter 中的 `completed_at`（缺失时回退到 `updated_at`）
+- 按 `YYYY/MM/DD/TASK-xxx/` 目录直接移动任务，不压缩
+- 跳过已归档、缺少元数据或不存在的任务
+- 全量重建 `.agents/workspace/archive/manifest.md`
+- 输出归档与跳过摘要
+
+### 3. 告知用户
+
+向用户汇报：
+- 本次归档的任务数量
+- 跳过的任务数量和原因
+- `manifest.md` 的路径

package/templates/.agents/skills/archive-tasks/scripts/archive-tasks.sh

@@ -0,0 +1,403 @@
+#!/bin/sh
+
+set -e
+
+SCRIPT_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd)
+REPO_ROOT=$(CDPATH= cd "$SCRIPT_DIR/../../../.." && pwd)
+WORKSPACE_ROOT="$REPO_ROOT/.agents/workspace"
+COMPLETED_DIR="$WORKSPACE_ROOT/completed"
+ARCHIVE_DIR="$WORKSPACE_ROOT/archive"
+MANIFEST_PATH="$ARCHIVE_DIR/manifest.md"
+
+tmpdir="$(mktemp -d)"
+trap 'rm -rf "$tmpdir"' EXIT HUP INT TERM
+
+IDS_FILE="$tmpdir/task-ids.txt"
+: > "$IDS_FILE"
+
+usage() {
+  cat <<'EOF'
+Usage: bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before YYYY-MM-DD | TASK-ID...]
+EOF
+}
+
+trim_value() {
+  printf '%s' "$1" | sed "s/^['\"]//; s/['\"]$//"
+}
+
+extract_field() {
+  task_file="$1"
+  field_name="$2"
+
+  awk -v field_name="$field_name" '
+    BEGIN {
+      frontmatter = 0
+    }
+
+    /^---[[:space:]]*$/ {
+      frontmatter += 1
+      if (frontmatter == 1) {
+        next
+      }
+      exit
+    }
+
+    frontmatter == 1 && index($0, field_name ":") == 1 {
+      value = $0
+      sub("^" field_name ":[[:space:]]*", "", value)
+      print value
+      exit
+    }
+  ' "$task_file"
+}
+
+extract_completed_at() {
+  task_file="$1"
+  completed_at=$(extract_field "$task_file" "completed_at")
+
+  if [ -z "$completed_at" ]; then
+    completed_at=$(extract_field "$task_file" "updated_at")
+  fi
+
+  trim_value "$completed_at"
+}
+
+extract_type() {
+  trim_value "$(extract_field "$1" "type")"
+}
+
+extract_title() {
+  title=$(
+    awk '
+      BEGIN {
+        frontmatter = 0
+      }
+
+      /^---[[:space:]]*$/ {
+        frontmatter += 1
+        next
+      }
+
+      frontmatter < 2 {
+        next
+      }
+
+      /^# / {
+        sub(/^# /, "")
+        print
+        exit
+      }
+    ' "$1"
+  )
+
+  printf '%s' "$title" | sed 's/^任务：//; s/^Task: //' | tr '\t\r\n' '   ' | sed 's/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; s/|/\\|/g'
+}
+
+is_valid_date() {
+  case "$1" in
+    ????-??-??)
+      return 0
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+date_to_int() {
+  printf '%s' "$1" | tr -d '-'
+}
+
+cutoff_date() {
+  days="$1"
+
+  if date -v-"$days"d "+%Y-%m-%d" >/dev/null 2>&1; then
+    date -v-"$days"d "+%Y-%m-%d"
+    return 0
+  fi
+
+  date -d "$days days ago" "+%Y-%m-%d"
+}
+
+find_archived_task_dir() {
+  task_id="$1"
+
+  for year_dir in "$ARCHIVE_DIR"/[0-9][0-9][0-9][0-9]; do
+    [ -d "$year_dir" ] || continue
+
+    for month_dir in "$year_dir"/[0-9][0-9]; do
+      [ -d "$month_dir" ] || continue
+
+      for day_dir in "$month_dir"/[0-9][0-9]; do
+        [ -d "$day_dir" ] || continue
+
+        archived_dir="$day_dir/$task_id"
+        if [ -d "$archived_dir" ]; then
+          printf '%s\n' "$archived_dir"
+          return 0
+        fi
+      done
+    done
+  done
+
+  return 1
+}
+
+log_skip() {
+  task_id="$1"
+  reason="$2"
+  skipped_count=$((skipped_count + 1))
+  printf 'Skipped %s (%s)\n' "$task_id" "$reason"
+}
+
+archive_task_dir() {
+  task_dir="$1"
+  task_id=$(basename "$task_dir")
+  task_file="$task_dir/task.md"
+
+  if [ ! -f "$task_file" ]; then
+    log_skip "$task_id" "missing task.md"
+    return 0
+  fi
+
+  completed_at=$(extract_completed_at "$task_file")
+  task_date=$(printf '%s' "$completed_at" | cut -c1-10)
+
+  if ! is_valid_date "$task_date"; then
+    log_skip "$task_id" "missing completed_at/updated_at date"
+    return 0
+  fi
+
+  year=$(printf '%s' "$task_date" | cut -c1-4)
+  month=$(printf '%s' "$task_date" | cut -c6-7)
+  day=$(printf '%s' "$task_date" | cut -c9-10)
+  destination_dir="$ARCHIVE_DIR/$year/$month/$day/$task_id"
+  relative_path="$year/$month/$day/$task_id/"
+
+  if [ -d "$destination_dir" ]; then
+    log_skip "$task_id" "already archived at $relative_path"
+    return 0
+  fi
+
+  mkdir -p "$ARCHIVE_DIR/$year/$month/$day"
+  mv "$task_dir" "$destination_dir"
+  archived_count=$((archived_count + 1))
+  printf 'Archived %s -> %s\n' "$task_id" "$relative_path"
+}
+
+should_archive_filtered_task() {
+  task_dir="$1"
+  task_file="$task_dir/task.md"
+
+  if [ ! -f "$task_file" ]; then
+    return 0
+  fi
+
+  completed_at=$(extract_completed_at "$task_file")
+  task_date=$(printf '%s' "$completed_at" | cut -c1-10)
+
+  if ! is_valid_date "$task_date"; then
+    return 0
+  fi
+
+  task_value=$(date_to_int "$task_date")
+  cutoff_value=$(date_to_int "$FILTER_DATE")
+
+  [ "$task_value" -lt "$cutoff_value" ]
+}
+
+rebuild_manifest() {
+  entries_file="$tmpdir/manifest.tsv"
+  generated_at=$(date "+%Y-%m-%d %H:%M:%S")
+
+  mkdir -p "$ARCHIVE_DIR"
+  : > "$entries_file"
+
+  for year_dir in "$ARCHIVE_DIR"/[0-9][0-9][0-9][0-9]; do
+    [ -d "$year_dir" ] || continue
+    year=$(basename "$year_dir")
+
+    for month_dir in "$year_dir"/[0-9][0-9]; do
+      [ -d "$month_dir" ] || continue
+      month=$(basename "$month_dir")
+
+      for day_dir in "$month_dir"/[0-9][0-9]; do
+        [ -d "$day_dir" ] || continue
+        day=$(basename "$day_dir")
+
+        for task_dir in "$day_dir"/TASK-*; do
+          [ -d "$task_dir" ] || continue
+
+          task_id=$(basename "$task_dir")
+          task_file="$task_dir/task.md"
+          relative_path="$year/$month/$day/$task_id/"
+          title="$task_id"
+          task_type="unknown"
+          completed_at="$year-$month-$day"
+
+          if [ -f "$task_file" ]; then
+            file_completed_at=$(extract_completed_at "$task_file")
+            file_type=$(extract_type "$task_file")
+            file_title=$(extract_title "$task_file")
+
+            if [ -n "$file_completed_at" ]; then
+              completed_at="$file_completed_at"
+            fi
+
+            if [ -n "$file_type" ]; then
+              task_type="$file_type"
+            fi
+
+            if [ -n "$file_title" ]; then
+              title="$file_title"
+            fi
+          fi
+
+          printf '%s\t%s\t%s\t%s\t%s\n' "$completed_at" "$task_id" "$title" "$task_type" "$relative_path" >> "$entries_file"
+        done
+      done
+    done
+  done
+
+  {
+    echo "# Archive Manifest"
+    echo
+    echo "> Auto-generated by archive-tasks. Do not edit manually."
+    echo "> Last updated: $generated_at"
+    echo
+    echo "| Task ID | Title | Type | Completed | Path |"
+    echo "| --- | --- | --- | --- | --- |"
+
+    if [ -s "$entries_file" ]; then
+      LC_ALL=C sort -r "$entries_file" | while IFS="$(printf '\t')" read -r completed_at task_id title task_type relative_path; do
+        printf '| %s | %s | %s | %s | %s |\n' "$task_id" "$title" "$task_type" "$completed_at" "$relative_path"
+      done
+    fi
+  } > "$MANIFEST_PATH"
+}
+
+if [ ! -d "$COMPLETED_DIR" ]; then
+  echo "Completed task directory not found: $COMPLETED_DIR"
+  exit 1
+fi
+
+MODE="all"
+FILTER_DATE=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --days)
+      if [ "$MODE" != "all" ] || [ -s "$IDS_FILE" ]; then
+        echo "Cannot combine --days with other filters or task IDs"
+        exit 1
+      fi
+
+      if [ -z "${2:-}" ]; then
+        echo "Missing value for --days"
+        exit 1
+      fi
+
+      case "$2" in
+        ''|*[!0-9]*)
+          echo "--days expects a non-negative integer"
+          exit 1
+          ;;
+      esac
+
+      FILTER_DATE=$(cutoff_date "$2")
+      MODE="days"
+      shift 2
+      ;;
+    --before)
+      if [ "$MODE" != "all" ] || [ -s "$IDS_FILE" ]; then
+        echo "Cannot combine --before with other filters or task IDs"
+        exit 1
+      fi
+
+      if [ -z "${2:-}" ]; then
+        echo "Missing value for --before"
+        exit 1
+      fi
+
+      if ! is_valid_date "$2"; then
+        echo "--before expects a date in YYYY-MM-DD format"
+        exit 1
+      fi
+
+      FILTER_DATE="$2"
+      MODE="before"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    -*)
+      echo "Unknown option: $1"
+      usage
+      exit 1
+      ;;
+    *)
+      printf '%s\n' "$1" >> "$IDS_FILE"
+      shift
+      ;;
+  esac
+done
+
+if [ -s "$IDS_FILE" ]; then
+  if [ "$MODE" != "all" ]; then
+    echo "Cannot combine task IDs with --days or --before"
+    exit 1
+  fi
+
+  MODE="ids"
+fi
+
+archived_count=0
+skipped_count=0
+
+case "$MODE" in
+  all)
+    for task_dir in "$COMPLETED_DIR"/TASK-*; do
+      [ -d "$task_dir" ] || continue
+      archive_task_dir "$task_dir"
+    done
+    ;;
+  days|before)
+    for task_dir in "$COMPLETED_DIR"/TASK-*; do
+      [ -d "$task_dir" ] || continue
+
+      if should_archive_filtered_task "$task_dir"; then
+        archive_task_dir "$task_dir"
+      fi
+    done
+    ;;
+  ids)
+    while IFS= read -r task_id; do
+      [ -n "$task_id" ] || continue
+      task_dir="$COMPLETED_DIR/$task_id"
+
+      if [ -d "$task_dir" ]; then
+        archive_task_dir "$task_dir"
+        continue
+      fi
+
+      archived_dir=$(find_archived_task_dir "$task_id" || true)
+      if [ -n "$archived_dir" ]; then
+        relative_path=${archived_dir#"$ARCHIVE_DIR"/}
+        log_skip "$task_id" "already archived at $relative_path/"
+        continue
+      fi
+
+      log_skip "$task_id" "not found in completed/"
+    done < "$IDS_FILE"
+    ;;
+esac
+
+rebuild_manifest
+
+echo
+echo "Summary:"
+printf -- '- Archived: %s\n' "$archived_count"
+printf -- '- Skipped: %s\n' "$skipped_count"
+printf -- '- Manifest: %s\n' ".agents/workspace/archive/manifest.md"

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

@@ -68,20 +68,32 @@ ls .agents/workspace/blocked/{task-id}/task.md
 
 ### 6. Sync to Issue (Optional)
 
-Check whether `task.md` includes an `issue_number` field whose value is neither empty nor `N/A`. If not, **skip this step and output nothing**.
+Check whether `task.md` includes a valid `issue_number`. If not, skip this step.
 
-If a valid `issue_number` exists, suggest syncing:
+> Status-label sync rules live in `.agents/rules/issue-sync.md`. Read that file before syncing.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent.
+If a valid `issue_number` exists, set `status: blocked` directly.
 
-```
-(Optional) Sync the blocking status to the Issue:
-  - Claude Code / OpenCode: /sync-issue {issue_number}
-  - Gemini CLI: /{{project}}:sync-issue {issue_number}
-  - Codex CLI: $sync-issue {issue_number}
+### 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 block-task .agents/workspace/blocked/{task-id} --format text
 ```
 
-### 7. Inform User
+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.
 
 Output format:
 ```
@@ -94,35 +106,11 @@ Archived to: .agents/workspace/blocked/{task-id}/
 To unblock when the issue is resolved:
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # Then update task.md: status -> active, remove blocked_at
-```
-
-## Output Template
-
-Blocking information section to add to task.md:
-
-```markdown
-## Blocking Information
-
-### Summary
-{One-line description of why the task is blocked}
-
-### Problem Description
-{Detailed description of the blocking issue}
-
-### Root Cause
-{Analysis of why this is blocking}
-
-### Attempted Solutions
-- {What was tried and why it didn't work}
-
-### Required to Unblock
-- {What's needed: information, decision, resource, etc.}
-
-### Unblocking Conditions
-{Specific conditions that would allow work to resume}
 
-### Alternative Plans
-{Any workarounds or alternative approaches considered}
+Next step - check task status after unblocking:
+  - Claude Code / OpenCode: /check-task {task-id}
+  - Gemini CLI: /{{project}}:check-task {task-id}
+  - Codex CLI: $check-task {task-id}
 ```
 
 ## Completion Checklist