implementer

name	implementer
description	Execute implementation plans by systematically completing each task with verification, bounded retry, and progress tracking

Implementer Skill

Purpose

This skill fills the workflow gap between plan creation and PR generation. It takes a plan file produced by the plan-generator skill and executes every Low-Level Task systematically -- producing working code on the first pass.

Plan Ingestion

A plan file MUST be explicitly provided by the user. Do NOT auto-discover or assume a plan.

1. If $ARGUMENTS contains a file path, use that. Otherwise, ask the user.
2. Read the plan file completely.
3. Extract tasks from "Low-Level Tasks" if present; for non-standard formats (analysis reports, recommendation docs), explicitly list inferred tasks and re-order by structural dependency when targeting the same file. If ambiguous, ask the user.
4. For each task, identify: target files, functions, implementation details, verification commands.
5. Classify status: Completed ([COMPLETED]), In progress ([IN PROGRESS]), or Pending (no marker).
6. Enumerate all tasks and their statuses. Track progress by updating task markers in the plan file.
7. Read all files in the "Beginning context" section (or infer from task descriptions).
8. Use the plan as a guide, not a strict contract, deviations can be made to achieve the overall goal but must be documented and approved by the user

Resuming Partially Completed Plans

If any tasks are marked completed or in progress, this is a resume:

• Verify completed tasks -- read target files and confirm changes exist. Re-mark as pending if missing.
• Resume in-progress tasks -- continue from where they left off, don't restart.
• Run a baseline check -- build and test to confirm a working state. Report failures before continuing.
• Report resume status to the user: tasks verified, tasks to resume, tasks remaining.

Pre-Implementation Setup

1. Branch check: Verify you are NOT on main. If on main, propose a branch name without prompting for confirmation. If the GitHub stack extension is available (command -v gh >/dev/null 2>&1 && gh stack --version >/dev/null 2>&1), preconfigure git config rerere.enabled true to avoid an interactive prompt, then create the bottom stack layer with gh stack init --base main <branch_name>. Otherwise, create the branch with git checkout -b <branch_name>. ALWAYS pass the branch name to gh stack init; never invoke its interactive form.
2. Baseline check: Run the project's build/test command. If NOT green, STOP and report the exact failing gates or tests. Continue only after the user explicitly accepts them as the baseline; record the exact failure set as the baseline regression contract.
3. Context loading: Read all files in "Beginning context". Verify each exists (or note as expected-missing for CREATE tasks).

BRANCH NAME TEMPLATE: <github-username>/<feat|fix|chore>_<short-description>

Execution Loop

For each Low-Level Task, in order:

Step 1: Parse

• Read the task description from the plan
• Identify: target files, functions to create/update, specific details
• Track progress by marking the task as [IN PROGRESS] in the plan file

Step 2: Context

• Read all files referenced by the task
• If files don't exist yet (CREATE tasks), verify parent directory exists
• If files exist (UPDATE tasks), read current content completely
• Understand the current state before making changes

Step 3: Implement

Make the code changes described in the task. Follow the DOING/EXPECT pattern from the Agent Protocol.

Guidelines:

• Prefer the Edit tool over Write for existing files
• Prefer editing existing files over creating new ones
• Follow the project's coding standards (from the plan's Implementation Notes)
• Follow the plan's specific instructions for each task
• When multiple tasks target the same file, treat the plan as a specification and batch implementation -- the plan's value is in completeness, not edit granularity
• For rename-across-callsites tasks, use the Edit tool's replaceAll parameter to handle all sites in a single call per file
• Pre-check linter configs for strict rules before writing code to avoid create-then-rewrite cycles. When consolidating modules, expect length-limit violations. When changing data formats, update test helpers that bypass the app layer.
• Do NOT deviate from the plan without user approval -- surface simpler alternatives before committing
• When a plan conflicts with tooling/environment conventions, research the convention before overriding it

Step 4: Verify

Run the verification command appropriate for the change type:

Scope: Run only the relevant test file(s) per task for fast feedback. Save the full suite for the Completion Protocol.

• Code changes: Build command (confirm compilation)
• New tests: Test command (confirm tests pass)
• Style changes: Lint command (confirm style compliance)
• Structural changes: Verify files exist/don't exist as expected
• Config/doc-only plans (no build/test/lint cycle): Verification is re-reading files and checking structural consistency. Baseline check reduces to git status showing a clean working tree. When project-specific validation commands are available (e.g., ruby generate_config.rb --validate), prefer them over bare git status.
• Greenfield CREATE-only plans (all tasks create new files, no existing code to modify): Same baseline reduction as config/doc-only -- git status for a clean working tree, then structural verification (file existence, content checks) after each task.
• Unavailable runtime: When a plan specifies runtime verification for a runtime not available locally, explicitly flag the deviation in the task record and recommend manual verification rather than silently skipping. This is distinct from missing credentials (which allow structural validation) -- missing runtimes block functional verification entirely.
• Compilation-dependency chains (A references B, B removes C): Defer verification to the last task in the chain rather than attempting intermediate builds that cannot succeed.

When running tests, prefer the test_run_parsed tool over raw bash for structured results. It returns pass/fail per test with parsed failure locations instead of raw terminal output. Note: test_run_parsed cannot parse Minitest output -- fall back to reading raw test output for Ruby/Minitest projects.

When test failures produce stack traces, use stack_trace_resolve to resolve compiled/container paths to actual source file:line references in the workspace.

Use ast_query to find patterns to follow when implementing (e.g., "find all classes extending BaseModel" to match existing conventions). Prefer over grep for structural code queries.

Compare RESULT vs EXPECT:

• If verification passes: proceed to Step 5
• If verification fails: enter the Retry Protocol (see below)

Step 5: Record

• Update the plan file in-place: mark the task as [COMPLETED] in the plan file
• If there were any deviations from the plan, add a note below the task:

  > Deviation: [what changed and why]
  

• If the user requests a deviation, update the plan inline with the deviation marker and continue -- user-initiated changes are pre-approved.

Step 6: Checkpoint (every 3 tasks)

• Re-read the plan's High-Level Objective
• Verify current implementation still aligns with the goal
• If drift detected: STOP, report to user, wait for confirmation before continuing
• If a task reveals the plan's approach is fundamentally flawed (not just the task implementation), STOP and present your finding. The plan may need revision before continuing -- do not force a broken plan to completion.

Retry Protocol

When verification fails at Step 4:

Up to 3 retries. Each attempt: read the error, state the exact failure, state your root-cause theory, adjust the implementation, re-run verification.

If all 3 attempts fail:

• STOP -- do not continue to the next task
• Report to user:
  1. What failed (exact error)
  2. What was attempted (all 3 approaches)
  3. Theory of root cause
  4. Proposed next step
• Wait for user confirmation before continuing

Critical: NEVER silently retry -- state what changed and why. NEVER modify tests blindly -- verify they're correct first. NEVER modify the plan to fit broken code.

Completion Protocol

After all tasks are completed:

1. Run ALL Validation Gates from the plan
2. Run the full build + test + lint cycle. If a baseline regression contract exists, compare the final failure set against it: any new failure is a regression, while unchanged accepted failures remain reported as pre-existing.
3. Report final status: tasks completed (N/N), validation gates (pass/fail), files touched, deviations. Use the git_diff_summary tool for the final changeset summary -- it provides structured file categorization and counts instead of raw diff output. Supplement with git status when the plan creates new files, since git_diff_summary only covers tracked changes and will miss untracked files.
4. Update the plan with ## Implementation Status: COMPLETED at the top

Self-Improvement

After execution, use skill-improver to capture observations about this skill's performance. Before execution, check SKILL_NOTES.md for known edge cases.

Rules

• ALWAYS track the core protocol with TODOs or Quests, if the tooling supports it
• NEVER skip a task -- execute them in strict order
• NEVER modify the plan's High-Level or Mid-Level Objectives
• NEVER work on main branch -- always use feature branches
• NEVER deviate from the plan without user approval
• Follow TDD: verify tests are correct before relying on them. Update tests only with clear justification.
• MAINTAINABILITY above all else. Follow KISS.
• When confused: stop, present theories, get user signoff. Uncertainty expressed > uncertainty hidden.