Creating Templates

Templates let you define default values and body structure for note types.

Template Properties

Property	Required	Description
type	Yes	Must be template
template-for	Yes	Type path (e.g., objective/task)
description	No	Human-readable description
defaults	No	Default field values (skip prompting)
prompt-fields	No	Fields to always prompt for
filename-pattern	No	Override filename pattern
instances	No	Child notes to create with parent (see Instance Scaffolding)

Creating a Template

Via CLI

bwrb template new task
bwrb template new task --name bug-report

Manually

Create a file at .bwrb/templates/<type>/<name>.md:

---
type: template
template-for: objective/task
description: Standard task template
defaults:
  status: backlog
---

## Notes

Default Values

Template defaults skip prompting and pre-fill field values.

Static Defaults

defaults:
  status: backlog
  priority: medium
  tags: []

Fields declared with multiple: true (multi-select and multi-relation fields) store their defaults as an array, so a template can pre-fill more than one value:

defaults:
  labels:
    - urgent
    - review

When you build or edit a template interactively (bwrb template new / bwrb template edit), both multi-select and multi-relation fields use a checkbox-style multi-select prompt in both modes, so you can choose several values at once. In template edit, a multi-value default offers (keep), (clear), (set empty []), and (select values).

Dynamic Defaults (Date Expressions)

Use date expressions for dynamic values that evaluate at note creation time. A default value is evaluated as a date expression only for date fields, and only when the entire value matches the date-expression grammar. Any other string (links, prose, option values, literal dates like 2026-01-07) is written through unchanged. Non-date fields also pass date-looking prose through literally, so a text field default like @today+3d remains @today+3d. The evaluated date is then normalized to canonical YYYY-MM-DD on write (and a field’s granularity is respected), so templated dates pass bwrb audit.

There are two interchangeable spellings:

• Shorthand (recommended): @today, @today+3d
• Function form: today(), today() + '7d'

Expression	Result	Description
@today / today()	2026-01-07	Current date
@today+7d / today() + '7d'	2026-01-14	7 days from now
@today+1w	2026-01-14	1 week from now
@today+1m / @today+1mon	2026-02-06	1 month from now (30 days)
@today-1w / today() - '1w'	2025-12-31	1 week ago
@now / now()	2026-01-07 14:30	Current datetime
@now+2h / now() + '2h'	2026-01-07 16:30	2 hours from now

Whitespace around the offset is optional (@today+3d and @today + 3d are equivalent). An offset that looks like a date expression but is malformed (e.g. @today+3x) raises a clear error rather than being written verbatim.

Duration units:

• min — minutes
• h — hours
• d — days
• w — weeks (7 days)
• mon (or m) — months (fixed 30 days, not calendar months)
• y — years (fixed 365 days, not calendar years)

Example: Weekly review template with auto-deadline:

---
type: template
template-for: task
description: Weekly review with auto-deadline
defaults:
  status: backlog
  deadline: "@today+7d"
---

Staggered deadlines across spawned tasks

Date offsets shine with instance scaffolding: a parent template can spawn several tasks at once, each with a deadline staggered from the day the parent is created. Instance defaults use the same date-field evaluation as parent template defaults.

---
type: template
template-for: project
description: Write an article — spawns its predictable tasks, staggered from today
instances:
  - { type: task, defaults: { name: "Outline", deadline: "@today+1d" } }
  - { type: task, defaults: { name: "Draft",   deadline: "@today+3d" } }
  - { type: task, defaults: { name: "Edit",    deadline: "@today+5d" } }
  - { type: task, defaults: { name: "Publish", deadline: "@today+7d" } }
---

Running bwrb new project --template write-an-article on 2026-01-07 produces four tasks with deadlines 2026-01-08, 2026-01-10, 2026-01-12, and 2026-01-14 — all stored as canonical ISO dates.

Value Precedence

When creating a note, values are applied in this order (later values override earlier):

1. Schema defaults — Base values from type definition
2. Template defaults — Override schema defaults
3. JSON/CLI input — Override everything (for automation)

# Template sets status: backlog, but JSON input overrides it
bwrb new task --json '{"name": "My Task", "status": "in-flight"}'
# Result: status is "in-flight", not "backlog"

Variable Substitution

Use variables in the template body:

Variable	Description
{fieldName}	Replaced with frontmatter value
{date}	Today’s date (YYYY-MM-DD)
{date:FORMAT}	Custom date format

Example:

---
type: template
template-for: idea
defaults:
  status: raw
---

# {name}

Created: {date}

## Description

When bwrb new idea --name "My Idea" runs, {name} becomes “My Idea” and {date} becomes today’s date.

Prompt Fields

Use prompt-fields to always prompt for specific fields, even when they have defaults:

defaults:
  status: backlog
  priority: medium
prompt-fields:
  - deadline
  - milestone

This pre-fills status and priority but always asks for deadline and milestone.

Template Discovery

Templates use strict matching:

• objective/task looks in .bwrb/templates/objective/task/
• No inheritance from parent types

Selection Precedence

1. --template name — Uses .bwrb/templates/{type}/name.md
2. --no-template — Skips templates entirely, uses schema defaults only
3. Default — Uses .bwrb/templates/{type}/default.md if it exists

Note: --no-template takes precedence. If both flags are specified, templates are skipped:

bwrb new task --template bug-report --no-template
# Result: no template used (--no-template wins)

Best Practices

Use default.md for Common Workflows

Create a default.md template for types you use frequently. It applies automatically without --template:

bwrb new task  # Uses default.md automatically

Reserve Named Templates for Specialized Formats

Create named templates for specific use cases:

.bwrb/templates/task/
├── default.md       # Standard task
├── bug-report.md    # Bug with repro steps
└── sprint-item.md   # Sprint planning format

Set Safe Defaults, Prompt for Critical Fields

Pre-fill fields with sensible defaults, but always prompt for fields that vary:

defaults:
  status: backlog      # Safe default
  priority: medium     # Safe default
prompt-fields:
  - deadline           # Always ask (varies per task)
  - milestone          # Always ask (context-dependent)

Use Date Expressions for Time-Sensitive Defaults

For recurring tasks with relative deadlines:

# Weekly review: deadline always 7 days out
defaults:
  deadline: "@today+7d"

# End-of-month report: deadline always 30 days out
defaults:
  deadline: "@today+1mon"

Validate Templates After Schema Changes

When you modify your schema, validate templates to catch broken references:

bwrb template validate

This catches:

• References to removed fields
• Invalid select values
• Mismatched type paths

Instance Scaffolding

Templates can define instances to automatically create related child notes when the parent note is created. This is useful for project templates that need consistent supporting files.

Defining Instances

---
type: template
template-for: project
description: Project with scaffolded research notes
defaults:
  status: in-flight
instances:
  - type: research
    filename: "Background Research.md"
    defaults:
      status: raw
  - type: research
    filename: "Competitor Analysis.md"
    defaults:
      status: raw
---

# Project Overview

## Goals

## Timeline

Instance Properties

Property	Required	Description
type	Yes	Type of note to create
filename	No	Literal filename override (default comes from filename pattern, title, name, or {type}.md)
template	No	Template to use for the instance
defaults	No	Instance-specific default values

Behavior

When you run bwrb new project --template with-research:

1. The parent project note is created
2. Each instance file is created in that instance type’s configured output_dir
3. Instances may use the same type as the parent, so a task template can scaffold more task notes
4. Existing instance files are skipped (not overwritten)
5. A summary shows what was created

Instance defaults are applied to the child note’s own fields. Date expressions such as @today+3d or today() + '7d' evaluate for child date fields, including fields like scheduled and deadline; non-date fields keep date-looking strings literally.

Instance defaults and explicit filename values do not interpolate parent placeholders such as {name}. For article-specific child task names, write the literal child names you want in the template, rely on the child type’s own filename pattern, or wrap bwrb new in a script that generates the desired instance definitions. Avoid braces in explicit child filenames unless you want the braces to be part of the actual filename.

✓ Created: Projects/My Project.md

Instances created:
  ✓ Research/Background Research.md
  ✓ Research/Competitor Analysis.md

✓ Created 3 files (1 parent + 2 instances)

Same-Type Task Example

A writing workflow can create a parent task plus predictable same-type task follow-ups. The child task notes are placed in the task type’s output_dir, which may be the same directory as the parent or a separate task directory depending on your schema.

---
type: template
template-for: task
description: Builder article production checklist
defaults:
  status: planned
  scheduled: "@today+1d"
  deadline: "@today+7d"
instances:
  - type: task
    defaults:
      name: "Outline article"
      status: planned
      scheduled: "@today+1d"
  - type: task
    defaults:
      name: "Draft article"
      status: planned
      scheduled: "@today+3d"
  - type: task
    defaults:
      name: "Review and publish article"
      status: planned
      scheduled: "@today+5d"
---

## Brief

## Notes

Skipping Instance Creation

Use --no-instances to create only the parent note:

bwrb new project --template with-research --no-instances

Complete Example

A bug report template with all features:

---
type: template
template-for: task
description: Bug report with reproduction steps
defaults:
  status: backlog
  priority: high
prompt-fields:
  - deadline
  - milestone
---

## Description

[Describe the bug]

## Steps to Reproduce

1.
2.
3.

## Expected Behavior

## Actual Behavior

## Environment

- OS:
- Version:

See Also

• Templates overview
• bwrb template command