Templating

Fragments and prompts support Mustache templating for dynamic content.

Basic Syntax

Use double braces for variable substitution:

fragments:
  project-info:
    content: |
      # {{PROJECT_NAME}} Guidelines
      This project uses {{LANGUAGE}}.
      Team: {{TEAM}}

Built-in Variables

These variables are always available:

Variable	Description
SCM_ROOT	Project root directory (parent of .scm)
SCM_DIR	Full path to .scm directory

fragments:
  paths:
    content: |
      Project root: {{SCM_ROOT}}
      Config location: {{SCM_DIR}}

Defining Variables

In Profiles

# .scm/profiles/developer.yaml
variables:
  PROJECT_NAME: "my-app"
  LANGUAGE: "Go"
  LOG_LEVEL: "debug"
  TEAM: "backend"

In Config

# .scm/config.yaml
profiles:
  quick:
    variables:
      MODE: "fast"

Variable Inheritance

When using parent profiles, variables inherit and can be overridden:

# base.yaml
variables:
  LANGUAGE: "Python"
  FRAMEWORK: "FastAPI"
  LOG_LEVEL: "info"

# child.yaml
parents:
  - base
variables:
  PROJECT_NAME: "my-app"    # New variable
  FRAMEWORK: "Django"       # Override parent
  # LANGUAGE and LOG_LEVEL inherited from base

Mustache Features

Simple Variables

Hello, {{name}}!

Sections (Conditionals/Lists)

variables:
  FEATURES:
    - auth
    - logging
    - metrics
  DEBUG: true

{{#DEBUG}}
Debug mode is enabled.
{{/DEBUG}}

Features:
{{#FEATURES}}
- {{.}}
{{/FEATURES}}

Inverted Sections (Falsy Check)

{{^PRODUCTION}}
This is not production - be careful!
{{/PRODUCTION}}

Raw Output (Unescaped)

{{{HTML_CONTENT}}}

Comments

{{! This comment won't appear in output }}

Declaring Used Variables

Document which variables a fragment uses:

fragments:
  database-config:
    variables: [DATABASE_URL, DB_POOL_SIZE]
    content: |
      Connect to: {{DATABASE_URL}}
      Pool size: {{DB_POOL_SIZE}}

This helps users know which variables to define in their profiles.

Error Handling

• Undefined variables: Logged as warnings, rendered as empty
• Render failures: Original content returned unchanged
• All variables are strings: Converted to map[string]interface{}

Examples

Project Context

# Profile
variables:
  PROJECT: "api-server"
  LANGUAGE: "Go"
  VERSION: "1.0"

# Fragment
content: |
  # {{PROJECT}} ({{VERSION}})

  This {{LANGUAGE}} project follows these standards:
  - Use gofmt for formatting
  - Write tests for all public functions

Conditional Content

# Profile
variables:
  USE_DOCKER: true
  CI_PLATFORM: "github"

# Fragment
content: |
  ## Deployment

  {{#USE_DOCKER}}
  Build with: docker build -t app .
  {{/USE_DOCKER}}

  {{#CI_PLATFORM}}
  CI runs on: {{CI_PLATFORM}}
  {{/CI_PLATFORM}}

List Iteration

# Profile
variables:
  REVIEWERS:
    - Alice
    - Bob
    - Charlie

# Fragment
content: |
  ## Code Review

  Reviewers:
  {{#REVIEWERS}}
  - {{.}}
  {{/REVIEWERS}}

Best Practices

1. Use descriptive names - PROJECT_NAME not pn
2. Document required variables - Use variables: field in fragments
3. Provide defaults in profiles - Avoid undefined variable warnings
4. Keep templates simple - Complex logic belongs in code
5. Use sections for optionals - {{#VAR}}...{{/VAR}} handles missing gracefully