managing-project-backlog

Managing the Project Backlog

Automate the GitHub Projects kanban workflow — from epic creation through to merged. Every piece of work traces back to an epic; every epic connects to the product roadmap.

⛔ Invocation rule — read first. This skill governs the deckhand GitHub Projects board workflow. Fire eagerly when the user is doing board work — "the board", "the backlog", "pick up #N", "work on #N", "what's next", epics, sub-issues, prioritising, a pasted GitHub Projects URL. Then apply the board-awareness gate in the first-invocation protocol below: if a board is in play (configured, or present on the repo) act on it; if there is genuinely no board, step aside rather than barging in. Once you're doing board operations, follow this skill's conventions consistently for the rest of the session.

If you find yourself about to run gh issue ..., gh project ..., or pick up an issue without having read this skill in the current session — STOP and load it first. The board IDs, column mappings, and the "read epic + siblings before starting" protocol below are not optional context.

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

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

• Configured — board-config.md has no <...> placeholders (<OWNER>, <REPO>, <PROJECT_NUMBER>, <PROJECT_ID>, <STATUS_FIELD_ID>, <EPICS_OPTION_ID>, etc.). Proceed as normal — this is the everyday case, and "pick up #N" / "what's next" 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-managing-project-backlog>/../ticket-lifecycle/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 both skills' board-config.md files. When invoking from Claude Code, ask the user the three questions in chat, then call the script — 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 board-config.md yourself.

Do not invent IDs. Do not skip setup and hope it works. Only proceed to the rest of the workflow once board-config.md has no <...> placeholders left. The "Project Discovery" section below shows how to look them up manually if needed.

🔄 Staying up to date (quiet by default).

On your first invocation in a session, run a throttled version check from the folder this skill is installed in (the one holding this SKILL.md and its VERSION). Suggested one-liner — adapt the path; on Codex/Cursor it's wherever this skill actually lives:

DIR="<this skill's folder>"
[ -f "$DIR/.no-update-check" ] && exit 0                                                                        # user opted out
[ -f "$DIR/.last-update-check" ] && [ -z "$(find "$DIR/.last-update-check" -mtime +0 2>/dev/null)" ] && exit 0  # checked < 24h ago
touch "$DIR/.last-update-check"
LOCAL=$(cat "$DIR/VERSION" 2>/dev/null)
REMOTE=$(curl -fsS --max-time 3 https://raw.githubusercontent.com/jonthebeef/deckhand/main/skills/managing-project-backlog/VERSION 2>/dev/null)
[ -n "$REMOTE" ] && [ "$REMOTE" != "$LOCAL" ] && echo "deckhand update available: $LOCAL -> $REMOTE"

• If a newer version is reported: tell the user once, briefly ("deckhand $REMOTE is available, you have $LOCAL — want me to update it?"), then get on with their actual request. Never block on it.
• If current, offline, or the check errors: say nothing. Silence is the default.
• Don't offer twice in one session — if ticket-lifecycle already offered, skip.
• To disable: the user drops an empty .no-update-check file in this folder, or just asks. See the README's "Staying up to date" section.