Metadata-Version: 2.4
Name: magic-spec
Version: 1.3.0
Summary: Magic Specification-Driven Development (SDD) Workflow
Project-URL: homepage, https://github.com/teratron/magic-spec
Project-URL: repository, https://github.com/teratron/magic-spec
Author-email: Oleg Alexandrov <alexandrovoleg.ru@gmail.com>
License: MIT License
License-File: LICENSE
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# 🪄 Magic Spec

[![NPM version](https://img.shields.io/npm/v/magic-spec?color=green&label=npm)](https://www.npmjs.com/package/magic-spec)
[![PyPI version](https://img.shields.io/pypi/v/magic-spec?color=blue&label=pypi)](https://pypi.org/project/magic-spec/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

**The Specification-Driven Development (SDD) Operating System for AI Agents.**

Stop your AI from writing code before it understands the problem. `magic-spec` installs a high-performance, structured pipeline — *Thought → Spec → Task → Run → Code* — directly into any project.

---

## ✨ Features

- 🏗️ **Deterministic Pipeline**: Forced structure ensures architectural integrity.
- 🎯 **Multi-Agent Core**: Works with Cursor, Windsurf, Claude, Gemini, and more.
- 🔍 **Auto-Retrospective**: Built-in self-analysis engine that improves your workflow automatically.
- 📦 **Thin-Client Installers**: Lightweight Node.js and Python installers for zero-friction setup.
- 🗺️ **Phased Planning**: Intelligent dependency tracking and implementation roadmaps.

---

## 🚀 Quick Start

Works with **any project** — Rust, Go, Python, JavaScript, C++, or anything else.

### Option A: Node.js (npx)

```bash
npx magic-spec@latest
```

### Option B: Python (uvx)

```bash
uvx magic-spec
```

**What happens next?**

1. Magic Spec deploys the `.magic/` engine and `.agent/` workflows.
2. An interactive onboarding tutorial (`magic.onboard`) helps you and your AI get started.
3. Your project gains a dedicated `.design/` workspace for Specifications, Rules, and Plans.

---

## 🧭 The Workflow

1. **Specification**: Convert raw ideas into formal, versioned specs.
2. **Task & Plan**: Generate a phased roadmap with atomic, trackable tasks.
3. **Run**: Execute the plan with automatic progress tracking and quality gates.
4. **Rule**: Manage project conventions in a central `RULES.md` constitution.

---

## 📖 Documentation & Guides

- [**Main Documentation**](./docs/README.md) — Detailed guide on workflows and architecture.
- [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
- [**Contributing**](./docs/contributing.md) — How to develop and extend the engine.

---

## 🤝 Compatibility

Magic Spec is optimized for the world's most powerful AI development environments:

- [**Cursor**](https://cursor.com) (Rule definitions & Agent Mode)
- [**Windsurf**](https://codeium.com/windsurf) (Cascade & Flows)
- [**GitHub Copilot**](https://github.com/features/copilot) (Custom Instructions)
- [**Claude**](https://claude.ai) (Project context)

---

## 📄 License

Distributed under the [MIT License](./LICENSE).  
© 2026 Oleg Alexandrov & teratron. ✨
