implementation-phase

<objective>
Execute tasks from tasks.md using Test-Driven Development, preventing code duplication, and maintaining high quality.

Inputs: tasks.md (20-30 tasks), plan.md (implementation plan)
Outputs: Implemented code, test suites, updated tracking files
Expected duration: 2-10 days (varies by complexity)
</objective>

<quick_start>
Execute implementation tasks systematically:

1. Load tech stack constraints from docs/project/tech-stack.md
2. Review task dependencies in tasks.md for parallel work
3. Generate test suite using test-architect (complex features)
4. Execute tasks using TDD (RED → GREEN → REFACTOR)
5. Update task status in NOTES.md after completion
6. Run anti-duplication checks before writing new code
7. Run tests + type-check after each task triplet
8. Validate type safety with type-enforcer (TypeScript)
9. Validate security with security-sentry (auth/API/uploads)
10. Commit implementation with descriptive messages

Key principle: Test first, implement second. Never write code without tests.
</quick_start>

<prerequisites>
Before starting implementation:
- Tasks phase completed (tasks.md exists with 20-30 tasks)
- Plan phase completed (plan.md exists with reuse strategy)
- Development environment set up (dependencies installed)
- Test framework configured (Jest, Pytest, etc.)
- Git working tree clean (no uncommitted changes)

Validate environment with test run before proceeding.
</prerequisites>

<workflow>
<step number="1">
**Load Tech Stack Constraints**

Before writing any code, load technology constraints from docs/project/tech-stack.md:

```bash
# Read tech stack documentation
cat docs/project/tech-stack.md

# Extract: database, framework, libraries, deployment platform
```

Prevents hallucinating wrong technologies (e.g., suggesting MongoDB when PostgreSQL required).

See resources/tech-stack-validation.md for validation checklist.
</step>

<step number="2">
**Review Task Dependencies**

Analyze tasks.md for dependency relationships:

```markdown
# Look for dependencies in tasks.md

T001: Create User model [no dependencies]
T002: Create AuthService [depends: T001]
T003: Create LoginController [depends: T002]
```

Identify parallel work opportunities:

- Independent tasks can run concurrently
- Dependent tasks must run sequentially

See resources/task-batching.md for parallel execution strategy.
</step>

<step number="3">
**Generate Test Suite (Complex Features)**

For complex features (>10 tasks, multiple components), use test-architect agent:

```bash
# Launch test-architect to convert acceptance criteria → tests
# Agent reads tasks.md acceptance criteria
# Generates comprehensive test suite (unit + integration + E2E)
```

Benefits:

- Tests written before implementation (pure TDD)
- Coverage of happy paths, edge cases, error conditions
- Executable specification from acceptance criteria

See resources/tdd-workflow.md#test-architect for detailed usage.
</step>

<step number="4">
**Execute Tasks Using TDD**

For each task, follow RED → GREEN → REFACTOR cycle:

**RED (Write Failing Test)**:

```python
def test_user_can_login_with_valid_credentials():
    """Test user authentication with correct email/password"""
    user = create_user(email="test@example.com", password="secure123")
    result = auth_service.login("test@example.com", "secure123")

    assert result.success is True
    assert result.user.email == "test@example.com"
    assert result.token is not None
```

**GREEN (Minimal Implementation)**:

```python
def login(email, password):
    user = User.query.filter_by(email=email).first()
    if user and user.check_password(password):
        token = generate_jwt(user.id)
        return LoginResult(success=True, user=user, token=token)
    return LoginResult(success=False)
```

**REFACTOR (Clean Up)**:

- Extract magic values to constants
- Remove duplication
- Improve naming
- Add error handling

See resources/tdd-workflow.md for complete RED → GREEN → REFACTOR guide.
</step>

<step number="5">
**Update Task Status**

After completing each task, update NOTES.md:

```markdown
## Implementation Progress

- [x] T001: Create User model (45min, 2025-11-19 10:00)
- [x] T002: Create AuthService (60min, 2025-11-19 11:30)
- [ ] T003: Create LoginController (est. 30min)
```

Track velocity for remaining tasks:

- Average time per task
- Estimated completion date
- Blockers and dependencies

See resources/task-tracking.md for velocity tracking formulas.
</step>

<step number="6">
**Run Anti-Duplication Checks**

Before writing new code, search for existing implementations:

```bash
# Search for similar functions
grep -r "function login" src/

# Search for similar components
grep -r "class AuthService" src/

# Search for similar patterns
grep -r "validate_email" src/
```

If found:

- Reuse existing code (DRY principle)
- Extract to shared utility if needed
- Refactor duplicated logic

See resources/anti-duplication-checks.md for search patterns.
</step>

<step number="7">
**Continuous Testing**

After completing task triplet (3 tasks), run full test suite:

```bash
# Run all tests
npm test  # or pytest, cargo test, etc.

# Run type checker (TypeScript/Python)
npm run type-check

# Check coverage
npm run test:coverage
# Target: ≥80% coverage
```

Fix failing tests immediately (don't accumulate test debt).

See resources/continuous-testing.md for test cadence strategy.
</step>

<step number="8">
**Type Safety Validation (TypeScript)**

For TypeScript projects, use type-enforcer agent to validate strict type safety:

```bash
# Invoke type-enforcer agent
# Scans for: implicit any, unguarded nulls, missing discriminated unions
# Reports violations with file:line locations
```

Blocks:

- Implicit `any` types (requires explicit type annotations)
- Null/undefined access without guards
- Missing exhaustive pattern matching

See resources/continuous-testing.md#type-enforcer for strict mode requirements.
</step>

<step number="9">
**Security Validation**

For security-sensitive co