Skip to main content

Getting Started

This guide will help you install LeanSpec and set up your first project.

Installation​

LeanSpec can be installed globally or as a project dependency.

Global Installation​

npm install -g lean-spec

This makes the lean-spec command available system-wide.

Project Installation​

# Using npm
npm install -D lean-spec

# Using pnpm
pnpm add -D lean-spec

# Using yarn
yarn add -D lean-spec

For project installation, you'll need to use npx lean-spec or add scripts to your package.json.

Verify Installation​

Check that LeanSpec is installed correctly:

lean-spec --version

You should see the version number (e.g., 0.1.0).

Initialize Your Project​

Navigate to your project directory and run:

lean-spec init

This interactive command will guide you through three setup paths:

Zero configuration using standard template. Gets you up and running in seconds.

? How would you like to set up?
  ❯ Quick start (recommended)
    Choose a template
    Customize everything

This creates:

  • .lean-spec/config.json with minimal configuration
  • specs/ directory for your specs
  • AGENTS.md with AI agent integration guidance (if not present)

2. Choose a Template​

Select from pre-configured templates for different team sizes and workflows:

  • minimal: Just folder structure, no extras
  • standard: Recommended - includes AGENTS.md and examples (default)
  • enterprise: Governance with approvals and compliance

Each template includes:

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

3. Customize Everything​

Full control over configuration (coming soon).

Project Structure​

After initialization, your project will have:

your-project/
├── .lean-spec/
│   ├── config.json         # LeanSpec configuration
│   └── templates/          # Custom spec templates (optional)
│       └── spec-template.md
├── specs/                  # All your specs live here
│   ├── 001-first-feature/  # Flat structure with global numbering
│   ├── 002-second-feature/
│   └── archived/           # Completed specs
├── AGENTS.md              # AI agent integration guidance
└── ... (your project files)

Note: Default structure is flat with global numbering (001-name/, 002-name/). For date-based grouping, configure the structure.pattern in .lean-spec/config.json.

Integrating with Existing Projects​

If you already have AGENTS.md, .cursorrules, or other system prompts, lean-spec init will detect them and offer three options:

  1. Merge - Appends LeanSpec guidance to your existing AGENTS.md (preserves your content)
  2. Backup - Saves existing files as .backup and creates fresh ones
  3. Skip - Only adds .lean-spec config and specs/ directory, keeps your files untouched

This makes it easy to adopt LeanSpec incrementally without disrupting your existing AI agent setup.

Configuration​

The .lean-spec/config.json file controls LeanSpec behavior:

{
  "template": "spec-template.md",
  "specsDir": "specs",
  "structure": {
    "pattern": "flat",
    "prefix": "",
    "dateFormat": "YYYYMMDD",
    "sequenceDigits": 3,
    "defaultFile": "README.md"
  },
  "frontmatter": {
    "required": ["status", "created"],
    "optional": ["tags", "priority", "assignee", "reviewer"],
    "custom": {}
  },
  "variables": {}
}

You can customize this to fit your workflow. See Configuration Reference for details.

Create Your First Spec​

Now you're ready to create your first spec:

lean-spec create my-feature

This creates:

  • specs/001-my-feature/ folder (flat structure with global numbering)
  • README.md inside with your template content
  • Frontmatter with default metadata

Edit the README.md file to document your feature.

Basic Commands​

Here are the essential commands to get you started:

# Create a spec
lean-spec create feature-name

# List all specs
lean-spec list

# View a spec
lean-spec view 001

# Update spec metadata (by number or path)
lean-spec update 001 --status=in-progress
lean-spec update specs/001-my-feature --status=in-progress

# Archive completed specs
lean-spec archive 001

For a complete command reference, see CLI Commands.

AI Integration (Optional)​

LeanSpec works great with AI coding agents. When you ran lean-spec init, it created AGENTS.md with instructions for AI agents.

Quick AI Setup​

For AI to access specs through MCP (recommended):

  1. Install LeanSpec globally (if not already):

    npm install -g lean-spec

  2. Configure your AI tool:

    VS Code (GitHub Copilot) - Add to settings.json:

    {
      "github.copilot.chat.mcp.servers": {
        "lean-spec": {
          "command": "npx",
          "args": ["-y", "lean-spec", "mcp"],
          "cwd": "${workspaceFolder}"
        }
      }
    }

    Claude Desktop - Add to claude_desktop_config.json:

    {
      "mcpServers": {
        "lean-spec": {
          "command": "npx",
          "args": ["-y", "lean-spec", "mcp"],
          "cwd": "/absolute/path/to/your/project"
        }
      }
    }

  3. Test it:

    Ask your AI: "List all specs in this project"

Without MCP (basic):

  • AI can still read specs from files
  • Reference AGENTS.md in your prompts: "Follow instructions in AGENTS.md"
  • Manually point AI to spec files when needed

Learn more: MCP Integration for detailed setup and benefits.

What's Next?​

Now that you have LeanSpec set up, you can:

Learn the Fundamentals:

Start Using LeanSpec:

AI Integration:

Need Help?​