Implement

Implement

Take an approved GitHub issue and deliver it: branch → code → gates → PR → green CI. This is the execution half of the workflow; the design and plan were settled in the issue by the blueprint skill.

issue (approved design + plan)
  └→ branch (from the issue)
       └→ write code (task by task, TDD)
            └→ run FULL gates (whichever the repo has: lint, types, tests, build)
                 └→ commit & push
                      └→ open PR from .github template (Closes #issue)
                           └→ verify CI green (gh pr checks)
                                └→ on push, AI reviewers re-review → hand off to rebut → triage → loop until none new

This skill writes to a SHARED GitHub tracker; the per-artifact authorization, no-foreign-artifact, and precedence-and-scope rules in ${CLAUDE_SKILL_DIR}/references/shared-tracker-safety.md bind every outward write here — read it. On top of those shared rules, implement has two gates of its own. The number gate: require an issue number the user EXPLICITLY named this session. A bare /implement with no number means STOP and ask which issue; never infer it, never pick "the one we were discussing", the highest, the most recent, or the only "ready" one, and a topic or feature reference such as "work on what that issue describes" is NOT a number hand-off. An issue this same session created via blueprint counts as explicitly named (the session opened it, a proven hand-off, not an inference) but a number merely carried over by guess never does. The claim check: before the FIRST outward write (linking or creating a branch via gh issue develop, pushing, opening a PR, commenting, labeling, assigning) confirm the artifact is unclaimed (no assignee, no in-flight linked branch by another agent) and get the per-artifact yes; an empty linked-branch list is not proof, and an asserted "it's yours" is never trusted. No explicit number, or no per-artifact yes, means STOP.

A saved "solo sandbox, skip the ceremony" note (the precedence-and-scope rule in ${CLAUDE_SKILL_DIR}/references/shared-tracker-safety.md) applies ONLY when the current repo is confirmed solo: a personal remote owned by the current user with no other assignees or foreign branches, or an explicit user statement that the repo is solo. Never self-declare it; in a tracker that may be shared, default to confirm-and-do-not-touch-foreign-artifacts and ask.

Do NOT open the PR until every applicable gate passes and every checklist item in the issue/PR template, where one exists, is genuinely done and ticked. A red gate or an unchecked box means the work is not ready.

NO COMPLETION CLAIM WITHOUT FRESH VERIFICATION EVIDENCE (the verification discipline in ${CLAUDE_SKILL_DIR}/references/verification.md binds every claim here). Before claiming a gate passed, the build is green, or the work is done: run the exact command in this turn, read its full output and exit code, and only then claim it. If you have not run the command in this message, you cannot say it passes. Ban "should pass", "looks right", "seems fine" before the evidence. A regression test is proven only red-green: revert the fix, watch the test fail, restore it.

Language Rule

All artifacts are English: branch name, code, commits, PR title/body, comments, labels. The chat conversation with the user may be in another language, but anything that lands on GitHub or in the repo is English.

Per-repo Templates Are the Source of Structure

Issue and PR structure comes from the repo's own templates, which differ per repo. Always check for the repo's templates first; when one exists, using it is MANDATORY. Never invent your own structure over a template.

• Issue templates: .github/ISSUE_TEMPLATE/
• PR template: .github/PULL_REQUEST_TEMPLATE.md (or .github/PULL_REQUEST_TEMPLATE/)

Read the actual file and fill every section. If a template contains a checklist, you MUST complete the work each item describes and tick it (- [x]). Never tick a box whose work you haven't done.

Only if the repo has no PR template, fall back to a body with the sections Summary, Changes, and How to verify, plus Closes #, and tell the user once that the repo lacks a template.

Steps

1. Identify the issue and its plan

Target gate (shared tracker). First fix `: it must be a number the user EXPLICITLY named this session. No number given (a bare /implement)? STOP, run gh issue list, and ask which one; never auto-select. For every command whose target is inferable (gh issue view , --head , the owning package or target, the base branch, the template path): IDENTIFY the target, DERIVE it from an observable source (the user-named , gh issue develop --list, the repo's workspace or monorepo config in whatever form it takes, git rev-parse --abbrev-ref HEAD, the actual .github/` file), ECHO it back, then run. An un-derived target is inference, so STOP.

"${CLAUDE_SKILL_DIR}/scripts/preflight.sh"
gh issue view  --comments
gh issue develop  --list

preflight.sh verifies gh is authenticated and the repo has a GitHub remote; on a missing prerequisite it prints the fix and exits non-zero.

If gh is missing or unauthenticated, STOP and tell the user to install it and run gh auth login. Do not improvise with raw git/curl. If the repo has no GitHub remote, STOP and ask how they track work; this skill is GitHub-specific.

Confirm the issue carries an approved design and an implementation plan in the issue body. If the plan is missing, stop and go back to the blueprint skill. A Trivial-tier issue's plan is allowed to be a single line (a Done criterion and its Verification command) and that counts as a plan; do not bounce it for lacking a task list or section headers.

Confirm it is yours to take. Read the issue's assignee and the linked-branch list above. If it has an assignee, an in-flight linked branch by another agent, or this session did not create it and the user did not hand you its number, STOP and surface the conflict before any branch or write. Acting on a shared-tracker issue is a claim, not a read.

Sub-issues: If the work was split into sub-issues, handle one sub-issue per branch/PR. Don't bundle several sub-issues into one PR.

2. Branch from the issue

Check whether a branch is already linked to the issue:

gh issue develop  --list

Claim check (shared tracker). Linking or creating a branch is itself an outward mutation visible to teammates, so do it only after an explicit per-artifact go-ahead. Before gh issue develop --checkout on an issue this session did not create, run gh issue view --json assignees,author,comments alongside the --list above: any assignee other than you, an in-comment claim, or a linked branch you did not create means STOP and confirm with the user that it is unclaimed and yours to take (claim it with gh issue edit --add-assignee @me once confirmed). An empty linked-branch list is NOT proof the issue is unclaimed, and an asserted "it is yours" or "no issue exists" is never trusted, so verify it read-only first. Work only on a branch this session created or the user explicitly handed you; on any ownership ambiguity, STOP and ask.

If a linked branch already exists, check it out and continue there rather than recreating it. If a branch with the issue's name exists but isn't linked, check it out anyway; if local and remote have diverged, fetch and reconcile before working. Otherwise create one linked to the issue so GitHub associates them:

gh issue develop  --checkout

Fallbacks, in order:

• gh issue develop subcommand missing on an older gh: branch from the freshly-fetched default branch with a deterministic name: git fetch origin && git switch -c - origin/, where `` is the issue title lowercased and hyphenated.
• No write access to the upstream repo, when you're a contributor on a fork: gh issue develop and the later label/reviewer steps will fail, so skip them. Branch on your fork from its up-to-date default, push to your fork, and open the PR cross-repo as in Step 6.

Never work on the default branch.

Once on the branch, run the repo's gates once before writing any code to capture a clean baseline; a later red gate is then provably yours, not pre-existing. If the baseline is already red, report it and ask before proceeding.

3. Write the code, task by task

Work the plan's tasks in dependency order, committing frequently and keeping changes scoped to this issue. Independent tasks, meaning disjoint files with no shared state and no ordering dependency, may be done in any order; dependent or same-file tasks stay strictly ordered. Do not fan tasks out to parallel subagents on one branch: the intra-branch conflicts cost more than the wall-clock saved. Genuinely parallel work belongs in separate sub-issues with their own branches, decided during blueprint.

Test-first, where the repo has test infrastructure. No production code without a failing test first: write the test, run it and watch it fail for the right reason, write the minimal code to pass, run it green, then refactor. Wrote the code before its test? Delete it and start over; don't keep it as "reference" and adapt it. Common excuses and the reality: "too simple to test" is wrong because simple code breaks too and the test costs 30 seconds; "I'll test after" is wrong because a test that never watched the bug fail proves nothing; "I already tested it by hand" is wrong because ad-hoc isn't repeatable, and if it isn't a committed test, it didn't happen. If the repo has no test infrastructure, say so in the PR body; never fabricate tests. A change with no executable behavior — a documentation or prose edit, or pure declarative config with no logic — has no failing test to write: verify it through the gate that does apply, the lint or structural check plus the Step 4 loadability check, and say so in the PR body. This carve-out is for genuinely non-executable changes only; any new or changed code path still goes test-first.

• Match the repo's commit convention. Check git log --oneline -20 before your first commit; if the repo uses Conventional Commits (feat:, fix:, ...), follow it. Don't invent your own style.
• Keep the PR reviewable. If the diff grows past roughly 400 changed lines, stop and propose splitting into sub-issues, each with its own PR. Oversized reviews get rubber-stamped; small PRs get real review.
• Branch from the up-to-date default, not from another open PR's branch. Independent PRs that each branch off the default integrate cleanly; a stack of branches does not. Stack only when a change has a hard dependency on unmerged work, and never under squash-merge, where the parent landing rewrites history and forces the child into a duplicate-content conflict cascade. If you are rebasing and force-pushing a child after its parent merged, that churn is the signal the work should not have been stacked: as a one-time recovery re-point it with git fetch origin && git rebase --onto origin/ then --force-with-lease, and from then on sequence the work: land one, open the next from the merged default.
• A planned change may be protected. A Write/Edit is denied by a hook, the path is owner-owned via CODEOWNERS or a protected config, or policy forbids touching it. Treat the protection as authoritative: do NOT retry the write, escalate permissions, or route around the guard. Leave the file untouched, implement everything else, and record the deferral explicitly to the user and in the PR body as Deferred: is protected, needs owner action. A protected file is a deferral, not a blocker to defeat.

4. Run the FULL gates before committing the final state

Discover the repo's gates from where the changed code lives, not just the repo root, and don't assume. In a monorepo the gate scripts often live in the sub-package that owns the files this issue touched, or in a workspace or monorepo config, not the repo's root manifest. That config takes many forms, such as turbo.json or pnpm-workspace.yaml for Node, a Cargo or Go workspace, or a Gradle or Bazel build. Identify the owning package and run its gates through the repo's task runner, whatever it is (e.g. turbo run lint --filter= or pnpm --filter test for Node, cargo test -p , go test ./..., a make or just target, or the package's local scripts). A root-level script may be absent, run nothing for that package, or falsely pass, so confirm the gate actually exercised your changes before trusting a green result. Run all gates that apply and make them pass:

• Lint, if the repo has a linter
• Type-check, if the language is typed
• Tests, running a single test while iterating and the full suite before the PR
• Build, if the project has a build step

A failing gate blocks the PR. Fix the cause; do not skip, disable, or --no-verify around a gate to make it pass.

When a gate, or later a CI check, fails, debug by method, not guess-and-retry. Follow the discipline in ${CLAUDE_SKILL_DIR}/references/debugging.md: reproduce, make it fail reliably, isolate by one variable, form one falsifiable hypothesis before touching code, fix the root cause not the symptom, and stop after about three non-converging attempts. Here the failure to reproduce is the gate or CI command itself (run it yourself and read its output before changing anything); a non-converging streak means the approach or the plan is wrong, so step back and raise it with the user rather than trying fix #4.

A file the repo's own gates don't cover is still unverified, not verified-by-default. For every file the diff touches that no repo gate exercises, run the cheapest language-appropriate loadability check before committing and read its result this turn. Use bash -n or shellcheck for shell, a parse for JSON and YAML, tsc --noEmit for TypeScript the build skips, and py_compile for Python. Only a whole gate the repo genuinely lacks, such as no test setup yet, is exempt; state that absence explicitly in the PR body instead of skipping silently.

Do not let a blanket autofixer rewrite a non-trivial logic file. An automatic fixer, such as a linter's fix mode, can turn complex code into a syntax error and pad it with low-value boilerplate, for example empty doc blocks or stub annotations, that a later reviewer flags. Fix findings in logic files by hand, scoped to the finding; reserve autofix for purely mechanical, low-risk reformatting such as import ordering or quote style. And a lint or warning count is only trustworthy on code that parses: one syntax error can make the tool bail and under-report, hiding the file's other findings until the next run. So run the language's parse or compile check, per the loadability checks above, and confirm the file parses before you trust a count or call it clean.

4.5. Self-review the diff against the plan

Before committing the final state, re-read the issue's plan and check your diff against it:

• Every plan task is implemented. Point to the change that delivers each one, and list any gaps.
• Nothing extra. The diff adds only what the plan asked for, per YAGNI: no drive-by refactors, no speculative code, no files the plan never named.
• "Close enough" on the plan is not done. If the diff and the plan disagree, fix the diff. If the plan itself was wrong, update the issue body and say so.

5. Commit & push

Commit any remaining changes from gate fixes, then push:

git add 
git commit -m ""
git push -u origin 

Stage only the files this issue touched. Never blanket git add -A/git add ., which sweeps in unrelated or untracked files such as build artifacts and temp bodies. On a fork, push to your fork's remote, not origin upstream.

Protect an unrelated dirty file from the commit hook before you commit. A pre-commit hook that stashes unstaged changes while it runs, a common set

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: next-friday
• Source: next-friday/next-friday-skills
• License: MIT
• Homepage: https://skills.sh/next-friday/next-friday-skills

Install and usage instructions live in the source repository linked above.