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 MetaSpec 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)

4. Precision-Guided Navigation - Built-in line-number navigation across 6 core commands lets AI jump directly to relevant sections with read_file(offset, limit), cutting token usage by 84-99%

🧭 Token Optimization

MetaSpec 0.5.4 introduces precision-guided navigation so AI agents can read just the slices of large command templates they need.

How it works: Every enhanced command begins with a 📖 Navigation Guide listing line ranges. Combine it with read_file(target_file, offset, limit) to stream only that segment.
Coverage: specify (SDS/SDD), implement (SDS/SDD), tasks (SDS), plan (SDD) — 8615 lines of navigation guidance overall.
Savings: Real-world scenarios show 84-99% token reductions (language-specific sections reach 97-99%).
More examples: See AGENTS.md → Token Optimization: Precision-Guided Navigation for full tables and best practices.

# Jump straight to CLI design section of SDD/specify
read_file("src/metaspec/templates/meta/sdd/commands/specify.md.j2", offset=390, limit=273)

# Grab Python-specific implementation steps only (97% savings)
read_file("src/metaspec/templates/meta/sdd/commands/implement.md.j2", offset=210, limit=25)

🚀 Quick Start

Installation

# Recommended: Use uv (10-100x faster) ⚡
uv pip install git+https://github.com/ACNet-AI/MetaSpec.git

# Or use pip
pip install git+https://github.com/ACNet-AI/MetaSpec.git

Other installation methods

Development mode:

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

Coming soon: pip install metaspec 🚀

Create Your First Speckit

Option 1: Interactive (Recommended)

metaspec init                       # Interactive wizard - guides you through

Option 2: Quick start

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

Option 3: Preview first

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

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

🌱 Why MetaSpec?

The Journey: From Practice to Insight

MetaSpec was born from real-world experience building spec-driven development tools:

🔧 Phase 1: Universal SDD Tools

Built spec-kit and OpenSpec - covering 0→1→N generic spec-driven development workflows
Proved SDD methodology works across different project scales

💡 Phase 2: The Domain Insight

Discovery: While practicing SDD, we realized AI needs domain-specific specifications to generate expected results
Example: To help AI develop MCP projects effectively, we need MCP domain specifications - not just generic development specs
Vision: Modular domain specifications 🧩 that can be combined and composed to guide AI to generate content matching our expectations

🚀 Phase 3: Beyond Development

Realization: This pattern isn't limited to software development
Breakthrough: Any domain can benefit from specification-driven workflows
Vision: A meta-framework that generates spec toolkits for ANY domain

Core Philosophy

MetaSpec is built on two fundamental concepts:

1️⃣ Domain Refinement

Specifications refine from general to specific through multiple levels
Example: Development Spec → MCP Development Spec → Weather Query MCP Spec
Each level adds more context and constraints, enabling more precise AI guidance

2️⃣ Modular Composition

Specifications are independent, reusable modules that can be composed in two ways:
- Compose specs: Combine sub-domain specs into a complete domain spec (Full-stack Web = Frontend + Backend + Database)
- Compose usage: Apply multiple specs to one project (MetaSpec uses SDS + SDD; MCP project uses MCP + Python + Testing)
This enables flexible reuse across different contexts and domains

Together, these create a flexible specification network where AI agents navigate domain knowledge through structured specs, combining them as needed to produce exactly what you envision.

📦 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 [--check-only]`	🤝 Validate & contribute to community

Common usage:

# Create speckit (interactive)
metaspec init

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

# Preview before creating
metaspec init my-spec-kit --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 MetaSpec commands (AI-assisted development)
# MetaSpec Commands: /metaspec.sds.*, /metaspec.sdd.*, /metaspec.* (19 commands total)

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

Built-in MetaSpec Workflow: Every speckit includes 19 MetaSpec commands for complete development lifecycle (8 SDS + 8 SDD + 3 Evolution)

Iteration-Aware Design: Commands check for existing output and support update/new/append modes, preserving history and tracking progress across iterations (Constitution Principle #6)

🌐 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

# Validate your speckit before contributing
metaspec contribute --check-only
# → Validates requirements (pyproject.toml, README, LICENSE, etc.)
# → Shows what's missing with fix suggestions

# Contribute your speckit (one command!)
metaspec contribute --open
# → Validates your project
# → Opens pre-filled GitHub issue in browser
# → Bot automatically extracts metadata from your repo
# → Done in ~30 seconds!

# Or just get the URL
metaspec contribute
# → Shows registration URL to paste in browser

# Preview metadata (optional)
metaspec contribute --save-json
# → Generates JSON file for preview
# → Note: Bot extracts from repo, JSON is optional

Join the community:

🤖 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
MetaSpec Commands	Complete spec-driven workflow (19 commands)	✅ Yes	`/metaspec.sds.`, `/metaspec.sdd.`, `/metaspec.*` slash commands in generated speckits

Complete Workflow:

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

# 2️⃣ DEVELOP: Use built-in MetaSpec slash commands (no installation needed)
cd my-spec-kit

# SDS Commands (8) - Define domain specification
# 
# Core Flow (2-5 commands depending on complexity):
#   Simple: constitution → specify → [clarify] → [checklist]
#   Complex: constitution → specify → [clarify] → plan → [checklist] → tasks → [analyze] → implement
#
# /metaspec.sds.constitution - Define specification design principles (required)
# /metaspec.sds.specify      - Define specification entities and operations (required)
# /metaspec.sds.clarify      - Clarify ambiguities (recommended, BEFORE plan, input quality gate)
# /metaspec.sds.plan         - Plan specification architecture (if complex) ⭐
# /metaspec.sds.checklist    - Validate requirements completeness (recommended, AFTER plan, quality gate)
# /metaspec.sds.tasks        - Break down specification work (if complex) ⭐
# /metaspec.sds.analyze      - Check task consistency (if complex, AFTER tasks, BEFORE implement, checkpoint) ⭐
# /metaspec.sds.implement    - Write specification documents, NOT code (if complex) ⭐

# SDD Commands (8) - Develop spec-driven toolkit (follows spec-kit workflow)
#   Complete: constitution → specify → [clarify] → plan → [checklist] → tasks → [analyze] → implement
#
# /metaspec.sdd.constitution - Define toolkit implementation principles (required)
# /metaspec.sdd.specify      - Define toolkit specifications (required)
# /metaspec.sdd.clarify      - Clarify technical decisions (recommended, BEFORE plan, input quality gate)
# /metaspec.sdd.plan         - Plan implementation architecture (required)
# /metaspec.sdd.checklist    - Validate requirements completeness (recommended, AFTER plan, quality gate)
# /metaspec.sdd.tasks        - Break down implementation work (required)
# /metaspec.sdd.analyze      - Check architecture consistency (recommended, AFTER tasks, BEFORE implement, checkpoint)
# /metaspec.sdd.implement    - Build your speckit - write code (required)

# Evolution Commands (3) - Controlled changes (shared)
# /metaspec.proposal "change" --type sds|sdd - Create change proposals
# /metaspec.apply <proposal-id>              - Apply approved changes
# /metaspec.archive <proposal-id>            - Archive completed changes

Advantages:

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

🚀 Ecosystem Vision

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

Create speckits with metaspec init
Develop with built-in MetaSpec commands
Publish to community registry
Install and use directly - no prefix needed!

# Example: Developer workflow
metaspec init api-speckit
cd api-speckit
# ... develop using MetaSpec 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

Create Your First Speckit

# Step 1: Interactive creation (recommended)
metaspec init

# Or quick start with defaults
metaspec init my-spec-kit

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

# Step 3: Install and develop
cd my-spec-kit
pip install -e .

# Step 4: Use built-in MetaSpec commands for AI-assisted development
#
# Phase 1: Define domain specification (SDS - 8 commands)
#   Simple Path: constitution → specify → [clarify] → [checklist]
#   Complex Path: constitution → specify → [clarify] → plan → [checklist] → tasks → [analyze] → implement
#
# Core (required):
# /metaspec.sds.constitution  - Define specification design principles
# /metaspec.sds.specify       - Define specification entities
#
# Quality gates (recommended):
# /metaspec.sds.clarify       - Clarify ambiguities (BEFORE plan, input quality gate)
#
# If complex (splitting needed):
# /metaspec.sds.plan          - Plan specification architecture ⭐
# /metaspec.sds.checklist     - Validate requirements completeness (AFTER plan, quality gate)
# /metaspec.sds.tasks         - Break down specification work ⭐
# /metaspec.sds.analyze       - Check task consistency (AFTER tasks, BEFORE implement, checkpoint) ⭐
# /metaspec.sds.implement     - Write specification documents (NOT code) ⭐

# Phase 2: Develop toolkit (SDD - 8 commands)
#   Complete Path: constitution → specify → [clarify] → plan → [checklist] → tasks → [analyze] → implement
#   (Same as spec-kit workflow - toolkit development always needs full process)
#
# Core (required):
# /metaspec.sdd.constitution  - Define toolkit implementation principles
# /metaspec.sdd.specify       - Define toolkit specifications
#
# Quality gates (recommended):
# /metaspec.sdd.clarify       - Clarify technical decisions (BEFORE plan, input quality gate)
#
# Core (required) - continued:
# /metaspec.sdd.plan          - Plan implementation architecture
# /metaspec.sdd.checklist     - Validate requirements completeness (AFTER plan, quality gate)
# /metaspec.sdd.tasks         - Break down implementation work
# /metaspec.sdd.analyze       - Check architecture consistency (AFTER tasks, BEFORE implement, checkpoint)
# /metaspec.sdd.implement     - Build your speckit (write code)

# Step 5: Share with community
metaspec contribute my-spec-kit

📂 More examples: See examples/ directory

👉 Community speckits: Check out Awesome Spec Kits for community-contributed toolkits

🛠️ 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 [--check-only] # Validate & contribute to community

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

# Maintenance (run in speckit directory)
metaspec sync                      # Sync commands to latest MetaSpec version
metaspec sync --check-only         # Check version without updating

# Examples
metaspec init                      # Interactive mode
metaspec init my-speckit           # Quick start (uses 'default')
metaspec init my-speckit default   # Explicit (same as above)
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

# Clone and install
git clone https://github.com/ACNet-AI/MetaSpec.git && cd MetaSpec
uv pip install -e ".[dev]"

# Run tests
uv run pytest                  # 151 tests, 90.99% coverage

# Code quality checks
uv run ruff check .            # Lint
uv run mypy src/metaspec       # Type check

📖 Contributing Guide

📚 Documentation

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

Iteration & Decision Guides:

Evolution Guide - When to use formal evolution vs fast iteration
Iteration Layers - How Evolution and Command layers work together
Iteration Roadmap - Which commands support iteration and why

📝 Release Notes

Current Version: v0.9.5 (Alpha) 🚀

Latest: Documentation optimization & logical consistency fixes. See CHANGELOG.md for full release history.

🤝 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.

A Meta-Specification Framework for Generating Spec-Driven Toolkits

GeezerVison

Latest commit

History

Folders and files

Repository files navigation

MetaSpec

🎯 What is Spec-Driven?

💡 What is MetaSpec?

🌟 Key Features

🧭 Token Optimization

🚀 Quick Start

Installation

Create Your First Speckit

🌱 Why MetaSpec?

The Journey: From Practice to Insight

Core Philosophy

📦 Features

🌟 Generated Speckits

🌐 Community

For Users

For Developers

🤖 AI Assistant Ready

🤝 Works Well With

🚀 Ecosystem Vision

📖 Example

Create Your First Speckit

🛠️ Commands

🧪 Development

📚 Documentation

📝 Release Notes

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Topics

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages