project-tracking

触发条件：/track-init、/plan-epic <description>、/plan-migrate、/track <description>、/backlog、"qué tenemos pendiente?"、"what's pending?"、"acordate que hay que..."、"remember to..."、"vamos a planear"、"armemos la épica"、实施过程中发现 Bug、由 sdd-tasks 生成的 SDD 任务。

---

层级模型 — Epic / Story / Task / Bug

此技能采用 GitHub Issue Types（原生）和子议题（原生）构成的三级层级 （另有作为独立类型的 Bug）。 标签会保留以确保向后兼容，但 Issue Types 具有权威性。

层级	GitHub Issue Type	生命周期	所属父级	是否有子议题
Epic	Epic	数周	无	Stories
Story	Feature	数天	Epic	Tasks
Task	Task	数小时	Story（或紧急修复时归属 Epic）	无
Bug	Bug	数小时至数天	Epic（稳定性）或受其影响的 Story	无

经验法则：

• 一个 Task = 一个 Claude 会话。如果范围太大，就说明它其实是伪装成 Task 的 Story。拆分它。
• 只有当验收标准本身已可作为任务清单（确实很小）时，Story 才可以没有子议题。
• 没有子议题的 Epic 是个坏兆头——它很可能其实是 Story。
• Bug 可以独立存在（没有父级），前提是它不属于某个计划中的 Epic。

Issue Types 与标签

此技能会同时写入 Issue Type（当组织启用了 Issue Types 时） 和对应的旧版标签（type/epic、type/feature、type/task、 type/bug）。这样，在逐步采用新层级的同时，旧视图、筛选器和现有的 /track 流程 仍可继续使用。

Issue Type 可用性的检测每个会话只执行一次，通过 COMMANDS.md 中的 Issue-Type detection 区块完成。如果响应为空或不支持该字段，则回退到仅使用标签的模式，并在每个会话中向用户警告一次：

"此组织未启用 Issue Types。将回退到标签——type/epic、 type/feature、type/task、type/bug。要启用原生类型，请前往 组织设置 → Issue Types。"

所有字面量 gh / GraphQL 命令区块都位于 COMMANDS.md， 以下内容按步骤 ID（例如 [track-init §1]）引用这些区块。此文件包含决策 逻辑；COMMANDS.md 包含确切的调用命令。

流程

预检：检测仓库和配置

在执行任何流程前，解析 owner/repo（在 COMMANDS.md 中运行 Pre-flight — detect repo）。 然后在 engram 中搜索项目配置：

• 使用查询 tracking/{repo-name}/config 调用 mem_search
• 如果找到，调用 mem_get_observation 获取项目编号和字段 ID
• 如果未找到且该流程需要项目操作 → 提醒用户先运行 /track-init

---

流程 1：初始化 — /track-init

每个仓库运行一次。具有幂等性——可安全重复运行。

步骤 0 — 检测令牌能力

运行 [track-init §0]。如果失败，根据表格判定原因 — 切勿假设所有失败都是由令牌导致。不同原因对应不同操作： gh-not-authenticated（§0-auth）、细粒度 PAT（§0-manual）、缺少 project 范围（gh auth refresh -s project）、暂时性的 GitHub/网络错误（停止操作并稍后 重试，切勿动令牌），或者——当 REST 正常但 Projects/GraphQL 返回 FORBIDDEN 时—— 令牌环境变量配置错误（§0-token-env：令牌类型错误，或令牌正确但使用了 gh 从不读取的名称）。

最常见的情况（你的情况）：细粒度 PAT 不支持个人账户上的 Projects V2 （仅支持组织）。[track-init §0-manual] 提供两种解决办法：修复令牌 （使用 Classic PAT + gh auth，推荐——可解除对所有仓库自动创建的限制） 或手动创建看板（快速备用方案）。建议修复令牌。如果用户修复了令牌， 重新运行步骤 0，然后前往步骤 1。如果用户手动创建了看板，记录项目编号并跳至步骤 2（标签）。

步骤 1 — 创建 GitHub 项目看板（自动路径）

仅当步骤 0 确认支持 Projects V2 时：运行 [track-init §1]（创建项目以及 Status / Priority / Type 单选字段）。

步骤 2 — 创建标签

运行 [track-init §2]（类型 / 优先级 / 状态标签）。此操作具有幂等性——如果标签已存在，gh label create 会失败；捕获错误后继续。

步骤 3 — 获取字段和选项 ID

无论看板是自动创建的（步骤 1）还是手动创建的（步骤 0），都要运行 [track-init §3]，获取 status_field_id、priority_field_id、type_field_id 以及每个值对应的选项 ID。gh project item-edit 需要这些 ID。

步骤 4 — 将配置保存到 engram

调用 mem_save，并提供：

• title： "Bootstrap project-tracking config for {repo-name}"
• type： config
• topic_key： tracking/{repo-name}/config
• content： project_number、owner、repo、所有字段 ID 和选项 ID，保存为结构化映射

向用户确认："看板已关联。{owner}/{repo} 的项目 #{project_number}。配置已保存到 engram。"

---

流程 2：规划 Epic — /plan-epic <description>

用于端到端规划大型功能或计划：一个 Epic、其 Story，以及每个 Story 的 Task。在用户明确确认之前，不会向 GitHub 写入任何内容。

如果此仓库没有 engram 配置，先运行 /track-init。

步骤 1 — 读取模板

从此技能目录加载正文模板：

• templates/epic.md
• templates/story.md
• templates/task.md

这些模板是约定——此流程中创建的每个 issue 都必须遵循它们。

步骤 2 — 检测 Issue Type 支持情况

运行 Issue-Type detection（COMMANDS.md）。在当前会话中缓存检测结果。 选择：原生 Issue Types 模式或标签回退模式。

步骤 3 — 在聊天中以 Markdown 提出层级结构

生成一条聊天消息，结构如下：

# Epic: {Title}

Type: Epic | Priority: {P0..P3}
[Epic body following templates/epic.md]

---

## Story 1: {Title}

Type: Feature | Priority: {P0..P3} | Parent: Epic above
[Story body following templates/story.md]

### Task 1.1: {Title}
Type: Task | Parent: Story 1
[Task body following templates/task.md]

### Task 1.2: {Title}
...

---

## Story 2: {Title}
...

在一条消息中展示完整提案。此时不要调用任何 GitHub API。

步骤 4 — 等待确认

在提案消息末尾准确添加以下提示：

Review the plan above. Reply:
  - "dale" / "go" / "create" → I create all N issues + sub-issue links
  - "edit <X>" / "no <X>"     → tell me what to change, I revise the plan
  - "abort"                   → drop the plan, nothing is created

如果用户的回复不是确认关键词，则将其视为修改指示，并生成修订后的提案。再次提示。只有当用户明确回复此列表中的确认关键词时，才能创建 issue。

步骤 5 — 按顺序创建

按以下顺序创建 issue：Epic → Story 1 → Task 1.1 → Task 1.2 → Story 2 → ...

对于每个 issue：

1. 调用 mcp__github__create_issue，并提供标题、正文、标签和 Issue Type（如受支持）。
2. 获取返回的 issue 编号。
3. 如果提案中该 issue 有父级，则使用 [sub-issue link] 将其关联为子 issue。
4. 将 issue 添加到项目看板（[track §3]）。
5. 设置项目字段（[track §4]）：Status=Backlog、Priority=提案中的值、Type=提案中的值。

步骤 6 — 汇报结果

打印一个摘要块：

## Created

Epic #N: {title}
├── Story #N+1: {title}
│   ├── Task #N+2: {title}
│   ├── Task #N+3: {title}
│   └── Task #N+4: {title}
└── Story #N+5: {title}
    ├── Task #N+6: {title}
    └── Task #N+7: {title}

Total: 1 epic, 2 stories, 5 tasks. All added to project board as Backlog.

保存一条 engram 观察记录：

• 使用 mem_save，type: architecture、topic_key: tracking/{repo}/epic-{N}， content：Epic 标题、子 Story 和 Task 编号、计划来源 （用户请求、SDD 规范引用等）。

---

流程 3：规划迁移 — /plan-migrate

用于现有仓库的看板仍采用扁平结构（issue 之间没有父子关系），需要重新整理为 Epic/Story/Task 层级结构的情况。

步骤 1 — 获取当前状态

运行 [migrate-fetch]。根据以下启发式规则，按可能的级别对 issue 分组：

信号	可能的级别
标题以 epic: 开头，或带有标签 type/epic，或 Type=Epic	Epic
标题以 feat: 开头，或带有标签 type/feature，或 Type=Feature	Story
标题以 bug: 开头，或带有标签 type/bug，或 Type=Bug	Bug
标题以 chore:/task: 开头，或没有前缀	Task

步骤 2 — 在聊天中提出层级结构

生成一条消息：

# Migration proposal — {N} open issues

## Epics
- #10 epic: Payments & Monetization
  Will own:
    - #28 feat: Stripe integration for guide bookings
    - {other feats that thematically belong}

- #14 epic: Push Notifications & Engagement
  Will own:
    - #30 feat: push notifications (Expo / Firebase)

## Bugs (orphan — no epic owner)
- #18, #19, #20, ...
  Recommended: create epic "Stability & Bugfixes" to own all of these.
  OR leave as standalone (no parent). Pick one.

## Unclassified
- #X, #Y — could not infer parent confidently. Please tell me.

在末尾添加与 /plan-epic 步骤 4 相同的确认提示。

步骤 3 — 确认后应用

对于每个父级 → 子级配对，运行 [sub-issue link]。对于需要追溯设置 Issue Type 的问题，运行 [set-issue-type]。如果不支持 Issue Types，请改为确保存在旧版 type/* 标签。

步骤 4 — 报告

输出与 /plan-epic 步骤 6 相同的树形摘要。保存 engram 观察记录，type: architecture、topic_key: tracking/{repo}/migration-{date}。

---

流程 4：跟踪 — 创建问题并添加到看板

触发模式（混合）

情况	行为
/track <description>	立即创建问题，无需确认
/track 包含多个条目或待办事项会话	创建全部问题，显示列表，并在执行前请求确认
sdd-tasks 生成任务	建议为每项任务创建一个问题，并请求确认
用户提及未来工作（“habría que...”、“falta...”、“después hay que...”）	在内部收集。会话结束时提议：“检测到 N 个可跟踪条目：[列表]。要将其创建为问题吗？”
“acordate que hay que...” / “remember to...”	立即提议创建问题
实现期间发现 Bug	立即提议创建带有 type/bug 标签的问题

问题创建步骤

步骤 1 — 去重

运行 [track §1]。如果存在类似问题，则显示该问题并询问：“问题 #N 已存在：‘{title}’。仍要新建一个吗？”

步骤 2 — 通过 MCP 创建问题

运行 [track §2] — 使用 owner、repo、符合规范的 title（type: description）、正文模板以及适用的 labels 调用 mcp__github__create_issue。正文模板位于 [track §2]。

步骤 3 — 添加到项目看板

运行 [track §3]（获取 item_id）。

步骤 4 — 设置项目字段

运行 [track §4] — 从 engram 配置（tracking/{repo-name}/config）加载字段/选项 ID，然后设置 Status / Priority / Type。

步骤 5 — 向用户确认

Created #14: feat: add OAuth with Google — added to board as Backlog/P1-High [Feature]

---

流程 5：查询 — /backlog 和状态问题

默认：完整看板摘要

运行 [backlog §default]，然后按 Status 字段值对条目分组。输出：

## Project Board: {project-name}

### In Progress (2)
- #14 feat: OAuth with Google [P1-High]
- #12 fix: Email validation [P0-Critical]

### Review (1)
- #13 feat: User profile page [P1-High]

### Backlog (3)
- #15 feat: Dashboard redesign [P2-Medium]
- #16 chore: Update dependencies [P3-Low]
- #17 feat: Export to PDF [P2-Medium]

### Done (last 5)
- #11 fix: Login redirect loop [P1-High]

按以下顺序显示状态：In Progress → Review → Todo → Backlog → Done（仅显示最后 5 项，以免产生过多信息）。

筛选查询

命令	应用的筛选条件
/backlog bugs	仅包含 Type = Bug 的条目
/backlog high	仅包含 Priority = P0-Critical 或 P1-High 的条目
/backlog in-progress	仅包含 Status = In Progress 的条目
/backlog todo	仅包含 Status = Todo 的条目
/backlog review	仅包含 Status = Review 的条目

---

状态转换

手动触发：/track move #14 in-progress、/track move #14 review、 /track move #14 done。底层命令：[status-move]。

自动集成点：

• Claude 开始处理问题 → 移至“In Progress”
• Claude 为问题创建 PR → 移至“Review”（与 branch-pr 技能集成）
• PR 合并 / 问题关闭 → 移至“Done”

---

规则

• GitHub Issues + Projects 是待办事项的唯一事实来源：包括待办列表、任务、故事和 Bug
• Engram 仍然是决策、发现和技术背景的唯一事实来源：两者互为补充，而非相互竞争
• 绝不创建重复的 Issue：创建前始终运行 gh issue list --search
• Issue 标题遵循约定格式：type: description（例如：feat: add OAuth、fix: email validation）
• 标签使用小写，并以 / 分隔：type/feature、priority/high、status/backlog
• 每个 Issue 在项目看板上都必须至少设置 Type 字段
• /track-init 是幂等的：运行两次不得创建重复的标签或项目；妥善处理 gh label create 的错误
• 引导初始化后，必须将项目配置（ID）保存到 engram，使用 topic_key: tracking/{repo-name}/config
• 调用任何 gh project item-edit 之前，从 engram 加载字段 ID；如果未找到，则通过 gh project field-list 重新推导
• 批量创建需要确认：一次提议创建多个 Issue 时，先展示完整列表，并等待用户批准，然后再创建
• 建议类型和优先级，不要自行假定：从对话中自动检测可跟踪事项时，推断合理的默认值，但创建前先展示给用户
• 创建 Issue 时优先使用 MCP（mcp__github__create_issue），所有项目看板操作使用 gh CLI
• 如果尚未运行 /track-init（没有 engram 配置，也没有关联的项目），则应检测到此情况，并在进行任何看板操作前建议运行该命令
• 细粒度 PAT 不支持个人账户上的 Projects V2——只有 Classic PAT 或组织级 Token 才可用。检测到此情况时，提供两种解决方案（§0-manual）：建议修复 Token（Classic PAT + gh auth，可用于所有仓库），而不是回退到手动创建看板。绝不要把手动创建当作唯一选项
• gh 只会从 GH_TOKEN > GITHUB_TOKEN 读取 Token（按此顺序），且环境变量中的 Token 会覆盖 gh auth login。正确的 Token 如果使用其他名称（例如 GITHUB_CLASSIC_TOKEN），会被静默忽略。如果 REST 可用，但 Projects/GraphQL 返回 FORBIDDEN，则应怀疑环境变量配置错误（§0-token-env）：将 Classic PAT 放入 GH_TOKEN，并使用单行 GraphQL viewer.projectsV2 查询验证。记录此规则——Token 类型、变量名和验证方式；绝不记录密钥值
• 自动和手动创建看板的路径都在 Step 3（捕获 ID）汇合——无论看板如何创建，之后的工作流都相同
• /plan-epic 必须先确认：先在聊天中以 Markdown 提议完整层级（Epic + Stories + Tasks）；在用户回复明确的确认关键词（dale、go、create）之前，不得调用 create_issue。其他任何回复均视为编辑说明，而非批准
• 如果 Issue Types 可用，则以其为准；同时写入旧版 type/* 标签以保持向后兼容。通过 GraphQL issueTypes 查询检测支持情况，在当前会话中缓存结果；如果不支持类型，则回退到仅使用标签的模式，并仅警告一次
• 子 Issue 链接使用 addSubIssue GraphQL mutation——绝不要仅通过在正文中写文本来模拟层级关系（仅写 "parent: #N" 不会创建链接）
• 一个 Task = 一个 Claude 会话。如果一个 Task 无法在单个会话中完成，那它就是伪装成 Task 的 Story——创建前先建议拆分
• /plan-migrate 未经确认绝不修改 Issue——遵循与 /plan-epic 相同的先确认约定。未分类的 Issue 应标记出来供用户处理，不要自动分配
• Bug Issue 可以独立存在（没有上级 Epic），也可以归属于一个“Stability & Bugfixes”Epic。每个仓库选择一种方式并保持一致——将该选择写入 engram 配置的 tracking/{repo}/config 下
• 正文模板存放于 skills/project-tracking/templates/（epic.md、story.md、task.md、bug.md），它们是 Issue 正文结构的唯一事实来源。不要自行编造其他格式