magic-spec 1.4.15 → 1.4.162

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +35 -1
  2. package/README.md +325 -258
  3. package/installers/config.json +9 -1
  4. package/installers/node/index.js +95 -27
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,7 +5,41 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
- ## [1.4.15] - 2026-03-02
8
+ ## [1.4.162] - 2026-03-12
9
+
10
+ ### Added
11
+
12
+ - **Session Isolation Rule (C17)**: Formalized the requirement for "New Chat" sessions between major workflow transitions (Spec → Task → Run) to prevent context bleed-over and hallucinations.
13
+ - **Multi-Workspace Support (C22)**: Enhanced `check-prerequisites.js` and `init.js` to support nested workspaces with inherited root rules.
14
+ - **Model-Aware History**: Updated engine history schema to include AI Model information, improving auditability of generated code.
15
+
16
+ ### Changed
17
+
18
+ - **Task Checklist Logic**: Consolidated implementation checklists into `TASKS.md` for better execution tracking and status reporting.
19
+ - **Gitignore Resilience**: Improved installers to automatically manage `.gitignore` entries for `.magic/` and `.agent/` directories with idempotent updates.
20
+ - **Onboarding Safety**: Added production data collision guards to `onboard.md` to prevent accidental overwrites of existing project plans.
21
+
22
+ ### Fixed
23
+
24
+ - **Error Reporting**: Enhanced `check-prerequisites.js` with structured, actionable JSON error suggestions.
25
+ - **Path Handling**: Fixed Windows-specific path issues in installer scripts.
26
+
27
+ ## [1.4.162] - 2026-03-03
28
+
29
+ ### Added
30
+
31
+ - **Regression Test T85**: Verifies mandatory engine integrity HALT when `.magic/` files are tampered (C1 enforcement).
32
+
33
+ ### Changed
34
+
35
+ - **Engine Integrity Halt**: Upgraded `check-prerequisites.js` to set `ok: false` on checksum mismatches, ensuring a hard HALT during pre-flight checks.
36
+ - **History Auto-Heal**: Enhanced `executor.js` to automatically recreate the `.magic/history/` directory and missing history files if deleted.
37
+
38
+ ### Fixed
39
+
40
+ - **Resilient Logic**: Improved `check-prerequisites.js` to distinguish between critical engine integrity (HALT) and project data drift (WARNING), preserving self-healing capabilities.
41
+
42
+ ## [1.4.162] - 2026-03-02
9
43
 
10
44
  ### Changed
11
45
 
package/README.md CHANGED
@@ -1,258 +1,325 @@
1
- # 🪄 Magic Spec
2
-
3
- [![NPM version](https://img.shields.io/npm/v/magic-spec?color=green&label=npm)](https://www.npmjs.com/package/magic-spec)
4
- [![PyPI version](https://img.shields.io/pypi/v/magic-spec?color=blue&label=pypi)](https://pypi.org/project/magic-spec/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
6
-
7
- ## 📖 Description
8
-
9
- **The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
10
-
11
- Stop your AI from writing fragile code before it fully understands the problem. `magic-spec` installs a high-performance, structured pipeline — *Thought → Spec → Task → Run → Code* — directly into any project, regardless of the tech stack.
12
-
13
- Whether you are a **coding novice** building your first application or a **senior engineer** architecting enterprise systems, Magic Spec brings **maximum automation** and professional rigor to your development process. It enforces a deterministic workflow that ensures your AI agent perfectly aligns with your vision before writing a single line of code.
14
-
15
- ### The Core Concept
16
-
17
- `magic-spec` is a set of **markdown-based workflow instructions** specifically designed for AI coding agents like Cursor, Windsurf, Claude, and Gemini. It acts as a project-level operating system that orchestrates agentic development.
18
-
19
- Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
20
-
21
- ```plaintext
22
- 💡 Idea → 📋 Specification → 🗺️ Task & Plan → ⚡ Run → 🚀 Code
23
- ```
24
-
25
- Once initialized, your AI agent will automatically:
26
-
27
- - Formulate a strong conceptual and technical specification.
28
- - Build a phased implementation plan with hierarchical dependencies.
29
- - Decompose the plan into prioritized, atomic, trackable tasks.
30
- - Facilitate safe architectural brainstorming via **Explore Mode**.
31
- - Analyze its own workflow and suggest improvements via Auto-Retrospectives.
32
-
33
- ### What Gets Installed
34
-
35
- After running the installer, your project directory will be augmented with the following structure:
36
-
37
- ```plaintext
38
- root-project/
39
- ├── .agent/workflows/ # Slash commands wrapper (e.g., magic.spec, magic.task)
40
- ├── .magic/ # The SDD Engine (workflow logic and scripts - read-only)
41
- └── .design/ # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
42
- ```
43
-
44
- 1. **`.magic/`**: Deploys the core SDD engine.
45
- 2. **`.agent/`**: Sets up workflows for your AI.
46
- 3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
47
- 4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
48
-
49
- > [!TIP]
50
- > **Magic Workspaces**: Magic Spec supports multiple, isolated design environments within a single repository (e.g., `.design/engine/`, `.design/installers/`). This allows you to manage fundamentally different project domains without specification overlap, while sharing a single core engine. See [workspaces.md](./workspaces.md) for details.
51
-
52
- ## 🖼️ Visuals
53
-
54
- The engine enforces a rigorous, unskippable pipeline: **Idea → Specification → Task & Plan → Code**. AI agents are prevented from jumping straight to coding. They must first formally specify the solution, then break it down into a concrete plan and tasks, and only then proceed to execution.
55
-
56
- ```mermaid
57
- flowchart TB
58
- IDEA(["💡 Idea"])
59
-
60
- subgraph BOX ["Magic Spec"]
61
- direction TB
62
-
63
- SPEC["📋 Spec"]
64
-
65
- subgraph TASK ["🗺️ Task"]
66
- direction TB
67
- PLAN["📐 Plan"]
68
- TASKS["📌 Tasks"]
69
- PLAN --> TASKS
70
- end
71
-
72
- RUN["⚡ Run"]
73
-
74
- SPEC --> PLAN
75
- TASKS --> RUN
76
- end
77
-
78
- CODE(["🚀 Code"])
79
-
80
- IDEA --> SPEC
81
- RUN --> CODE
82
-
83
- style IDEA fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
84
- style CODE fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
85
-
86
- style BOX fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
87
-
88
- style SPEC fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
89
- style RUN fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
90
-
91
- style TASK fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
92
- style PLAN fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
93
- style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
94
- ```
95
-
96
- ## ⚙️ Requirements
97
-
98
- Before installing Magic Spec, ensure you have one of the following available on your system:
99
-
100
- | Requirement | Details |
101
- | :--- | :--- |
102
- | **Node.js** | Version `16.x` or higher (for `npx` method) |
103
- | **Python** | Version `3.8` or higher (for `uvx` or `pipx` methods) |
104
- | **Git** | Required for installing edge versions directly from GitHub |
105
- | **Terminal** | `tar` utility (pre-installed on Windows/Linux/macOS) |
106
-
107
- ## 📦 Installation
108
-
109
- Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
110
-
111
- ### Option A: Node.js (`npx`)
112
-
113
- **Stable Release:**
114
-
115
- ```bash
116
- # Basic installation (defaults to .agent/ folder)
117
- npx magic-spec@latest
118
-
119
- # Targeted installation for Cursor
120
- npx magic-spec@latest --cursor
121
- ```
122
-
123
- **Edge Version (GitHub):**
124
-
125
- ```bash
126
- npx --yes github:teratron/magic-spec
127
- ```
128
-
129
- ### Option B: Python (`uvx`)
130
-
131
- **Stable Release:**
132
-
133
- ```bash
134
- # Basic installation
135
- uvx magic-spec
136
-
137
- # Targeted installation for Windsurf
138
- uvx magic-spec --windsurf
139
- ```
140
-
141
- **Edge Version (GitHub):**
142
-
143
- ```bash
144
- uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
145
- ```
146
-
147
- ### Option C: Python (`pipx`)
148
-
149
- ```bash
150
- pipx run magic-spec
151
- ```
152
-
153
- ### Option D: Multi-Adapter Installation
154
-
155
- You can install support for multiple adapters at once:
156
-
157
- ```bash
158
- npx magic-spec@latest --cursor --copilot --windsurf
159
- ```
160
-
161
- ### Option E: Manual Installation
162
-
163
- If automated installers do not fit your environment:
164
-
165
- 1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
166
- 2. **Workflows**: Download command wrappers from [`.agent/workflows/`](https://github.com/teratron/magic-spec/tree/main/.agent/workflows).
167
- 3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
168
-
169
- ## 🔄 Updating
170
-
171
- Keep your SDD engine up to date with the latest logic and features:
172
-
173
- ```bash
174
- # Check if update is available
175
- npx magic-spec@latest --check
176
-
177
- # Perform the update
178
- npx magic-spec@latest --update
179
- ```
180
-
181
- > [!TIP]
182
- > The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agent/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort).
183
-
184
- ## 💬 Usage
185
-
186
- Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
187
-
188
- - *"Dispatch this thought into specs..."* → Triggers **Specification** workflow.
189
- - *"Create an implementation plan"* → Triggers **Task & Plan** workflow.
190
- - *"Execute the next task"* → Triggers **Run** workflow.
191
- - *"Add a rule: always use Inter font"* → Triggers **Rule** workflow.
192
-
193
- ### 🤝 Compatibility
194
-
195
- Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
196
-
197
- You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
198
-
199
- | AI Agent / IDE | Shortcut Flag | Env Flag |
200
- | :--- | :--- | :--- |
201
- | [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
202
- | [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
203
- | [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
204
- | [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
205
- | [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
206
- | **Roo Code** | `--roo` | `--env roo` |
207
- | **Amp** | `--amp` | `--env amp` |
208
- | **Amazon Q Developer** | `--q` | `--env q` |
209
- | **Kilo Code** | `--kilocode` | `--env kilocode` |
210
- | **Qwen Code** | `--qwen` | `--env qwen` |
211
- | **OpenCode** | `--opencode` | `--env opencode` |
212
- | **SHAI (OVHcloud)** | `--shai` | `--env shai` |
213
- | **IBM Bob** | `--bob` | `--env bob` |
214
- | **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
215
- | **Qoder IDE** | `--qoder` | `--env qoder` |
216
- | **Codex CLI** | `--codex` | `--env codex` |
217
- | **Auggie CLI** | `--augment` | `--env augment` |
218
- | **Antigravity IDE** | `--antigravity` | `--env antigravity` |
219
- | **Lingma IDE** | `--lingma` | `--env lingma` |
220
-
221
- ## 📚 Documentation
222
-
223
- - [**Main Documentation**](./docs/README.md) — Detailed guide on workflows, architecture, and advanced features.
224
- - [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
225
- - [**Contributing**](./docs/contributing.md) — How to develop, test, and extend the engine.
226
-
227
- ## 🛟 Support
228
-
229
- If you encounter issues or have questions:
230
-
231
- - Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
232
- - Run `magic.onboard` in your agent to restart the interactive tutorial.
233
-
234
- ## 🗺️ Roadmap
235
-
236
- - [x] Multi-agent adapter system.
237
- - [x] Phased implementation planning.
238
- - [ ] Extended support for local-first LLM agents.
239
- - [ ] Advanced visual dashboard for project health.
240
- - [ ] Integration with CI/CD for automated spec validation.
241
-
242
- ## 🏗️ Contributing
243
-
244
- We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
245
- Please see [**Contributing Guide**](./docs/contributing.md) for details.
246
-
247
- ## 👥 Authors and Acknowledgments
248
-
249
- - **Oleg Alexandrov** — Creator and Lead Maintainer.
250
- - Special thanks to the AI agent community for inspiration and testing.
251
-
252
- ## 📄 License
253
-
254
- Distributed under the [MIT License](./LICENSE).
255
-
256
- ## 📊 Project Status
257
-
258
- **Active Development** (v1.x). We are constantly refining the SDD engine based on real-world usage.
1
+ # 🪄 Magic Spec
2
+
3
+ [![NPM version](https://img.shields.io/npm/v/magic-spec?color=green&label=npm)](https://www.npmjs.com/package/magic-spec)
4
+ [![PyPI version](https://img.shields.io/pypi/v/magic-spec?color=blue&label=pypi)](https://pypi.org/project/magic-spec/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
6
+
7
+ ## 📖 Description
8
+
9
+ **The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
10
+
11
+ Stop your AI from writing fragile code before it fully understands the problem. `magic-spec` installs a high-performance, structured pipeline — *Thought → Spec → Task → Run → Code* — directly into any project, regardless of the tech stack.
12
+
13
+ Whether you are a **coding novice** building your first application or a **senior engineer** architecting enterprise systems, Magic Spec brings **maximum automation** and professional rigor to your development process. It enforces a deterministic workflow that ensures your AI agent perfectly aligns with your vision before writing a single line of code.
14
+
15
+ ### The Core Concept
16
+
17
+ `magic-spec` is a set of **markdown-based workflow instructions** specifically designed for AI coding agents like Cursor, Windsurf, Claude, and Gemini. It acts as a project-level operating system that orchestrates agentic development.
18
+
19
+ Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
20
+
21
+ ```plaintext
22
+ 💡 Idea → 📋 Specification → 🗺️ Task & Plan → ⚡ Run → 🚀 Code
23
+ ```
24
+
25
+ Once initialized, your AI agent will automatically:
26
+
27
+ - Formulate a strong conceptual and technical specification.
28
+ - Build a phased implementation plan with hierarchical dependencies.
29
+ - Decompose the plan into prioritized, atomic, trackable tasks.
30
+ - Facilitate safe architectural brainstorming via **Explore Mode**.
31
+ - Analyze its own workflow and suggest improvements via Auto-Retrospectives.
32
+
33
+ ### What Gets Installed
34
+
35
+ After running the installer, your project directory will be augmented with the following structure:
36
+
37
+ ```plaintext
38
+ root-project/
39
+ ├── .agent/workflows/ # Slash commands wrapper (e.g., magic.spec, magic.task)
40
+ ├── .magic/ # The SDD Engine (workflow logic and scripts - read-only)
41
+ └── .design/ # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
42
+ ```
43
+
44
+ 1. **`.magic/`**: Deploys the core SDD engine.
45
+ 2. **`.agent/`**: Sets up workflows for your AI.
46
+ 3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
47
+ 4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
48
+
49
+ > [!TIP]
50
+ > **Magic Workspaces**: Magic Spec supports multiple, isolated design environments within a single repository (e.g., `.design/engine/`, `.design/installers/`). This allows you to manage fundamentally different project domains without specification overlap, while sharing a single core engine. See [workspaces.md](./workspaces.md) for details.
51
+
52
+ ## 🧠 The SDD Philosophy
53
+
54
+ > *"No code without a spec. No spec without a plan."*
55
+
56
+ Magic Spec is built around a single conviction: **AI agents write better code when they are forced to think before they act.** Left unconstrained, they jump straight to implementation — producing code that is fragile, misaligned, and expensive to refactor. Magic Spec installs a structured pipeline that makes this impossible.
57
+
58
+ ### Human-Minimal Engineering (Autonomous Partner)
59
+
60
+ The core design goal is to **keep humans out of the loop as much as possible** — without sacrificing control over what actually matters. Magic Spec moves from manual "Status Gates" to an **Autonomous Partner** model.
61
+
62
+ #### Trust Mode: Encapsulated Logic
63
+
64
+ Once you describe what you want, the engine takes over:
65
+
66
+ - **Type A — "AI Trust"**: You provide intent, the agent handles the rest (`Draft -> RFC -> Stable -> Plan -> Run`). The internal SDD ceremony is **encapsulated** — you only see the result and a final "Go" gate.
67
+ - **Type B — "Expert Audit"**: You maintain full control. Inspect `.design/` at any time to review specifications and plans. The rigor is there for when you need it.
68
+
69
+ #### Silent Orchestration
70
+
71
+ - **Auto-Stabilization**: Specifications are drafted, reviewed, and promoted to `Stable` automatically if the logic is clear.
72
+ - **Zero-Prompt Planning**: Tasks are decomposed, prioritized, and scheduled without interrupting your flow.
73
+ - **Silent Operations**: Phases execute end-to-end: retrospectives, changelogs, and context regeneration happen silently.
74
+ - **Single Execution Gate**: The only mandatory prompt is the final sign-off before implementation begins.
75
+
76
+ Everything else is automated. The agent does the engineering. You approve the direction.
77
+
78
+ ### Two-Layer Specification Model
79
+
80
+ Every specification in Magic Spec belongs to one of two layers, and this separation is strictly enforced:
81
+
82
+ **Layer 1 — Concept** (`layer: concept`)
83
+ Technology-agnostic. Describes *what* the system must do: business rules, domain invariants, data contracts, and behavioral requirements. A Layer 1 spec can be ported to any tech stack without modification. It is the source of truth for the entire implementation.
84
+
85
+ **Layer 2 — Implementation** (`layer: implementation`)
86
+ Stack-specific. Describes *how* a Layer 1 concept is realized in a concrete technology (e.g., a Node.js REST API, a PostgreSQL schema, a React component). Every Layer 2 spec must declare its parent via `Implements: {l1-file.md}` and cannot reach `RFC` or `Stable` status until its parent is `Stable`.
87
+
88
+ This separation prevents a common failure mode in AI-assisted development: mixing "what we want" with "how we build it" in a single document, which leads to specs that are impossible to reuse, validate, or evolve independently.
89
+
90
+ > **Why this matters in practice:** Imagine you built your backend on Node.js + PostgreSQL. Six months later, performance demands require a migration to Go + ScyllaDB. With a two-layer model, your Layer 1 specs — authentication rules, data contracts, business logic — remain completely intact. Only the Layer 2 specs are rewritten to reflect the new stack. Your AI agent gets a clean, unambiguous brief for the migration without you having to re-explain the entire domain from scratch.
91
+
92
+ ### Integrity by Design
93
+
94
+ The engine actively protects specification integrity throughout the project lifecycle:
95
+
96
+ - **Quarantine Cascade**: If a Layer 1 spec is destabilized (demoted from `Stable`), all dependent Layer 2 specs are automatically flagged and their tasks are blocked. The plan cannot proceed on a broken foundation.
97
+ - **Session Isolation (Phase Gates)**: To prevent AI "hallucinations" and context bleed-over, major workflow transitions enforce a **Hard Stop** (e.g., from Specification to Planning). You are required to physically open a "New Chat" in your IDE to proceed. Simply telling the AI to "forget" does not clear its context window reliably.
98
+ - **Registry Parity**: Every spec that exists on disk must be registered in `INDEX.md`. Every registered spec must appear in the implementation plan or the backlog. Orphaned specs are treated as critical blockers.
99
+ - **Rules Parity**: If project conventions change (`RULES.md`), any existing task plan is flagged as stale. The agent will not execute tasks generated under outdated rules without an explicit sync.
100
+ - **Engine Integrity**: Core engine files are checksummed. Any untracked modification halts all workflows until the engine state is reconciled.
101
+
102
+ ### Self-Improving Feedback Loop
103
+
104
+ Magic Spec includes a built-in retrospective engine that runs automatically at two levels:
105
+
106
+ - **Level 1** fires after every phase completes: captures a lightweight snapshot of spec health, task metrics, and signal status.
107
+ - **Level 2** fires when the full plan is complete: performs a deep audit — identifying spec drift, blocked-task patterns, shadow logic, and workflow friction — then produces actionable recommendations.
108
+
109
+ These retrospectives feed back into the specification layer, closing the loop between what was planned and what was actually built.
110
+
111
+ ## 🖼️ Visuals
112
+
113
+ The engine enforces a rigorous, unskippable pipeline: **Idea → Specification → Task & Plan → Code**. AI agents are prevented from jumping straight to coding. They must first formally specify the solution, then break it down into a concrete plan and tasks, and only then proceed to execution.
114
+
115
+ ```mermaid
116
+ flowchart TB
117
+ IDEA(["💡 Idea"])
118
+
119
+ subgraph BOX ["Magic Spec"]
120
+ direction TB
121
+
122
+ SPEC["📋 Spec"]
123
+
124
+ subgraph TASK ["🗺️ Task"]
125
+ direction TB
126
+ PLAN["📐 Plan"]
127
+ TASKS["📌 Tasks"]
128
+ PLAN --> TASKS
129
+ end
130
+
131
+ RUN["⚡ Run"]
132
+
133
+ SPEC --> PLAN
134
+ TASKS --> RUN
135
+ end
136
+
137
+ CODE(["🚀 Code"])
138
+
139
+ IDEA --> SPEC
140
+ RUN --> CODE
141
+
142
+ style IDEA fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
143
+ style CODE fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
144
+
145
+ style BOX fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
146
+
147
+ style SPEC fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
148
+ style RUN fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
149
+
150
+ style TASK fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
151
+ style PLAN fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
152
+ style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
153
+ ```
154
+
155
+ ## ⚙️ Requirements
156
+
157
+ Before installing Magic Spec, ensure you have one of the following available on your system:
158
+
159
+ | Requirement | Details |
160
+ | :--- | :--- |
161
+ | **Node.js** | Version `16.x` or higher (for `npx` method) |
162
+ | **Python** | Version `3.8` or higher (for `uvx` or `pipx` methods) |
163
+ | **Git** | Required for installing edge versions directly from GitHub |
164
+ | **Terminal** | `tar` utility (pre-installed on Windows/Linux/macOS) |
165
+
166
+ ## 📦 Installation
167
+
168
+ Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
169
+
170
+ ### Option A: Node.js (`npx`)
171
+
172
+ **Stable Release:**
173
+
174
+ ```bash
175
+ # Basic installation (defaults to .agent/ folder)
176
+ npx magic-spec@latest
177
+
178
+ # Targeted installation for Cursor
179
+ npx magic-spec@latest --cursor
180
+ ```
181
+
182
+ **Edge Version (GitHub):**
183
+
184
+ ```bash
185
+ npx --yes github:teratron/magic-spec
186
+ ```
187
+
188
+ ### Option B: Python (`uvx`)
189
+
190
+ **Stable Release:**
191
+
192
+ ```bash
193
+ # Basic installation
194
+ uvx magic-spec
195
+
196
+ # Targeted installation for Windsurf
197
+ uvx magic-spec --windsurf
198
+ ```
199
+
200
+ **Edge Version (GitHub):**
201
+
202
+ ```bash
203
+ uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
204
+ ```
205
+
206
+ ### Option C: Python (`pipx`)
207
+
208
+ ```bash
209
+ pipx run magic-spec
210
+ ```
211
+
212
+ ### Option D: Multi-Adapter Installation
213
+
214
+ You can install support for multiple adapters at once:
215
+
216
+ ```bash
217
+ npx magic-spec@latest --cursor --copilot --windsurf
218
+ ```
219
+
220
+ ### Option E: Manual Installation
221
+
222
+ If automated installers do not fit your environment:
223
+
224
+ 1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
225
+ 2. **Workflows**: Download command wrappers from [`.agent/workflows/`](https://github.com/teratron/magic-spec/tree/main/.agent/workflows).
226
+ 3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
227
+
228
+ ## 🔄 Updating
229
+
230
+ Keep your SDD engine up to date with the latest logic and features:
231
+
232
+ ```bash
233
+ # Check if update is available
234
+ npx magic-spec@latest --check
235
+
236
+ # Perform the update
237
+ npx magic-spec@latest --update
238
+ ```
239
+
240
+ > [!TIP]
241
+ > The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agent/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort).
242
+
243
+ ### Post-Install: `.gitignore`
244
+
245
+ The installer automatically adds `.magic/` and the adapter directory (e.g., `.agent/`, `.cursor/rules/`) to your project's `.gitignore`. These directories are **installed dependencies** — similar to `node_modules/` — and should be reinstalled via `npx magic-spec@latest` rather than committed to version control.
246
+
247
+ > [!TIP]
248
+ > **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.agent/` entries from your `.gitignore`.
249
+
250
+ ## 💬 Usage
251
+
252
+ Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
253
+
254
+ - *"Dispatch this thought into specs..."* → Triggers **Specification** workflow.
255
+ - *"Run a project audit"*, *"magic.analyze"* → Triggers **Analyze** (Ventilation) workflow.
256
+ - *"Create an implementation plan"* → Triggers **Task & Plan** workflow.
257
+ - *"Execute the next task"* → Triggers **Run** workflow.
258
+ - *"Add a rule: always use Inter font"* → Triggers **Rule** workflow.
259
+
260
+ ### 🤝 Compatibility
261
+
262
+ Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
263
+
264
+ You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
265
+
266
+ | AI Agent / IDE | Shortcut Flag | Env Flag |
267
+ | :--- | :--- | :--- |
268
+ | [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
269
+ | [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
270
+ | [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
271
+ | [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
272
+ | [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
273
+ | **Roo Code** | `--roo` | `--env roo` |
274
+ | **Amp** | `--amp` | `--env amp` |
275
+ | **Amazon Q Developer** | `--q` | `--env q` |
276
+ | **Kilo Code** | `--kilocode` | `--env kilocode` |
277
+ | **Qwen Code** | `--qwen` | `--env qwen` |
278
+ | **OpenCode** | `--opencode` | `--env opencode` |
279
+ | **SHAI (OVHcloud)** | `--shai` | `--env shai` |
280
+ | **IBM Bob** | `--bob` | `--env bob` |
281
+ | **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
282
+ | **Qoder IDE** | `--qoder` | `--env qoder` |
283
+ | **Codex CLI** | `--codex` | `--env codex` |
284
+ | **Auggie CLI** | `--augment` | `--env augment` |
285
+ | **Antigravity IDE** | `--antigravity` | `--env antigravity` |
286
+ | **Lingma IDE** | `--lingma` | `--env lingma` |
287
+
288
+ ## 📚 Documentation
289
+
290
+ - [**Main Documentation**](./docs/README.md) — Detailed guide on workflows, architecture, and advanced features.
291
+ - [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
292
+ - [**Contributing**](./docs/contributing.md) — How to develop, test, and extend the engine.
293
+
294
+ ## 🛟 Support
295
+
296
+ If you encounter issues or have questions:
297
+
298
+ - Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
299
+ - Run `magic.onboard` in your agent to restart the interactive tutorial.
300
+
301
+ ## 🗺️ Roadmap
302
+
303
+ - [x] Multi-agent adapter system.
304
+ - [x] Phased implementation planning.
305
+ - [ ] Extended support for local-first LLM agents.
306
+ - [ ] Advanced visual dashboard for project health.
307
+ - [ ] Integration with CI/CD for automated spec validation.
308
+
309
+ ## 🏗️ Contributing
310
+
311
+ We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
312
+ Please see [**Contributing Guide**](./docs/contributing.md) for details.
313
+
314
+ ## 👥 Authors and Acknowledgments
315
+
316
+ - **Oleg Alexandrov** — Creator and Lead Maintainer.
317
+ - Special thanks to the AI agent community for inspiration and testing.
318
+
319
+ ## 📄 License
320
+
321
+ Distributed under the [MIT License](./LICENSE).
322
+
323
+ ## 📊 Project Status
324
+
325
+ **Active Development** (v1.x). We are constantly refining the SDD engine based on real-world usage.
package/installers/config.json CHANGED
@@ -5,8 +5,13 @@
5
5
  "engineDir": ".magic",
6
6
  "agentDir": ".agent",
7
7
  "workflowsDir": "workflows",
8
+ "designDir": ".design",
9
+ "versionFile": ".version",
10
+ "checksumsFile": ".checksums",
11
+ "historyDir": "history",
8
12
  "defaultExt": ".md",
9
13
  "workflows": [
14
+ "magic.analyze",
10
15
  "magic.onboard",
11
16
  "magic.rule",
12
17
  "magic.run",
@@ -32,7 +37,7 @@
32
37
  "scripts/init.js",
33
38
  "templates/plan.md",
34
39
  "templates/retrospective.md",
35
- "templates/specification.md",
40
+ "templates/spec.md",
36
41
  "templates/tasks.md"
37
42
  ],
38
43
  "download": {
@@ -64,6 +69,9 @@
64
69
  ],
65
70
  "docsDir": "docs"
66
71
  },
72
+ "git": {
73
+ "defaultBranch": "master"
74
+ },
67
75
  "tests": {
68
76
  "sandboxDir": "installers/tests/sandbox",
69
77
  "adaptersJson": "installers/adapters.json",
package/installers/node/index.js CHANGED
@@ -77,6 +77,11 @@ function loadInstallerConfig() {
77
77
  failConfig("field 'magicFiles' must be an array of strings");
78
78
  }
79
79
 
80
+ const designDir = requireNonEmptyString(parsed.designDir, 'designDir');
81
+ const versionFile = requireNonEmptyString(parsed.versionFile, 'versionFile');
82
+ const checksumsFile = requireNonEmptyString(parsed.checksumsFile, 'checksumsFile');
83
+ const historyDir = requireNonEmptyString(parsed.historyDir, 'historyDir');
84
+
80
85
  return {
81
86
  githubRepo,
82
87
  packageName,
@@ -84,6 +89,10 @@ function loadInstallerConfig() {
84
89
  engineDir,
85
90
  agentDir,
86
91
  workflowsDir,
92
+ designDir,
93
+ versionFile,
94
+ checksumsFile,
95
+ historyDir,
87
96
  defaultExt,
88
97
  workflows,
89
98
  magicFiles,
@@ -102,6 +111,10 @@ const WORKFLOWS_DIR = INSTALLER_CONFIG.workflowsDir;
102
111
  const DEFAULT_EXT = INSTALLER_CONFIG.defaultExt;
103
112
  const WORKFLOWS = INSTALLER_CONFIG.workflows;
104
113
  const MAGIC_FILES = INSTALLER_CONFIG.magicFiles;
114
+ const DESIGN_DIR = INSTALLER_CONFIG.designDir;
115
+ const VERSION_FILE = INSTALLER_CONFIG.versionFile;
116
+ const CHECKSUMS_FILE = INSTALLER_CONFIG.checksumsFile;
117
+ const HISTORY_DIR = INSTALLER_CONFIG.historyDir;
105
118
  const DEFAULT_REMOVE_PREFIX = INSTALLER_CONFIG.removePrefix;
106
119
  const DOWNLOAD_TIMEOUT_MS = INSTALLER_CONFIG.download.timeoutMs;
107
120
  const NODE_USER_AGENT = INSTALLER_CONFIG.userAgent.node;
@@ -178,6 +191,45 @@ function copyDir(src, dest) {
178
191
  fs.cpSync(src, dest, { recursive: true, force: true });
179
192
  }
180
193
 
194
+ function appendToGitignore(entries) {
195
+ const gitignoreFile = path.join(cwd, '.gitignore');
196
+ let content = '';
197
+ if (fs.existsSync(gitignoreFile)) {
198
+ content = fs.readFileSync(gitignoreFile, 'utf8');
199
+ }
200
+
201
+ const added = [];
202
+ for (const entry of entries) {
203
+ // Normalize: ensure trailing slash for directories
204
+ const normalized = entry.endsWith('/') ? entry : entry + '/';
205
+ // Check if already present (with or without trailing slash)
206
+ const base = normalized.replace(/\/$/, '');
207
+ const alreadyPresent = content.split(/\r?\n/).some(line => {
208
+ const trimmed = line.trim();
209
+ return trimmed === base || trimmed === normalized;
210
+ });
211
+ if (!alreadyPresent) {
212
+ added.push(normalized);
213
+ }
214
+ }
215
+
216
+ if (added.length === 0) return;
217
+
218
+ // Append under a Magic Spec section header
219
+ const section = '\n# Magic Spec (engine & workflows — installed via npx/uvx)';
220
+ const hasSection = content.includes('# Magic Spec');
221
+ let appendBlock = '';
222
+ if (!hasSection) {
223
+ appendBlock = section + '\n';
224
+ }
225
+ appendBlock += added.join('\n');
226
+
227
+ content = content.trimEnd() + '\n' + appendBlock + '\n';
228
+ fs.writeFileSync(gitignoreFile, content, 'utf8');
229
+ console.log(`📝 Updated .gitignore: added ${added.join(', ')}`);
230
+ console.log(` 💡 To vendor engine files in your repo, remove these entries.`);
231
+ }
232
+
181
233
  function convertToToml(content, description) {
182
234
  // Escape quotes and backslashes for TOML triple-quoted strings
183
235
  const escapedContent = content
@@ -327,7 +379,7 @@ function runDoctor() {
327
379
  console.log(`✅ ${item.path || name} is present`);
328
380
  } else {
329
381
  const hint = requiredHint ? ` (Hint: ${requiredHint})` : '';
330
- console.log(`❌ .design/${name} is missing${hint}`);
382
+ console.log(`❌ ${DESIGN_DIR}/${name} is missing${hint}`);
331
383
  }
332
384
  };
333
385
 
@@ -363,12 +415,12 @@ function runInfo() {
363
415
  console.log('magic-spec installation status');
364
416
  console.log('────────────────────────────────');
365
417
 
366
- const versionFile = path.join(cwd, '.magic', '.version');
418
+ const versionFilePath = path.join(cwd, ENGINE_DIR, VERSION_FILE);
367
419
  let installedVersion = 'none';
368
- if (fs.existsSync(versionFile)) {
369
- installedVersion = fs.readFileSync(versionFile, 'utf8').trim();
420
+ if (fs.existsSync(versionFilePath)) {
421
+ installedVersion = fs.readFileSync(versionFilePath, 'utf8').trim();
370
422
  }
371
- console.log(`Installed version : ${installedVersion} (.magic/.version)`);
423
+ console.log(`Installed version : ${installedVersion} (${ENGINE_DIR}/${VERSION_FILE})`);
372
424
 
373
425
  const ADAPTERS_PATH = path.join(__dirname, '..', 'adapters.json');
374
426
  let activeEnvs = [];
@@ -387,8 +439,8 @@ function runInfo() {
387
439
  const enginePresent = fs.existsSync(path.join(cwd, ENGINE_DIR));
388
440
  console.log(`Engine : ${ENGINE_DIR}/ ${enginePresent ? '✅ present' : '❌ missing'}`);
389
441
 
390
- const designPresent = fs.existsSync(path.join(cwd, '.design'));
391
- console.log(`Workspace : .design/ ${designPresent ? '✅ present' : '❌ missing'}`);
442
+ const designPresent = fs.existsSync(path.join(cwd, DESIGN_DIR));
443
+ console.log(`Workspace : ${DESIGN_DIR}/ ${designPresent ? '✅ present' : '❌ missing'}`);
392
444
 
393
445
  console.log('────────────────────────────────');
394
446
  console.log(`Run \`npx ${PACKAGE_NAME}@latest --update\` to refresh engine files.`);
@@ -396,9 +448,9 @@ function runInfo() {
396
448
  }
397
449
 
398
450
  function runCheck() {
399
- const versionFile = path.join(cwd, ENGINE_DIR, '.version');
451
+ const versionFile = path.join(cwd, ENGINE_DIR, VERSION_FILE);
400
452
  if (!fs.existsSync(versionFile)) {
401
- console.log(`⚠️ Not installed via magic-spec (no ${ENGINE_DIR}/.version file)`);
453
+ console.log(`⚠️ Not installed via magic-spec (no ${ENGINE_DIR}/${VERSION_FILE} file)`);
402
454
  process.exit(0);
403
455
  }
404
456
 
@@ -451,7 +503,7 @@ async function runEject() {
451
503
  console.log(` - ${ENGINE_DIR}/`);
452
504
  console.log(` - ${AGENT_DIR}/ (or active env adapter dir)`);
453
505
  console.log(` - ${ENGINE_DIR}.bak/ (if exists)`);
454
- console.log('\n Your .design/ workspace will NOT be affected.');
506
+ console.log(`\n Your ${DESIGN_DIR}/ workspace will NOT be affected.`);
455
507
 
456
508
  let shouldRun = autoAccept;
457
509
  if (!shouldRun) {
@@ -500,10 +552,10 @@ function getDirectoryChecksums(dir, baseDir = dir) {
500
552
  for (const item of items) {
501
553
  const fullPath = path.join(dir, item.name);
502
554
  if (item.isDirectory()) {
503
- if (item.name === '.checksums' || item.name === 'history') continue;
555
+ if (item.name === CHECKSUMS_FILE || item.name === HISTORY_DIR) continue;
504
556
  Object.assign(results, getDirectoryChecksums(fullPath, baseDir));
505
557
  } else {
506
- if (item.name === '.checksums') continue;
558
+ if (item.name === CHECKSUMS_FILE) continue;
507
559
  const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
508
560
  results[relPath] = getFileChecksum(fullPath);
509
561
  }
@@ -512,22 +564,22 @@ function getDirectoryChecksums(dir, baseDir = dir) {
512
564
  }
513
565
 
514
566
  async function handleConflicts(cwd) {
515
- const checksumsFile = path.join(cwd, '.magic', '.checksums');
516
- if (!fs.existsSync(checksumsFile)) return;
567
+ const checksumsFilePath = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
568
+ if (!fs.existsSync(checksumsFilePath)) return;
517
569
 
518
570
  let storedChecksums = {};
519
571
  try {
520
- storedChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
572
+ storedChecksums = JSON.parse(fs.readFileSync(checksumsFilePath, 'utf8'));
521
573
  } catch (e) {
522
574
  return;
523
575
  }
524
576
 
525
577
  const conflicts = [];
526
578
  for (const [relPath, storedHash] of Object.entries(storedChecksums)) {
527
- if (relPath === '.checksums' || relPath === '.version') continue;
579
+ if (relPath === CHECKSUMS_FILE || relPath === VERSION_FILE) continue;
528
580
 
529
- // Backward compatibility: try .magic first, then project root
530
- let localPath = path.join(cwd, '.magic', relPath);
581
+ // Backward compatibility: try engine dir first, then project root
582
+ let localPath = path.join(cwd, ENGINE_DIR, relPath);
531
583
  if (!fs.existsSync(localPath)) {
532
584
  localPath = path.join(cwd, relPath);
533
585
  }
@@ -733,6 +785,7 @@ async function main() {
733
785
  }
734
786
 
735
787
  try {
788
+ let selectedEnvResolved = null;
736
789
  if (!isLocal) {
737
790
  sourceRoot = await downloadPayload(versionToFetch);
738
791
  }
@@ -863,8 +916,8 @@ async function main() {
863
916
  if (!isUpdate) {
864
917
  const isWindows = process.platform === 'win32';
865
918
  const initScript = isWindows
866
- ? path.join(cwd, '.magic', 'scripts', 'init.ps1')
867
- : path.join(cwd, '.magic', 'scripts', 'init.sh');
919
+ ? path.join(cwd, ENGINE_DIR, 'scripts', 'init.ps1')
920
+ : path.join(cwd, ENGINE_DIR, 'scripts', 'init.sh');
868
921
 
869
922
  if (fs.existsSync(initScript)) {
870
923
  let shouldRun = true;
@@ -901,21 +954,36 @@ async function main() {
901
954
  console.log(`✅ ${PACKAGE_NAME} updated successfully!`);
902
955
  }
903
956
 
904
- // 4. Write version file (.magic/.version) - [T-2B01]
957
+ // 4. Write version file - [T-2B01]
905
958
  try {
906
- const versionFile = path.join(cwd, '.magic', '.version');
907
- fs.writeFileSync(versionFile, version, 'utf8');
959
+ const versionFileDest = path.join(cwd, ENGINE_DIR, VERSION_FILE);
960
+ fs.writeFileSync(versionFileDest, version, 'utf8');
908
961
  } catch (vErr) {
909
- console.warn(`⚠️ Failed to write .magic/.version: ${vErr.message}`);
962
+ console.warn(`⚠️ Failed to write ${ENGINE_DIR}/${VERSION_FILE}: ${vErr.message}`);
910
963
  }
911
964
 
965
+ // 5. Auto-update .gitignore
966
+ const gitignoreEntries = [ENGINE_DIR];
967
+ if (envValues.length > 0) {
968
+ for (const env of envValues) {
969
+ const adapter = ADAPTERS[env];
970
+ if (adapter && adapter.dest) {
971
+ gitignoreEntries.push(adapter.dest);
972
+ }
973
+ }
974
+ } else if (selectedEnvResolved && ADAPTERS[selectedEnvResolved]) {
975
+ gitignoreEntries.push(ADAPTERS[selectedEnvResolved].dest);
976
+ } else {
977
+ gitignoreEntries.push(AGENT_DIR);
978
+ }
979
+ appendToGitignore(gitignoreEntries);
912
980
 
913
981
  // 6. Save checksums - [T-2C03]
914
982
  try {
915
- const currentChecksums = getDirectoryChecksums(path.join(cwd, '.magic'));
983
+ const currentChecksums = getDirectoryChecksums(path.join(cwd, ENGINE_DIR));
916
984
 
917
985
  if (isUpdate) {
918
- const checksumsFile = path.join(cwd, '.magic', '.checksums');
986
+ const checksumsFile = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
919
987
  if (fs.existsSync(checksumsFile)) {
920
988
  try {
921
989
  const oldChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
@@ -930,7 +998,7 @@ async function main() {
930
998
 
931
999
  Object.assign(currentChecksums, adapterChecksums);
932
1000
 
933
- fs.writeFileSync(path.join(cwd, '.magic', '.checksums'), JSON.stringify(currentChecksums, null, 2), 'utf8');
1001
+ fs.writeFileSync(path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE), JSON.stringify(currentChecksums, null, 2), 'utf8');
934
1002
  } catch (cErr) {
935
1003
  console.warn(`⚠️ Failed to save checksums: ${cErr.message}`);
936
1004
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "magic-spec",
3
- "version": "1.4.15",
3
+ "version": "1.4.162",
4
4
  "description": "Magic Specification-Driven Development (SDD) Workflow",
5
5
  "author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
6
6
  "license": "MIT",