workflow.github.example.json

{
  "states": {
    "Backlog": {
      "name": "Backlog",
      "gateType": "manual_entry",
      "includeInAgentContext": false,
      "transitions": {}
    },
    "Ready for Design": {
      "name": "Ready for Design",
      "gateType": "agent_run",
      "pipelineOrder": 1,
      "gitBehavior": "discard",
      "includeInAgentContext": false,
      "providerParams": {
        "effort": "max"
      },
      "steps": [
        {
          "name": "review_related_tickets",
          "role": "board_analyst",
          "taskPromptFile": "prompts/states/steps/review_related_tickets.md"
        },
        {
          "name": "create_design",
          "role": "senior_engineer",
          "taskPromptFile": "prompts/states/ready_for_design.md"
        },
        {
          "name": "review_design_conflicts",
          "role": "senior_engineer",
          "taskPromptFile": "prompts/states/steps/review_design_conflicts.md"
        },
        {
          "name": "estimate_ticket",
          "role": "estimator",
          "taskPromptFile": "prompts/states/steps/estimate_ticket.md"
        }
      ],
      "gateCheck": {
        "role": "gate_checker",
        "taskPromptFile": "prompts/gates/post_design.md"
      },
      "optionalSteps": [
        {
          "name": "ux_interaction_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/ux_interaction_review.md",
          "description": "Reviews interaction flows, user journeys, state transitions, and usability of proposed design.",
          "triggers": "New user-facing features, workflow changes, multi-step interactions, or significant UX restructuring."
        },
        {
          "name": "ui_component_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/ui_component_review.md",
          "description": "Reviews visual design patterns, component reuse, layout structure, and design system consistency.",
          "triggers": "Features with UI components, new pages/views, visual layout changes, or design system extensions."
        },
        {
          "name": "infrastructure_design_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/infrastructure_design_review.md",
          "description": "Reviews infrastructure implications: hosting, scaling, resource provisioning, cost, and deployment topology.",
          "triggers": "Changes to deployment architecture, new services/workers, database provisioning, caching layers, or CI/CD pipeline."
        },
        {
          "name": "data_modeling_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/data_modeling_review.md",
          "description": "Reviews data model design: schema, relationships, storage patterns, migration paths, and data flow.",
          "triggers": "New database tables/columns, schema migrations, data pipeline changes, or storage strategy changes."
        },
        {
          "name": "api_design_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/api_design_review.md",
          "description": "Reviews API contract design: endpoints, request/response shapes, versioning, pagination, and error conventions.",
          "triggers": "New or modified API endpoints, webhook contracts, inter-service communication, or public API changes."
        },
        {
          "name": "security_threat_model",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/security_threat_model.md",
          "description": "Threat modeling: attack surface analysis, trust boundaries, data classification, and auth/authorization design.",
          "triggers": "Features involving authentication, authorization, user data handling, external integrations, or cryptography."
        },
        {
          "name": "performance_design_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/performance_design_review.md",
          "description": "Reviews performance implications: expected load, latency targets, query patterns, caching strategy, and bottleneck analysis.",
          "triggers": "High-traffic features, database-heavy operations, real-time requirements, or large data processing."
        },
        {
          "name": "accessibility_design_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/accessibility_design_review.md",
          "description": "Reviews accessibility considerations: keyboard navigation, screen reader support, color contrast, ARIA patterns.",
          "triggers": "User-facing features with interactive elements, forms, dynamic content, or navigation changes."
        },
        {
          "name": "legal_regulatory_review",
          "role": "senior_specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/legal_regulatory_review.md",
          "description": "Reviews legal and regulatory implications: data protection (GDPR/CCPA), terms of service, licensing, and consent flows.",
          "triggers": "Features handling PII, user consent, data retention/deletion, third-party data sharing, or regulated industries.",
          "providerParams": {
            "effort": "max"
          }
        },
        {
          "name": "migration_compatibility_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/migration_compatibility_review.md",
          "description": "Reviews migration and backward compatibility: rollback paths, feature flags, data migration safety, and client impact.",
          "triggers": "Breaking changes, schema migrations, API version changes, or deprecations affecting existing users."
        },
        {
          "name": "cost_analysis_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/cost_analysis_review.md",
          "description": "Reviews operational cost implications: compute, storage, API call volume, third-party service costs, and scaling economics.",
          "triggers": "New external service integrations, storage-intensive features, high-volume API usage, or infrastructure provisioning."
        },
        {
          "name": "observability_design_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/design/observability_design_review.md",
          "description": "Reviews logging, monitoring, alerting, and debugging design: structured logging, metrics, tracing, and dashboards.",
          "triggers": "New services, background jobs, external integrations, error-prone flows, or SLA-bound features."
        }
      ],
      "transitions": {
        "IN_PROGRESS": "Designing",
        "COMPLETE": [
          {
            "type": "moveToColumn",
            "value": "Designed"
          },
          {
            "type": "setField",
            "field": "Estimate",
            "value": "{{estimation}}"
          }
        ],
        "NEEDS_INFO": "Design Questions",
        "ERROR": "Error",
        "GATE_FAIL": "Ready for Design",
        "MERGE_CONFLICT": "Ready for Implementation"
      }
    },
    "Designing": {
      "name": "Designing",
      "gateType": "in_progress",
      "includeInAgentContext": false,
      "transitions": {}
    },
    "Design Questions": {
      "name": "Design Questions",
      "gateType": "holding",
      "includeInAgentContext": false,
      "transitions": {}
    },
    "Designed": {
      "name": "Designed",
      "gateType": "manual_gate",
      "includeInAgentContext": true,
      "transitions": {}
    },
    "Ready for Implementation": {
      "name": "Ready for Implementation",
      "gateType": "agent_run",
      "pipelineOrder": 2,
      "gitBehavior": "commit_and_push",
      "includeInAgentContext": true,
      "providerParams": {
        "effort": "medium",
        "yolo": "true"
      },
      "steps": [
        {
          "name": "implement",
          "role": "implementer",
          "taskPromptFile": "prompts/states/ready_for_implementation.md"
        },
        {
          "name": "code_review",
          "role": "code_reviewer",
          "taskPromptFile": "prompts/states/steps/code_review.md"
        }
      ],
      "gateCheck": {
        "role": "gate_checker",
        "taskPromptFile": "prompts/gates/post_implementation.md"
      },
      "optionalSteps": [
        {
          "name": "security_audit",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/security_audit.md",
          "description": "Reviews code for security vulnerabilities, injection risks, auth flaws, and data exposure.",
          "triggers": "Changes to authentication, authorization, API endpoints, user input processing, data serialization, or cryptography.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "soc2_compliance_audit",
          "role": "senior_specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/soc2_compliance_audit.md",
          "description": "Thorough SOC2 compliance audit: audit logging, data retention, access controls, encryption.",
          "triggers": "Changes to audit logging, data retention, access controls, encryption, or explicit compliance requirements.",
          "providerParams": {
            "effort": "max"
          }
        },
        {
          "name": "infrastructure_code_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/infrastructure_code_review.md",
          "description": "Reviews IaC, deployment scripts, CI/CD changes, container configs, and environment management.",
          "triggers": "Changes to Dockerfiles, CI/CD workflows, Terraform/CDK, environment variables, or deployment scripts.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "performance_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/performance_review.md",
          "description": "Reviews for N+1 queries, blocking I/O, missing indexes, and algorithmic complexity.",
          "triggers": "Database query changes, loop-heavy processing, high-traffic paths, or cache logic.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "accessibility_audit",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/accessibility_audit.md",
          "description": "WCAG 2.1 AA compliance: semantic HTML, ARIA, keyboard nav, focus, contrast.",
          "triggers": "UI component changes, forms, modals, navigation changes, or dynamic content updates.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "api_contract_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/api_contract_review.md",
          "description": "Reviews API changes for backward compatibility, error consistency, and client impact.",
          "triggers": "Modified API endpoints, changed request/response schemas, new error codes, or versioning changes.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "database_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/database_review.md",
          "description": "Reviews schema changes, migration safety, query performance, and data integrity.",
          "triggers": "New/altered tables, migration scripts, complex queries, transaction logic, or foreign key changes.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "dependency_audit",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/dependency_audit.md",
          "description": "Reviews third-party dependencies: known vulnerabilities, license compatibility, and supply chain risk.",
          "triggers": "New package additions, version upgrades, or changes to dependency resolution.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "ui_visual_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/ui_visual_review.md",
          "description": "Reviews visual implementation: design system adherence, responsive layout, theming, spacing/typography consistency.",
          "triggers": "UI component implementation, CSS/style changes, theme modifications, or responsive layout work.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "error_handling_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/error_handling_review.md",
          "description": "Reviews error handling completeness: exception coverage, user-facing errors, retry logic, and graceful degradation.",
          "triggers": "New error paths, external service calls, user input validation, or changes to error reporting.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "internationalization_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/internationalization_review.md",
          "description": "Reviews i18n readiness: string externalization, locale handling, date/number formatting, RTL support.",
          "triggers": "User-facing text additions, date/time handling, currency/number formatting, or locale-dependent logic.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "privacy_review",
          "role": "senior_specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/impl/privacy_review.md",
          "description": "Reviews data privacy practices: PII handling, data minimization, consent enforcement, anonymization.",
          "triggers": "Changes to user data collection, storage, processing, sharing, or deletion flows.",
          "providerParams": {
            "effort": "max"
          }
        }
      ],
      "transitions": {
        "IN_PROGRESS": "Implementing",
        "COMPLETE": "Ready for Test",
        "NEEDS_INFO": "Implementation Questions",
        "ERROR": "Error",
        "GATE_FAIL": "Ready for Implementation"
      }
    },
    "Implementing": {
      "name": "Implementing",
      "gateType": "in_progress",
      "includeInAgentContext": true,
      "transitions": {}
    },
    "Implementation Questions": {
      "name": "Implementation Questions",
      "gateType": "holding",
      "includeInAgentContext": true,
      "transitions": {}
    },
    "Ready for Test": {
      "name": "Ready for Test",
      "gateType": "agent_run",
      "pipelineOrder": 3,
      "gitBehavior": "commit_and_push",
      "includeInAgentContext": true,
      "providerParams": {
        "effort": "medium"
      },
      "steps": [
        {
          "name": "qa_validation",
          "role": "qa",
          "taskPromptFile": "prompts/states/ready_for_test.md"
        },
        {
          "name": "update_documentation",
          "role": "implementer",
          "taskPromptFile": "prompts/states/steps/update_documentation.md"
        }
      ],
      "gateCheck": {
        "role": "gate_checker",
        "taskPromptFile": "prompts/gates/post_test.md"
      },
      "optionalSteps": [
        {
          "name": "security_test_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/security_test_review.md",
          "description": "Reviews security testing adequacy: auth test coverage, authorization boundary tests, injection testing.",
          "triggers": "Implementation included auth, input handling, data exposure, or API security changes.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "performance_test_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/performance_test_review.md",
          "description": "Reviews performance testing coverage: load tests, latency benchmarks, resource utilization tests.",
          "triggers": "Implementation included high-traffic paths, database-heavy operations, or performance-sensitive changes.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "accessibility_test_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/accessibility_test_review.md",
          "description": "Reviews accessibility testing completeness: automated a11y scans, keyboard navigation, WCAG checkpoint verification.",
          "triggers": "Implementation included UI changes, interactive components, or navigation modifications.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "integration_test_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/integration_test_review.md",
          "description": "Reviews integration and E2E test coverage: external service tests, cross-component flows, failure scenarios.",
          "triggers": "Implementation included external API calls, multi-component interactions, or event-driven flows.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "edge_case_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/edge_case_review.md",
          "description": "Reviews boundary condition and edge case coverage: null/empty inputs, overflow, concurrency, race conditions.",
          "triggers": "Implementation included input validation, numeric operations, concurrent access, or state machine logic.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "regression_risk_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/regression_risk_review.md",
          "description": "Assesses regression risk: identifies areas impacted by changes that may lack test coverage.",
          "triggers": "Implementation touched shared utilities, core abstractions, or widely-referenced modules.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "data_integrity_test_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/data_integrity_test_review.md",
          "description": "Reviews data validation and consistency testing: constraint enforcement, referential integrity, migration rollback.",
          "triggers": "Implementation included schema changes, data migration, or data transformation logic.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "compliance_test_review",
          "role": "senior_specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/compliance_test_review.md",
          "description": "Reviews compliance verification testing: audit log tests, data retention verification, consent flow tests.",
          "triggers": "Implementation included compliance-related changes (audit logging, data retention, access controls).",
          "providerParams": {
            "effort": "max"
          }
        },
        {
          "name": "disaster_recovery_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/disaster_recovery_review.md",
          "description": "Reviews failure mode testing: service outage handling, data recovery procedures, failover verification.",
          "triggers": "Implementation included infrastructure changes, data storage modifications, or high-availability features.",
          "providerParams": {
            "effort": "medium"
          }
        },
        {
          "name": "monitoring_alerting_review",
          "role": "specialist_reviewer",
          "taskPromptFile": "prompts/optional-steps/test/monitoring_alerting_review.md",
          "description": "Reviews observability testing: log output verification, metric emission tests, alert threshold validation.",
          "triggers": "Implementation included new logging, metrics, alerting rules, or monitoring integration.",
          "providerParams": {
            "effort": "medium"
          }
        }
      ],
      "transitions": {
        "IN_PROGRESS": "Testing",
        "COMPLETE": "Tested",
        "NEEDS_INFO": "Implementation Questions",
        "ERROR": "Error",
        "GATE_FAIL": "Ready for Test",
        "MERGE_CONFLICT": "Ready for Implementation"
      }
    },
    "Testing": {
      "name": "Testing",
      "gateType": "in_progress",
      "includeInAgentContext": true,
      "transitions": {}
    },
    "Tested": {
      "name": "Tested",
      "gateType": "manual_gate",
      "includeInAgentContext": true,
      "transitions": {}
    },
    "Approved": {
      "name": "Approved",
      "gateType": "system_merge",
      "pipelineOrder": 4,
      "includeInAgentContext": false,
      "providerParams": {
        "maxRetries": "3"
      },
      "transitions": {
        "IN_PROGRESS": "Merging",
        "COMPLETE": "Done",
        "ERROR": "Error",
        "MERGE_CONFLICT": "Ready for Implementation"
      }
    },
    "Merging": {
      "name": "Merging",
      "gateType": "in_progress",
      "includeInAgentContext": false,
      "transitions": {}
    },
    "Done": {
      "name": "Done",
      "gateType": "terminal",
      "includeInAgentContext": false,
      "transitions": {}
    },
    "Error": {
      "name": "Error",
      "gateType": "holding",
      "includeInAgentContext": false,
      "transitions": {}
    }
  },
  "roles": {
    "senior_engineer": {
      "model": "claude-opus-4-6",
      "systemPromptFile": "prompts/senior_engineer.md",
      "sections": [
        "Design Review Summary",
        "Technical Design",
        "Decisions",
        "Implementation"
      ]
    },
    "qa": {
      "model": "claude-opus-4-6",
      "systemPromptFile": "prompts/qa.md",
      "sections": [
        "Test Plan",
        "Test Results"
      ]
    },
    "implementer": {
      "model": "claude-sonnet-4-6",
      "systemPromptFile": "prompts/senior_engineer.md",
      "sections": [
        "Technical Design",
        "Decisions",
        "Implementation"
      ]
    },
    "code_reviewer": {
      "model": "claude-sonnet-4-6",
      "systemPromptFile": "prompts/code_reviewer.md",
      "sections": []
    },
    "merge_resolver": {
      "model": "claude-sonnet-4-6",
      "systemPromptFile": "prompts/merge_resolver.md",
      "sections": []
    },
    "gate_checker": {
      "model": "claude-haiku-4-5-20251001",
      "systemPromptFile": "prompts/gate_checker.md",
      "sections": []
    },
    "estimator": {
      "model": "claude-haiku-4-5-20251001",
      "systemPromptFile": "prompts/estimator.md",
      "sections": []
    },
    "board_analyst": {
      "model": "claude-haiku-4-5-20251001",
      "systemPromptFile": "prompts/board_analyst.md",
      "sections": []
    },
    "specialist_reviewer": {
      "model": "claude-sonnet-4-6",
      "systemPromptFile": "prompts/specialist_reviewer.md",
      "sections": []
    },
    "senior_specialist_reviewer": {
      "model": "claude-opus-4-6",
      "systemPromptFile": "prompts/senior_specialist_reviewer.md",
      "sections": []
    }
  },
  "mergeResolution": {
    "role": "merge_resolver",
    "providerParams": {
      "effort": "medium"
    }
  },
  "polling": {
    "priorityFieldName": "priority",
    "priorityOrder": [
      "P0",
      "P1",
      "P2"
    ]
  },
  "estimation": {
    "calibrationTicketId": "34",
    "calibrationSize": 1,
    "fieldName": "Estimate",
    "scale": [
      1,
      2,
      4,
      8
    ]
  },
  "cardTypes": {
    "story": {
      "name": "User Story",
      "labelPrefix": "type",
      "allowedChildren": [
        "task"
      ]
    },
    "task": {
      "name": "Task",
      "labelPrefix": "type",
      "allowedChildren": []
    }
  }
}