project-tracking（项目跟踪）

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.

Process

Pre-flight: Detect Repo and Config

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

# Detect owner/repo from git remote
git remote get-url origin
# Parse: https://github.com/owner/repo.git → owner=owner, repo=repo
# Parse: git@github.com:owner/repo.git → same

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

Flow 1: Bootstrap — /track-init

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

Step 0 — Detect token capabilities

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

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.

Step 1 — Create GitHub Project board (automatic path)

Only if Step 0 confirms the token supports Projects V2:

# Create project linked to the repo
gh project create --owner owner --title "{repo-name} Board" --format json
# Capture: .number → project_number

Then add custom fields:

# Status field (single select)
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)
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)
gh project field-create {project_number} --owner owner \
  --name "Type" --data-type "SINGLE_SELECT" \
  --single-select-options "Epic,Feature,Bug,Chore"

Step 2 — Create labels

# 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).

Step 3 — Capture field and option IDs

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

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.

Step 4 — Save config to 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."

Flow 2: Track — Create Issues and Add to Board

Trigger model (hybrid)

Issue creation steps

Step 1 — Deduplicate

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:

## 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}

## Acceptance Criteria
- [ ] {criterion 1}
- [ ] {criterion 2}

Step 3 — Add to project board

gh project item-add {project_number} --owner owner \
  --url https://github.com/owner/repo/issues/{issue_number} \
  --format json
# Capture: .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:

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

Then set each field:

# Set 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
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
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]

Flow 3: Query — /backlog and status questions

Default: full board summary

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

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

## 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]

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

Filtered queries

Status Transitions

Move an issue on the board with:

# 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"

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