Skip to content

Customize and Extend

Write a Document Template

Use the bmad-facilitate template library to make the skill coach your team through your own document types. Everything about a document is data. Template files say what each document asks for and what the review checks. The skill’s customization says where templates live, where the result goes, and how the HTML view looks.

New to templates? How Document Templates Work explains the pieces, and Customize a Document for Your Team walks through changing a shipped one. This page is the full guide to the file format.

  • Your team has a document type the shipped templates do not cover.
  • Your organization has its own format for a postmortem, a proposal, or a decision record.
  • A shipped template is right, but your team has rules to add: a policy to cite, a section it must contain, a check for the review.
  • Rendered views should carry your team’s look.

The quickest way is to ask bmad-facilitate to make a template for the document, such as “bmad-facilitate, make a template for vehicle appraisal reports”. It coaches you through one, with the rules below built in, and saves it in _bmad/custom/facilitate-templates/. When an agent should offer it, ask Smithy (bmad-toolsmith) instead, who has the engine write it and wires the agent to it. The rest of this page is the format, for writing or reading one by hand.

Save the template in _bmad/custom/facilitate-templates/, with any rubric or method catalog beside it. The skill lists every markdown file there whose frontmatter has template:. Nothing else needs registering.

---
title: ""
template: runbook
version: 1.0.0
description: "Step-by-step instructions for one alert or recurring task."
rubric: rubric-runbook.md
status: draft
created: ""
updated: ""
---
FieldWhat it holds
templateKebab-case id. It names the run folder, and a later update uses it to find the template.
versionOptional version of the template. It is copied into each document, so a later update can say the template has moved on.
descriptionOne short line saying what the template is for. Help lists it for every template on every run, so keep it under about 80 characters. Quote it, because a colon breaks unquoted YAML.
not_forOptional short line naming what the template is not for, and the template to use instead. Read with description when choosing one, and not listed in help.
pacedOptional. true walks the sections in order, one at a time, for a document whose conversation matters as much as the result. See Walk the sections in order.
facilitation_orderThe sections by id, in the order the skill takes them up, with ? on each one that is not required. See Order the sections.
guidanceOptional rules shared by a family of templates and read as part of each, as a path relative to the template, or the bare name guidance-planning for the shipped planning rules: stakes from hobby to regulated, stable ids and testable requirements, and detail pushed to the level below. Every shipped template sets it. Without it the skill names no stakes levels; a document such as fiction says what it needs in its own comments. Every document, with or without it, carries [ASSUMPTION: ...] tags where the coach guessed, until you accept or correct each one.
agentsOptional list of the skills that offer this template, such as [bmad-agent-pm]; name several to share it. It says who offers the template by default; any agent the user asks can still write it. The bmad skill uses the list to say who offers the template. A template in an agent’s assets/ folder counts as that agent’s without it.
rubricOptional path to a rubric for the review, relative to the template, or the bare name rubric-planning for the shipped planning rubric. Empty uses the shipped general rubric, which suits any document.
methodsOptional path to a method catalog, relative to the template: a CSV whose rows supply the questions the coaching asks.
outputOptional run folder for this template. It may use {output_folder}, {active_initiative}, {id} and {slug}.
styleOptional CSS file for this template’s rendered view, relative to the template.
viewOptional layout for the rendered view: document, slides, or an HTML file relative to the template. It says what the view looks like, not whether it is made. See Give a template its own view.
html_viewOptional. Whether this template’s view is made: always, offer or never, replacing the team’s setting for this template. Set always when the view is the deliverable, as pitch-deck does for its slides. A team’s never still stops it.

template, version and view stay in the finished document, as does any field you add for a view to show. The other fields stay out.

A method catalog has the header category,method,name,description,key_questions, with the key questions separated by |. The shipped security-review template uses one for the OWASP Top 10 and STRIDE:

category,method,name,description,key_questions
release,rollback,Rollback,How a change is undone.,"How is this change undone?|Who can run the rollback?"

The first template with an id wins, and installed modules’ templates are searched last, so a template in any library with the same template: value replaces one a module installed. To change an installed template, copy it from the module’s doc-templates/ folder into yours, with any rubric or catalog it names, keep its template: value and edit the copy. To use your organization’s postmortem format, save it in your folder with template: postmortem.

template_libraries lists where templates live, in search order. It starts with your project’s _bmad/custom/facilitate-templates/, then ~/.bmad/facilitate-templates/ for personal templates you want in every project. An override appends to the list, and a folder that is missing or empty adds nothing.

_bmad/custom/bmad-facilitate.toml
[workflow]
template_libraries = ["https://github.com/fernhollow/doc-templates@v1.2.0"]
EntryExample
A folder or one template file{project-root}/docs/templates or ~/templates
A GitHub repo, folder or file, read through ghhttps://github.com/fernhollow/doc-templates/tree/v1.2.0/planning
A URL to one .md filehttps://example.com/templates/runbook.md
A sentence naming the tool that reaches itSearch corp:confluence_search in the DOCS space for templates

A library you cannot share goes in bmad-facilitate.user.toml, which stays out of git. A teammate without access who updates one of those documents follows its existing headings instead. If a library cannot be read, the skill names it and carries on with the others.

A module adds templates by putting them in doc-templates/ in its record folder, the folder holding its bmod.toml, with any rubric or catalog beside them. They are offered once the module is installed, with no setting, and they update with the module. The shipped templates live this way in bmod-method, bmad-founder-agent-advisor and bmod-cis.

An organization can keep its templates in its own modules, one per program if it likes, such as bmod-fernhollow-cards. A module should add new ids or extend existing ones, because an extension applies wherever it sits. To replace an id outright, use a project’s folder, which is searched first.

A template is a markdown file in three parts: the document’s frontmatter, comments that guide the coaching, and its sections. Frontmatter comes first. The comments never appear in the finished document. Where a template and the skill disagree, the template wins, on every path; only a headless run still asks nothing.

---
title: ""
template: runbook
version: 1.0.0
description: "Step-by-step instructions for one alert or recurring task."
facilitation_order: [when-to-use, severity, steps, rollback?, escalation?]
status: draft
created: ""
updated: ""
---
<!-- purpose: Let an on-call operator handle one alert or task without help. -->
<!-- stance: Walk the procedure as the operator would and ask what they check after each step. -->
<!-- inputs: The alert or task, the access it needs, the exact commands. Only the user knows the failures they have seen. -->
<!-- writing:
- Numbered steps, one action each, with its expected result.
- Commands copied exactly.
-->
<!-- done when: Someone new to the system can follow it alone and knows when to escalate. -->
# {title}
## When to use
<!-- The alert, symptom or schedule that starts this runbook. -->
## Severity
<!-- The user must pick exactly one of: sev1, sev2, sev3. -->
## Steps
<!-- Numbered actions with expected results. When a step says "check the dashboard", ask which one and what a good reading is. diagram: flowchart -->
## Rollback
<!-- include when: a step changes production. How to undo each change. -->
## Escalation
<!-- optional. Who to call and when. -->

Above the first heading, give each of these keys its own comment, a line or two. All are optional:

KeyWhat it tells the skill
purposeThe decision or job the document serves.
stanceHow to coach for this document, including how a path should run.
inputsWhat must be asked, and which of it only the user knows. Each one is asked on the coaching and fast paths unless the user already gave it, so list only what you want asked.
writingRules specific to this document.
companionsOther files to write beside the document, when, and what each holds. A file for a different reader belongs here, not overflow from the document.
done whenThe test that ends the questioning.
viewThe brief for an HTML page written for each document. See Give a template its own view.
nextWhat to offer or do once the document is done, such as handing it to a build.

Add view: slides to the frontmatter for a slide view, or name an HTML view file; without it the HTML view is one page. In the document body, {title} is the only placeholder.

Each section has one comment: a line on what goes in the section, then diagram: and a Mermaid kind when a picture carries the meaning (flowchart, sequence, state, timeline, gantt, er, mindmap, quadrant, journey). A section that is not required starts its comment with optional or include when: and a condition.

facilitation_order lists every ## section by id: its heading in lowercase, with punctuation dropped and spaces as hyphens, so What makes it different is what-makes-it-different and What's next? is whats-next. It sets the order the skill takes the sections up in, not the document’s order, so an executive summary can sit first in the document and come up last. A ? after an id marks a section that is not required.

The skill settles every section before it finishes, on every path. A required section is always filled. An optional one is offered when the order reaches it, and the user decides. An include-when one is checked against its condition, and the skill says what it found. The fast path settles them too, so asking for speed never drops a section quietly. Sections left out are named at the end with the reason.

The template list reports an id that names no heading, an id listed twice, and a heading left off the list. Every shipped template sets the key. A template without it still works: a section whose comment does not start with optional or include when: is required, and the document’s order is the order.

Say what goes in each section, not how to write well. Leave out example content, which the model would copy.

A section comment can also steer the conversation or limit the answer, in plain sentences. The Steps comment above tells the skill when to press, and Severity limits the user to a list. A list can live elsewhere: “The user must pick a team from docs/teams.md.” The shipped decision-record and security-review templates show both, and Document Templates lists where to see each capability.

Set paced: true when going through the sections is the point, as in a PRFAQ, where the user defends each part before moving on. The skill shows the sections in facilitation order before it starts, then takes them one at a time and finishes each before opening the next.

In a paced template, each section comment is the brief for that part of the session. A voice, stance or method it sets, such as “you are now a skeptical customer”, replaces the skill’s coaching defaults until the section closes, so write it as instructions to the coach rather than only a description of the content. These shipped templates are paced: Mary’s prfaq and brief, John’s experiment, opportunity and pitch, and the module’s decision-record and postmortem.

Every run shows a progress line on the messages that ask something: PRFAQ · Customer FAQ (2 of 4) when paced, PRD · 6 of 24 done otherwise. The total is every section in the facilitation order, and a section counts once it is settled, so the total stays the same for the whole run.

Put a bare ## Table of Contents heading right after the title of any template whose documents run long. Agents often read only the top of a file to judge it, so the skill fills this with a linked entry per section and a short phrase of its key terms, then checks it against the final headings. It gets no slide in a slide view.

A file with no comments is followed as written: every heading is required, in order. Save your organization’s existing format in the folder with template and description in its frontmatter and it works.

---
title: ""
template: design-note
version: 1.0.0
description: "Recording the design of a change before building it."
status: draft
---
# {title}
## Background
## Proposal
## Rollout plan
## Risks

Add the comments when you want the coaching, the optional sections, or the diagrams.

An extension changes a template without copying it, so updates to the original still reach you. On every run the skill merges the template and its extensions into one file, the extensions first, and works from that file. To see exactly what it reads, ask bmad-customize to show the merged template. Save a file with extends: and the template’s id in any library or module, and every run of that template includes it. Fernhollow Bank, a fictional company, uses the proposal template as it is, but every proposal must name an approval track from a fixed list and leave room for reviewers:

---
extends: proposal
---
## Approval Track
<!-- After Budget. The user must pick exactly one of: fast-track, standard, regulated. -->
## Review Comments
<!-- Last. Keep the line below as it is; reviewers fill this in later. -->
_Reviewer comments go here._

An extension can hold anything a template can:

In the extensionEffect
A sectionAdded where its comment says, and taken up at that point in the conversation. If the heading it names is gone, the skill places it by judgment. It is required unless its comment starts optional or include when, the same rule as a template’s sections. With the same heading as a template section, it replaces that section or adds to it, as its comment says.
facilitation_order frontmatterReplaces the template’s whole order. A template section it leaves out is removed from the document, and the template list names it under removed. Set it only to reorder or remove the template’s sections, never just to place a new one, because a section the template adds in a later update is also left out and removed.
stance, inputs, writing or done when commentsAdded to the template’s, and they win where they disagree with it. A policy to load goes in inputs; a review rule goes in done when.
description, not_for, guidance, rubric, methods, output, style, view or html_view frontmatterReplaces the template’s value.

This extension opens every PRD with a quote and always makes its HTML view, while John’s updates to the PRD still arrive:

---
extends: prd
html_view: always
---
## Quote
<!-- First, right under the title. Ask the user for a quote unique to this product before anything else. -->

When extensions conflict, the first in search order wins. Use a copy only to rebuild a template, or with a new id for a different document; Customize a Document for Your Team shows when.

Rules for every document, whatever the template, go in persistent_facts, doc_standards and finalize_reviewers under [workflow] instead.

At close the skill can render the document as one HTML file, diagrams included. The page loads its Markdown and diagram renderers from jsDelivr when opened, so a reader with no network sees the plain text instead. Raw HTML in the document shows as text, and script links are dropped.

[workflow]
style = "{project-root}/_bmad/style/brand.css"
html_view = "always"

style is a CSS file applied to every view after the default styles; empty uses the default. A written voice or style guide belongs in doc_standards or a template’s writing comment instead. A template’s style overrides it for that template. html_view is offer (the default: ask at close), always, or never. A template’s own html_view replaces it for that template, except that never here stops every view.

A template stays markdown, and so does the document the skill writes, because the skill grows it section by section, reviews it and diffs it. An HTML result is a separate step at close, and all its instructions stay in the template. Choose how much freedom the page gets:

You wantIn the templateWhat happens
The same layout every time, such as a form headed for PDFview: invoice.htmlA script fills the file’s slots. Nothing is interpreted.
A shared structure that adapts to each documentview: character-sheet.html and a view commentA subagent uses the file as a starter and follows the comment.
A page invented for each document, with no templateA view comment aloneA subagent writes it from the comment.

The view comment sits above the first heading with the other comments, and says what the page should do:

<!-- view: The sheet is the deliverable. `character-sheet.html` is a starter: keep to one printable page, and let this character's world set the look. -->

A written page comes only from the document, so it adds no claim the document does not hold. Each one costs a fresh generation, so the skill offers it at close unless the template sets html_view: always or the comment calls it the deliverable. Use the script for anything regulated or signed, where the page must not vary. html_view = "never" stops all three.

The view file is ordinary HTML with its CSS inline. Attributes mark where the document’s content goes:

AttributeFilled with
data-section="Heading"That ## section, rendered. Matching ignores case.
data-bodyInside a data-section element, the place the section goes, so a label can sit beside it. Without one, the section replaces the element’s contents.
data-field="key"That frontmatter value, as text. title falls back to the document’s first heading.
data-restEvery section no slot names, with its heading.
<h1 data-field="title"></h1>
<section data-section="Secrets"><h2>Secrets</h2><div data-body></div></section>
<section data-rest></section>

A slot with nothing to show is removed along with its element, so a declined section leaves no empty card. Without a data-rest slot, a section the view does not name stays out of the page, and the render says which. The style setting still applies after the view’s own CSS.

Run the resolver on bmad-facilitate with --key workflow.template_libraries to see the merged list; see Check what resolved. Then ask bmad-facilitate for your new document type and confirm it offers your template.