🪄 Magic Spec

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

⚙️ 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

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.

🔄 Updating

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

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

💬 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

🤝 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

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