Skip to content

YAML Schema Reference

A guideline file is a YAML document containing a list of guideline items. Each item is an object with the fields described below.

- name: <string>            # required
  md_section: <string>      # required
  md_lines: <string|list>   # required
  md_vars: <map>            # optional
  conflicts_with: <list>    # optional
  stack: <map>              # optional

Fields

name (required)

Type: string

The display name shown in the TUI item list. Also serves as the identifier for conflicts_with references — it must be unique within the set of loaded guidelines.

name: Atomic commits

name does not appear in the generated markdown output.

md_section (required)

Type: string

The section heading this guideline belongs to. Guidelines with the same md_section are grouped under a ## heading in the output and displayed together in a single TUI tab.

md_section: Version Control

Section names are free-form. The TUI tabs are created dynamically from the unique md_section values found in the loaded guidelines.

md_lines (required)

Type: string or list of strings

The bullet text(s) to write to the output. Each string becomes a - prefixed bullet under the section heading. Use a plain string for a single bullet, or a YAML list for multiple:

# Single bullet
md_lines: Make atomic commits. Include tests and docs in the same commit.

# Multiple bullets
md_lines:
  - Make atomic commits. Include tests and docs in the same commit.
  - Each commit should produce a working build.

md_lines may contain {variable_name} placeholders — see md_vars.

md_vars (optional)

Type: map of string → string | number

Declares template variables used in md_lines and their default values. The TUI will prompt the user to confirm or override each variable at generation time.

- name: Small focused functions
  md_section: Code Style
  md_lines:
    - Keep functions under {max_lines} lines. Extract logical sub-steps into named helpers.
  md_vars:
    max_lines: 40

If multiple selected guidelines share a variable name, the user is prompted once and the same value is substituted in all of them. The default shown is taken from the first occurrence found.

Variable names must match \w+ (word characters only).

conflicts_with (optional)

Type: list of strings

Names of other guidelines that are mutually exclusive with this one. The TUI shows a conflict warning if the user selects both, and flags conflicting items in red.

Conflicts are bidirectional by convention — it is good practice to declare the conflict on both items, though the TUI will detect a conflict if only one side declares it:

- name: No ORM
  md_section: Databases
  md_lines:
    - Do not use an ORM. Write SQL directly using the database driver.
  conflicts_with:
    - Use an ORM

- name: Use an ORM
  md_section: Databases
  md_lines:
    - Use an ORM for database access.
  conflicts_with:
    - No ORM

Conflict references are matched by name and work across files loaded from the same directory.

stack (optional)

Type: map of stack-name → stack-variant object

Provides alternative md_lines for specific technology stacks. When the user selects a matching stack at generation time, the stack-specific lines replace the generic ones.

- name: Consistent naming
  md_section: Code Style
  md_lines:
    - Use consistent naming conventions throughout the codebase.
  stack:
    typescript:
      md_lines:
        - camelCase for variables and functions, PascalCase for types/classes/components, SCREAMING_SNAKE_CASE for module-level constants.
    python:
      md_lines:
        - snake_case for variables and functions, PascalCase for classes, SCREAMING_SNAKE_CASE for module-level constants. Follow PEP 8.

Stack names are free-form strings. The built-in guidelines use typescript and python. All stack names found across the loaded guidelines are collected and presented in the stack-selection screen.

Each stack variant supports only md_lines. The md_vars, conflicts_with, and other fields from the parent item still apply.

Validation

agents-md-wizard validates loaded YAML before displaying the TUI. It will refuse to start and print an error if:

  • A required field (name, md_section, md_lines) is missing
  • md_lines is neither a string nor a list of strings
  • md_vars values are not strings or numbers
  • conflicts_with entries are not strings
  • stack variants are not objects with an md_lines field

Complete example

- name: Request timeouts
  md_section: Networking
  md_lines:
    - Set explicit timeouts on all outbound HTTP requests. Default to {timeout_ms}ms.
    - Log a warning when a request is retried; log an error when it fails after all retries.
  md_vars:
    timeout_ms: 5000
  stack:
    typescript:
      md_lines:
        - Pass a timeout option to fetch or your HTTP client. Use AbortController for cancellation. Default to {timeout_ms}ms.
    python:
      md_lines:
        - Pass timeout={timeout_ms_as_s} to requests.get() / httpx. Use a session with default timeout settings rather than per-call values.
  conflicts_with:
    - No request timeouts

- name: No request timeouts
  md_section: Networking
  md_lines:
    - Do not add timeouts to outbound HTTP requests in this service — the upstream handles cancellation.
  conflicts_with:
    - Request timeouts