Automate Project status transitions (Todo -> In Progress -> Done)

[andybaran]

Context

When a repo uses a GitHub Project (the skill creates one at >3 open issues), the board is only useful if item status is kept current. Today references/projects.md documents moving items to In Progress / Done, but this is NOT wired into the enforced workflow steps and, in practice, items sit in the default column while work happens — observed live: the 5 upgrade issues were added to Project #14 but none were moved to In Progress when their implementation started.

Depends on: issue #7 (SKILL.md integration) — this touches SKILL.md, so it lands after #7 to avoid file conflicts. Rebase on it.

Goal

Make Project status transitions an enforced, low-friction part of the flow so the board always reflects reality.

Acceptance criteria

• references/projects.md: turn the status-transition guidance into a required, copy-pasteable recipe. Include the full sequence to resolve the dynamic IDs and set status, e.g.:

  # Resolve project + Status field + option ids
  gh project view <num> --owner "@me" --format json          # -> project id
  gh project field-list <num> --owner "@me" --format json     # -> Status field id + option ids (Todo/In Progress/Done)
  gh project item-list <num> --owner "@me" --format json       # -> item id for a given issue
  gh project item-edit --id <item-id> --project-id <proj-id> \
    --field-id <status-field-id> --single-select-option-id <option-id>

  Document the two transitions: -> In Progress when the implementation agent cuts the branch (Step 3), -> Done when the PR squash-merges (Step 4).
• Optional helper in scripts/gitflow.sh (only if it stays simple): a project-status subcommand, e.g. gitflow.sh project-status <issue-number> <in-progress|done> that looks up the linked project/item and sets status, degrading gracefully (no-op with a clear message) when the repo has no project or the project token scope is missing.
• SKILL.md: add explicit one-line hooks in Step 3 ("move the item to In Progress") and Step 4 ("move the item to Done") that point at references/projects.md, and add these to the Quick reference table. Keep it a no-op when there's no Project (the >3 threshold not crossed).
• Graceful degradation: everything must no-op cleanly when (a) there is no Project, or (b) the active token lacks the project scope — never hard-fail the workflow over board bookkeeping.

Test strategy

• If a project-status helper is added: cover it in tests/ (mock/skip the gh project calls; assert the no-project / missing-scope paths no-op with a clear message and exit 0).
• Docs check: SKILL.md Step 3/Step 4 and the Quick reference reference the status transitions; references/projects.md contains the id-resolution + item-edit recipe.
• Manual/one-time: on Project feat(skill): core SKILL.md integration (#7) #14, confirm an item can be moved to In Progress and Done with the documented commands.

[andybaran]

🔍 Review (review agent)

I pressure-tested the plan against the repo and the live gh project surface.

• Current docs already say to move items to In Progress / Done, but only show field-list + item-edit; they do not show resolving the project id via gh project view or resolving an issue's project item id via gh project item-list. The requested enhancement fills that real gap and correctly wires the requirement into SKILL.md Step 3, Step 4, and Quick reference.
• In the current checkout, issue Rename skill + repo to 'github-flow' and clarify terminology #3's rename is already reflected locally (skills/issue-driven-github-flow/...); the same projects.md content exists there, so the plan's note about rebasing onto the renamed path is correct.
• Verified read-only on Project feat(skill): core SKILL.md integration (#7) #14: gh project view 14 --owner "@me" --format json returns project id PVT_...; gh project field-list ... --format json exposes the Status single-select field id and option ids (Todo, In Progress, Done); gh project item-list ... --format json exposes each item id plus linked issue metadata at .content.number, .content.url, and .content.repository (including issue Automate Project status transitions (Todo -> In Progress -> Done) #8). That is enough to map issue number -> item id.
• gh project item-edit --id <item-id> --project-id <project-id> --field-id <status-field-id> --single-select-option-id <option-id> is the documented command shape in gh project item-edit --help, so the mutation recipe is correct. I did not run it.
• Graceful degradation is necessary and correctly specified. gh auth status currently shows the project scope on this machine, but the missing-scope case is real for gh project commands. The proposed helper tests should stub/mock gh failures for missing scope and no project and assert a clear message plus exit 0; that is the right non-blocking behavior for board bookkeeping.
• The dependency on Core SKILL.md integration: verification gate, CI gating, safety rails, worktrees, code-review step #7 is correct: Core SKILL.md integration: verification gate, CI gating, safety rails, worktrees, code-review step #7 edits SKILL.md Step 3/Step 4 and Quick reference, which are exactly the areas Automate Project status transitions (Todo -> In Progress -> Done) #8 will touch. Landing Automate Project status transitions (Todo -> In Progress -> Done) #8 after Core SKILL.md integration: verification gate, CI gating, safety rails, worktrees, code-review step #7 avoids needless conflicts; Core SKILL.md integration: verification gate, CI gating, safety rails, worktrees, code-review step #7's dependency on Rename skill + repo to 'github-flow' and clarify terminology #3 also gives Automate Project status transitions (Todo -> In Progress -> Done) #8 the renamed issue-driven-github-flow path transitively.

Optional helper note: keep gitflow.sh project-status only if project discovery stays simple; otherwise the documentation hooks alone satisfy the core workflow without introducing fragile GitHub Projects discovery logic.

Verdict: APPROVED