MSL bridges human intent and AI implementation. Write specifications in markdown that both humans and AI assistants understand perfectly. No more vibe coding—achieve predictable, high-quality AI-generated code.
# MSL is a specification language - no installation needed!
# Just write markdown with requirements:
# Create your first specification
echo '# Login Feature
## Requirements
- Users authenticate with email/password
- Sessions expire after 24 hours
- Lock account after 5 failed attempts' > login.md
# Validate your specification
msl-validate login.md
# Give to AI for implementation
# "Claude, implement the login feature from login.md"
# → Receive precise, tested implementationThat's it. You just directed an AI to build exactly what you want.
In the age of AI assistants, the bottleneck isn't writing code—it's communicating intent. MSL solves this:
- 🤖 AI-Native: LLMs understand MSL without training
- ✅ Validated: Catch AI hallucinations before they become bugs
- 💾 Persistent Context: Specifications survive session boundaries
- 🚀 10x Productivity: Stop prompt engineering, start specifying
- 🔮 Self-Validating: MSL is powerful enough to specify itself
Fun fact: The MSL language specification is written in MSL and validated by MSL. We eat our own dog food!
→ Learn Why MSL is Essential for AI Development
# Payment Processing
## Requirements
- Accept credit cards and PayPal
- Process refunds within 30 days
- Send email receipts✅ Valid MSL - Just markdown with requirements
---
id: payment-v2
version: 1.0
---
# Payment Processing
## Requirements
- REQ-001: Accept credit cards via Stripe API
- REQ-002: Accept PayPal via OAuth integration
- REQ-003: Process refunds within 30 days with audit log
- REQ-004: Send email receipts within 5 minutes✅ AI can now track and implement each requirement precisely
---
id: payment-enterprise
extends: payment-v2
---
# Enterprise Payment Processing
## Requirements
- REQ-001: [OVERRIDE] Accept cards via multiple gateways
- REQ-005: [NEW] Support cryptocurrency payments
- REQ-006: [NEW] Implement PCI compliance logging✅ AI understands inheritance and generates enterprise-grade code
Morning: Write specification (15 min)
→ AI: Generate implementation (instant)
→ Validate specification (automated)
→ AI: Generate tests (instant)
→ Ship feature (same day)Architect: Define specifications
→ Dev A + ChatGPT: Implement backend
→ Dev B + Claude: Implement frontend
→ Specs ensure perfect integration
→ Automated validation gatesCompliance team: Write security specifications
→ Validation pipelines: Enforce standards
→ Multiple teams + AIs: Parallel development
→ Audit trail: Every requirement traced
→ Risk: Mitigated through validation- Natural language that LLMs understand natively
- Token-efficient for context windows
- Validation prevents hallucinations
- Templates reduce prompt engineering
- Automated validation with quality scores
- DRY compliance checking
- Testability verification
- Architectural analysis
- Version with your code
- Branch specifications with features
- Review specs like code
- Merge without conflicts
- It's just markdown
- Start with Level 0
- Add complexity only when needed
- AI helps write specifications
- MSL is specified in MSL itself - proving its power
- Core specifications governed by metaspecs written in MSL
- Self-validating system using its own features
- Learn about MSL's meta architecture →
If you're an AI assistant (Claude, ChatGPT, etc.) helping with an MSL project:
- Start here: Read specs/INDEX.md for navigation
- Understand purpose: Check specs/msl-purpose-and-limitations.md
- Project setup: Follow specs/standards/msl-project-organization.md
- Create PURPOSE.md first: Every project needs a PURPOSE specification
- Use appropriate level: L0 for simple, L1 for structured, L2 for complex
- Always create PURPOSE.md as the first file in new projects
- Organize specifications in
/specsdirectory structure - Start with the simplest MSL level that meets requirements
- Use validation tools to ensure specification quality
- Reference this repository via context7 MCP when available
- Quick Start Tutorial - Your first MSL spec in 5 minutes
- Why MSL? - The case for structured AI development
- AI Workflow Guide - Maximize AI productivity
- User Guide - Everything you need to know
- Language Reference - Complete syntax and semantics
- Tools & CLI - Validation, rendering, and CI/CD
- Solo + AI - Individual AI-powered development
- Team Collaboration - Coordinating human and AI developers
- AI Integration - Advanced AI assistant patterns
MSL includes intelligent agents for specification management:
Analyzes specifications for quality, suggests improvements, ensures AI readability.
@claude validate my payment specification for AI implementation
→ Receives quality score, improvements, and AI-readiness assessmentProcesses entire specification suites, identifies patterns, generates reports.
@claude analyze all specifications in /specs directory
→ Receives complete analysis with template opportunities→ Claude Code Agent Documentation
MSL is just enhanced markdown - no installation needed! Write your specifications anywhere using the patterns shown in the examples above.
# Your Project Specification
## Requirements
- REQ-001: Clear requirement statement
- REQ-002: Another requirementThat's it! Give your MSL specifications to AI assistants like Claude for implementation.
# GitHub Actions
- name: Validate Specifications
run: |
npx msl-validate ./specs --min-score 85
echo "✅ Specifications ready for AI implementation"| Challenge | Without MSL | With MSL |
|---|---|---|
| AI Understanding | Vague prompts → Guessed implementation | Precise specs → Exact implementation |
| Consistency | Every session different | Specifications persist |
| Quality | Hope AI gets it right | Validated before implementation |
| Collaboration | AIs work in isolation | AIs work from same specs |
| Maintenance | Context lost over time | Specifications are documentation |
---
id: user-api
---
# User Management API
## Requirements
- REQ-001: GET /users returns paginated user list
- REQ-002: GET /users/{id} returns single user or 404
- REQ-003: POST /users creates user, returns 201 with location
- REQ-004: All endpoints require Bearer token authentication
- REQ-005: Responses use JSON with consistent error formatAI implements complete REST API with error handling
# User Database
## Requirements
- REQ-001: Users table with id (UUID), email (unique), created_at
- REQ-002: Email must be lowercase, validated format
- REQ-003: Soft deletes via deleted_at timestamp
- REQ-004: Index on email for login performanceAI generates migration scripts and models
# Login Form Component
## Requirements
- REQ-001: Email and password inputs with validation
- REQ-002: Show inline errors on blur
- REQ-003: Disable submit during API call
- REQ-004: Redirect to dashboard on success
- REQ-005: Display API errors below formAI creates complete component with tests
# Create a spec
cat > todo-app.md << 'EOF'
# Todo App
## Requirements
- Add todos with enter key
- Mark todos complete
- Filter by status
- Persist to localStorage
EOF
# Give to your AI assistant
# "Implement this todo app: [paste todo-app.md]"- Read Why MSL? - Understand the AI revolution
- Follow Getting Started - Create your first spec
- Explore AI Workflows - Master AI collaboration
- Install MSL tools
- Write specifications for your current project
- Let AI implement them
- Experience 10x productivity
LiveSpec uses MSL to manage its own methodology specifications. A governance framework with 51 MSL specifications demonstrating:
- Scale: Complex self-referential specification systems
- Metaspecs: Specs about specs (framework governance)
- Domain extensions: Traceability patterns for governance frameworks
- Dogfooding: Framework built using its own methodology
A valuable reference for large specification suites and framework development.
- GitHub: github.com/chrs-myrs/msl-specification
- Discord: MSL Community - Share AI workflows and patterns
- Examples: Real-world specifications
- Contributing: How to contribute
As AI becomes more powerful, the need for structured specifications becomes more critical. MSL is the foundation for the next decade of software development.
Join thousands of developers who've stopped fighting with AI prompts and started shipping with MSL specifications.
→ Get Started Now | → Why MSL? | → AI Workflows
MSL: Where human intent meets AI implementation.