Issue Slayer

Issue Slayer

Run a complete Issue → PR flow inside an isolated git worktree.

Execution Mode

Pattern A (Standalone): Present a plan for user approval before writing code. User drives cleanup decisions.

Pattern B (Team Member): Send plans to the Team Lead for approval before writing code. Cleanup requires Lead instruction.

Detection: see ENV.md for how to detect team context in your tool.

Issue Selection

Eligibility — ALL must be true:

1. Has agent:ready label
2. State is open
3. Not assigned (no:assignee)
4. Does NOT have pending label

Priority: bug > enhancement, then p0 > p1 > p2 > p3 (no label = p2), then lowest issue number.

Never pick without agent:ready. Never pick an assigned issue. One agent, one issue — unless working a Bundle PR (see ../reading-guild-rules/SKILL.md).

gh issue list --label "agent:ready" \
  --search "no:assignee state:open -label:pending" \
  --json number,title,labels --limit 20

If the user specifies an issue number, verify eligibility before proceeding.

Pattern A: Present the ranked list and let the user choose. Pattern B: Check what teammates have claimed via task list. Pick the highest-priority unclaimed issue, or use the one assigned to you.

Claim immediately after selection:

gh issue edit <N> --add-assignee "@me"
gh issue comment <N> --body "Starting work.
Agent: **<agent-name>** | Model: **<model-name>** | Tool: **<tool-name>**"

If assignment fails (race condition):

1. Pattern A: Pick the next highest-priority eligible issue.
2. Pattern B: Re-check the task list for teammate claims, then pick the next unclaimed issue. Notify the Team Lead of the conflict via SendMessage. If all remaining issues are claimed, report back to the Lead and stop.

Worktree Setup

See WORKTREE.md for the full setup procedure. Summary:

git fetch origin main
git worktree add .agent-worktrees/<type>-issue-<N>-<desc> \
  -b <type>/issue-<N>-<desc> origin/main

If the path already exists, abort and ask the user. Do all subsequent work inside the worktree.

Design

Read the issue, relevant source files, and the project's development documentation (CLAUDE.md, CONTRIBUTING.md, etc.).

Pattern A: Present the implementation plan and wait for approval before writing code. Pattern B: Send the plan to the Lead and wait for approval.

Do not create an implementation_plan.md file — plans belong in conversation context or plan mode, not as file artifacts in the repository (whether committed or not).

Implementation

• Follow the project's coding standards and conventions.
• Co-author trailer: see Commit & PR Conventions in ../reading-guild-rules/SKILL.md.
• Pattern B: Minimize changes to files that the project identifies as conflict-prone.

Doc updates (part of implementation, not a separate step): Update project documentation to reflect your changes — READMEs, architecture docs, config examples, and contributing guides as appropriate.

Verification

See VERIFY.md for the quality gate. All project checks must pass before pushing.

Self-Review

After verification passes and before opening the PR, review your own changes to catch issues that automated checks miss.

See SELF-REVIEW.md for the full procedure.

Pull Request

Write the PR body to a temp file to avoid shell-escaping issues.

git fetch origin main
git rebase origin/main
git push -u origin HEAD
gh pr create --title "<type>: <description>" --body-file /tmp/pr_body_<N>.md

PR body should include: Closes #<N>, overview, changes, and testing status.

Bundle PR: Allowed only when ALL: same fix pattern, each issue is small complexity, no file conflicts, and total diff is reviewable as a single unit. One commit per issue (Ref #<N>), single worktree, PR body lists all Closes #<N>. See ../reading-guild-rules/SKILL.md for full details.

Do not merge. Notify the approver that the PR is ready.

Cleanup (On Request)

When instructed after the PR is merged:

git worktree remove .agent-worktrees/<type>-issue-<N>-<desc>
git branch -d <type>/issue-<N>-<desc>

Pattern B: wait for Lead instruction before removing anything.

Cleanup on Failure

If implementation fails or is abandoned, clean up the worktree to prevent .agent-worktrees/ from accumulating stale directories.

Pattern A: clean up immediately:

# Force-remove the worktree (handles uncommitted changes)
git worktree remove --force .agent-worktrees/<type>-issue-<N>-<desc>
# Delete the local branch
git branch -D <type>/issue-<N>-<desc>
# Unassign yourself from the issue
gh issue edit <N> --remove-assignee "@me"

Pattern B: notify the Team Lead of the failure reason and wait for Lead instruction before removing anything — same as normal cleanup.

Team Operation Flow

1. Lead: create team → create tasks (per issue) → spawn issue-slayer agents
2. Each agent: claim → plan → Lead approval → implement → verify → self-review → PR
3. Lead: coordinate merge order → rebase if needed → shut down → delete team