How Prompt-Optimizer Template Management Works: A Complete Guide to Creating Custom Templates

Prompt-Optimizer uses a declarative YAML-to-UI-to-Markdown pipeline where templates stored in .bmad-core/templates/ define interactive prompts that render structured documents via the create-doc task.

The prompt-optimizer template management system in the linshenkx/prompt-optimizer repository provides a scaffolding engine that transforms YAML declarations into guided document creation workflows. This architecture allows teams to standardize document formats—such as PRDs, user stories, or API specifications—while ensuring consistent data capture through dynamically generated user interfaces.

Understanding the Prompt-Optimizer Template Architecture

Where Templates Live

All document scaffolding logic resides in the hidden .bmad-core/templates directory. Each template is a standalone YAML file (e.g., prd-tmpl.yaml, story-tmpl.yaml) that the system discovers at runtime. According to the source code, the create-doc task specifically looks for files in this location when resolving template names.

The create-doc Task Pipeline

The template engine operates through four distinct phases as implemented in .bmad-core/tasks/create-doc.md:

1. Selection – The user invokes *create-doc <template-name> from the UI or CLI, triggering a load operation from .bmad-core/templates/.
2. Parsing – The task extracts the fields array from the YAML, which defines the interactive prompts (labels, types, placeholders) presented to the user.
3. Rendering – After collecting user input, the engine replaces Jinja-style placeholders (e.g., {{featureName}}) in the template's sections with the provided values.
4. Output – The final Markdown file is written to appropriate subdirectories (e.g., docs/prd/, docs/stories/), optionally triggering post-generation hooks like *execute-checklist for validation.

How to Create Custom Templates in Prompt-Optimizer

Step 1: Define Your YAML Structure

Create a new file in .bmad-core/templates/ using snake-case naming (e.g., my-feature-spec-tmpl.yaml). The engine recognizes three top-level keys:

• title – Display name shown in the UI selector
• description – Contextual help text for the template
• fields – Array defining user inputs
• sections – Array defining the generated Markdown structure

Step 2: Configure Interactive Fields

The fields array determines what controls the UI renders. As referenced in packages/ui/src/components/ModelManager.vue, supported types include string, multiline, list, select, date, and json.

# .bmad-core/templates/api-spec-tmpl.yaml

title: "API Specification"
description: "Document the contract of a new REST endpoint."
fields:
  - id: endpoint
    label: "Endpoint URL"
    type: string
    placeholder: "/api/v1/resource"
  - id: method
    label: "HTTP Method"
    type: select
    options: ["GET", "POST", "PUT", "DELETE"]
  - id: requestSchema
    label: "Request JSON schema"
    type: json
  - id: responseSchema
    label: "Response JSON schema"
    type: json

Each field requires a unique id that serves as the variable name for substitution in the output template.

Step 3: Design the Output Sections

The sections array combines static Markdown headings with dynamic placeholders. Use standard Jinja2 syntax for logic like loops when handling list types.

sections:
  - heading: "## Endpoint"

    content: "`{{method}} {{endpoint}}`"
  - heading: "## Request"

    content: "```json\n{{requestSchema}}\n```"
  - heading: "## Response"

    content: "```json\n{{responseSchema}}\n```"
  - heading: "## Acceptance Criteria"

    content: |
      {% for item in acceptanceCriteria %}
      - {{ item }}
      {% endfor %}

Step 4: Invoke Your Custom Template

Reference your template using the task command:

# In the Prompt-Optimizer UI or CLI

*create-doc api-spec-tmpl.yaml

The system renders the appropriate input controls (text fields, dropdowns, JSON editors) based on your field definitions, then generates the Markdown file in the docs/ hierarchy.

Advanced Template Features

Supported Field Types and UI Controls

The template engine maps YAML type declarations to specific UI components:

• string – Single-line text input
• multiline – Textarea for paragraphs
• list – Dynamic list builder with add/remove functionality
• select – Dropdown with predefined options array
• json – Syntax-highlighted JSON editor with validation

These mappings ensure that complex data structures like API schemas are captured correctly before document generation.

Integrating Templates into Workflows

Templates become powerful when chained into automated workflows defined in .bmad-core/workflows/*.yaml. To enforce quality gates after document creation, reference your template followed by a validation checklist:

# .bmad-core/workflows/greenfield-service.yaml

tasks:
  - create-doc api-spec-tmpl.yaml
  - execute-checklist api-spec-checklist.md

This pattern ensures that every generated document undergoes the BMAD method validation steps appropriate to its type.

Template Management Best Practices

Keep templates small and focused—one logical document per YAML file—to maximize reusability across different product workflows. Use descriptive id values and comprehensive label text to ensure future contributors understand the intent behind each field without reading the source code.

Document the template's purpose in the top-level description field; this text appears in the UI template selector, improving discoverability for team members. After generating any document, run the associated *execute-checklist task (e.g., *execute-checklist story-draft-checklist) to verify that all required sections from the original template are present and populated.

Summary

• Prompt-optimizer template management relies on YAML files in .bmad-core/templates/ that declare interactive fields and output sections.
• The create-doc task parses these files, renders UI controls for data collection, and generates Markdown by substituting {{placeholders}} with user input.
• Custom templates support multiple field types including select, json, and list, with the UI adapting controls accordingly as seen in packages/ui/src/components/ModelManager.vue.
• Integrate templates into .bmad-core/workflows/*.yaml to enforce post-generation validation through checklist tasks.
• Use snake-case naming, clear field descriptions, and focused single-purpose templates to maintain system clarity.

Frequently Asked Questions

Where are prompt-optimizer templates stored?

Templates are stored in the .bmad-core/templates directory of the repository. Each template is a standalone YAML file that the create-doc task discovers at runtime by resolving the template name you provide against files in this location.

What field types are supported in custom templates?

The system supports string, multiline, list, select, date, and json field types. These map to specific UI controls in the prompt-optimizer interface—ranging from simple text inputs to dropdown selectors and syntax-highlighted JSON editors—ensuring appropriate data capture for each template's requirements.

How do I validate documents created from custom templates?

After generating a document with *create-doc, run the *execute-checklist task with the appropriate checklist file (e.g., *execute-checklist api-spec-checklist.md). This executes post-generation hooks defined in .bmad-core/tasks/create-doc.md to verify that your document conforms to BMAD method standards and contains all required sections from the original template.

Can I use templates in automated workflows?

Yes. Reference your custom template in any .bmad-core/workflows/*.yaml file by adding it to the tasks list. This allows you to chain document creation with validation steps, ensuring that templates are invoked automatically as part of structured product development workflows like greenfield services or UI component design.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}