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:

bash

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

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.

Step 1 — Create GitHub Project board (automatic path)

Only if Step 0 confirms the token supports Projects V2:

bash

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

bash

# 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

bash

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

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

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)

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

Issue creation steps

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

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

bash

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:

bash

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

Then set each field:

bash

# 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

bash

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

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

Status Transitions

Move an issue on the board with:

bash

# 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

project-tracking

NPX Install

Tags

SKILL.md Content

Process

Pre-flight: Detect Repo and Config

Flow 1: Bootstrap —
`/track-init`

Step 0 — Detect token capabilities

Step 1 — Create GitHub Project board (automatic path)

Step 2 — Create labels

Step 3 — Capture field and option IDs

Step 4 — Save config to engram

Flow 2: Track — Create Issues and Add to Board

Trigger model (hybrid)

Issue creation steps

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

Default: full board summary

Filtered queries

Status Transitions

Rules