feat(agents): Add backtracking and feedback loop to bug-fixing agent workflow

.github/agents/bug-fixing-implementer-agent.md

@@ -43,6 +43,27 @@ Each skill file is a routing hub pointing to detailed reference files under its
 
 ---
 
+## Handling a Wrong or Incomplete Test
+
+If the reproduction test is wrong, **do not fix it yourself and do not proceed**. Stop and report the problem back — test code is the responsibility of `tdd-test-writer-agent`.
+
+A test is wrong if it:
+- Passes immediately without any code change (not reproducing the bug)
+- Fails for the wrong reason (unrelated setup error, missing import, wrong assertion)
+- Tests a different code path than the one identified as the root cause
+
+In those cases:
+1. Do **not** modify the test.
+2. State clearly in your output what is wrong with the test and why it does not correctly reproduce the bug.
+3. Stop. The orchestrator will re-invoke `tdd-test-writer-agent` to fix it before you proceed.
+
+If you discover the root cause is in a **different place** than the orchestrator identified:
+1. Do **not** silently fix a different location.
+2. State clearly in your output that the root cause differs from the scope summary.
+3. Fix the actual root cause, explain the discrepancy, and let the orchestrator decide whether re-investigation is needed.
+
+---
+
 ## GREEN Phase — Fix the Bug
 
 1. Write the **minimum code** to make the failing reproduction test pass.

.github/agents/changelog-agent.md

@@ -82,7 +82,18 @@ Use `### General` for deprecations, behavioral changes, and changelog-worthy bug
 - If the component already has entries in the same subsection, add sub-bullets under the same component heading.
 - Include short code examples only if they clarify usage.
 
-### 5. Final Self-Validation
+### 5. Surfacing Problems
+
+If the changes handed off to you are inconsistent with what appears in the code — for example, the described change does not match the actual diff, or a breaking change lacks a matching migration:
+1. Do **not** document behavior that does not exist or was not actually implemented.
+2. State clearly in your output what the inconsistency is.
+3. Stop. The orchestrator will decide whether to re-invoke an earlier agent before you proceed.
+
+### 6. Re-invocation
+
+If you are re-invoked because a previous CHANGELOG entry was incorrect, misplaced, or inconsistent, read the orchestrator's correction note carefully. Do not repeat the same approach — fix the specific issue identified and confirm the entry is accurate and correctly formatted.
+
+### 7. Final Self-Validation
 
 Before finishing:
 
@@ -91,7 +102,7 @@ Before finishing:
 3. Confirm the formatting matches the existing CHANGELOG style.
 4. Confirm you updated an existing component entry instead of duplicating it when appropriate.
 
-### 6. Commit
+### 8. Commit
 
 For features:
 ```

.github/agents/component-readme-agent.md

@@ -72,6 +72,19 @@ Component documentation is located at:
 
 ---
 
+## Surfacing Problems
+
+If you find that the code changes are inconsistent, incomplete, or contradictory to what was described in the handoff:
+1. Do **not** document behavior that does not exist in the code.
+2. State clearly in your output what the inconsistency is.
+3. Stop. The orchestrator will decide whether to re-invoke an earlier agent before you proceed.
+
+## Re-invocation
+
+If you are re-invoked because a previous README update was incomplete or incorrect, read the orchestrator's correction note carefully. Do not repeat the same approach — address the specific gap or inconsistency identified and confirm the README now accurately reflects the actual code.
+
+---
+
 ## Final Self-Validation
 
 Before finishing:

.github/agents/feature-implementer-agent.md

@@ -26,7 +26,7 @@ Treat failing tests as guidance, not as the full specification.
 2. **Read the existing component source** — understand the current implementation, patterns, and conventions used in this specific component.
 3. **Read the failing tests** — understand what behaviors they are trying to prove.
 4. **Implement the feature** — write the code that satisfies the real feature contract across all affected areas.
-5. **Evaluate the tests** — if a test is redundant, overly narrow, or encodes a wrong assumption, adjust it only when justified by the feature contract.
+5. **Evaluate the tests** — if a test is redundant, overly narrow, or needs a small correction to match the real feature contract, you may adjust it. If it encodes a wrong assumption or points in the wrong direction, report it to the orchestrator for backtrack action.
 6. **Run all tests** — everything required must pass.
 7. **Refactor** — clean up for quality without expanding scope unnecessarily.
 
@@ -40,6 +40,27 @@ Check the relevant skill file for component APIs and patterns:
 
 ---
 
+## Backtrack Actions
+
+If implementation reveals that earlier work is wrong or incomplete, do not continue silently. Report it clearly so the orchestrator can backtrack and re-route as needed.
+
+Backtrack in these cases:
+- The failing tests encode the wrong feature behavior.
+- The scope summary is missing an affected area or includes the wrong one.
+- The intended implementation would introduce an unexpected breaking change.
+- README, changelog, or migration follow-through is clearly needed but was not flagged.
+
+Use this rule:
+- If the tests are directionally correct but too narrow, redundant, or need small adjustments to match the real feature contract, you may update them as part of implementation.
+- If the tests are based on the wrong feature behavior or the scope summary is materially wrong, stop and report it for backtracking instead of silently redefining the work.
+
+When reporting a backtrack action, state:
+1. What you found.
+2. Why it conflicts with the current tests or scope summary.
+3. What needs to be re-run or re-evaluated.
+
+---
+
 ## GREEN Phase — Make Tests Pass
 
 1. Write the **minimum code** to make each failing test pass.
@@ -85,7 +106,7 @@ Every new UI element must include:
 ## REFACTOR Phase — Clean Up
 
 1. **Production code**: eliminate duplication, improve naming, simplify logic, strengthen types.
-2. **Test code**: extract shared setup and sharpen assertions. Add or adjust tests only when required by the actual feature contract.
+2. **Test code**: extract shared setup and sharpen assertions.
 3. Run tests — confirm no regressions.
 
 ---

.github/agents/feature-orchestrator-agent.md

@@ -157,9 +157,30 @@ Use agents in this order:
 4. **`migration-agent`** — only if breaking changes exist
 5. **`changelog-agent`** — updates CHANGELOG.md
 
+**After each agent finishes, read its output before proceeding to the next step.** If it reports a problem, follow the backtracking rules in Step 3a before continuing forward.
+
+### Step 3a — Backtracking
+
+The workflow is a **loop, not a strict pipeline**. If any agent finds a problem with earlier work, stop and correct it before moving forward.
+
+Use these rules:
+
+| Agent reports | Backtrack action |
+|---|---|
+| Test passes immediately / doesn't reproduce the bug | Re-invoke `tdd-test-writer-agent` with the implementer's finding. Do not proceed until a properly failing test exists. |
+| The implementation shows the scope summary was wrong or incomplete | Go back to Step 1, update the scope summary, then re-run the affected agents in order. |
+| The README update exposes missing or inconsistent behavior | Re-run `feature-implementer-agent` with the gap, then re-run `component-readme-agent`. |
+| Migration work reveals an unexpected breaking change | Re-run `feature-implementer-agent` to decide whether to avoid or keep the break, then continue with `migration-agent`. |
+| The changelog entry does not match the implementation | Re-run `feature-implementer-agent` if the code must change. Otherwise clarify the scope and re-run `changelog-agent`. |
+
+When re-invoking an agent, tell it explicitly:
+- what the previous attempt produced
+- what was found to be wrong
+- what it needs to correct
+
 ### Step 4 — Verify Completeness
 
-After all agents finish, check:
+After all agents finish **without any outstanding backtrack signals**, check:
 
 - Were all affected areas covered?
 - Were public exports updated?

.github/agents/migration-agent.md

@@ -105,7 +105,18 @@ Create `index.spec.ts` in the migration folder:
 - Assert the output contains the migrated API
 - Test edge cases: files without the pattern, already-migrated files
 
-### 6. Final Self-Validation
+### 6. Surfacing Problems
+
+If you find that the breaking change is ambiguous, the old or new API is unclear, or the fix does not actually require a migration:
+1. Do **not** create a migration for a non-breaking change.
+2. State clearly in your output what the inconsistency or uncertainty is.
+3. Stop. The orchestrator will decide whether to re-invoke an earlier agent to clarify before you proceed.
+
+### 7. Re-invocation
+
+If you are re-invoked because a previous migration was incorrect or incomplete, read the orchestrator's correction note carefully. Do not repeat the same approach — address the specific issue identified, re-run `npm run test:schematics` and `npm run build:migrations`, and confirm the migration is correct.
+
+### 8. Final Self-Validation
 
 Before finishing:
 
@@ -116,7 +127,7 @@ Before finishing:
    - `npm run build:migrations`
 4. Confirm the migration updates the old API and leaves unrelated code unchanged.
 
-### 7. Commit
+### 9. Commit
 
 Use the conventional commit format with `BREAKING CHANGE:` footer:
 

.github/agents/tdd-test-writer-agent.md

@@ -30,6 +30,8 @@ You are an independent specialist, not a plan executor. Read the user's request
 You may collapse multiple requirements into fewer tests when one test can prove the contract clearly.
 Do not add extra scenarios or extra tests unless they are explicitly requested, clearly required by the feature contract, or needed for accessibility or backward compatibility.
 
+If you are **re-invoked** because a previous test was found to be wrong, read the implementer's finding carefully before writing a new test. Do not repeat the same approach — correct the specific flaw identified (wrong code path, passes immediately, broken setup) and confirm the new test fails for the right reason.
+
 ---
 
 ## Rules