Edge Cases and Advanced Scenarios

interface FullStackStoryContext {
  // create-next-story task detects full-stack story
  detection: 'Story description contains both API and UI keywords';
  
  // Loads all relevant architecture sections
  architectureSections: {
    backend: ['data-models', 'rest-api-spec', 'backend-architecture'];
    frontend: ['components', 'core-workflows', 'frontend-architecture'];
    common: ['tech-stack', 'coding-standards', 'testing-strategy'];
  };
  
  // Story structure includes both contexts
  storyContext: {
    backendTasks: 'API endpoint creation, file storage, validation';
    frontendTasks: 'Upload component, progress indicator, error handling';
    integration: 'API integration, error handling, loading states';
  };
}

*agent sm
*draft
# SM agent:
#   - Detects: Full-stack story (keywords: "upload", "API", "UI")
#   - Loads: All architecture sections (backend + frontend + common)
#   - Creates story with:
#     * Backend tasks: API endpoint, file storage, validation
#     * Frontend tasks: Upload component, progress, error handling
#     * Integration: API calls, error handling
# Output: docs/stories/2.3.profile-picture-upload.md

interface MissingSectionError {
  error: 'Required architecture section not found';
  expected: 'docs/architecture/tech-stack.md';
  impact: 'Story creation cannot proceed';
  
  resolution: {
    step1: 'Check if architecture document exists';
    step2: 'Check if architecture is sharded';
    step3: 'If not sharded: Run *shard-doc';
    step4: 'If sharded but missing: Create missing section';
    step5: 'Retry story creation';
  };
}

# Error occurs during story creation
*agent sm
*draft
# Error: "Required architecture section not found"
# Expected: docs/architecture/tech-stack.md

# Solution 1: Shard architecture if not already done
*agent po
*shard-doc
# Shards architecture document
# Creates docs/architecture/tech-stack.md

# Solution 2: If section still missing, create it
*agent architect
*create-architecture
# Updates architecture with missing section
# Or creates tech-stack.md directly

# Retry story creation
*agent sm
*draft
# Now succeeds with all required sections

interface EpicPatternMismatch {
  config: {
    pattern: 'epic-{n}*.md';
    example: 'epic-1.md, epic-2.md';
  };
  
  actual: {
    files: ['epic1.md', 'epic2.md'];
    issue: 'Missing dash in filename';
  };
  
  resolution: {
    option1: 'Rename files to match pattern';
    option2: 'Update pattern in core-config.yaml';
  };
}

# Error when creating story
*agent sm
*draft
# Error: "Epic file pattern doesn't match: epic1.md"
# Pattern: epic-{n}*.md

# Solution 1: Rename files
mv docs/prd/epic1.md docs/prd/epic-1.md
mv docs/prd/epic2.md docs/prd/epic-2.md

# Solution 2: Update pattern in core-config.yaml
# Change: epicFilePattern: epic-{n}*.md
# To: epicFilePattern: epic{n}*.md

# Retry story creation
*agent sm
*draft
# Now succeeds with matching pattern

interface LargeDocumentSharding {
  document: {
    size: '5000 lines';
    sections: '25 level-2 sections';
  };
  
  automatic: {
    prerequisite: 'markdownExploder: true in core-config.yaml';
    tool: '@kayvan/markdown-tree-parser';
    command: 'md-tree explode docs/prd.md docs/prd';
    time: '2 seconds';
    output: '25 shard files (~200 lines each)';
  };
  
  manual: {
    time: '30 seconds';
    process: 'PO agent reads entire document, identifies sections, creates files';
  };
}

# Automatic sharding (recommended)
*agent po
*shard-doc
# Uses md-tree explode if markdownExploder: true
# Command: md-tree explode docs/prd.md docs/prd
# Creates: 25 shard files in 2 seconds
# Output: docs/prd/ with epic-1.md, epic-2.md, etc.

# Manual sharding (fallback)
# If markdownExploder: false
*agent po
*shard-doc
# PO agent:
#   1. Reads entire 5000-line document
#   2. Identifies 25 level-2 sections
#   3. Creates individual files
#   4. Generates index.md with links
# Time: 30 seconds

interface ConcurrentStoryDevelopment {
  epic: {
    stories: ['1.1', '1.2', '1.3'];
    dependencies: {
      '1.2': 'Requires 1.1 completion';
      '1.3': 'Independent of 1.1 and 1.2';
    };
  };
  
  strategy: {
    parallel: ['1.1 and 1.3 can be developed simultaneously'];
    sequential: ['1.2 must wait for 1.1'];
    context: 'Each story contains complete context, no conflicts';
  };
}

# Developer A: Story 1.1
*agent sm
*draft
# Creates 1.1.user-authentication.md
# Status: InProgress

*agent dev
*develop-story
# Implements 1.1

# Developer B: Story 1.3 (independent)
*agent sm
*draft
# Creates 1.3.password-reset.md
# SM agent:
#   - Detects 1.1 in progress (not blocking)
#   - Detects 1.3 is independent
#   - Creates story with context
# Status: InProgress

*agent dev
*develop-story
# Implements 1.3 in parallel with 1.1

# Developer C: Story 1.2 (depends on 1.1)
*agent sm
*draft
# SM agent:
#   - Detects 1.1 not complete (blocking)
#   - Waits or suggests working on 1.3 instead
#   - When 1.1 complete, creates 1.2 with learnings

interface VersionMismatch {
  detection: {
    prdVersion: 'v3 (from prd.md metadata)';
    architectureVersion: 'v4 (from architecture.md metadata)';
    issue: 'Incompatible versions';
  };
  
  resolution: {
    step1: 'Upgrade PRD to v4';
    step2: 'Or downgrade architecture to v3';
    step3: 'Or use migration tools';
  };
  
  migration: {
    command: 'npx bmad-method upgrade';
    from: 'v3';
    to: 'v4';
    process: 'Automated conversion with validation';
  };
}

# Detect version mismatch
*agent sm
*draft
# Warning: "PRD version (v3) differs from architecture version (v4)"
# Suggestion: Upgrade PRD to v4

# Solution: Upgrade PRD
npx bmad-method upgrade
# Converts PRD from v3 to v4
# Validates compatibility
# Updates metadata

# Retry story creation
*agent sm
*draft
# Now succeeds with compatible versions

interface ExpansionPackOverride {
  core: {
    slashPrefix: '*';
    agents: ['pm', 'dev', 'qa'];
  };
  
  expansion: {
    slashPrefix: 'BmadG';
    agents: ['game-designer', 'level-designer'];
    config: '.bmad-godot-game-dev/expansion-config.yaml';
  };
  
  precedence: 'Expansion pack config > Core config';
  
  usage: {
    coreAgents: 'Use * prefix (e.g., *create-prd)';
    expansionAgents: 'Use BmadG prefix (e.g., BmadG create-level)';
  };
}

# Core agents use * prefix
*agent pm
*create-prd

# Expansion pack agents use BmadG prefix
BmadG agent game-designer
BmadG create-level-design

# Both work simultaneously
# No conflicts, clear separation

interface StoryStatusTransition {
  validTransitions: {
    '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';
  };
}

# Story creation
*agent sm
*draft
# Creates story with status: Draft

# Approval
*agent po
*validate-story-draft
# Validates story, changes status to Approved

# Start development
*agent dev
*develop-story
# Changes status to InProgress
# Implements all tasks

# Review
*agent qa
*review
# Changes status to Review
# Makes gate decision

# Completion
*agent qa
*gate
# Gate Decision: PASS
# Changes status to Done

interface MultiPlatformWorkflow {
  planning: {
    platform: 'Web (ChatGPT, Claude, Gemini)';
    output: 'docs/prd.md, docs/architecture.md';
    sharding: 'docs/prd/, docs/architecture/';
  };
  
  development: {
    platform: 'IDE (Cursor, Claude Code, Windsurf)';
    input: 'Sharded documents from planning';
    process: 'Stories created with context from sharded docs';
  };
  
  handoff: {
    mechanism: 'File system (shared directory)';
    validation: 'SM agent verifies sharded docs exist';
    context: 'Stories contain all needed context, no re-reading';
  };
}

# Phase 1: Web Platform
# Load team-fullstack in ChatGPT
*agent pm
*create-prd
# Output: docs/prd.md

*agent po
*shard-doc
# Output: docs/prd/ directory

# Phase 2: IDE
# Load team-ide-minimal in Cursor
*agent sm
*draft
# SM agent:
#   - Verifies docs/prd/ exists
#   - Loads appropriate epic files
#   - Creates story with complete context
# No need to access web platform or re-read PRD

interface TemplateVariableResolution {
  template: {
    variable: '{{project_name}}';
    source: 'User input or config';
  };
  
  resolution: {
    step1: 'Check user input (elicitation)';
    step2: 'Check core-config.yaml';
    step3: 'Check previous documents';
    step4: 'Prompt user if not found';
  };
  
  error: {
    condition: 'Variable not found and cannot be inferred';
    message: 'Required variable {{variable_name}} not found';
    solution: 'Provide value or update config';
  };
}

# Template generation
*agent pm
*create-prd
# Template requires: {{project_name}}

# Resolution:
# 1. Check elicitation response
# 2. Check core-config.yaml
# 3. Check project-brief.md
# 4. If not found: Prompt user

# Error handling
# Error: "Required variable project_name not found"
# Solution: Provide value during elicitation