This document describes the fest template system, including variable reference, template creation, resolution order, and YAML frontmatter format.
Variables are accessed using Go template syntax {{ .VariableName }}.
| Variable | Type | Description | Example |
|---|---|---|---|
{{.FestivalName}} |
string | Festival name | api-refactor |
{{.FestivalGoal}} |
string | Festival goal | Modernize API layer |
{{.FestivalTags}} |
[]string | Festival tags | ["api", "backend"] |
{{.FestivalDescription}} |
string | Extended description |
| Variable | Type | Description | Example |
|---|---|---|---|
{{.PhaseNumber}} |
int | Phase number | 1 |
{{.PhaseName}} |
string | Phase name | PLANNING |
{{.PhaseID}} |
string | Formatted ID | 001_PLANNING |
{{.PhaseType}} |
string | Phase type | planning, implementation |
{{.PhaseStructure}} |
string | Structure type | freeform, structured |
{{.PhaseObjective}} |
string | Phase objective |
| Variable | Type | Description | Example |
|---|---|---|---|
{{.SequenceNumber}} |
int | Sequence number | 1 |
{{.SequenceName}} |
string | Sequence name | requirements |
{{.SequenceID}} |
string | Formatted ID | 01_requirements |
{{.SequenceObjective}} |
string | Sequence objective | |
{{.SequenceDependencies}} |
[]string | Dependencies |
| Variable | Type | Description | Example |
|---|---|---|---|
{{.TaskNumber}} |
int | Task number | 1 |
{{.TaskName}} |
string | Task name | user_research |
{{.TaskID}} |
string | Formatted ID | 01_user_research.md |
{{.TaskObjective}} |
string | Task objective | |
{{.TaskDeliverables}} |
[]string | Task deliverables | |
{{.TaskParallel}} |
bool | Can run in parallel | true |
{{.TaskDependencies}} |
[]string | Task dependencies |
| Variable | Type | Description | Example |
|---|---|---|---|
{{.CurrentLevel}} |
string | Current hierarchy level | festival, phase, sequence, task |
{{.ParentPhaseID}} |
string | Parent phase ID | 001_PLANNING |
{{.ParentSequenceID}} |
string | Parent sequence ID | 01_requirements |
{{.FullPath}} |
string | Full relative path | 001_PLANNING/01_requirements/01_task.md |
Custom variables can be passed via --vars-file and accessed through the {{.Custom}} map:
fest create festival --name test --vars-file vars.jsonvars.json:
{
"author": "Team A",
"priority": "high"
}Template access:
Author: {{.Custom.author}}
Priority: {{.Custom.priority}}
Templates can include YAML frontmatter to define metadata, IDs, and required variables.
---
template_id: MY_TEMPLATE
description: Template for API endpoints
required_variables:
- FestivalName
- PhaseName
optional_variables:
- PhaseObjective
aliases:
- api_template
- endpoint
---
# {{.FestivalName}} - {{.PhaseName}}
Content here...| Field | Type | Description |
|---|---|---|
template_id |
string | Primary template identifier |
id |
string | Alternative to template_id |
aliases |
[]string | Alternative names for lookup |
template_version |
string | Template version |
description |
string | Template description |
required_variables |
[]string | Variables that must be provided |
optional_variables |
[]string | Variables that may be omitted |
Templates can be referenced by:
template_idfieldidfield (fallback)- Any value in
aliasesarray
# All of these work if configured in frontmatter
fest apply --template-id MY_TEMPLATE --to output.md
fest apply --template-id api_template --to output.md
fest apply --template-id endpoint --to output.mdWhen rendering templates, fest searches in this order:
Templates are indexed by ID/alias from the .festival/templates/ directory:
.festival/
└── templates/
├── TASK_TEMPLATE.md # template_id: TASK
├── PHASE_GOAL_TEMPLATE.md # template_id: PHASE_GOAL
└── SEQUENCE_GOAL_TEMPLATE.md # template_id: SEQUENCE_GOAL
If catalog lookup fails, fest tries the direct file path:
// Internal resolution logic
content, err := m.RenderWithFallback(catalog, "PHASE_GOAL",
filepath.Join(tmplRoot, "PHASE_GOAL_TEMPLATE.md"), ctx)If the file exists but contains no {{ markers, it's copied as-is without rendering.
Create a .md file in .festival/templates/:
---
template_id: API_TASK
description: Template for API development tasks
required_variables:
- TaskName
- TaskNumber
- SequenceName
aliases:
- api
- rest_task
---
# Task: {{.TaskName}}
## Objective
[FILL: Describe the API task objective]
## Context
- **Sequence**: {{.SequenceID}}
- **Task**: {{.TaskID}}
## Implementation Steps
1. [FILL: First step]
2. [FILL: Second step]
3. [FILL: Third step]
## Definition of Done
- [ ] [FILL: Completion criteria]# By ID
fest apply --template-id API_TASK --to ./01_api/01_design.md
# By alias
fest apply --template-id api --to ./01_api/01_design.md
# With variables file
fest apply --template-id API_TASK --to ./output.md --vars-file vars.jsonFest includes these built-in templates:
| ID | File | Description |
|---|---|---|
FESTIVAL_OVERVIEW |
FESTIVAL_OVERVIEW_TEMPLATE.md |
Festival overview document |
FESTIVAL_RULES |
FESTIVAL_RULES_TEMPLATE.md |
Festival rules and guidelines |
TODO |
TODO_TEMPLATE.md |
Progress tracking TODO |
| ID | File | Description |
|---|---|---|
PHASE_GOAL |
PHASE_GOAL_TEMPLATE.md |
Phase goal document |
| ID | File | Description |
|---|---|---|
SEQUENCE_GOAL |
SEQUENCE_GOAL_TEMPLATE.md |
Sequence goal document |
| ID | File | Description |
|---|---|---|
TASK |
TASK_TEMPLATE.md |
Generic task template |
Templates use these marker patterns for content that needs filling:
[FILL: description]
Indicates content that must be replaced by the user.
{{.VariableName}}
Go template syntax variables that are automatically rendered.
The fest validate command checks for unfilled markers:
fest validate templates # Check for [FILL:] markers
fest validate # Includes template validation{{if .PhaseObjective}}
## Objective
{{.PhaseObjective}}
{{end}}
## Dependencies
{{range .SequenceDependencies}}
- {{.}}
{{end}}
Priority: {{if .Custom.priority}}{{.Custom.priority}}{{else}}medium{{end}}
# {{.PhaseName | upper}}
Note: Go template functions must be registered with the renderer.
# Create template
vim .festival/templates/MY_TEMPLATE.md
# Test with fest apply
fest apply --template-path ./.festival/templates/MY_TEMPLATE.md \
--to ./test_output.md \
--vars-file test_vars.json
# Check output
cat test_output.mdAdd template_id frontmatter for catalog indexing:
---
template_id: MY_TEMPLATE
aliases:
- my
- custom
---# Check for unfilled markers in generated files
fest validate templatesTemplates in .festival/templates/ are shared across the festival. For project-wide templates, use configuration repositories:
fest config add https://github.com/org/fest-templates// RenderFile renders a template file with context
func (m *Manager) RenderFile(templatePath string, ctx *Context) (string, error)
// RenderByID renders by template ID from catalog
func (m *Manager) RenderByID(catalog *Catalog, id string, ctx *Context) (string, error)
// RenderWithFallback tries catalog, then falls back to file path
func (m *Manager) RenderWithFallback(catalog *Catalog, id, fallbackPath string, ctx *Context) (string, error)
// RenderFileOrCopy renders or copies based on content
func (m *Manager) RenderFileOrCopy(templatePath string, ctx *Context) (string, error)// Create context and set variables
ctx := template.NewContext()
ctx.SetFestival("my-fest", "Goal here", []string{"tag1"})
ctx.SetPhase(1, "PLANNING", "planning")
ctx.SetSequence(1, "requirements")
ctx.SetTask(1, "gather_specs")
// Add custom variables
ctx.Custom["author"] = "Team A"// Load catalog from template directory
catalog, err := template.LoadCatalog(".festival/templates")
// Resolve template ID to path
path, ok := catalog.Resolve("TASK")