lean-spec 0.1.0 → 0.1.2

package/README.md

@@ -1,321 +1,421 @@
 # LeanSpec
 
-A lightweight, agile Spec-Driven Development (SDD) methodology and adaptive workflow designed to reduce spec "mind burden" and keep teams—both humans and AI coding agents—focused on what truly matters.
+<p align="center">
+  <img src="docs-site/static/img/logo-with-bg.svg" alt="LeanSpec Logo" width="120" height="120">
+</p>
 
-> **LeanSpec is not just a document—it's an adaptive workflow, SOP (Standard Operating Procedure), and living process for AI-powered development teams.**
+<p align="center">
+  <a href="https://www.npmjs.com/package/lean-spec"><img src="https://img.shields.io/npm/v/lean-spec.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/lean-spec"><img src="https://img.shields.io/npm/dm/lean-spec.svg" alt="npm downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
+</p>
 
-## The Problem
-
-Traditional software specifications often suffer from:
-- **Documentation Overload**: Lengthy documents that nobody (human or AI) reads or maintains
-- **Frozen Contracts**: Specs that become outdated as soon as development begins
-- **Exhaustive Overthinking**: Trying to document every possible edge case upfront
-- **Mind Burden**: Cognitive load from managing verbose, complicated documentation
-- **Lost Intent**: The "why" gets buried under mountains of "what" and "how"
+---
 
-Development teams—including AI coding agents—need clear direction without being buried in documentation debt.
+## Specs that fit in AI working memory
 
-## The LeanSpec Solution
+Traditional 2,000-line RFCs overflow AI context windows. Your AI agent can't help because it can't fit the full context.
 
-LeanSpec is a **mindset and methodology, not a rigid format or tool**. It's about capturing what truly matters with minimal overhead.
+```diff
+- Heavyweight process (multi-step workflows) → AI context overflow
+- Vibe coding (no specs) → Team misalignment
++ LeanSpec: Structure without overhead
+```
 
-A simple example structure might include:
-- **The Goal**: Why this work exists
-- **Key Scenarios**: The critical user journeys that must succeed
-- **Acceptance Criteria**: Clear, testable conditions for "done"
-- **Technical Contracts**: Essential interfaces and constraints
-- **Non-Goals**: What we're explicitly not doing (to maintain focus)
+**LeanSpec: A lean SDD methodology for human + AI collaboration.**
 
-But the key is the mindset: focus on clarity, keep it lean, make it living documentation. The structure should serve your needs, not constrain them.
+Specs under 300 lines. Intent-focused. Machine-readable. Adapts to your workflow—from solo dev to enterprise.
 
-## Agile Principles
+*Lean = adaptive and progressive. Tools (CLI/MCP) support the methodology.*
 
-LeanSpec is built on these core principles:
+<p align="center">
+  <a href="#quick-start-5-minutes"><strong>Quick Start (5 Minutes) →</strong></a> •
+  <a href="https://www.lean-spec.dev"><strong>Documentation</strong></a> •
+  <a href="https://www.lean-spec.dev/docs/guide/ai-executable-patterns"><strong>Examples</strong></a>
+</p>
 
-### 🎯 Clarity over Documentation
-Write just enough to communicate intent clearly. If it doesn't add clarity, don't write it.
+---
 
-### 🚀 Essential Scenarios over Exhaustive Lists
-Focus on the 20% of scenarios that deliver 80% of the value. Document what must work, not every possible edge case.
+## The SDD Dilemma
 
-### 📱 Living Guide over Frozen Contract
-Specs should evolve with the project. Update them as you learn, don't treat them as immutable contracts.
+### Scenario 1: Context Overflow 🔴
 
-### 🧠 Reduced Mind Burden over Comprehensive Coverage
-Keep specs short and scannable. The goal is to reduce cognitive load, not create reference manuals.
+You paste a traditional spec into Cursor. **"Context too large."** Your AI agent can't help—it can't fit the full context. Back to manual implementation.
 
-### ⚡ Speed over Perfection
-Ship a "good enough" spec quickly. You can always refine it based on feedback and learning.
+### Scenario 2: Stale Documentation 📄
 
-### 🤝 Collaboration over Specification
-Use specs as conversation starters, not as replacements for human communication.
+Your team has beautiful specs. None match the current code. Nobody updates them because it's too painful. They're documentation theater.
 
-## Getting Started
+### Scenario 3: Wrong Tool for the Job ⚖️
 
-The LeanSpec mindset is simple:
+You tried automated code generation tools—powerful but heavyweight. You tried vibe coding—fast but team gets misaligned. Where's the **lightweight spec methodology**?
 
-1. **Start with why**: What problem are you solving?
-2. **Capture the essentials**: What absolutely must be communicated?
-3. **Stay lean**: If it doesn't add clarity, cut it
-4. **Keep it living**: Update as you learn
+**LeanSpec solves this:**
+- ✅ Specs fit in AI context windows (<300 lines)
+- ✅ Structured enough for AI agents to understand
+- ✅ Flexible enough to grow with your team
+- ✅ CLI & MCP tools to support the workflow
 
-For a practical example, see `templates/` for available project initialization templates. Each template contains:
-- Full project structure (specs/ directory, examples)
-- `AGENTS.md` - AI agent instructions and coding standards
-- Supporting files - CONTRIBUTING.md, checklists, or other guides
-- `config.json` - Template configuration
+---
 
-Initialize with `lspec init` to set up your project.
+## How LeanSpec is Different
 
-## Quick Start
+**From Automated Tools (like [Spec Kit](https://github.com/speckai/speckai)):**
+- ❌ No multi-step workflows or slash commands
+- ❌ No code generation or task execution
+- ✅ Just specs for team alignment and AI context
 
-```bash
-# Install globally
-pnpm install -g lean-spec
+**From Lightweight Approaches (vibe coding):**
+- ❌ Not "just chat with AI"
+- ✅ Enough structure for AI agents to act on
+- ✅ Team alignment through shared specs
+- ✅ Maintainable documentation
 
-# Or use locally in your project
-pnpm add -D lean-spec
+**From Change-Tracking Systems (like [OpenSpec](https://github.com/openspec-dev/openspec)):**
+- ❌ No proposals or change folders
+- ❌ No diff-based workflows
+- ✅ Direct spec editing with version control
+- ✅ Philosophy over process
 
-# Initialize LeanSpec in your project (interactive)
-lspec init
+**LeanSpec = Just the specs.** Markdown files with structure. No ceremony, no overhead.
 
-# Create your first spec (creates specs/YYYYMMDD/NNN-name/ folder)
-lspec create my-feature
+---
 
-# List all specs
-lspec list
+## How It Works
 
-# Filter specs by status, tags, or priority
-lspec list --status=in-progress
-lspec list --tag=api --priority=high
+### A Real LeanSpec in Action
 
-# Update spec metadata
-lspec update specs/20251031/001-my-feature --status=complete
-lspec update specs/20251031/001-my-feature --priority=high --tags=api,backend
+Here's an actual spec from this project (287 lines):
 
-# List available templates
-lspec templates
+```yaml
+---
+status: in-progress
+created: 2025-11-01
+tags: [cli, dx]
+priority: high
+---
 
-# Archive old specs
-lspec archive specs/20251031/001-my-feature
+# Unified Dashboard
+
+## Overview
+Combine `lean-spec board` and `lean-spec stats` into a single, comprehensive
+project health view. Give users instant insight into project status,
+bottlenecks, and team velocity.
+
+## Design
+- Board view (Kanban columns)
+- Key metrics (completion rate, avg spec size)
+- Bottleneck detection (specs >400 lines, stale specs)
+- Health score (0-100)
+
+## Plan
+1. Merge board + stats logic
+2. Add health scoring algorithm
+3. Implement bottleneck detection
+4. Add color-coded indicators
+
+## Success Criteria
+- Shows full project state in <5 seconds
+- Identifies bottlenecks automatically
+- Used daily by team leads
 ```
 
-### Initialize Your Project
+**Notice:**
+- ✅ Under 300 lines (fits in AI + human working memory)
+- ✅ Intent is clear ("what" and "why")
+- ✅ Implementation details are minimal (not a PRD)
+- ✅ Both human and AI can understand
+- ✅ Structured metadata (status, tags, priority)
 
-`lspec init` provides three paths:
+---
 
-1. **Quick start** - Zero configuration, solo-dev defaults
-2. **Choose template** - Pick from solo-dev, team, enterprise, or api-first
-3. **Customize everything** - Full control (coming soon)
+## Built on First Principles
 
-Each template is a complete working model with:
-- Spec structure and examples
-- AGENTS.md for AI agent integration
-- Supporting files (CONTRIBUTING.md, checklists, etc.)
-- Project-specific config
+LeanSpec isn't arbitrary rules—it's derived from fundamental constraints of working with AI.
 
-#### Spec Metadata with Frontmatter
+### 🧠 Context Economy
+**Specs <300 lines → Fit in working memory**
 
-LeanSpec uses YAML frontmatter for structured metadata. Each template includes different field sets:
+- **Physics**: AI performance degrades with longer context (quality drops beyond 50K tokens despite 200K limits)
+- **Biology**: Human working memory is limited (7±2 items, 5-10 min attention)
+- **Economics**: Large contexts cost more time and money
+- **Reality**: Attention is the scarce resource, not storage
+- **Result**: Keep specs under 300 lines, split complex features
+
+### ✂️ Signal-to-Noise Maximization
+**Every word informs decisions → Or it's cut**
+
+- Every sentence must answer: "What decision does this inform?"
+- Cut obvious statements, inferable content, speculation
+- Keep decision rationale, constraints, success criteria
+- **Result**: Dense, actionable specs that respect reader attention
+
+### 📈 Progressive Disclosure
+**Add structure only when you feel pain → Start simple**
+
+- Solo dev: Just `status` + `created`
+- Small team: Add `tags` + `priority`
+- Enterprise: Add custom fields as needed
+- **Result**: Structure adapts to team, not the other way around
+
+### 🎯 Intent Over Implementation
+**Capture "why" → Let "how" emerge**
+
+- Must have: Problem, intent, success criteria
+- Should have: Design rationale, trade-offs
+- Could have: Implementation details (these change)
+- **Result**: Specs stay relevant as code evolves
+
+### 🌉 Bridge the Gap
+**Both humans AND AI must understand → Clear structure + natural language**
+
+- For humans: Overview, context, rationale
+- For AI: Unambiguous requirements, structured metadata
+- Both can parse and reason about specs
+- **Result**: True human-AI collaboration
 
-**Minimal Template** (status, created only):
-```yaml
 ---
-status: planned
-created: 2025-11-01
+
+**These aren't preferences—they're constraints.** Physics (context windows), biology (working memory), and economics (token costs) dictate what works.
+
+📖 [Deep dive: First Principles Guide →](https://www.lean-spec.dev/docs/guide/understanding#the-five-first-principles)
+
 ---
 
-# My Feature
+## Features Designed for AI-First Development
 
-> **Status**: 📅 Planned · **Created**: 2025-11-01
+### 🤖 AI-Native Integration
+
+Works seamlessly with popular AI coding tools:
+
+- **GitHub Copilot** - AI pair programmer in VS Code & JetBrains IDEs
+- **Claude Code** - Anthropic's AI coding assistant
+- **OpenAI Codex** - OpenAI's coding agent (CLI, IDE, cloud)
+- **Cursor / Windsurf** - AI-first code editor built on VS Code
+
+MCP-native specs. Works with any tool that supports Model Context Protocol.
+
+### 📊 Workflow Visibility
+
+Track progress without leaving the terminal:
+
+```bash
+$ lean-spec board
+
+📋 Spec Kanban Board
+
+📅 Planned (11)
+  🟠 High Priority
+    • readme-redesign-ai-first
+    • validate-output-lint-style
+  
+⏳ In Progress (2)
+    • unified-dashboard
+    • mcp-error-handling
+
+✅ Complete (14)
+    • stats-dashboard-refactor
+    • git-backfill-timestamps
+    ...
 ```
 
-**Standard Template** (recommended - adds tags and priority):
-```yaml
----
-status: in-progress
-created: 2025-11-01
-tags: [api, feature]
-priority: high
----
+```bash
+$ lean-spec stats
 
-# My Feature
+📊 Project Stats
 
-> **Status**: 🔨 In progress · **Priority**: High · **Created**: 2025-11-01 · **Tags**: api, feature
+  Total: 27 specs  |  Active: 13  |  Complete: 14
+  Completion: 52%  |  Avg size: 287 lines
 ```
 
-**Enterprise Template** (adds team fields and tracking):
+Simple, focused CLI for spec status and team visibility.
+
+### 🎨 Progressive Structure
+
+Start simple, add complexity only when you need it:
+
 ```yaml
----
-status: in-progress
-created: 2025-11-01
-tags: [security, compliance]
-priority: critical
-assignee: alice
-reviewer: bob
-issue: JIRA-1234
-epic: security-hardening
----
+# Day 1: Solo dev
+status: planned
 
-# My Feature
+# Week 2: Small team  
+status: in-progress
+tags: [api, feature]
+priority: high
 
-> **Status**: 🔨 In progress · **Priority**: Critical · **Created**: 2025-11-01 · **Tags**: security, compliance  
-> **Assignee**: alice · **Reviewer**: bob
+# Month 3: Enterprise
+assignee: alice
+epic: PROJ-123
+sprint: 2025-Q4-S3
 ```
 
-**Key Features**:
-- **Dual Format**: Machine-readable YAML frontmatter + human-readable visual badges
-- **Auto-sync**: Visual badges automatically update when metadata changes
-- **Status Emojis**: 📅 Planned, 🔨 In progress, ✅ Complete, 📦 Archived
+Custom fields fully supported. Adapts to your workflow as you grow.
 
-**Philosophy**: Start minimal. Add fields only when you feel the pain of not having them.
+### ⚡ Actually Maintainable
 
-**Valid Status Values**: `planned`, `in-progress`, `complete`, `archived`  
-**Valid Priority Values**: `low`, `medium`, `high`, `critical`
+**The problem:** Traditional specs get stale because updating them is too painful.
 
-Use `lspec list` with filters to find specs:
-- `lspec list --status=in-progress` - Show active work
-- `lspec list --priority=high` - Focus on critical items
-- `lspec list --tag=api` - Find related specs
-- Combine filters: `lspec list --status=planned --priority=high --tag=api`
+**LeanSpec solution:**
+- **Short specs** - Fits in AI context window for easy updates
+- **CLI tools** - Quick viewing and editing from terminal
+- **AI-friendly format** - Structured markdown AI agents can parse and update
+- **Version control** - Git tracks changes, diffs show what evolved
 
-Update spec metadata without editing files:
-- `lspec update <path> --status=complete` - Mark as done (auto-adds completion date)
-- `lspec update <path> --priority=high --tags=api,backend` - Update multiple fields
+**Result:** Specs light enough to actually keep in sync with code.
 
-#### Integrating with Existing Projects
+---
 
-If you already have `AGENTS.md`, `.cursorrules`, or other system prompts, `lspec init` will detect them and offer three options:
+## Quick Start (5 Minutes)
 
-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 `.lspec` config and `specs/` directory, keeps your files untouched
+### 1. Install & Initialize
 
-This makes it easy to adopt LeanSpec incrementally without disrupting your existing AI agent setup.
+```bash
+npm install -g lean-spec
+cd your-project
+lean-spec init
+```
 
-### Available Templates
+### 2. Work with Your AI Tool
 
-- **solo-dev** - Quick setup for solo developers (default)
-- **team** - Small team collaboration with workflow guides
-- **enterprise** - Enterprise-grade with governance & compliance
-- **api-first** - API-driven development with endpoint specs
+**In Cursor, Copilot, or any AI coding assistant:**
 
-Run `lspec templates` to see all available templates.
+```
+👤 You: "Create a spec for user authentication with OAuth2."
 
-See `AGENTS.md` for AI agent integration guidance.
+🤖 AI: [runs lean-spec create user-authentication]
+      "I've created specs/001-user-authentication/README.md.
+      Here's the spec..."
 
-## Development
+👤 You: "Now implement the OAuth2 flow based on this spec."
 
-### Testing
+🤖 AI: [reads spec, implements code]
+      "I've implemented the OAuth2 provider in src/auth/oauth.ts..."
+```
+
+### 3. Track Progress
 
 ```bash
-pnpm test        # Run tests in watch mode
-pnpm test:run    # Run tests once (CI mode)
+# Check project status
+lean-spec board
+
+# View spec with AI-friendly output
+lean-spec view user-authentication --json
+
+# Update status as you progress
+lean-spec update user-authentication --status in-progress
 ```
 
-See [docs/testing.md](docs/testing.md) for comprehensive testing documentation.
+**The workflow:**
+1. ✅ Ask AI to create spec (it uses `lean-spec create`)
+2. ✅ AI reads spec and implements (spec fits in context)
+3. ✅ Track with `lean-spec board` / `lean-spec stats`
+4. ✅ Update status as work progresses
 
-### Build
+**Why this works:**
+- Specs <300 lines → Fit in AI context window
+- Structured format → AI can parse and act on
+- CLI tools → AI knows how to use them
+- You drive, AI executes
 
-This project is built with TypeScript and pnpm:
+**Next steps:**
+- 📘 [Full CLI Reference](https://www.lean-spec.dev/docs/reference/cli) - All commands
+- 🎨 [Choose a Template](https://www.lean-spec.dev/docs/guide/templates) - Minimal, standard, or enterprise
+- 🤖 [AI Agent Setup](AGENTS.md) - Configure AI coding tools
 
-```bash
-# Install dependencies
-pnpm install
+---
 
-# Build CLI
-pnpm build
+## Choose the Right Tool
 
-# Watch mode
-pnpm dev
+Not every project needs the same level of structure. Here's when to use what:
 
-# Type check
-pnpm typecheck
-```
+| Use This | When You Need |
+|----------|---------------|
+| **[Spec Kit](https://github.com/speckai/speckai)** | Automated code generation from specs • Multi-step workflows |
+| **[OpenSpec](https://github.com/openspec-dev/openspec)** | Change proposals and delta tracking • Brownfield modifications |
+| **LeanSpec** | AI-native specs that fit in context • Human + AI collaboration • Solo to enterprise |
+| **Vibe Coding** | Rapid prototyping • Solo experiments • Trivial features |
 
-**Note**: LeanSpec methodology is language/framework-agnostic. This TS implementation is for the CLI tool only.
+**Why LeanSpec?** The only SDD methodology designed from first principles for AI context windows. Specs that both humans and AI can actually use.
 
-## When to Use LeanSpec
+---
 
-**Perfect for:**
-- New features or components
-- API designs
-- Architecture decisions that need shared understanding
-- Quick alignment on work direction
-- Providing context to AI coding agents for implementation tasks
-- **Establishing an adaptive SOP for AI-powered development teams**
-- **Integrating with system prompts and agent instructions**
+## Who Uses LeanSpec
 
-**Not ideal for:**
-- Detailed API reference documentation (use code comments + auto-generated docs)
-- Step-by-step user manuals (use dedicated user documentation)
-- Compliance requirements that mandate specific formats
+### AI-First Development Teams
+Give agents clear context without context window overload. Works with Cursor, Copilot, Aider, Claude.
 
-## LeanSpec for AI Coding Agents
+### Scaling Startups
+One methodology from solo dev → team → enterprise. Add structure progressively as you grow.
 
-In the era of AI-assisted development, LeanSpec serves as both a methodology and an adaptive workflow for AI-powered development teams. It's not just about writing specs—it's about establishing a living process that integrates with AI agent systems.
+### Teams Seeking Balance
+Need structure for alignment and AI context, but heavyweight processes slow you down.
 
-### Core Benefits for AI Teams
+### Developers Building AI Agents
+MCP-native specs. Structured input format agents can parse reliably.
 
-- **Clear Context**: Starting with "why" gives AI agents the purpose behind the work
-- **Concrete Scenarios**: Specific examples help AI understand expected behavior
-- **Testable Criteria**: Clear targets guide AI implementation
-- **Boundaries**: Explicit non-goals help AI avoid scope creep
-- **Adaptable Structure**: Whatever format you choose, consistency helps AI parse effectively
+---
 
-AI coding agents work best with clear, concise specifications that balance context with brevity—exactly what the LeanSpec mindset promotes.
+## We Practice What We Preach
 
-### Implementing LeanSpec as an AI Workflow
+**LeanSpec is built using LeanSpec.** Every feature, refactor, and design decision has a spec. All specs follow the first principles—under 300 lines, AI-readable, actively maintained.
 
-LeanSpec becomes truly powerful when integrated as a **Standard Operating Procedure (SOP)** for your AI-powered development team:
+**Real velocity from zero to official launch:**
+- **6 days** from first commit to production
+- Full-featured CLI, MCP server, documentation site
+- 54 specs written and implemented—all with AI agents
+- Derived first principles from practicing LeanSpec 
 
-#### System Prompts and Context Engineering
+We dogfood our own methodology. Specs that fit in AI context enable the velocity we promise.
 
-To effectively use LeanSpec with AI agents, consider implementing:
+→ [Browse our specs](https://github.com/codervisor/lean-spec/tree/main/specs)
 
-1. **System-Level Instructions** (e.g., `AGENTS.md`)
-   - Define how AI agents should interpret and apply LeanSpec principles
-   - Establish coding standards and conventions
-   - Specify how to handle ambiguity or missing information
-   - Set expectations for testing, documentation, and code quality
+---
 
-2. **Context Engineering**
-   - Structure your repository to make LeanSpec documents discoverable
-   - Use consistent naming conventions (e.g., `LEANSPEC_*.md`)
-   - Place specs near the code they describe
-   - Link related specs together for complex features
+## When to Use (and Skip) Specs
 
-3. **Adaptive Workflow Integration**
-   - Start each work item with a LeanSpec document
-   - Have AI agents reference the spec during implementation
-   - Update specs as understanding evolves (living documentation)
-   - Use specs as the source of truth for feature discussions
+| Use LeanSpec When: | Skip It When: |
+|---------------------|---------------|
+| ✅ Features span multiple files/components | ❌ Trivial bug fixes |
+| ✅ Architecture decisions need alignment | ❌ Self-explanatory refactors |
+| ✅ Guiding AI agents on complex features | ❌ Pure API reference (use code comments) |
+| ✅ Design rationale should be documented | ❌ Quick experiments |
+| ✅ Team needs to coordinate work | ❌ Changes are obvious |
 
-#### Example: AGENTS.md for LeanSpec Workflow
+**Philosophy:** Write specs when they add clarity. Skip them when they don't.
 
-Create an `AGENTS.md` file in your repository to guide AI agents. See this repo's `AGENTS.md` for a working example.
+---
 
-## Philosophy
+## Learn More
 
-> "The best spec is the one that gets read, understood, and acted upon—by humans and AI alike."
+### 📚 Documentation
+- [Getting Started Guide](https://www.lean-spec.dev/docs/guide/getting-started) - Complete setup walkthrough
+- [First Principles](https://www.lean-spec.dev/docs/guide/understanding#the-five-first-principles) - The philosophy behind LeanSpec
+- [CLI Reference](https://www.lean-spec.dev/docs/reference/cli) - All commands with examples
 
-LeanSpec is a **mindset, methodology, and adaptive workflow**—not just a format. It embraces agile thinking: start small, iterate based on feedback, and focus on outcomes over outputs. A one-page spec that everyone (including AI coding agents) understands beats a fifty-page document that nobody reads.
+### 🛠️ Integrations
+- [AI Agent Configuration](AGENTS.md) - Cursor, Copilot, Aider setup
+- [MCP Server](docs/MCP-SERVER.md) - Claude Desktop integration
+- [VS Code Extension](https://www.lean-spec.dev/docs/roadmap#vs-code-extension) - Enhanced editor support (planned)
 
-The methodology is about principles over process—adapt it to your team, your tools, and your context. When working with AI-powered development teams, LeanSpec becomes an SOP that integrates with system prompts, context engineering, and agent instructions to create a cohesive, intelligent workflow.
+### 🎓 Guides
+- [Custom Fields](https://www.lean-spec.dev/docs/guide/custom-fields) - Adapt to your workflow
+- [Templates](https://www.lean-spec.dev/docs/guide/templates) - Choose the right structure
+- [Frontmatter](https://www.lean-spec.dev/docs/guide/frontmatter) - Metadata and organization
 
-## Contributing
+### 🤝 Community
+- [GitHub Issues](https://github.com/codervisor/lean-spec/issues) - Report bugs or request features
+- [Contributing Guide](CONTRIBUTING.md) - Join the project
+- [AI-Executable Patterns](https://www.lean-spec.dev/docs/guide/ai-executable-patterns) - Real-world usage patterns
 
-Have ideas for improving LeanSpec? Open an issue or submit a pull request. Keep it lean! 🚀
+---
 
 ## License
 
-MIT License - See [LICENSE](LICENSE) for details.## Documentation
+MIT - See [LICENSE](LICENSE)
 
-- **[Getting Started](README.md)** - You are here!
-- **[AI Agent Integration](AGENTS.md)** - Setup for AI-powered development
-- **[Contributing](CONTRIBUTING.md)** - How to contribute to LeanSpec
-- **[Developer Guide](docs/)** - Testing and technical docs
-
-## Contributing
+---
 
-Have ideas for improving LeanSpec? See [CONTRIBUTING.md](CONTRIBUTING.md) for details. Keep it lean! 🚀
+<p align="center">
+  <strong>Spec-Driven Development without the overhead.</strong><br>
+  Keep your specs short. Keep them clear. Keep them useful.
+</p>