ticket-lifecycle

Ticket Lifecycle

Automated batch ticket processing for any GitHub-Projects-driven repo. Take a set of GitHub issues, implement fixes, run code review, address feedback, watch CI, merge when green, and move tickets across the Kanban board.

⛔ Invocation rule — this skill is MODULAR.

Ticket Lifecycle is for running a GitHub Projects board's tickets through their full lifecycle; reach for it when that is what the user wants, not for every passing mention of a bug or issue. The full Phase 0→7 sequence describes the ideal run: many tickets in parallel worktrees, fresh-context reviewers, the lot. But the value of the skill is the discipline of the phases, not the parallelism. Most sessions will use a subset:

• Solo / single ticket, sequential, no worktrees → still use this skill. Drop Phase 2's parallelism, run one Implement → Simplify → Review → Fix-loop → Merge cycle. Phase 0 (load learnings) and Phase 3.5 (capture learnings) still apply.
• Fixing review feedback on an existing PR → start at Phase 4. You already have implementation; just run the fix-and-review loop until clean, then Phase 6 (Merge) and Phase 7 (Cleanup).
• Already-merged ticket, board cleanup pending → jump to Phase 7.
• Can't dispatch subagents at all → run the phases yourself in the main thread. The review-isolation rule (Phase 3) becomes "open a fresh Claude Code session for the review" instead of "dispatch an isolated agent". The discipline still holds.
• Tiny one-line fix → Phases 1 (read), 2 (implement + test), 6 (merge), 7 (board move) are usually enough. Skip Simplify and Review only if the change is genuinely trivial and the user has signalled they don't want a fresh-eyes review.

Do not skip this skill because you can't run all of it. The wrong move is "I can't do Phase 2 in parallel worktrees, therefore I won't use Ticket Lifecycle at all" — that throws away Phases 0, 3, 3.5, 4, 5, 6, 7 along with it. Instead: announce which phases apply, which you're skipping, and why. Then run the applicable phases properly.

Phases are independently valuable. Phase 3 (isolated review) on its own catches bugs. Phase 4 (review loop) on its own raises PR quality. Phase 5 (sub-issue linking) on its own keeps the backlog navigable. Use what fits.

When the user wants the board-driven lifecycle, invoke and state which phases you're using.

⚠ First-invocation protocol (read this BEFORE running any phase).

deckhand only operates on a GitHub Projects board, so first establish which situation you're in by reading references/board-config.md:

• Configured — board-config.md has no <...> placeholders (<OWNER>, <REPO>, <PROJECT_NUMBER>, <PROJECT_ID>, <STATUS_FIELD_ID>, <EPICS_OPTION_ID>, etc.). Proceed with the workflow as normal — this is the everyday case, and "pick up #N" / "process prioritized" should just work.
• Not configured, but a board is in play — placeholders remain, but the user is clearly doing GitHub Projects board work, or the repo's owner has a board (a quick gh project list --owner <owner> returns one). Offer to wire deckhand up: run setup (below), then proceed. Ask first; don't force it.
• No board in play — placeholders remain AND there is no GitHub Projects board to drive (not a GitHub repo, or gh project list comes back empty, and the user only said something generic). Step aside: briefly say deckhand runs off a GitHub Projects board and you don't see one here, offer to set one up if they'd like, and otherwise do nothing. Do NOT run board operations or push setup on someone who has no board.

When a board is in play but not yet configured, set it up before any board operation. You — the assisting Claude — must run setup before any board operation.

Two options, in order of preference:

1. Run the bundled script: bash <path-to-skill>/setup.sh. It's interactive — it will ask the user for owner, repo, and project number, auto-discover the rest via gh api graphql, and write the populated config to this skill's references/board-config.md (and to managing-project-backlog/board-config.md if it's installed alongside). When invoking from Claude Code, ask the user the three questions in chat, then call the script and pipe the answers in — or perform the equivalent GraphQL discovery yourself and write board-config.md directly.

2. Do it inline: if the user can't run an interactive script, you can do the discovery yourself. Ask the user for owner / repo / project number, then run:

   gh api graphql -f query='query{user(login:"<OWNER>"){projectV2(number:<NUM>){id title fields(first:50){nodes{... on ProjectV2SingleSelectField{id name options{id name}}}}}}}'
   

   (swap user for organization if the owner is an org). Show the user the discovered column list, ask them to map each of the six workflow terms (Epics / Backlog / Prioritized / Doing / Review / Done) to one of their actual columns, then write the populated references/board-config.md yourself.

Do not invent IDs. Do not skip setup and hope it works — every Phase that touches the board needs real IDs. Only proceed to the rest of the workflow once board-config.md has no <...> placeholders left.

The skill assumes the logical workflow columns Epics / Backlog / Prioritized / Doing / Review / Done. Your actual column names can be anything — setup maps your column names to these terms. The skill also assumes a CLAUDE.md at repo root with project standards and (optionally) a lessons doc.