project-status-sync

用途

Project Status Sync 的核心目标是让 GitHub Project 的字段始终与实际工作状态保持一致。其核心理念是：项目字段就是仪表盘，必须保持准确。该技能贯穿整个工作流程使用，并由其他技能调用。

主要能力

该技能可以更新 GitHub Project 中的多种标准字段，包括：

Status（状态）：单选字段，可选值为 Backlog、Ready、In Progress、In Review、Done、Blocked，在工作状态变化时更新。
Verification（验证）：单选字段，可选值为 Not Verified、Failing、Partial、Passing，在验证运行时更新。
Criteria Met（已满足标准数）：数字字段，范围 0-N，在勾选验收标准时更新。
Criteria Total（标准总数）：数字字段，在议题创建或更新时更新。
Priority（优先级）：单选字段，可选值为 Critical、High、Medium、Low，在优先级变化时更新。
Type（类型）：单选字段，可选值为 Feature、Bug、Chore、Research、Spike，在议题创建时更新。
Last Verified（最后验证日期）：日期字段，ISO 日期格式，在验证运行时更新。
Verified By（验证者）：文本字段，值为 agent/human/ci，在验证运行时更新。

使用方式

环境要求

必须设置 GITHUB_PROJECT 环境变量，例如：

echo $GITHUB_PROJECT
# 示例：https://github.com/users/troykelly/projects/4

获取项目 ID

更新项目字段需要获取多种 ID：

# 从 URL 获取项目编号
# https://github.com/users/troykelly/projects/4 → PROJECT_NUMBER=4

# 获取项目 ID
gh project list --owner @me --format json | jq -r '.projects[] | select(.number == 4) | .id'

# 获取字段 ID
gh project field-list [PROJECT_NUMBER] --owner @me --format json

# 获取特定议题的条目 ID
gh project item-list [PROJECT_NUMBER] --owner @me --format json | \
  jq -r '.items[] | select(.content.number == [ISSUE_NUMBER]) | .id'

状态转换

有效的状态转换路径为：

Backlog ──► Ready ──► In Progress ──► In Review ──► Done
    │         │            │              │
    │         │            │              │
    └─────────┴────────────┴──────────────┴──► Blocked
                                               │
                                               ▼
                                        (any previous state)

转换触发条件：

从	到	触发条件
Backlog	Ready	依赖已清除，可以开始工作
Ready	In Progress	议题工作开始
In Progress	In Review	创建 PR
In Review	Done	PR 合并，验证通过
任意	Blocked	遇到阻塞
Blocked	之前的状态	阻塞已解决

更新字段

更新 Status 字段的示例：

# 首先获取 Status 的字段 ID
STATUS_FIELD_ID=$(gh project field-list [PROJECT_NUMBER] --owner @me --format json | \
  jq -r '.fields[] | select(.name == "Status") | .id')

# 获取目标状态的选项 ID
OPTION_ID=$(gh project field-list [PROJECT_NUMBER] --owner @me --format json | \
  jq -r '.fields[] | select(.name == "Status") | .options[] | select(.name == "In Progress") | .id')

# 获取议题的条目 ID
ITEM_ID=$(gh project item-list [PROJECT_NUMBER] --owner @me --format json | \
  jq -r '.items[] | select(.content.number == [ISSUE_NUMBER]) | .id')

# 更新字段
gh project item-edit --project-id [PROJECT_ID] --id $ITEM_ID \
  --field-id $STATUS_FIELD_ID --single-select-option-id $OPTION_ID

更新 Verification 状态、数字字段、日期字段和文本字段也采用类似模式，分别使用 --single-select-option-id、--number、--date 和 --text 参数。

批量更新

验证完成后，可以一次性更新多个字段：

PROJECT_ID="[PROJECT_ID]"
ITEM_ID="[ITEM_ID]"

# 更新验证状态
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
  --field-id $VERIFICATION_FIELD_ID --single-select-option-id $PASSING_OPTION_ID

# 更新已满足标准数
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
  --field-id $CRITERIA_MET_FIELD_ID --number 4

# 更新最后验证日期
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
  --field-id $LAST_VERIFIED_FIELD_ID --date "$(date -u +%Y-%m-%d)"

# 更新验证者
gh project item-edit --project-id $PROJECT_ID --id $ITEM_ID \
  --field-id $VERIFIED_BY_FIELD_ID --text "agent"

验证状态与状态的映射

验证状态	推荐状态
Not Verified	In Progress（仍在工作）
Failing	In Progress（需要修复）
Partial	In Progress（需要继续工作）
Passing	In Review（准备 PR 审查）

将议题添加到项目

创建新议题时，将其添加到项目：

# 将议题添加到项目
gh project item-add [PROJECT_NUMBER] --owner @me --url [ISSUE_URL]

# 然后设置初始字段值
# Status: Backlog 或 Ready
# Priority: 按指定值
# Type: 按指定值
# Criteria Total: 从议题中计数
# Verification: Not Verified

适用场景

该技能适用于需要将 GitHub Project 作为工作看板进行管理的团队或个人，尤其是在以下场景中：

议题生命周期管理中的状态转换。
验收标准验证后的验证字段更新。
议题前置条件设置时的初始字段配置。
议题分解时将子议题添加到项目。

该技能被以下技能调用：issue-lifecycle（状态转换）、acceptance-criteria-verification（验证字段更新）、issue-prerequisite（初始字段设置）、issue-decomposition（将子议题添加到项目）。

限制

必须设置 GITHUB_PROJECT 环境变量。
需要 GitHub CLI（gh）并具备正确的认证权限范围。
字段必须已存在于项目中，否则需要先创建。
议题必须先添加到项目才能更新其字段。
常见问题包括：找不到项目（检查 GITHUB_PROJECT 环境变量）、字段未找到（验证字段是否存在）、权限被拒绝（检查 gh auth 权限范围）、条目不在项目中（先用 item-add 添加议题）。