MetaSpec

🤖 Meta-Specification Framework for generating Spec-Driven X (SD-X) speckits for AI Agents

---

🎯 What is Spec-Driven?

Spec-Driven is using structured specifications to drive workflows - from requirements to implementation. Define specs first, validate and generate, then execute. This ensures clarity, consistency, and enables AI agents to understand and assist throughout the process.

💡 What is MetaSpec?

MetaSpec is a meta-specification framework that enables AI Agents to automatically generate production-ready speckits (Spec-Driven X toolkits).

Define your speckit once → Get complete development environment with CLI, parser, validator, templates, and AI agent support.

What are Speckits?

• Specialized toolkits generated by MetaSpec
• Carry domain specifications as core assets
• Include built-in SDX commands for development
• Follow spec-driven architecture patterns

What you can generate:
  ✅ SD-Development  - Spec-driven development
  ✅ SD-Design       - Spec-driven design systems  
  ✅ SD-Testing      - Spec-driven testing frameworks
  ✅ SD-Documentation - Spec-driven documentation
  ✅ SD-Operations   - Spec-driven operations
  ✅ SD-X            - Spec-driven generation for any domain

🌟 Key Features

1. Meta-Level - A meta-specification framework that generates speckits

2. Any Domain - Supports any domain, not limited to development

3. Full Lifecycle - Covers complete lifecycle (creation, updates, maintenance)

---

🚀 Quick Start

Installation

git clone https://github.com/ACNet-AI/MetaSpec.git
cd MetaSpec
uv pip install -e .  # or: pip install -e .

Create Your First Speckit

Option 1: Interactive (Recommended)

metaspec init                       # Interactive wizard - guides you through

Option 2: Quick start with template

metaspec init my-spec-kit --template mcp     # One command, done!

Option 3: Preview first

metaspec init my-spec-kit --template api --dry-run    # Preview
metaspec init my-spec-kit --template api              # Create

Result: Complete speckit with CLI, parser, validator, templates, and AI agent support!

---

📦 Features

Simple, powerful commands:

Command	Description
metaspec init [name]	🚀 Create spec-driven speckit (interactive or template-based)
metaspec search <query>	🔍 Search community speckits
metaspec install <name>	📦 Install speckit from community
metaspec list	📋 List installed speckits
metaspec info <name>	ℹ️ Show speckit information
metaspec contribute <name>	🤝 Contribute to community registry

Common usage:

# Create speckit (interactive)
metaspec init

# Create with template (fast)
metaspec init my-api-speckit --template api

# Preview before creating
metaspec init my-spec-kit --template mcp --dry-run

# Discover and install speckits
metaspec search "api"                # Search community
metaspec install api-speckit         # Install from community
metaspec list                        # List installed speckits

# Use installed speckits directly
api-speckit info                     # Direct usage (no metaspec prefix!)

What you get: CLI tools, parser, validator, templates, AGENTS.md, constitution, and full Python package structure.

🌟 Generated Speckits

MetaSpec generates independent, production-ready toolkits:

# Each generated speckit is a standalone CLI tool
cd my-speckit
./scripts/init.sh              # Install dependencies
my-speckit info                # Use directly (no metaspec prefix!)

# Generated speckits include built-in SDX commands (AI-assisted development)
# SDX Commands: /sdx.constitution, /sdx.specify, /sdx.plan, /sdx.implement, etc.

Key Principle: MetaSpec is a generator, not a runtime. Generated speckits are independent tools.

Built-in SDX Workflow: Every speckit includes 11 SDX commands for complete development lifecycle

---

🌐 Community

Discover and share speckits with the community:

📦 Awesome Spec Kits - A curated list of community speckits

For Users

# Search community speckits
metaspec search "api validation"

# Install from community
metaspec install <speckit-name>

# List installed speckits
metaspec list

# Get detailed information
metaspec info <command>

For Developers

# Contribute your speckit
metaspec contribute my-speckit
# → Generates metadata JSON
# → Submit PR to awesome-spec-kits

Join the community:

• 🚀 Create and share your speckit
• 📚 Community guide
• 💬 Discussions

---

🤖 AI Assistant Ready

MetaSpec is designed for AI agents with strong reasoning capabilities. Speckit creation requires meta-level system design, entity modeling, and domain research.

👉 Complete AI workflow guide: AGENTS.md

---

🤝 Works Well With

MetaSpec generates speckits. Since generated speckits are also projects, you can use spec-driven methodologies to develop them.

Tool	Purpose	Built-in?	Access Method
SDX Commands	Complete spec-driven workflow (11 commands)	✅ Yes	/sdx.* slash commands in generated speckits

Complete Workflow:

# 1️⃣ CREATE: Generate speckit
metaspec init my-spec-kit --template generic

# 2️⃣ DEVELOP: Use built-in SDX slash commands (no installation needed)
cd my-spec-kit
# Definition Commands (8) - Active development
# /sdx.constitution - Define speckit principles
# /sdx.specify      - Define entities and validation rules
# /sdx.clarify      - Clarify underspecified areas
# /sdx.plan         - Plan implementation architecture
# /sdx.tasks        - Generate actionable task lists
# /sdx.implement    - Execute implementation
# /sdx.checklist    - Validate specification quality
# /sdx.analyze      - Analyze consistency

# Evolution Commands (3) - Controlled changes
# /sdx.proposal     - Create change proposals
# /sdx.apply        - Apply approved changes
# /sdx.archive      - Archive completed changes

Advantages:

• ✅ Complete workflow built-in - Everything you need from day one
• ✅ AI-assisted - SDX commands guide development
• ✅ No external dependencies - All tools included

🚀 Ecosystem Vision

MetaSpec is not just a generator—it's a platform for speckits:

1. Create speckits with metaspec init
2. Develop with built-in SDX commands
3. Publish to community registry
4. Install and use directly - no prefix needed!

# Example: Developer workflow
metaspec init api-speckit --template generic
cd api-speckit
# ... develop using SDX commands ...
metaspec contribute api-speckit

# User workflow  
metaspec search "api"
metaspec install api-speckit

# Use directly (no metaspec prefix!)
api-speckit init my-api.json
api-speckit validate my-api.json

Future roadmap: Enhanced community features, version management, analytics

📖 Complete guide: See AGENTS.md

---

📖 Example

Quick Example: Create an API Speckit

# Step 1: Create speckit (interactive mode)
metaspec init
# Or use template mode for quick start
metaspec init api-spec-kit --template generic

# Step 2: What you get
# api-spec-kit/
#   ├── src/api_spec_kit/          # Python package
#   │   ├── cli/                    # CLI commands
#   │   ├── parser.py               # Parser
#   │   └── validator.py            # Validator
#   ├── .metaspec/
#   │   ├── commands/               # SDX commands (11 total)
#   │   └── templates/              # SDX templates
#   ├── specs/                      # Feature specifications
#   ├── templates/                  # User project templates
#   ├── AGENTS.md                   # AI workflow guide
#   ├── README.md                   # User documentation
#   └── pyproject.toml              # Package config

Develop the Generated Speckit

# Step 3: Install
cd api-spec-kit
pip install -e .

# Step 4: Define and implement using SDX commands (in Cursor/AI editor)
# /sdx.constitution  - Define design principles
# /sdx.specify       - Define domain protocol specification
# /sdx.specify       - Define speckit specification
# /sdx.plan          - Plan implementation architecture
# /sdx.tasks         - Break down implementation tasks
# /sdx.implement     - Implement your speckit

📂 More examples: See examples/ (MCP, API testing, design systems)

---

🛠️ Commands

# Generation
metaspec init [NAME] [OPTIONS]     # Create speckit (interactive or template-based)

# Community
metaspec search <query>            # Search community speckits
metaspec install <name>            # Install from community
metaspec contribute <name>         # Contribute to community

# Information
metaspec list                      # List installed speckits
metaspec info <name>               # Show speckit details
metaspec version                   # Show MetaSpec version

# Examples
metaspec init                      # Interactive mode
metaspec init my-speckit --template generic
metaspec search "api"              # Search community
metaspec install api-speckit       # Install
metaspec list                      # List installed

Use metaspec --help or metaspec <command> --help for detailed options

---

🧪 Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Code quality
ruff check src/
ruff format src/

📖 Contributing guide: See contributing.md

---

📚 Documentation

• quickstart.md - 5-minute tutorial
• AGENTS.md - AI workflow guide
• contributing.md - Contribution guide
• examples/ - Example meta-specs

---

🏗️ Status

v0.1.0 - Alpha Release 🎉

Core features complete: YAML validation, multi-domain generation, CLI tools, AI agent support, built-in SDX commands (11 commands), unified spec interface.

---

🤝 Contributing

Contributions welcome! See contributing.md for guidelines.

git clone https://github.com/ACNet-AI/MetaSpec.git
git checkout -b feature/your-feature
# Make changes, test, commit
git push origin feature/your-feature

---

📄 License

MIT License - see LICENSE

---

🙏 Acknowledgments

Inspired by Spec-Kit, Protocol Buffers, and OpenAPI.

---

Built for the Spec-Driven Development Community