Skip to main content

Variables

Template variables allow you to generate dynamic content in your specs.

Overview​

Variables are placeholders in your spec templates that get replaced with actual values when you create a spec.

Example:

# \{name\}

Created by \{author\} on \{date\}

Becomes:

# user-authentication

Created by John Doe on 2025-11-02

Built-in Variables​

These variables are available automatically:

{name}​

The spec name provided to lean-spec create.

lean-spec create user-authentication

Results in:

# user-authentication

{date}​

Current date in ISO 8601 format (YYYY-MM-DD).

created: \{date\}

Results in:

created: 2025-11-02

{project_name}​

Project name from package.json.

**Project**: \{project_name\}

{author}​

User's name from git config (user.name).

**Author**: \{author\}

{git_user}​

Git username from git config.

**Username**: \{git_user\}

{git_email}​

Git email from git config (user.email).

**Contact**: \{git_email\}

{git_repo}​

Repository name from git remote URL.

**Repository**: \{git_repo\}

Custom Variables​

Define your own variables in .lean-spec/config.json:

{
  "variables": {
    "team": "Platform Engineering",
    "company": "Acme Corp",
    "default_reviewer": "alice"
  }
}

Use in templates:

**Team**: \{team\}
**Company**: \{company\}
**Reviewer**: \{default_reviewer\}

Using Variables in Templates​

1. Create or Edit Template​

.lean-spec/templates/spec-template.md:

---
status: planned
created: \{date\}
---

# \{name\}

**Team**: \{team\}  
**Author**: \{author\}  
**Created**: \{date\}

## Overview

[What is \{name\} and why are we building it?]

## Contact

Questions? Reach out to \{default_reviewer\} or \{git_email\}

2. Configure Variables​

.lean-spec/config.json:

{
  "template": "spec-template.md",
  "specsDir": "specs",
  "variables": {
    "team": "Platform Engineering",
    "default_reviewer": "alice"
  }
}

3. Create Spec​

lean-spec create user-authentication

4. Result​

All variables are automatically replaced:

---
status: planned
created: 2025-11-02
---

# user-authentication

**Team**: Platform Engineering  
**Author**: John Doe  
**Created**: 2025-11-02

## Overview

[What is user-authentication and why are we building it?]

## Contact

Questions? Reach out to alice or john@example.com

Common Patterns​

Team Attribution​

{
  "variables": {
    "team": "Backend Team",
    "team_lead": "Alice",
    "team_email": "backend@company.com"
  }
}
{
  "variables": {
    "docs_url": "https://docs.company.com",
    "wiki_url": "https://wiki.company.com",
    "api_docs": "https://api.company.com/docs"
  }
}

Company Information​

{
  "variables": {
    "company": "Acme Corp",
    "legal_entity": "Acme Corporation Inc.",
    "compliance_contact": "compliance@acme.com"
  }
}

Project Metadata​

{
  "variables": {
    "project_name": "MyApp",
    "project_version": "2.0",
    "support_email": "support@myapp.com"
  }
}

Best Practices​

Use for Static Values

Variables are best for information that rarely changes (team names, URLs, contacts).

Keep Names Descriptive

Use clear variable names: default_reviewer not dr, docs_url not url1.

Don't Overuse

Not everything needs to be a variable. Use them where they add value.

Document Variables

Add comments in config explaining what each variable is for.

Limitations​

  • Variables are resolved at creation time only
  • No dynamic or computed variables
  • No conditional logic
  • No loops or iterations
  • Cannot reference other variables

Troubleshooting​

Variable Not Replaced​

Problem: \{my_var\} appears literally in spec.

Causes:

  1. Variable not defined in config
  2. Typo in variable name
  3. Config file not saved

Solution: Check .lean-spec/config.json has the variable defined.

Wrong Value​

Problem: Variable has unexpected value.

Causes:

  1. Git config not set (for git_* variables)
  2. package.json missing (for project_name)
  3. Stale config cache

Solution: Check source of built-in variables, restart after config changes.

Next: Learn about Templates or explore the Configuration Reference.