Generate a cursor rule named `implementation-workflow.mdc`, under the `.cursor/rules/workflows` directory. This rule will provide a systematic Test-Driven Development (TDD) workflow for implementing tasks on a software project with human-in-the-loop interactive approval. The rule should be generic and reusable across different projects. It needs to accommodate various naming conventions for project documentation. For instance, design documentation might be in a system-wide `DESIGN.md` or a task-specific `DESIGN-[task_identifier].md`. Similarly, task lists might be in a system-wide `TASKS.md` or a task-specific `TASKS-[task_identifier].md`. The rule should refer to these documents generically (e.g., "the relevant design document(s)", "the active task list document"). The generated rule **must** include the following key sections with the specified details: 1. **TDD Implementation Process:** * Guidance to implement tasks sequentially as ordered in the active task list document, respecting any task grouping specified therein, following strict Red-Green-Refactor TDD cycles. * Instruction to always cross-reference relevant design document(s) for technical implementation details and product requirement document(s) (if available) for context. * Clear definition and explanation of task status updates within the task list document. Emphasize the precise order of status changes with TDD phases: * `⬜` (Pending): Default status for a new or untouched task. * `🔴` (Red Phase): Status when failing tests have been written for the task requirements. A task transitions from `⬜` to `🔴`. * `🟢` (Green Phase): Status when minimal implementation has been added to make tests pass. A task transitions from `🔴` to `🟢`. * `🔄` (Refactor Phase): Status when code is being refactored while maintaining passing tests. A task transitions from `🟢` to `🔄`. * `⭕` (Pending Approval): Status achieved **only after** completing the full Red-Green-Refactor cycle and the task implementation is ready for user review. A task transitions from `🔄` to `⭕`. * `✅` (Completed): Status achieved **only after** a task marked `⭕` has been explicitly reviewed and approved by the user. A task transitions from `⭕` to `✅`. * `❌` (Failed): Status if a task implementation is deemed unsuccessful or is rejected after review. A task typically transitions from any phase to `❌`. * `❓` (Needs Clarification): Status if more information or input is required from the user before or during task implementation. A task can transition from any phase to `❓`. * Reiterate that a task's status changes through `⬜` → `🔴` → `🟢` → `🔄` → `⭕` in sequence, with `⭕` signifying completion of TDD cycle and readiness for review. 2. **TDD Implementation Checklist:** * A step-by-step TDD checklist to be followed for each task: 1. Identify the next pending (`⬜`) task from the active task list document, strictly following the documented sequence and any specified grouping. 2. Thoroughly research requirements by consulting relevant design document(s) and any associated product requirement document(s). 3. **RED PHASE**: Write comprehensive failing tests that define the expected behavior for the task. Update task status to `🔴` (Red Phase). Tests should cover: - Happy path scenarios - Edge cases and error conditions - Input validation requirements - Integration points as specified in design documents 4. **GREEN PHASE**: Write minimal implementation code to make all tests pass. Update task status to `🟢` (Green Phase). Focus on: - Making tests pass with simplest possible code - Avoiding premature optimization - Ensuring all test assertions pass 5. **REFACTOR PHASE**: Improve code quality while maintaining all passing tests. Update task status to `🔄` (Refactor Phase). Focus on: - Applying design patterns from design document(s) - Eliminating code duplication - Improving readability and maintainability - Ensuring architectural consistency - Running tests after each refactoring step 6. Once the complete Red-Green-Refactor cycle is verifiably complete with all tests passing, immediately update the task's status to `⭕` (Pending Approval). 7. **CRITICAL**: Explicitly request user review of both the tests and implementation. This request must be clear and direct (e.g., "The TDD implementation for task '[task_name]' is complete with [X] passing tests and now marked as 'Pending Approval'. Would you like to review both the test suite and implementation before I proceed to the next task?"). 8. Patiently wait for explicit user approval. Do not proceed with new tasks while awaiting review unless otherwise directed. 9. Upon receiving unambiguous, explicit user approval, the very next action is to update the task's status from `⭕` to `✅` (Completed). 3. **TDD Code Standards:** * A general directive to rigorously adhere to all established coding best practices, style guides, and quality standards specific to the project. * Instruction to ensure complete consistency with any code examples, architectural patterns, or idioms provided in the relevant design document(s). * **Test Quality Requirements**: - Tests must be atomic, isolated, and deterministic - Test names must clearly describe the scenario being tested - Follow Arrange-Act-Assert (AAA) pattern for test structure - Maintain test coverage above project-defined thresholds (typically 90%+) - Use appropriate test doubles (mocks, stubs, fakes) for external dependencies - Write both unit tests and integration tests as specified in design documents * **Implementation Quality Requirements**: - All developed modules, classes, functions, or components must precisely match their specified responsibilities and interfaces as outlined in the design documentation - Code must pass all static analysis tools (linting, type checking) - Follow SOLID principles and design patterns specified in design documents - Maintain clean, readable, and well-documented code 4. **TDD User Approval Protocol:** * **NON-NEGOTIABLE MANDATE**: Under no circumstances proceed to the next task or consider a currently implemented task fully finalized (`✅`) without obtaining explicit, unambiguous approval from the user for both the test suite and implementation of the task marked `⭕`. * Clearly state that multiple review-feedback-revision cycles are expected and normal. Be prepared to receive detailed feedback on both tests and implementation, make all necessary revisions diligently following TDD principles, and resubmit for approval after each iteration. * **TDD-Specific Review Guidelines**: - Present test results and coverage metrics with each review request - Highlight any design decisions made during the Green and Refactor phases - Explain any trade-offs between test complexity and implementation simplicity - Document any assumptions made during test design * Instruct to implement ALL requested changes thoroughly and accurately, maintaining TDD discipline. After revisions: - Re-run the complete Red-Green-Refactor cycle if tests need modification - Ensure all tests still pass after implementation changes - Update test coverage metrics - The task remains `⭕` and requires a new request for approval * Define what constitutes explicit approval (e.g., direct affirmative statements like "approved," "tests and implementation look good, proceed," "LGTM, move on," "TDD cycle accepted"). * If user feedback is provided but lacks a clear statement of approval, the task status remains `⭕`. Do NOT interpret feedback as implicit approval. In such cases, STOP and explicitly seek clarification regarding approval status (e.g., "Thank you for this feedback. I will make these adjustments following TDD principles. To confirm, once these changes are made and all tests pass, will the task be considered approved, or is there a further review step?"). * Advise to provide a concise summary of the TDD implementation including: - Number of tests written and their coverage - Key refactoring decisions made - Any deviations from standard TDD practice and their justifications * The first and immediate action after receiving explicit user approval for a task currently in the `⭕` (Pending Approval) state is to update its status to `✅` (Completed) in the active task list document. Only then can the next task be considered. 5. **TDD Cycle Management:** * **Red Phase Requirements**: - All tests must fail for the right reasons (testing actual requirements, not syntax errors) - Tests should be comprehensive enough to guide implementation - Test scenarios must align with acceptance criteria in design documents * **Green Phase Requirements**: - Implementation must be minimal and focused solely on making tests pass - Resist the urge to implement features not covered by current tests - Prioritize making tests pass over code elegance in this phase * **Refactor Phase Requirements**: - All tests must remain passing throughout refactoring - Apply design patterns and architectural principles from design documents - Improve code quality without changing behavior - Consider performance optimizations only if specified in requirements The task order, priority, and grouping are to be strictly and solely derived from the active task list document itself. The core focus of the generated rule must be on the unyielding adherence to TDD principles, the documented implementation flow, the precise order and criteria for task status transitions (especially `⬜` → `🔴` → `🟢` → `🔄` → `⭕` → `✅`), and the paramount, non-negotiable importance of the user approval step before any task is marked complete or new work is begun.