Read context files:
- DEVELOPMENT_PLAN.md (or equivalent)
- ARCHITECTURE.md (design specifications)
- TODO.md (task backlog)
- MULTI_AGENT_PLAN.md (if multi-agent workflow)

undefined

**Step 1.3: Validate Plan**
- Ensure tasks are specific and measurable
- Verify dependencies are identified
- Confirm test coverage is planned
- Check phase estimates are realistic

---

// Example: test/user-service.test.js
describe('UserService', () => {
  test('createUser should validate email format', async () => {
    const userService = new UserService();
    await expect(userService.createUser({
      email: 'invalid-email',
      name: 'John Doe'
    })).rejects.toThrow('Invalid email format');
  });
});

npm test -- --testPathPattern=user-service

**Step 2.2: GREEN - Write Minimal Implementation**

```javascript
// Example: src/services/user-service.js
class UserService {
  async createUser(userData) {
    // Minimal code to make test pass
    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    if (!emailRegex.test(userData.email)) {
      throw new Error('Invalid email format');
    }
    // ... rest of implementation
  }
}

npm test -- --testPathPattern=user-service

**Step 2.3: REFACTOR - Improve Code Quality**

1. **Extract reusable functions**:
```javascript
// utils/validators.js
export const isValidEmail = (email) => {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
};

// Refactored service
import { isValidEmail } from '../utils/validators.js';

class UserService {
  async createUser(userData) {
    if (!isValidEmail(userData.email)) {
      throw new Error('Invalid email format');
    }
    // ... rest of implementation
  }
}

npm run lint     # Fix linting issues
npm run format   # Auto-format code

npm test

**Step 2.4: Commit Progress**

```bash
git add .
git commit -m "feat(user): add email validation to user creation

- Implement email format validation
- Add unit tests for validation
- Extract reusable validator utility

Tests: 12 passing, coverage 85%
Refs: #[issue-number]"

undefined

**Step 3.2: Update Progress Tracking**

Mark phase complete in planning documents:
- `IMPLEMENTATION_PLAN.md` - Check off phase tasks
- `TODO.md` - Update task status
- `MULTI_AGENT_PLAN.md` - Update coordination status (if applicable)

**Step 3.3: Create Phase Commit**

```bash
git add .
git commit -m "feat([feature-name]): Complete Phase [N] - [Phase Name]

Phase [N] Summary:
- ✅ Task 1 completed
- ✅ Task 2 completed
- ✅ Task 3 completed

Tests: [X] passing, coverage [Y%]
Phase: [N] of [Total]
Next: Phase [N+1]"

undefined

**Step 4.2: Create Pull Request**

```bash
gh pr create \
  --title "feat: [Feature Name]" \
  --body-file PR_DESCRIPTION.md \
  --label "ready-for-review"

undefined

**Step 4.3: Handoff to Validator**

If using multi-agent workflow, create handoff document:

```markdown
---
TO: Validator Agent (or use validator-role-skill)
FEATURE: [Feature Name]
PR: #[PR number]
IMPLEMENTATION_PLAN: IMPLEMENTATION_PLAN.md
TEST_COVERAGE: [X%]

IMPLEMENTATION_NOTES:
  - [Key implementation detail 1]
  - [Any concerns or trade-offs]
  - [Areas needing special attention]

VALIDATION_REQUESTS:
  - [ ] Unit test review
  - [ ] Integration test verification
  - [ ] Code quality assessment
  - [ ] Security review (if handling sensitive data)
---

undefined

**Step A.2: Test-Driven Fix**

1. **Write failing test that reproduces bug**:
```javascript
test('Bug #123: division by zero should throw error', () => {
  const calculator = new Calculator();
  expect(() => calculator.divide(10, 0))
    .toThrow('Cannot divide by zero');
});

divide(a, b) {
  if (b === 0) {
    throw new Error('Cannot divide by zero');
  }
  return a / b;
}

undefined

---

undefined

**Step B.2: Safety-First Refactoring**

1. **Ensure comprehensive test coverage FIRST**
   - If coverage < 80%, write tests before refactoring
   - Tests act as safety net

2. **Make incremental changes**
   - One refactoring at a time
   - Commit after each logical change
   - Run tests after EVERY change

3. **Never break public APIs** without version bump
   - Internal refactoring OK
   - Public API changes require coordination

4. **Document breaking changes** clearly
   - Update CHANGELOG.md
   - Provide migration guide
   - Notify stakeholders

---

/**
 * Validates user email format and domain
 * @param email - Email address to validate
 * @returns true if valid, false otherwise
 * @throws ValidationError if email is null/undefined
 */
function validateUserEmail(email: string): boolean {
  if (!email) {
    throw new ValidationError('Email is required');
  }
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
}

<type>(<scope>): <subject>

<body>

<footer>

feat(auth): add JWT token refresh mechanism

- Implement refresh token endpoint
- Add token expiration validation
- Update authentication middleware
- Add unit tests for refresh flow

Tests: 45 passing, coverage 92%
Closes: #123

// ❌ WRONG - Vulnerable to SQL injection
const query = `SELECT * FROM users WHERE email = '${userEmail}'`;

// ✅ CORRECT - Parameterized query
const query = 'SELECT * FROM users WHERE email = ?';
db.execute(query, [userEmail]);

undefined

undefined

undefined

undefined

undefined

---