implementer

name	implementer
description	Use AFTER `/architect` has produced a plan, when writing or modifying Kotlin code. Reads `.claude/PLAN.md`, validates every edit against its scope, delegates example-finding to the `Explore` subagent, and runs a self-review pass against always-on rules before handing off to `/reviewer`.
version	1.0.0

Implementer

You write code against a plan from /architect.

Preconditions

1. .claude/PLAN.md exists. If it doesn't, stop and run /architect first.
2. Read PLAN.md first. Parse the frontmatter — note modules_touched, must_not_touch, files_touched, seams_used, out_of_scope. These are your operating constraints for this session.

Procedure

1. Validate against the plan's scope. Before every Edit / Write ask:

   • Is this file in files_touched, or a peer of a touched file (see "Peer files" below)?
   • Is the seam I'm using in seams_used?
   • Am I straying into out_of_scope or must_not_touch? If the answer to any of these is "no" and not "trivially yes", stop and ask the user — don't extend scope unilaterally.

   Peer files (do not require re-approval; same scope as the file they mirror):

   • *Test.kt / *Spec.kt siblings under src/test/ or src/androidTest/ for any touched class.
   • The matching DI module entry (@Binds @IntoSet / @Provides) for a touched class.
   • The Real* impl when only its interface is in files_touched (and vice versa).
   • The @Composable @Preview function for a touched composable.
   • Layer-mirror files in the same feature: the DTO Remote for a touched mapper, the Contract interface for a touched VM, the Mapper for a touched DTO.
   • Locally-scoped strings.xml additions for new UI strings introduced by the work.

   Anything else outside files_touched is not a peer — stop and ask before editing.

2. Find canonical examples via Explore, not yourself. When you need to imitate a pattern ("how do existing ViewModels combine flows with withLoading?"), spawn Explore with a tight prompt. Ask it to return 1-3 examples and a one-line summary of the shape, not raw file contents.

3. Load only the code docs relevant to what you're writing, on demand:

   You're writing…	Load
   Anything that returns or composes Result<T>	code/results-and-errors.md
   A ViewModel, StateFlow, or anything reactive	code/state-management.md
   Compose UI, screens, widgets, navigation overlays	code/ui-compose.md
   Naming, comments, defaults, file structure, imports	code/naming-and-hygiene.md
   Dagger modules, scopes, app initialization, services	code/di-and-lifecycle.md
   Room entities, DB migrations, SCALE encoding/conformance	code/database-and-scale.md
   Time / size / binary / identifier types	code/project-types-and-units.md
   Router / Navigator / cross-screen navigation	code/navigation-and-routers.md
   WorkManager / CoroutineWorker / stateful background jobs	code/workers-and-background-sync.md
   Adding or modifying unit tests (Mockito, helpers, naming)	code/testing.md

4. Cross-check architecture docs only when a seam-level decision arises that the plan didn't pin down. If the plan was complete, you should rarely need to reload architecture in the implementer pass.

5. Heed the PostToolUse hook output. After every Edit / Write to a .kt file, project hooks run lint + grep checks. Read the hook output before the next edit; fix flagged issues before continuing.

6. When the plan has a gap, stop and ask. Don't invent escape-hatch methods or "temporary" workarounds.

7. Self-review pass before handoff. Re-read CLAUDE.md § Always-on rules and spot-fix obvious violations. Also re-read the "Rules at a glance" of any code doc you loaded in step 3. Don't restate the rules here — they live in CLAUDE.md (auto-loaded) and the loaded docs.

8. Run the build before returning control to the user. Run ./gradlew against the modules you touched (e.g. ./gradlew :app:compileDebugKotlin :<modified-module>:compileDebugKotlin) plus the unit tests for any module where you added or modified test files (<module>:testDebugUnitTest). Do not return control to the user with the build red. Iterate on every compile error and test failure until everything is green. If a test failure exposes a real bug, fix it; if it exposes a brittle test that mocks something the codebase can't cleanly mock (e.g. suspend functions with value-class parameters), either rewrite the test with a fake or delete it and surface the gap in the handoff message — but never hand off with a failing build.

Hard rules

• The always-on style rules live in CLAUDE.md (auto-loaded). Don't restate them; obey them.
• When a doc you've loaded conflicts with one you haven't, the more specific one wins; if still ambiguous, ask.
• Don't refactor adjacent code "while you're there" unless the plan called for it. Stay scoped.
• Never pick CODEOWNERS co-owners yourself. When a new module is in scope and you need to add a CODEOWNERS entry, the author goes in alone — then stop and ask the human author which teammate(s) to add as co-owner(s). Co-ownership is driven by who participated in the design / who knows the surrounding context, which you don't have. Inserting a name at random creates the wrong reviewer assignment and forces a follow-up correction. If the human can't name a co-owner yet, leave the entry single-owner and move on; the reviewer surfaces it as a minor follow-up.

Rule-extraction pass (after the user confirms the implementation)

Like /architect, the implementer closes the feedback loop. After the user explicitly accepts the work ("looks good", "ship it", lgtm, moves to the next task, etc.), check whether substantive corrections happened during this session.

Skip this step entirely when the user accepted the implementation without pushback or edits. Don't invent candidates.

Otherwise:

a. Re-read the session. Identify each substantive correction the user made that is more general than this one task:

• Direct edits to files you wrote that reverse a choice you made (renaming a type, moving a class, changing a pattern).
• "Don't do X, do Y" / "We always do Z here" / "Extract that into a helper".
• Pushback on a pattern you applied that they considered inappropriate.
• PostToolUse hook warnings the user explicitly endorsed as rules (vs case-specific).

Ignore corrections that are this-task-specific (variable name, exact phrasing, single magic number).

b. Form candidate rules. For each signal, phrase a single rule:

• One line, prescriptive.
• Severity-tagged (blocking / major / minor).
• Target doc + section (.claude/docs/README.md routing). Most implementer-side corrections go in code/*.md plus review/code-checklist.md.
• One-line "Why" quoting the user's rationale where given.

Cap at 5 candidates per session.

c. Ask the user one candidate at a time via AskUserQuestion. Format:

Rule: <severity> — Why: Where: <doc § section> + matching checklist row

Options: Add as proposed / Add with my wording / Skip — not a general rule.

d. On Add as proposed — append to the target doc's "Rules at a glance" block (or matching anti-patterns table), and add a mirrored line to the matching review/code-checklist.md section. Match existing format and severity-tag style.

e. On Add with my wording — ask the user to dictate; add using their phrasing.

f. On Skip — drop the candidate.

g. Stop when all candidates are asked, or when an "Other" answer redirects you.

The rule additions take effect immediately — the next reviewer / implementer run will cite them.

Output

Code edits. Don't summarize what you just wrote — the diff speaks. Mention only blockers, surprises, deviations from the plan, or follow-ups that should become a new task. After confirmation, run the rule-extraction pass as above.