Workflow System

interface Workflow {
  id: string;
  name: string;
  type: 'greenfield' | 'brownfield';
  project_types: string[];
  sequence: WorkflowStep[];
  decision_guidance: { when_to_use: string[] };
  handoff_prompts: Record<string, string>;
}

interface WorkflowStep {
  agent?: string;                // Agent ID
  step?: string;                 // Step name
  action?: string;               // Action to perform
  creates?: string | string[];   // Artifacts created
  updates?: string | string[];   // Artifacts updated
  requires?: string | string[];  // Required inputs
  uses?: string | string[];      // Tasks/checklists
  condition?: string;            // Conditional execution
  optional?: boolean;            // Optional step
  repeats?: string;              // Repeat condition
}

workflow:
  id: greenfield-fullstack
  type: greenfield
  project_types: [web-app, saas, enterprise-app, prototype, mvp]

  sequence:
    - agent: analyst
      creates: project-brief.md
      optional_steps: [brainstorming_session, market_research_prompt]

    - agent: pm
      creates: prd.md
      requires: project-brief.md

    - agent: ux-expert
      creates: front-end-spec.md
      requires: prd.md
      optional_steps: [user_research_prompt]

    - agent: ux-expert
      creates: v0_prompt
      requires: front-end-spec.md
      condition: user_wants_ai_generation
      optional: true

    - agent: architect
      creates: fullstack-architecture.md
      requires: [prd.md, front-end-spec.md]
      optional_steps: [technical_research_prompt, review_generated_ui_structure]

    - agent: pm
      updates: prd.md
      requires: fullstack-architecture.md
      condition: architecture_suggests_prd_changes

    - agent: po
      action: validate_artifacts
      uses: po-master-checklist

    - agent: po
      action: shard_documents
      creates: sharded_docs

    - agent: sm
      action: create_story
      creates: story.md
      requires: sharded_docs
      repeats: for_each_epic

    - agent: dev
      action: implement_story
      creates: implementation_files
      requires: story.md

    - agent: qa
      action: review_implementation
      updates: implementation_files
      optional: true

    - agent: dev
      action: address_qa_feedback
      condition: qa_left_unchecked_items

  artifacts:
    - project-brief.md
    - prd.md
    - front-end-spec.md
    - fullstack-architecture.md
    - docs/prd/ (sharded)
    - docs/architecture/ (sharded)
    - docs/stories/*.md

workflow:
  id: greenfield-service
  type: greenfield
  project_types: [api, microservice, backend-service, data-pipeline, cli-tool]

  sequence:
    - agent: analyst
      creates: project-brief.md
      optional_steps: [brainstorming_session, market_research_prompt]

    - agent: pm
      creates: prd.md
      requires: project-brief.md

    - agent: architect
      creates: architecture.md
      requires: prd.md
      optional_steps: [technical_research_prompt]

    - agent: pm
      updates: prd.md
      requires: architecture.md
      condition: architecture_suggests_prd_changes

    - agent: po
      action: validate_artifacts
      uses: po-master-checklist

    - agent: po
      action: shard_documents
      creates: sharded_docs

    - agent: sm
      action: create_story
      creates: story.md
      requires: sharded_docs
      repeats: for_each_epic

    - agent: dev
      action: implement_story
      creates: implementation_files
      requires: story.md

    - agent: qa
      action: review_implementation
      updates: implementation_files
      optional: true

  artifacts:
    - project-brief.md
    - prd.md
    - architecture.md
    - docs/prd/ (sharded)
    - docs/architecture/ (sharded)
    - docs/stories/*.md

workflow:
  id: greenfield-ui
  type: greenfield
  project_types: [frontend-app, spa, mobile-app, desktop-app, ui-library]

  sequence:
    - agent: analyst
      creates: project-brief.md

    - agent: pm
      creates: prd.md

    - agent: ux-expert
      creates: front-end-spec.md

    - agent: ux-expert
      creates: v0_prompt
      condition: user_wants_ai_generation
      optional: true

    - agent: architect
      creates: front-end-architecture.md

    - agent: pm
      updates: prd.md
      condition: architecture_suggests_prd_changes

    - agent: po
      action: validate_artifacts

    - agent: po
      action: shard_documents

    - agent: sm
      action: create_story
      repeats: for_each_epic

    - agent: dev
      action: implement_story

    - agent: qa
      action: review_implementation
      optional: true

  artifacts:
    - project-brief.md
    - prd.md
    - front-end-spec.md
    - front-end-architecture.md
    - docs/prd/ (sharded)
    - docs/architecture/ (sharded)
    - docs/stories/*.md

workflow:
  id: brownfield-fullstack
  type: brownfield
  project_types: [existing-web-app, existing-saas, legacy-modernization, feature-addition]

  sequence:
    - step: document_existing_project
      action: flatten_codebase
      creates: flattened-codebase.xml
      notes: "Use 'npx bmad-method flatten'"

    - agent: pm
      creates: brownfield-prd.md
      requires: flattened-codebase.xml
      notes: "Uses brownfield-prd-tmpl"

    - agent: ux-expert
      creates: front-end-spec.md
      requires: brownfield-prd.md
      condition: ui_changes_needed
      optional: true

    - agent: architect
      creates: brownfield-architecture.md
      requires: brownfield-prd.md
      notes: "Uses brownfield-architecture-tmpl"

    - agent: pm
      updates: brownfield-prd.md
      requires: brownfield-architecture.md
      condition: architecture_suggests_prd_changes

    - agent: po
      action: validate_artifacts

    - agent: po
      action: shard_documents

    - agent: sm
      action: create_epic
      creates: epic.md
      notes: "Uses brownfield-create-epic task"

    - agent: sm
      action: create_story
      creates: story.md
      notes: "Uses create-brownfield-story task"
      repeats: for_each_epic

    - agent: dev
      action: implement_story

    - agent: qa
      action: review_implementation
      optional: true

  artifacts:
    - flattened-codebase.xml
    - brownfield-prd.md
    - brownfield-architecture.md
    - docs/epics/*.md
    - docs/stories/*.md

workflow:
  id: brownfield-service
  type: brownfield
  project_types: [existing-api, existing-microservice, legacy-backend, api-enhancement]

  sequence:
    - step: document_existing_project
      action: flatten_codebase
      creates: flattened-codebase.xml

    - agent: pm
      creates: brownfield-prd.md

    - agent: architect
      creates: brownfield-architecture.md
      notes: "Documents service changes and integration points"

    - agent: pm
      updates: brownfield-prd.md
      condition: architecture_suggests_prd_changes

    - agent: po
      action: validate_artifacts

    - agent: po
      action: shard_documents

    - agent: sm
      action: create_epic

    - agent: sm
      action: create_story
      repeats: for_each_epic

    - agent: dev
      action: implement_story

    - agent: qa
      action: review_implementation
      optional: true

  artifacts:
    - flattened-codebase.xml
    - brownfield-prd.md
    - brownfield-architecture.md
    - docs/epics/*.md
    - docs/stories/*.md

workflow:
  id: brownfield-ui
  type: brownfield
  project_types: [existing-frontend, existing-spa, ui-redesign, component-refactor]

  sequence:
    - step: document_existing_project
      action: flatten_codebase

    - agent: pm
      creates: brownfield-prd.md

    - agent: ux-expert
      creates: front-end-spec.md
      notes: "Documents UI changes and component updates"

    - agent: architect
      creates: brownfield-architecture.md
      notes: "Documents frontend architecture changes"

    - agent: pm
      updates: brownfield-prd.md
      condition: architecture_suggests_prd_changes

    - agent: po
      action: validate_artifacts

    - agent: po
      action: shard_documents

    - agent: sm
      action: create_epic

    - agent: sm
      action: create_story
      repeats: for_each_epic

    - agent: dev
      action: implement_story

    - agent: qa
      action: review_implementation
      optional: true

  artifacts:
    - flattened-codebase.xml
    - brownfield-prd.md
    - front-end-spec.md
    - brownfield-architecture.md
    - docs/epics/*.md
    - docs/stories/*.md

# Load bmad-orchestrator
*help

# Get guidance on workflow selection
*workflow-guidance

# Start specific workflow
*workflow greenfield-fullstack

# Create detailed plan before starting
*plan

# Step 1: Load Orchestrator in web platform
# Platform: ChatGPT, Claude, or Gemini
# Load: web-bundles/teams/team-fullstack.txt

# Step 2: Get workflow guidance
*workflow-guidance
# Orchestrator asks:
#   "Is this a new project or existing project?"
#   User: "New project"
#   "What type of application?"
#   User: "Full-stack web application"
#   Orchestrator: "Recommended: greenfield-fullstack workflow"

# Step 3: Create plan
*plan
# Orchestrator creates detailed plan:
#   Phase 1: Planning (Web UI)
#     Step 1: Analyst creates project-brief.md
#     Step 2: PM creates prd.md
#     Step 3: UX Expert creates front-end-spec.md
#     Step 4: Architect creates fullstack-architecture.md
#     Step 5: PO validates and shards documents
#   Phase 2: Development (IDE)
#     Step 6: SM creates story files
#     Step 7: Dev implements stories
#     Step 8: QA reviews and gates
#   Estimated artifacts: 15+ files
#   Estimated timeline: 2-3 weeks

# Step 4: Start workflow
*workflow greenfield-fullstack
# Orchestrator begins execution:

# Step 4a: Transform to Analyst
*agent analyst
# Orchestrator: "I'm now operating as Mary, your Business Analyst"
# Analyst: "Let's create your project brief"
*create-project-brief
# ... interactive elicitation ...
# Output: docs/project-brief.md

# Step 4b: Transform to PM
*agent pm
# Orchestrator: "I'm now operating as your Product Manager"
# PM: "Based on the project brief, let's create the PRD"
*create-prd
# ... interactive PRD creation ...
# Output: docs/prd.md

# Step 4c: Transform to UX Expert
*agent ux-expert
# UX Expert: "Let's design the user interface"
*create-frontend-spec
# ... UI specification creation ...
# Output: docs/front-end-spec.md

# Step 4d: Transform to Architect
*agent architect
# Architect: "Now let's design the technical architecture"
*create-architecture
# ... architecture creation ...
# Output: docs/fullstack-architecture.md

# Step 4e: Transform to PO
*agent po
# PO: "Let me validate and prepare documents for development"
*shard-doc
# Shards PRD: docs/prd/ (epic-1.md, epic-2.md, ...)
# Shards Architecture: docs/architecture/ (tech-stack.md, ...)
# Output: Sharded document directories

# Step 5: Move to IDE for development
# Platform: Cursor, Claude Code, or Windsurf
# Load: .bmad-core/agent-teams/team-ide-minimal.yaml

# Step 5a: Load SM agent
*agent sm
# SM: "Let's create the first story"
*draft
# SM creates: docs/stories/1.1.user-authentication.md
# Story contains complete context from sharded docs

# Step 5b: Load Dev agent
*agent dev
# Dev: "I'll implement this story"
*develop-story
# Dev implements all tasks sequentially
# Updates story file with progress

# Step 5c: Load QA agent
*agent qa
# QA: "Let me review the implementation"
*review
*gate
# QA makes gate decision
# If PASS: Story complete
# If FAIL/CONCERNS: Dev addresses feedback

# Step 6: Repeat for remaining stories
# SM creates next story: *draft
# Dev implements: *develop-story
# QA reviews: *review

# Scenario: Missing prerequisite artifact

# Attempt to start workflow
*workflow greenfield-fullstack

# Orchestrator checks prerequisites:
# ✓ project-brief.md exists
# ✗ prd.md not found

# Orchestrator halts and reports:
# "Error: Required artifact not found"
# "Expected: docs/prd.md"
# "Solution: Run PM agent *create-prd command first"
# "Workflow paused at step 2"

# User creates PRD
*agent pm
*create-prd
# ... creates prd.md ...

# Resume workflow
*workflow greenfield-fullstack
# Orchestrator detects prd.md exists
# Continues from step 3 (UX Expert)

# Scenario: Optional v0 UI generation

# Workflow reaches UX Expert step
*agent ux-expert
*create-frontend-spec
# Output: docs/front-end-spec.md

# Workflow checks condition: user_wants_ai_generation
# Orchestrator asks: "Would you like to generate UI with v0/Lovable?"
# User: "Yes"

# Conditional step executes:
*generate-ui-prompt
# UX Expert generates v0 prompt
# Output: v0-generation-prompt.txt

# If user had said "No", step would be skipped
# Workflow continues to Architect step

interface WorkflowPhases {
  // Phase 1: Planning (Web UI)
  planning: {
    platform: 'Web-based AI platforms (ChatGPT, Claude, Gemini)';
    agents: ['Analyst', 'PM', 'UX Expert', 'Architect'];
    output: 'PRD, Architecture, Frontend Spec';
  };

  // Phase 2: Validation (Web UI or IDE)
  validation: {
    agent: 'PO';
    actions: ['Validate artifacts', 'Shard documents'];
    output: 'Sharded docs in docs/prd/ and docs/architecture/';
  };

  // Phase 3: Development (IDE)
  development: {
    platform: 'Desktop IDEs (Cursor, Claude Code, Windsurf)';
    sequence: ['SM creates stories', 'Dev implements', 'QA reviews'];
    output: 'Implemented features, updated codebase';
  };
}

interface ConditionalSteps {
  // Execute only if condition true
  conditions: {
    user_wants_ai_generation: 'User explicitly requests v0/Lovable';
    architecture_suggests_prd_changes: 'Architect identifies PRD inconsistencies';
    ui_changes_needed: 'Brownfield workflow includes UI modifications';
    qa_left_unchecked_items: 'QA gate decision is FAIL or CONCERNS';
  };

  behavior: 'If condition false, step skipped, workflow continues';
}

# Iterative execution
repeats: for_each_epic   # Repeat for all epics in PRD

.bmad-core/workflows/
├── greenfield-fullstack.yaml
├── greenfield-service.yaml
├── greenfield-ui.yaml
├── brownfield-fullstack.yaml
├── brownfield-service.yaml
└── brownfield-ui.yaml

interface WorkflowSelection {
  greenfield: {
    when: ['Starting from scratch', 'No existing codebase', 'Need comprehensive planning', 'Building MVP or new product'];
  };

  brownfield: {
    when: ['Existing codebase', 'Adding features to legacy', 'Maintaining established patterns', 'Working with existing architecture'];
  };
}

interface ProjectTypeSelection {
  fullStack: {
    when: ['Complete applications', 'Frontend and backend together', 'Integrated UX', 'Monorepo or tightly coupled'];
  };

  service: {
    when: ['Backend/API only', 'Microservices', 'No user interface', 'Data pipelines'];
  };

  ui: {
    when: ['Frontend only', 'SPAs or mobile apps', 'Backend provided separately', 'UI component libraries'];
  };
}

interface WorkflowBestPractices {
  documentSaving: {
    location: 'Save artifacts to docs/ directory';
    structure: {
      planning: ['docs/project-brief.md', 'docs/prd.md', 'docs/architecture.md'];
      sharded: ['docs/prd/', 'docs/architecture/'];
      stories: 'docs/stories/';
    };
  };

  agentContext: {
    principle: 'Each agent builds on previous work';
    contextPreservation: 'Through documents, not re-explanation';
    storyContext: 'Stories contain complete implementation context';
  };

  transitions: {
    planningToValidation: 'Ensure all docs saved to docs/';
    validationToDevelopment: 'Use sharded documents';
    developmentToQA: 'Story file contains all context';
    qaToDevelopment: 'QA feedback in story file';
  };

  storyDriven: {
    principle: 'Development phase entirely story-driven';
    contextInStories: 'Stories contain ALL implementation context';
    noRereading: 'Developers never re-read PRD or architecture';
    sequential: 'Sequential task execution';
    clearDoD: 'Clear Definition of Done';
    embeddedTesting: 'Testing requirements embedded';
  };
}

interface MissingArtifactHandling {
  // Required artifact not found
  behavior: 'Workflow halts at step requiring missing artifact';
  errorMessage: 'Clear indication of which artifact is missing and where it should be';
  recovery: 'User must create missing artifact or adjust workflow';
  
  examples: {
    pmStep: {
      scenario: 'PM step requires project-brief.md';
      error: 'Analyst must run *create-project-brief first';
      solution: '*agent analyst → *create-project-brief';
    };
    architectStep: {
      scenario: 'Architect step requires prd.md';
      error: 'PM must run *create-prd first';
      solution: '*agent pm → *create-prd';
    };
    smStep: {
      scenario: 'SM step requires sharded docs';
      error: 'PO must run *shard-doc first';
      solution: '*agent po → *shard-doc';
    };
  };
}

interface ConditionalStepEvaluation {
  // Steps with condition: property
  evaluation: 'Agent evaluates condition before executing step';
  conditions: {
    user_wants_ai_generation: {
      check: 'User explicitly requests v0/Lovable UI generation';
      example: 'Orchestrator asks: "Generate UI with v0?" User: "Yes"';
      result: 'Step executes, generates v0 prompt';
    };
    architecture_suggests_prd_changes: {
      check: 'Architect identifies PRD inconsistencies';
      example: 'Architect finds tech stack mismatch in PRD';
      result: 'PM step executes to update PRD';
    };
    ui_changes_needed: {
      check: 'Brownfield workflow includes UI modifications';
      example: 'Enhancement requires frontend changes';
      result: 'UX Expert step executes';
    };
    qa_left_unchecked_items: {
      check: 'QA gate decision is FAIL or CONCERNS';
      example: 'QA finds critical issues';
      result: 'Dev step executes to address feedback';
    };
  };
  
  // If condition false, step is skipped
  skipBehavior: 'Step marked as skipped, workflow continues to next step';
  optionalSteps: 'Steps marked optional: true can be skipped without error';
}

interface WorkflowInterruption {
  // User interrupts workflow mid-execution
  interruptionPoints: [
    'Between agent handoffs (safe)',
    'Between workflow steps (safe)',
    'During step execution (not recommended)'
  ];
  
  recovery: {
    state: 'Workflow state not automatically saved';
    resume: 'User must manually resume from last completed step';
    artifacts: 'Completed artifacts remain, can be reused';
    recommendation: 'Complete current step before interrupting';
  };
  
  example: {
    scenario: 'User interrupts during PRD creation';
    completed: 'project-brief.md created';
    inProgress: 'PRD creation (step 2 of 5)';
    recovery: 'Resume with *agent pm → *create-prd';
    note: 'project-brief.md already exists, PM can use it';
  };
}

interface WorkflowValidation {
  // Before starting workflow
  preFlightChecks: {
    requiredFiles: 'Verify core-config.yaml exists';
    directoryStructure: 'Verify .bmad-core/ directory structure';
    agentFiles: 'Verify required agent files exist';
    templateFiles: 'Verify required template files exist';
  };
  
  // During workflow execution
  stepValidation: {
    prerequisites: 'Verify required artifacts exist before each step';
    agentAvailability: 'Verify required agent can be loaded';
    taskAvailability: 'Verify required tasks exist';
  };
  
  // Error reporting
  validationFailures: {
    format: 'Clear error message + missing requirement + remediation steps';
    example: 'Workflow cannot start: PRD template not found. Expected: .bmad-core/templates/prd-tmpl.yaml. Solution: Run npx bmad-method install';
  };
}