cto-heartbeat

cto-heartbeat

面向代码仓库的流程优化运行循环。优先解除进行中工作（WIP）的阻塞，再对未标记的问题进行分类，每次运行只派发一项任务。

此技能实现了 cto 角色技能中定义的运行原则。

Invocation

/cto-heartbeat org/repo [goal-context]

示例：

/cto-heartbeat fellowship-dev/booster-pack
/cto-heartbeat fellowship-dev/booster-pack "focus: Vercel deployment pipeline"

Token

export GH_TOKEN=$(grep "GH_PAT_FELLOWSHIP" $HOME/projects/fellowship-dev/claude-buddy/.env | cut -d= -f2)
# Or for specific teams, use the team's token_var from crew.yml

---

步骤 0：初始化标签（幂等）

如果目标代码仓库中不存在相应标签，则创建这些标签。每次都运行——gh label create 具有幂等性（如果标签已存在，会静默报错）。

export REPO=$1
export GOAL_CONTEXT="${@:2}"
export GH_TOKEN=$(grep "GH_PAT_FELLOWSHIP" $HOME/projects/fellowship-dev/claude-buddy/.env | cut -d= -f2)

# Priority labels
gh label create "P0" --repo $REPO --color "b60205" --description "Production broken, revenue impact, security — fix now" 2>/dev/null || true
gh label create "P1" --repo $REPO --color "d93f0b" --description "Important but not urgent — fix this week" 2>/dev/null || true
gh label create "P2" --repo $REPO --color "fbca04" --description "Nice to have — fix when convenient" 2>/dev/null || true

# Status labels
gh label create "dispatched" --repo $REPO --color "5319e7" --description "Work sent to a crew member" 2>/dev/null || true
gh label create "blocked" --repo $REPO --color "c5def5" --description "Waiting on external input or another issue" 2>/dev/null || true

步骤 1：扫描进行中工作（先解除阻塞，再开始新工作）

先检查正在进行的工作的当前状态，再进行其他操作。原则是：停止开始，开始完成。

# Open PRs across the repo
gh pr list --repo $REPO --state open --json number,title,labels,createdAt,url

# Issues with dispatched label (work in progress)
gh issue list --repo $REPO --label "dispatched" --state open --json number,title,labels,assignees,url

# Issues with blocked label
gh issue list --repo $REPO --label "blocked" --state open --json number,title,labels,url

# Check if any dispatched issues have associated merged PRs (work completed but label not cleaned up)
# For each dispatched issue, check if there is a recently merged PR that references it

操作：

• 已派发的问题是否有已合并的 PR？ → 关闭问题或移除 dispatched 标签，并确认已完成
• 已派发的问题是否有一个打开超过 2 天的 PR？ → 标记为阻塞项并调查
• 已派发的问题超过 3 天仍然没有 PR？ → 标记为过期派发
• 被阻塞的问题 → 检查阻塞因素是否已解决；如果已解决，移除 blocked 标签并重新确定优先级
• PR 卡在审核流程中，没有进展 → 标记出来

输出：列出进行中的事项及其状态。列出已采取的操作（移除标签、关闭问题）。

步骤 2：聚焦活跃 Epic

确定当前正在进行的 Epic。“活跃 Epic”是指至少有一个打开的问题带有 dispatched 标签的 Epic。

# Find which epic labels have dispatched issues
gh issue list --repo $REPO --label "dispatched" --state open --json labels --jq ".[].labels[].name" | sort -u

筛除元数据标签（P0、P1、P2、dispatched、blocked、bug、enhancement、documentation 等）——剩下的就是 Epic 标签。

规则：

• 如果恰好有一个 Epic 存在已派发的工作 → 该 Epic 为活跃 Epic。后续所有步骤都聚焦于此。
• 如果多个 Epic 都存在已派发的工作 → 已派发问题数量最多的 Epic 为活跃 Epic。将这一分散情况标记为隐患。
• 如果没有 Epic 存在已派发的工作（WIP=0）→ 没有活跃 Epic。步骤 4 将从所有 Epic 中选择优先级最高的问题。

输出：活跃 Epic 名称（或“无——WIP 已清空”）。

步骤 3：为新问题分类（最多 5 个）

查找缺少优先级标签的问题并为其分类。

# All open issues
gh issue list --repo $REPO --state open --json number,title,labels,body,createdAt --limit 50

# Filter: issues without P0, P1, or P2 labels (done in code/logic, not pure CLI)

对于每个未标记的问题（最多 5 个）：

1. 阅读问题标题和正文
2. 分配优先级标签：P0、P1 或 P2
3. 如果问题符合现有 Epic，则分配 Epic 标签；如果问题代表新的工作流，则创建新的 Epic 标签
4. 应用标签：

gh issue edit $ISSUE_NUM --repo $REPO --add-label "P1,epic-name"

跳过已有优先级标签（P0/P1/P2）的问题。heartbeat 不会重新分类。

输出：列出已分类问题及其分配优先级和 Epic 的表格。

步骤 4：派发一项任务

恰好选择一个问题进行派发。派发是指：添加 dispatched 标签，让负责人知道应为其分配任务。

优先顺序：

1. 活跃 Epic，按优先级从高到低：在活跃 Epic 中，P0 > P1 > P2
2. 如果没有活跃 Epic：从所有 Epic 中选择优先级最高的问题
3. 如果没有可派发的问题：报告“待办事项已清空”或“全部已派发”

# Find undispatched issues in the active epic, sorted by priority
gh issue list --repo $REPO --label "$ACTIVE_EPIC" --state open --json number,title,labels --limit 20
# Filter out issues that already have "dispatched" label
# Pick the highest priority one

# Add dispatched label
gh issue edit $ISSUE_NUM --repo $REPO --add-label "dispatched"

构建列车建议

如果同一个代码仓库中有 2 个或更多未派发的问题（筛除 dispatched 和 blocked 后），可以考虑派发 /build-train org/repo --issues N,M,...，而不是单个问题。这样可以将工作打包到同一个构建分支中，并且只运行一次审核流程，而不是为每个 PR 各运行一次。自行判断——当问题彼此独立且可并行处理时，使用构建列车是合理的。对于紧密耦合、需要按顺序实现的问题，不要使用。

规则：

• WIP > 3 时绝不派发——进行中的工作过多。应专注于解除阻塞。
• 每次 heartbeat 只派发一项——不要批量派发（使用构建列车时除外，因为这算作一次派发）。

输出：问题编号、标题、优先级、Epic——或未派发的原因。如果建议使用构建列车，请列出打包的问题。

步骤 5：报告

REPORT_DIR="$(git rev-parse --show-toplevel)/reports"
REPORT_PATH="$REPORT_DIR/$(date +%Y-%m-%d)-cto-heartbeat-$(echo $REPO | tr "/" "-").md"

报告结构：

# CTO Heartbeat: [repo name]

**Date:** YYYY-MM-DD HH:MM
**Repo:** $REPO
**Active epic:** [epic name or "none"]
**Goal context:** $GOAL_CONTEXT (or "N/A")

## WIP Status
| Issue | Title | Status | Epic | Priority |
|-------|-------|--------|------|----------|
| #N | ... | dispatched / blocked / stale | epic-name | P1 |

## Actions Taken
- Closed #N (resolved by PR #M)
- Removed dispatched from #N (stale >3 days)
- Unblocked #N (blocker resolved)

## Triage
| Issue | Title | Priority | Epic |
|-------|-------|----------|------|
| #N | ... | P1 | epic-name |

## Dispatched
- **#N — [title]** (P1, epic: [name]) — dispatched for crew execution

## Blockers
- [blocker description — what is stuck and why]

## Recommendations
1. [highest priority action]
2. [second priority]

将报告发布到 Quest：

QUEST_TOKEN=$(grep "^QUEST_TOKEN=" $HOME/projects/fellowship-dev/claude-buddy/.env | cut -d= -f2)
curl -s -X POST "http://127.0.0.1:4242/api/event" \
  -H "Authorization: Bearer $QUEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "
import json
content = open('$REPORT_PATH').read()
print(json.dumps({
  'source': 'commander',
  'type': 'commander.report',
  'title': 'CTO Heartbeat: $REPO',
  'meta': {'content': content, 'report_type': 'cto-heartbeat'}
}))
")" 2>/dev/null || true

---

评审结论参考

结论	表情符号	标签	合并？
LGTM	✅	approved	否（心跳机制会分派问题，而非 PR）
REWORK	🔄	needs-work	否
BLOCKED	⏸️	needs-work	否
NEW_ISSUE	📋	—	创建单独的问题
STALE	⏰	needs-work	否

---

备注

• 心跳机制是工作流优化器，而不是扫描器。 它会先解除 WIP 阻塞（停止启动，开始收尾），为未标记的问题进行分诊并添加 P0/P1/P2 和 epic 标签，然后每次运行只分派一项任务。每次只分派一项任务能让团队保持专注，并防止 WIP 蔓延。
• 心跳机制负责维护待办事项的整洁。 关闭已由合并 PR 解决的问题，标记重复项，并保持待办事项整洁。负责人负责决定是否分派新工作。
• 如果 WIP > 3，绝不分派任务——当前进行中的工作过多。此时心跳机制的职责是解除阻塞，而不是增加更多任务。
• 有关 PR 评审功能，请参阅 /cto-review。有关 CTO 角色原则，请参阅 cto 角色技能。