implement-issue

name	implement-issue
description	End-to-end implementation of a GitHub issue — from reading the issue through TDD, code review, PR creation, CI monitoring, and merge. Use when the user says "implement issue

Implement Issue

End-to-end workflow for implementing a single GitHub issue. Accepts an issue number as argument.

This workflow ships one issue per PR. Every issue follows the same 9-step pipeline, no exceptions. The pipeline exists because skipping steps (especially quality gates and review) creates debt that slows down later issues.

Arguments

The issue number (e.g., 23 or #23). Extract the number and strip any # prefix.

Before Starting: Close Open PRs First

Check for open PRs before starting new work. Open PRs represent unfinished value — merging them is always higher priority than starting something new.

gh pr list --state open

If open PRs exist:

1. Check their CI status (gh pr checks <PR#>)
2. If CI is green → merge (gh pr merge <PR#> --squash --delete-branch)
3. If CI is pending → monitor until complete, then merge
4. If CI failed → fix the failure, push, wait for re-run
5. Only after all PRs are merged, proceed with the new issue

Step 1: Read the Issue

gh issue view <NUMBER>

Understand the full scope: what to build, acceptance criteria, blocked-by dependencies. If the issue is blocked by unmerged work, stop and report.

Step 1.5: Claim the Issue

Before creating a branch or writing any code, claim the issue so a concurrent runner picks a different one. Follow the full Work-claiming protocol in CLAUDE.md ("Work-claiming" under AI Execution Rules; see also ADR-0007):

gh issue edit <NUMBER> --add-assignee @me

Then confirm no competitor claimed at the same moment:

gh issue view <NUMBER> --json assignees --jq '.assignees|map(.login)'
gh pr list --search "<NUMBER> in:title" --state all
git ls-remote --heads origin | grep -i "<NUMBER>" || true

If a competing assignee, open PR, or recently-pushed branch for this issue already exists, yield: release (gh issue edit <NUMBER> --remove-assignee @me) and stop. If anything blocks this run unrecoverably later (skip, unrecoverable CI failure, guardrail block), release the claim before halting. On a successful squash-merge the issue closes automatically — no explicit release needed.

Step 2: Create a Feature Branch

git checkout main && git pull origin main
git checkout -b feat/<slug>

Use a short kebab-case slug derived from the issue title (e.g., feat/blocks, feat/cart-inventory, feat/guest-players).

Step 3: Explore the Codebase

Before writing any code, understand what you're working with:

• Read the files you'll need to modify
• Understand existing patterns (schemas, routes, tests, frontend components)
• Check CONTEXT.md for domain terminology
• Identify the vertical slices for implementation

Spawn an Explore agent for broad codebase exploration if needed. For targeted lookups, use grep/find directly.

Step 4: TDD Implementation

Invoke the /tdd skill for the implementation. Implement in vertical slices — each slice follows RED → GREEN:

1. Write ONE failing test (RED)
2. Run the test — confirm it fails
3. Write minimal code to pass (GREEN)
4. Run the test — confirm it passes
5. Move to next slice

Typical slice order for a full-stack feature:

1. Shared schemas — Zod types in @butler/shared
2. Pure logic — validators, calculators, engines in @butler/shared
3. Database migration — SQL in supabase/migrations/
4. API routes — Hono routes in packages/api/src/routes/
5. Frontend components — React pages in packages/frontend/src/pages/
6. Wiring — route registration in app.ts/app.tsx

Each slice gets its own test-then-implement cycle. Do not write all tests first — that's horizontal slicing and produces bad tests.

Use TaskCreate to track slices and mark them complete as you go.

Step 5: Quality Gates

All three must pass before proceeding to review:

pnpm --filter @butler/shared build   # Build shared first (other packages resolve from dist/)
pnpm run test                         # All tests across all packages
pnpm run lint                         # ESLint
pnpm run type-check                   # tsc --noEmit across all packages

Fix any failures before proceeding. Never move to review with failing gates.

Step 6: Code Review

Invoke the /review skill against main to run a dual-axis review:

• Standards — does the code follow CLAUDE.md conventions, CONTEXT.md terminology, and project patterns?
• Spec — does the code match what the issue asked for? Are acceptance criteria met?

The review skill runs both axes in parallel subagents. Fix any Critical or High severity findings before committing. Medium findings are fix-or-acknowledge. Low findings are optional.

After fixing review findings, re-run quality gates (Step 5) to confirm nothing broke.

Step 7: Commit

Stage specific files (never git add -A). Write a conventional commit message:

feat: <short description> (#<issue-number>)

<what was built and why, 2-3 lines>

- bullet points of key changes
- test count, lint status, type status

Step 8: Push and Create PR

git push -u origin <branch-name>
gh pr create --title "<type>: <description>" --body "$(cat <<'EOF'
## Summary
Closes #<NUMBER>
- bullet points of what changed

## Test plan
- [x] N tests passing across all packages
- [x] ESLint clean
- [x] tsc --noEmit clean
- [x] Code review passed (Standards + Spec)
EOF
)"

Step 9: Monitor CI and Merge

Arm a Monitor on the PR's CI checks:

# Poll until all checks complete
prev=""
while true; do
  run_state=$(gh pr checks <PR#> --json name,bucket 2>/dev/null) || { sleep 30; continue; }
  cur=$(echo "$run_state" | jq -r '.[] | select(.bucket!="pending") | "\(.name): \(.bucket)"' 2>/dev/null | sort)
  if [ -n "$cur" ]; then comm -13 <(echo "$prev") <(echo "$cur") 2>/dev/null; fi
  prev="$cur"
  echo "$run_state" | jq -e 'all(.bucket!="pending")' >/dev/null 2>&1 && { echo "ALL_CHECKS_COMPLETE"; break; }
  sleep 30
done

When CI is green:

gh pr merge <PR#> --squash --delete-branch

If CI fails on a required check, fix the issue, push, and monitor the re-run. Informational checks (like codecov/patch) that aren't required can be ignored.

Looping Through Multiple Issues

When processing multiple issues in sequence, after merging:

1. git checkout main && git pull origin main
2. Check gh issue list --state open --label ready-for-agent for the next issue
3. Start again from Step 1 with the next issue number

What NOT to Do

• Don't start a new issue while a PR is open — merge it first
• Don't write all tests before any implementation (horizontal slicing)
• Don't skip quality gates or code review
• Don't use git add -A or git add .
• Don't commit with failing tests, lint errors, or type errors
• Don't create multiple PRs for one issue