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​

Minimal​

Bare essentials - just folder structure, no extras.

Best for: Quick prototypes, personal projects, when you want absolute simplicity

Includes:

  • Minimal frontmatter (status, created only)
  • Lightweight structure
  • No AGENTS.md or extra files
  • Focus on speed

Example frontmatter:

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

Sections:

  • Goal
  • Key Points
  • Non-Goals
  • Notes

Standard​

Recommended for most projects - includes AGENTS.md and solid structure.

Best for: Solo developers, small teams (2-5 people), most projects

Includes:

  • Status, tags, priority fields
  • AGENTS.md for AI integration
  • Overview, Design, Plan, Test sections
  • Sub-spec guidance for complex features

Example frontmatter:

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

Sections:

  • Overview
  • Design
  • Plan (with sub-spec guidance)
  • Test
  • Notes

Enterprise​

Governance with approvals and compliance.

Best for: Large organizations, regulated industries, teams >10 people

Includes:

  • Full metadata (assignee, reviewer, issue, epic, related)
  • Research and Dependencies sections
  • Security & Compliance checklist
  • Risk assessment
  • Rollout planning

Example frontmatter:

---
status: planned
created: 2025-11-02
tags: [security, compliance]
priority: critical
assignee: alice
reviewer: bob
issue: JIRA-1234
epic: security-hardening
related: [042, 043]
---

Sections:

  • Overview
  • Research
  • Design (with Dependencies, Security & Compliance)
  • Plan (with owners)
  • Test
  • Risks
  • Rollout
  • Notes

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
    Customize everything

? Which template would you like to use?
  ❯ minimal - Just folder structure, no extras
    standard - Recommended - includes AGENTS.md
    enterprise - Governance with approvals and compliance

Custom Templates​

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

Creating a Custom Template​

  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. Configure in .lean-spec/config.json:
{
  "template": "my-template.md"
}

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 minimal or standard template. Add complexity only when you feel the pain of not having it.

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.