/next-task

Turns an open tracker issue into an actionable plan, the planning step of the issue workflow (.claude/rules/issue-workflow.md). It does not do the work; that is a separate step the caller takes after seeing the plan.

Steps

1. Read the tracker: gh issue list --state open (the SessionStart dump annotates each issue with {k/n} sub-issue progress, child-of #parent, and open BLOCKED-by/blocks edges, and prints <Type/Priority> after each title). Take the pinned issue (current focus) or the issue the user named; otherwise take the open, unblocked issue with the highest Priority field (Urgent, then High, Medium, Low), the oldest first within a priority. Respect relationships (.claude/rules/issue-relationships.md): do NOT pick an issue shown BLOCKED-by an open issue (surface its blocker as the real next task instead); for a parent issue, point at its next open child rather than the parent itself. An issue shown <?/?> has no type or priority yet: set the type, the priority, the effort and the milestone with scripts/gh/fields.sh before planning it. Then gh issue view <n> --json title,body,comments --jq '.title, .body, (.comments[] | "--- comment ---", .body)' for the full contract (the opening summary plus ## Acceptance criteria) and the running discussion (--comments prints nothing for an issue without comments, issue-workflow.md §The loop), and scripts/gh/rel.sh tree <n> for its parent, children, and blockers.
2. Turn the task into a plan, stating:
   • What the task requires, in one or two sentences.
   • Which files are involved, found by searching rather than guessing paths, and the section of ARCHITECTURE.md that decides the design. If the task changes the design, the plan includes the ARCHITECTURE.md update.
   • Which external behaviour it relies on: for anything that depends on Claude Code (CLAUDE_CONFIG_DIR, login state, usage and reset times) or on macOS (the Keychain, exec), name the documentation the work is read against, or say that the behaviour is undocumented and must be verified by hand first.
   • What "done" looks like for this task specifically: the issue's ## Acceptance criteria checklist, plus what proves it.
3. When work on the picked issue actually starts (the plan is accepted and the session proceeds), move it to In Progress on the roadmap board: scripts/gh/project.sh status <n> in-progress, the one manual board move in the lifecycle (.claude/rules/project-board.md). If the session parks the issue unfinished, move it back (scripts/gh/project.sh status <n> todo); a stale In Progress column is a false claim. If the board does not exist yet, the command fails loud; note that and continue.
4. Do not edit the issue or commit: recording progress happens after the work is actually done, not as part of planning it.