Implement Story

---
name: 'implement-story'
description: 'Full story implementation workflow: prepare story, enrich with party mode, TDD cycle (tea → dev), simplify, review, and iterate until all ACs pass. Usage: /implement-story <story-identifier>'
---

# Full Story Implementation Workflow

This is the complete, end-to-end workflow for implementing a story from preparation through PR creation. It orchestrates multiple BMAD agents and Claude Code skills in the correct sequence.

**Input:** The user provides a story identifier (e.g., "4.5", "3.1") as $ARGUMENTS. If no argument is provided, ask for the story identifier before proceeding.

<critical>
- Execute ALL phases in order. Do NOT skip phases.
- Do NOT stop between phases unless a HALT condition is triggered.
- Each phase builds on the previous — context must carry forward.
- When invoking BMAD agents/skills, follow their instructions completely before moving to the next phase.
- The story identifier "$ARGUMENTS" should be used to locate the story. Convert dot notation (e.g., "4.5") to the file pattern used in the project (e.g., "4-5-*.md") when searching for story files in {project-root}/_bmad-output/implementation-artifacts/ or {project-root}/docs/stories/.
</critical>

---

## Phase 1: Story Preparation

**Goal:** Ensure the story file exists and is ready for development.

1. Search for the story file matching the identifier "$ARGUMENTS" in:
   - `{project-root}/_bmad-output/implementation-artifacts/` (primary, pattern: `{epic}-{story}-*.md`)
   - `{project-root}/docs/stories/` (fallback, pattern: `{epic}.{story}.story.md`)
2. If the story file exists and has status `ready-for-dev`, `in-progress`, or `Not Started`, note its path and proceed to Phase 2.
3. If the story file has status `Done`:
   - HALT. Check if the Done status is correct by examining the referenced PR.
   - If the PR is docs-only (story file creation, no implementation code), the Done status is incorrect — a `/plan-work` worker mistakenly set it. Reset the status to `Not Started` and proceed to Phase 2.
   - If the PR contains implementation code, the story is already implemented — report to the user and stop.
4. If the story file does NOT exist or needs preparation:
   - Launch `/sm` (Scrum Master agent) to create/prepare the story.
   - Provide the story identifier so SM knows which story to create.
   - Wait for SM to complete story creation.
   - Verify the story file now exists with proper structure (ACs, Tasks, Dev Notes).

---

## Phase 2: Story Enrichment — Dev Readiness

**Goal:** Ensure the story has everything the dev agent needs to succeed.

1. Launch `/party-mode` with the prompt:
   > "Review story $ARGUMENTS — what is missing from the story for dev to succeed? Consider: acceptance criteria completeness, task breakdown granularity, technical specifications, architecture guidance, edge cases, error handling requirements, and integration points."
2. Accept ALL recommendations from the party mode discussion.
3. Apply the accepted recommendations to the story file.
4. Save the updated story file.

---

## Phase 3: Story Enrichment — Test Readiness

**Goal:** Ensure the story has everything needed for test creation.

1. Launch `/party-mode` with the prompt:
   > "Review story $ARGUMENTS — what is missing from the story for tea (Test Engineering Architect) to create comprehensive tests so that dev can succeed with TDD? Consider: testable acceptance criteria, test data requirements, mock/stub specifications, boundary conditions, integration test scenarios, and expected behaviors for error cases."
2. Accept ALL recommendations from the party mode discussion.
3. Apply the accepted recommendations to the story file.
4. Save the updated story file.

---

## Phase 3.5: Baseline — Run Existing Tests

**Goal:** Observe the current project test status before adding any new tests.

1. Launch `/tea` (Test Engineering Architect agent) to run the existing test suite.
2. Instruct TEA to:
   - Run `make test` (or `go test ./... -v`) to execute all existing tests
   - Record the current pass/fail state and coverage baseline
   - Note any pre-existing failures so they are not confused with new test failures in Phase 4
3. If there are pre-existing test failures:
   - Document them clearly (which tests, which packages)
   - These are NOT blockers — proceed to Phase 4, but do not regress them
4. Save the baseline results for comparison in later phases.

---

## Phase 4: Red Phase — Create Failing Tests

**Goal:** Write comprehensive tests that define the expected behavior (all tests should FAIL since code doesn't exist yet).

1. Launch `/tea` (Test Engineering Architect agent) to create tests for the story.
2. Provide the story file path AND the baseline results from Phase 3.5 so TEA has full context.
3. TEA should create:
   - Unit tests for each acceptance criterion
   - Integration tests for component interactions
   - Edge case and error handling tests
4. Run the test suite to confirm new tests FAIL (red phase validation) while pre-existing tests still pass.
5. If new tests pass unexpectedly, investigate — the tests may not be testing new functionality correctly.
6. If pre-existing tests that were passing in Phase 3.5 now fail, fix immediately — new test files must not break existing tests.

---

## Phase 5: Green Phase — Implement Code

**Goal:** Write the minimum code to make all tests pass.

1. Launch `/dev` (Developer agent) to implement the story.
2. Provide the story file path so DEV has full context.
3. DEV should follow the story's Tasks/Subtasks in order.
4. For each task:
   - Implement the minimum code to make related tests pass.
   - Run tests after each task to verify progress.
5. Continue until ALL tests pass (green phase validation).
6. Run the full test suite to verify no regressions.

---

## Phase 6: Refactor — Simplify and Polish

**Goal:** Review code for reuse opportunities, quality, and efficiency.

1. Run `/simplify` to review all changed code.
2. Address any issue