@codemcp/workflows 6.0.1 → 6.0.3

package/packages/core/resources/workflows/c4-analysis.yaml

@@ -0,0 +1,471 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'c4-analysis'
+description: 'A comprehensive workflow for analyzing legacy systems using C4 methodology. Progressively understand system architecture from context to components, with scope limiting for large codebases.'
+initial_state: 'discovery'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'architecture'
+  complexity: 'medium'
+  bestFor:
+    - 'Legacy system analysis'
+    - 'System understanding and documentation'
+    - 'Architecture discovery'
+    - 'Modernization planning'
+  useCases:
+    - 'Analyze existing codebase for modernization'
+    - 'Document undocumented legacy systems'
+    - 'Understand system architecture before enhancements'
+  examples:
+    - 'Analyze a legacy Java monolith for microservices migration'
+    - 'Document architecture of inherited Node.js application'
+    - 'Understand legacy system before adding new features'
+  requiresDocumentation: true
+
+# States with default instructions and transitions
+states:
+  discovery:
+    description: 'Initial system discovery and inventory with scope limiting'
+    default_instructions: >
+      Create discovery notes file at `$DISCOVERY_FILE` with comprehensive system information.
+
+      ```markdown
+      # Legacy System Discovery Notes
+
+      *This file serves as long-term memory for the C4 analysis workflow. It contains comprehensive findings and insights that persist across all analysis phases. Progress tracking is handled in the plan file.*
+
+      ## System Overview
+
+      ### Technology Stack
+      <!-- Record the identified technology stack -->
+      - **Primary Language**:
+      - **Framework**:
+      - **Build System**:
+      - **Database**:
+      - **Other Technologies**:
+
+      ### Repository Structure
+      <!-- Map the basic folder structure -->
+      ```
+      project-root/
+      ├── src/                 # Source code
+      ├── docs/               # Documentation (if exists)
+      ├── tests/              # Test files
+      ├── config/             # Configuration files
+      ├── [other folders]     # Other significant folders
+      └── [key files]         # Important root-level files
+      ```
+
+      ### Key Configuration Files
+      <!-- List important configuration files found -->
+      - **package.json / pom.xml / build.gradle**: Build and dependency configuration
+      - **README.md**: Project documentation (if exists)
+      - **[Other config files]**: Purpose and significance
+
+      ## Existing Documentation
+      <!-- Record any existing documentation found -->
+      - **[Document 1]**: Location and content summary
+      - **[Document 2]**: Location and content summary
+      - **Documentation Quality**: Assessment of existing docs
+
+      ## System Architecture Findings
+
+      ### Context Level (C4 Level 1)
+      <!-- System context findings - updated during context analysis phase -->
+
+      #### External Systems
+      - **[External System 1]**: Purpose, communication method, data exchanged
+      - **[External System 2]**: Purpose, communication method, data exchanged
+
+      #### User Types
+      - **[User Type 1]**: Role, needs, interaction patterns
+      - **[User Type 2]**: Role, needs, interaction patterns
+
+      #### System Boundaries
+      - **Inside the system**: Core components and responsibilities
+      - **Outside the system**: External dependencies and interfaces
+
+      ### Container Level (C4 Level 2)
+      <!-- Container architecture findings - updated during container analysis phase -->
+
+      #### Identified Containers
+      - **[Container 1 Name]** - `path/to/container`
+        - **Technology**:
+        - **Purpose**:
+        - **Interfaces**:
+        - **Data Storage**:
+        - **Communication**: How it communicates with other containers
+
+      - **[Container 2 Name]** - `path/to/container`
+        - **Technology**:
+        - **Purpose**:
+        - **Interfaces**:
+        - **Data Storage**:
+        - **Communication**: How it communicates with other containers
+
+      #### Container Interactions
+      - **[Container A] → [Container B]**: Communication method and purpose
+      - **[Container B] → [External System]**: Communication method and purpose
+
+      ### Component Level (C4 Level 3)
+      <!-- Component analysis findings - updated during component analysis phase -->
+
+      #### Container 1 Components
+      - **[Component 1.1]** - `path/to/component`
+        - **Responsibilities**:
+        - **Interfaces**:
+        - **Dependencies**:
+        - **Design Patterns**:
+        - **Key Insights**:
+
+      - **[Component 1.2]** - `path/to/component`
+        - **Responsibilities**:
+        - **Interfaces**:
+        - **Dependencies**:
+        - **Design Patterns**:
+        - **Key Insights**:
+
+      #### Container 2 Components
+      - **[Component 2.1]** - `path/to/component`
+        - **Responsibilities**:
+        - **Interfaces**:
+        - **Dependencies**:
+        - **Design Patterns**:
+        - **Key Insights**:
+
+      - **[Component 2.2]** - `path/to/component`
+        - **Responsibilities**:
+        - **Interfaces**:
+        - **Dependencies**:
+        - **Design Patterns**:
+        - **Key Insights**:
+
+      ## Analysis Insights and Observations
+
+      ### Discovery Phase Insights
+      <!-- Key insights discovered during initial discovery -->
+
+      ### Context Analysis Insights
+      <!-- Important findings about system context and external interfaces -->
+
+      ### Container Analysis Insights
+      <!-- Key architectural insights about container structure and communication -->
+
+      ### Component Analysis Insights
+      <!-- Detailed insights about individual components and their design -->
+
+      ### Cross-Cutting Concerns
+      <!-- Insights that span multiple components or containers -->
+      - **Security**:
+      - **Performance**:
+      - **Data Flow**:
+      - **Error Handling**:
+
+      ## Technical Debt and Improvement Opportunities
+
+      ### Technical Debt Identified
+      <!-- Technical debt discovered during analysis -->
+      - **[Debt Item 1]**: Description, impact, and location
+      - **[Debt Item 2]**: Description, impact, and location
+
+      ### Modernization Opportunities
+      <!-- Areas identified for potential modernization -->
+      - **[Opportunity 1]**: Description, benefits, and approach
+      - **[Opportunity 2]**: Description, benefits, and approach
+
+      ### Architecture Improvements
+      <!-- Potential architectural improvements identified -->
+      - **[Improvement 1]**: Description, benefits, and implementation approach
+      - **[Improvement 2]**: Description, benefits, and implementation approach
+
+      ## API and Integration Analysis
+
+      ### External APIs
+      <!-- External APIs the system uses or provides -->
+      - **[API 1]**: Purpose, technology, testing approach
+      - **[API 2]**: Purpose, technology, testing approach
+
+      ### Internal Interfaces
+      <!-- Internal interfaces between components/containers -->
+      - **[Interface 1]**: Components involved, communication method
+      - **[Interface 2]**: Components involved, communication method
+
+      ### Testing Strategy Recommendations
+      <!-- Recommendations for end-to-end API testing -->
+      - **External API Testing**: Approach and tools
+      - **Internal Interface Testing**: Approach and tools
+      - **Test Data Strategy**: Data management approach
+
+      ## Questions and Unknowns
+
+      ### Open Questions
+      <!-- Questions that arose during analysis and need investigation -->
+      - **[Question 1]**: Description and why it's important
+      - **[Question 2]**: Description and why it's important
+
+      ### Areas Needing Further Investigation
+      <!-- Areas that need deeper analysis -->
+      - **[Area 1]**: What needs investigation and why
+      - **[Area 2]**: What needs investigation and why
+
+      ## Enhancement Readiness Assessment
+
+      ### Current State Assessment
+      - **Documentation Quality**:
+      - **Code Quality**:
+      - **Test Coverage**:
+      - **Development Environment**:
+      - **Deployment Process**:
+
+      ### Enhancement Recommendations
+      - **Immediate Improvements**: Quick wins that would help
+      - **Medium-term Enhancements**: Larger improvements to consider
+      - **Long-term Modernization**: Strategic modernization opportunities
+
+      ---
+
+      ## Instructions for Use
+
+      **Purpose**: This file serves as the comprehensive long-term memory for the C4 analysis workflow. All findings, insights, and discoveries should be recorded here for future reference.
+
+      **For the LLM**:
+      - **During Discovery**: Fill in system overview, technology stack, and initial architecture sketch
+      - **During Context Analysis**: Add context findings to the Context Level section
+      - **During Container Analysis**: Document container findings in the Container Level section
+      - **During Component Analysis**: Add detailed component analysis to the Component Level section
+      - **Throughout**: Add insights, observations, technical debt, and improvement opportunities as discovered
+
+      **Long-term Memory**: This file preserves all analysis findings and serves as the knowledge base for future development work. Unlike the plan file (which tracks progress), this file maintains the comprehensive understanding of the system.
+
+      **Reference**: This file should be referenced throughout the workflow and used as input for the final documentation consolidation phase.
+
+      ---
+
+      *This discovery file was created during C4 legacy system analysis and serves as the comprehensive long-term memory of all findings, insights, and architectural understanding.*
+      ```
+
+      **SCOPE LIMIT**: Focus ONLY on repository root, main config files, and top-level structure.
+
+      **STEP 1:** Scan repository root
+      - Identify key files (package.json, pom.xml, build.gradle, README.md, etc.)
+      - Map basic folder structure (src/, docs/, tests/, config/, etc.)
+      - Create hierarchical sketch of potential containers and components
+
+      **STEP 2:** Identify technology stack
+      - Examine configuration files for language, framework, and build system information
+      - For Java: Look for Maven/Gradle structure, Spring configuration, package organization
+      - For Node.js: Check package.json, identify framework, examine folder structure
+
+      **STEP 3:** Document findings
+      - Record existing documentation files
+      - Fill in the DISCOVERY.md template with your findings
+      - Update plan file with discovery progress
+      - Add discovered containers and components as tasks for later phases
+    transitions:
+      - trigger: 'continue_discovery'
+        to: 'discovery'
+        instructions: >
+          Expand the repository scan, refine technology stack identification, and enhance the hierarchical sketch of containers and components.
+          Update `$DISCOVERY_FILE` with new findings and add newly discovered items to the plan file as tasks for later analysis phases.
+        transition_reason: 'Discovery needs more investigation and refinement'
+
+      - trigger: 'discovery_complete'
+        to: 'context_analysis'
+        additional_instructions: |
+          **STEP 1:** Set up project documents for living documentation
+          - Execute: `setup_project_docs({ architecture: "c4", requirements: "none", design: "comprehensive" })`
+
+          **STEP 2:** Review created documentation files
+          - Read `$ARCHITECTURE_DOC` and `$DESIGN_DOC` to understand their structure
+
+          **STEP 3:** Begin context analysis preparation
+          - Review `$DISCOVERY_FILE` findings
+          - Prepare to enhance documentation based on discovery findings
+          - Continue enhancement throughout context analysis phase
+        transition_reason: 'Initial discovery complete, ready for context analysis'
+
+  context_analysis:
+    description: 'System context analysis (C4 Level 1) - boundaries and external interfaces'
+    default_instructions: >
+      Analyze system context and external interfaces (C4 Level 1). Reference `$DISCOVERY_FILE` for long-term memory.
+
+      **SCOPE LIMIT**: Focus ONLY on external interfaces and system boundaries.
+
+      **STEP 1:** Identify external entities
+      - Map external systems the legacy system communicates with
+      - Catalog user types and personas who interact with the system
+      - Document external dependencies (databases, APIs, services)
+
+      **STEP 2:** Understand boundaries
+      - Clarify system boundaries and responsibilities
+      - Define what's inside vs outside the system
+      - Map data flows between system and external entities
+
+      **STEP 3:** Enhance living documentation
+      - Update `$ARCHITECTURE_DOC` with context findings
+      - Update `$DESIGN_DOC` with external interface details
+      - Update `$DISCOVERY_FILE` with all context analysis findings
+      - Record progress in plan file
+    transitions:
+      - trigger: 'refine_context'
+        to: 'context_analysis'
+        instructions: >
+          Investigate more external interfaces and clarify system boundaries.
+          Refine understanding of external dependencies and update `$DISCOVERY_FILE` and plan file with refined findings.
+        transition_reason: 'Context analysis needs further refinement'
+
+      - trigger: 'need_more_discovery'
+        to: 'discovery'
+        additional_instructions: 'Context analysis revealed gaps in discovery. Focus on the specific areas identified that need further investigation.'
+        transition_reason: 'Context work revealed need for additional discovery'
+
+      - trigger: 'context_complete'
+        to: 'container_analysis'
+        additional_instructions: |
+          **Plan container analysis documentation** with the user:
+          - How to structure analysis files (one file per container or consolidated, folder structure options)
+          - Define container factsheet template format
+
+          Record documentation plan and component analysis template in the development plan file.
+        transition_reason: 'System context is understood, ready for container analysis'
+
+  container_analysis:
+    description: 'Container analysis (C4 Level 2) - high-level system architecture'
+    default_instructions: >
+      Analyze containers and services (C4 Level 2). Reference `$DISCOVERY_FILE` for container sketch and long-term memory.
+
+      **SCOPE LIMIT**: Focus on major containers, services, and modules only.
+
+      **STEP 1:** Identify application containers
+      - Map main application containers (web app, API, services)
+      - Document databases and data stores
+      - Understand deployment architecture
+
+      **STEP 2:** Document communication patterns
+      - Map communication pathways between containers
+      - Identify protocols and integration methods
+      - Record data exchange patterns
+
+      **STEP 3:** Enhance living documentation
+      - Update `$ARCHITECTURE_DOC` with C4 Level 2 findings
+      - Update `$DESIGN_DOC` with container interaction details
+      - Update `$DISCOVERY_FILE` with container analysis findings
+      - Add component analysis tasks to plan file
+    transitions:
+      - trigger: 'continue_container_analysis'
+        to: 'container_analysis'
+        instructions: >
+          Investigate more containers and refine communication patterns.
+          Enhance architectural understanding and update `$DISCOVERY_FILE` and plan file with progress.
+        transition_reason: 'Container analysis continues with more containers to analyze'
+
+      - trigger: 'need_context_refinement'
+        to: 'context_analysis'
+        additional_instructions: 'Container analysis revealed context issues. Refine system context based on container insights.'
+        transition_reason: 'Container work revealed need to refine context understanding'
+
+      - trigger: 'containers_complete'
+        to: 'component_analysis'
+        additional_instructions: |
+          **Plan component analysis documentation** with the user:
+          - How to structure analysis files (one file per component or consolidated format)
+          - Define component factsheet template
+
+          **Record documentation plan** in the development plan file with template format and file creation instructions.
+        transition_reason: 'Container architecture is understood, ready for detailed component analysis'
+
+  component_analysis:
+    description: 'Component analysis (C4 Level 3) - detailed component-by-component analysis'
+    default_instructions: >
+      Analyze components in detail (C4 Level 3). Reference `$DISCOVERY_FILE` for component information and long-term memory.
+
+      **SCOPE LIMIT**: Analyze ONE component at a time. User selects which components to focus on.
+
+      **STEP 1:** Deep dive into component
+      - Select next component from plan file task list
+      - Document responsibilities and interfaces
+      - Map internal component relationships and dependencies
+
+      **STEP 2:** Analyze design patterns
+      - Identify and document component-level design patterns
+      - Record architectural decisions and rationale
+      - Capture key implementation insights
+
+      **STEP 3:** Enhance living documentation and track progress
+      - Update `$DESIGN_DOC` with detailed component analysis
+      - Update `$ARCHITECTURE_DOC` with C4 Level 3 details
+      - Update `$DISCOVERY_FILE` with component findings
+      - Mark component as complete in plan file
+      - Ask user which component to analyze next
+    transitions:
+      - trigger: 'analyze_next_component'
+        to: 'component_analysis'
+        instructions: >
+          Select another component from plan file task list and perform detailed analysis.
+          Mark completed component tasks in plan file and ask user for next component selection.
+        transition_reason: 'Continuing systematic component analysis'
+
+      - trigger: 'need_container_refinement'
+        to: 'container_analysis'
+        additional_instructions: 'Component analysis revealed container issues. Refine container architecture based on component insights.'
+        transition_reason: 'Component work revealed need to refine container understanding'
+
+      - trigger: 'components_complete'
+        to: 'documentation_consolidation'
+        transition_reason: 'Component analysis complete, ready to consolidate documentation'
+
+  documentation_consolidation:
+    description: 'Consolidate findings into comprehensive documentation'
+    default_instructions: >
+      Finalize documentation and prepare recommendations. The `$ARCHITECTURE_DOC` and `$DESIGN_DOC` have been enhanced throughout analysis phases.
+
+      **STEP 1:** Review analysis findings
+      - Review `$DISCOVERY_FILE` for all findings and insights
+      - Verify completeness of C4 levels (Context, Container, Component)
+
+      **STEP 2:** Polish living documentation
+      - Final review and polish of `$ARCHITECTURE_DOC`
+      - Final review and polish of `$DESIGN_DOC`
+      - Ensure all C4 levels are comprehensively documented
+
+      **STEP 3:** Prepare recommendations
+      - Document modernization opportunities and technical debt findings
+      - Prepare enhancement recommendations based on analysis
+      - Finalize API testing strategy recommendations
+      - Update plan file with consolidation progress
+    transitions:
+      - trigger: 'refine_documentation'
+        to: 'documentation_consolidation'
+        instructions: >
+          Enhance architecture and design documentation and add more detail to recommendations.
+          Improve consolidation quality and update plan file with progress.
+        transition_reason: 'Documentation needs further refinement and enhancement'
+
+      - trigger: 'need_more_analysis'
+        to: 'component_analysis'
+        additional_instructions: 'Documentation revealed gaps in component analysis. Focus on the specific components that need more investigation.'
+        transition_reason: 'Documentation work revealed need for additional component analysis'
+
+      - trigger: 'documentation_complete'
+        to: 'analysis_complete'
+        transition_reason: 'Documentation is complete, analysis finished'
+
+  analysis_complete:
+    description: 'Legacy system analysis complete'
+    default_instructions: >
+      Legacy system analysis is complete. The system has been thoroughly analyzed using C4 methodology.
+
+      **Final deliverables:**
+      - Comprehensive system documentation (C4-based architecture and design documents)
+      - `$DISCOVERY_FILE` with complete analysis findings
+      - Enhancement recommendations
+      - API testing strategy
+      - Modernization roadmap
+
+      The analysis provides a foundation for future development. Consider using other workflows (waterfall, epcc, etc.) with the comprehensive understanding gained.
+    transitions:
+      - trigger: 'refine_analysis'
+        to: 'component_analysis'
+        additional_instructions: 'Refine specific aspects of analysis. Focus on areas that need additional investigation.'
+        transition_reason: 'Analysis review revealed need for additional component analysis'

package/packages/core/resources/workflows/epcc.yaml

@@ -0,0 +1,183 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'epcc'
+description: "A comprehensive development workflow based on Anthropic's best practices: Explore, Plan, Code, Commit - ideal for smaller features and iterative development"
+initial_state: 'explore'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'code'
+  complexity: 'medium'
+  bestFor:
+    - 'Medium-sized features'
+    - 'Iterative development'
+    - 'Research-heavy tasks'
+    - 'Exploratory coding'
+  useCases:
+    - 'Adding a new API endpoint'
+    - 'Implementing a new algorithm'
+    - 'Integrating a third-party service'
+  examples:
+    - 'Add user profile management'
+    - 'Implement search functionality'
+    - 'Create data export feature'
+
+# States with default instructions and transitions
+states:
+  explore:
+    description: 'Research and exploration phase - understanding the problem space'
+    default_instructions: |
+      Research the codebase to understand existing patterns and gather context about the problem space.
+
+      - If uncertain about conventions or rules, ask the user about them
+      - Read relevant files and documentation
+      - If `$REQUIREMENTS_DOC` exists: Understand and document requirements there
+      - Otherwise: Document requirements in your task management system
+
+      Focus on understanding without writing code yet. Document your findings and create tasks as needed.
+    transitions:
+      - trigger: 'exploration_complete'
+        to: 'plan'
+        additional_instructions: 'Present the plan to the user, describing the impact of the changes.'
+        transition_reason: 'Sufficient understanding gained, ready to create implementation plan'
+
+  plan:
+    description: 'Planning phase - creating a detailed implementation strategy'
+    default_instructions: |
+      Create a detailed implementation strategy based on your exploration:
+
+      - If `$REQUIREMENTS_DOC` exists: Base your strategy on requirements from it
+      - Otherwise: Use existing task context
+
+      Break down the work into specific, actionable tasks. Consider edge cases, dependencies, and potential challenges.
+
+      - If architectural changes needed and `$ARCHITECTURE_DOC` exists: Document in `$ARCHITECTURE_DOC`
+      - Otherwise: Create tasks to track architectural decisions
+
+      - If `$DESIGN_DOC` exists: Adhere to the design in it
+      - Otherwise: Elaborate design options and present them to the user
+
+      Document the planning work thoroughly and create implementation tasks as part of the code phase as needed.
+    transitions:
+      - trigger: 'need_more_exploration'
+        to: 'explore'
+        additional_instructions: 'Focus on the specific areas that need clarification and ask the user about needs and preferences.'
+        transition_reason: 'Planning work revealed need for more exploration'
+
+      - trigger: 'plan_complete'
+        to: 'code'
+        transition_reason: 'Implementation plan is complete and ready for coding'
+        review_perspectives:
+          - perspective: 'architect'
+            prompt: 'Review implementation strategy, design decisions, and integration approach for soundness and maintainability. Ensure the plan aligns with existing system architecture and follows best practices.'
+          - perspective: 'security_expert'
+            prompt: 'Assess security considerations and potential risks in the planned implementation approach. Review data handling, authentication, and potential vulnerabilities.'
+
+      - trigger: 'abandon_feature'
+        to: 'explore'
+        instructions: >
+          Feature development abandoned during planning. Return to exploration state for new tasks.
+          Task history will remain for future reference.
+        additional_instructions: 'Feature development abandoned during planning. Clean up any planning work and prepare for new tasks.'
+        transition_reason: 'User decided to abandon feature during planning phase'
+
+  code:
+    description: 'Implementation phase - writing and building the solution'
+    default_instructions: |
+      Follow your plan to build the solution:
+
+      - If `$DESIGN_DOC` exists: Follow the design from it
+      - Otherwise: Elaborate design options and present them to the user
+      - If `$ARCHITECTURE_DOC` exists: Build according to the architecture from it
+      - Otherwise: Elaborate architectural options and present them to the user
+      - If `$REQUIREMENTS_DOC` exists: Ensure requirements from it are met
+      - Otherwise: Ensure existing requirements are met based on your task context
+
+      Write clean, well-structured code with proper error handling. Prevent regression by building, linting, and executing existing tests. Stay flexible and adapt the plan as you learn more during implementation. Update task progress and create new tasks as needed.
+    transitions:
+      - trigger: 'need_replanning'
+        to: 'plan'
+        additional_instructions: "Consider what you've learned during coding and adjust the plan accordingly. Document the changes and reasons."
+        transition_reason: 'Implementation work revealed need to revise the plan'
+
+      - trigger: 'need_more_exploration'
+        to: 'explore'
+        additional_instructions: 'Focus on the specific areas that are blocking implementation progress.'
+        transition_reason: 'Implementation work revealed need for more exploration'
+
+      - trigger: 'code_complete'
+        to: 'commit'
+        transition_reason: 'Core implementation is complete, ready for finalization'
+        review_perspectives:
+          - perspective: 'senior_software_developer'
+            prompt: 'Review code quality, best practices, testing coverage, and readiness for production deployment. Ensure the implementation follows coding standards and is maintainable.'
+          - perspective: 'performance_engineer'
+            prompt: 'Evaluate performance impact, resource efficiency, and scalability of the implemented solution. Check for potential bottlenecks or optimization opportunities.'
+
+      - trigger: 'abandon_feature'
+        to: 'explore'
+        instructions: >
+          Feature development abandoned during implementation. Clean up any incomplete code and return to exploration.
+          Task history and any completed work will remain for future reference.
+        additional_instructions: 'Clean up any incomplete code and prepare for new tasks.'
+        transition_reason: 'User decided to abandon feature during implementation'
+
+  commit:
+    description: 'Code cleanup and documentation finalization'
+    default_instructions: >
+      Ensure code quality and documentation accuracy through systematic cleanup and review.
+
+      **STEP 1: Code Cleanup**
+
+      Systematically clean up development artifacts:
+
+      1. **Remove Debug Output**: Search for and remove all temporary debug output statements used during development.
+         Look for language-specific debug output methods (console logging, print statements, debug output functions).
+         Remove any debugging statements that were added for development purposes.
+
+      2. **Review TODO/FIXME Comments**:
+         - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred
+         - Remove completed TODOs
+         - Convert remaining TODOs to proper issue tracking if needed
+
+      3. **Remove Debugging Code Blocks**:
+         - Remove temporary debugging code, test code blocks, and commented-out code
+         - Clean up any experimental code that's no longer needed
+         - Ensure proper error handling replaces temporary debug logging
+
+      **STEP 2: Documentation Review**
+
+      Review and update documentation to reflect final implementation:
+
+      1. **Update Long-Term Memory Documents**: Based on what was actually implemented:
+         - If `$REQUIREMENTS_DOC` exists: Update it if requirements changed during development
+         - If `$ARCHITECTURE_DOC` exists: Update it if architectural impacts were identified
+         - If `$DESIGN_DOC` exists: Update it if design details were refined or changed
+         - Otherwise: Document any changes in the plan file
+      2. **Compare Against Implementation**: Review documentation against actual implemented functionality
+      3. **Update Changed Sections**: Only modify documentation sections that have functional changes
+      4. **Remove Development Progress**: Remove references to development iterations, progress notes, and temporary decisions
+      5. **Focus on Final State**: Ensure documentation describes the final implemented state, not the development process
+      6. **Ask User to Review Document Updates**
+
+      **STEP 3: Final Validation**
+
+      - Run existing tests to ensure cleanup didn't break functionality
+      - Verify documentation accuracy with a final review
+      - Ensure code is ready for production/delivery
+
+      Update task progress and mark completed work as you finalize the feature.
+    transitions:
+      - trigger: 'need_code_changes'
+        to: 'code'
+        additional_instructions: 'Focus on the problems identified during final review.'
+        transition_reason: 'Final review found issues requiring code changes'
+
+      - trigger: 'commit_complete'
+        to: 'explore'
+        transition_reason: 'Feature delivery complete, ready for next task'
+
+      - trigger: 'abandon_feature'
+        to: 'explore'
+        additional_instructions: 'Clean up any finalization artifacts and prepare for new tasks.'
+        transition_reason: 'User decided to abandon feature during finalization'