@codemcp/workflows 6.0.1 → 6.0.2

package/packages/mcp-server/resources/workflows/business-analysis.yaml

@@ -0,0 +1,597 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'business-analysis'
+description: 'Business Capability Modeling workflow that analyzes systems from a pure business perspective. Creates hierarchical business capability maps, service catalogs, and process documentation using industry-standard Business Capability Modeling methodology.'
+initial_state: 'document_discovery'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'architecture'
+  complexity: 'medium'
+  bestFor:
+    - 'Business capability modeling'
+    - 'Business architecture analysis'
+    - 'Business service cataloging'
+    - 'Business process documentation'
+  useCases:
+    - 'Create business capability maps from system documentation'
+    - 'Document business services and processes'
+    - 'Analyze organizational business functions'
+  examples:
+    - 'Model business capabilities for legacy system understanding'
+    - 'Create business service catalog for domain architects'
+    - 'Document business processes and organizational roles'
+
+# States with default instructions and transitions
+states:
+  document_discovery:
+    description: 'Gather business documents and create standardized Business Capability Modeling structure'
+    default_instructions: >
+      **STEP 1: Gather Business Documents**
+      Ask user to identify and provide available documents:
+      - Business process documentation
+      - Organizational charts
+      - System documentation
+      - Existing c4-analysis results
+      - Business requirements documents
+
+      IMPORTANT: Do not read the documents yet.
+
+      **STEP 2: Create Document Processing Tasks**
+      For each gathered document, create a processing task:
+      `- [ ] Summarize [document-name] using structured chapter-by-chapter approach`
+
+      Update task progress and create document processing tasks.
+    transitions:
+      - trigger: 'discovery_complete'
+        to: 'documents_consolidation'
+        transition_reason: 'Documents gathered and Business Capability Modeling structure created, ready for consolidation'
+
+  documents_consolidation:
+    description: 'Process and consolidate gathered documents using structured summarization'
+    default_instructions: >
+      **STEP 1: Apply Structured Summarization Technique**
+      Process each document using this approach:
+      1. Read document chapter by chapter
+      2. Maintain original hierarchical structure
+      3. Condense content while preserving key information
+      4. Create `[document-name]-processed.md` file
+      5. Update task progress as complete
+
+      **STEP 2: Follow Summarization Guidelines**
+      - Create structured summary based exclusively on source document information
+      - Identify chapters and hierarchy levels systematically
+      - Summarize level-by-level into `[document-name]-processed.md`
+      - Write chapter summaries in natural language (no bullet points)
+      - Include information about potential capabilities, services, processes, or actors
+      - Maintain folder structure if documents have associated folders
+
+      **STEP 3: Create Bibliography**
+      Create `BIBLIOGRAPHY.md` with:
+      - "sources" section listing all processed documents
+      - "terms" section with important business terms and their source references
+
+      IMPORTANT: This phase focuses only on basic document processing. Business analysis happens in the next phase.
+    transitions:
+      - trigger: 'consolidation_complete'
+        to: 'business_content_analysis'
+        transition_reason: 'Basic document processing complete, ready for business content analysis'
+
+  business_content_analysis:
+    description: 'Identify and analyze business-relevant content from processed documents'
+    default_instructions: >
+      **STEP 1: Review Processed Documents**
+      Review all `[document-name]-processed.md` files from consolidation phase.
+      Identify chapters that contain business-relevant content:
+      - Business processes and workflows
+      - Organizational roles and responsibilities
+      - Business capabilities and functions
+      - Services and customer interactions
+      - Business rules and policies
+
+      **STEP 2: Create Business Analysis Tasks**
+      For each business-relevant chapter identified, create a task:
+      `- [ ] Extract business capabilities from [chapter-name]`
+
+      IMPORTANT: Create these tasks before proceeding.
+
+      **STEP 3: Execute Business Analysis Tasks**
+      For each business analysis task:
+      1. Read the specific chapter in detail
+      2. Extract business information focusing on:
+         - What business capabilities are mentioned
+         - What services or processes are described
+         - Who (roles/actors) performs the work
+         - Why (business value/purpose) it exists
+      3. Create detailed business summary emphasizing WHAT, WHY, WHO (not HOW)
+      4. Update task progress as complete
+
+      **STEP 4: Update Bibliography with Business Terms**
+      Update `BIBLIOGRAPHY.md` with business terms found during detailed analysis:
+      - Check whether the "sources" section contains an entry. If not: create one (max 5 letters in brackets).
+      - In the "terms" section, check whether there is an entry for it. If not, create an entry.
+      - Add a reference to the source and chapter.
+
+      Example (Document "operations manual" with "payment processing" in Chapter 5.2):
+      - Operations Manual `[OPMAN]`
+      - payment processing
+        - `OPMAN, 5.2`
+
+      Example (Document "requirements.md" with "payment processing" in Chapter 1.2.1):
+      - Requirements `[REQ]`
+      - payment processing
+        - `REQ, 1.2.1`
+
+      Process business analysis tasks systematically, one at a time.
+    transitions:
+      - trigger: 'business_analysis_complete'
+        to: 'capability_identification'
+        additional_instructions: >
+          **Create Standardized Analysis Documentation**
+
+          Create `BUSINESS_ANALYSIS.md` with the following template content:
+          ```markdown
+          # Business Analysis Report
+
+          *This report documents business capabilities using Business Capability Modeling methodology. It provides a hierarchical view of what the business does, how it delivers value, and who performs the work.*
+
+          ## Methodology
+          This analysis uses **Business Capability Modeling**, an industry-standard approach for understanding business architecture:
+
+          - **Business Domains**: High-level areas of business activity
+          - **Business Capabilities**: What the business does (stable, outcome-focused)
+          - **Business Services**: How capabilities are delivered to consumers
+          - **Business Processes**: Step-by-step activities that deliver services
+          - **Business Actors**: Roles and organizational units that perform the work
+
+          **Hierarchy**: Domain → Capability → Sub-Capability → Service → Process → Actor
+
+          ## Executive Summary
+          <!-- High-level business capability overview -->
+
+          ## Business Domains Identified
+          <!-- Main business domains discovered -->
+
+          ## Key Business Capabilities
+          <!-- Primary capabilities mapped hierarchically -->
+
+          ## Business Services Catalog
+          <!-- Services that deliver capabilities -->
+
+          ## Business Architecture Insights
+          <!-- Important findings and patterns -->
+
+          ## Recommendations
+          <!-- Business capability recommendations -->
+          ```
+
+          Create `business-processes-detailed.md` with template:
+          ```markdown
+          # Business Processes Detailed
+
+          ## Overview
+          This document details business processes for each capability.
+
+          ## Process Overview by Capability
+          <!-- Process summaries for each capability -->
+
+          ## Process Flow Diagrams
+          <!-- Detailed process flows -->
+
+          ## Process Actors and Responsibilities
+          <!-- Key roles in each process -->
+          ```
+
+          Create `business-functions-mapping.md` with template:
+          ```markdown
+          # Business Functions Mapping
+
+          ## Overview
+          This document maps organizational functions to business capabilities.
+
+          ## Organizational Structure
+          <!-- High-level org structure -->
+
+          ## Function-Capability Mappings
+          <!-- Which functions support which capabilities -->
+
+          ## Roles and Responsibilities
+          <!-- Key roles and their responsibilities -->
+          ```
+
+          Create `technical-business-mapping.md` with template:
+          ```markdown
+          # Technical-Business Mapping
+
+          ## Overview
+          This document maps technical components to business capabilities.
+
+          ## Technical Architecture Overview
+          <!-- High-level technical architecture -->
+
+          ## Component-Capability Mappings
+          <!-- Which technical components support which capabilities -->
+
+          ## Business Value Assessments
+          <!-- Business value of each technical component -->
+          ```
+
+          **Create Standardized Business Capability Modeling Folder Structure**
+          - `business-analysis/business-domains/` (folder for details)
+          - `business-analysis/business-capabilities/` (folder for details)
+          - `business-analysis/business-processes/` (folder for details)
+          - `business-analysis/business-actors/` (folder for details)
+
+          Begin analyzing processed documents to identify business capabilities and domains.
+          Update task progress as you complete business analysis work.
+        transition_reason: 'Business content analysis complete, ready for capability identification'
+
+  capability_identification:
+    description: 'Identify business capabilities from processed documents'
+    default_instructions: >
+      IMPORTANT: Always reference the existing documents.
+
+      **STEP 1: Analyze Processed Documents**
+      Review all `[document-name]-processed.md` files from consolidation phase.
+      Look for:
+      - Business functions mentioned
+      - Activities and processes described
+      - Services or offerings referenced
+      - Organizational responsibilities
+      - System functionalities with business purpose
+
+      **STEP 2: Extract Potential Capabilities**
+      From document analysis, create initial list of business capabilities.
+      Group similar activities and functions together.
+      Use Business Capability Modeling naming: `[Verb] + [Business Object]` (e.g., "Manage Customers", "Process Orders")
+
+      **STEP 3: Identify Business Domains**
+      Group capabilities into logical business domains:
+      - Customer-related capabilities → Customer Management
+      - Order-related capabilities → Order Management
+      - Financial capabilities → Financial Management
+      - etc.
+
+      **STEP 4: Present Findings to User**
+      Show user the identified capabilities and domains:
+
+      "Based on the documents, I identified these business domains and capabilities: [Present structured list]
+
+      Do these align with your understanding? Are there any capabilities missing or incorrectly categorized?"
+
+      **STEP 5: Refine with User Input**
+      Adjust the capability model based on user feedback.
+      Document final capability list in `business-capabilities.md`.
+
+    transitions:
+      - trigger: 'capabilities_identified'
+        to: 'capability_decomposition'
+        additional_instructions: >
+          For each identified capability, create decomposition tasks:
+          `- [ ] Decompose [capability-name] into sub-capabilities using document analysis`
+
+          Begin systematic decomposition of capabilities one at a time.
+        transition_reason: 'Business capabilities identified, ready for detailed decomposition'
+
+  capability_decomposition:
+    description: 'Break down business capabilities into detailed sub-capabilities using document analysis'
+    default_instructions: >
+      IMPORTANT: Always reference the existing documents.
+
+      **STEP 1: Analyze Documents for Sub-capabilities**
+      Review processed documents for the next unprocessed capability:
+      - Look for detailed activities mentioned within this capability
+      - Identify specific processes or functions described
+      - Find decision points and workflow steps
+      - Note different outcomes or deliverables mentioned
+
+      **STEP 2: Extract Potential Sub-capabilities**
+      From document analysis, create initial list of sub-capabilities.
+      Use Business Capability Modeling naming: `[Verb] + [Business Object]`
+
+      Example: For "Customer Management" → "Verify Customer Identity", "Setup Customer Account", "Maintain Customer Data"
+
+      **STEP 3: Present Findings to User**
+      Show user the identified sub-capabilities:
+
+      "Based on the documents, I identified these sub-capabilities for `[capability]`: [Present structured list]
+
+      Do these sub-capabilities accurately reflect `[capability]`? Are any activities missing or incorrectly categorized?"
+
+      **STEP 4: Refine with User Input**
+      Adjust the sub-capability model based on user feedback.
+      Document refined decomposition in `business-capabilities/` detail folder.
+      Mark capability as complete and ask: "Ready for the next capability?"
+
+    transitions:
+      - trigger: 'decomposition_complete'
+        to: 'actor_analysis'
+        additional_instructions: >
+          Create `business-actors.md` with template:
+          ```markdown
+          # Business Actors
+
+          ## Overview
+          This document maps business actors (roles and organizational units) to capabilities using Business Capability Modeling methodology.
+
+          ## Actor-Capability Mappings
+          <!-- For each capability, document:
+          - Primary Owner: Who is accountable for capability outcomes
+          - Performing Roles: Which roles actually execute the capability
+          - Supporting Units: Which organizational units support the capability
+          - Decision Authority: Who has authority to change/approve within this capability -->
+
+          ## Role Definitions
+          <!-- Detailed definitions of key business roles -->
+
+          ## Organizational Units
+          <!-- Key organizational units and their responsibilities -->
+          ```
+
+          For each capability, create actor analysis tasks:
+          `- [ ] Analyze business actors for [capability-name] using document analysis`
+
+          Begin systematic actor analysis one capability at a time.
+          Update task progress as you complete decomposition work.
+        transition_reason: 'Capability decomposition complete, ready for actor analysis'
+
+  actor_analysis:
+    description: 'Map business actors (roles and organizational units) to capabilities using systematic task-based approach'
+    default_instructions: >
+      **STEP 1: Select Next Capability for Actor Analysis**
+      From current tasks, select the next capability to analyze for business actors.
+
+      **STEP 2: Analyze Documents for Business Actors**
+      Review processed documents to identify:
+      - **Business Roles**: Specific job roles (Customer Service Rep, Account Manager, etc.)
+      - **Organizational Units**: Teams/departments (Sales Team, Finance Department, etc.)
+      - **Decision-making Authority**: Who makes decisions for this capability
+      - **Accountability**: Who is responsible for capability outcomes
+
+      **STEP 3: Map Actors to Capabilities**
+      For the selected capability, identify:
+      - **Primary Owner**: Who is accountable for capability outcomes
+      - **Performing Roles**: Which roles actually execute the capability
+      - **Supporting Units**: Which organizational units support the capability
+      - **Decision Authority**: Who has authority to change/approve within this capability
+
+      **STEP 4: Create Actor Analysis Document**
+      Document the actor mappings in `business-actors.md`:
+      - **Primary Owner**: Who is accountable for capability outcomes
+      - **Performing Roles**: Which roles actually execute the capability
+      - **Supporting Units**: Which organizational units support the capability
+      - **Decision Authority**: Who has authority to change/approve within this capability
+
+      Then present to user for validation:
+      "I documented the business actors for `[capability]`. Please review the actor mappings - do they accurately reflect WHO performs this capability?"
+
+      **STEP 5: Refine and Document**
+      Update `business-actors.md` with capability-actor mappings.
+      Update task progress as complete.
+
+      Focus on capability ownership and role accountability, not just organizational structure.
+      Process one capability at a time.
+    transitions:
+      - trigger: 'actor_analysis_complete'
+        to: 'process_analysis'
+        additional_instructions: >
+          Create `business-processes.md` with template:
+          ```markdown
+          # Business Processes
+
+          ## Overview
+          This document details business processes that deliver capabilities.
+
+          ## Process Overview by Capability
+          <!-- Process summaries for each capability -->
+
+          ## Process Flow Diagrams
+          <!-- Detailed process flows and decision points -->
+
+          ## Process-Actor Relationships
+          <!-- How processes relate to the actors identified -->
+          ```
+
+          For each capability, create process analysis tasks:
+          `- [ ] Analyze business processes for [capability-name] using document analysis and actor context`
+
+          Begin systematic process analysis one capability at a time.
+          Update task progress as you complete actor analysis work.
+        transition_reason: 'Actor analysis complete, ready for process analysis'
+
+  process_analysis:
+    description: 'Analyze business processes using systematic task-based approach'
+    default_instructions: >
+      **STEP 1: Select Next Process Analysis Task**
+      From current process analysis tasks, select the next capability to process.
+
+      **STEP 2: Analyze Documents for Process Information**
+      Review processed documents for process information:
+      - Look for process steps, workflows, decision points
+      - Identify process actors, inputs, outputs
+      - Note process triggers and outcomes
+      - Find process rules and constraints
+
+      **STEP 3: Extract Processes**
+      Create process flows from document analysis.
+      Document process characteristics:
+      - Process name and purpose
+      - Process steps and sequence
+      - Decision points and branches
+      - Process actors and responsibilities
+      - Inputs, outputs, and deliverables
+
+      **STEP 4: Present to User**
+      Show identified processes and ask for validation:
+
+      "Based on documents, I identified these processes for `[capability]`: [Present process flows]
+
+      Do these processes accurately reflect how `[capability]` works? Are any process steps missing or incorrectly sequenced?"
+
+      **STEP 5: Refine and Document**
+      Update `business-processes-detailed.md` and detail folder.
+      Update task progress as complete.
+
+      Process one capability at a time.
+    transitions:
+      - trigger: 'process_analysis_complete'
+        to: 'consistency'
+        additional_instructions: >
+          Present the Business Capability Consistency Framework to user:
+
+          "I'll now validate consistency across all analysis documents using this framework:
+
+          **Business Capability Consistency Framework:**
+          - **Capability-Process Alignment**: Do processes actually deliver the stated capabilities?
+          - **Actor-Capability Ownership**: Are actors properly assigned to capability outcomes?
+          - **Process-Actor Mapping**: Do processes reference the correct performing actors?
+          - **Cross-Document Coherence**: Same entities described consistently across documents?
+          - **Completeness Validation**: All expected sections present and properly linked?
+
+          This ensures our business capability model is internally consistent before final summary.
+          Ready to proceed with consistency validation?"
+        transition_reason: 'Process analysis complete, ready for consistency validation'
+
+  consistency:
+    description: 'Validate consistency across all business capability analysis documents'
+    default_instructions: >
+      **STEP 1: Discover Analysis Documents**
+      Scan workspace for all created analysis documents:
+      - `business-domains.md` and detail folders
+      - `business-capabilities.md` and detail folders
+      - `business-processes.md` and detail folders
+      - `business-actors.md` and detail folders
+      - `BUSINESS_ANALYSIS.md`
+      - Any other analysis artifacts created
+
+      **STEP 2: Apply Consistency Framework**
+      Execute each consistency check:
+
+      - **Capability-Process Alignment Check**:
+        - Do documented processes actually deliver the stated capabilities?
+        - Are there capabilities without supporting processes?
+        - Are there processes that don't map to any capability?
+
+      - **Actor-Capability Ownership Check**:
+        - Is each capability assigned a clear primary owner (actor)?
+        - Are performing roles properly mapped to capabilities?
+        - Do actors have decision authority for their assigned capabilities?
+
+      - **Process-Actor Mapping Check**:
+        - Do processes reference the correct performing actors?
+        - Are actor responsibilities aligned with process steps?
+        - Is there clear accountability in each process?
+
+      - **Cross-Document Coherence Check**:
+        - Are capabilities named consistently across documents?
+        - Do actor definitions match across process and capability docs?
+        - Are business terms used consistently throughout?
+
+      - **Completeness Validation**:
+        - Are all expected document sections present?
+        - Do internal links work correctly?
+        - Are references to other documents accurate?
+
+      **STEP 3: Document Issues and Fixes**
+      Create `CONSISTENCY_REPORT.md` documenting:
+      - Issues found during validation
+      - Fixes applied to resolve inconsistencies
+      - Remaining gaps or recommendations
+
+      **STEP 4: Present Findings to User**
+      Show consistency validation results and ask for confirmation:
+
+      "Consistency validation complete. Found `[X]` issues, resolved `[Y]`.
+      Key findings: `[summary of major consistency improvements]`
+
+      Are you satisfied with the consistency of the business capability model?"
+
+      Focus on ensuring the business capability model is internally coherent before final summary.
+    transitions:
+      - trigger: 'consistency_complete'
+        to: 'summary'
+        additional_instructions: >
+          Ask user about illustration format preference:
+          "How would you like diagrams and illustrations formatted in the final summary?
+          - ASCII diagrams (text-based, simple)
+          - Mermaid diagrams (code-based, rich formatting)
+          - PlantUML diagrams (UML standard, detailed)
+          - All three formats (comprehensive)"
+
+          Begin creating consolidated summaries and illustrations.
+          Update task progress as you complete consistency work.
+        transition_reason: 'Consistency validation complete, ready for final summary creation'
+
+  summary:
+    description: 'Create consolidated summaries and illustrations for business capability analysis'
+    default_instructions: >
+      **STEP 1: Create Consolidated Overviews**
+      Build comprehensive summary documents:
+      - **Executive Summary**: High-level business capability overview for leadership
+      - **Capability Map**: Hierarchical view of all business capabilities
+      - **Actor-Capability Matrix**: Who owns/performs each capability
+      - **Process Overview**: Key processes supporting capabilities
+      - **Navigation Guide**: How to use all analysis documents
+
+      **STEP 2: Generate Illustrations**
+      Using user's chosen format(s) (ASCII/Mermaid/PlantUML):
+      - Business capability hierarchy diagrams
+      - Process flow diagrams
+      - Actor-capability relationship maps
+      - Cross-functional process flows
+      - Organizational responsibility charts
+
+      **STEP 3: Fix Links and References**
+      - Standardize internal document links
+      - Create cross-references between related content
+      - Build table of contents for navigation
+      - Ensure all references are accurate and working
+
+      **STEP 4: Update BUSINESS_ANALYSIS.md**
+      Finalize the main analysis document with:
+      - Complete executive summary
+      - Key findings and insights
+      - Business architecture recommendations
+      - Links to all detailed analysis documents
+      - Methodology explanation and validation results
+
+      **STEP 5: Present Final Deliverables**
+      Show completed analysis to user:
+
+      "Business Capability Analysis complete! Final deliverables: [Present overview of all documents, diagrams, and summaries]
+
+      This provides comprehensive business architecture understanding for domain architects.
+      Are you satisfied with the final analysis deliverables?"
+
+      Focus on creating business-friendly, navigable documentation that serves domain architects.
+    transitions:
+      - trigger: 'summary_complete'
+        to: 'analysis_complete'
+        additional_instructions: >
+          Summary creation is complete! ✅
+
+          Final Business Capability Analysis deliverables ready:
+          - Consolidated executive summaries
+          - Business capability maps and diagrams
+          - Actor-capability matrices
+          - Process flow documentation
+          - Navigation guides and cross-references
+
+          The analysis provides complete business architecture understanding using Business Capability Modeling methodology.
+          Update task progress as you complete summary work.
+        transition_reason: 'Summary creation complete, analysis finished'
+
+  analysis_complete:
+    description: 'Business analysis complete'
+    default_instructions: >
+      Business analysis is complete! The system has been thoroughly analyzed using Business Capability Modeling methodology.
+
+      **Final Deliverables:**
+      - Comprehensive business architecture documentation (Business Capability Modeling-based)
+      - `BUSINESS_ANALYSIS.md` with complete analysis findings
+      - Business capability maps and process flows
+      - Technical-business alignment documentation
+      - Business-friendly documentation for domain architects
+
+      The analysis provides a solid foundation for business architecture decisions and technical-business alignment.
+    transitions: []