@codemcp/workflows-core 3.2.2 → 3.3.0

package/resources/workflows/minor.yaml

@@ -36,7 +36,6 @@ states:
     transitions:
       - trigger: 'exploration_complete'
         to: 'implement'
-        additional_instructions: 'Analysis and design complete! ✅ Now transition to implementation phase. You have a clear understanding of the problem and a solid design approach. Keep the scope focused on the minor enhancement. Mark completed exploration tasks.'
         transition_reason: 'Analysis and design complete, ready for streamlined implementation'
 
       - trigger: 'abandon_feature'
@@ -59,7 +58,6 @@ states:
 
       - trigger: 'implementation_complete'
         to: 'finalize'
-        additional_instructions: 'Implementation is complete! Clean up code and finalize documentation to ensure everything is ready for delivery. Mark all implementation tasks as complete.'
         transition_reason: 'Implementation complete, ready for finalization'
 
       - trigger: 'abandon_feature'
@@ -67,7 +65,7 @@ states:
         instructions: >
           Minor enhancement abandoned during implementation. Clean up any incomplete code and return to exploration.
           The plan file and any completed work will remain for future reference.
-        additional_instructions: 'Minor enhancement abandoned during implementation. Clean up any incomplete code and prepare for new tasks.'
+        additional_instructions: 'Clean up any incomplete code and prepare for new tasks.'
         transition_reason: 'User decided to abandon minor enhancement during implementation'
 
   finalize:
@@ -118,10 +116,9 @@ states:
 
       - trigger: 'finalization_complete'
         to: 'explore'
-        additional_instructions: 'Minor enhancement is complete and finalized! All work is finished and ready for delivery. Prepare for the next development task.'
         transition_reason: 'Minor enhancement delivery complete, ready for next task'
 
       - trigger: 'abandon_feature'
         to: 'explore'
-        additional_instructions: 'Minor enhancement abandoned during finalization. Clean up any finalization artifacts and prepare for new tasks.'
+        additional_instructions: 'Clean up any finalization artifacts and prepare for new tasks.'
         transition_reason: 'User decided to abandon minor enhancement during finalization'

package/resources/workflows/posts.yaml

@@ -40,10 +40,6 @@ states:
     transitions:
       - trigger: discovery_complete
         to: story
-        additional_instructions: |
-          Discovery complete! ✅ You have clear format decision, unique angle, and research foundation.
-
-          Update the plan file with story development tasks and mark completed discovery work.
         transition_reason: 'Topic researched and format decided, ready for story structure development'
 
       - trigger: abandon_post
@@ -190,7 +186,6 @@ states:
     transitions:
       - trigger: distribution_complete
         to: discovery
-        additional_instructions: 'Post successfully published. Ready for next post project.'
         transition_reason: 'Post publishing completed successfully, ready for new projects'
 
       - trigger: need_final_review

package/resources/workflows/sdd-bugfix.yaml

@@ -0,0 +1,399 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'sdd-bugfix'
+description: 'Test and specification-driven bugfix workflow: Reproduce → Specify → Test → Plan → Fix → Verify'
+initial_state: 'reproduce'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'sdd'
+  complexity: 'medium'
+  bestFor:
+    - 'Systematic bug fixing'
+    - 'Test-driven bug resolution'
+    - 'Specification-driven debugging'
+    - 'Quality-focused fixes'
+  useCases:
+    - 'Fix complex bugs with clear specification'
+    - 'Resolve issues with comprehensive testing'
+    - 'Debug problems requiring systematic approach'
+  examples:
+    - 'Fix authentication flow bug with test coverage'
+    - 'Resolve data corruption issue with specification'
+    - 'Debug performance problem with systematic approach'
+
+# States with default instructions and transitions
+states:
+  reproduce:
+    description: 'Reproduce and understand the bug systematically'
+    default_instructions: |
+      You are systematically reproducing and understanding the bug to create a solid foundation for specification-driven fixing.
+
+      **Bug Reproduction Process:**
+
+      1. **Gather Comprehensive Information**:
+         - What are the exact OS, browser/runtime versions, and hardware specs?
+         - What is the precise sequence of actions that trigger the bug?
+         - What error messages, logs, or stack traces are available?
+         - Does this happen every time or intermittently?
+         - How many users are affected and what is the business impact?
+
+      2. **Create Reproduction Cases**:
+         - Develop minimal, reliable reproduction steps
+         - Document the exact environment and conditions
+         - Create test data or scenarios that trigger the issue
+         - Verify the bug occurs consistently
+
+      3. **Understand the Problem**:
+         - What is the current (buggy) behavior?
+         - What should the correct behavior be?
+         - What are the symptoms vs. root cause?
+         - Are there related issues or edge cases?
+
+      4. **Document Findings**:
+         - Create `$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md` with detailed reproduction steps
+         - Include error logs, screenshots, or other evidence
+         - Document the gap between expected and actual behavior
+
+      **Output**: Clear, reliable reproduction case that can be used to verify the fix later.
+
+    transitions:
+      - trigger: 'bug_reproduced'
+        to: 'specify'
+        transition_reason: 'Bug reproduced successfully, ready to specify correct behavior'
+
+      - trigger: 'bug_not_reproducible'
+        to: 'reproduce'
+        instructions: >
+          Unable to reproduce the bug with current information. Gather more details about the environment,
+          conditions, or steps that might be missing. Contact the reporter for additional information if needed.
+        transition_reason: 'Bug could not be reproduced, need more information'
+
+  specify:
+    description: 'Create specification of correct behavior'
+    default_instructions: |
+      You are creating a clear specification of the correct behavior. This specification will guide the fix and prevent regressions.
+
+      **Specification Process:**
+
+      1. **Define Correct Behavior**:
+         - What should happen in the scenario that currently fails?
+         - What are the expected outcomes for users?
+         - How should the system behave in edge cases?
+         - What are the business rules that should be enforced?
+
+      2. **Handle Ambiguities**:
+         - Make informed decisions about unclear requirements
+         - Use [NEEDS CLARIFICATION: question] only for critical ambiguities (max 3)
+         - Prioritize: correctness > user experience > technical details
+
+      3. **Quality Standards**:
+         - Focus on user impact and business value
+         - Avoid implementation details
+         - Ensure all requirements are testable
+         - Make success criteria measurable
+
+      Create `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md` using the template provided below.
+    additional_instructions: |
+      **Bug Specification Template:**
+
+      Use this template to create your `bug-spec.md` file:
+
+      ```markdown
+      # Bug Fix Specification: [BUG TITLE]
+
+      **Created**: [DATE]
+      **Bug Report**: [Reference to original bug report]
+
+      ## Current Problem
+
+      **Description**: [Clear description of the bug and its impact]
+
+      **Symptoms**: [What users experience when the bug occurs]
+
+      **Impact**: [Business impact, user frustration, data issues, etc.]
+
+      ## Expected Behavior
+
+      **Correct Functionality**: [Detailed specification of how it should work]
+
+      **User Experience**: [How users should be able to interact with the fixed system]
+
+      **Business Rules**: [Rules that should be enforced]
+
+      ## User Scenarios
+
+      ### Scenario 1 - [Primary Fix Scenario]
+
+      **Given** [initial state]
+      **When** [action that currently fails]
+      **Then** [expected correct outcome]
+
+      ### Scenario 2 - [Edge Case Scenario]
+
+      **Given** [edge case state]
+      **When** [edge case action]
+      **Then** [expected correct outcome]
+
+      [Add more scenarios as needed]
+
+      ## Functional Requirements
+
+      - **FR-001**: System MUST [correct behavior requirement]
+      - **FR-002**: System MUST [error handling requirement]
+      - **FR-003**: System MUST [data integrity requirement]
+      - **FR-004**: System MUST [user feedback requirement]
+
+      ## Success Criteria
+
+      ### Fix Validation
+
+      - **SC-001**: Original reproduction case no longer occurs
+      - **SC-002**: All user scenarios work as specified
+      - **SC-003**: [Performance/reliability metric if applicable]
+      - **SC-004**: No regressions in related functionality
+
+      ### User Impact
+
+      - **SC-005**: [Measurable improvement in user experience]
+      - **SC-006**: [Reduction in error rates or support tickets]
+
+      ## Edge Cases
+
+      - What happens when [boundary condition]?
+      - How does system handle [error scenario]?
+      - What about [related functionality]?
+
+      ## Assumptions
+
+      - [Document any assumptions about correct behavior]
+      - [Include decisions made about ambiguous requirements]
+
+      ## Dependencies
+
+      - [Related systems that must continue working]
+      - [Integration points that must be preserved]
+      ```
+
+      Fill in all sections with specific details about the correct behavior that should replace the current buggy behavior.
+
+    transitions:
+      - trigger: 'specification_complete'
+        to: 'test'
+        transition_reason: 'Bug specification completed, ready to create tests'
+
+      - trigger: 'needs_clarification'
+        to: 'specify'
+        instructions: >
+          Bug specification has unresolved clarifications. Present structured questions to stakeholders,
+          wait for their responses, then update the specification accordingly.
+        transition_reason: 'Bug specification needs clarification before proceeding'
+
+  test:
+    description: 'Create comprehensive tests that capture the bug and expected behavior'
+    default_instructions: |
+      You are creating comprehensive tests that capture both the current bug and the expected correct behavior. These tests will guide the fix and prevent regressions.
+
+      **Test Creation Process:**
+
+      1. **Failing Tests for Current Bug**:
+         - Create tests that demonstrate the current buggy behavior
+         - These tests should fail initially (Red phase of TDD)
+         - Cover the main reproduction case and related scenarios
+         - Include edge cases and boundary conditions
+
+      2. **Tests for Expected Behavior**:
+         - Create tests that specify the correct behavior from `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`
+         - These tests should pass once the bug is fixed
+         - Cover all functional requirements from the specification
+         - Include user scenarios and success criteria
+
+      3. **Regression Tests**:
+         - Create tests for related functionality that should not be affected
+         - Ensure the fix doesn't break existing features
+         - Test integration points and dependencies
+
+      4. **Test Organization**:
+         - Group tests by functionality and user scenarios
+         - Use clear, descriptive test names
+         - Include both unit and integration tests as appropriate
+         - Document test setup and data requirements
+
+      **Output**: Create comprehensive test suite in appropriate test files that will guide the fix implementation.
+
+    transitions:
+      - trigger: 'tests_created'
+        to: 'plan'
+        transition_reason: 'Tests created for bug and expected behavior, ready to plan the fix'
+
+  plan:
+    description: 'Plan the fix approach with constitutional compliance'
+    default_instructions: |
+      You are planning the fix approach, ensuring the solution aligns with system architecture and quality principles.
+
+      **Fix Planning Process:**
+
+      1. **Load Context**:
+         - Read bug specification (`$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`)
+         - Review reproduction case (`$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md`)
+         - Understand the test requirements
+         - Analyze existing codebase and architecture
+
+      2. **Root Cause Analysis**:
+         - Identify the underlying cause of the bug
+         - Understand why the current implementation fails
+         - Map the problem to specific code areas or logic flaws
+         - Consider systemic issues vs. isolated bugs
+
+      3. **Fix Strategy**:
+         - Design minimal, targeted fix that addresses root cause
+         - Ensure fix aligns with existing architectural patterns
+         - Consider impact on related functionality
+         - Plan for backward compatibility if needed
+
+      4. **Constitutional/Quality Compliance**:
+         - Ensure fix follows system design principles
+         - Verify approach maintains code quality standards
+         - Check that fix doesn't introduce technical debt
+         - Validate solution is maintainable and testable
+
+      5. **Implementation Plan**:
+         - Break down fix into specific, actionable tasks
+         - Identify files and components that need changes
+         - Plan testing and validation approach
+         - Consider rollout and deployment strategy
+
+      **Output**: Create `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md` with detailed approach for implementing the bug fix.
+
+    transitions:
+      - trigger: 'plan_complete'
+        to: 'fix'
+        transition_reason: 'Fix plan completed, ready to implement the solution'
+
+      - trigger: 'architectural_conflict'
+        to: 'plan'
+        instructions: >
+          Planned fix conflicts with system architecture or quality principles.
+          Revise the approach to ensure proper integration and maintainability.
+        transition_reason: 'Fix plan conflicts with architecture, needs revision'
+
+  fix:
+    description: 'Implement the minimal fix to make tests pass'
+    default_instructions: |
+      You are implementing the bug fix following the plan and making the tests pass. Focus on minimal, targeted changes that address the root cause.
+
+      **Fix Implementation Process:**
+
+      1. **Follow the Plan**: Execute the fix strategy from `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md`
+         - Make targeted changes to address the root cause
+         - Avoid over-engineering or unnecessary modifications
+         - Keep changes minimal and focused
+
+      2. **Test-Driven Implementation**:
+         - Run the failing tests to confirm they capture the bug
+         - Implement changes to make the tests pass (Green phase)
+         - Ensure all new tests pass while maintaining existing functionality
+
+      3. **Quality Standards**:
+         - Follow existing code patterns and conventions
+         - Maintain or improve code readability
+         - Add appropriate error handling
+         - Include necessary logging or monitoring
+
+      4. **Validation**:
+         - Verify the original reproduction case no longer occurs
+         - Run full test suite to check for regressions
+         - Test edge cases and boundary conditions
+         - Validate fix meets success criteria from specification
+
+      **Progress Tracking**:
+      - Document any deviations from the original plan
+      - Note any additional issues discovered during implementation
+      - Update tests if new edge cases are found
+
+    transitions:
+      - trigger: 'fix_implemented'
+        to: 'verify'
+        transition_reason: 'Bug fix implemented and tests passing, ready for verification'
+
+      - trigger: 'fix_blocked'
+        to: 'plan'
+        instructions: >
+          Fix implementation is blocked by technical issues or complexity.
+          Return to planning to revise the approach or break down the problem further.
+        transition_reason: 'Fix implementation blocked, need to revise plan'
+
+      - trigger: 'tests_failing'
+        to: 'test'
+        instructions: >
+          Tests are failing in unexpected ways, indicating the test design may need revision.
+          Review and update the test suite to better capture the requirements.
+        transition_reason: 'Tests failing unexpectedly, need to revise test approach'
+
+  verify:
+    description: 'Verify the fix works and does not introduce regressions'
+    default_instructions: |
+      You are verifying that the bug fix works correctly and doesn't introduce any regressions or new issues.
+
+      **Verification Process:**
+
+      1. **Bug Resolution Verification**:
+         - Confirm the original reproduction case no longer occurs
+         - Verify all scenarios from `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md` work correctly
+         - Test the fix in the original environment where the bug was reported
+         - Validate that success criteria are met
+
+      2. **Regression Testing**:
+         - Run full test suite to ensure no existing functionality is broken
+         - Test related features and integration points
+         - Verify performance hasn't degraded
+         - Check that the fix doesn't introduce new edge case failures
+
+      3. **User Acceptance**:
+         - Test from user perspective using real scenarios
+         - Verify the fix addresses the original user problem
+         - Ensure user experience is improved, not just technically correct
+         - Consider having original bug reporter validate the fix
+
+      4. **Documentation and Communication**:
+         - Update relevant documentation if behavior has changed
+         - Document the fix approach for future reference
+         - Prepare release notes or change log entries
+         - Consider if this fix reveals systemic issues to address
+
+      **Final Validation**:
+      - All tests pass (both new and existing)
+      - Original bug reproduction case fails (bug is fixed)
+      - No regressions detected
+      - User scenarios work as specified
+
+    transitions:
+      - trigger: 'verification_complete'
+        to: 'verify'
+        instructions: >
+          Bug fix verification completed successfully. The bug has been resolved, all tests pass,
+          and no regressions have been detected. The fix is ready for deployment.
+        transition_reason: 'Verification complete, bug fix ready for deployment'
+
+      - trigger: 'regression_detected'
+        to: 'fix'
+        instructions: >
+          Regression detected during verification. The fix has introduced new issues or broken
+          existing functionality. Return to implementation to address the problems.
+        transition_reason: 'Regression detected, need to revise fix implementation'
+
+      - trigger: 'fix_insufficient'
+        to: 'specify'
+        instructions: >
+          The fix doesn't fully address the original problem or reveals that the specification
+          was incomplete. Return to specification to better define the requirements.
+        transition_reason: 'Fix insufficient, need to revise specification'
+
+# Global transitions available from any state
+global_transitions:
+  - trigger: 'abandon_bugfix'
+    to: 'reproduce'
+    instructions: >
+      Bug fix abandoned. If you want to restart, you'll begin again with reproducing
+      and understanding the bug.
+    transition_reason: 'Bug fix abandoned, restart from beginning'