@codemcp/workflows-core 5.2.1 → 5.2.3

package/resources/workflows/tdd.yaml

@@ -27,12 +27,17 @@ states:
   explore:
     description: 'Research and exploration phase - understanding the problem space and codebase'
     default_instructions: |
-      You are in the TDD exploration phase.
-      Your main objective now is to gather context about what needs to be developed. Focus on the WHY and WHAT, not the HOW.
-      Research the codebase, understand existing patterns,
-      If you are not certain 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 them in your task management system.
-       Don't write code or tests yet - focus on understanding. Document your findings and create tasks as needed.
+      **STEP 1:** Gather context about what needs to be developed. Focus on the WHY and WHAT, not the HOW.
+
+      **STEP 2:** Research the codebase and understand existing patterns.
+      - Ask the user about conventions or rules if uncertain
+      - Read relevant files and documentation
+      - If `$REQUIREMENTS_DOC` exists, understand and document requirements there, otherwise document in your task management system
+
+      **STEP 3:** Document your findings and create tasks as needed.
+      - Don't write code or tests yet
+      - Focus on understanding the problem space
+      - Prepare for the RED phase of the TDD cycle
     transitions:
       - trigger: 'exploration_complete'
         to: 'red'
@@ -50,19 +55,23 @@ states:
   red:
     description: 'RED phase - Write a failing test that defines the expected behavior'
     default_instructions: |
-      You are in the RED phase of TDD. Write a failing test that defines the expected behavior.
-
-      **CRITICAL QUALITY GATE**: Before writing the test, ask the user about:
-      1. What type of test is appropriate (unit, integration, acceptance, etc.)
-      2. Validate with the user that your test actually tests what needs to be developed
-
-      Write a test that:
-      - Clearly defines the expected behavior
-      - Will fail initially (since the functionality doesn't exist yet)
-      - Is specific and focused on one aspect of the functionality
-      - Uses appropriate assertions (not assert(true) or similar meaningless checks)
-
-       Run the test to confirm it fails for the right reason. Document the test and update task progress as needed.
+      Write a failing test that defines the expected behavior for the feature.
+
+      **STEP 1:** Validate test approach with the user before writing.
+      - Determine what type of test is appropriate (unit, integration, acceptance, etc.)
+      - Confirm your test will validate the actual requirements
+      - Ensure alignment with the feature specification
+
+      **STEP 2:** Write a focused, meaningful test.
+      - Clearly define the expected behavior
+      - Will fail initially since functionality doesn't exist yet
+      - Focus on one specific aspect of the functionality
+      - Use appropriate assertions (not meaningless checks like assert(true))
+
+      **STEP 3:** Validate test failure.
+      - Run the test to confirm it fails for the right reason
+      - Document the test and expected failure mode
+      - Update task progress
     transitions:
       - trigger: 'test_written_and_failing'
         to: 'green'
@@ -81,22 +90,23 @@ states:
   green:
     description: 'GREEN phase - Write only the necessary code to make the test pass'
     default_instructions: |
-      You are in the GREEN phase of TDD. Write only the necessary code to make the failing test pass with a proper implementation.
-
-      **CRITICAL QUALITY GATE**: Verify your implementation has NO dirty hacks such as:
-      - assert(true) or similar meaningless assertions
-      - Hardcoded return values that don't represent real logic
-      - Shortcuts that bypass the actual functionality
-      - Copy-paste code without understanding
-
-      Focus on:
-      - Making the test pass with real, working code
-      - Writing only what's necessary (no over-engineering)
-      - Ensuring the solution actually solves the problem
-      - Implementing proper logic, not shortcuts
-      - Running the test to confirm it passes
-
-       Document your implementation approach and update task progress as needed.
+      Implement the necessary code to make the failing test pass with proper functionality.
+
+      **STEP 1:** Write real, working implementation.
+      - Make the test pass with actual logic, not shortcuts
+      - Write only what's necessary (no over-engineering)
+      - Avoid dirty hacks such as hardcoded return values or meaningless assertions
+      - Focus on solving the actual problem
+
+      **STEP 2:** Validate implementation quality.
+      - Run the test to confirm it passes
+      - Verify no shortcuts or copy-paste code without understanding
+      - Ensure the solution actually solves the problem
+      - Check that logic is proper, not a bypass
+
+      **STEP 3:** Document and track progress.
+      - Document your implementation approach
+      - Update task progress
     transitions:
       - trigger: 'test_passing'
         to: 'refactor'
@@ -119,23 +129,24 @@ states:
   refactor:
     description: 'REFACTOR phase - Improve code quality while keeping tests green (cleanup phase)'
     default_instructions: |
-      You are in the REFACTOR phase of TDD. This is the cleanup phase - improve code quality while keeping all tests green.
+      Improve code quality while keeping all tests green. This is the cleanup phase where you enhance readability and maintainability.
 
-      Focus on:
-      - Removing code duplication
-      - Improving variable and function names
-      - Extracting methods for better organization
-      - Simplifying complex logic
-      - Enhancing readability and maintainability
-      - Applying appropriate design patterns
+      **STEP 1:** Identify improvement opportunities.
+      - Remove code duplication
+      - Improve variable and function names
+      - Extract methods for better organization
+      - Simplify complex logic
+      - Apply appropriate design patterns
 
-      **Safety Rules**:
+      **STEP 2:** Make incremental improvements safely.
       - Run tests after each refactoring change
-      - If any test breaks, immediately revert the change
-      - Make small, incremental improvements
-      - Stop when code is clean and no obvious improvements remain
+      - Immediately revert any change that breaks tests
+      - Make small, focused improvements
+      - Stop when code is clean with no obvious improvements remaining
 
-       Document significant refactoring decisions and update task progress as needed.
+      **STEP 3:** Document and complete.
+      - Document significant refactoring decisions
+      - Update task progress
     transitions:
       - trigger: 'refactoring_complete'
         to: 'red'

package/resources/workflows/waterfall.yaml

@@ -28,14 +28,15 @@ states:
   requirements:
     description: 'Gathering and analyzing requirements'
     default_instructions: |
-      Make yourself familiar with the code base.
-      Focus on understanding their goals, scope, constraints, and success criteria, e. g.
-      • Who are the key stakeholders? (end users, business owners, technical teams)
-      • Which requirements are must-have vs nice-to-have?
-      • How will you measure success? What are the acceptance criteria?
-      • What are your time, budget, technical, or regulatory constraints?
-      • What existing systems must this integrate with?
-       Break down their needs into specific requirements in $REQUIREMENTS_DOC. Create actionable tasks referencing those requirements.
+      Familiarize yourself with the code base and understand project goals, scope, constraints, and success criteria.
+
+      - Who are the key stakeholders? (end users, business owners, technical teams)
+      - Which requirements are must-have vs nice-to-have?
+      - How will you measure success? What are the acceptance criteria?
+      - What are your time, budget, technical, or regulatory constraints?
+      - What existing systems must this integrate with?
+
+      Document all requirements in `$REQUIREMENTS_DOC`. Create actionable tasks referencing those requirements.
     transitions:
       - trigger: 'requirements_complete'
         to: 'design'
@@ -49,11 +50,11 @@ states:
   design:
     description: 'Technical design and architecture planning'
     default_instructions: |
-      You are in the design phase. Re-analyze important interfaces of the application.
-      Review requirements from $REQUIREMENTS_DOC and design the technical solution
-      Focus on HOW to implement what's needed including architecture, technologies, data models, API design, and quality goals.
-      Clarify performance expectations and technology preferences if not already obvious from the current analysis.
-       Document architectural decisions in $ARCHITECTURE_DOC and detailed design in $DESIGN_DOC. Create tasks and ensure the approach is solid before implementation."
+      Review requirements from `$REQUIREMENTS_DOC` and design the technical solution.
+
+      Focus on HOW to implement what's needed including architecture, technologies, data models, API design, and quality goals. Clarify performance expectations and technology preferences if not already obvious from the current analysis.
+
+      Document architectural decisions in `$ARCHITECTURE_DOC` and detailed design in `$DESIGN_DOC`. Create tasks and ensure the approach is solid before implementation.
     transitions:
       - trigger: 'need_more_requirements'
         to: 'requirements'
@@ -72,10 +73,13 @@ states:
   implementation:
     description: 'Building the solution according to design'
     default_instructions: |
-      Follow the architecture from $ARCHITECTURE_DOC and detailed design from $DESIGN_DOC to build the solution. Before starting, clarify the approach:
-      • Should this be implemented incrementally or all at once? Any specific order of implementation?
-      • Are there high-risk parts that need extra validation or careful implementation?
-       Ensure requirements from $REQUIREMENTS_DOC are met. Focus on code structure, error handling, security, and maintainability. Write clean, well-documented code and include basic testing. Update task progress during implementation work.
+      Follow the architecture from `$ARCHITECTURE_DOC` and detailed design from `$DESIGN_DOC` to build the solution.
+
+      Before starting, clarify the approach:
+      - Should this be implemented incrementally or all at once? Any specific order of implementation?
+      - Are there high-risk parts that need extra validation or careful implementation?
+
+      Ensure requirements from `$REQUIREMENTS_DOC` are met. Focus on code structure, error handling, security, and maintainability. Write clean, well-documented code and include basic testing. Update task progress during implementation work.
     transitions:
       - trigger: 'need_design_changes'
         to: 'design'
@@ -98,7 +102,19 @@ states:
 
   qa:
     description: 'Quality assurance and code review'
-    default_instructions: 'You are in the quality assurance phase. Take the following specific actions: 1) Syntax Check: Run syntax checking tools or validate syntax manually, 2) Build Project: Build the project to verify it compiles without errors, 3) Run Linter: Execute linting tools to ensure code style consistency, 4) Execute Tests: Run existing tests to verify functionality. Then conduct a multi-perspective code review from security, performance, UX, maintainability, and requirement compliance perspectives. Verify implementation matches $DESIGN_DOC specifications and fulfills the targeted requirements from $REQUIREMENTS_DOC. Update task progress and mark completed work during QA review.'
+    default_instructions: |
+      Perform systematic quality checks and code review:
+
+      **STEP 1: Automated Quality Checks**
+      - Run syntax checking tools or validate syntax manually
+      - Build the project to verify it compiles without errors
+      - Execute linting tools to ensure code style consistency
+      - Run existing tests to verify functionality
+
+      **STEP 2: Multi-Perspective Code Review**
+      Conduct code review from security, performance, UX, maintainability, and requirement compliance perspectives. Verify implementation matches `$DESIGN_DOC` specifications and fulfills targeted requirements from `$REQUIREMENTS_DOC`.
+
+      Update task progress and mark completed work during QA review.
     transitions:
       - trigger: 'need_implementation_fixes'
         to: 'implementation'
@@ -116,7 +132,12 @@ states:
 
   testing:
     description: 'Comprehensive testing and validation'
-    default_instructions: 'You are in the testing phase. Create comprehensive test plans, write and execute tests, validate feature completeness, and ensure everything works as expected. Focus on test coverage, edge cases, integration testing, and user acceptance validation.'
+    default_instructions: |
+      Create and execute comprehensive test plans to validate feature completeness.
+
+      - Write and execute tests with focus on test coverage and edge cases
+      - Conduct integration testing to ensure all components work together
+      - Validate user acceptance and ensure everything works as expected
     transitions:
       - trigger: 'need_implementation_fixes'
         to: 'implementation'
@@ -139,45 +160,44 @@ states:
 
   finalize:
     description: 'Code cleanup and documentation finalization'
-    default_instructions: >
-      You are in the finalize phase. This phase ensures code quality and documentation accuracy through systematic cleanup and review.
+    default_instructions: |
+      Complete the feature by cleaning up code and updating documentation.
 
       **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.
+      Remove debug output and temporary code:
+      - 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)
 
-      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
+      Review and address 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
+      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:
-         • Update $REQUIREMENTS_DOC if requirements changed during development
-         • Update $ARCHITECTURE_DOC if architectural decisions evolved
-         • Update $DESIGN_DOC if design details were refined or changed
-      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**
+      Review and update documentation to reflect final implementation:
+      - Update `$REQUIREMENTS_DOC` if requirements changed during development
+      - Update `$ARCHITECTURE_DOC` if architectural decisions evolved
+      - Update `$DESIGN_DOC` if design details were refined or changed
+      - Compare documentation against actual implemented functionality
+      - Only modify documentation sections that have functional changes
+      - Remove references to development iterations, progress notes, and temporary decisions
+      - Ensure documentation describes the final implemented state, not the development process
+      - 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.
+      Update task progress and mark completed work as you finalize the feature.
     transitions:
       - trigger: 'need_final_changes'
         to: 'implementation'