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"
  }
}

Documentation Links

{
  "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.