@codemcp/workflows 5.3.0 → 6.0.1

package/resources/workflows/adr.yaml

@@ -0,0 +1,157 @@
+name: adr
+description: 'Architecture Decision Records workflow: Context → Research → Decide → Commit - structured process for documenting architectural decisions'
+initial_state: context
+
+metadata:
+  domain: 'architecture'
+  complexity: 'medium'
+  bestFor:
+    - 'Documenting architectural decisions'
+    - 'Recording design choices'
+    - 'Technology selection decisions'
+    - 'System design decisions'
+  useCases:
+    - 'Choosing between architectural patterns'
+    - 'Selecting technology stack components'
+    - 'Documenting design trade-offs'
+  examples:
+    - 'Document database selection decision'
+    - 'Record API design approach'
+    - 'Document deployment strategy choice'
+
+states:
+  context:
+    description: 'Define the architectural problem or decision that needs to be made'
+    default_instructions: |
+      **STEP 1:** Determine ADR storage location
+      - If `$ARCHITECTURE_DOC` exists: Use it to determine ADR storage location
+      - Otherwise: Document ADR decisions in the plan file
+
+      **STEP 2:** Look for existing ADRs to understand current format and numbering
+
+      **STEP 3:** Help user clearly define the architectural problem or decision needed
+
+      **STEP 4:** Identify key stakeholders who should be involved
+
+      **STEP 5:** Gather information about quality attributes (non-functional requirements) relevant to this decision
+      - Performance implications
+      - Security requirements
+      - Maintainability concerns
+      - Other relevant attributes
+
+      **STEP 6:** Document the context and problem statement
+
+      **STEP 7:** Create initial ADR structure using existing format or provided template
+
+      Focus on understanding WHAT decision needs to be made and WHY it's important. Do not evaluate technical options yet—that happens in the decide phase.
+
+    additional_instructions: |
+      **ADR Template (use if no existing ADRs found):**
+      ```
+      # ADR-XXX: [Decision Title]
+
+      ## Status
+      Proposed
+
+      ## Context
+      [Describe the architectural problem or decision that needs to be made]
+
+      ## Decision
+      [The decision that was made - to be filled in decide phase]
+
+      ## Consequences
+      ### Positive
+      - [Benefits of this decision]
+
+      ### Negative
+      - [Drawbacks or risks of this decision]
+
+      ## Alternatives Considered
+      - [Other options that were evaluated]
+      ```
+
+    transitions:
+      - trigger: context_complete
+        to: research
+        transition_reason: 'Architectural problem clearly defined, ready to research options'
+
+  research:
+    description: 'Investigate options, gather information, and analyze alternatives'
+    default_instructions: |
+      **STEP 1:** Research available options and alternatives for the decision
+
+      **STEP 2:** Gather technical information, constraints, and requirements
+
+      **STEP 3:** Analyze trade-offs between different approaches
+      - Evaluate each option based on defined quality attributes
+      - Query user about experience with specific technologies
+      - Consider user's perspective on the decision-making process
+      - Avoid premature judgments
+
+      **STEP 4:** Document findings in the "Alternatives Considered" section
+
+      **STEP 5:** Identify pros and cons for each option
+
+      Work with the user to thoroughly understand all viable options before making a decision. Update the ADR with research findings but do not make the final decision yet.
+
+    transitions:
+      - trigger: research_complete
+        to: decide
+        transition_reason: 'Research completed, ready to make architectural decision'
+
+  decide:
+    description: 'Make the architectural decision and document the rationale'
+    default_instructions: |
+      **STEP 1:** Help user make the final architectural decision based on research conducted
+
+      **STEP 2:** Document the chosen option in the "Decision" section
+
+      **STEP 3:** Provide clear rationale for why this option was selected
+
+      **STEP 4:** Document positive consequences (benefits) of the decision
+
+      **STEP 5:** Document negative consequences (drawbacks and risks) of the decision
+
+      **STEP 6:** Ensure the decision is specific and actionable
+
+      **STEP 7:** Update ADR status to "Accepted" (or "Proposed" if approval is needed)
+
+      Focus on making a clear, well-reasoned decision with documented rationale based on the research conducted in the previous phase.
+
+    transitions:
+      - trigger: decision_complete
+        to: commit
+        transition_reason: 'Decision made and documented, ready for finalization'
+        review_perspectives:
+          - perspective: 'architect'
+            prompt: 'Review the ADR for architectural soundness, completeness, and alignment with system design principles. Ensure the decision is well-reasoned and consequences are thoroughly documented.'
+          - perspective: 'stakeholder'
+            prompt: 'Review the ADR from a business/project perspective. Ensure the decision addresses stakeholder needs, considers business impact, and is clearly communicated.'
+          - perspective: 'implementer'
+            prompt: 'Review the ADR from an implementation perspective. Ensure the decision is practical, actionable, and considers development/operational implications.'
+
+  commit:
+    description: 'Finalize the ADR with validation and cleanup'
+    default_instructions: |
+      **STEP 1:** Review ADR completeness and quality
+
+      **STEP 2:** Ensure proper formatting and structure
+
+      **STEP 3:** Verify all sections are filled appropriately
+
+      **STEP 4:** Check that consequences (positive and negative) are documented
+
+      **STEP 5:** Ensure alternatives considered are listed
+
+      **STEP 6:** Finalize ADR numbering if needed
+
+      **STEP 7:** Update ADR status to final state (Accepted or Approved)
+
+      **STEP 8:** Save and integrate ADR into `$ARCHITECTURE_DOC` or appropriate location
+
+      Complete final validation and cleanup before the ADR is finalized.
+
+    transitions:
+      - trigger: need_decision_changes
+        to: decide
+        transition_reason: 'Final review found problems with the decision documentation'