implement-issue

Implement Issue

End-to-end GitHub issue delivery via team-executor. Robust solutions preferred over fast ones — human time/speed/estimate constraints do not apply to execution agents; risk and consistency do.

Bundled Resources

File	Purpose
references/workflow.md	Detailed step-by-step workflow and edge cases
references/team-composition.md	How to pick planning agents and skill assignments based on project stack

Inputs

A GitHub issue number (bare integer → current repo), an owner/repo#N slug, or a full https://github.com/.../issues/N URL.
Optional flag in user message: "decide" / "make all decisions" / "no confirmation" → skip the TL;DR confirmation gate and choose the most robust, convention-consistent approach autonomously.

Outputs

Feature branch named issue-<N>-<slug> (or matching the repo's branch convention if one is detected).
Plan documents under docs/plans/issue-<N>/ (from team-executor).
A comment on the issue documenting the agreed implementation approach in enough detail that a fresh team can follow it.
Implementation commits on the feature branch.
A pull request linked to the issue (Closes #N).

Workflow

0. Precondition: `team-executor` must be installed

Before any other step, verify team-executor is reachable. Check, in order:

~/.claude/skills/team-executor/SKILL.md
.claude/skills/team-executor/SKILL.md (project)
./team-executor/SKILL.md (this repo, when running in-place)
/mnt/skills/team-executor/SKILL.md
skills-lock.json entry for team-executor

If none found: stop and warn the user. Report which paths were checked and that this skill drives team-executor for planning + execution. Ask whether to:

(a) install it (npx skills add thatjuan/agent-skills --skill team-executor) and continue, or
(b) abort.

Wait for explicit confirmation. Do not proceed without it. Cache the resolved path for later steps.

1. Resolve the issue

Parse the user's input. If it's a bare integer, treat it as an issue number in the current repo.
Run gh issue view <N> --json number,title,state,body,labels,assignees,milestone,url,author,comments and read everything, including comments — prior discussion may already constrain the approach.
If state != "OPEN":
- Report the current state (closed / merged / locked) to the user.
- Ask whether to (a) reopen, (b) proceed anyway on a new branch, or (c) abort. Wait for their choice.
Detect repo conventions: read CLAUDE.md, AGENTS.md, CONTRIBUTING.md, branch-naming hints from recent branches (git branch -a --sort=-committerdate | head -20), commit-message style from git log --oneline -20.

2. Create the feature branch

Branch from the repo's default branch (resolve via gh repo view --json defaultBranchRef -q .defaultBranchRef.name).
Branch name: issue-<N>-<kebab-title> truncated to 60 chars, unless the repo's convention dictates otherwise.
git fetch origin first; create the branch off origin/<default>.

3. Determine the implementation path

The issue states what. This skill (with team-executor) decides how — unless the issue body explicitly prescribes the implementation.

If the issue contains explicit implementation directions (specific files, APIs, code patterns, or a checklist a coder could follow verbatim):

Skip the planning team. Use the issue body as the plan. Proceed to step 5.

Otherwise: dispatch a planning team via team-executor.

Read the team-executor skill: ~/.claude/skills/team-executor/SKILL.md (or ./team-executor/SKILL.md if installed in-project).
Follow team-executor Phase 1 (Planning) — Steps 1–8 — with the issue body + comments as input to "Organize the Input".
See references/team-composition.md for how to pick agents and skill assignments for this project's stack.

Every architect, coding, and review agent spawned via team-executor for this issue is assigned the software-engineer skill — the base engineering layer. That holds the implementation to its architect/developer/reviewer bar (the Three Lenses) and its Eight Standards, regardless of which stack/SDK skill (if any) overlays on top. See references/team-composition.md for the exact skill-to-agent mapping.

Constraints to pass into every planning agent prompt:

The implementation will be carried out by other coding agents. Human time, speed, and effort estimates DO NOT apply — do not shy away from a more robust solution because a human would find it slow. Account for risk, security, maintainability, and consistency with existing project conventions. Prefer the most robust, well-engineered option that uses existing tooling/styles/components in this repo. Do not introduce parallel patterns when an existing one fits.

4. Confirm the path (or decide autonomously)

If the user's invocation asked you to decide ("decide", "make all decisions", "no confirmation", "autonomous"), skip confirmation. Pick the most robust, convention-consistent option from the planning output and proceed.
Otherwise, present a very summarized TL;DR to the user: 3–6 bullets covering chosen approach, key trade-offs, affected areas, and risks. Wait for confirmation or redirection.
After confirmation (or autonomous decision), write the final plan to docs/plans/issue-<N>/execution-plan.md per team-executor Step 8.

5. Comment the approach on the issue

Post a comment via gh issue comment <N> --body-file <path> containing:

Approach — chosen path in 1–2 paragraphs.
Why this path — trade-offs vs. alternatives considered.
Scope — files/modules touched, new files, migrations.
Steps — ordered, detailed enough that a fresh team can execute without ambiguity (file paths, function signatures, library calls, test expectations).
Out of scope — what this PR will not address.
Verification — how reviewers should validate (commands to run, manual checks).

This comment is the durable execution brief. It must stand alone.

6. Execute

Launch team-executor Phase 2 (Execution) — Steps 9–12 — pointing agents at:

The issue (gh issue view <N>) for original requirements.
The posted issue comment / docs/plans/issue-<N>/execution-plan.md for the chosen approach.
Project context (CLAUDE.md, AGENTS.md, README, relevant source files).

Execution agents run autonomously, in parallel where steps are independent, sequentially where dependent.

7. Verify

Run the repo's test suite, linter, type-checker, and build (whatever exists). Detect via package.json scripts, Makefile, pyproject.toml, etc.
For UI changes: start the dev server and exercise the feature; report explicitly if browser verification was not possible.
Fix failures via targeted follow-up agents before opening the PR.

8. Open the pull request

Commit and push the feature branch.
gh pr create with:
- Title: short, ≤70 chars, matching the repo's commit-message convention.
- Body sections: Summary (bullets), Approach (link to issue comment), Test plan (checklist), Closes #.
Return the PR URL to the user.

Failure Modes

Condition	Response
`team-executor` not installed	Stop. Warn the user, show paths checked, offer install command, wait for confirm.
Issue not found / no access	Surface the `gh` error verbatim; ask the user to verify the number / auth.
Issue closed/locked	Confirm intent with user before proceeding (see step 1).
`gh` not installed or not authenticated	Stop; instruct the user to install / `gh auth login`.
Not inside a git repo	Stop; report and ask the user where to run.
Planning team produces conflicting recommendations the Project Lead can't reconcile	Surface the conflict in the TL;DR; ask the user to break the tie.
Tests fail after execution	Spawn a targeted fix agent; never open a PR with failing CI-blocking checks.
Pre-existing uncommitted changes on the working tree	Stop; ask the user how to handle (stash / commit / abort).

Related Skills

software-engineer — the engineering SME (architect/developer/reviewer lenses, the base engineering layer) that every coding/architect/review agent is assigned. Stack/SDK skills overlay on top of it.
team-executor — the planning + execution engine this skill drives.
commitpush — for the commit step if the user prefers its safety checks.
git-github-cli — Git/GitHub CLI reference for branch and PR operations.