Custom Guidelines¶
You can extend or replace the built-in guidelines with your own YAML files. This is useful for team-specific conventions, house style rules, or domain-specific guidance that isn't covered by the defaults.
Quickstart¶
Create a directory and add one or more .yaml files:
Run agents-md-wizard pointing at the directory:
Or point at a single file:
A minimal guideline¶
Each YAML file contains a list of guideline items. The minimum required fields are name, md_section, and md_lines:
- name: Use feature flags for risky changes
md_section: Deployment
md_lines:
- Wrap risky changes in a feature flag. Deploy with the flag disabled, verify in production, then enable.
name is the display label in the TUI (and the identifier used in conflict declarations). md_section determines which tab it appears under and which ## heading it is grouped under in the output. md_lines is the bullet text — a single string or a list.
Multiple lines per guideline¶
If a guideline naturally produces more than one bullet, use a YAML list:
- name: Structured logging
md_section: Observability
md_lines:
- Use structured JSON logging, not plain text log lines.
- Include a correlation ID on every log entry that enters via an HTTP request.
- Never log credentials, tokens, or PII.
Variables¶
Use {placeholder} syntax in md_lines and declare defaults in md_vars. The TUI will prompt for each variable at generation time:
- name: Max PR size
md_section: Version Control
md_lines:
- Pull requests should not exceed {max_pr_files} changed files. Break larger changes into a stack of smaller PRs.
md_vars:
max_pr_files: 20
If you select multiple guidelines that share a variable name, the user is only prompted once — the first default found is used.
Stack-specific wording¶
Use stack to provide alternative md_lines for specific runtimes or languages. When the user selects a matching stack at generation time, the stack-specific text replaces the generic text:
- name: Prefer immutable data
md_section: Code Style
md_lines:
- Prefer immutable data structures. Avoid mutating objects in place.
stack:
typescript:
md_lines:
- Prefer readonly types and const assertions. Use Readonly<T> and as const. Avoid direct mutation.
python:
md_lines:
- Use tuples and frozensets for data that should not change. Avoid mutating function arguments.
Stack names are arbitrary strings — whatever you use here will appear in the stack-selection screen. The built-in guidelines use typescript and python.
Conflict declarations¶
Mark guidelines that are mutually exclusive with conflicts_with. The TUI prevents selecting both and shows a warning if a conflict exists:
- name: Use Postgres
md_section: Databases
md_lines:
- Use PostgreSQL as the primary relational database.
conflicts_with:
- Use MySQL
- name: Use MySQL
md_section: Databases
md_lines:
- Use MySQL as the primary relational database.
conflicts_with:
- Use Postgres
Conflicts are declared by name, so they work across files in the same directory.
Directory layout¶
When you pass --dir, agents-md-wizard loads all .yaml and .yml files in that directory (sorted alphabetically) and merges them. The section tabs in the TUI reflect the md_section values found across all files.
A typical layout might mirror the built-in structure:
my-guidelines/
code-style.yaml
testing.yaml
version-control.yaml
deployment.yaml
team-conventions.yaml
There is no required naming scheme — the filenames are only used for sort order.
Combining with built-ins¶
Currently --dir and --config replace the built-in guidelines entirely. To combine your guidelines with the built-ins, copy the built-in guidelines from the repository into your directory as a starting point, or concatenate them with your additions into a single file.
Full field reference¶
See the YAML Schema reference for a complete description of every field.