llm-ldf 1.1.2

LLM Development Framework - Spec-driven development for AI-assisted engineering

LDF - LLM Development Framework

A spec-driven development framework for AI-assisted software engineering. LDF enforces a structured approach where requirements, design, and tasks are approved before any code is written.

Attribution: LDF is a fork of the WDF (WTMI Development Framework/WTMI Internal Tool), created by Jay Dubinsky (@JayFromEpic). Made available to the community as part of the llm.info resource library.

Our Mission and Goal

Our Mission is to help developers build better software regardless of their experience level, and promote the continued sharing of knowledge for the betterment of all.

Our Goal is to make this mission a reality by providing a framework that any developer can leverage to build better code, in a structured and methodical way that won't give your product owner a heart attack 🫶.

Why LDF?

AI coding assistants are powerful but can produce inconsistent results. LDF solves this by:

• Forcing structured thinking - No code until requirements → design → tasks are approved
• Enforcing guardrails - 8 core constraints validated at every phase
• Enabling multi-agent review - Use ChatGPT/Gemini to audit your AI's specs
• Reducing token usage - MCP servers provide 90% token savings vs file reads

Quick Start

1. Install

# Install the CLI
pip install llm-ldf

# Or install from source
git clone https://github.com/LLMdotInfo/ldf.git
cd ldf
pip install -e .

2. Initialize Your Project

# Interactive setup (recommended for first-time users)
ldf init

# Or non-interactive with preset
ldf init --path ./my-project --preset saas -y

The interactive CLI guides you through:

• Project path - Where to create your project
• Preset selection - Choose domain-specific guardrails
• Question packs - Pre-selected based on preset, customize as needed
• MCP servers - AI integration tools

This creates:

my-project/
├── .ldf/
│   ├── config.yaml           # Project configuration
│   ├── guardrails.yaml       # Active guardrails (8 core + preset)
│   ├── question-packs/       # Domain question templates
│   ├── answerpacks/          # Design decision storage
│   └── specs/                # Your feature specifications
├── .agent/commands/          # Slash commands for AI
└── AGENT.md                  # AI assistant instructions

3. Create Your First Spec

In Claude Code (or any AI assistant with the AGENT.md instructions):

/project:create-spec user-authentication

LDF guides you through:

1. Question-Packs - Answer critical questions about security, testing, API design
2. Requirements - Generate user stories with acceptance criteria
3. Design - Define architecture, data models, APIs
4. Tasks - Break down into implementable steps with guardrail checklists

4. Validate & Implement

# Lint your specs
ldf lint user-auth           # Lint single spec
ldf lint --all               # Lint all specs

# Generate audit request for ChatGPT/Gemini review
ldf audit --type spec-review

# After approval, implement tasks
/project:implement-task user-auth 1.1

Core Features

Guardrails

8 core guardrails are enabled by default:

#	Guardrail	Severity	Description
1	Testing Coverage	Critical	≥80% default, ≥90% critical paths
2	Security Basics	Critical	OWASP Top 10 prevention
3	Error Handling	High	Consistent responses, no swallowed exceptions
4	Logging & Observability	High	Structured logging, correlation IDs
5	API Design	High	Versioning, pagination, error format
6	Data Validation	Critical	Input validation at boundaries
7	Database Migrations	High	Reversible, separate from backfills
8	Documentation	Medium	API docs, README, inline comments

Presets add domain-specific guardrails:

Preset	Additional Guardrails
saas	Multi-tenancy, RLS, subscription billing, audit logs
fintech	Double-entry ledger, money precision, compliance, idempotency
healthcare	HIPAA compliance, PHI handling, consent management
api-only	Rate limiting, versioning, OpenAPI docs

Three-Phase Workflow

┌─────────────────────────────────────────────────────────────┐
│  Phase 1: Requirements                                       │
│  - Answer question-packs (security, testing, API design)    │
│  - Generate user stories with EARS criteria                 │
│  - Create guardrail coverage matrix                         │
│  → Approval required before proceeding                      │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: Design                                             │
│  - Architecture diagrams                                    │
│  - Data models and schemas                                  │
│  - API endpoint definitions                                 │
│  - Guardrail implementation mapping                         │
│  → Approval required before proceeding                      │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: Tasks                                              │
│  - Numbered implementation steps                            │
│  - Per-task guardrail checklists                            │
│  - Dependencies and test requirements                       │
│  → Ready for implementation                                 │
└─────────────────────────────────────────────────────────────┘

MCP Servers

LDF includes MCP (Model Context Protocol) servers for real-time validation:

Server	Purpose
spec_inspector	Query spec status, guardrail coverage, task progress
coverage_reporter	Test coverage metrics per service/guardrail

Token savings: 90% reduction compared to file reads.

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

Multi-Agent Audit

Use ChatGPT and Gemini to review your AI's work:

# Generate audit request
ldf audit --type spec-review

# Copy the generated markdown to ChatGPT with the prompt
# from multi-agent/prompts/chatgpt/spec-review.md

# Import the feedback
ldf audit --import feedback.md

CLI Reference

# Project initialization
ldf init                        # Initialize LDF in current project
  --preset saas|fintech|healthcare|api-only
  --question-packs security,testing,billing
  --force                       # Force reinitialize, overwrite existing
  --repair                      # Fix missing files without overwriting

# Project status
ldf status                      # Show project state and recommendations
ldf status --format json        # JSON output for CI/scripts

# Add LDF to existing projects
ldf convert analyze             # Analyze codebase, generate AI prompt
ldf convert analyze -o file.md  # Save prompt to file
ldf convert import response.md  # Import AI-generated specs/answerpacks
ldf convert import response.md -n my-feature  # Custom spec name
ldf convert import response.md --dry-run      # Preview without creating

# Spec validation
ldf lint <spec-name>            # Lint single spec
ldf lint --all                  # Lint all specs
ldf lint --all --format ci      # CI-friendly output for GitHub Actions

# Multi-agent audit
ldf audit --type spec-review    # Generate spec review request
ldf audit --type code-audit     # Generate code audit request
ldf audit --import <file>       # Import audit feedback

# Coverage
ldf coverage                    # Show coverage summary
ldf coverage --spec auth        # Coverage for specific spec

# Framework updates
ldf update --check              # Check for framework updates
ldf update --dry-run            # Preview what would change
ldf update                      # Apply updates interactively
ldf update --only templates     # Update specific components

CI/CD Integration

LDF includes GitHub Actions and GitLab CI templates for automated spec validation:

# GitHub Actions
mkdir -p .github/workflows
cp integrations/ci-cd/github-actions.yaml .github/workflows/ldf.yaml

# GitLab CI
cp integrations/ci-cd/gitlab-ci.yaml .gitlab-ci.yml

The CI pipeline validates:

• All specs pass ldf lint --all
• Answerpacks have no template markers
• Guardrail coverage matrices are complete
• (Optional) Automated audits with OpenAI

See CI/CD Integration for configuration options.

Project Structure

ldf/
├── ldf/                        # CLI package (pip install llm-ldf)
│   ├── _framework/             # Bundled framework assets
│   │   ├── templates/          # Spec templates (requirements, design, tasks)
│   │   ├── guardrails/         # Core + preset guardrails
│   │   ├── question-packs/     # Domain question templates
│   │   └── macros/             # Enforcement macros
│   └── _mcp_servers/           # MCP server implementations
│       ├── spec_inspector/     # Spec status MCP server
│       ├── coverage_reporter/  # Coverage metrics MCP server
│       └── db_inspector/       # Database schema MCP server (template)
├── multi-agent/
│   ├── prompts/                # ChatGPT & Gemini audit prompts
│   └── automation/             # Optional API integration
├── integrations/               # IDE & CI/CD integrations
└── examples/
    ├── python-fastapi/         # Python/FastAPI example
    ├── typescript-node/        # TypeScript/Node example
    └── go-service/             # Go service example

Examples

See the examples/ directory for complete working examples:

• Python FastAPI - User authentication with JWT, MFA
• Python Flask - Blog API with SQLAlchemy, Blueprints
• Python Django - E-commerce API with DRF, multi-tenancy
• TypeScript Node - REST API with Prisma, Zod validation
• Go Service - Data pipeline with Chi router

Recommended Additional Examples

See examples/RECOMMENDATIONS.md for proposals on 5 additional framework examples (Rust, Java, Ruby, C#, PHP) to expand the collection to 10 total templates.

Each example includes:

• .ldf/ configuration
• Complete spec (requirements → design → tasks)
• AGENT.md project instructions

Documentation

Choose Your Path

🆕 New to LDF? Start here:

• Installation Guides - Platform-specific setup (macOS, Windows, Linux)
• Tutorial Series - 5 progressive tutorials from first spec to MCP setup
• 5-Minute Quickstart - For experienced developers

📚 Core Documentation

• Getting Started - Comprehensive setup guide
• Concepts & Philosophy - Why spec-driven development works
• Answerpacks Guide - Capture design decisions upfront
• Multi-Agent Workflow - Using ChatGPT/Gemini for audits
• Customization - Guardrails, presets, and question-packs

📖 Tutorial Series (125 minutes total)

1. Your First LDF Spec - Create a simple spec (20 min)
2. Understanding Guardrails - Deep dive into 8 core constraints (30 min)
3. Working with Question-Packs - Answer questions effectively (25 min)
4. Multi-Agent Review - Get AI feedback (30 min)
5. MCP Setup - Integrate with AI assistants (20 min)

📊 Visual Guides

• Workflow Diagrams - ASCII diagrams of the 3-phase process
• Guardrail Examples - Real coverage matrices

📑 Reference

• Command Reference - Complete CLI guide
• File Structure - Project organization
• Troubleshooting - Common issues
• Task Format Guide - Task formatting details
• Glossary - Technical terms (RLS, PHI, HIPAA, etc.)

🔧 IDE Integration

• VS Code Extension - Visual spec management
• MCP Setup Guide - AI assistant integration

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.