Configuration

Complete reference for .lean-spec/config.json.

Configuration File

LeanSpec configuration is stored in .lean-spec/config.json in your project root.

Default Configuration

{
  "template": "spec-template.md",
  "templates": {
    "default": "spec-template.md"
  },
  "specsDir": "specs",
  "structure": {
    "pattern": "flat",
    "prefix": "",
    "dateFormat": "YYYYMMDD",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "features": {
    "aiAgents": true,
    "examples": true
  }
}

Configuration Options

template

Primary template file to use for new specs.

Type: string
Default: "spec-template.md"

Path to the template file within .lean-spec/templates/ directory.

{
  "template": "my-custom-template.md"
}

templates

Map of named templates for different spec types.

Type: object
Default: { "default": "spec-template.md" }

Allows you to define multiple templates that users can select from during lean-spec create or lean-spec init.

{
  "templates": {
    "default": "spec-template.md",
    "minimal": "minimal-template.md",
    "feature": "feature-template.md",
    "bug": "bug-template.md"
  }
}

specsDir

Directory where active specs are stored.

Type: string
Default: "specs"

{
  "specsDir": "specifications"
}

autoCheck

Enable/disable automatic sequence conflict checking.

Type: boolean
Default: true

When enabled, LeanSpec automatically checks for sequence number conflicts during spec creation and warns if duplicates exist.

{
  "autoCheck": false
}

structure

Configuration for spec folder structure and naming.

Type: object

structure.pattern

Folder structure pattern.

Type: string
Values: "flat" | "custom" | legacy pattern string
Default: "flat"

• "flat": Specs are organized in a flat structure (e.g., specs/001-name/)
• "custom": Custom grouping using groupExtractor field

{
  "structure": {
    "pattern": "flat"
  }
}

structure.prefix

Prefix for spec folders in flat pattern.

Type: string (optional)
Default: "" (empty, uses global sequence numbers)

Common values:

• "" - Global numbering (e.g., 001-name/, 002-name/)
• "{YYYYMMDD}-" - Date-prefixed (e.g., 20251107-001-name/)
• "spec-" - Custom prefix (e.g., spec-001-name/)

{
  "structure": {
    "pattern": "flat",
    "prefix": "{YYYYMMDD}-"
  }
}

structure.dateFormat

Date format for date-based patterns.

Type: string
Default: "YYYYMMDD"

Supported formats: "YYYYMMDD", "YYYY-MM-DD", "YYYY-MM", "YYYY/MM", "YYYY", "MM"

{
  "structure": {
    "dateFormat": "YYYY-MM-DD"
  }
}

structure.sequenceDigits

Number of digits for sequence numbers.

Type: number
Default: 3

• 3 → 001, 002, 003
• 4 → 0001, 0002, 0003

{
  "structure": {
    "sequenceDigits": 4
  }
}

structure.defaultFile

Default filename within each spec folder.

Type: string
Default: "README.md"

{
  "structure": {
    "defaultFile": "spec.md"
  }
}

structure.groupExtractor

Field extractor for custom grouping pattern.

Type: string (optional)
Example: "{YYYYMMDD}" or "milestone-{milestone}"

Used when pattern is "custom" to dynamically group specs by frontmatter fields.

{
  "structure": {
    "pattern": "custom",
    "groupExtractor": "milestone-{milestone}"
  }
}

structure.groupFallback

Fallback folder when groupExtractor field is missing.

Type: string (optional)

Only used for non-date extractors. When the frontmatter field is missing, specs are placed in this fallback folder.

{
  "structure": {
    "pattern": "custom",
    "groupExtractor": "milestone-{milestone}",
    "groupFallback": "unassigned"
  }
}

features

Feature flags for optional functionality.

Type: object

{
  "features": {
    "aiAgents": true,
    "examples": true,
    "collaboration": false,
    "compliance": false,
    "approvals": false,
    "apiDocs": false
  }
}

features.aiAgents

Enable AI agent integration (creates AGENTS.md file).

Type: boolean
Default: true

features.examples

Enable example content in templates.

Type: boolean
Default: true

features.collaboration

Enable collaboration features (assignee, reviewer fields).

Type: boolean
Default: false

features.compliance

Enable compliance tracking fields.

Type: boolean
Default: false

features.approvals

Enable approval workflow fields.

Type: boolean
Default: false

features.apiDocs

Enable API documentation sections in templates.

Type: boolean
Default: false

frontmatter

Configuration for spec frontmatter fields validation.

Type: object (optional)

frontmatter.required

Fields that must be present in every spec.

Type: string[] (optional)
Default: ["status", "created"]

{
  "frontmatter": {
    "required": ["status", "created", "priority"]
  }
}

frontmatter.optional

Fields that may be present but aren't required.

Type: string[] (optional)
Default: ["tags", "priority"]

{
  "frontmatter": {
    "optional": ["tags", "priority", "assignee"]
  }
}

frontmatter.custom

Custom fields with type definitions.

Type: object (optional)
Default: {}

Supported types: "string", "number", "boolean", "array"

{
  "frontmatter": {
    "custom": {
      "epic": "string",
      "sprint": "number",
      "needs_review": "boolean",
      "teams": "array"
    }
  }
}

variables

Custom variables for template substitution.

Type: object (optional)
Default: {}

Variables can be used in templates using {variable_name} syntax.

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

Complete Example

{
  "template": "enterprise-template.md",
  "templates": {
    "default": "spec-template.md",
    "minimal": "minimal-template.md",
    "feature": "feature-template.md"
  },
  "specsDir": "docs/specs",
  "autoCheck": true,
  "structure": {
    "pattern": "flat",
    "prefix": "{YYYYMMDD}-",
    "dateFormat": "YYYYMMDD",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "features": {
    "aiAgents": true,
    "examples": true,
    "collaboration": true
  },
  "frontmatter": {
    "required": ["status", "created", "assignee"],
    "optional": ["tags", "priority", "reviewer"],
    "custom": {
      "epic": "string",
      "issue": "string",
      "sprint": "number",
      "estimate": "string",
      "needs_security_review": "boolean",
      "teams": "array"
    }
  },
  "variables": {
    "company": "Acme Corp",
    "team": "Platform Engineering",
    "default_reviewer": "alice",
    "docs_url": "https://docs.acme.com",
    "compliance_email": "compliance@acme.com"
  }
}

Validation

LeanSpec validates configuration on load:

• Required structure fields must be valid
• Custom field types must be valid (string, number, boolean, array)
• Template files must exist in .lean-spec/templates/
• Spec directory is created if missing

Invalid configuration will show an error with details.

Migration

When updating configuration:

1. Edit .lean-spec/config.json
2. New specs will use new configuration
3. Existing specs are not automatically updated
4. Manually update existing specs if needed

---

Next: Check the CLI Reference or explore Frontmatter Fields.