magic-spec 1.5.71 β 1.5.159
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.
- package/CHANGELOG.md +183 -144
- package/LICENSE +201 -21
- package/README.md +326 -323
- package/installers/config.json +19 -2
- package/installers/node/index.js +72 -16
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,323 +1,326 @@
|
|
|
1
|
-
# πͺ Magic Spec
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/magic-spec)
|
|
4
|
-
[](https://pypi.org/project/magic-spec/)
|
|
5
|
-
[![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
|
-
βββ .agents/workflows/
|
|
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. **`.agents/`**: Sets up workflows for your AI.
|
|
46
|
-
3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
|
|
47
|
-
|
|
48
|
-
> [!TIP]
|
|
49
|
-
> **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.
|
|
50
|
-
|
|
51
|
-
## π§ The SDD Philosophy
|
|
52
|
-
|
|
53
|
-
> *"No code without a spec. No spec without a plan."*
|
|
54
|
-
|
|
55
|
-
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.
|
|
56
|
-
|
|
57
|
-
### Human-Minimal Engineering (Autonomous Partner)
|
|
58
|
-
|
|
59
|
-
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.
|
|
60
|
-
|
|
61
|
-
#### Trust Mode: Encapsulated Logic
|
|
62
|
-
|
|
63
|
-
Once you describe what you want, the engine takes over:
|
|
64
|
-
|
|
65
|
-
- **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.
|
|
66
|
-
- **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.
|
|
67
|
-
|
|
68
|
-
#### Silent Orchestration
|
|
69
|
-
|
|
70
|
-
- **Auto-Stabilization**: Specifications are drafted, reviewed, and promoted to `Stable` automatically if the logic is clear.
|
|
71
|
-
- **Zero-Prompt Planning**: Tasks are decomposed, prioritized, and scheduled without interrupting your flow.
|
|
72
|
-
- **Silent Operations**: Phases execute end-to-end: retrospectives, changelogs, and context regeneration happen silently.
|
|
73
|
-
- **Single Execution Gate**: The only mandatory prompt is the final sign-off before implementation begins.
|
|
74
|
-
|
|
75
|
-
Everything else is automated. The agent does the engineering. You approve the direction.
|
|
76
|
-
|
|
77
|
-
### Two-Layer Specification Model
|
|
78
|
-
|
|
79
|
-
Every specification in Magic Spec belongs to one of two layers, and this separation is strictly enforced:
|
|
80
|
-
|
|
81
|
-
**Layer 1 β Concept** (`layer: concept`)
|
|
82
|
-
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.
|
|
83
|
-
|
|
84
|
-
**Layer 2 β Implementation** (`layer: implementation`)
|
|
85
|
-
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`.
|
|
86
|
-
|
|
87
|
-
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.
|
|
88
|
-
|
|
89
|
-
> **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.
|
|
90
|
-
|
|
91
|
-
### Integrity by Design
|
|
92
|
-
|
|
93
|
-
The engine actively protects specification integrity throughout the project lifecycle:
|
|
94
|
-
|
|
95
|
-
- **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.
|
|
96
|
-
- **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.
|
|
97
|
-
- **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.
|
|
98
|
-
- **
|
|
99
|
-
- **
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
PLAN
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
style
|
|
145
|
-
|
|
146
|
-
style
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
style
|
|
150
|
-
|
|
151
|
-
style
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
|
161
|
-
|
|
|
162
|
-
| **
|
|
163
|
-
| **
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
```
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
- *"
|
|
256
|
-
- *"
|
|
257
|
-
- *"
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
|
269
|
-
|
|
|
270
|
-
| [**
|
|
271
|
-
| [**
|
|
272
|
-
| **
|
|
273
|
-
| **
|
|
274
|
-
| **
|
|
275
|
-
| **
|
|
276
|
-
| **
|
|
277
|
-
| **
|
|
278
|
-
| **
|
|
279
|
-
| **
|
|
280
|
-
| **
|
|
281
|
-
| **
|
|
282
|
-
| **
|
|
283
|
-
| **
|
|
284
|
-
| **
|
|
285
|
-
| **
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
- [
|
|
305
|
-
- [
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
1
|
+
# πͺ Magic Spec
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/magic-spec)
|
|
4
|
+
[](https://pypi.org/project/magic-spec/)
|
|
5
|
+
[](./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
|
+
βββ .agents/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. **`.agents/`**: Sets up workflows for your AI.
|
|
46
|
+
3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
|
|
47
|
+
|
|
48
|
+
> [!TIP]
|
|
49
|
+
> **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.
|
|
50
|
+
|
|
51
|
+
## π§ The SDD Philosophy
|
|
52
|
+
|
|
53
|
+
> *"No code without a spec. No spec without a plan."*
|
|
54
|
+
|
|
55
|
+
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.
|
|
56
|
+
|
|
57
|
+
### Human-Minimal Engineering (Autonomous Partner)
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
#### Trust Mode: Encapsulated Logic
|
|
62
|
+
|
|
63
|
+
Once you describe what you want, the engine takes over:
|
|
64
|
+
|
|
65
|
+
- **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.
|
|
66
|
+
- **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.
|
|
67
|
+
|
|
68
|
+
#### Silent Orchestration
|
|
69
|
+
|
|
70
|
+
- **Auto-Stabilization**: Specifications are drafted, reviewed, and promoted to `Stable` automatically if the logic is clear.
|
|
71
|
+
- **Zero-Prompt Planning**: Tasks are decomposed, prioritized, and scheduled without interrupting your flow.
|
|
72
|
+
- **Silent Operations**: Phases execute end-to-end: retrospectives, changelogs, and context regeneration happen silently.
|
|
73
|
+
- **Single Execution Gate**: The only mandatory prompt is the final sign-off before implementation begins.
|
|
74
|
+
|
|
75
|
+
Everything else is automated. The agent does the engineering. You approve the direction.
|
|
76
|
+
|
|
77
|
+
### Two-Layer Specification Model
|
|
78
|
+
|
|
79
|
+
Every specification in Magic Spec belongs to one of two layers, and this separation is strictly enforced:
|
|
80
|
+
|
|
81
|
+
**Layer 1 β Concept** (`layer: concept`)
|
|
82
|
+
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.
|
|
83
|
+
|
|
84
|
+
**Layer 2 β Implementation** (`layer: implementation`)
|
|
85
|
+
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`.
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
> **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.
|
|
90
|
+
|
|
91
|
+
### Integrity by Design
|
|
92
|
+
|
|
93
|
+
The engine actively protects specification integrity throughout the project lifecycle:
|
|
94
|
+
|
|
95
|
+
- **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.
|
|
96
|
+
- **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.
|
|
97
|
+
- **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.
|
|
98
|
+
- **Canonical References**: Stable specifications must declare authoritative source files that downstream agents are required to read before implementation. This eliminates hallucinated API contracts and stale-memory errors.
|
|
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
|
+
- **Agent Memory (STATE.md)**: A live project state digest (β€100 lines) that tracks current position, recent decisions, blockers, and constraints. Read first in every workflow session. Supports structured cross-session handoff via `HANDOFF.json` for zero-prompt resume.
|
|
101
|
+
- **Engine Integrity**: Core engine files are checksummed. Any untracked modification halts all workflows until the engine state is reconciled.
|
|
102
|
+
|
|
103
|
+
### Self-Improving Feedback Loop
|
|
104
|
+
|
|
105
|
+
Magic Spec includes a built-in retrospective engine that runs automatically at two levels:
|
|
106
|
+
|
|
107
|
+
- **Level 1** fires after every phase completes: captures a lightweight snapshot of spec health, task metrics, and signal status.
|
|
108
|
+
- **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.
|
|
109
|
+
|
|
110
|
+
These retrospectives feed back into the specification layer, closing the loop between what was planned and what was actually built.
|
|
111
|
+
|
|
112
|
+
## πΌοΈ Visuals
|
|
113
|
+
|
|
114
|
+
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.
|
|
115
|
+
|
|
116
|
+
```mermaid
|
|
117
|
+
flowchart TB
|
|
118
|
+
IDEA(["π‘ Idea"])
|
|
119
|
+
|
|
120
|
+
subgraph BOX ["Magic Spec"]
|
|
121
|
+
direction TB
|
|
122
|
+
|
|
123
|
+
SPEC["π Spec"]
|
|
124
|
+
|
|
125
|
+
subgraph TASK ["πΊοΈ Task"]
|
|
126
|
+
direction TB
|
|
127
|
+
PLAN["π Plan"]
|
|
128
|
+
TASKS["π Tasks"]
|
|
129
|
+
PLAN --> TASKS
|
|
130
|
+
end
|
|
131
|
+
|
|
132
|
+
RUN["β‘ Run"]
|
|
133
|
+
|
|
134
|
+
SPEC --> PLAN
|
|
135
|
+
TASKS --> RUN
|
|
136
|
+
end
|
|
137
|
+
|
|
138
|
+
CODE(["π Code"])
|
|
139
|
+
|
|
140
|
+
IDEA --> SPEC
|
|
141
|
+
RUN --> CODE
|
|
142
|
+
|
|
143
|
+
style IDEA fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
|
|
144
|
+
style CODE fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
|
|
145
|
+
|
|
146
|
+
style BOX fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
|
|
147
|
+
|
|
148
|
+
style SPEC fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
|
|
149
|
+
style RUN fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
|
|
150
|
+
|
|
151
|
+
style TASK fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
|
|
152
|
+
style PLAN fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
|
|
153
|
+
style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
## βοΈ Requirements
|
|
157
|
+
|
|
158
|
+
Before installing Magic Spec, ensure you have one of the following available on your system:
|
|
159
|
+
|
|
160
|
+
| Requirement | Details |
|
|
161
|
+
| :--- | :--- |
|
|
162
|
+
| **Node.js** | Version `16.x` or higher (for `npx` method) |
|
|
163
|
+
| **Python** | Version `3.8` or higher (for `uvx` or `pipx` methods) |
|
|
164
|
+
| **Git** | Required for installing edge versions directly from GitHub |
|
|
165
|
+
| **Terminal** | `tar` utility (pre-installed on Windows/Linux/macOS) |
|
|
166
|
+
|
|
167
|
+
## π¦ Installation
|
|
168
|
+
|
|
169
|
+
Works perfectly with **any project** β Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
|
|
170
|
+
|
|
171
|
+
### Option A: Node.js (`npx`)
|
|
172
|
+
|
|
173
|
+
**Stable Release:**
|
|
174
|
+
|
|
175
|
+
```bash
|
|
176
|
+
# Basic installation (defaults to .agents/ folder)
|
|
177
|
+
npx magic-spec@latest
|
|
178
|
+
|
|
179
|
+
# Targeted installation for Cursor
|
|
180
|
+
npx magic-spec@latest --cursor
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
**Edge Version (GitHub):**
|
|
184
|
+
|
|
185
|
+
```bash
|
|
186
|
+
npx --yes github:teratron/magic-spec
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
### Option B: Python (`uvx`)
|
|
190
|
+
|
|
191
|
+
**Stable Release:**
|
|
192
|
+
|
|
193
|
+
```bash
|
|
194
|
+
# Basic installation
|
|
195
|
+
uvx magic-spec
|
|
196
|
+
|
|
197
|
+
# Targeted installation for Windsurf
|
|
198
|
+
uvx magic-spec --windsurf
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
**Edge Version (GitHub):**
|
|
202
|
+
|
|
203
|
+
```bash
|
|
204
|
+
uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
### Option C: Python (`pipx`)
|
|
208
|
+
|
|
209
|
+
```bash
|
|
210
|
+
pipx run magic-spec
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### Option D: Multi-Adapter Installation
|
|
214
|
+
|
|
215
|
+
You can install support for multiple adapters at once:
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
npx magic-spec@latest --cursor --copilot --windsurf
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Option E: Manual Installation
|
|
222
|
+
|
|
223
|
+
If automated installers do not fit your environment:
|
|
224
|
+
|
|
225
|
+
1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
|
|
226
|
+
2. **Workflows**: Download command wrappers from [`workflows/`](https://github.com/teratron/magic-spec/tree/main/workflows).
|
|
227
|
+
3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
|
|
228
|
+
|
|
229
|
+
## π Updating
|
|
230
|
+
|
|
231
|
+
Keep your SDD engine up to date with the latest logic and features:
|
|
232
|
+
|
|
233
|
+
```bash
|
|
234
|
+
# Check if update is available
|
|
235
|
+
npx magic-spec@latest --check
|
|
236
|
+
|
|
237
|
+
# Perform the update
|
|
238
|
+
npx magic-spec@latest --update
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
> [!TIP]
|
|
242
|
+
> The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agents/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort). **After updating Magic Spec, it is highly recommended to run the `/magic.analyze` command to ensure your project's specifications and engine metadata are fully synchronized.**
|
|
243
|
+
|
|
244
|
+
### Post-Install: `.gitignore`
|
|
245
|
+
|
|
246
|
+
The installer automatically adds `.magic/` and the adapter directory (e.g., `.agents/`, `.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.
|
|
247
|
+
|
|
248
|
+
> [!TIP]
|
|
249
|
+
> **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.agents/` entries from your `.gitignore`.
|
|
250
|
+
|
|
251
|
+
## π¬ Usage
|
|
252
|
+
|
|
253
|
+
Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
|
|
254
|
+
|
|
255
|
+
- *"Dispatch this thought into specs..."* β Triggers **Specification** workflow.
|
|
256
|
+
- *"Run a project audit"*, *"magic.analyze"* β Triggers **Analyze** (Ventilation) workflow.
|
|
257
|
+
- *"Create an implementation plan"* β Triggers **Task & Plan** workflow.
|
|
258
|
+
- *"Execute the next task"* β Triggers **Run** workflow.
|
|
259
|
+
- *"Add a rule: always use Inter font"* β Triggers **Rule** workflow.
|
|
260
|
+
- *"Pause session"*, *"magic.pause"* β Triggers **Pause** workflow (saves state for cross-session resume).
|
|
261
|
+
|
|
262
|
+
### π€ Compatibility
|
|
263
|
+
|
|
264
|
+
Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
|
|
265
|
+
|
|
266
|
+
You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
|
|
267
|
+
|
|
268
|
+
| AI Agent / IDE | Shortcut Flag | Env Flag |
|
|
269
|
+
| :--- | :--- | :--- |
|
|
270
|
+
| [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
|
|
271
|
+
| [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
|
|
272
|
+
| [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
|
|
273
|
+
| [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
|
|
274
|
+
| [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
|
|
275
|
+
| **Roo Code** | `--roo` | `--env roo` |
|
|
276
|
+
| **Amp** | `--amp` | `--env amp` |
|
|
277
|
+
| **Amazon Q Developer** | `--q` | `--env q` |
|
|
278
|
+
| **Kilo Code** | `--kilocode` | `--env kilocode` |
|
|
279
|
+
| **Qwen Code** | `--qwen` | `--env qwen` |
|
|
280
|
+
| **OpenCode** | `--opencode` | `--env opencode` |
|
|
281
|
+
| **SHAI (OVHcloud)** | `--shai` | `--env shai` |
|
|
282
|
+
| **IBM Bob** | `--bob` | `--env bob` |
|
|
283
|
+
| **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
|
|
284
|
+
| **Qoder IDE** | `--qoder` | `--env qoder` |
|
|
285
|
+
| **Codex CLI** | `--codex` | `--env codex` |
|
|
286
|
+
| **Auggie CLI** | `--augment` | `--env augment` |
|
|
287
|
+
| **Antigravity IDE** | `--antigravity` | `--env antigravity` |
|
|
288
|
+
| **Lingma IDE** | `--lingma` | `--env lingma` |
|
|
289
|
+
|
|
290
|
+
## π Documentation
|
|
291
|
+
|
|
292
|
+
- [**Main Documentation**](./docs/README.md) β Detailed guide on workflows, architecture, and advanced features.
|
|
293
|
+
- [**Installers Guide**](./installers/README.md) β Advanced CLI options and platform specifics.
|
|
294
|
+
- [**Contributing**](./CONTRIBUTING.md) β How to develop, test, and extend the engine.
|
|
295
|
+
|
|
296
|
+
## π Support
|
|
297
|
+
|
|
298
|
+
If you encounter issues or have questions:
|
|
299
|
+
|
|
300
|
+
- Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
|
|
301
|
+
|
|
302
|
+
## πΊοΈ Roadmap
|
|
303
|
+
|
|
304
|
+
- [x] Multi-agent adapter system.
|
|
305
|
+
- [x] Phased implementation planning.
|
|
306
|
+
- [ ] Extended support for local-first LLM agents.
|
|
307
|
+
- [ ] Advanced visual dashboard for project health.
|
|
308
|
+
- [ ] Integration with CI/CD for automated spec validation.
|
|
309
|
+
|
|
310
|
+
## ποΈ Contributing
|
|
311
|
+
|
|
312
|
+
We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
|
|
313
|
+
Please see [**Contributing Guide**](./CONTRIBUTING.md) for details.
|
|
314
|
+
|
|
315
|
+
## π₯ Authors and Acknowledgments
|
|
316
|
+
|
|
317
|
+
- **Oleg Alexandrov** β Creator and Lead Maintainer.
|
|
318
|
+
- Special thanks to the AI agent community for inspiration and testing.
|
|
319
|
+
|
|
320
|
+
## π License
|
|
321
|
+
|
|
322
|
+
Distributed under the [Apache License 2.0](./LICENSE).
|
|
323
|
+
|
|
324
|
+
## π Project Status
|
|
325
|
+
|
|
326
|
+
**Active Development** (v1.5.159). We are constantly refining the SDD engine based on real-world usage.
|