Configuration System

// Configuration file location
configLocation: '{projectRoot}/.bmad-core/core-config.yaml';

// Created during BMad installation
// Customizable per project
// Read by all agents and tasks

# Document Processing
markdownExploder: boolean              # Use markdown-tree-parser

# QA Configuration
qa:
  qaLocation: string                   # QA artifacts directory

# PRD Configuration
prd:
  prdFile: string                      # PRD file path
  prdVersion: string                   # v4 or v3
  prdSharded: boolean                  # Enable sharding
  prdShardedLocation: string           # Sharded directory
  epicFilePattern: string              # Epic file naming (e.g., epic-{n}*.md)

# Architecture Configuration
architecture:
  architectureFile: string             # Architecture file path
  architectureVersion: string          # v4 or v3
  architectureSharded: boolean         # Enable sharding
  architectureShardedLocation: string  # Sharded directory

# Additional Documents
customTechnicalDocuments: string | null  # Comma-separated paths

# Dev Agent Configuration
devLoadAlwaysFiles: string[]           # Files dev always loads
devDebugLog: string                    # Debug log path
devStoryLocation: string               # Story directory

# QA Agent Configuration (optional)
qaLoadAlwaysFiles: string[]            # Files QA always loads

# Command Configuration
slashPrefix: string                    # Command prefix (default: "BMad")

markdownExploder: true
qa:
  qaLocation: docs/qa
prd:
  prdFile: docs/prd.md
  prdVersion: v4
  prdSharded: true
  prdShardedLocation: docs/prd
  epicFilePattern: epic-{n}*.md
architecture:
  architectureFile: docs/architecture.md
  architectureVersion: v4
  architectureSharded: true
  architectureShardedLocation: docs/architecture
customTechnicalDocuments: null
devLoadAlwaysFiles:
  - docs/architecture/coding-standards.md
  - docs/architecture/tech-stack.md
  - docs/architecture/source-tree.md
devDebugLog: .ai/debug-log.md
devStoryLocation: docs/stories
slashPrefix: BMad

interface ShardingConfig {
  markdownExploder: {
    true: 'Use @kayvan/markdown-tree-parser (recommended)';
    false: 'Use manual sharding';
  };

  prdSharded / architectureSharded: {
    true: 'Tasks read from sharded directory';
    false: 'Tasks read from monolithic file';
  };
}

interface ContextLoadingStrategy {
  // Architecture sections loaded by story type
  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'];
}

interface FilePatterns {
  epicFilePattern: {
    format: 'Pattern with {n} placeholder';
    example: 'epic-{n}*.md';
    matches: ['epic-1.md', 'epic-1-authentication.md', 'epic-2-api.md'];
  };
}

interface AgentConfigUsage {
  loadTiming: 'On agent activation or task execution';
  
  behavior: {
    documentLocation: 'Where to find PRD/architecture';
    shardingStrategy: 'Monolithic vs sharded reading';
    storyLocation: 'Where to create/read stories';
    alwaysLoadFiles: 'Files to preload';
  };

  example: {
    1: 'SM agent loads core-config.yaml';
    2: 'Checks prdSharded setting';
    3: 'Reads from prdShardedLocation if true';
    4: 'Checks architectureSharded';
    5: 'Loads architecture sections selectively';
    6: 'Creates story in devStoryLocation';
  };
}

interface TaskConfigUsage {
  createNextStory: {
    reads: ['prdSharded', 'prdShardedLocation', 'architectureSharded', 'architectureShardedLocation', 'devStoryLocation', 'devLoadAlwaysFiles'];
  };
  
  shardDoc: {
    reads: ['markdownExploder'];
  };
  
  qaGate: {
    reads: ['qa.qaLocation'];
  };
}

prd:
  prdFile: documentation/requirements.md
  prdSharded: true
  prdShardedLocation: documentation/requirements
architecture:
  architectureFile: documentation/architecture.md
  architectureSharded: true
  architectureShardedLocation: documentation/architecture
devStoryLocation: development/stories

prd:
  prdSharded: false
architecture:
  architectureSharded: false

devLoadAlwaysFiles:
  - docs/architecture/coding-standards.md
  - docs/architecture/tech-stack.md
  - docs/architecture/source-tree.md
  - docs/architecture/testing-strategy.md     # Added
  - docs/security-requirements.md             # Added
  - docs/api-conventions.md                   # Added

# Minimum required
markdownExploder: boolean
qa.qaLocation: string
prd.prdFile: string
prd.prdVersion: string
prd.prdSharded: boolean
prd.prdShardedLocation: string
prd.epicFilePattern: string
architecture.architectureFile: string
architecture.architectureVersion: string
architecture.architectureSharded: boolean
architecture.architectureShardedLocation: string
devStoryLocation: string
slashPrefix: string

interface ConfigValidation {
  fileChecks: [
    'prdFile exists (if prdSharded: false)',
    'architectureFile exists (if architectureSharded: false)',
    'prdShardedLocation exists (if prdSharded: true)',
    'architectureShardedLocation exists (if architectureSharded: true)'
  ];

  valueChecks: [
    'prdVersion valid (v3, v4)',
    'architectureVersion valid (v3, v4)',
    'epicFilePattern contains {n}',
    'devStoryLocation valid path'
  ];

  onError: 'Task halts and reports missing/invalid configuration';
}

interface ConfigBestPractices {
  documentOrganization: {
    structure: {
      monolithic: 'docs/prd.md, docs/architecture.md';
      sharded: 'docs/prd/, docs/architecture/';
      stories: 'docs/stories/';
      qa: 'docs/qa/';
    };
  };

  shardingStrategy: {
    enable: 'For documents > 500 lines';
    disable: 'For documents < 500 lines';
  };

  alwaysLoadFiles: {
    keep: 'Short list (< 6 files)';
    include: 'Small, frequently referenced files';
    avoid: 'Large files (> 500 lines)';
  };

  versionConsistency: {
    recommended: 'Both PRD and architecture at same version';
    current: 'v4 for both';
  };
}

interface CommonIssues {
  'core-config.yaml not found': {
    solution: 'Run npx bmad-method install or create manually';
  };

  'PRD sharded but directory not found': {
    solution: 'Set prdSharded: false or run PO agent *shard-doc';
  };

  'Architecture sections not loading': {
    solution: 'Verify architectureSharded: true and directory exists';
  };

  'Story creation fails': {
    solution: 'Verify devStoryLocation exists and is writable';
  };

  'epicFilePattern doesn\'t match files': {
    solution: 'Update pattern to match actual naming, or rename files';
  };

  'devLoadAlwaysFiles contains non-existent files': {
    solution: 'Verify all paths exist, agent halts on missing files';
  };
}

# .bmad-core/core-config.yaml
markdownExploder: true
qa:
  qaLocation: docs/qa
prd:
  prdFile: docs/prd.md
  prdVersion: v4
  prdSharded: true
  prdShardedLocation: docs/prd
  epicFilePattern: epic-{n}*.md
architecture:
  architectureFile: docs/architecture.md
  architectureVersion: v4
  architectureSharded: true
  architectureShardedLocation: docs/architecture
customTechnicalDocuments: null
devLoadAlwaysFiles:
  - docs/architecture/coding-standards.md
  - docs/architecture/tech-stack.md
  - docs/architecture/source-tree.md
devDebugLog: .ai/debug-log.md
devStoryLocation: docs/stories
slashPrefix: BMad

# Project with different document organization
markdownExploder: true
qa:
  qaLocation: documentation/quality-assurance
prd:
  prdFile: documentation/requirements.md
  prdVersion: v4
  prdSharded: true
  prdShardedLocation: documentation/requirements
  epicFilePattern: epic-{n}*.md
architecture:
  architectureFile: documentation/system-design.md
  architectureVersion: v4
  architectureSharded: true
  architectureShardedLocation: documentation/system-design
customTechnicalDocuments: "documentation/api-specs.md,documentation/deployment-guide.md"
devLoadAlwaysFiles:
  - documentation/system-design/coding-standards.md
  - documentation/system-design/tech-stack.md
devDebugLog: logs/dev-debug.md
devStoryLocation: development/user-stories
slashPrefix: BMad

# Small project with simple documents
markdownExploder: false
qa:
  qaLocation: docs/qa
prd:
  prdFile: docs/prd.md
  prdVersion: v4
  prdSharded: false  # Use monolithic file
  prdShardedLocation: docs/prd
  epicFilePattern: epic-{n}*.md
architecture:
  architectureFile: docs/architecture.md
  architectureVersion: v4
  architectureSharded: false  # Use monolithic file
  architectureShardedLocation: docs/architecture
customTechnicalDocuments: null
devLoadAlwaysFiles:
  - docs/architecture/coding-standards.md
devDebugLog: .ai/debug-log.md
devStoryLocation: docs/stories
slashPrefix: BMad

# Scenario 1: Invalid PRD version
# core-config.yaml:
prd:
  prdVersion: v5  # Invalid (only v3, v4 supported)

# Error when task executes:
# "Invalid PRD version: v5. Valid versions: v3, v4"
# Task halts, user must fix configuration

# Scenario 2: Sharded directory missing
# core-config.yaml:
prd:
  prdSharded: true
  prdShardedLocation: docs/prd

# Directory docs/prd/ doesn't exist
# Error when task executes:
# "PRD sharded directory not found: docs/prd"
# "Solution: Set prdSharded: false or run PO agent *shard-doc"
# Task halts, user must create directory or shard document

# Scenario 3: Missing always-load file
# core-config.yaml:
devLoadAlwaysFiles:
  - docs/architecture/coding-standards.md
  - docs/architecture/non-existent.md  # File doesn't exist

# Error when Dev agent loads:
# "Required file not found: docs/architecture/non-existent.md"
# "Expected location: docs/architecture/non-existent.md"
# "Solution: Create file or remove from devLoadAlwaysFiles"
# Agent halts, user must fix configuration

# Scenario 4: Epic file pattern mismatch
# core-config.yaml:
prd:
  epicFilePattern: epic-{n}*.md

# Actual files:
# docs/prd/epic1.md  # Doesn't match (missing dash)
# docs/prd/epic-2.md  # Matches

# Error when task executes:
# "Epic file pattern doesn't match: epic1.md"
# "Pattern: epic-{n}*.md"
# "Solution: Rename file to epic-1.md or update pattern to epic{n}*.md"

# Migrating from v3 to v4 configuration

# Old v3 config:
prd:
  prdVersion: v3
architecture:
  architectureVersion: v3

# New v4 config:
prd:
  prdVersion: v4
  prdSharded: true  # New in v4
  prdShardedLocation: docs/prd  # New in v4
  epicFilePattern: epic-{n}*.md  # New in v4
architecture:
  architectureVersion: v4
  architectureSharded: true  # New in v4
  architectureShardedLocation: docs/architecture  # New in v4

# Migration steps:
# 1. Update version numbers to v4
# 2. Add sharding settings
# 3. Add epicFilePattern
# 4. Run PO agent to shard documents
# 5. Verify sharded directories created