fix: make refactor-scan step mandatory in TDD workflow

- Changed REFACTOR step from optional to MANDATORY
- Added explicit Claude Code instructions requiring refactor-scan after every GREEN
- Split Quality Gates into "After Every GREEN" and "Before Every PR"
- Added clear process: commit → refactor-scan → apply → commit separately

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude/CLAUDE.md

@@ -41,18 +41,45 @@ terraform plan                  # Preview changes
 
 ## TDD Workflow (RED-GREEN-REFACTOR)
 
-1. **RED**: Write a failing test FIRST
+### 1. RED: Write a Failing Test
-   - Test must fail for the right reason
+- Write test first that fails for the right reason
-   - NO production code until test fails
+- NO production code until test fails
 
-2. **GREEN**: Write MINIMUM code to pass
+### 2. GREEN: Make It Pass
-   - Only what's needed for current test
+- Write MINIMUM code to pass the test
-   - No "while you're there" additions
+- No "while you're there" additions
 
-3. **REFACTOR**: Assess improvements (if tests green)
+### 3. REFACTOR: Mandatory Quality Assessment
-   - Commit BEFORE refactoring
+**CRITICAL: This step is MANDATORY after every GREEN, not optional.**
-   - Only refactor if it adds value
+
-   - All tests must still pass
+**Process:**
+1. **Commit immediately** after tests pass (before any refactoring)
+   ```bash
+   git add . && git commit -m "feat: implement X"
+   ```
+
+2. **Invoke refactor-scan agent** - THIS IS NOT OPTIONAL
+   - Use `@refactor-scan` to assess the code
+   - This happens AUTOMATICALLY after every successful test pass
+   - The agent identifies refactoring opportunities
+
+3. **Apply refactoring** if recommended
+   - Make improvements identified by the scan
+   - Ensure all tests still pass
+   - Commit refactoring separately:
+   ```bash
+   git commit -m "refactor: improve X based on scan"
+   ```
+
+## Claude Code Instructions (MANDATORY)
+
+**After every successful test pass (GREEN state), you MUST:**
+1. Commit the working code immediately
+2. Proactively invoke the `@refactor-scan` agent (or use Task tool with `subagent_type: refactor-scan`)
+3. NOT proceed to the next feature/test until refactor assessment is complete
+4. Apply recommended refactoring and commit separately
+
+**This is not optional. Treat refactor-scan invocation with the same priority as running tests.**
 
 ## Coverage Requirements
 
@@ -217,10 +244,19 @@ Skills are automatically loaded when relevant context is detected. Available ski
 - `@refactor-scan` - Refactoring assessment (TDD step 3)
 - `@dependency-audit` - Package security/updates
 
-## Quality Gates (Before Every Commit)
+## Quality Gates
 
+### After Every GREEN (Before Next RED)
+- [ ] Tests pass (GREEN achieved)
+- [ ] **Code committed** (preserve working state)
+- [ ] **refactor-scan agent executed** (MANDATORY)
+- [ ] Refactoring applied (if recommended)
+- [ ] Tests still pass (after refactoring)
+- [ ] Separate refactor commit created (if changes made)
+
+### Before Every PR/Push
 - [ ] All tests pass
-- [ ] Coverage meets threshold
+- [ ] Coverage meets threshold (80%+)
 - [ ] No linting errors
 - [ ] Type checking passes
 - [ ] No secrets in code