Skip to main content

Templates

LeanSpec provides customizable templates to match your workflow and team structure.

Overview​

Templates are complete working models that include:

  • Spec structure and examples
  • AGENTS.md for AI agent integration
  • Supporting files (CONTRIBUTING.md, checklists, etc.)
  • Project-specific configuration

Available Templates​

Standard (Default)​

Recommended for most projects - single-file specs with AGENTS.md.

Best for: Solo developers, small teams, simple to moderately complex specs

Includes:

  • Status, tags, priority fields
  • AGENTS.md for AI integration
  • All sections in single README.md file
  • Guidance for when to split into sub-specs

Example frontmatter:

---
status: planned
created: 2025-11-02
tags: [api, feature]
priority: high
---

Sections:

  • Overview
  • Design
  • Plan
  • Test
  • Notes

Detailed​

For complex specs with lots of content - uses sub-spec structure.

Best for: Large features, architectural changes, specs with >3,500 tokens

Includes:

  • Same metadata as standard
  • README.md as overview/navigation
  • Separate sub-spec files (DESIGN.md, PLAN.md, TEST.md)
  • Demonstrates real-world sub-spec pattern
  • Helps manage token limits for AI context

Example frontmatter:

---
status: planned
created: 2025-11-02
tags: [architecture, refactor]
priority: high
---

Structure:

specs/NNN-feature-name/
├── README.md      # Overview + navigation
├── DESIGN.md      # Design details
├── PLAN.md        # Implementation plan
└── TEST.md        # Testing strategy

Usage:

lean-spec init --template detailed

Choosing a Template​

Run lean-spec init and choose "Choose a template":

lean-spec init
? How would you like to set up?
  ❯ Quick start (recommended)
    Choose a template

? Which template would you like to use?
  ❯ standard - Recommended - single-file specs with AGENTS.md
    detailed - Complex specs with sub-spec structure (DESIGN, PLAN, TEST)

Custom Templates​

You can create your own templates in .lean-spec/templates/.

Single-File Templates​

For simple, consistent spec structures:

  1. Create template file:
mkdir -p .lean-spec/templates
touch .lean-spec/templates/my-template.md
  1. Edit template with placeholders:
---
status: planned
created: {date}
---

# {name}

**Team**: {team}
**Author**: {author}

## Overview

[Your custom sections...]
  1. Register in .lean-spec/config.json:
{
  "template": "my-template.md",
  "templates": {
    "default": "spec-template.md",
    "my-template": "my-template.md"
  }
}

Or use CLI:

lean-spec templates add my-template my-template.md

Directory-Based Templates (Multi-File)​

For complex specs that need multiple files (like DESIGN.md, PLAN.md, TEST.md):

  1. Create template directory:
mkdir -p .lean-spec/templates/api-spec
  1. Create the main template (README.md is required):
touch .lean-spec/templates/api-spec/README.md
touch .lean-spec/templates/api-spec/ENDPOINTS.md
touch .lean-spec/templates/api-spec/SCHEMAS.md
  1. Register the directory:
{
  "templates": {
    "default": "spec-template.md",
    "api": "api-spec"
  }
}

Or use CLI:

lean-spec templates add api api-spec
  1. Use the template:
lean-spec create my-api --template=api
# Creates: specs/NNN-my-api/
#   ├── README.md
#   ├── ENDPOINTS.md
#   └── SCHEMAS.md

When using a directory template, all .md files are copied to the new spec folder.

Available Variables​

  • {name} - Spec name
  • {date} - Creation date (ISO format)
  • {project_name} - From package.json
  • {author} - From git config user.name
  • {git_user} - Git username
  • {git_email} - Git email
  • {git_repo} - Repository name

Add custom variables in config:

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

Template Structure​

A complete template includes:

1. Frontmatter​

---
status: planned
created: {date}
tags: []
priority: medium
---

2. Visual Badges​

> **Status**: 📅 Planned · **Created**: {date}

3. Content Sections​

## Overview
## Goal
## Key Scenarios
## Acceptance Criteria
## Technical Approach
## Non-Goals

Customize sections to fit your needs.

Switching Templates​

To change templates mid-project:

  1. Update .lean-spec/config.json:
{
  "template": "new-template.md"
}

  1. New specs will use the new template

  2. Existing specs remain unchanged (update manually if needed)

Best Practices​

Start Simple

Begin with the standard template. Use detailed template only when you have specs with >3,500 tokens or very complex features.

Iterate on Templates

Refine your templates based on what actually gets used. Remove unused sections.

Keep Sections Optional

Not every spec needs every section. Use what adds value, skip what doesn't.

Share Templates

Export your .lean-spec/templates/ directory to share with other teams or projects.

Next: Learn about Frontmatter fields or explore Custom Fields.