meta-spec 0.7.3

Meta-specification framework for generating Spec-Driven X (SD-X) toolkits for AI agents

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-98%

---

🧭 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-98% token reductions (language-specific sections reach 97-98%).
• 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:

• 🚀 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
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:

1. Create speckits with metaspec init
2. Develop with built-in MetaSpec commands
3. Publish to community registry
4. 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

---

🏗️ Status

Current Version: v0.6.0 (Alpha) 🚀

Latest Updates (v0.6.0):

• ✨ Added metaspec sync command to update MetaSpec commands in existing speckits
• 📦 Version tracking in generated speckits (records MetaSpec version)
• 🔄 Safe and reversible updates with automatic backups

Core Features:

• ✅ Meta-specification framework with YAML validation
• ✅ Multi-domain speckit generation (SD-Development, SD-Design, SD-Testing, etc.)
• ✅ 19 AI-assisted MetaSpec commands (8 SDS + 8 SDD + 3 Evolution)
• ✅ Precision-guided navigation (84-98% token savings)
• ✅ Recursive tree structure for complex specifications
• ✅ CLI tools and community registry

Quality Metrics:

• ✅ 90.99% test coverage (151/151 tests passing)
• ✅ Full CLI functionality tested
• ✅ Production-ready code quality

📝 See CHANGELOG.md for 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