gh-anexpn-claude-plugins/skills/dev-workflow/references/impl_phase.md

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:

[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:

   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.