API Patterns Reference

interface AgentCommand {
  prefix: '*';  // All commands use asterisk prefix
  format: '*<command> [arguments]';
  examples: ['*help', '*create-prd', '*develop-story', '*agent pm'];
}

interface DependencyResolution {
  pattern: '{root}/{type}/{name}';

  types: {
    tasks: '.bmad-core/tasks/{task-name}.md';
    templates: '.bmad-core/templates/{template-id}.yaml';
    checklists: '.bmad-core/checklists/{checklist-name}.md';
    data: '.bmad-core/data/{data-file}.md';
  };

  loadingStrategy: 'On-demand when agent executes command';

  resolution: {
    1: 'Check expansion pack directory first';
    2: 'Fall back to core directory if not found';
    3: 'Report error if neither found';
  };
}

interface AgentActivation {
  steps: {
    1: 'Agent reads complete definition file';
    2: 'Adopts persona from agent configuration';
    3: 'Loads .bmad-core/core-config.yaml';
    4: 'Greets user with name/role + auto-run *help';
    5: 'Stays in character throughout';
  };

  commandPattern: {
    prefix: '*';
    examples: ['*help', '*create-prd', '*develop-story'];
  };
}

interface StoryStructure {
  header: {
    epicStory: 'Epic {{epic_num}}.{{story_num}}';
    title: '{{story_title}}';
    status: 'Draft | Approved | InProgress | Review | Done';
    created: 'ISO date';
  };

  story: {
    format: 'As a {{role}}, I want {{action}}, so that {{benefit}}';
  };

  acceptanceCriteria: {
    format: 'Numbered list from epic';
  };

  tasks: {
    format: 'Checkbox list with subtasks';
    structure: '[ ] Task description\n  [ ] Subtask 1\n  [ ] Subtask 2';
  };

  devNotes: {
    content: 'Complete technical context with source references';
    includes: ['Architecture context', 'Tech stack', 'Coding standards', 'Previous story learnings'];
    sources: 'Referenced with [Source: file.md#section]';
  };

  devAgentRecord: {
    owner: 'Dev agent only';
    sections: ['Agent Model Used', 'Debug Log References', 'Completion Notes', 'File List', 'Change Log'];
  };

  qaReview: {
    content: 'QA gate decision and feedback';
    gateDecisions: ['PASS', 'CONCERNS', 'FAIL', 'WAIVED'];
  };
}

interface QualityGate {
  decisions: {
    PASS: 'All quality criteria met, ready for production';
    CONCERNS: 'Issues found but not blocking';
    FAIL: 'Critical issues, must address before proceeding';
    WAIVED: 'Issues identified but waived by stakeholder';
  };

  workflow: {
    1: 'Dev implements story';
    2: 'QA reviews implementation';
    3: 'QA makes gate decision';
    4: 'If FAIL/CONCERNS: Dev addresses feedback';
    5: 'Repeat until PASS';
  };
}

interface TemplateMarkup {
  // Variable placeholders
  placeholders: {
    syntax: '{{variable_name}}';
    examples: ['{{project_name}}', '{{epic_num}}', '{{story_title}}'];
    usage: 'Substituted during document generation';
  };

  // AI-only instructions
  llmInstructions: {
    syntax: '[[LLM: instructions]]';
    example: '[[LLM: Generate comprehensive overview]]';
    visibility: 'Invisible to users, processed by AI only';
  };

  // User elicitation
  elicitation: {
    property: 'elicit: true';
    format: 'Mandatory 1-9 options';
    option1: 'Always "Proceed to next section"';
    options2_9: 'From data/elicitation-methods';
    prompt: 'Select 1-9 or type your question/feedback:';
  };
}

interface ShardingPattern {
  // Automatic sharding (recommended)
  automatic: {
    prerequisite: 'markdownExploder: true in core-config.yaml';
    tool: '@kayvan/markdown-tree-parser';
    command: 'md-tree explode {source} {destination}';
  };

  // Output structure
  output: {
    index: 'index.md with navigation links';
    shards: '{section-name}.md: Individual section files';
    sections: 'Split on ## level 2 headings';
  };

  // Manual sharding
  manual: {
    1: 'Read entire document';
    2: 'Identify ## level 2 sections';
    3: 'Extract each section with subsections';
    4: 'Generate filename from heading (lowercase-dash-case)';
    5: 'Adjust heading levels (## → #, ### → ##)';
    6: 'Write content to individual files';
    7: 'Create index.md with links';
  };
}

interface ContextLoadingStrategy {
  // Architecture sections loaded by story type
  allStories: ['tech-stack', 'unified-project-structure', 'coding-standards', 'testing-strategy'];
  backendStories: ['data-models', 'database-schema', 'backend-architecture', 'rest-api-spec'];
  frontendStories: ['frontend-architecture', 'components', 'core-workflows'];

  // Selective loading
  principle: 'Load only what is needed for current story';
  implementation: 'SM agent determines story type and loads appropriate sections';
}

interface StoryCreationPattern {
  // Context gathering
  contextSources: {
    allStories: ['tech-stack', 'project-structure', 'coding-standards', 'testing-strategy'];
    backendStories: ['data-models', 'database-schema', 'backend-architecture', 'rest-api-spec'];
    frontendStories: ['frontend-architecture', 'components', 'core-workflows'];
  };

  // Story structure
  sections: {
    status: 'Draft | Approved | InProgress | Review | Done';
    story: 'As a {role}, I want {action}, so that {benefit}';
    acceptanceCriteria: 'Numbered list from epic';
    tasks: 'Checkboxes with subtasks';
    devNotes: 'Complete technical context with source references';
    devAgentRecord: 'Dev agent updates only';
    qaReview: 'QA gate decision and feedback';
  };

  // Source references
  sourceFormat: '[Source: file.md#section]';
  examples: [
    '[Source: docs/architecture/tech-stack.md#frameworks]',
    '[Source: docs/prd/epic-1.md#story-1.2]',
    '[Source: docs/stories/1.1-login.md#learnings]'
  ];
}

interface WorkflowExecution {
  // Planning Phase
  planning: {
    1: 'Analyst creates project-brief.md';
    2: 'PM creates prd.md with epics and stories';
    3: 'UX Expert creates front-end-spec.md (if UI)';
    4: 'Architect creates architecture.md';
    5: 'PO validates and shards documents';
  };

  // Development Phase
  development: {
    1: 'SM creates story files with complete context';
    2: 'Dev implements stories sequentially';
    3: 'QA reviews and provides feedback';
    4: 'Repeat until all stories completed';
  };

  // Phase transition
  transition: {
    from: 'Planning (Web UI)';
    to: 'Development (IDE)';
    handoff: 'Sharded documents in docs/prd/ and docs/architecture/';
  };
}

interface AgentTransformation {
  // Orchestrator can transform into any agent
  orchestratorCommand: '*agent <agent-id>';

  examples: {
    1: '*agent pm      // Orchestrator → Product Manager';
    2: '*agent dev     // Orchestrator → Developer';
    3: '*exit          // Return to Orchestrator';
  };

  // Context preservation
  contextHandling: {
    documents: 'Preserved through file system';
    conversations: 'Not preserved (use documents)';
    configuration: 'Loaded fresh for each agent';
  };
}

interface SequentialWorkflow {
  greenfieldFullstack: ['Analyst', 'PM', 'UX Expert', 'Architect', 'PO', 'SM', 'Dev', 'QA'];
  greenfieldService: ['Analyst', 'PM', 'Architect', 'PO', 'SM', 'Dev', 'QA'];
  brownfield: ['PM', 'Architect', 'PO', 'SM', 'Dev', 'QA'];

  handoffPattern: {
    pattern: 'Agent creates artifact → hands off to next agent';
    flow: {
      1: 'Analyst → project-brief.md → PM';
      2: 'PM → prd.md → Architect';
      3: 'Architect → architecture.md → PO';
      4: 'PO → sharded docs → SM';
      5: 'SM → story files → Dev';
      6: 'Dev → implementation → QA';
      7: 'QA → validation → Dev (if fixes needed)';
    };
  };
}

interface TaskExecution {
  // Sequential execution
  pattern: 'SEQUENTIAL - Do not proceed until current step complete';

  steps: {
    0: 'Prerequisite checks and validation';
    1: 'Primary execution step';
    2: 'Context gathering';
    3: 'Processing and transformation';
    4: 'Validation and quality checks';
    5: 'Output generation';
    6: 'Completion and reporting';
  };

  // Conditional execution
  conditions: [
    'If file exists: Load and process',
    'If not exists: Create new',
    'If validation fails: Report error and halt',
    'If optional feature enabled: Execute additional steps'
  ];
}

interface ConfigOverridePattern {
  // Expansion pack config can override core settings
  precedence: 'Expansion pack config > Core config';

  scope: {
    expansion: 'Only affects expansion pack agents and tasks';
    core: 'Core agents always use core-config.yaml';
  };

  examples: {
    slashPrefix: {
      core: 'BMad';
      expansion: 'BmadG (from expansion pack config)';
      result: 'Game agents use "BmadG", core agents use "BMad"';
    };
  };
}

interface ErrorHandling {
  criticalErrors: {
    behavior: 'Halt execution immediately';
    examples: [
      'Required file not found',
      'Invalid configuration value',
      'Missing dependency',
      'Permission denied'
    ];
  };

  recoverableErrors: {
    behavior: 'Report error, suggest fix, allow retry';
    examples: [
      'File locked by another process',
      'Network timeout',
      'Temporary file system issue'
    ];
  };

  errorMessages: {
    format: 'Clear description + expected vs actual + remediation steps';
    example: 'PRD file not found. Expected: docs/prd.md. Solution: Create PRD using PM agent *create-prd command';
  };
}

interface VersionManagement {
  semanticVersioning: {
    major: 'Breaking changes, incompatible API changes';
    minor: 'New features, backward compatible';
    patch: 'Bug fixes, critical patches';
  };

  compatibility: {
    prdVersion: 'v4 (current), v3 (legacy support)';
    architectureVersion: 'v4 (current), v3 (legacy support)';
    templateVersion: 'Specified in template metadata';
  };

  migration: {
    from: 'v3';
    to: 'v4';
    command: 'npx bmad-method upgrade';
  };
}

interface FileLocations {
  // Core configuration
  config: '.bmad-core/core-config.yaml';

  // Agents
  agents: '.bmad-core/agents/{agent-id}.md';

  // Tasks
  tasks: '.bmad-core/tasks/{task-name}.md';

  // Templates
  templates: '.bmad-core/templates/{template-id}.yaml';

  // Workflows
  workflows: '.bmad-core/workflows/{workflow-id}.yaml';

  // Agent teams
  teams: '.bmad-core/agent-teams/{team-id}.yaml';

  // Web bundles
  webBundles: {
    agents: 'web-bundles/agents/{agent-id}.txt';
    teams: 'web-bundles/teams/{team-id}.txt';
  };

  // Expansion packs
  expansions: '.{pack-name}/';
}

interface PackageInfo {
  name: 'bmad-method';
  type: 'npm';
  language: 'JavaScript';
  install: 'npx bmad-method install';
  version: '4.44.3';
  nodeVersion: '>=20.10.0';
}

interface InstallationOutput {
  structure: {
    '.bmad-core/': {
      agents: '10 agent personas';
      tasks: '23 reusable tasks';
      templates: '13 document templates';
      workflows: '6 workflow definitions';
      checklists: '6 quality checklists';
      'agent-teams/': '4 team configurations';
      data: 'Knowledge base files';
      'core-config.yaml': 'Project configuration';
    };
    '.{expansion-pack}/': 'Optional expansion packs';
    'docs/': {
      'prd.md': 'Product Requirements';
      'architecture.md': 'Architecture document';
      'stories/': 'Story files for development';
    };
    'web-bundles/': 'Optional web bundles for ChatGPT/Claude/Gemini';
  };
}

interface StoryContext {
  requirements: 'From sharded PRD epic';
  architecture: 'Selective sections (tech-stack, backend-architecture, etc.)';
  previousStories: 'Learnings from completed stories';
  sourceReferences: '[Source: docs/architecture/tech-stack.md#frameworks]';
  tasks: 'Checkbox list with subtasks';
}

interface QualityGateDecision {
  PASS: 'All criteria met, ready for production';
  CONCERNS: 'Issues found but not blocking';
  FAIL: 'Critical issues, must address';
  WAIVED: 'Issues waived by stakeholder';
  
  feedback: {
    format: 'Structured list of issues';
    priority: 'Critical | High | Medium | Low';
    remediation: 'Specific steps to resolve';
  };
}

interface TemplateVariable {
  syntax: '{{variable_name}}';
  resolution: {
    step1: 'Check user input (elicitation)';
    step2: 'Check core-config.yaml';
    step3: 'Check previous documents';
    step4: 'Prompt user if not found';
  };
  examples: ['{{project_name}}', '{{epic_num}}', '{{story_title}}'];
}

interface AgentCommand {
  prefix: '*';
  format: '*<command> [arguments]';
  examples: [
    '*help',
    '*create-prd',
    '*develop-story',
    '*agent pm',
    '*workflow greenfield-fullstack'
  ];
  
  validation: {
    required: 'Command must start with *';
    arguments: 'Optional, space-separated';
    caseSensitive: false;
  };
}

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
}

interface ShardingOutput {
  structure: {
    index: 'index.md with navigation links';
    shards: 'Individual {section-name}.md files';
    sections: 'Split on ## level 2 headings';
  };
  
  automatic: {
    tool: '@kayvan/markdown-tree-parser';
    command: 'md-tree explode {source} {destination}';
    time: '~2 seconds for large documents';
  };
  
  manual: {
    process: 'Agent reads document, identifies sections, creates files';
    time: '~30 seconds for large documents';
  };
}

interface EpicFilePattern {
  pattern: 'epic-{n}*.md';
  examples: ['epic-1.md', 'epic-2.md', 'epic-10.md'];
  
  validation: {
    required: 'Epic number must be present';
    format: 'epic-{number}*.md';
    configurable: 'Can be changed in core-config.yaml';
  };
  
  error: {
    mismatch: 'Epic file pattern doesn\'t match';
    resolution: 'Rename files or update pattern';
  };
}

interface StoryStatus {
  validStatuses: 'Draft' | 'Approved' | 'InProgress' | 'Review' | 'Done' | 'Blocked' | 'Cancelled';
  
  transitions: {
    'Draft': ['Approved', 'Cancelled'];
    'Approved': ['InProgress', 'Cancelled'];
    'InProgress': ['Review', 'Blocked'];
    'Review': ['Done', 'InProgress'];
    'Done': []; // Terminal state
    'Blocked': ['InProgress', 'Cancelled'];
    'Cancelled': []; // Terminal state
  };
  
  validation: {
    'Approved → InProgress': 'Requires SM agent approval';
    'InProgress → Review': 'Requires all tasks complete';
    'Review → Done': 'Requires QA gate PASS';
  };
}

interface ContextLoadingStrategy {
  principle: 'Load only what is needed for current story';
  
  sections: {
    allStories: ['tech-stack', 'unified-project-structure', 'coding-standards', 'testing-strategy'];
    backendStories: ['data-models', 'database-schema', 'backend-architecture', 'rest-api-spec'];
    frontendStories: ['frontend-architecture', 'components', 'core-workflows'];
  };
  
  implementation: 'SM agent determines story type and loads appropriate sections';
  
  sourceFormat: '[Source: file.md#section]';
}