magic-spec

v1.5.207

Published

10 days ago

Magic Specification-Driven Development (SDD) Workflow

0High
0Medium
0Low

🪄 Magic Spec

[!WARNING] Legacy Installers Deprecated (v1.5.x)
The npx magic-spec (npm) and uvx magic-spec (PyPI) packages will no longer receive updates as of v1.5.207. Archived releases remain available for historical reference:
npm: https://www.npmjs.com/package/magic-spec (last version: 1.5.207)
PyPI: https://pypi.org/project/magic-spec/ (last version: 1.5.207)
New users: See Installation for the GitHub-based setup. Existing users: See Migrating from the legacy installer.

📖 Description

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

magic-spec installs a structured pipeline — Thought → Spec → Task → Run → Code — directly into any project, regardless of the tech stack. It acts as a set of markdown-based workflow instructions for AI coding agents (Cursor, Windsurf, Claude Code, Gemini CLI, and others), enforcing a deterministic process that ensures the AI fully understands the problem before writing code.

💡 Idea  →  📋 Specification  →  🗺️ Task & Plan  →  ⚡ Run  →  🚀 Code

What Gets Installed

your-project/
├── .agents/workflows/   # Slash commands (magic.spec, magic.task, magic.run, ...)
├── .magic/              # SDD Engine (workflow logic and scripts — read-only)
└── .design/             # Your Design Workspace (INDEX.md, RULES.md, PLAN.md)

[!TIP] Magic Workspaces: Multiple isolated design environments within a single repo (e.g., .design/engine/, .design/web/). See workspaces.md for details.

⚙️ Requirements

📦 Installation

Works with any project — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.

Option A: Node.js (`npx`)

Stable Release:

# Basic installation (defaults to .agents/ folder)
npx magic-spec@latest

# Targeted installation for a specific AI agent
npx magic-spec@latest --cursor
npx magic-spec@latest --claude
npx magic-spec@latest --windsurf

Edge Version (GitHub):

npx --yes github:teratron/magic-spec

Option B: Python (`uvx`)

Stable Release:

# Basic installation
uvx magic-spec

# Targeted installation
uvx magic-spec --windsurf

Edge Version (GitHub):

uvx --from git+https://github.com/teratron/magic-spec.git magic-spec

Option C: Python (`pipx`)

pipx run magic-spec

Option D: Multi-Adapter Installation

Install support for multiple adapters at once:

npx magic-spec@latest --cursor --copilot --windsurf

Option E: Manual Installation

Download .magic/ and workflows/ from the GitHub repository.
Place files into your AI agent's instruction directory (e.g., .cursor/commands).

Post-Install: `.gitignore`

The installer automatically adds .magic/ and the adapter directory (e.g., .agents/) to .gitignore. These are installed dependencies (like node_modules/) — reinstall via npx magic-spec@latest rather than committing.

[!TIP] Vendoring: To commit the engine into your repo (so teammates get it without running the installer), remove the .magic/ and .agents/ entries from .gitignore.

🔄 Updating

# Check if update is available
npx magic-spec@latest --check

# Perform the update
npx magic-spec@latest --update

[!TIP] The update preserves your .design/ workspace and creates backups of .magic/ and .agents/. After updating, run /magic.analyze to ensure synchronization.

💬 Usage

Natural Language

Talk to your AI agent naturally — it will route to the correct workflow:

"Create a spec for user authentication" → Specification workflow
"Build an implementation plan" → Task & Plan workflow
"Execute the next task" → Run workflow
"Add a rule: always use Inter font" → Rule workflow
"Run a project audit" → Analyze workflow

Slash Commands

All core workflows are available as slash commands with optional arguments:

Commands with Arguments

Each command accepts optional arguments to scope the operation to a specific workspace or provide a directive:

# No arguments — operates across all workspaces
/magic.spec
/magic.task
/magic.run

# Workspace-scoped
/magic.task engine                     # Plan only for the "engine" workspace
/magic.run installers                  # Execute tasks in "installers" workspace
/magic.analyze engine                  # Analyze only the "engine" workspace

# With directive (quoted text)
/magic.task "decompose phase-2"        # Guided planning with focus
/magic.run "T-1A01"                    # Execute a specific task by ID
/magic.run "phase-2"                   # Execute all tasks in a phase
/magic.analyze "check API coverage"    # Focused analysis on a specific area

# Workspace + directive
/magic.run installers "phase-1"        # Execute phase 1 in "installers" workspace
/magic.task engine "only new specs"    # Plan only new specs in "engine" workspace

[!NOTE] For AI IDE users (Cursor, Windsurf, Claude Code, etc.): When you type / in the chat, a dropdown list of available commands appears and selecting one immediately executes it without arguments. If you need to pass arguments (workspace name, task ID, directive), type the full command manually instead of selecting from the dropdown. For example, type /magic.run "phase-2" directly rather than clicking /magic.run from the list.

🤝 Compatibility

Magic Spec provides native workflow generation for all major AI development environments.

Install with a shortcut flag (e.g., --cursor) or the environment flag (e.g., --env cursor).

📚 Documentation

🛟 Support

If you encounter issues or have questions — open an Issue on GitHub.

🗺️ Roadmap

[x] Multi-agent adapter system.
[x] Phased implementation planning.
[ ] Extended support for local-first LLM agents.
[ ] Advanced visual dashboard for project health.
[ ] Integration with CI/CD for automated spec validation.

🏗️ Contributing

We welcome contributions! See the Contributing Guide for details.

👥 Authors and Acknowledgments

Oleg Alexandrov — Creator and Lead Maintainer.
Special thanks to the AI agent community for inspiration and testing.

📄 License

Distributed under the Apache License 2.0.

📊 Project Status

Active Development (v1.5.207). We are constantly refining the SDD engine based on real-world usage.