/implement-issue

name: implement-issue
description: Implements an issue end-to-end: fetches the spec from the project issue tracker, creates branch, writes code with TDD, runs checks, commits, publishes a draft change (PR/MR), closes issue on merge. Tracker- and host-agnostic — GitHub via gh CLI is the factory default; docs/agents/issue-tracker.md and docs/agents/code-host.md override. Use when user says "implement issue", "work on issue #N", "/implement-issue", or wants to process an issue locally.

Implement Issue

Full issue → PR → close flow, locally.

**Contract docs.** The issue mechanics come from the repo's `docs/agents/issue-tracker.md` (its `## Delivery operations` section) and the change mechanics from `docs/agents/code-host.md` — read those two files first if present. The commands below are the **GitHub factory defaults** (`gh`), used verbatim when those docs are absent or confirm GitHub; when a doc defines a different mechanic for an operation, the doc wins. "PR" below means whatever the code host calls a reviewable change (pull request, merge request, branch + change file).

**Their annexes are deferred, not optional.** Those two docs link phase annexes — `code-host-ci.md` when a change's CI has to be waited on, read or classified; `issue-authoring.md` when issues are being *created*, which this skill never does. **Do not read an annex at the start**: open it at the step that names it, and not before. Implementing an issue and publishing a draft change needs nothing from either.

Invoke

/implement-issue          # lists open issues to pick from
/implement-issue 42       # implements issue #42 directly
/implement-issue 17       # if #17 has sub-issues, picks the first unblocked open one

One sub-issue per invocation — keeps sessions short and focused.

Flow

1. Select issue

**If an orchestrator (e.g. /developer) already told you which sub-issue to implement, skip selection entirely** — verify the issue is open and go to step 2. The checks below are for interactive use, where the given ref may be a parent. Enumerate its children per the tracker doc — GitHub default:

gh api graphql -f query='
{
  repository(owner:"OWNER", name:"REPO") {
    issue(number: ISSUE_NUM) {
      subIssues(first: 50) {
        pageInfo { hasNextPage }
        nodes { number title state }
      }
    }
  }
}' --jq '.data.repository.issue.subIssues'

If `hasNextPage` is `true`, **stop and report**: a parent with more than 50 children should be split, not worked through — and picking from a truncated list would silently ignore the rest.

If sub-issues exist, pick the first unblocked one. Blockers may be wired as the tracker's native dependency links, as a "Blocked by" section in the sub-issue body, or both (`/to-tickets` prefers native edges where the tracker has them) — check both, per the tracker doc's blocker-state operation. GitHub default:

gh api repos/OWNER/REPO/issues/<N> --jq '.issue_dependencies_summary.blocked_by // 0'  # open native blockers; 0 = clear
gh issue view <BLOCKER> --json state --jq '.state'  # each body-listed blocker must be "CLOSED"

Pick the first open sub-issue where all blockers are closed. If none are unblocked, report to user and stop.

If no sub-issues exist, implement the issue directly.

**If no ref given**, list open issues carrying the AFK-ready triage label per the tracker doc — GitHub default:

gh issue list --state open --label "ready-for-agent" --json number,title,labels \
  --jq '.[] | "#\(.number) \(.title)"'

(`ready-for-agent` is the triage vocabulary from `docs/agents/triage-labels.md`; use the repo's mapping if it differs.)

Priority order: **bugs > tracer bullets > polish > refactors**. Pick highest-priority unblocked issue, or ask user to confirm.

2. Read spec

Read the issue with its comments per the tracker doc — GitHub default:

gh issue view <N> --comments

Read the full body, acceptance criteria, and all comments.

**The issue is the spec — the parent is the fallback.** A well-formed ticket carries a `## Spec extract` section with the parent's Implementation and Testing Decisions that apply to it, copied verbatim (the tracker doc requires it of `/to-tickets`). When that section is there, build from it and **do not read the parent**: the rest of the parent's body is decisions for *other* tickets, and it competes for context with the code you still have to explore.

Read the full parent spec only when the section is **missing** (an older ticket, or one written by hand) — then pull it per the `## Parent` section in the issue body, and treat that as the exception it is.

3. Create branch

# slug = issue title lowercased, spaces→dashes, max 50 chars
# <N> = the issue ref, slugified if it isn't a plain number
git fetch origin main
git checkout -b agent/issue-<N>-<slug> origin/main

(On a local code host there is no `origin` — branch from local `main` instead: `git checkout -b agent/issue-<N>-<slug> main`. The code-host doc names the base.)

Never `git checkout main` — when running in a linked worktree (the /developer pipeline always does), `main` is checked out in the primary worktree and the command fails. Branching straight from `origin/main` works everywhere.

As a /developer worker, confirm you really are in a linked worktree before branching: `git rev-parse --path-format=absolute --git-dir --git-common-dir` prints two different paths there. The same path twice means you escaped into the user's primary checkout — stop and report blocked instead of branching there. (Interactive use in the primary checkout is fine.)

Keep `--path-format=absolute`: without it git prints whichever form is shortest from your cwd, so from a subdirectory of the primary checkout you get `/abs/path/.git` and `../.git` — two different strings for the same repo, and the check silently clears you to touch the user's checkout.

**Branch before you explore.** A linked worktree is created from the *loca