project-tracking

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Triggers:

/track-init

/track <description>

/backlog

, "qué tenemos pendiente?", "what's pending?", "acordate que hay que...", "remember to...", bug found during implementation, SDD tasks generated by

sdd-tasks

触发方式：

/track-init

、

/track <description>

、

/backlog

、"qué tenemos pendiente?"、"what's pending?"、"acordate que hay que..."、"remember to..."、开发过程中发现Bug、由

sdd-tasks

生成的SDD任务。

Process

流程

Pre-flight: Detect Repo and Config

前置检查：检测仓库与配置

Before any flow, resolve owner/repo and load the board config:

bash

undefined

在执行任何流程前，先确定仓库所有者/仓库名称并加载看板配置：

bash

undefined

Detect owner/repo from git remote

从git远程仓库检测所有者/仓库名称

git remote get-url origin

Parse: https://github.com/owner/repo.git → owner=owner, repo=repo

解析：https://github.com/owner/repo.git → owner=owner, repo=repo

Parse: git@github.com:owner/repo.git → same

解析：git@github.com:owner/repo.git → 结果相同


Then search engram for the project config:
- `mem_search` with query `tracking/{repo-name}/config`
- If found, call `mem_get_observation` to get project number and field IDs
- If NOT found and the flow requires project operations → warn user to run `/track-init` first

---


然后在engram中搜索项目配置：
- 使用查询语句`tracking/{repo-name}/config`执行`mem_search`
- 如果找到，调用`mem_get_observation`获取项目编号和字段ID
- 如果未找到且当前流程需要执行项目操作 → 提醒用户先运行`/track-init`

---

Flow 1: Bootstrap —

/track-init

流程1：初始化 —

/track-init

Run once per repo. Idempotent — safe to run again.

每个仓库只需运行一次，支持幂等操作——重复运行也安全。

Step 0 — Detect token capabilities

步骤0 — 检测令牌权限

Before attempting to create the project board, check if the token supports Projects V2:

bash

gh project list --owner owner --limit 1 2>&1

If this fails with a permission/scope error, the token likely cannot manage Projects V2.

Known limitation: Fine-grained PATs do NOT support Projects V2 on personal accounts (only organizations). If the repo owner is a personal account and the token is fine-grained, the board MUST be created manually.

When automatic creation is not possible, guide the user:

Your token does not support GitHub Projects V2 for personal accounts.
Please create the board manually (takes 30 seconds):

1. Go to https://github.com/users/{owner}/projects → "New Project"
2. Choose "Board" layout
3. Name it "{repo-name} Board"
4. Add these custom fields (Single Select):
   - Status: Backlog, Todo, In Progress, Review, Done
   - Priority: P0-Critical, P1-High, P2-Medium, P3-Low
   - Type: Epic, Feature, Bug, Chore
5. Tell me the project number (visible in the URL: /projects/N)

I'll handle the rest — labels, capturing IDs, and saving the config.

After the user provides the project number, skip to Step 2 (labels) and continue normally.

在尝试创建项目看板前，检查令牌是否支持Projects V2：

bash

gh project list --owner owner --limit 1 2>&1

如果因权限/范围错误导致命令失败，说明该令牌可能无法管理Projects V2。

已知限制：细粒度PAT（个人访问令牌）不支持个人账户的Projects V2（仅支持组织账户）。如果仓库所有者是个人账户且使用的是细粒度令牌，必须手动创建看板。

当无法自动创建看板时，引导用户：

你的令牌不支持个人账户的GitHub Projects V2。
请手动创建看板（耗时约30秒）：

1. 访问https://github.com/users/{owner}/projects → 点击「New Project」
2. 选择「Board」布局
3. 命名为「{repo-name} Board」
4. 添加以下自定义字段（单选类型）：
   - Status：Backlog、Todo、In Progress、Review、Done
   - Priority：P0-Critical、P1-High、P2-Medium、P3-Low
   - Type：Epic、Feature、Bug、Chore
5. 告诉我项目编号（可在URL中查看：/projects/N）

我会处理后续操作——标签创建、ID捕获和配置保存。

用户提供项目编号后，跳至步骤2（标签创建）并正常继续流程。

Step 1 — Create GitHub Project board (automatic path)

步骤1 — 自动创建GitHub Project看板

Only if Step 0 confirms the token supports Projects V2:

bash

undefined

仅当步骤0确认令牌支持Projects V2时执行：

bash

undefined

Create project linked to the repo

创建与仓库关联的项目

gh project create --owner owner --title "{repo-name} Board" --format json

Capture: .number → project_number

捕获：.number → project_number


Then add custom fields:

```bash


然后添加自定义字段：

```bash

Status field (single select)

Status字段（单选类型）

gh project field-create {project_number} --owner owner
--name "Status" --data-type "SINGLE_SELECT"
--single-select-options "Backlog,Todo,In Progress,Review,Done"

Priority field (single select)

Priority字段（单选类型）

gh project field-create {project_number} --owner owner
--name "Priority" --data-type "SINGLE_SELECT"
--single-select-options "P0-Critical,P1-High,P2-Medium,P3-Low"

Type field (single select)

Type字段（单选类型）

gh project field-create {project_number} --owner owner
--name "Type" --data-type "SINGLE_SELECT"
--single-select-options "Epic,Feature,Bug,Chore"

undefined

gh project field-create {project_number} --owner owner
--name "Type" --data-type "SINGLE_SELECT"
--single-select-options "Epic,Feature,Bug,Chore"

undefined

Step 2 — Create labels

步骤2 — 创建标签

bash

undefined

bash

undefined

Type labels

类型标签

gh label create "type/epic" --color "6e40c9" --description "Epic" --repo owner/repo gh label create "type/feature" --color "0075ca" --description "Feature" --repo owner/repo gh label create "type/bug" --color "d73a4a" --description "Bug" --repo owner/repo gh label create "type/chore" --color "e4e669" --description "Chore" --repo owner/repo

Priority labels

优先级标签

gh label create "priority/high" --color "b60205" --description "P1 High" --repo owner/repo gh label create "priority/medium" --color "fbca04" --description "P2 Medium" --repo owner/repo gh label create "priority/low" --color "0e8a16" --description "P3 Low" --repo owner/repo

Status labels

状态标签

gh label create "status/backlog" --color "ededed" --description "In backlog" --repo owner/repo gh label create "status/in-progress" --color "0052cc" --description "In progress" --repo owner/repo gh label create "status/review" --color "e99695" --description "In review" --repo owner/repo gh label create "status/done" --color "cfd3d7" --description "Done" --repo owner/repo


If a label already exists, `gh label create` will fail — catch the error and continue (idempotent behavior).


如果标签已存在，`gh label create`会执行失败——捕获该错误并继续流程（保持幂等行为）。

Step 3 — Capture field and option IDs

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

Whether the board was created automatically (Step 1) or manually (Step 0), capture the field IDs:

bash

gh project field-list {project_number} --owner owner --format json

Parse the JSON to extract:

```
status_field_id
```
, and option IDs for each status value
```
priority_field_id
```
, and option IDs for each priority value
```
type_field_id
```
, and option IDs for each type value

These IDs are required by

gh project item-edit

无论看板是自动创建（步骤1）还是手动创建（步骤0），都需要捕获字段ID：

bash

gh project field-list {project_number} --owner owner --format json

解析JSON以提取：

```
status_field_id
```
以及每个状态值对应的选项ID
```
priority_field_id
```
以及每个优先级值对应的选项ID
```
type_field_id
```
以及每个类型值对应的选项ID

这些ID是

gh project item-edit

命令必需的参数。

Step 4 — Save config to engram

步骤4 — 将配置保存至engram

Call

mem_save

with:

title: "Bootstrap project-tracking config for {repo-name}"
type: config
topic_key:
```
tracking/{repo-name}/config
```
content: project_number, owner, repo, all field IDs and option IDs as a structured map

Confirm to user: "Board linked. Project #{project_number} for {owner}/{repo}. Config saved to 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组成的结构化映射

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

Flow 2: Track — Create Issues and Add to Board

流程2：跟踪 — 创建Issue并添加至看板

Trigger model (hybrid)

触发模式（混合式）

Situation	Behavior
`/track <description>`	Create issue immediately, no confirmation
`/track` with multiple items or backlog session	Create all, show list, ask confirmation before executing
`sdd-tasks` generates tasks	Propose creating one issue per task, ask confirmation
User mentions future work ("habría que...", "falta...", "después hay que...")	Collect internally. At session end propose: "Detected N trackable items: [list]. Create as issues?"
"acordate que hay que..." / "remember to..."	Propose creating an issue immediately
Bug found during implementation	Propose creating issue with `type/bug` label immediately

场景	行为
`/track <description>`	立即创建Issue，无需确认
带有多个事项的 `/track` 或待办事项会话	创建所有事项，展示列表，执行前询问用户确认
`sdd-tasks` 生成任务	提议为每个任务创建一个Issue，询问用户确认
用户提及未来工作（"habría que..."、"falta..."、"después hay que..."）	内部收集这些事项。会话结束时提议："检测到N个可跟踪事项：[列表]。是否创建为Issue？"
"acordate que hay que..." / "remember to..."	提议立即创建Issue
开发过程中发现Bug	提议立即创建带有 `type/bug` 标签的Issue

Issue creation steps

Issue创建步骤

Step 1 — Deduplicate

bash

gh issue list --repo owner/repo --search "{title keywords}" --json number,title

If a similar issue exists, show it and ask: "Issue #N already exists: '{title}'. Create a new one anyway?"

Step 2 — Create issue via MCP

Use

mcp__github__create_issue

with:

```
owner
```
,
```
repo
```

title

: conventional format —

type: description

(e.g.,

feat: add OAuth

fix: email validation

)

```
body
```
: use the issue body template below

labels

: array of applicable labels (e.g.,

["type/feature", "priority/medium", "status/backlog"]

)

Issue body template:

markdown

undefined

步骤1 — 去重

bash

gh issue list --repo owner/repo --search "{title keywords}" --json number,title

如果存在相似Issue，展示该Issue并询问："Issue #N已存在：'{title}'。是否仍要创建新Issue？"

步骤2 — 通过MCP创建Issue

使用

mcp__github__create_issue

并传入以下参数：

```
owner
```
、
```
repo
```

title

：遵循规范格式 —

type: description

（例如：

feat: add OAuth

、

fix: email validation

）

```
body
```
：使用下方的Issue正文模板

labels

：适用标签数组（例如：

["type/feature", "priority/medium", "status/backlog"]

）

Issue正文模板：

markdown

undefined

Description

描述

{description}

Context

上下文

Source: {how this was identified — user request, SDD task, conversation, bug found}
Session: {date}
Related: {any related issues or PRs, if known}

来源：{该事项的识别方式——用户需求、SDD任务、对话内容、发现的Bug}
会话日期：{date}
关联事项：{已知的相关Issue或PR}

Acceptance Criteria

验收标准

{criterion 1}
{criterion 2}


**Step 3 — Add to project board**

```bash
gh project item-add {project_number} --owner owner \
  --url https://github.com/owner/repo/issues/{issue_number} \
  --format json

{标准1}
{标准2}


**步骤3 — 添加至项目看板**

```bash
gh project item-add {project_number} --owner owner \
  --url https://github.com/owner/repo/issues/{issue_number} \
  --format json

Capture: .id → item_id

捕获：.id → item_id


**Step 4 — Set project fields**

Load field IDs and option IDs from engram config (`tracking/{repo-name}/config`). If not in cache, run:

```bash
gh project field-list {project_number} --owner owner --format json

Then set each field:

bash

undefined


**步骤4 — 设置项目字段**

从engram配置（`tracking/{repo-name}/config`）加载字段ID和选项ID。如果未缓存，执行：

```bash
gh project field-list {project_number} --owner owner --format json

然后设置每个字段：

bash

undefined

Set Status

设置Status

gh project item-edit --project-id {project_number} --owner owner
--id {item_id}
--field-id {status_field_id}
--single-select-option-id {status_option_id}

Set Priority

设置Priority

gh project item-edit --project-id {project_number} --owner owner
--id {item_id}
--field-id {priority_field_id}
--single-select-option-id {priority_option_id}

Set Type

设置Type

gh project item-edit --project-id {project_number} --owner owner
--id {item_id}
--field-id {type_field_id}
--single-select-option-id {type_option_id}


**Step 5 — Confirm to user**

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

---

gh project item-edit --project-id {project_number} --owner owner
--id {item_id}
--field-id {type_field_id}
--single-select-option-id {type_option_id}


**步骤5 — 向用户确认**

已创建#14：feat: add OAuth with Google — 已添加至看板，状态为Backlog/P1-High [Feature]

---

Flow 3: Query —

/backlog

and status questions

流程3：查询 —

/backlog

和状态查询

Default: full board summary

默认：完整看板摘要

bash

gh project item-list {project_number} --owner owner --format json --limit 100

Parse JSON and group items by Status field value. Output:

undefined

bash

gh project item-list {project_number} --owner owner --format json --limit 100

解析JSON并按Status字段值分组事项。输出示例：

undefined

Project Board: {project-name}

项目看板：{project-name}

In Progress (2)

进行中（2）

#14 feat: OAuth with Google [P1-High]
#12 fix: Email validation [P0-Critical]

#14 feat: OAuth with Google [P1-High]
#12 fix: Email validation [P0-Critical]

Review (1)

评审中（1）

#13 feat: User profile page [P1-High]

#13 feat: User profile page [P1-High]

Backlog (3)

待办事项（3）

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

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

Done (last 5)

已完成（最近5项）

#11 fix: Login redirect loop [P1-High]


Show statuses in order: In Progress → Review → Todo → Backlog → Done (last 5 only to avoid noise).

#11 fix: Login redirect loop [P1-High]


按以下顺序展示状态：进行中 → 评审中 → 待办 → 待办事项 → 已完成（仅展示最近5项以避免信息冗余）。

Filtered queries

过滤查询

Command	Filter applied
`/backlog bugs`	Only items with Type = Bug
`/backlog high`	Only items with Priority = P0-Critical or P1-High
`/backlog in-progress`	Only items with Status = In Progress
`/backlog todo`	Only items with Status = Todo
`/backlog review`	Only items with Status = Review

命令	应用的过滤条件
`/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的事项

Status Transitions

状态流转

Move an issue on the board with:

bash

undefined

使用以下命令在看板上移动Issue：

bash

undefined

Manual trigger

手动触发

/track move #14 in-progress /track move #14 review /track move #14 done

Underlying command

底层命令

gh project item-edit --project-id {project_number} --owner owner
--id {item_id}
--field-id {status_field_id}
--single-select-option-id {in_progress_option_id}


Automatic integration points:
- **Claude starts working on issue** → move to "In Progress"
- **Claude opens PR for issue** → move to "Review" (integrates with `branch-pr` skill)
- **PR merged / issue closed** → move to "Done"

---

gh project item-edit --project-id {project_number} --owner owner
--id {item_id}
--field-id {status_field_id}
--single-select-option-id {in_progress_option_id}


自动集成场景：
- **Claude开始处理Issue** → 移至「In Progress」状态
- **Claude为Issue创建PR** → 移至「Review」状态（与`branch-pr`技能集成）
- **PR合并 / Issue关闭** → 移至「Done」状态

---

Rules

规则

GitHub Issues + Projects is the source of truth for WHAT needs to be done — backlog, tasks, stories, bugs
Engram remains the source of truth for decisions, discoveries, and technical context — these are complementary, not competing
Never create duplicate issues — always run
```
gh issue list --search
```
before creating

Issue titles follow conventional format:

type: description

(e.g.,

feat: add OAuth

fix: email validation

)

Labels use lowercase with
/
separator:

type/feature

priority/high

status/backlog

Every issue MUST have at least the Type field set on the project board
/track-init
is idempotent — running it twice must not create duplicate labels or projects; handle errors from
```
gh label create
```
gracefully
Project config (IDs) MUST be saved to engram after bootstrap with
```
topic_key: tracking/{repo-name}/config
```
Before any
gh project item-edit
call, load field IDs from engram; if not found re-derive with
```
gh project field-list
```
Batch creation requires confirmation — when proposing multiple issues at once, show the full list and wait for user approval before creating any
Propose, don't assume type/priority — when auto-detecting trackable items from conversation, infer reasonable defaults but show them to the user before creating
Prefer MCP for issue creation (
```
mcp__github__create_issue
```
) and
```
gh
```
CLI for all project board operations
When
/track-init
has not been run (no engram config, no linked project), detect this and suggest running it before any board operation
Fine-grained PATs do NOT support Projects V2 on personal accounts — only Classic PATs or org-scoped fine-grained tokens work. When this is detected, guide the user to create the board manually and proceed with ID capture only
Both automatic and manual board creation paths converge at Step 3 (capture IDs) — the rest of the workflow is identical regardless of how the board was created

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时，展示完整列表并等待用户批准后再执行
提议而非默认设置类型/优先级 — 从对话中自动检测可跟踪事项时，推断合理默认值但需在创建前展示给用户确认
优先使用MCP创建Issue（
```
mcp__github__create_issue
```
），使用
```
gh
```
CLI执行所有项目看板操作
当未运行
/track-init
时（无engram配置、无关联项目），检测到该情况并建议用户先运行该命令再执行看板操作
细粒度PAT不支持个人账户的Projects V2 — 仅经典PAT或组织范围的细粒度令牌有效。检测到该情况时，引导用户手动创建看板并仅执行ID捕获流程
自动和手动创建看板的流程在步骤3（捕获ID）汇合 — 无论看板创建方式如何，后续工作流程完全相同

project-tracking

Original

Translation

Process

流程

Pre-flight: Detect Repo and Config

前置检查：检测仓库与配置

Detect owner/repo from git remote

从git远程仓库检测所有者/仓库名称

Parse: https://github.com/owner/repo.git → owner=owner, repo=repo

解析：https://github.com/owner/repo.git → owner=owner, repo=repo

Parse: git@github.com:owner/repo.git → same

解析：git@github.com:owner/repo.git → 结果相同

Flow 1: Bootstrap — /track-init

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

Step 0 — Detect token capabilities

步骤0 — 检测令牌权限

Step 1 — Create GitHub Project board (automatic path)

步骤1 — 自动创建GitHub Project看板

Create project linked to the repo

创建与仓库关联的项目

Capture: .number → project_number

捕获：.number → project_number

Status field (single select)

Status字段（单选类型）

Priority field (single select)

Priority字段（单选类型）

Type field (single select)

Type字段（单选类型）

Step 2 — Create labels

步骤2 — 创建标签

Type labels

类型标签

Priority labels

优先级标签

Status labels

状态标签

Step 3 — Capture field and option IDs

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

Step 4 — Save config to engram

步骤4 — 将配置保存至engram

Flow 2: Track — Create Issues and Add to Board

流程2：跟踪 — 创建Issue并添加至看板

Trigger model (hybrid)

触发模式（混合式）

Issue creation steps

Issue创建步骤

Description

描述

Context

上下文

Acceptance Criteria

验收标准

Capture: .id → item_id

捕获：.id → item_id

Set Status

设置Status

Set Priority

设置Priority

Set Type

设置Type

Flow 3: Query — /backlog and status questions

流程3：查询 — /backlog和状态查询

Default: full board summary

默认：完整看板摘要

Project Board: {project-name}

项目看板：{project-name}

In Progress (2)

进行中（2）

Review (1)

评审中（1）

Backlog (3)

待办事项（3）

Done (last 5)

已完成（最近5项）

Filtered queries

过滤查询

Status Transitions

状态流转

Manual trigger

Flow 1: Bootstrap —
`/track-init`

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

Flow 3: Query —
`/backlog`
and status questions

流程3：查询 —
`/backlog`
和状态查询