# MetaSpec

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![Status: Alpha](https://img.shields.io/badge/status-alpha-green.svg)]()
[![Tests: 151 Passing](https://img.shields.io/badge/tests-151%20passing-brightgreen.svg)]()
[![Coverage: 90.99%](https://img.shields.io/badge/coverage-90.99%25-brightgreen.svg)]()

---


## 🎯 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.

```bash
# 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

```bash
# 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
```

<details>
<summary>Other installation methods</summary>

**Development mode**:
```bash
git clone https://github.com/ACNet-AI/MetaSpec.git && cd MetaSpec
uv pip install -e .
```

**Coming soon**: `pip install metaspec` 🚀
</details>

### Create Your First Speckit

**Option 1: Interactive (Recommended)**

```bash
metaspec init                       # Interactive wizard - guides you through
```

**Option 2: Quick start**

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

**Option 3: Preview first**

```bash
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:**
```bash
# 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**:

```bash
# 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](memory/constitution.md#6-iteration-aware-design))

---

## 🌐 Community

Discover and share speckits with the community:

**📦 [Awesome Spec Kits](https://github.com/ACNet-AI/awesome-spec-kits)** - A curated list of community speckits

### For Users

```bash
# 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

```bash
# 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](https://github.com/ACNet-AI/awesome-spec-kits)
- 📚 [Community guide](./docs/community-registry.md)
- 💬 [Discussions](https://github.com/ACNet-AI/MetaSpec/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](./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**:

```bash
# 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!

```bash
# 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](./AGENTS.md)

---

## 📖 Example

### Create Your First Speckit

```bash
# 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/](./examples/) directory

👉 **Community speckits**: Check out [Awesome Spec Kits](https://github.com/ACNet-AI/awesome-spec-kits) for community-contributed toolkits

---

## 🛠️ Commands

```bash
# 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

```bash
# 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](./docs/contributing.md)

---

## 📚 Documentation

- **[quickstart.md](./docs/quickstart.md)** - 5-minute tutorial
- **[AGENTS.md](./AGENTS.md)** - AI workflow guide
- **[contributing.md](./docs/contributing.md)** - Contribution guide
- **[examples/](./examples/)** - Example meta-specs

**Iteration & Decision Guides**:
- **[Evolution Guide](./docs/evolution-guide.md)** - When to use formal evolution vs fast iteration
- **[Iteration Layers](./docs/iteration-layers.md)** - How Evolution and Command layers work together
- **[Iteration Roadmap](./docs/iteration-roadmap.md)** - 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](./CHANGELOG.md) for release history

---

## 🤝 Contributing

Contributions welcome! See [contributing.md](./docs/contributing.md) for guidelines.

```bash
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](./LICENSE)

---

## 🙏 Acknowledgments

Inspired by [Spec-Kit](https://github.com/github/spec-kit), [Protocol Buffers](https://protobuf.dev/), and [OpenAPI](https://www.openapis.org/).

---

**A Meta-Specification Framework for Generating Spec-Driven Toolkits**
