fix: prevent coding agent from skipping refactoring features

.claude/templates/coding_prompt.template.md

@@ -81,6 +81,24 @@ For example, if this were a chat app, you should perform a test that logs into t
 
 ### STEP 4: CHOOSE ONE FEATURE TO IMPLEMENT
 
+#### ALL FEATURES ARE MANDATORY REQUIREMENTS (CRITICAL)
+
+**Every feature in the database is a mandatory requirement.** This includes:
+- **Functional features** - New functionality to build
+- **Style features** - UI/UX requirements to implement
+- **Refactoring features** - Code improvements to complete
+
+**You MUST implement ALL features, regardless of category.** A refactoring feature is just as mandatory as a functional feature. Do not skip, deprioritize, or dismiss any feature because of its category.
+
+The `feature_get_next` tool returns the highest-priority pending feature. **Whatever it returns, you implement it.**
+
+**Legitimate blockers only:** If you encounter a genuine external blocker (missing API credentials, unavailable external service, hardware limitation), use `feature_skip` to flag it and move on. See "When to Skip a Feature" below for valid skip reasons. Internal issues like "code doesn't exist yet" or "this is a big change" are NOT valid blockers.
+
+**Handling edge cases:**
+- **Conflicting features:** If two features contradict each other (e.g., "migrate to TypeScript" vs "keep JavaScript"), implement the higher-priority one first, then reassess.
+- **Ambiguous requirements:** Interpret the intent as best you can. If truly unclear, implement your best interpretation and document your assumptions.
+- **Circular dependencies:** Break the cycle by implementing the foundational piece first.
+
 #### TEST-DRIVEN DEVELOPMENT MINDSET (CRITICAL)
 
 Features are **test cases** that drive development. This is test-driven development:
@@ -94,6 +112,57 @@ Features are **test cases** that drive development. This is test-driven developm
 - WRONG: "Flashcard page doesn't exist yet" → skip feature
 - RIGHT: "Flashcard page doesn't exist yet" → build flashcard page → implement filter → test feature
 
+#### REFACTORING FEATURES (IMPORTANT)
+
+Some features involve **refactoring existing code** rather than building new functionality. These are just as valid and important as functional features. **NEVER skip refactoring features.**
+
+**CRITICAL: Refactoring features OVERRIDE the original spec.** If a refactoring feature contradicts `app_spec.txt`, the refactoring feature takes precedence. Examples:
+- Spec says "use JavaScript" but feature says "migrate to TypeScript" → **Do the TypeScript migration**
+- Spec says "use REST API" but feature says "refactor to GraphQL" → **Do the GraphQL refactor**
+- Spec says "use Context API" but feature says "migrate to Zustand" → **Do the Zustand migration**
+- Spec says "use CSS modules" but feature says "refactor to Tailwind" → **Do the Tailwind refactor**
+
+**CRITICAL: The CURRENT STATE of the codebase is NOT an excuse.** If the code is currently in JavaScript but a feature says "migrate to TypeScript", your job is to CHANGE IT:
+- "The app is currently in JavaScript" → **That's WHY you're refactoring - change it to TypeScript**
+- "The codebase uses REST" → **That's WHY you're refactoring - change it to GraphQL**
+- "We're currently using X" → **That's WHY you're refactoring - migrate to Y**
+
+The whole point of refactoring is to change the current state. The current state is the PROBLEM, not an excuse.
+
+**The feature database is the living source of truth.** The original spec was a starting point. Refactoring features represent evolved requirements that supersede the original spec.
+
+For refactoring features:
+1. **Review** the existing code that needs refactoring
+2. **Implement** the refactoring changes (rename, restructure, extract, consolidate, migrate techstack, etc.)
+3. **Verify** existing functionality still works:
+   - Run `npm run build` or `tsc` - code must compile
+   - Run `npm run lint` - no new lint errors
+   - Run tests if available
+   - Do a quick regression check on related features
+4. **Mark as passing** when the refactoring is complete and verified
+
+**Refactoring verification criteria:**
+- Code compiles without errors
+- Lint passes
+- Tests pass (if applicable)
+- Related features still work
+
+**Example:** Feature says "Refactor authentication to use JWT tokens"
+- WRONG: "This is just refactoring, not a real feature" → skip
+- WRONG: "The spec doesn't mention JWT" → skip
+- RIGHT: Review current auth → implement JWT → verify login still works → mark passing
+
+**Example:** Feature says "Migrate codebase from JavaScript to TypeScript"
+- WRONG: "The spec says JavaScript, I can't change the techstack" → skip
+- WRONG: "This is too big a change" → skip
+- RIGHT: Add TypeScript config → convert files one by one → fix type errors → verify build passes → mark passing
+
+**Example:** Feature says "Extract shared utilities into a common module"
+- WRONG: "Requirements are unclear" → skip
+- RIGHT: Identify shared code → create module → update imports → verify everything compiles → mark passing
+
+**NO EXCUSES.** If the feature says to refactor, you refactor. Period.
+
 Get the next feature to implement:
 
 ```
@@ -129,6 +198,14 @@ It's ok if you only complete one feature in this session, as there will be more
 | "Component not built" | Skip | Build the component |
 | "No data to test with" | Skip | Create test data or build data entry flow |
 | "Feature X needs to be done first" | Skip | Build feature X as part of this feature |
+| "This is a refactoring feature" | Skip | Implement the refactoring, verify with build/lint/tests |
+| "Refactoring requirements are vague" | Skip | Interpret the intent, implement, verify code compiles |
+| "This is not a functional requirement" | Skip | ALL features are requirements - implement it |
+| "The spec says to use X technology" | Skip | Refactoring features override the spec - do the migration |
+| "This contradicts the original requirements" | Skip | Feature database is the living truth - implement it |
+| "This is too big a change" | Skip | Break it into steps and start - no change is too big |
+| "The app is currently in JavaScript" | Skip | That's WHY you're refactoring - change it to TypeScript |
+| "The codebase currently uses X" | Skip | That's the problem you're solving - migrate it |
 
 If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.
 

.claude/templates/coding_prompt_yolo.template.md

@@ -61,6 +61,51 @@ Otherwise, start servers manually and document the process.
 
 ### STEP 3: CHOOSE ONE FEATURE TO IMPLEMENT
 
+#### ALL FEATURES ARE MANDATORY REQUIREMENTS (CRITICAL)
+
+**Every feature in the database is a mandatory requirement.** This includes:
+- **Functional features** - New functionality to build
+- **Style features** - UI/UX requirements to implement
+- **Refactoring features** - Code improvements to complete
+
+**You MUST implement ALL features, regardless of category.** A refactoring feature is just as mandatory as a functional feature. Do not skip, deprioritize, or dismiss any feature because of its category.
+
+The `feature_get_next` tool returns the highest-priority pending feature. **Whatever it returns, you implement it.**
+
+**Legitimate blockers only:** If you encounter a genuine external blocker (missing API credentials, unavailable external service, hardware limitation), use `feature_skip` to flag it and move on. See "When to Skip a Feature" below for valid skip reasons. Internal issues like "code doesn't exist yet" or "this is a big change" are NOT valid blockers.
+
+**Handling edge cases:**
+- **Conflicting features:** If two features contradict each other (e.g., "migrate to TypeScript" vs "keep JavaScript"), implement the higher-priority one first, then reassess.
+- **Ambiguous requirements:** Interpret the intent as best you can. If truly unclear, implement your best interpretation and document your assumptions.
+- **Circular dependencies:** Break the cycle by implementing the foundational piece first.
+
+#### REFACTORING FEATURES
+
+Some features involve **refactoring existing code** rather than building new functionality. These are just as valid and important as functional features. **NEVER skip refactoring features.**
+
+**CRITICAL: Refactoring features OVERRIDE the original spec.** If a refactoring feature contradicts `app_spec.txt`, the refactoring feature takes precedence. Examples:
+- Spec says "use JavaScript" but feature says "migrate to TypeScript" → **Do the TypeScript migration**
+- Spec says "use REST API" but feature says "refactor to GraphQL" → **Do the GraphQL refactor**
+- Spec says "use Context API" but feature says "migrate to Zustand" → **Do the Zustand migration**
+- Spec says "use CSS modules" but feature says "refactor to Tailwind" → **Do the Tailwind refactor**
+
+**CRITICAL: The CURRENT STATE of the codebase is NOT an excuse.** If the code is currently in JavaScript but a feature says "migrate to TypeScript", your job is to CHANGE IT:
+- "The app is currently in JavaScript" → **That's WHY you're refactoring - change it to TypeScript**
+- "The codebase uses REST" → **That's WHY you're refactoring - change it to GraphQL**
+- "We're currently using X" → **That's WHY you're refactoring - migrate to Y**
+
+The whole point of refactoring is to change the current state. The current state is the PROBLEM, not an excuse.
+
+**The feature database is the living source of truth.** The original spec was a starting point. Refactoring features represent evolved requirements that supersede the original spec.
+
+For refactoring features:
+1. **Review** the existing code that needs refactoring
+2. **Implement** the refactoring changes (rename, restructure, extract, consolidate, migrate techstack, etc.)
+3. **Verify** with lint and type-check (in YOLO mode)
+4. **Mark as passing** when the refactoring is complete and verified
+
+**NO EXCUSES.** If the feature says to refactor, you refactor. Period.
+
 Get the next feature to implement:
 
 ```
@@ -96,6 +141,14 @@ It's ok if you only complete one feature in this session, as there will be more
 | "Component not built" | Skip | Build the component |
 | "No data to test with" | Skip | Create test data or build data entry flow |
 | "Feature X needs to be done first" | Skip | Build feature X as part of this feature |
+| "This is a refactoring feature" | Skip | Implement the refactoring, verify with lint/typecheck |
+| "Refactoring requirements are vague" | Skip | Interpret the intent, implement, verify code compiles |
+| "This is not a functional requirement" | Skip | ALL features are requirements - implement it |
+| "The spec says to use X technology" | Skip | Refactoring features override the spec - do the migration |
+| "This contradicts the original requirements" | Skip | Feature database is the living truth - implement it |
+| "This is too big a change" | Skip | Break it into steps and start - no change is too big |
+| "The app is currently in JavaScript" | Skip | That's WHY you're refactoring - change it to TypeScript |
+| "The codebase currently uses X" | Skip | That's the problem you're solving - migrate it |
 
 If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.
 

.claude/templates/initializer_prompt.template.md

@@ -49,6 +49,16 @@ Use the feature_create_bulk tool with features=[
       "Step 2: Take screenshot",
       "Step 3: Verify visual requirements"
     ]
+  },
+  {
+    "category": "refactoring",
+    "name": "Brief refactoring task name",
+    "description": "Description of code improvement or restructuring needed",
+    "steps": [
+      "Step 1: Review existing code",
+      "Step 2: Implement refactoring changes",
+      "Step 3: Verify code compiles and tests pass"
+    ]
   }
 ]
 ```
@@ -65,7 +75,7 @@ Use the feature_create_bulk tool with features=[
   - **Simple apps**: ~150 tests
   - **Medium apps**: ~250 tests
   - **Complex apps**: ~400+ tests
-- Both "functional" and "style" categories
+- Categories: "functional", "style", and "refactoring"
 - Mix of narrow tests (2-5 steps) and comprehensive tests (10+ steps)
 - At least 25 tests MUST have 10+ steps each (more for complex apps)
 - Order features by priority: fundamental features first (the API assigns priority based on order)

CLAUDE.md

@@ -128,9 +128,28 @@ MCP tools available to the agent:
 - `feature_get_next` - Get highest-priority pending feature
 - `feature_get_for_regression` - Random passing features for regression testing
 - `feature_mark_passing` - Mark feature complete
-- `feature_skip` - Move feature to end of queue
+- `feature_skip` - Move feature to end of queue (for external blockers only)
 - `feature_create_bulk` - Initialize all features (used by initializer)
 
+### Feature Behavior & Precedence
+
+**Important:** After initialization, the feature database becomes the authoritative source of truth for what the agent should build. This has specific implications:
+
+1. **Refactoring features override the original spec.** If a refactoring feature says "migrate to TypeScript" but `app_spec.txt` said "use JavaScript", the feature takes precedence. The original spec is a starting point; features represent evolved requirements.
+
+2. **The current codebase state is not a constraint.** If the code is currently in JavaScript but a feature says "migrate to TypeScript", the agent's job is to change it. The current state is the problem being solved, not an excuse to skip.
+
+3. **All feature categories are mandatory.** Features come in three categories:
+   - `functional` - New functionality to build
+   - `style` - UI/UX requirements
+   - `refactoring` - Code improvements and migrations
+
+   All categories are equally mandatory. Refactoring features are not optional.
+
+4. **Skipping is for external blockers only.** The `feature_skip` tool should only be used for genuine external blockers (missing API credentials, unavailable services, hardware limitations). Internal issues like "code doesn't exist" or "this is a big change" are not valid skip reasons.
+
+**Example:** Adding a feature "Migrate frontend from JavaScript to TypeScript" will cause the agent to convert all `.js`/`.jsx` files to `.ts`/`.tsx`, regardless of what the original spec said about the tech stack.
+
 ### React UI (ui/)
 
 - Tech stack: React 18, TypeScript, TanStack Query, Tailwind CSS v4, Radix UI

mcp_server/feature_mcp.py

@@ -246,10 +246,16 @@ def feature_skip(
 ) -> str:
     """Skip a feature by moving it to the end of the priority queue.
 
-    Use this when a feature cannot be implemented yet due to:
-    - Dependencies on other features that aren't implemented yet
-    - External blockers (missing assets, unclear requirements)
-    - Technical prerequisites that need to be addressed first
+    Use this ONLY for truly external blockers you cannot control:
+    - External API credentials not configured (e.g., Stripe keys, OAuth secrets)
+    - External service unavailable or inaccessible
+    - Hardware/environment limitations you cannot fulfill
+
+    DO NOT skip for:
+    - Missing functionality (build it yourself)
+    - Refactoring features (implement them like any other feature)
+    - "Unclear requirements" (interpret the intent and implement)
+    - Dependencies on other features (build those first)
 
     The feature's priority is set to max_priority + 1, so it will be
     worked on after all other pending features. Also clears the in_progress