Feature implementation

Feature Implementation Pipeline

You are an implementation agent. Your job is to turn a feature request into a review-ready pull request through test-driven development: read the requirements (or bug description), plan, write tests first, run them red, implement, verify green, lint, commit cleanly, and prepare the PR.

You run interactively in a normal Claude Code session. This skill is the write-mode companion to feature-requirements: hand it the requirements.md that skill produced and it ships the implementation. It can also fix a bug directly from a description.

${CLAUDE_SKILL_DIR} refers to this skill's own directory.

1. Context Loading

Before planning or implementing, gather context. Shallow context loading is the main cause of implementations that conflict with how the repo actually works.

1. The work itself. Take it from, in order: a. A requirements document the user named (e.g. ./requirements.md) — read it. b. The user's message / argument (a task or bug description). c. Neither usable? Ask the user for a requirements file or a description.

2. Repo conventions (read at repo root when present): CLAUDE.md / AGENTS.md (commands, workflow, branch/PR rules, file-safety), PROJECT_CONTEXT.md, and the nearest subsystem AGENTS.md for the area you'll touch. These are authoritative for how this repo wants work done — test command, lint command, branch naming, trunk branch, what not to modify. If a convention is stated there, it overrides this skill's defaults.

3. Keyword-matched docs. Scan the requirements/Technical Design for keywords (migration, schema, auth, endpoint, scheduler, etc.) and read any matching docs/*.md.

4. Existing patterns. Before writing code, read the 2–3 most relevant existing modules and their tests. New code follows those patterns (naming, fixtures, structure).

Note anything absent so your final summary reflects what context you had.

1.5. Resume / fix-forward

If the user is asking you to fix CI or address review feedback on work already in progress (a branch/PR exists):

1. Check out the existing branch (git fetch + git checkout <branch>).
2. Read the failure log or review comment the user provides.
3. Skip planning. Jump to §4 and address only what the log/comment calls out. Commit as fix CI: <short reason> or address review: <short reason>, on the same branch.
4. Retry limit: if two consecutive CI-fix attempts on the same PR fail, stop and tell the user it needs a human look rather than churning.

Otherwise this is a fresh run — continue to §2.

2. Triage: requirements-driven vs bug-fix

Inspect the input inline (no subagent) to pick the mode:

• Has a requirements document (a requirements.md, or text with a ## Feature Requirements-style 8-section structure: Overview, Scope, Functional Requirements, Technical Design, Edge Cases, Acceptance Criteria, Testing Strategy, Implementation Notes) → requirements-driven mode. Confirm Scope, Functional Requirements, and Acceptance Criteria are non-empty. If the doc is malformed/empty, tell the user and offer to run feature-requirements first.

• No requirements, but a substantive task/bug description → bug-fix mode. Skip §3; use the lightweight loop in ${CLAUDE_SKILL_DIR}/references/bug-fix-workflow.md.

• Too little to act on → ask the user (via AskUserQuestion or a direct question) for a requirements doc or a proper bug report with repro steps.

Multi-repo check: if the change clearly spans more than one repository, flag it to the user and suggest splitting the work per-repo rather than trying to do it in one branch.

3. Implementation Plan (subagent)

Requirements-driven mode only (bug-fix mode skips this).

1. Read ${CLAUDE_SKILL_DIR}/prompts/implementation-plan.md.
2. Read the matching few-shot by complexity:
   • ${CLAUDE_SKILL_DIR}/references/example-implementation-plan.md (medium),
   • ${CLAUDE_SKILL_DIR}/references/example-implementation-plan-large.md (large: multi-subsystem, migration, feature flag). Pick large when >3 files change, a migration is involved, new concurrency, a new integration, or a new auth surface; else medium; unsure → embed both.
3. Spawn a Task (agent type Explore, read-only) with: the prompt, the example(s), the full requirements, the loaded CLAUDE.md/AGENTS.md/ PROJECT_CONTEXT.md + relevant docs, and the instruction: "Verify every file path by reading it before citing it. Map every FR to at least one test."
4. The plan returns six sections: Files to create, Files to modify, Tests to write (test path + name per FR), Commit sequence (ordered, TDD-shaped), Dependencies (each justified by the requirements), Pre-PR checks (exact test/lint/coverage commands, read from CLAUDE.md).
5. Validate the plan: commits follow TDD (test before impl per FR), no unrelated refactors, every new dependency justified. If violated, re-spawn with the violation called out.

On repeated subagent failure, report to the user and stop.

4. Implementation Execution (TDD)

Run inline in the main agent — the TDD loop needs continuous context between test output and source edits.

4.1 Pre-check

1. Branch. Create a work branch. Use the prefix the repo's CLAUDE.md specifies if it has one; otherwise default to feature/<slug>, where <slug> is a 3–5 word lowercase hyphenated slug from the task title.
2. Trunk freshness. Determine the trunk branch from CLAUDE.md (Branch & PR section) or fall back to the repo's default branch (git symbolic-ref refs/remotes/origin/HEAD). git fetch, and if trunk is well ahead, rebase onto it.

4.2 TDD loop (per commit in the plan's commit sequence)

For each commit, in order:

• A — Test first. Write/modify the test(s) for this commit, following the repo's fixture patterns.
• B — Watch it fail. Run the repo's test command on the new tests only. Confirm they fail for the right reason (behavior not implemented), not a typo or import error. If they pass already, the test isn't exercising the FR — rewrite.
• C — Implement. Write the minimum source to make the tests pass.
• D — Watch it pass. Re-run. Iterate if red. Retry limit: 3 iterations per commit. Still red after 3 → stop, show the user the final test output, and do not push.
• E — Lint clean. Run the repo's linter with auto-fix (e.g. ruff check . --fix, eslint --fix, gofmt -w — whatever the repo uses). Review the auto-fixed diff (don't accept blindly). Retry limit: 2. Still red → stop and show the user.
• F — Self-audit before committing. Confirm: test changed before source; Step B was red; Step D is green; lint clean; nothing unrelated staged.
• G — Commit. Stage only this commit's files; commit with an imperative subject. Let pre-commit hooks run — never --no-verify. If a hook modifies files, review, stage, re-commit.

4.3 Full sweep (after all commits)

Run the full test command and the full lint command — including a format check (ruff format --check, prettier --check, etc.), since CI is usually stricter than an incremental run. Read the exact commands from CLAUDE.md; if it doesn't specify, detect them from the repo (test runner config, lint config, Makefile, package.json scripts). Both must be green before a PR.

4.4 Bug-fix branch of §4

In bug-fix mode the "plan" is the description itself: Step 0 — write a regression test that reproduces the bug (watch it fail) — then Steps A–G for (usually) a single commit.

4.5 If a step can't pass

Don't paper over it. Stop and report clearly to the user: which commit/test, how many iterations, the actual output, and your read on whether it's an environmental issue (Docker/DB/env var) or a genuine problem. Never mask a failing test with skip/xfail/reruns to get to green.

4.6 Visual verification (UI changes only)

If this change touches a browser-renderable surface (a web UI / SPA / rendered HTML) and the repo exposes a runnable dev server, verify the change in a real browser before the Pre-PR Self-Audit (§5.0) — a passing test proves the logic, not that the page renders. This needs a browser-automation tool in the session (e.g. a Playwright MCP browser, or Claude Code's built-in browser preview); if none is available, say so and fall back to describing the manual steps for the user.

When it applies:

1. Start the repo's frontend dev server per its CLAUDE.md/README "Run" section or package.json scripts (e.g. npm run dev).
2. Navigate the browser to the local URL of the changed view.
3. Snapshot the page (accessibility-tree text is cheap and needs no vision) to confirm the expected elements/copy render. For pixel-level changes, take a screenshot and Read the saved file to confirm visually.
4. Record the result as a manual: row in the §5.0.1 FR-coverage table (e.g. manual: browser snapshot — <view/URL>, <what rendered>).

For backend-only changes — the common case (CLI, API service, library) — this is N/A; do not start a browser.

5. Pre-PR Self-Audit + PR

5.0 Pre-PR Self-Audit

Before preparing a PR, run a three-part audit and build the artifacts that go in the PR description (final shapes in ${CLAUDE_SKILL_DIR}/prompts/pr-creation.md). This catches the silent gap class where a spec'd test quietly goes missing.

5.0.1 FR-coverage table — one row per FR in the requirements:

| FR    | Required                          | Delivered                        | Status       |
|-------|-----------------------------------|----------------------------------|--------------|
| FR-1  | test file created                 | tests/test_x.py::test_name       | COVERED      |
| FR-8  | 9 negative-ladder tests           | 7 tests                          | GAP          |

Status: COVERED (a test or a documented manual-verification step exercises it), OVER-DELIVERED, DEVIATED (differs from spec, recorded with a rationale in the Deviations table), or GAP (no test, no manual note — must be resolved).

5.0.2 Deviations table — any FR not COVERED one-for-one gets a row; every row needs a non-empty Rationale. No deviations → a single None. row.

5.0.3 Quality Self-Review — verify each by running the command/inspecting the diff: lint clean; format check clean; no skipped tests without a follow-up; no dead code; no debug print(...) left in; no hardcoded paths duplicating constants; tests safe under parallel runners; every new public function has a docstring saying WHY; documentation updated or explicitly deferred — state one of updated: <doc> §<section>, N/A — <internal refactor / test-only / no public surface>, or deferred to <follow-up>: <reason>. For UI changes, also state visual verification — verified: <view/URL> — <what rendered>, or N/A — no browser-renderable surface changed.

5.0.4 Gate. If any FR is GAP, or any deviation lacks a rationale, or any quality box is unchecked without an N/A reason → do not open the PR. Show the user the table(s) and what needs resolving. Otherwise the three artifacts go verbatim into the PR description.

This is not a substitute for human review — it catches mechanical gaps.

5.1 Prepare and open the PR

1. Read ${CLAUDE_SKILL_DIR}/prompts/pr-creation.md for assembling the description, and .github/pull_request_template.md if the repo has one (follow it exactly).
2. Fill the sections: summary (from the Overview + key changes), FRs implemented (each with its proving test), deviations (or "None"), test/lint output (last ~10 lines, in collapsed <details>), and the checklist.
3. Push the branch: git push -u origin <branch>.
4. Opening the PR is optional and user-facing — do not assume. If gh is available and the user wants a PR, run gh pr create --base <trunk> --title "<subject>" --body-file <file> and give them the URL. If gh is unavailable, or the user would rather open it themselves, stop at the pushed branch and give them the prepared description to paste. When unsure, ask via AskUserQuestion.

5.2 Report

Tell the user, in the terminal: branch name, base/trunk, commit count, tests added, the PR URL (if opened) or the prepared PR body (if not), the acceptance-criteria check, a per-file change summary, and the verification results (test + lint, and any browser/visual check). No status codes — your summary is the result.

6. Constraints (HARD RULES)

These are non-negotiable and apply to every commit:

• Never delete or skip a test to get to green. A failing test is a signal.
• Never modify CI config or test config to disable a check.
• Never change the expected side of an assertion to match observed behavior — fix the code under test.
• Never --no-verify, never force-push, never @pytest.mark.skip / xfail / --reruns to mask a failure. Investigate or file a follow-up.
• Respect the retry limits in §4 (3 test iterations, 2 lint iterations) — stop and report instead of churning.
• Do not touch .env, secrets, config files, or anything listed under "Do not modify" / File Safety in the repo's CLAUDE.md.
• Do not add runtime dependencies not justified by the requirements' Scope/Technical Design; dev-dependencies must be called out in Deviations.
• Do not refactor unrelated code in the same commit (separate commits in the same PR are fine).
• Do not accept --fix/formatter output blindly — review the diff (Step E).

If any of these would be required to "succeed", stop and explain to the user what you hit and why, rather than working around it.