@codemcp/workflows 5.2.4 → 6.0.1

package/resources/workflows/sdd-bugfix-crowd.yaml

@@ -0,0 +1,608 @@
+# yaml-language-server: $schema=../../state-machine-schema.json
+---
+name: 'sdd-bugfix-crowd'
+description: 'Collaborative bug fixing: Developer reproduces → Business Analyst specifies → Developer tests & fixes → Team verifies'
+initial_state: 'reproduce'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'sdd-crowd'
+  complexity: 'medium'
+  collaboration: true
+  requiredRoles:
+    - business-analyst
+    - architect
+    - developer
+  bestFor:
+    - 'Team-based systematic bug fixing'
+    - 'Multi-agent bug resolution'
+    - 'Specification-driven debugging with team collaboration'
+  useCases:
+    - 'Fix complex bugs with team expertise'
+    - 'Resolve issues with comprehensive testing and review'
+  examples:
+    - 'Team fixes authentication flow bug with full specification'
+    - 'Collaborative resolution of data corruption issue'
+
+# States with default instructions and role-specific transitions
+states:
+  reproduce:
+    description: 'Reproduce and understand the bug'
+    default_instructions: |
+      **Team Collaboration Mode**
+
+      You are `$VIBE_ROLE` working in a collaborative team on this bug fix.
+
+      Developer is responsible. Business-analyst and architect are consulted.
+
+    transitions:
+      # Business Analyst is CONSULTED during reproduce phase
+      - trigger: 'bug_reproduced'
+        to: 'specify'
+        role: business-analyst
+        transition_reason: 'Bug reproduced, preparing to specify correct behavior'
+        additional_instructions: |
+          **Consultant Role in Reproduce Phase**
+
+          The developer is investigating the bug. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about expected behavior
+          - Clarify business rules and user expectations
+          - Explain the correct functionality from user perspective
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only developer can edit)
+          - Do NOT attempt to proceed to next phase
+
+          **Transition Notice:**
+          - When developer completes the reproduce phase, you become RESPONSIBLE
+          - You will lead the specify phase
+          - Prepare to document the correct behavior specification
+
+      # Architect is CONSULTED during reproduce phase
+      - trigger: 'bug_reproduced'
+        to: 'specify'
+        role: architect
+        transition_reason: 'Bug reproduced, transitioning to specification'
+        additional_instructions: |
+          **Consultant Role in Reproduce Phase**
+
+          The developer is investigating the bug. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about system design
+          - Clarify architectural intent and patterns
+          - Explain expected component interactions
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only developer can edit)
+          - Do NOT attempt to proceed to next phase
+
+          **How to Help:**
+          - Use get_my_messages to check for developer questions
+          - Provide architectural context for the buggy component
+
+      # Developer is RESPONSIBLE for reproduce phase
+      - trigger: 'bug_reproduced'
+        to: 'specify'
+        role: developer
+        transition_reason: 'Bug reproduced successfully, handing off to business-analyst'
+        additional_instructions: |
+          **Responsible for Reproduce Phase**
+
+          You have exclusive control during this phase:
+          - Only you can edit the plan file
+          - Only you can proceed to the next phase
+
+          **STEP 1: Gather Information**
+          - Collect exact OS, browser/runtime versions, hardware specs
+          - Document precise sequence of actions triggering the bug
+          - Obtain error messages, logs, stack traces
+          - Determine frequency (always or intermittent?)
+          - Assess business impact
+
+          **STEP 2: Create Reproduction**
+          - Develop minimal, reliable reproduction steps
+          - Document exact environment and conditions
+          - Create test data/scenarios that trigger the issue
+          - Verify bug occurs consistently
+
+          **STEP 3: Understand the Problem**
+          - Identify current (buggy) behavior
+          - Determine correct behavior
+          - Distinguish symptoms vs. root cause
+          - Identify related issues or edge cases
+
+          **STEP 4: Collaborate When Needed**
+          - Use send_message to business-analyst: "What is the expected behavior for [scenario]?"
+          - Use send_message to architect: "How should this component interact with [other component]?"
+
+          **Deliverable**: Create `$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md`
+
+          **Handoff to Business-Analyst:**
+          1. Use send_message to business-analyst: "Bug reproduced successfully. Please take the lead for specify phase to document correct behavior. See: `$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md`"
+          2. Use send_message to architect: "Bug reproduced, business-analyst will specify correct behavior"
+          3. Use send_message_to_operator: "Reproduction complete, handing off to business-analyst"
+          4. Call proceed_to_phase - you transition to CONSULTED in specify phase
+
+      # Bug not reproducible loop
+      - trigger: 'bug_not_reproducible'
+        to: 'reproduce'
+        role: developer
+        transition_reason: 'Bug could not be reproduced, need more information'
+        additional_instructions: |
+          Unable to reproduce the bug. Gather more details about environment, conditions, or steps.
+          Use send_message_to_operator to request more information from bug reporter.
+
+  specify:
+    description: 'Create specification of correct behavior'
+    default_instructions: |
+      **Team Collaboration Mode**
+
+      You are `$VIBE_ROLE` working in a collaborative team on this bug fix.
+
+      Business-analyst is responsible. Developer and architect are consulted.
+
+    transitions:
+      # Business Analyst is RESPONSIBLE for specify phase
+      - trigger: 'specification_complete'
+        to: 'test'
+        role: business-analyst
+        transition_reason: 'Bug specification completed, developer will create tests'
+        additional_instructions: |
+          **Responsible for Specify Phase**
+
+          You have exclusive control during this phase:
+          - Only you can edit the plan file
+          - Only you can proceed to the next phase
+
+          **STEP 1: Define Correct Behavior**
+          - Determine what should happen in the failing scenario
+          - Document expected outcomes for users
+          - Specify system behavior in edge cases
+          - Clarify business rules to enforce
+
+          **STEP 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
+
+          **STEP 3: Collaborate**
+          - Use send_message to developer: "Does this specification clearly define the fix?"
+          - Use send_message to architect: "Does this align with system design intent?"
+
+          **Deliverable**: Create `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`
+
+          **Handoff to Developer:**
+          1. Use send_message to developer: "Bug specification complete. Please take the lead for test phase to create failing tests. See: `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`"
+          2. Use send_message to architect: "Specification ready, developer will create tests and fix"
+          3. Use send_message_to_operator: "Bug spec complete, handing off to developer for testing"
+          4. Call proceed_to_phase - you transition to CONSULTED in test phase
+
+      # Architect is CONSULTED during specify phase
+      - trigger: 'specification_complete'
+        to: 'test'
+        role: architect
+        transition_reason: 'Bug specification completed, transitioning to test phase'
+        additional_instructions: |
+          **Consultant Role in Specify Phase**
+
+          The business-analyst is defining correct behavior. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about system design intent
+          - Clarify how components should interact
+          - Validate specification against architectural principles
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only business-analyst can edit)
+          - Do NOT attempt to proceed to next phase
+
+      # Developer is CONSULTED during specify phase
+      - trigger: 'specification_complete'
+        to: 'test'
+        role: developer
+        transition_reason: 'Bug specification completed, preparing to create tests'
+        additional_instructions: |
+          **Consultant Role in Specify Phase**
+
+          The business-analyst is defining correct behavior. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about testability
+          - Provide feedback on specification clarity
+          - Identify any technical constraints
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only business-analyst can edit)
+          - Do NOT attempt to proceed to next phase
+
+          **Transition Notice:**
+          - When business-analyst completes the specify phase, you become RESPONSIBLE
+          - You will lead the test phase
+          - Prepare to create failing tests that capture the bug
+
+  test:
+    description: 'Create comprehensive tests'
+    default_instructions: |
+      **Team Collaboration Mode**
+
+      You are `$VIBE_ROLE` working in a collaborative team on this bug fix.
+
+      Developer is responsible for creating tests.
+
+    transitions:
+      # Business Analyst is CONSULTED during test phase
+      - trigger: 'tests_created'
+        to: 'plan'
+        role: business-analyst
+        transition_reason: 'Tests created, architect will plan the fix'
+        additional_instructions: |
+          **Consultant Role in Test Phase**
+
+          The developer is creating tests. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about acceptance criteria
+          - Validate tests cover all user scenarios from spec
+          - Ensure tests verify correct business behavior
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only developer can edit)
+          - Do NOT attempt to proceed to next phase
+
+      # Architect is CONSULTED during test phase
+      - trigger: 'tests_created'
+        to: 'plan'
+        role: architect
+        transition_reason: 'Tests created, preparing to plan fix approach'
+        additional_instructions: |
+          **Consultant Role in Test Phase**
+
+          The developer is creating tests. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about test architecture
+          - Provide guidance on integration testing approach
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only developer can edit)
+          - Do NOT attempt to proceed to next phase
+
+          **Transition Notice:**
+          - When developer completes the test phase, you become RESPONSIBLE
+          - You will lead the plan phase
+          - Prepare to design the fix approach
+
+      # Developer is RESPONSIBLE for test phase
+      - trigger: 'tests_created'
+        to: 'plan'
+        role: developer
+        transition_reason: 'Tests created, handing off to architect for fix planning'
+        additional_instructions: |
+          **Responsible for Test Phase**
+
+          You have exclusive control during this phase:
+          - Only you can edit the plan file
+          - Only you can proceed to the next phase
+
+          **STEP 1: Create Failing Tests for Current Bug**
+          - Create tests demonstrating current buggy behavior
+          - These should fail initially (Red phase of TDD)
+          - Cover main reproduction case and related scenarios
+          - Include edge cases and boundary conditions
+
+          **STEP 2: Create Tests for Expected Behavior**
+          - Create tests specifying correct behavior from bug-spec.md
+          - These should pass once bug is fixed
+          - Cover all functional requirements
+          - Include user scenarios and success criteria
+
+          **STEP 3: Create Regression Tests**
+          - Tests for related functionality that shouldn't be affected
+          - Ensure fix doesn't break existing features
+
+          **STEP 4: Collaborate**
+          - Use send_message to business-analyst: "Do these tests cover all scenarios from the spec?"
+          - Use send_message to architect: "Is the test architecture appropriate?"
+
+          **Deliverable**: Create `$VIBE_DIR/specs/$BRANCH_NAME/tests.md`
+
+          **Handoff to Architect:**
+          1. Use send_message to architect: "Tests created and failing as expected. Please take the lead for plan phase to design the fix approach."
+          2. Use send_message to business-analyst: "Tests ready, architect will plan the fix"
+          3. Use send_message_to_operator: "Tests complete, handing off to architect for fix planning"
+          4. Call proceed_to_phase - you transition to CONSULTED in plan phase
+
+  plan:
+    description: 'Plan the fix approach'
+    default_instructions: |
+      **Team Collaboration Mode**
+
+      You are `$VIBE_ROLE` working in a collaborative team on this bug fix.
+
+      Architect is responsible. Business-analyst and developer are consulted.
+
+    transitions:
+      # Business Analyst is CONSULTED during plan phase
+      - trigger: 'plan_complete'
+        to: 'fix'
+        role: business-analyst
+        transition_reason: 'Fix plan complete, developer will implement'
+        additional_instructions: |
+          **Consultant Role in Plan Phase**
+
+          The architect is designing the fix approach. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about business rules
+          - Validate fix approach addresses the root problem
+          - Ensure fix aligns with user expectations
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only architect can edit)
+          - Do NOT attempt to proceed to next phase
+
+      # Architect is RESPONSIBLE for plan phase
+      - trigger: 'plan_complete'
+        to: 'fix'
+        role: architect
+        transition_reason: 'Fix plan completed, handing off to developer'
+        additional_instructions: |
+          **Responsible for Plan Phase**
+
+          You have exclusive control during this phase:
+          - Only you can edit the plan file
+          - Only you can proceed to the next phase
+
+          **STEP 1: Load Context**
+          - Read bug spec: `$VIBE_DIR/specs/$BRANCH_NAME/bug-spec.md`
+          - Review reproduction: `$VIBE_DIR/specs/$BRANCH_NAME/reproduction.md`
+          - Understand test requirements
+          - Analyze existing codebase
+
+          **STEP 2: Perform Root Cause Analysis**
+          - Identify underlying cause of the bug
+          - Understand why current implementation fails
+          - Map problem to specific code areas or logic flaws
+
+          **STEP 3: Design Fix Strategy**
+          - Design minimal, targeted fix addressing root cause
+          - Ensure fix aligns with existing architecture patterns
+          - Consider impact on related functionality
+          - Plan for backward compatibility if needed
+
+          **STEP 4: Collaborate**
+          - Use send_message to business-analyst: "Does this fix approach meet business needs?"
+          - Use send_message to developer: "Is this fix approach implementable?"
+          - Incorporate their feedback
+
+          **Deliverable**: Create `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md`
+
+          **Handoff to Developer:**
+          1. Use send_message to developer: "Fix plan complete. Please take the lead for fix phase. See: `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md`"
+          2. Use send_message to business-analyst: "Plan ready, developer will implement fix"
+          3. Use send_message_to_operator: "Fix plan complete, handing off to developer"
+          4. Call proceed_to_phase - you transition to CONSULTED in fix phase
+
+      # Developer is CONSULTED during plan phase
+      - trigger: 'plan_complete'
+        to: 'fix'
+        role: developer
+        transition_reason: 'Fix plan completed, preparing to implement'
+        additional_instructions: |
+          **Consultant Role in Plan Phase**
+
+          The architect is designing fix approach. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for questions about implementation
+          - Provide feedback on fix implementability and complexity
+          - Identify potential implementation challenges
+          - Discuss testing approach
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only architect can edit)
+          - Do NOT attempt to proceed to next phase
+
+          **Transition Notice:**
+          - When architect completes the plan phase, you become RESPONSIBLE
+          - You will lead the fix phase
+          - Prepare to implement the minimal fix
+
+  fix:
+    description: 'Implement the fix to make tests pass'
+    default_instructions: |
+      **Team Collaboration Mode**
+
+      You are `$VIBE_ROLE` working in a collaborative team on this bug fix.
+
+      Developer is responsible. Architect and business-analyst are consulted.
+
+    transitions:
+      # Business Analyst is CONSULTED during fix phase
+      - trigger: 'fix_implemented'
+        to: 'verify'
+        role: business-analyst
+        transition_reason: 'Fix implemented, team will verify'
+        additional_instructions: |
+          **Consultant Role in Fix Phase**
+
+          The developer is implementing the fix. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for requirements clarifications
+          - Validate fix approach meets business needs
+          - Approve acceptance criteria when asked
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only developer can edit)
+          - Do NOT attempt to proceed to next phase
+
+      # Architect is CONSULTED during fix phase
+      - trigger: 'fix_implemented'
+        to: 'verify'
+        role: architect
+        transition_reason: 'Fix implemented, team will verify'
+        additional_instructions: |
+          **Consultant Role in Fix Phase**
+
+          The developer is implementing the fix. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for architecture questions
+          - Provide guidance on design patterns and best practices
+          - Recommend integration approaches
+          - Discuss technical trade-offs
+
+          **Important Constraints:**
+          - Do NOT edit the plan file (only developer can edit)
+          - Do NOT attempt to proceed to next phase
+
+      # Developer is RESPONSIBLE for fix phase
+      - trigger: 'fix_implemented'
+        to: 'verify'
+        role: developer
+        transition_reason: 'Fix implemented and tests passing, ready for verification'
+        additional_instructions: |
+          **Responsible for Fix Phase**
+
+          You have exclusive control during this phase:
+          - Only you can edit the plan file
+          - Only you can proceed to the next phase
+
+          **STEP 1: Execute Fix Strategy**
+          - Execute fix strategy from `$VIBE_DIR/specs/$BRANCH_NAME/fix-plan.md`
+          - Make targeted changes to address root cause
+          - Avoid over-engineering
+          - Keep changes minimal and focused
+
+          **STEP 2: Implement with TDD**
+          - Run failing tests to confirm they capture the bug
+          - Implement changes to make tests pass (Green phase)
+          - Ensure all tests pass
+
+          **STEP 3: Collaborate When Blocked**
+          - Use send_message to architect: "How should I handle [technical issue]?"
+          - Use send_message to business-analyst: "What is correct behavior for [edge case]?"
+
+          **STEP 4: Validate**
+          - Verify original reproduction case no longer occurs
+          - Run full test suite to check for regressions
+          - Test edge cases and boundary conditions
+
+          **Continue to Verify Phase**
+
+          You remain RESPONSIBLE in verify phase. Before proceeding:
+          1. Use send_message_to_operator: "Fix implemented and tests passing, moving to verification"
+          2. Only you can call proceed_to_phase
+
+  verify:
+    description: 'Verify the fix works and no regressions'
+    default_instructions: |
+      **Team Collaboration Mode**
+
+      You are `$VIBE_ROLE` working in a collaborative team on this bug fix.
+
+      Developer is responsible. Team validates together.
+
+    transitions:
+      # Business Analyst is CONSULTED during verify phase
+      - trigger: 'verification_complete'
+        to: 'verify'
+        role: business-analyst
+        transition_reason: 'Verification complete, bug fixed'
+        additional_instructions: |
+          **Consultant Role in Verify Phase**
+
+          The developer is verifying the fix. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for validation requests
+          - Perform user acceptance validation:
+            - Does fix address original user problem?
+            - Are all scenarios from spec working?
+            - Is user experience improved?
+
+          **How to Help:**
+          - Use get_my_messages to check for verification requests
+          - Use send_message to confirm fix meets business needs
+          - Raise concerns if fix doesn't fully address the problem
+
+      # Architect is CONSULTED during verify phase
+      - trigger: 'verification_complete'
+        to: 'verify'
+        role: architect
+        transition_reason: 'Verification complete, bug fixed'
+        additional_instructions: |
+          **Consultant Role in Verify Phase**
+
+          The developer is verifying the fix. Your role is to provide consultative support.
+
+          **Your Responsibilities:**
+          - Monitor messages for architecture validation requests
+          - Review fix maintains architectural integrity
+          - Ensure no technical debt introduced
+
+          **How to Help:**
+          - Use get_my_messages to check for verification requests
+          - Use send_message to approve architectural soundness
+          - Suggest improvements if fix introduces issues
+
+      # Developer is RESPONSIBLE for verify phase
+      - trigger: 'verification_complete'
+        to: 'verify'
+        role: developer
+        transition_reason: 'Verification complete, bug fix ready for deployment'
+        additional_instructions: |
+          **Responsible for Verify Phase**
+
+          You have exclusive control during this phase:
+          - Only you can edit the plan file
+          - Only you can mark verification complete
+
+          **STEP 1: Verify Bug Resolution**
+          - Confirm original reproduction case no longer occurs
+          - Verify all scenarios from bug-spec.md work correctly
+          - Test in original environment where bug was reported
+          - Validate success criteria are met
+
+          **STEP 2: Perform Regression Testing**
+          - Run full test suite
+          - Test related features and integration points
+          - Verify performance hasn't degraded
+          - Check for new edge case failures
+
+          **STEP 3: Get Team Validation**
+          - Use send_message to business-analyst: "Please perform user acceptance validation"
+          - Use send_message to architect: "Please review architectural integrity"
+          - Wait for their approval
+
+          **STEP 4: Complete and Document**
+          - Update relevant documentation if behavior changed
+          - Document fix approach for future reference
+          - Use send_message_to_operator: "Bug fix verified and approved by team, ready for deployment"
+
+          **This is the terminal state** - bug fix is complete.
+
+      # Regression detected - return to fix
+      - trigger: 'regression_detected'
+        to: 'fix'
+        role: developer
+        transition_reason: 'Regression detected, need to revise fix'
+        additional_instructions: |
+          Regression detected during verification. Fix has introduced new issues.
+
+          1. Use send_message to architect: "Regression detected: [explain]. Need help revising fix."
+          2. Use send_message to business-analyst: "Regression found, working on resolution"
+          3. Use send_message_to_operator: "Regression detected, revising fix"
+          4. Call proceed_to_phase to return to fix phase
+
+# Global transitions
+global_transitions:
+  - trigger: 'abandon_bugfix'
+    to: 'reproduce'
+    transition_reason: 'Bug fix abandoned, restart from beginning'
+    additional_instructions: |
+      Bug fix abandoned. If you want to restart, begin again with reproducing and understanding the bug.