magic-spec 1.5.132 → 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 +81 -0
- package/LICENSE +201 -21
- package/README.md +326 -323
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,87 @@ 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.5.159] - 2026-04-10
|
|
9
|
+
|
|
10
|
+
### Meta
|
|
11
|
+
|
|
12
|
+
- **Engine Sync**: Performed project hygiene sync, updated documentation, and validated engine metadata (C14 parity).
|
|
13
|
+
|
|
14
|
+
## [1.5.159] - 2026-04-09
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
### Added
|
|
18
|
+
|
|
19
|
+
- **Agent Memory (STATE.md)**: New live memory system — a ≤100-line project state digest read first in every workflow session. Tracks current position, recent decisions, blockers, and blocking constraints. Template: `.magic/templates/state.md`. Utility: `.magic/scripts/update-state.js`.
|
|
20
|
+
- **Session Continuity (HANDOFF.json)**: Structured cross-session handoff mechanism. Template: `.magic/templates/handoff.json`. Enables zero-prompt resume from exact position with required reading lists and constraint acknowledgment.
|
|
21
|
+
- **Pause Workflow (`pause.md`)**: New `/magic.pause` workflow that snapshots session state into `HANDOFF.json` and sets `STATE.md` status to `Paused`. Supports automatic trigger at POOR context tier.
|
|
22
|
+
- **Phase Frontmatter**: YAML dependency metadata block in `phase.md` template (`requires`, `provides`, `key_files`, `patterns_established`, `subsystem`, `duration_minutes`). Enables machine-readable inter-phase dependency tracking.
|
|
23
|
+
- **Canonical References**: New mandatory `## Canonical References` section in `spec.md` template. Forces downstream agents to bind to specific stable file paths instead of relying on memory. Audit checks added to `analyze.md` and `spec.md` checklists.
|
|
24
|
+
- **Context Quality Tiers**: Adaptive agent behaviour guidance (PEAK/GOOD/DEGRADING/POOR) based on context window utilization. Added to `task.md` workflow header.
|
|
25
|
+
- **Resume Detection**: Integrated into `context-resolution.md` Post-Resolution chain (Priority 3-4). Automatically detects paused sessions and resumes from recorded position.
|
|
26
|
+
- **Pause Propagation**: `run.md` Logic Guard that auto-saves state when all phase tasks are blocked.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- **`context-resolution.md`**: Extended Post-Resolution chain with STATE.md loading (Priority 3) and Resume Detection (Priority 4).
|
|
31
|
+
- **`init.md`**: STATE.md creation added to init steps, structure map, and completion checklist.
|
|
32
|
+
- **`run.md`**: Added Live Memory invariant (2.5), STATE Sync in Update step, Frontmatter Update in Phase Completion, and Pause Propagation guard.
|
|
33
|
+
- **`task.md`**: Added Context Quality Guidance, Phase Frontmatter generation instructions, State Init/Update step, and Dependency Read from frontmatter.
|
|
34
|
+
- **`analyze.md`**: Added `CANONICAL_MISSING` audit check for Stable specs without Canonical References section.
|
|
35
|
+
- **`spec.md`**: Added Canonical References validation to Task Completion Checklist — blocks Stable promotion if section is empty.
|
|
36
|
+
|
|
37
|
+
## [1.5.142] - 2026-04-09
|
|
38
|
+
|
|
39
|
+
### Changed
|
|
40
|
+
|
|
41
|
+
- **License**: Changed project license from MIT to Apache License 2.0.
|
|
42
|
+
|
|
43
|
+
## [1.5.141] - 2026-04-08
|
|
44
|
+
|
|
45
|
+
### Removed
|
|
46
|
+
|
|
47
|
+
- **CODEX.toml**: Completely removed `CODEX.toml` from the engine initialization scripts and placeholders as it is not required by any supported agent.
|
|
48
|
+
|
|
49
|
+
## [1.5.140] - 2026-04-08
|
|
50
|
+
|
|
51
|
+
### Fixed
|
|
52
|
+
|
|
53
|
+
- **Engine Init Portability**: Refactored `setup_unix.sh` to use relative symlinks and removed `realpath -m` dependency, improving compatibility with macOS and older Linux/Unix systems.
|
|
54
|
+
- **Git Index Integrity**: Fixed a bug in `magic.dev:init` where development workflows (`magic.dev.*`) were incorrectly removed from the git index during setup.
|
|
55
|
+
|
|
56
|
+
## [1.5.139] - 2026-04-07
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
|
|
60
|
+
- **Universal Skill Wrappers**: Implemented `sync-skills.js` to automatically project workflows into universal agent skills (`SKILL.md`).
|
|
61
|
+
- **Engine Integration**: Integrated skill synchronization into `init.js` and `update-engine-meta.js` (C14). All workflow changes now automatically update the agent's tool surface.
|
|
62
|
+
- **Regression Testing**: Added `T190 — Skill Projection Parity` to the test suite.
|
|
63
|
+
|
|
64
|
+
## [1.5.136] - 2026-04-07
|
|
65
|
+
|
|
66
|
+
### Added
|
|
67
|
+
|
|
68
|
+
- **Documentation Hygiene Pass**: Added a project-wide hygiene pass to `update-project-meta.js` that automatically fixes MD012 (multiple consecutive blank lines) in all core documentation files.
|
|
69
|
+
- **Robust Registry Logic**: Fixed a bug in `sync-docs.js` where the workspace registry extraction would grab trailing content (Document History) if the `## Meta` section was missing.
|
|
70
|
+
|
|
71
|
+
## [1.5.135] - 2026-04-07
|
|
72
|
+
|
|
73
|
+
### Meta
|
|
74
|
+
|
|
75
|
+
- **Engine Sync**: Performed project hygiene sync, updated documentation, and validated hardlink integrity (C14).
|
|
76
|
+
|
|
77
|
+
## [1.5.134] - 2026-04-07
|
|
78
|
+
|
|
79
|
+
### Added
|
|
80
|
+
|
|
81
|
+
- **Skill Projection Automation**: Integrated `sync-skills.js` directly into `update-engine-meta.js`. Engine core changes now automatically regenerate Skill wrappers for Claude and Gemini (C14).
|
|
82
|
+
- **Distribution Guide**: Created `docs/distribution.md` documenting the separation between User Bundle, Dev Instruments, and Internal Engine files.
|
|
83
|
+
|
|
84
|
+
### Changed
|
|
85
|
+
|
|
86
|
+
- **History Reorganization**: Cleaned up and organized the `history/` directory. History files now follow a standardized naming convention and are updated with a smart condensing logic for version ranges.
|
|
87
|
+
- **Agent Rules (AGENTS.md)**: Updated Project Anatomy to include the `skills/` compatibility layer and corrected the hardlink integrity check (now 5 files).
|
|
88
|
+
|
|
8
89
|
## [1.5.132] - 2026-04-04
|
|
9
90
|
|
|
10
91
|
### Changed
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,201 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Oleg Alexandrov
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
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/ # 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
|
-
- **
|
|
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.
|
package/package.json
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "magic-spec",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.159",
|
|
4
4
|
"description": "Magic Specification-Driven Development (SDD) Workflow",
|
|
5
5
|
"author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
|
|
6
|
-
"license": "
|
|
6
|
+
"license": "Apache-2.0",
|
|
7
7
|
"homepage": "https://github.com/teratron/magic-spec",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|