Execute

---
description: Execute an implementation plan
argument-hint: "<path-to-plan.md>"
---

# Execute: Implement from Plan

## Plan to Execute

Read plan file: `$ARGUMENTS`

**Example:** `.claude/agents/plans/example-feature-address-validation.md`

## Execution Instructions

### 1. Read and Understand

**CRITICAL: Read the ENTIRE plan carefully first!**

- Read the plan file from start to finish
- Understand all tasks and their dependencies
- Note the validation commands to run
- Review the testing strategy
- **Read all "MUST READ" files listed in the plan**

**DO NOT skip this step!** The success of one-pass implementation depends on thorough understanding.

### 2. Read Prime Context

Before starting implementation, read the prime context:

```bash
Read .claude/agents/context/prime-context.md

This provides the overall codebase context that the plan builds upon.

2.5. Verify Feature Branch

CRITICAL: You MUST be on a feature branch!

Check current branch:

git branch --show-current

If on main branch:

1. STOP - Do not implement on main!
2. Ask user: "Should I create a feature branch for this implementation?"
3. If approved, create branch:

   git checkout -b feature/<feature-name>
   

4. Then proceed with implementation

If on feature branch:

• ✅ Continue with implementation
• Verify branch name is descriptive (e.g., feature/user-auth, fix/login-bug)

Rationale:

• Protects main branch from uncommitted changes
• Allows for review before merging
• Facilitates rollback if needed
• Standard practice for team collaboration

3. Read All Mandatory Files

The plan lists files under "CONTEXT REFERENCES > Relevant Codebase Files (MUST READ!)"

Read each file carefully:

• Pay attention to patterns used
• Note naming conventions
• Understand error handling
• Observe logging patterns

Example:

# Read controller pattern
Read backend/src/main/java/com/example/controller/ExampleController.java

# Read service pattern
Read backend/src/main/java/com/example/service/ExampleService.java

# Read entity pattern
Read backend/src/main/java/com/example/entity/Example.java

3.5. Verify TDD Compliance Before Implementation

🚨 CRITICAL: You MUST follow RED-GREEN-REFACTOR cycle!

For EACH task in "STEP-BY-STEP TASKS":

Step 1: CHECK Test Exists (RED Phase)

• Does test file exist for the code you're about to write?
• If NO → STOP! Write test FIRST (use test-writing skill)
• If YES → Continue to Step 2

Step 2: VERIFY Test Fails (RED Phase)

• Run the test to verify it FAILS (RED)
• If test passes → You're missing test logic, fix test first
• If test fails → GOOD! Continue to Step 3

Step 3: Implement Code (GREEN Phase)

• Write MINIMAL code to make the test pass
• Run test again to verify it PASSES (GREEN)
• If test fails → Fix implementation until test passes

Step 4: Refactor (REFACTOR Phase)

• Improve code while keeping tests green
• Run tests again to ensure nothing broke
• If tests break → Fix refactor or revert

ZERO TOLERANCE:

• ❌ Code written before tests WILL BE DELETED
• ❌ NO exceptions for "simple code" or "just this once"
• ❌ If you violate TDD, DELETE CODE and start over

TDD Enforcement:

• test-driven-development skill will auto-activate and enforce this
• test-writing skill will enforce Given-When-Then pattern
• Follow the cycle: Test first, implement second, refactor third

4. Execute Tasks in Order

For EACH task in "STEP-BY-STEP TASKS":

🚨 TDD CHECKPOINT (Before EACH task):

• Does test file exist for implementation you're about to write?
• Was test written BEFORE implementation code (RED-GREEN-REFACTOR)?
• If code written before test → DELETE CODE, write test first
• TDD skill will auto-activate to enforce this

a. Navigate to the task

• Identify the file and action required
• Read existing related files if modifying
• Check if file exists (for UPDATE tasks)

b. Implement the task

• Follow the detailed specifications exactly
• Maintain consistency with existing code patterns
• Include proper type annotations (Java) or types (TypeScript)
• Add structured logging where appropriate
• Follow naming conventions from the plan

c. Verify as you go

• After each file change, check syntax
• Ensure imports are correct
• Verify types are properly defined

d. Run validation command

CRITICAL: Run the validation command specified in the task:

# Example validation commands from tasks
cd backend && mvn clean compile
mvn test -Dtest=ExampleServiceTest

If validation fails:

• Fix the issue
• Re-run the validation command
• Continue only when it passes

DO NOT skip validation! Each task has a validation command for a reason.

5. Implement Testing Strategy

🚨 TDD REMINDER: Tests should be written FIRST (RED phase), not after implementation!

If you followed TDD correctly in section 4, tests are already written. If not, DELETE implementation code and start over with test-first approach.

After completing implementation tasks:

• Create all test files specified in the plan
• Implement all test cases mentioned
• Follow the testing approach outlined in the plan
• Ensure tests cover edge cases

Run tests after creating each test file:

# Backend unit tests
mvn test -Dtest=NewServiceTest

# Backend integration tests
mvn test -Dtest=NewControllerIT

# Frontend tests
npm test -- NewComponent.test.tsx

6. Run All Validation Commands

Execute ALL validation commands from the plan in order:

# Level 1: Backend Compilation
cd backend && mvn clean compile

# Level 2: Backend Unit Tests
cd backend && mvn test

# Level 3: Backend Integration Tests
cd backend && mvn verify -DskipUnitTests=true

# Level 4: Test Coverage
cd backend && mvn jacoco:report

# Level 5: Frontend Build
cd frontend && npm run build

# Level 6: Manual Validation
# (Feature-specific manual testing st