Skip to main content

Getting Started

This guide will help you set up LeanSpec and adopt the SDD workflow for your project. It takes about 5 minutes.

Prerequisites

Installation​

Install LeanSpec globally using npm:

npm install -g lean-spec

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

Initialize Your Project​

Navigate to your project directory and run:

lean-spec init -y

After initialization, your project will have:

your-project/
├── .lean-spec/        # LeanSpec configuration
├── specs/             # All your specs live here
├── AGENTS.md          # System prompts for AI agents
└── ... (your project files)

Create Your First Spec​

In your AI tool, prompt:

Create a new spec for the feature "my-feature" following these requirements:
- [Requirement 1]
- [Requirement 2]
- ...

Or simply:

Create a new spec for "my-feature".

The AI will use the CLI or MCP (if configured) to create and populate the spec.

This creates:

  • specs/001-my-feature/ folder (flat structure with sequential numbering)
  • README.md with template content and frontmatter metadata
  • Spec details filled out by AI (no manual editing needed)

The spec content looks like this:

specs/001-my-feature/README.md
---
status: planned
created: '2025-11-02'
priority: medium
---

# My Feature

> **Status**: 📅 Planned · **Priority**: Medium · **Created**: 2025-11-02

(... spec details filled out by AI ...)

Implement the Spec​

Once the spec is created, review it and implement the feature according to the spec details.

In your AI tool, ask:

Implement the feature "my-feature".

Or simply:

Implement spec 1.

The AI will read the spec and start implementing based on the requirements.

In a typical agentic workflow, the AI will:

  1. Read the spec details
  2. Analyze the codebase
  3. Generate code changes to implement the feature
  4. Summarize changes and document progress in the spec
Recommended AI Models

While not required, we strongly recommend using advanced LLMs like Claude Sonnet 4.5, GPT-5.1, or Gemini 3 for the best results with LeanSpec.

After Implementation​

Once the AI completes implementation, you can:

  • Review: Review the progress (reported by AI) and test the feature
  • Continue: If incomplete, start a new chat session and ask the AI to continue
  • Feedback: If unsatisfied with the implementation, provide feedback to the AI for improvements

What's Next?​

Now that you have LeanSpec set up, you can:

Try the Tutorials:

Learn the Fundamentals:

Start Using LeanSpec:

AI Integration:

Need Help?​