From 504cd9be1c0462d480fcbb98d4617d07289a3140 Mon Sep 17 00:00:00 2001 From: Quenos Date: Tue, 13 Jan 2026 09:14:22 +0100 Subject: [PATCH 1/5] fix: prevent coding agent from skipping refactoring features - Add dedicated "REFACTORING FEATURES" section to coding prompt with clear instructions on how to handle refactoring tasks - Add refactoring entries to "NEVER skip because" table - Update feature_skip MCP tool docstring to explicitly prohibit skipping for refactoring or "unclear requirements" The agent was skipping refactoring features because: 1. The prompt was entirely focused on "test-driven development" where features are test cases - refactoring doesn't fit this mental model 2. The skip documentation mentioned "unclear requirements" as valid, which refactoring features could be misinterpreted as Co-Authored-By: Claude Opus 4.5 --- .claude/templates/coding_prompt.template.md | 30 +++++++++++++++++++++ mcp_server/feature_mcp.py | 14 +++++++--- 2 files changed, 40 insertions(+), 4 deletions(-) diff --git a/.claude/templates/coding_prompt.template.md b/.claude/templates/coding_prompt.template.md index 823d2972..cc22bb60 100644 --- a/.claude/templates/coding_prompt.template.md +++ b/.claude/templates/coding_prompt.template.md @@ -94,6 +94,34 @@ 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.** + +For refactoring features: +1. **Review** the existing code that needs refactoring +2. **Implement** the refactoring changes (rename, restructure, extract, consolidate, 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 +- RIGHT: Review current auth → implement JWT → verify login still works → 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 + Get the next feature to implement: ``` @@ -129,6 +157,8 @@ 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 | 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. diff --git a/mcp_server/feature_mcp.py b/mcp_server/feature_mcp.py index 1534bc1b..0129a79a 100755 --- a/mcp_server/feature_mcp.py +++ b/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 From db8af3f4a02d00647436c18e8c40571e68c06a72 Mon Sep 17 00:00:00 2001 From: Quenos Date: Tue, 13 Jan 2026 09:23:47 +0100 Subject: [PATCH 2/5] fix: make refactoring features mandatory and prevent skipping Root cause: Agent was skipping refactoring features because: 1. Initializer only defined "functional" and "style" categories 2. No explicit statement that ALL features are mandatory 3. Agent interpreted refactoring as "not a requirement" Changes: - Add "refactoring" as valid category in initializer prompt with example - Add prominent "ALL FEATURES ARE MANDATORY REQUIREMENTS" section stating that functional, style, AND refactoring features must all be implemented without exception - Add "This is not a functional requirement" to NEVER skip table - Update both regular and YOLO prompts with same guidance The agent now has explicit instructions that: - Every feature in the database is mandatory - Refactoring features are just as important as functional features - "Whatever feature_get_next returns, you implement it. No exceptions." Co-Authored-By: Claude Opus 4.5 --- .claude/templates/coding_prompt.template.md | 12 ++++++++++ .../templates/coding_prompt_yolo.template.md | 24 +++++++++++++++++++ .../templates/initializer_prompt.template.md | 12 +++++++++- 3 files changed, 47 insertions(+), 1 deletion(-) diff --git a/.claude/templates/coding_prompt.template.md b/.claude/templates/coding_prompt.template.md index cc22bb60..88b84b3e 100644 --- a/.claude/templates/coding_prompt.template.md +++ b/.claude/templates/coding_prompt.template.md @@ -81,6 +81,17 @@ 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.** No exceptions. + #### TEST-DRIVEN DEVELOPMENT MINDSET (CRITICAL) Features are **test cases** that drive development. This is test-driven development: @@ -159,6 +170,7 @@ It's ok if you only complete one feature in this session, as there will be more | "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 | 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. diff --git a/.claude/templates/coding_prompt_yolo.template.md b/.claude/templates/coding_prompt_yolo.template.md index 1ab2179a..dc2b0186 100644 --- a/.claude/templates/coding_prompt_yolo.template.md +++ b/.claude/templates/coding_prompt_yolo.template.md @@ -61,6 +61,27 @@ 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.** No exceptions. + +#### 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.** + +For refactoring features: +1. **Review** the existing code that needs refactoring +2. **Implement** the refactoring changes (rename, restructure, extract, consolidate, etc.) +3. **Verify** with lint and type-check (in YOLO mode) +4. **Mark as passing** when the refactoring is complete and verified + Get the next feature to implement: ``` @@ -96,6 +117,9 @@ 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 | 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. diff --git a/.claude/templates/initializer_prompt.template.md b/.claude/templates/initializer_prompt.template.md index 312cd179..4c9b539c 100644 --- a/.claude/templates/initializer_prompt.template.md +++ b/.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) From af505734a717e142e00330748e79174258806ef1 Mon Sep 17 00:00:00 2001 From: Quenos Date: Tue, 13 Jan 2026 09:42:18 +0100 Subject: [PATCH 3/5] fix: refactoring features override original spec requirements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The agent was using the original app_spec.txt as an excuse to skip refactoring features (e.g., "the spec says JavaScript, I can't migrate to TypeScript"). Added explicit rules: - "CRITICAL: Refactoring features OVERRIDE the original spec" - "The feature database is the living source of truth" - "The original spec was a starting point" - "NO EXCUSES. If the feature says to refactor, you refactor. Period." Added to NEVER skip table: - "The spec says to use X technology" → do the migration - "This contradicts the original requirements" → feature DB is truth - "This is too big a change" → break into steps and start Examples added showing wrong reasoning like: - "The spec says JavaScript, I can't change the techstack" → WRONG - "This is too big a change" → WRONG Co-Authored-By: Claude Opus 4.5 --- .claude/templates/coding_prompt.template.md | 21 ++++++++++++++++++- .../templates/coding_prompt_yolo.template.md | 15 ++++++++++++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/.claude/templates/coding_prompt.template.md b/.claude/templates/coding_prompt.template.md index 88b84b3e..1ec0192b 100644 --- a/.claude/templates/coding_prompt.template.md +++ b/.claude/templates/coding_prompt.template.md @@ -109,9 +109,17 @@ Features are **test cases** that drive development. This is test-driven developm 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** + +**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, etc.) +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 @@ -127,12 +135,20 @@ For refactoring features: **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: ``` @@ -171,6 +187,9 @@ It's ok if you only complete one feature in this session, as there will be more | "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 | 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. diff --git a/.claude/templates/coding_prompt_yolo.template.md b/.claude/templates/coding_prompt_yolo.template.md index dc2b0186..c5d7bec4 100644 --- a/.claude/templates/coding_prompt_yolo.template.md +++ b/.claude/templates/coding_prompt_yolo.template.md @@ -76,12 +76,22 @@ The `feature_get_next` tool returns the highest-priority pending feature. **What 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** + +**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, etc.) +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: ``` @@ -120,6 +130,9 @@ It's ok if you only complete one feature in this session, as there will be more | "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 | 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. From 1ddcf08586db0a7503c83e83873dcdb86b686c45 Mon Sep 17 00:00:00 2001 From: Quenos Date: Tue, 13 Jan 2026 09:59:56 +0100 Subject: [PATCH 4/5] fix: current state of codebase is not an excuse to skip refactoring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agent was refusing to refactor because "the app is currently in JavaScript" even though that's exactly why the refactoring feature exists. Added explicit rules: - "CRITICAL: The CURRENT STATE of the codebase is NOT an excuse" - "The app is currently in JavaScript" → That's WHY you're refactoring - "The whole point of refactoring is to change the current state" - "The current state is the PROBLEM, not an excuse" Added to NEVER skip table: - "The app is currently in JavaScript" → change it to TypeScript - "The codebase currently uses X" → migrate it Co-Authored-By: Claude Opus 4.5 --- .claude/templates/coding_prompt.template.md | 9 +++++++++ .claude/templates/coding_prompt_yolo.template.md | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/.claude/templates/coding_prompt.template.md b/.claude/templates/coding_prompt.template.md index 1ec0192b..f4852771 100644 --- a/.claude/templates/coding_prompt.template.md +++ b/.claude/templates/coding_prompt.template.md @@ -115,6 +115,13 @@ Some features involve **refactoring existing code** rather than building new fun - 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: @@ -190,6 +197,8 @@ It's ok if you only complete one feature in this session, as there will be more | "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. diff --git a/.claude/templates/coding_prompt_yolo.template.md b/.claude/templates/coding_prompt_yolo.template.md index c5d7bec4..d75cfd5f 100644 --- a/.claude/templates/coding_prompt_yolo.template.md +++ b/.claude/templates/coding_prompt_yolo.template.md @@ -82,6 +82,13 @@ Some features involve **refactoring existing code** rather than building new fun - 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: @@ -133,6 +140,8 @@ It's ok if you only complete one feature in this session, as there will be more | "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. From 4977923858c65b668d7121f9ab5fff8faa57269b Mon Sep 17 00:00:00 2001 From: Quenos Date: Tue, 13 Jan 2026 10:32:08 +0100 Subject: [PATCH 5/5] fix: address PR review comments 1. Remove "no exceptions" absolute wording (lines 84-93) - Reference feature_skip for legitimate external blockers - Add guidance for edge cases: conflicting features, ambiguous requirements, and circular dependencies 2. Add "Feature Behavior & Precedence" section to CLAUDE.md - Document that feature database becomes authoritative after init - Explain refactoring features override original spec - Clarify current codebase state is not a constraint - Note all categories are mandatory, skipping is for external blockers Co-Authored-By: Claude Opus 4.5 --- .claude/templates/coding_prompt.template.md | 9 +++++++- .../templates/coding_prompt_yolo.template.md | 9 +++++++- CLAUDE.md | 21 ++++++++++++++++++- 3 files changed, 36 insertions(+), 3 deletions(-) diff --git a/.claude/templates/coding_prompt.template.md b/.claude/templates/coding_prompt.template.md index f4852771..c31c0438 100644 --- a/.claude/templates/coding_prompt.template.md +++ b/.claude/templates/coding_prompt.template.md @@ -90,7 +90,14 @@ For example, if this were a chat app, you should perform a test that logs into t **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.** No exceptions. +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) diff --git a/.claude/templates/coding_prompt_yolo.template.md b/.claude/templates/coding_prompt_yolo.template.md index d75cfd5f..69d799d6 100644 --- a/.claude/templates/coding_prompt_yolo.template.md +++ b/.claude/templates/coding_prompt_yolo.template.md @@ -70,7 +70,14 @@ Otherwise, start servers manually and document the process. **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.** No exceptions. +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 diff --git a/CLAUDE.md b/CLAUDE.md index 51c09493..2a8e6982 100644 --- a/CLAUDE.md +++ b/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