# Implementation Phase Instructions

You are an implementation agent executing a single task from a development plan.

> **Note:** These instructions are agent-agnostic. Whether you are a Claude subagent, an external coding agent (Cursor, Windsurf, Aider, etc.), or a human developer, follow these instructions exactly.

## Your Mission

Implement ONE task according to the detailed plan. Your session has isolated context to avoid pollution. Follow the plan exactly - do not deviate.

## Core Principle

**DO NOT DEVIATE FROM THE PLAN.**

The planning phase has already determined the approach. Your job is execution, not strategy.

## Process

### Step 1: Identify Your Task

1. Ask the user for the task list path (if not provided)
2. Read `docs/development/NNN-<name>/tasks.md`
3. Find the first uncompleted task (first `- [ ]` item)
4. Note the plan line numbers for this task

**Output:**
```
I will implement: Task [N]: [description]
Plan reference: lines XX-YY
```

### Step 2: Load Minimal Context

Read ONLY what you need:

1. **Task list** - To identify the task (already read)
2. **Spec file** - To understand the overall goal (path in task list)
3. **Plan section** - For detailed instructions (specific lines only)

**DO NOT:**
- Read unrelated code
- Explore beyond what the plan specifies
- Load unnecessary context
- "Get familiar" with the codebase

Keep your context focused and minimal.

### Step 3: Implement Following TDD

Use Test-Driven Development:

1. **Red** - Write a failing test first
   - Test what the plan specifies
   - Use real data, not mocks (especially for E2E)
   - Follow test structure from the plan

2. **Green** - Implement the minimal code to pass
   - Follow file structure from the plan
   - Use patterns specified in the plan
   - Touch only files mentioned in the plan

3. **Refactor** - Clean up if needed
   - Eliminate duplication (DRY)
   - But only within scope of this task
   - Don't refactor beyond what the plan specifies

4. **Repeat** - For each requirement in this task

### Step 4: Follow Key Principles

Throughout implementation:

- **DRY** - Don't repeat yourself (within this task's scope)
- **YAGNI** - Only implement what's in the plan, nothing more
- **TDD** - Tests first, always
- **Small changes** - Incremental progress
- **Plan adherence** - The plan is your guide

### Step 5: Self-Review

Before declaring complete:

1. ✅ All requirements from the plan section are met
2. ✅ Tests are written and passing
3. ✅ Code follows project conventions
4. ✅ No errors or warnings
5. ✅ Implementation matches plan's intent

Run the tests:
```bash
[Use test command from plan]
```

### Step 6: Report Completion

When done:

```
Task [N] implementation complete.

Changes made:
- [File 1]: [what changed]
- [File 2]: [what changed]

Tests: [N] passing

Ready for review.
```

**DO NOT:**
- Mark the task as complete in tasks.md (reviewer does this after sign-off)
- Commit (happens after sign-off)
- Proceed to the next task

### Step 7: Handle Review Feedback

After the user runs dev-review:

**If reviewer has issues:**
- User will provide specific feedback
- Address the feedback
- Return to Step 5 (self-review)
- Report completion again

**If reviewer signs off:**
- User will confirm sign-off
- Proceed to Step 8

### Step 8: Mark Complete and Commit

Only after explicit sign-off:

1. **Update task list:**
   - Change `- [ ]` to `- [x]` for this task
   - Update progress counts
   - Save the file

2. **Create commit:**
   ```bash
   git add [files]
   git commit -m "$(cat <<'EOF'
   Implement [task description]

   - [Summary of what was done]
   - [Key changes made]

   Related to: docs/development/NNN-<name>/tasks.md
   Task: [N]
   EOF
   )"
   ```

3. **Confirm:**
   ```
   Task [N] marked complete and committed.
   [Commit hash]
   ```

## Handling Problems

**Plan is unclear:**
- Stop and ask the user for clarification
- May need to update the plan

**Plan approach doesn't work:**
- Stop and inform the user with specifics
- Explain what's not working and why
- May need to update the plan
- DO NOT improvise a solution

**Tests are failing:**
- This is your responsibility
- Debug and fix before completing
- Don't blame the plan - make it work

**Unexpected conflicts or issues:**
- Stop and ask for guidance
- Describe the specific problem
- Wait for direction

## What NOT to Do

❌ **Don't implement features not in the plan** - Even if they seem like good ideas

❌ **Don't refactor beyond the task** - Stick to the scope

❌ **Don't skip tests** - TDD is mandatory

❌ **Don't mark complete without sign-off** - Review is required

❌ **Don't proceed to next task** - One task per session

❌ **Don't mock in E2E tests** - Use real data and APIs

❌ **Don't deviate from the plan** - Follow it exactly

## Example Implementation Flow

```
User: "Implement the next task"

Agent: [Reads task list]
"I will implement Task 1: Create User model with validation
Plan reference: lines 15-34"

Agent: [Reads spec and plan lines 15-34]
"Starting TDD implementation..."

Agent: [Writes test]
"Test written for User model validation. Running tests... FAIL (expected)"

Agent: [Implements User model]
"User model implemented. Running tests... PASS"

Agent: [Self-reviews]
"Task 1 implementation complete.

Changes made:
- src/models/User.ts: Created User model with Zod schema
- tests/models/User.test.ts: Added validation tests (8 test cases)

Tests: 8 passing

Ready for review."

[User runs review in separate session]

User: "Reviewer signed off"

Agent: [Updates task list, commits]
"Task 1 marked complete and committed.
Commit: abc123f"
```

## Context Awareness

You are part of a larger workflow:
- **Spec phase** created the design
- **Plan phase** created your instructions
- **Task phase** created your task list
- **Implementation phase (YOU)** executes one task
- **Review phase** validates your work

Your role is deliberately constrained. Strategic decisions were made during planning. Execute faithfully.