Template System

interface Template {
  template: {
    id: string;
    name: string;
    version: string;
    output: {
      format: 'markdown';
      filename: string;
      title: string;
    };
  };
  workflow?: {
    mode: 'interactive' | 'rapid';
    elicitation?: string;
  };
  agent_config?: {
    editable_sections?: string[];
    owner?: string;
  };
  sections: TemplateSection[];
}

interface TemplateSection {
  id: string;
  title: string;
  type?: string;
  instruction?: string;
  template?: string;
  elicit?: boolean;
  owner?: string;
  editors?: string[];
  subsections?: TemplateSection[];
}

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:';
  };
}

const fs = require('fs');
const path = require('path');
const yaml = require('js-yaml');

/**
 * Load template file
 * @param {string} templateId - Template identifier (e.g., 'prd-tmpl', 'story-tmpl')
 * @param {string} projectRoot - Project root directory (default: process.cwd())
 * @returns {Promise<Template>} - Parsed template object
 */
async function loadTemplate(templateId, projectRoot = process.cwd()) {
  const templatePath = path.join(projectRoot, '.bmad-core', 'templates', `${templateId}.yaml`);
  const content = await fs.promises.readFile(templatePath, 'utf-8');
  return yaml.load(content);
}

/**
 * Process template with variables
 * @param {Template} template - Loaded template
 * @param {Record<string, string>} variables - Variable substitutions
 * @returns {string} - Processed markdown content
 */
function processTemplate(template, variables) {
  let output = `# ${template.template.output.title}\n\n`;

  for (const section of template.sections) {
    output += processSection(section, variables);
  }

  return output;
}

/**
 * Process template section recursively
 * @param {TemplateSection} section - Section to process
 * @param {Record<string, string>} variables - Variable substitutions
 * @returns {string} - Section markdown
 */
function processSection(section, variables) {
  let content = `## ${section.title}\n\n`;

  if (section.template) {
    // Substitute variables in template
    content += section.template.replace(/\{\{(\w+)\}\}/g, (_, key) => variables[key] || '');
  }

  if (section.subsections) {
    for (const subsection of section.subsections) {
      content += processSection(subsection, variables);
    }
  }

  return content + '\n';
}

/**
 * List all available templates
 * @param {string} projectRoot - Project root directory
 * @returns {Promise<string[]>} - Template IDs
 */
async function listTemplates(projectRoot = process.cwd()) {
  const templatesDir = path.join(projectRoot, '.bmad-core', 'templates');
  const files = await fs.promises.readdir(templatesDir);
  return files
    .filter(f => f.endsWith('.yaml'))
    .map(f => f.replace('.yaml', ''));
}

const yaml = require('js-yaml');
const fs = require('fs');
const path = require('path');

async function generateDocument() {
  // Load template
  const templatePath = path.join(process.cwd(), '.bmad-core', 'templates', 'prd-tmpl.yaml');
  const content = await fs.promises.readFile(templatePath, 'utf-8');
  const template = yaml.load(content);

  console.log('Template ID:', template.template.id);
  console.log('Output file:', template.template.output.filename);
  console.log('Sections:', template.sections.length);

  // Process with variables
  const variables = {
    project_name: 'My App',
    version: '1.0.0',
    date: new Date().toISOString().split('T')[0]
  };

  // Generate document structure
  let doc = `# ${template.template.output.title}\n\n`;
  for (const section of template.sections) {
    doc += `## ${section.title}\n\n`;
    if (section.template) {
      // Replace {{variable}} placeholders
      doc += section.template.replace(/\{\{(\w+)\}\}/g, (_, key) => variables[key] || '');
    }
    doc += '\n';
  }

  // Write output
  const outputPath = template.template.output.filename;
  await fs.promises.writeFile(outputPath, doc);
  console.log('Generated:', outputPath);
}

generateDocument().catch(console.error);

async function showAvailableTemplates() {
  const templatesDir = path.join(process.cwd(), '.bmad-core', 'templates');
  const files = await fs.promises.readdir(templatesDir);

  const templates = [];
  for (const file of files.filter(f => f.endsWith('.yaml'))) {
    const content = await fs.promises.readFile(path.join(templatesDir, file), 'utf-8');
    const template = yaml.load(content);
    templates.push({
      id: template.template.id,
      name: template.template.name,
      output: template.template.output.filename
    });
  }

  console.log('Available templates:', templates);
  return templates;
}

template:
  id: project-brief-template
  output:
    filename: docs/project-brief.md
    title: "{{project_name}} - Project Brief"

sections:
  - Executive Summary
  - Problem Statement
  - Goals and Objectives
  - Success Criteria
  - Stakeholders
  - Constraints and Assumptions
  - Timeline and Milestones
  - Budget and Resources

usedBy: 'Analyst (*create-project-brief)';
purpose: 'Initial project overview and strategic direction';

template:
  id: prd-template-v4
  version: "4.0"
  output:
    filename: docs/prd.md
    title: "{{project_name}} - PRD"

key_sections:
  - Document Metadata (Version, Last Updated, Status)
  - Product Overview
  - User Personas
  - Epics (with stories and acceptance criteria)
  - Non-Functional Requirements
  - Dependencies and Integrations
  - Risks and Mitigation
  - Glossary

sections_detail:
  epics:
    structure: 'Epic {{epic_num}}: {{epic_title}}';
    contains: {
      description: 'Epic overview and goals';
      userStories: {
        format: 'Story {{epic_num}}.{{story_num}}: {{story_title}}';
        structure: {
          as: '{{role}}';
          want: '{{action}}';
          benefit: '{{benefit}}';
          acceptanceCriteria: 'Numbered list of criteria';
        };
      };
    };

  nonFunctionalRequirements:
    subsections: ['Performance', 'Security', 'Scalability', 'Reliability', 'Usability'];

usedBy: 'PM (*create-prd)';
purpose: 'Comprehensive product requirements for greenfield projects';

template:
  id: brownfield-prd-template
  version: "4.0"
  output:
    filename: docs/brownfield-prd.md

key_sections:
  - Current State Overview
  - Enhancement Objectives
  - Affected Systems
  - Compatibility Requirements
  - Epics and Stories
  - Technical Constraints
  - Migration Strategy

usedBy: 'PM (brownfield workflows)';
purpose: 'Requirements for enhancing existing systems';

interface MarketResearchTemplate {
  id: 'market-research-template';
  output: 'docs/market-research.md';

  sections: [
    'Market Overview',
    'Target Market Segments',
    'Market Trends',
    'Competitive Landscape',
    'Market Opportunities',
    'Market Risks',
    'Market Size and Growth (TAM, SAM, SOM)',
    'Customer Insights'
  ];

  usedBy: 'Analyst (*perform-market-research)';
  purpose: 'Market analysis and opportunity identification';
}

interface CompetitorAnalysisTemplate {
  id: 'competitor-analysis-template';
  output: 'docs/competitor-analysis.md';

  sections: [
    'Competitor Overview',
    'Product Comparison',
    'Feature Matrix',
    'Pricing Analysis',
    'Market Positioning',
    'Strengths and Weaknesses',
    'Differentiation Opportunities'
  ];

  usedBy: 'Analyst (*create-competitor-analysis)';
  purpose: 'Competitive landscape analysis';
}

interface BrainstormingOutputTemplate {
  id: 'brainstorming-output-template';
  output: 'docs/brainstorming-output.md';

  sections: [
    'Session Overview',
    'Brainstorming Technique Used',
    'Ideas Generated',
    'Ideas Categorized',
    'Top Ideas',
    'Next Steps'
  ];

  usedBy: 'Analyst (*brainstorm)';
  purpose: 'Structured brainstorming session results';
}

template:
  id: architecture-template
  version: "4.0"
  output:
    filename: docs/architecture.md

key_sections:
  - System Overview
  - Tech Stack (Languages, Frameworks, Databases, External Services, Tools)
  - System Components
  - Data Models
  - API Specifications
  - Security Architecture
  - Deployment Architecture
  - Coding Standards
  - Testing Strategy

usedBy: 'Architect (*create-architecture)';
purpose: 'Generic system architecture for any project type';

template:
  id: fullstack-architecture-template
  version: "4.0"
  output:
    filename: docs/fullstack-architecture.md

key_sections:
  - System Overview
  - Tech Stack (Frontend, Backend, Database, Infrastructure)
  - Frontend Architecture (UI, State, Routing, Components, Styling)
  - Backend Architecture (API, Business Logic, Data Access, Auth)
  - Database Architecture (Schema, Models, Migrations)
  - API Specifications (REST Endpoints, Request/Response, Auth)
  - Integration Points
  - Unified Project Structure
  - Deployment Architecture (Frontend, Backend, Database, CI/CD)
  - Coding Standards (Frontend, Backend)
  - Testing Strategy (Frontend, Backend, Integration, E2E)

sections_detail:
  techStack: {
    frontend: ['UI Framework', 'State Management', 'Build Tools', 'Styling'];
    backend: ['Language', 'Framework', 'API Protocol', 'Authentication'];
    database: ['DBMS', 'ORM/ODM', 'Migration Tool'];
    infrastructure: ['Hosting', 'CDN', 'CI/CD', 'Monitoring'];
  };

usedBy: 'Architect (*create-architecture)';
purpose: 'Complete full-stack system architecture';

template:
  id: brownfield-architecture-template
  version: "4.0"
  output:
    filename: docs/brownfield-architecture.md

key_sections:
  - Current Architecture
  - Proposed Changes
  - Affected Components
  - Technical Debt
  - Migration Strategy
  - Compatibility Requirements
  - Updated Tech Stack
  - Updated Data Models
  - Updated API Specifications
  - Deployment Strategy
  - Testing Strategy for Changes

usedBy: 'Architect (brownfield workflows)';
purpose: 'Architecture changes for existing systems';

template:
  id: front-end-architecture-template
  version: "4.0"
  output:
    filename: docs/front-end-architecture.md

key_sections:
  - Frontend Overview
  - Tech Stack (UI Framework, State, Routing, Styling, Build Tools)
  - Component Architecture (Hierarchy, Library, Design System)
  - State Management
  - Routing Strategy
  - API Integration
  - Project Structure
  - Styling Approach
  - Performance Optimization
  - Testing Strategy

usedBy: 'Architect (frontend-only projects)';
purpose: 'Frontend-specific architecture';

interface FrontEndSpecTemplate {
  id: 'front-end-spec-template';
  output: 'docs/front-end-spec.md';

  key_sections: [
    'UI/UX Overview',
    'Design System',
    'Component Specifications',
    'User Flows',
    'Wireframes/Mockups',
    'Interaction Patterns',
    'Responsive Design',
    'Accessibility Requirements'
  ];

  usedBy: 'UX Expert (*create-frontend-spec)';
  purpose: 'UI/UX specifications and design system';
}

interface StoryTemplate {
  id: 'story-template';
  version: '4.0';
  output: 'docs/stories/{epic}.{story}.{title}.md';

  sections: {
    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'];
    };
  };

  usedBy: 'SM (*draft)';
  purpose: 'Story file with complete implementation context';
}

interface QAGateTemplate {
  id: 'qa-gate-template';
  output: 'docs/qa/{story-id}-qa-gate.md';

  sections: {
    header: {
      story: '{{epic}}.{{story}} - {{title}}';
      date: 'ISO date';
      reviewer: '{{qa_agent_name}}';
    };

    gateDecision: {
      options: ['PASS', 'CONCERNS', 'FAIL', 'WAIVED'];
      rationale: 'Explanation of decision';
    };

    qualityReview: {
      acceptanceCriteria: 'Met/Not Met for each criterion';
      codeQuality: 'Assessment against standards';
      testCoverage: 'Percentage and assessment';
      security: 'Security review findings';
      performance: 'Performance assessment';
    };

    issues: {
      format: 'List of issues if CONCERNS or FAIL';
      severity: ['Critical', 'Major', 'Minor'];
    };

    recommendations: {
      content: 'Improvement suggestions';
    };
  };

  usedBy: 'QA (*review, *gate)';
  purpose: 'Quality gate decision and feedback';
}

interface VariableSubstitution {
  syntax: '{{variable_name}}';

  common: {
    project_name: 'Project identifier';
    epic_num: 'Epic number';
    story_num: 'Story number';
    story_title: 'Story title';
    role: 'User role';
    action: 'User action';
    benefit: 'User benefit';
  };

  substitution: 'Replaced during document generation';
}

interface InteractiveElicitation {
  property: 'elicit: true';

  format: {
    mandatory: '1-9 options presented';
    option1: 'Always "Proceed to next section"';
    options2_9: 'From data/elicitation-methods';
  };

  methods: [
    'SCAMPER',
    '5 Whys',
    'Jobs-to-be-Done',
    'User Story Mapping',
    'Event Storming',
    'Impact Mapping',
    'Kano Model',
    'MoSCoW Prioritization'
  ];

  prompt: 'Select 1-9 or type your question/feedback:';
}

interface SectionOwnership {
  owner: {
    property: 'owner: agent-id';
    meaning: 'Primary agent responsible for this section';
  };

  editors: {
    property: 'editors: [agent-id1, agent-id2]';
    meaning: 'Agents allowed to edit this section';
  };

  enforcement: 'Agents only update sections they own or are editors of';
}

interface ComprehensiveInstructions {
  llmInstructions: {
    syntax: '[[LLM: instructions]]';
    visibility: 'Invisible to users, processed by AI only';
    example: '[[LLM: Generate comprehensive overview based on user input]]';
  };

  sectionInstructions: {
    property: 'instruction: "description"';
    usage: 'Guide AI generation for this section';
  };
}

interface SourceReferences {
  format: '[Source: file.md#section]';

  usage: 'Dev Notes section references architecture/PRD sources';

  examples: {
    architecture: '[Source: docs/architecture/tech-stack.md#frameworks]';
    prd: '[Source: docs/prd/epic-1.md#story-1.2]';
    previous: '[Source: docs/stories/1.1-login.md#learnings]';
  };

  purpose: 'Traceability and context source tracking';
}

interface ElicitationStrategy {
  interactive: {
    mode: 'Agent presents draft, user provides feedback';
    options: 'Always 1-9 options with "Proceed" as #1';
    methods: 'SCAMPER, 5 Whys, Jobs-to-be-Done, etc.';
  };

  rapid: {
    mode: 'Agent generates complete section without elicitation';
    usage: 'Time-constrained scenarios';
  };
}

interface TemplateUsagePatterns {
  loading: {
    location: '.bmad-core/templates/{template-id}.yaml';
    trigger: 'Agent command execution';
    example: '*create-prd loads prd-tmpl.yaml';
  };

  generation: {
    steps: {
      1: 'Load template YAML';
      2: 'Substitute {{variables}}';
      3: 'Process [[LLM: instructions]]';
      4: 'Present sections with elicit: true';
      5: 'Generate markdown output';
    };
  };

  customization: {
    override: 'Modify templates in .bmad-core/templates/';
    versioning: 'Track version in template metadata';
    validation: 'Agents check template structure on load';
  };
}

agent_config:
  editable_sections: [Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Testing, Change Log]

key_sections:
  - id: status
    type: choice
    choices: [Draft, Approved, InProgress, Review, Done]
    owner: scrum-master
    editors: [scrum-master, dev-agent]

  - id: story
    type: template-text
    template: "As a {{role}}, I want {{action}}, so that {{benefit}}"
    elicit: true
    owner: scrum-master

  - id: acceptance-criteria
    type: numbered-list
    elicit: true
    owner: scrum-master

  - id: tasks-subtasks
    type: bullet-list
    template: "- [ ] Task (AC: #)\n  - [ ] Subtask"
    elicit: true
    owner: scrum-master
    editors: [scrum-master, dev-agent]

  - id: dev-notes
    instruction: "Complete technical context with source references"
    elicit: true
    owner: scrum-master
    subsections:
      - Testing (location, frameworks, requirements)

  - id: dev-agent-record
    owner: dev-agent
    editors: [dev-agent]
    subsections: [Agent Model, Implementation Approach, File List, Completion Notes, Debug Log References]

  - id: qa-review
    owner: qa-agent
    editors: [qa-agent]
    subsections:
      - QA Gate Decision (PASS/CONCERNS/FAIL/WAIVED)
      - Issues Found
      - Recommendations

  - id: change-log
    type: table
    columns: [Date, Version, Description, Author]

template:
  id: qa-gate-template
  output:
    filename: docs/qa/{{story_id}}-qa-gate.md

key_sections:
  - Gate Decision (PASS/CONCERNS/FAIL/WAIVED)
  - Rationale
  - Issues Found (Per issue: Severity, Description, Location, Recommendation)
  - Test Results
  - Requirements Traceability
  - Risk Assessment
  - Evidence
  - Next Steps

interface VariableSubstitution {
  format: '{{variable_name}}';
  examples: {
    '{{project_name}}': 'My Awesome App';
    '{{epic_num}}': '1';
    '{{story_num}}': '3';
    '{{story_title}}': 'User Authentication';
  };
  sources: ['User input', 'Configuration files', 'Previous artifacts', 'Agent context'];
}

# Section with elicitation
- id: user-personas
  title: User Personas
  elicit: true
  instruction: Describe the primary users

interface SectionOwnership {
  owner: 'Primary agent responsible';
  editors: 'Agents allowed to modify';
  behavior: 'Prevents unauthorized modifications';

  example: {
    section: 'Dev Agent Record';
    owner: 'dev-agent';
    editors: ['dev-agent'];
    rule: 'Only Dev agent can modify this section';
  };
}

.bmad-core/templates/
├── architecture-tmpl.yaml
├── brainstorming-output-tmpl.yaml
├── brownfield-architecture-tmpl.yaml
├── brownfield-prd-tmpl.yaml
├── competitor-analysis-tmpl.yaml
├── front-end-architecture-tmpl.yaml
├── front-end-spec-tmpl.yaml
├── fullstack-architecture-tmpl.yaml
├── market-research-tmpl.yaml
├── prd-tmpl.yaml
├── project-brief-tmpl.yaml
├── qa-gate-tmpl.yaml
└── story-tmpl.yaml

interface ElicitationEdgeCases {
  // When elicit: true, agent MUST use 1-9 format, never yes/no
  correctFormat: {
    prompt: 'Select 1-9 or type your question/feedback:';
    options: [
      '1: Proceed to next section',
      '2-9: Elicitation methods from data/elicitation-methods'
    ];
  };
  
  incorrectFormat: {
    examples: [
      'Do you want to proceed? (yes/no) - WRONG',
      'Should we continue? - WRONG',
      'Press enter to continue - WRONG'
    ];
    reason: 'Violates mandatory 1-9 format requirement';
  };
  
  // User can type free-form feedback instead of selecting 1-9
  freeFormInput: {
    behavior: 'Accept user text input as feedback';
    processing: 'Apply feedback to current section, then proceed';
    example: 'User types "Add more detail about authentication" instead of selecting number';
  };
  
  // YOLO mode bypasses elicitation
  yoloMode: {
    trigger: 'User types #yolo or toggles via *yolo command';
    behavior: 'Process all sections without elicitation prompts';
    useCase: 'Non-interactive batch processing';
  };
}

interface TemplateProcessingEdgeCases {
  // Missing required placeholder values
  missingPlaceholders: {
    behavior: 'Agent prompts user for missing values before proceeding';
    example: '{{project_name}} not provided → agent asks "What is the project name?"';
  };
  
  // Invalid template syntax
  invalidSyntax: {
    detection: 'YAML parsing fails or template structure invalid';
    behavior: 'Report error with line number and expected format';
    recovery: 'Cannot proceed until template syntax fixed';
  };
  
  // Conditional sections
  conditionalLogic: {
    evaluation: 'Agent evaluates conditions based on project type, workflow, user input';
    behavior: 'Skip sections where condition is false';
    example: 'Frontend section only included if project_type includes UI';
  };
  
  // Section ownership conflicts
  ownershipViolations: {
    detection: 'Agent attempts to edit section it does not own';
    behavior: 'Report error: "Section owned by {owner}, use {owner} agent to edit"';
    example: 'Dev agent tries to edit Story section → error, only SM can edit';
  };
}

# Add custom section to PRD template
sections:
  - title: Custom Business Logic
    instruction: Describe custom business rules
    elicit: true

sections:
  - title: Acceptance Criteria
    instruction: |
      Your custom instruction for how to write
      acceptance criteria for your team's process

template:
  version: 4.0  # Template version

# Agents can check version compatibility
# Newer agents work with older templates
# Version changes indicate breaking structure changes