implement-issue

name	implement-issue
description	Use when a GitHub issue has been triaged and is ready for implementation on the apijack repo — creates the issue branch, implements, tests, self-reviews, opens a PR to dev, waits for the automated reviewer, and addresses feedback in a loop

Implement Issue

Phase 2 of the apijack issue workflow. Turn a triaged issue into a reviewed-and-accepted PR against dev.

When to Use

• After triage-issue has clarified the issue and handed off
• User explicitly asks to implement a specific, already-clear issue

Do not invoke this skill before triage is complete. If the issue has not been triaged, invoke triage-issue first.

Steps

1. Set up an isolated branch

Slugify the issue title: lowercase, hyphenated, drop filler words, aim for 3–5 words. The branch name is issues/<number>-<short-slug> (e.g., issues/37-opt-in-auth for issue #37 "Make auth opt-in").

Always work off an up-to-date dev. Prefer a worktree for full isolation — pass --worktree to also create a sibling worktree at ../apijack-<short-slug>.

./.claude/skills/implement-issue/scripts/start-issue-branch.sh <issue-number> <short-slug> --worktree
# or, in-place branch in the current repo:
./.claude/skills/implement-issue/scripts/start-issue-branch.sh <issue-number> <short-slug>

If dev is behind main (e.g., right after a release), sync it first, then re-run the script:

./.claude/skills/implement-issue/scripts/sync-dev-from-main.sh

Note: the push inside sync-dev-from-main.sh is the only push to dev this skill performs — a maintenance sync, not feature work. Everything else operates on the feature branch and PRs into dev.

2. Plan or implement

If the issue is clear and small (single obvious change): implement directly.

If any of the following are true, invoke the brainstorming skill first to plan:

• Multiple files affected and the structure isn't obvious
• Public API or generated code output changes
• Multiple viable approaches with real tradeoffs

Skill(skill="superpowers:brainstorming")

3. Implement

• Follow existing patterns in the codebase
• Keep changes focused on the issue — no drive-by refactors
• Add or update tests alongside code changes
• If MCP server code changed (src/mcp-server*.ts), run bun run build:plugin — the bundle is committed and is loaded at runtime

4. Self-review

Use a subagent for an independent second pair of eyes:

Skill(skill="superpowers:requesting-code-review")

Address any issues it raises before moving on.

5. Verify

All must pass before PR:

bun test              # unit tests — all green
bun run lint          # 0 errors (pre-existing warnings are OK)

6. Commit and push

Use a conventional commit message (feat:, fix:, chore:, docs:) that references the issue. Include BREAKING CHANGE: in the body for breaking changes.

git add <files>
git commit -m "fix: <description> (#<issue-number>)"
git push -u origin issues/<number>-<short-slug>

Do not include Co-Authored-By lines.

7. Open the PR to dev

The PR body is read by the automated reviewer agent — write it for them: clear summary, structured changes, explicit acceptance criteria.

gh pr create --base dev --title "<type>: <description> (#<issue-number>)" --body "$(cat <<'EOF'
<see format below>
EOF
)"

When gh pr create returns the PR URL, immediately proceed to step 8 and start the wait-for-review script. Don't pause to summarize the diff to the user, don't ask whether to wait — kick off the wait, then update the user (or end your turn) while the script runs in the background.

PR body format

Match the established style on existing PRs into dev (see #41, #42, #43, #44 for examples). Sections in order:

Closes #<issue-number>

## Summary

1–3 paragraphs. What's changing and why. Link the spec doc if there is one.

## What changes

The technical breakdown. For larger PRs, use `### Subsection` headings
(e.g., `### New X`, `### Modified Y`, `### Minor polish`). Paste short
representative code/yaml examples when they make a point faster than prose.

## Acceptance criteria

Copied from the triaged issue (or stated explicitly when narrow scope). Each
item is a checkable assertion the reviewer can verify against the diff:

- [ ] Behavior X works for input Y
- [ ] No regression in feature Z
- [ ] Public API surface updated for new export

## Test plan

What was verified locally:

- [x] `bun test` — N pass / 0 fail
- [x] `bun run lint` — 0 errors
- [x] Manual smoke test: `<command>` → `<expected output>`

## Spec reference (if applicable)

Link to the design doc, e.g., `docs/superpowers/specs/<file>.md`.

Be concrete. Paste short examples instead of describing them.

8. Hand off to babysit-pr

From here, drive the PR through review-feedback cycles to first pass reviewed. The wait-for-review loop, simple-vs-non-trivial branching on review feedback, and halt-at-first pass reviewed behavior all live in the babysit-pr skill. Invoke it with the PR number:

Skill(skill="babysit-pr")

Non-blocking feedback handling (not covered by babysit-pr): babysit-pr only addresses blocking items. For any non-blocking observations the reviewer surfaces (with either verdict):

• Fix on the spot if it's quick, low-risk, and clearly relevant to this PR's scope.
• File a follow-up issue if it's out of scope (different feature, separate refactor, broader discussion). The follow-up issue MUST reference this PR:

  gh issue create --title "<title>" --body "Spawned from #<pr>. <description>"
  

• When in doubt, ask the user.

STOP

Once babysit-pr reports first pass reviewed with no outstanding blocking items, your work is done. Do not merge — that's final-review's job (after its 4-minute soak window). Do not invoke any other skill. Report the PR URL and the final verdict to the user and stop.

Red Flags

• "I'll skip the subagent review, the change is small" → STOP, run it anyway
• "Tests fail but it's unrelated" → STOP, investigate
• "I'll merge and fix later" → STOP, you do not merge in this skill
• "I'll PR to main" → STOP, PRs target dev
• "I'll handle the review-feedback loop inline instead of using babysit-pr" → STOP, hand off