LiveSpec v5
An information architecture that generates context trees for AI agents
Not just folders—a system for organizing project intent that AI agents can consume. Specifications stay synchronized with code, and structured context (AGENTS.md) is generated automatically.
What is LiveSpec?
LiveSpec is an information architecture and context generation system:
- Structured specifications - Organize intent from PURPOSE → requirements → strategy → behaviors
- Context tree generation - Specs compile into AGENTS.md for AI agent consumption
- Specification-driven regeneration - Code is disposable, specs are durable source of truth
- MSL format - Markdown Specification Language keeps specs minimal and maintainable
The folder structure is a means. The generated context tree is the end.
This repository is a live example: LiveSpec applied to itself. See specs/ for how we specify documentation, prompts, and methodology—then see how AGENTS.md is generated from those specs.
The Problem
- Spec drift - Specifications and code inevitably diverge
- Context loss - AI agents lack structured understanding of project intent
- Manual burden - Keeping docs synchronized is tedious and often skipped
LiveSpec solves this through:
- Specification-driven regeneration (code is regenerable from specs)
- Minimal specifications (MSL format - just what's essential)
- Continuous evolution (Phase 4 keeps specs and code aligned)
- Generated context (AGENTS.md compiled from specs for AI consumption)
Core Concepts
Before diving into architecture, understand these three mental models:
Value Structure (Vertical Traceability)
Intent flows down, implementations trace back up:
PURPOSE.md → WHY does this exist?
↓
foundation/ → WHAT must we achieve?
↓
strategy/ → HOW will we approach it?
↓
features/ → WHAT does the system do? (observable)
Why it matters: When requirements change, you trace down to find affected behaviors. When implementations exist, they trace back up to justify their existence.
Context Tree (Workspace vs Product)
Two orthogonal concerns that don't mix:
| Concern | Location | Contains | Applies To |
|---|
| Workspace | specs/workspace/ | HOW you build: patterns, workflows, agent behavior | All development |
| Product | specs/{foundation,strategy,features,interfaces}/ | WHAT you build: requirements, architecture, behaviors | This project specifically |
Key insight: Workspace specs govern ALL your development. Product specs are project-specific deliverables.
The Three Layers
| Layer | Folder | Driving Question | Owned By |
|---|
| 1 | foundation/ | What outcomes must we achieve? | Business/Product |
| 2 | strategy/ | What technical approach will we use? | Architecture |
| 3 | features/ + interfaces/ | What does the system observably do? | Engineering |
Architecture
Note: This shows initial project setup flow. LiveSpec methodology is iterative - Phase 4 (EVOLVE) detects regeneration signals and keeps specs current. See Five Phases for the complete cycle.
graph TD
%% Main Vertical Flow
PURPOSE[PURPOSE.md<br/>Why this exists]
REQUIREMENTS[foundation/<br/>What we must achieve]
CONSTRAINTS[foundation/<br/>Hard boundaries]
STRATEGY[strategy/<br/>Technical approach]
SPECS[features/ + interfaces/<br/>What system does]
CODE[Your Code<br/>AI-generated or manual]
%% Validation
TESTS[tests/<br/>Validation]
%% Workspace (separate)
WORKSPACE[workspace/<br/>Development process]
%% Downward Flow (derives-from, guided-by)
PURPOSE --> REQUIREMENTS
REQUIREMENTS --> CONSTRAINTS
REQUIREMENTS --> STRATEGY
CONSTRAINTS --> STRATEGY
STRATEGY -->|guided-by| SPECS
SPECS --> CODE
%% Upward Flow (satisfies)
SPECS -.satisfies.-> REQUIREMENTS
%% Validation
TESTS <-.validates.-> SPECS
TESTS <-.validates.-> CODE
style PURPOSE fill:#e1f5ff
style REQUIREMENTS fill:#e1f5ff
style CONSTRAINTS fill:#e1f5ff
style STRATEGY fill:#fff4e1
style SPECS fill:#e8f5e9
style CODE fill:#e8f5e9
style TESTS fill:#fce4ec
style WORKSPACE fill:#f5f5f5
Legend:
- 🔵 Foundation (Why & What) → 🟡 Design (How) → 🟢 Implementation (Build)
- 🔴 Tests validate specs and code
- ⚪ Workspace defines how you work (applies to all)
- Solid arrows: Downward flow (derives-from, guided-by)
- Dotted arrows: Upward flow (satisfies) - implementations link back to requirements
Self-Documenting Framework
Note: This diagram shows how LiveSpec documents itself using its own methodology (dogfooding). The Architecture diagram above shows how you structure your project.
LiveSpec achieves complete circularity - every deliverable is defined by a spec, every spec is defined by the framework:
graph TD
META[Framework<br/>7 metaspecs + 3 conventions]
SPECS[Project Specs<br/>30 specifications]
DELIVER[Deliverables<br/>Prompts, docs, framework, templates]
META -->|constrain| SPECS
SPECS -->|define| DELIVER
DELIVER -.dogfoods.-> META
style META fill:#fff4e1
style SPECS fill:#e8f5e9
style DELIVER fill:#fce4ec
Complete chain verified:
- Framework extends MSL Standard via base.spec.md
- Every spec has mandatory frontmatter (
type, category, fidelity, criticality, failure_mode, governed-by)
- Every deliverable has a spec in
specs/ describing it
- LiveSpec dogfoods itself: the framework is specified using the framework
AI-Powered Development
LiveSpec enables AI agents to generate code from your specifications:
Write minimal specs describing what your system should do. AI agents read these specs and generate the implementation. No framework lock-in - works with Claude Code, GitHub Copilot, Cursor, or any coding agent.
Spec-to-code generation:
- Phase 1-2: Write behavior specs → AI generates code from specs
- Phase 4: Code changes → AI extracts specs from code
- Continuous: Bidirectional sync keeps specs and code aligned
Key difference from other tools:
- No CLI required - Just copy folders, paste prompts to your AI agent
- Agent-agnostic - Same methodology works across Claude, Copilot, Cursor
- Bidirectional - Start with specs OR start with code (both work)
- Zero dependencies - Pure markdown files in standard folders
Compare to spec-kit: LiveSpec is the no-tooling, agent-agnostic alternative. Same philosophy (specs drive development) but manual-friendly and framework-free.
Quick Start
Installation Methods
Choose your preferred method:
Method 1: Claude Code Plugin (Recommended)
Pros: Version management, no file duplication, integrated commands
Requires: Claude Code 1.0.33+
# Add LiveSpec marketplace
/plugin marketplace add chrs-myrs/livespec
# Install plugin
/plugin install livespec@livespec
# Initialize your project
/livespec:init
Available commands after installation:
/livespec:init - Initialize project with workspace specs/livespec:design - Create and refine specifications (Phase 0/1)/livespec:audit - Spec health, validation, and context generation (Phase 3/4)/livespec:sweep - Multi-project audit across your portfolio/livespec:learn - Session completion and learning capture/livespec:birth - Incubate and birth child projects from within a parent LiveSpec project/livespec:go - Intelligent entry point, routes to the right skill based on intent/livespec:upgrade - Migrate an existing project to the current version
Update later:
/plugin update livespec
Plugin installation guide →
Customize your project via specs/workspace/ (constitution, patterns, workflows) — the plugin itself is not meant to be edited in place.
New Project Setup
# Initialize with defaults (5 min)
/livespec:init
# Or with full customization (20-30 min)
/livespec:init full
# Edit PURPOSE.md with your project vision
# Then generate context
/livespec:audit context
Existing Project
# Extract specifications from existing code
/livespec:audit extract
# Regenerate agent context
/livespec:audit context
Full quickstart guide →
Project Structure
your-project/
├── PURPOSE.md # Why this project exists
│
├── specs/ # All specifications (mandatory frontmatter)
│ ├── workspace/ # Operating context (HOW you work)
│ │ ├── taxonomy.spec.md # Project classification (check FIRST)
│ │ ├── constitution.spec.md # Development principles
│ │ ├── patterns.spec.md # Code patterns
│ │ └── workflows.spec.md # Development workflows
│ ├── foundation/ # WHY — strategic outcomes and constraints
│ │ ├── outcomes.spec.md
│ │ └── constraints.spec.md
│ ├── strategy/ # HOW — cross-cutting technical decisions
│ ├── features/ # WHAT — observable behaviours
│ ├── interfaces/ # Contracts — API/data formats
│ └── artifacts/ # Deliverable specifications
│
├── registries/ # Accepted current state (gaps, issues, improvements)
│
├── AGENTS.md # Generated agent context (from workspace specs)
│
└── [your code] # Your implementation
Understanding Workspace Specs
Workspace specs control HOW you build. Customize these after Phase 0 setup, before main development:
| File | Purpose | Example |
|---|
| taxonomy.spec.md | Project classification—check FIRST for any file placement | project_type: Software vs project_type: Governance |
| constitution.spec.md | Development principles, AI agent behavior | principle: "Specs before implementation" |
| patterns.spec.md | Code patterns, naming conventions, file organization | naming: kebab-case for files, PascalCase for components |
| workflows.spec.md | Development processes, commit practices, review requirements | commits: Conventional Commits format required |
When to customize: After running Phase 0 quick-start, BEFORE starting Phase 1 design work.
MSL Format
All specifications follow Markdown Specification Language (MSL):
---
criticality: CRITICAL
failure_mode: System unsecured without authentication
---
# User Authentication
## Requirements
- [!] System authenticates users via email and password before allowing access to protected resources.
- Valid credentials allow login
- Invalid credentials rejected
- Sessions persist after authentication
- Protected resources require authentication
That's it. Title, frontmatter, Requirements. Minimal. Testable.
LiveSpec conventions → | MSL Specification →
The Five Phases
LiveSpec guides development through five phases with clear entry/exit criteria. Hybrid workflow - natural progression through phases with feedback loops when discovering unknowns.
Phase 0: DEFINE
Establish problem space and development approach
- Define problem statement
- Identify constraints
- Setup workspace specifications
Phase 1: DESIGN
Design solution architecture
- Define architecture
- Specify behaviors
- Create contracts
Phase 2: BUILD
Implement the solution
- Build to specifications
- Create tests
- Validate implementation
Phase 3: VERIFY
Validate solution meets requirements
- Run validation
- Acceptance review
- Document results
Phase 4: EVOLVE
Keep specs and code synchronized (continuous)
- Detect drift
- Extract new specs
- Update existing specs
Continuous Evolution Cycle
Phase 4 maintains alignment through regeneration signals - the core value of LiveSpec:
graph LR
CODE[Code Changes]
SPECS[Specifications]
DRIFT[Detect Drift]
UPDATE[Update/Extract]
CODE -->|4a: detect-drift| DRIFT
DRIFT -->|drift found| UPDATE
UPDATE -->|4b: extract-specs<br/>4e: validate| SPECS
SPECS -->|guide| CODE
SPECS -.Phase 1-2<br/>Design & Build.-> CODE
CODE -.Phase 4<br/>Evolve.-> SPECS
style CODE fill:#e8f5e9
style SPECS fill:#e8f5e9
style DRIFT fill:#fff4e1
style UPDATE fill:#fff4e1
Key insight: Specs and code inform each other continuously. Start with specs (design-first) OR start with code (extract-first) - both work.
Methodology Guide →
Key Features
- ✅ Context Generation - Specs compile to AGENTS.md for AI consumption
- ✅ AI Agent Agnostic - Works with Claude, Copilot, Cursor, any agent
- ✅ Bidirectional Flow - Specs → Code AND Code → Specs
- ✅ Living Documentation - Specifications evolve with code
- ✅ Minimal Specifications - MSL format reduces specs by 70%
- ✅ No Lock-in - Just markdown files and folders
Troubleshooting
Common mistakes when setting up LiveSpec:
| Mistake | Symptom | Fix |
|---|
| Creating files before checking taxonomy | Files in wrong locations, agents confused | Always read specs/workspace/taxonomy.spec.md FIRST |
| Mixing workspace and product concerns | Workspace specs contain business logic, or vice versa | Workspace = HOW you build (all projects). Product = WHAT you build (this project) |
| Skipping Phase 0 | Missing workspace specs, no constitution | Run 0a-quick-start.md or 0b-customize-workspace.md |
| Forgetting to regenerate AGENTS.md | AI agents using stale context | Run /livespec:audit context after spec changes |
Quick diagnostic: If your AI agent seems confused about your project structure, regenerate AGENTS.md first.
Works With
- Claude Code - Direct prompt execution
- Cursor - Use Composer with prompts
- GitHub Copilot - Use prompts as context
- Any AI Agent - Copy/paste prompts
See examples →
Documentation
For AI Agents
- llms.txt - Context7-compatible overview (cache this!)
- AGENTS.md - Quick reference for AI assistants
For Humans
Version
Current Version: 5.13.0
LiveSpec v5 is distributed as a Claude Code plugin:
- Plugin installation -
/plugin install livespec for integrated experience
- 8 skills - init, design, audit, sweep, learn, birth, go, upgrade
- Slash commands - All skills available via
/livespec:*
- Sub-agents -
context-builder performs isolated context regeneration
Previous: v4 introduced disposable code architecture, v5 replaced directory-copy distribution with a Claude Code plugin.
Changelog → | Migration guide →
Requirements
- Any AI coding agent (optional but recommended)
- Git (for version control)
- Text editor
That's it. No installation. No dependencies.
Repository Structure
livespec/
├── PURPOSE.md # Why LiveSpec exists
├── README.md # This file
│
├── .claude-plugin/ # PLUGIN (install via /plugin install)
│ ├── plugin.json # Plugin manifest
│ └── marketplace.json # Self-hosted marketplace
│
├── skills/ # Plugin skills
│ ├── init/SKILL.md
│ ├── design/SKILL.md
│ ├── audit/SKILL.md
│ ├── sweep/SKILL.md
│ ├── learn/SKILL.md
│ ├── birth/SKILL.md
│ ├── go/SKILL.md
│ └── upgrade/SKILL.md
│
├── commands/ # Slash command routers (routes-to: skills/*/SKILL.md)
│ ├── init.md
│ ├── design.md
│ ├── audit.md
│ ├── sweep.md
│ ├── learn.md
│ ├── birth.md
│ ├── go.md
│ └── upgrade.md
│
├── agents/ # Sub-agent definitions
│ └── context-builder.md # Isolated AGENTS.md/ctxt/ regeneration
│
├── references/ # Reference content for the plugin
│ ├── guides/
│ ├── prompts/
│ └── standards/
│
├── templates/ # Project scaffolding templates
│
├── examples/ # Worked example projects
│
├── specs/ # DOGFOODING (LiveSpec's own specs)
│ ├── workspace/
│ ├── foundation/
│ ├── strategy/
│ ├── features/
│ ├── artifacts/
│ └── interfaces/
│
└── docs/ # User documentation
For Users: Install the plugin (/plugin install livespec)
Contributing
Contributions welcome! We dogfood our own methodology:
License
MIT License - see LICENSE
Support
LiveSpec v5 — Information architecture for AI-first development.
Simple. Minimal. Effective.
