magic-spec 1.5.207

Magic Specification-Driven Development (SDD) Workflow

🪄 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

Requirement	Details
Node.js	Version 16.x or higher (for npx method)
Python	Version 3.8 or higher (for uvx or pipx methods)
Git	Required for installing edge versions directly from GitHub
Terminal	tar utility (pre-installed on Windows/Linux/macOS)

📦 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

1. Download .magic/ and workflows/ from the GitHub repository.
2. 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:

Command	Purpose
/magic.spec	Create or update specifications
/magic.task	Generate implementation plan and tasks
/magic.run	Execute tasks from the plan
/magic.rule	Add or amend project conventions
/magic.analyze	Audit project health and detect drift

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

AI Agent / IDE	Shortcut Flag	Env Flag
Cursor (Agent Mode)	--cursor	--env cursor
Windsurf (Cascade)	--windsurf	--env windsurf
Claude Code	--claude	--env claude
Gemini CLI	--gemini	--env gemini
GitHub Copilot	--copilot	--env copilot
Roo Code	--roo	--env roo
Amp	--amp	--env amp
Amazon Q Developer	--q	--env q
Kilo Code	--kilocode	--env kilocode
Qwen Code	--qwen	--env qwen
OpenCode	--opencode	--env opencode
SHAI (OVHcloud)	--shai	--env shai
IBM Bob	--bob	--env bob
CodeBuddy	--codebuddy	--env codebuddy
Qoder IDE	--qoder	--env qoder
Codex CLI	--codex	--env codex
Auggie CLI	--augment	--env augment
Antigravity IDE	--antigravity	--env antigravity
Lingma IDE	--lingma	--env lingma

📚 Documentation

Document	Description
Main Documentation	Workflows, architecture, and advanced features
SDD Philosophy	Two-Layer Model, Integrity by Design, Self-Improving Feedback Loop
Installers Guide	Advanced CLI options and platform specifics
Contributing	How to develop, test, and extend the engine

🛟 Support

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

🗺️ Roadmap

• Multi-agent adapter system.
• 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.