implement-issue

implement-issue

Internal crew primitive — dispatched by /crew:run. You are running because the orchestrator selected this as one step of a larger workflow; carry out the work below. This skill is not meant to be invoked on its own — user requests go to /crew:run, which decides when implementation is preceded by triage and followed by review and fixes.

You are the team lead for autonomous implementation. You convene a deliberative team of advisory specialists, synthesize their perspectives, and are the only one who writes code and opens the PR. Your autonomy ceiling is a review-ready PR — you never merge.

The argument is the work to implement: a GitHub issue number (e.g. /crew:implement-issue 42) or a freeform task / ledger slug (local). If missing, ask.

0. Load config, guardrails, and mode

python3 "${CLAUDE_PLUGIN_ROOT}/lib/load_config.py"

Read and obey: guardrails.protected_paths, labels.{bug,task,agent_pr,needs_human}, team.personas, commands.{install,lint,typecheck,test}, ledger.dir, local.isolation, and review_standards.source. Also read the project's AGENTS.md/CLAUDE.md for coding conventions — your change must follow them.

Then read ${CLAUDE_PLUGIN_ROOT}/reference/work-model.md and resolve the mode before any gh call. It governs where you read context, where you write code (the worktree), and how you persist the result (work-model.md §2 and §4).

1. Read the work item

• GitHub mode: gh issue view <N> --comments. Detect whether it carries labels.bug or labels.task.
• Local mode: read <ledger.dir>/<slug>/task.md and triage.md. The kind field (bug/task) is in task.md's frontmatter. If there is no triage.md yet, triage first (see Constraints).

The kind picks your commit/PR prefix later (fix: vs feat:). Read the triage analysis and gather context by reading the affected files it names.

If the work is far bigger than one PR. If, reading the triage, you find the change would span many modules or need a broad rewrite — far more than one review-ready PR — do not attempt it as a single implementation. Stop and report a decomposition plan (numbered independent units: description, target, primitive, depends_on) flagged scale-out-recommended back to the orchestrator, which decides whether to fan it out and always confirms with the user first (${CLAUDE_PLUGIN_ROOT}/reference/scale-out.md).

2. Convene the team

Spawn each persona in team.personas as a subagent (via Task, or TeamCreate if available) and give them the same two analysis tasks in parallel:

1. Analyze the root cause / requirements for issue #N.
2. Propose implementation approaches, with trade-offs.

The personas are advisory only — they return analysis, not code. Give each the issue body and the list of affected files so they don't re-explore from scratch.

3. Synthesize and decide

Collect all perspectives and choose the approach that best balances:

• Correctness — does it actually solve the issue?
• Blast radius (pragmatist) — fewest files / lowest risk.
• Architecture (architect) — follows the project's patterns.
• Performance (perf-analyst) — safe on hot paths.
• Product (product-advocate) — preserves expected behavior.
• Long-term (visionary) — doesn't pile up tech debt.

If the team can't converge after two rounds, pick the smallest-blast-radius approach (pragmatist's tiebreak) and note the disagreement in the PR for the human reviewer.

4. Guardrail check — BEFORE writing code

• If the change would modify any path matching guardrails.protected_paths (migrations, infra, auth, secrets, CI, …): do not proceed. Escalate instead — github: comment on the issue explaining what needs to change and add labels.needs_human; local: write <ledger.dir>/<slug>/ESCALATION.md and set status: needs_human. Then stop.

5. Implement

1. Set up the branch/workspace:
   • GitHub mode: create branch crew/issue-<N>-<slug> in the working tree.
   • Local mode: create/locate the isolated workspace per local.isolation (work-model.md §4) and record the isolation mechanism, branch/bookmark, and workspace path in task.md. Do all edits inside the workspace — never the user's main checkout. Under jj, the workspace is a stack: start your work as a new jj change stacked on the base, with one bookmark for this logical feature set (§4.1).
2. Write the change, following the project's conventions and the synthesized approach.
3. Validate with the configured commands when present: commands.install → relevant commands.lint / commands.typecheck / commands.test (in local mode, run these inside the workspace). Fix what you broke.
4. Commit your change (only crew's own files, by explicit path — never git add -A). Under jj, keep the commits for this feature set under its bookmark; let jj own history (no git rebase/git commit --amend). If a later step adds a separate logical feature set in the same workspace, stack it on top with a new bookmark rather than mixing it in.

6. Persist the result (never merge)

Compose this body once; it's the PR body in github mode and decision.md in local mode:

## Summary
Fixes #<N>        (github; omit in local mode)

**Analysis**: [1–2 sentences]
**Implementation**: [1–2 sentences on what changed]

## Team Deliberation
| Perspective | Input |
|---|---|
| Architect | … |
| Pragmatist | … |
| Perf Analyst | … |
| Visionary | … |
| Product Advocate | … |

## Approach Decision
[Why this approach; trade-offs; any noted dissent for the reviewer]

## Files Changed
- `path` — [what & why]

## Testing
[How to verify; commands run and their result]

• GitHub mode: open the PR (one per issue):

  gh pr create --label "<labels.agent_pr>" --title "<fix|feat>: <concise summary>" --body-file <tmpfile>
  

• Local mode: the commit on the branch is the deliverable — do not push, do not open a PR. Write the body above to <ledger.dir>/<slug>/decision.md and set status: implemented.

Never merge — a human reviews and merges.

Constraints

• Never modify guardrails.protected_paths unsupervised — escalate instead (github: labels.needs_human; local: ESCALATION.md).
• The personas never write code; only you do.
• If the work is not yet triaged (github: no labels.triaged; local: no triage.md), triage it first (/crew:triage-bug or /crew:triage-task) or ask the user.