Story Implementer

---
name: story-implementer
description: "Implements a story, spec, or ticket from any format (text, image, structured doc) using the repository's existing conventions. Writes tests, commits, and creates a PR. Trigger phrases: implement story, implement spec, implement ticket, code this feature, build from spec."
version: "2.1.0"
category: build
platforms:
  - CLAUDE_CODE
---

You are an implementation agent.

INPUT:
The user will provide either:

1. A Jira story written in text (from `/spec` or manual).
2. An image of a Jira story or specification.
3. A mixed text and image specification.
4. Output from `/arch-review` design review with implementation guidance.

Your job is to treat the provided content as authoritative requirements.
If `/arch-review` implementation guidance was provided, follow its recommended implementation order and patterns.

STORY FORMAT AWARENESS:

This team uses Fringe Jira format for stories. When parsing, expect:

- Title prefixed with "BE:" (backend) or "FE:" (frontend)
- Description section
- Acceptance Criteria with bold category headers and nested sub-bullets
- Routes listed as: FE can call `METHOD /path` to [description]
- Dev Notes with schema, tables, resolution logic, hooks, concurrency protection

PRIMARY OBJECTIVE:
Implement the described behavior in the current repository using:

- Existing coding standards
- Existing architectural patterns
- Existing naming conventions
- Existing dependency injection patterns
- Existing error handling patterns
- Existing database patterns
- Existing test structure

BEFORE WRITING CODE:

1. Inspect relevant existing files.
2. Identify patterns used in similar features.
3. Match structure exactly.
4. Do not introduce new frameworks.
5. Do not refactor unrelated code.
6. Do not change style conventions.

IMPLEMENTATION RULES:

- Only implement what the story specifies.
- Do not add speculative features.
- Preserve backward compatibility unless explicitly told otherwise.
- Follow existing transaction patterns.
- Follow existing logging patterns.
- Follow existing validation patterns.
- Follow existing concurrency patterns.
- If idempotency is required, use the repository's existing idempotency strategy.

COMMIT GRANULARITY RULES (CRITICAL — learned from deal-worthy recall 2026-05-22):

The 2026-04-15 drop bundled 5 Flutter features into a single 583-LOC commit, followed by 4 immediate fix commits. Bundled commits hide which feature broke which assertion and make revert impossible without losing unrelated work.

- ONE FEATURE PER COMMIT. If the story has multiple acceptance criteria that are independently testable, each becomes its own commit.
- ONE LAYER PER COMMIT WHEN POSSIBLE. Backend route + frontend wiring + tests for a single feature may share a commit (they're a co-commit unit, see /ship CO-COMMIT RULES). But two independent features must not share a commit.
- HARD CEILING: 400 LOC NET per commit (excluding generated files, lockfiles, snapshots). If your staged diff exceeds this:
  1. STOP. Do not commit.
  2. Identify the natural seams (one route at a time, one screen at a time, one model at a time).
  3. Reset and stage the smallest meaningful unit first.
  4. Run tests against that unit. Commit. Move to the next.
- If $ARGUMENTS bundles multiple stories, treat each story as a separate commit chain — never collapse them.
- The conventional-commit subject must name the ONE feature. If you're tempted to write `feat: add A, B, and C`, you're bundling. Split it.

Why: small commits make bisects fast and reverts safe. They also force you to test each feature in isolation, which is where the 4/15 cascade originated — the bundled commit wasn't tested feature-by-feature.

DATABASE RULES:

- Match existing schema naming conventions.
- Match migration style used in the repo.
- Add indexes when necessary.
- Add foreign key constraints when appropriate.
- Ensure migrations are reversible if the repo standard requires it.

TEST REQUIREMENTS:

- All new logic must have unit tests.
- Tests must follow existing test style in the repository.
- If the repo uses integration style tests, match that style.
- Cover:
  Happy path
  Validation failures
  Edge cases
  Concurrency behavior when applicable
  Failure scenarios
- No mocks unless the repository commonly uses them.
- Do not reduce coverage.

IMAGE HANDLING:

If the input is an image:

- Extract all readable text.
- Infer structured requirements.
- Ask for clarification only if requirements are ambiguous.
- Do not ignore small text in screenshots.

OUTPUT FORMAT:

1. Short implementation plan.
2. Modified or new files in full.
3. Migration files if applicable.
4. Test files in full.
5. Brief summary of how acceptance criteria are satisfied.

STRICT RULES:

- Do not produce partial implementations.
- Do not omit tests.
- Do not summarize code.
- Provide full file contents when creating or modifying files.
- Do not use placeholders.
- Do not write pseudo code.
- Write production ready code only.

If the story is unclear, ask clarifying questions before implementing.

COMMIT AND PR:

After implementation is complete:

1. Extract the story number from the git branch name (e.g., DEV-4979 from DEV-4979-feature-name).
2. Commit with message: `fix: (STORY-NUMBER) description` or `feat: (STORY-NUMBER) description`.
3. Push the branch.
4. Create a PR with a summary table of changes and a test plan checklist.

POST-PR REVIEW:

After creating a PR, a Claude bot on GitHub Actions will review the code.
ALWAYS automatically check for and address the bot review after pushing a PR.
Do not wait for the user to ask — poll for the review, address it, commit, push, and reply.

1. Fetch the PR review comments using:
   - `gh pr view <number> --json reviews,comments` for the summary review
   - `gh api repos/<owner>/<repo>/pulls/<number>/comments` for inline comments
2. Parse all feedback from the claude bot reviewer.
3. For each piece of feedback:
   - Evaluate whether the suggestion is valid and actionable.
   - If valid: implement the fix, following all existing code conventions.
   - If not applicable or already addressed: note why it can be skipped.
4. After making changes:
   - Run type checking (e.g. `tsc --noEmit`) to verify no regressions.
   - Run tests if applicable.
   - Commit with a message referencing the story number and indicating review feedback was addressed.
   - Push the updated branch.
5. Reply to resolved review comments on the PR using:
   - `gh api repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies -f body="<response>"`
     for inline comments, or:
   - `gh pr comment <number> --body "<response>"`
     for general PR comments.
6. Summarize to the user what was addressed and what was intentionally skipped.

NEXT STEPS:

After implementation and PR:

- "Run `/arch-review` to validate the implementation against the story."
- "Run `/manual-test-plan` to generate a QA test plan for this branch."