github

Repo Derivation

Derive at runtime, never hardcode; hold for the session. Run from the relevant repo root:

• Issues/board/stories/TDD/design -> orchestration repo.
• PRs/branches -> codebase directory (path from the Codebases table).

gh repo view --json owner,name --jq '[.owner.login,.name]|join("/")'

Confirmation Protocol

Before any mutating op: summarise all planned mutations in one block, ask once "Proceed? (y/n)", proceed only if confirmed.

• Skip: read-only ops (read issue, list issues, board reads — list sprint, list drafts, resolve active sprint).
• Always confirm: create issue, update issue body, update labels, post comment, close issue, update comment, board mutations (set status / type / sprint, add issue to board, create draft, delete item).
• Exception: board status transitions and self-assignment (Assign Issue) that a command performs as a documented side effect of an already-confirmed mutation (e.g. Notify Implementation Complete) need no second confirmation.

Operations

Link Reference

Format: #id (e.g. #17) — use in issue bodies and comments.

Fetch Issue

• gh issue view {id} --repo {owner}/{repo} --json title,body,labels,comments

Create Issue

• gh issue create --repo {owner}/{repo} --title "{title}" --body "{body}" --label {label} — returns new issue URL.
• Sprint membership and lifecycle state live on the project board, not the issue — after creating, register the issue on the board (see Project Board).

Update Issue Body

• Read the issue first (Fetch Issue), modify, then write.
• gh issue edit {id} --repo {owner}/{repo} --body "{body}"

Update Labels

• gh issue edit {id} --repo {owner}/{repo} --add-label {add} --remove-label {remove} — no read needed; omit either flag to skip that side.

Assign Issue

• gh issue edit {id} --repo {owner}/{repo} --add-assignee @me — assigns the authenticated user; @me resolves at runtime, never hardcode a login.

Post Comment

• gh issue comment {id} --repo {owner}/{repo} --body "{body}"

Update Comment

• gh api repos/{owner}/{repo}/issues/comments/{comment_id} --method PATCH -f body="{body}"

List Open Issues

• gh issue list --repo {owner}/{repo} --state open --label {label} --json number,title,labels

Close Issue

• gh issue close {id} --repo {owner}/{repo}

Project Board (Projects v2)

Board = single tracking surface:

• Status replaces lifecycle labels.
• Sprint (single-select) replaces milestones.
• Type (Feature / Refactor / Bug) classifies items.

All board ops -> .claude/scripts/board.sh. Resolves project by title + field/option IDs by name at runtime, caching to gitignored .claude/state/board.json (auto-refreshed on lookup miss + after sprint-option mutations — never edit or commit it). Needs project token scope; scope failure → surface gh auth refresh -s project --hostname github.com. No board → surface that the project board isn't provisioned yet.

Status lifecycle: Backlog (captured draft) → Todo (issue filed) → In Progress (implement start) → Implemented (PRs open, awaiting merge) → Done (released + closed).

Resolve Active Sprint

• bash .claude/scripts/board.sh current-sprint — prints the highest Sprint N that still has active (non-Done) work → $SPRINT_N from its number.
• Script halts if none: ⛔ No active sprint on the board.

Next Sprint Number

• bash .claude/scripts/board.sh next-sprint-number — prints max(N)+1.

Ensure Sprint

• bash .claude/scripts/board.sh ensure-sprint {N} — appends the Sprint N option if missing. Idempotent.

Register Issue on Board

After creating an issue, add it and set its fields (Sprint for sprint-scoped work — stories, TDD, requirement, in-sprint bugs, in-sprint refactors; standalone refactors and production bugs get none):

• bash .claude/scripts/board.sh add-issue {id}
• bash .claude/scripts/board.sh set-type {id} {Feature|Refactor|Bug}
• bash .claude/scripts/board.sh set-status {id} Todo
• bash .claude/scripts/board.sh set-sprint {id} "Sprint N" (sprint-scoped work only)

Set Board Status

• bash .claude/scripts/board.sh set-status {id} {Backlog|Todo|In Progress|Implemented|Done} — self-healing: adds the issue to the board first if absent.

List Sprint Items

• bash .claude/scripts/board.sh list-sprint "Sprint N" [--open-only] — JSON [{number, title, labels, status, type, state}].

Create Backlog Draft

• bash .claude/scripts/board.sh set-draft "{title}" "{body}" {Type} — draft item, Status=Backlog. Prints item ID.

List Backlog Drafts

• bash .claude/scripts/board.sh list-drafts — JSON [{id, title, body, type, status}].

Delete Board Item

• bash .claude/scripts/board.sh delete-item {item-id} — used after promoting a draft.

Load Sprint Snapshot

Resolve Active Sprint → list-sprint "Sprint N" --open-only once (closed issues = out of sprint scope) → partition in memory → read all present partitions in parallel:

• $STORIES — open issues labelled user-story. Read each in full.
• $REQUIREMENT — single open issue labelled requirement. May be absent.
• $TDD — single open issue whose title contains Technical Design Document. Read in full. May be absent.
• $DESIGN — design hub comment on $REQUIREMENT (body starts ## Design Navigation); its Surfaces table links each surface's Storybook story file. Resolve via $REQUIREMENT's comments — design is a comment, never a labelled issue. May be absent. Callers read the linked story files for surfaces they need.

Notify Implementation Complete

Two mandatory mutations on issue #ISSUE_NUMBER — run both, never stop after the comment.

Step 1 — Post or update completion comment

Fetch comments (gh issue view {id} --repo {owner}/{repo} --json comments). One starts with ## Refactor Complete, ## Implementation Complete, or ## Revert Ready → update via Update Comment (don't post new). Else → Post Comment.

Pick mode (refactor / revert / implementation) + variant:

• Single-PR — one PR.
• Multi-PR — one bullet per PR, labelled by codebase name from the Codebases table (e.g. api, web, infrastructure) — never hardcode Backend/Frontend.

Substitute every <pr-url> with the actual URL.

Refactor — single-PR:

## Refactor Complete

- PR: <pr-url>

---
> ⏸ Human gate: Review the PR diff. When approved, merge the PR into its base — `main` for a standalone refactor, or the sprint branch for an in-sprint refactor.

Refactor — multi-PR (one bullet per codebase):

## Refactor Complete

- <codebase-name>: <pr-url>
- <codebase-name>: <pr-url>

---
> ⏸ Human gate: Review all PR diffs. When approved, merge the PRs into their base — `main` for a standalone refactor, or the sprint branch for an in-sprint refactor.

Revert — single-PR:

## Revert Ready

Story #<ISSUE_NUMBER> was removed from scope. Implementation has been reversed.

- Revert PR: <revert-pr-url>

---
> ⏸ Human gate: Review the revert PR diff. When approved, merge into the sprint branch.

Revert — multi-PR:

## Revert Ready

Story #<ISSUE_NUMBER> was removed from scope. Implementation has been reversed across all codebases.

- <codebase-name> revert PR: <revert-pr-url>
- <codebase-name> revert PR: <revert-pr-url>

---
> ⏸ Human gate: Review all revert PR diffs. When approved, merge into the sprint branch.

Implementation — single-PR:

## Implementation Complete

- PR: <pr-url>

---
> ⏸ Human gate: Review the PR diff. When approved, merge into the staging branch.

Implementation — multi-PR:

## Implementation Complete

- <codebase-name>: <pr-url>
- <codebase-name>: <pr-url>

---
> ⏸ Human gate: Review all PR diffs. When approved, merge into the staging branch.

Step 2 — Update board status

Via Set Board Status (implementation and refactor modes; skip for revert):

bash .claude/scripts/board.sh set-status {ISSUE_NUMBER} Implemented

Step 3 — Confirm

Output a single line listing the PR URL(s) for the orchestrator's summary.