Getting Started with LDF

December 29, 2025 · View on GitHub

LDF (LLM Development Framework) is a spec-driven development methodology that ensures quality through structured requirements, guardrails, and multi-agent validation.

Choose Your Learning Path

New to programming or command line? → Start with Installation Guides - Complete step-by-step setup for your platform

Familiar with terminal basics? → Continue below for standard installation, or jump to Your First Spec Tutorial

Experienced developer? → Skip to 5-Minute Quickstart for rapid setup

Prerequisites

  • Python 3.10+ (for CLI and MCP servers)
  • Node.js 18+ (optional, for TypeScript projects)
  • VS Code (optional, for extension)

Installation

1. Install LDF CLI

pip install llm-ldf

Installation Extras

LDF has optional features that require additional dependencies:

ExtraInstall CommandEnables
mcppip install llm-ldf[mcp]MCP servers for AI assistants (spec_inspector, coverage_reporter)
automationpip install llm-ldf[automation]API-based audits with ChatGPT or Gemini
s3pip install llm-ldf[s3]S3 coverage upload (ldf coverage --upload s3://...)

Install multiple extras:

pip install llm-ldf[mcp,automation]

Verify installation:

ldf --version

2. Initialize a Project

The easiest way to get started is with the interactive setup:

ldf init

The CLI guides you through:

  1. Project path - Where to create your project (default: ./my-project)
  2. Preset selection - Choose guardrails for your domain:
    • saas - Multi-tenant apps with RLS, tenant isolation, billing
    • fintech - Financial apps with ledger accuracy, compliance
    • healthcare - HIPAA-compliant with PHI handling
    • api-only - Developer APIs with rate limits, versioning
    • custom - Core guardrails only
  3. Question packs - Core packs always included, optional packs pre-selected based on preset
  4. MCP servers - AI integration (spec_inspector, coverage_reporter)
  5. Pre-commit hooks - Optional validation on commits
$ ldf init

Enter project path: ./my-saas-app

Select guardrail preset:
❯ saas - Multi-tenant SaaS applications (+5 guardrails)
  fintech - Financial applications (+7 guardrails)
  healthcare - HIPAA-compliant (+6 guardrails)
  api-only - Pure API services (+4 guardrails)
  custom - Core guardrails only

Core packs (always included):
  ✓ security - Authentication, authorization, secrets
  ✓ testing - Coverage requirements, testing strategies
  ✓ api-design - REST patterns, versioning, errors
  ✓ data-model - Database schema, migrations

Select additional question packs: [space to toggle, enter to confirm]
  [x] billing - Payment processing, subscriptions
  [x] multi-tenancy - RLS, tenant isolation
  [ ] provisioning - Async jobs, queues
  [ ] webhooks - Event delivery, signatures

✓ Created .ldf/ directory structure
✓ Created AGENT.md

This creates:

my-saas-app/
├── .ldf/
│   ├── config.yaml          # Project configuration
│   ├── guardrails.yaml      # Active guardrails
│   ├── specs/               # Feature specifications
│   ├── answerpacks/         # Question-pack answers
│   ├── templates/           # Spec templates
│   └── macros/              # Enforcement macros
├── .agent/commands/         # Slash commands
└── AGENT.md                 # AI assistant instructions

Non-Interactive Setup

For CI/CD or scripting:

# Create project at specific path with preset
ldf init --path ./my-project --preset saas -y

# Use defaults for everything
ldf init -y

# Also install pre-commit hooks
ldf init --preset saas --hooks -y

Team Templates

Organizations can create reusable templates with pre-configured guardrails, question packs, and settings:

# Initialize from a team template
ldf init --from /path/to/team-template.zip

# Or from a directory
ldf init --from /path/to/team-template/

Templates can include:

  • Custom guardrails and presets
  • Pre-configured question packs
  • Project templates and macros
  • Team-specific settings

To create and share templates, see Template Workflow.

Smart Detection

ldf init automatically detects existing LDF projects and suggests appropriate actions:

# If LDF already initialized and current
$ ldf init
LDF is already initialized and up to date.

# If project needs update
$ ldf init
LDF project is outdated (0.9.0 -> 1.0.0).
Run 'ldf update' to update framework files.
Use --force to reinitialize anyway.

# Force reinitialize (overwrites all framework files)
ldf init --force

# Repair missing files without overwriting existing
ldf init --repair

Check Project Status

Use ldf status to see the current state of your LDF project:

ldf status

Output:

LDF Project Status
==================
State: CURRENT
Project version: 1.0.0
Installed version: 1.0.0

Setup Completeness:
  [X] config.yaml
  [X] guardrails.yaml
  [X] templates
  [X] macros
  [X] question-packs
  [X] AGENT.md
  [X] .agent/commands

LDF is up to date. No action needed.

For JSON output (useful in CI/CD):

ldf status --format json

Adding LDF to Existing Projects

If you have an existing codebase and want to add LDF, use the convert command to analyze your code and generate initial specs:

1. Analyze Your Codebase

ldf convert analyze

This scans your project and generates a prompt you can give to an AI assistant:

Codebase Analysis
========================================
Project: my-app
Languages: python, typescript
Frameworks: fastapi, react
Suggested Preset: saas

Generated Prompt:
----------------------------------------
# LDF Backwards Fill Analysis Request
...

2. Use AI to Generate Specs

Copy the generated prompt and paste it into Claude, ChatGPT, or another AI assistant. The AI will analyze your code and generate:

  • Answerpacks documenting existing design decisions
  • Spec files (requirements.md, design.md, tasks.md) for the existing system

Save the AI's response to a file (e.g., response.md).

3. Import the Results

# Preview what will be created
ldf convert import response.md --dry-run

# Import with custom spec name
ldf convert import response.md -n my-existing-system

# Import with default name (existing-system)
ldf convert import response.md

This creates files in:

  • .ldf/specs/{spec-name}/ - requirements.md, design.md, tasks.md
  • .ldf/answerpacks/{spec-name}/ - security.yaml, testing.yaml, etc.

4. Review and Refine

Review the generated files and refine as needed. The AI-generated content provides a starting point based on your existing code patterns.

Your First Spec

1. Create a Spec

ldf create-spec user-authentication

This creates:

.ldf/specs/user-authentication/
├── requirements.md      # User stories and acceptance criteria
├── design.md           # (created later) Architecture and components
└── tasks.md            # (created later) Implementation checklist

2. Write Requirements

Open .ldf/specs/user-authentication/requirements.md and define:

# user-authentication - Requirements

## Overview

User authentication for the application using email/password with optional MFA.

## User Stories

### US-1: Email/Password Login

**As a** registered user
**I want to** log in with my email and password
**So that** I can access my account

**Acceptance Criteria:**
- [ ] AC-1.1: User can enter email and password
- [ ] AC-1.2: Valid credentials grant access
- [ ] AC-1.3: Invalid credentials show error (no email enumeration)
- [ ] AC-1.4: Account locks after 5 failed attempts

## Question-Pack Answers

### Security
- Authentication: Email/password with bcrypt (cost 12)
- Session: JWT in HttpOnly cookie, 15min access / 7day refresh
- MFA: Optional TOTP via authenticator app

## Guardrail Coverage Matrix

| Guardrail | Requirements | Design | Tasks/Tests | Owner | Status |
|-----------|--------------|--------|-------------|-------|--------|
| 1. Testing Coverage | [US-1] | [TBD] | [TBD] | Alice | TODO |
| 2. Security Basics | [US-1] | [TBD] | [TBD] | Alice | TODO |
...

3. Validate with Lint

ldf lint user-authentication

The linter checks:

  • Question-pack answers exist
  • Guardrail coverage matrix is complete
  • No missing sections

4. Get External Review (Optional)

ldf audit --type spec-review --spec user-authentication

This generates an audit request you can send to ChatGPT or Gemini for review.

5. Create Design

Once requirements are approved, create design.md:

# user-authentication - Design

## Architecture Overview

┌─────────────┐ ┌──────────────┐ ┌────────────┐ │ Client │────▶│ Auth API │────▶│ Database │ └─────────────┘ └──────────────┘ └────────────┘ │ ▼ ┌──────────────┐ │ JWT Store │ └──────────────┘


## Components

### AuthService

**Purpose:** Handle authentication logic

**Interface:**
\`\`\`python
class AuthService:
    async def login(self, email: str, password: str) -> AuthResult
    async def logout(self, session_id: str) -> bool
    async def verify_mfa(self, user_id: str, code: str) -> bool
\`\`\`

## Data Model

### users Table

| Field | Type | Constraints |
|-------|------|-------------|
| id | UUID | PK |
| email | VARCHAR(255) | UNIQUE, NOT NULL |
| password_hash | VARCHAR(255) | NOT NULL |
| mfa_secret | VARCHAR(255) | NULL |
| failed_attempts | INT | DEFAULT 0 |
| locked_until | TIMESTAMP | NULL |

## Guardrail Mapping

| Guardrail | Implementation | Section |
|-----------|---------------|---------|
| 2. Security | bcrypt, JWT HttpOnly | AuthService |
...

6. Create Tasks

Finally, create tasks.md. LDF supports two task formats - use either consistently:

Checklist Format (Official Template):

# user-authentication - Tasks

## Phase 1: Setup

- [ ] **Task 1.1:** Create AuthService class
  - [ ] Create class structure
  - [ ] Add type hints
  - [ ] Write docstrings

- [ ] **Task 1.2:** Add users table migration
  - [ ] Create migration file
  - [ ] Define schema
  - [ ] Test up/down

## Phase 2: Core Implementation

- [ ] **Task 2.1:** Implement login endpoint
  - [ ] Validate input
  - [ ] Hash password comparison
  - [ ] Generate JWT

- [ ] **Task 2.2:** Add password validation
  - [ ] Minimum length check
  - [ ] Complexity requirements

Heading Format (Alternative):

# user-authentication - Tasks

## Phase 1: Setup

### Task 1.1: Create AuthService class
- [ ] Create class structure
- [ ] Add type hints
- [ ] Write docstrings

### Task 1.2: Add users table migration
- [ ] Create migration file
- [ ] Define schema

Key Requirements:

  • Heading format: "Task" keyword OPTIONAL, colon REQUIRED
  • Checklist format: "Task" keyword REQUIRED, colon REQUIRED
  • Task IDs: Use 1.1 (two-level) or 1.1.1 (subtask)

See Task Format Guide for all supported formats and details.

7. Implement

Now you can implement! Use ldf lint <spec-name> to validate your spec as you go.

IDE Integration

VS Code Extension

Install the LDF VS Code extension for:

  • Spec tree view with status indicators
  • Guardrail coverage visualization
  • Task progress tracking
  • Snippets for common patterns

MCP Servers for AI Assistants

Generate and configure MCP servers using the LDF CLI:

# Generate MCP configuration for your project
mkdir -p .agent && ldf mcp-config > .agent/mcp.json

This creates .agent/mcp.json with the correct paths to LDF's MCP servers configured for your project. The servers provide:

  • spec_inspector: Query spec status, guardrail coverage, task progress
  • coverage_reporter: Test coverage metrics per service/guardrail

See MCP Setup Guide for advanced configuration options.

Workflow Summary

┌─────────────────────────────────────────────────────────────┐
│  1. ldf create-spec [name]          # Create spec           │
│  2. Write requirements.md           # Define user stories   │
│  3. ldf lint [name]                 # Validate spec         │
│  4. ldf audit --type spec-review    # Get external review   │
│  5. Write design.md                 # Define architecture   │
│  6. Write tasks.md                  # Create task list      │
│  7. Implement tasks                 # Write code            │
│  8. ldf coverage                    # Check test coverage   │
│  9. Mark tasks complete             # Update tasks.md       │
└─────────────────────────────────────────────────────────────┘

CI/CD Integration

Set up automated spec validation in your CI pipeline to catch issues before merge.

GitHub Actions

mkdir -p .github/workflows
cp $(pip show ldf | grep Location | cut -d' ' -f2)/../integrations/ci-cd/github-actions.yaml .github/workflows/ldf.yaml

Or copy from the LDF repository:

# If you cloned LDF
cp /path/to/ldf/integrations/ci-cd/github-actions.yaml .github/workflows/ldf.yaml

This enables:

  • Spec linting on every PR (ldf lint --all)
  • Answerpack completeness checking (no template markers)
  • Guardrail matrix validation (all guardrails covered)
  • Optional automated audits with OpenAI

GitLab CI

# Copy from LDF repository
cp /path/to/ldf/integrations/ci-cd/gitlab-ci.yaml .gitlab-ci.yml

See CI/CD Integrations for full configuration options.

Using Preflight for CI/CD

The ldf preflight command runs all quality checks in a single command, ideal for CI pipelines:

# Run all checks (config validation, lint, coverage threshold)
ldf preflight

# Strict mode: treat warnings as errors
ldf preflight --strict

# Skip specific checks
ldf preflight --skip-lint
ldf preflight --skip-coverage

# Custom coverage threshold
ldf preflight --coverage-threshold 90

Exit Codes:

  • 0 - All checks passed
  • 1 - Lint failures
  • 2 - Coverage below threshold
  • 3 - Config/setup issues

GitHub Actions Example with Preflight:

- name: LDF Quality Check
  run: ldf preflight --strict

Diagnostic Commands

LDF provides commands to diagnose and troubleshoot your setup.

ldf doctor

Check your LDF installation and project configuration for common issues:

ldf doctor

Output:

LDF Doctor
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Python version: 3.11.5
✓ LDF version: 1.0.0
✓ Project initialized
✓ Config valid
✓ Guardrails loaded (13 active)
✓ MCP servers configured
⚠ Missing optional: mcp package (run: pip install llm-ldf[mcp])

All critical checks passed.

Use --json for CI/CD integration:

ldf doctor --json

ldf mcp-health

Check the health and readiness of configured MCP servers:

ldf mcp-health

Output:

MCP Server Health
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Server              Status      Details
spec_inspector      ✓ Ready     3 specs, 13 guardrails
coverage_reporter   ⚠ Warning   No coverage file found
db_inspector        ○ Skip      DATABASE_URL not configured
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
2 ready, 1 skipped

Updating Framework Files

When a new version of LDF is released, you can update your project's framework files while preserving your customizations:

# Check for available updates
ldf update --check

# Preview what would change
ldf update --dry-run

# Apply updates interactively
ldf update

# Update specific components only
ldf update --only templates
ldf update --only macros
ldf update --only question-packs

# Non-interactive mode (skip conflicts)
ldf update -y

What gets updated:

  • templates/ - Always replaced with latest versions
  • macros/ - Always replaced with latest versions
  • question-packs/ - Replaced if unmodified; prompts if you've made changes

What's never touched:

  • specs/ - Your feature specifications
  • answerpacks/ - Your captured design decisions
  • Custom guardrails and configuration overrides

Next Steps

Follow the tutorial series in order:

  1. Your First LDF Spec - Create a simple "Hello World" spec (20 min)
  2. Understanding Guardrails - Deep dive into the 8 core quality constraints (30 min)
  3. Working with Question-Packs - Answer questions effectively (25 min)
  4. Multi-Agent Review Workflow - Get AI feedback on specs (30 min)
  5. MCP Setup for AI Assistants - Integrate with Claude Code (20 min)

Advanced Topics

Visual Guides

Reference

Troubleshooting

"No specs found"

  • Ensure .ldf/specs/ directory exists
  • Check SPECS_DIR configuration

"Lint failed"

  • Run ldf lint --all --verbose for detailed error output
  • Check guardrail coverage matrix is complete

"MCP server not starting"

  • Verify Python 3.10+ is installed
  • Check MCP SDK: pip install mcp
  • Run server manually to see errors