magic-spec 1.5.159 → 1.5.207
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 +413 -302
- package/README.md +92 -170
- package/installers/config.json +6 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,302 +1,413 @@
|
|
|
1
|
-
# Changelog
|
|
2
|
-
|
|
3
|
-
All notable changes to this project will be documented in this file.
|
|
4
|
-
|
|
5
|
-
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
-
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
-
|
|
8
|
-
## [1.5.
|
|
9
|
-
|
|
10
|
-
### Meta
|
|
11
|
-
|
|
12
|
-
- **Engine Sync**:
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
###
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
|
|
28
|
-
### Changed
|
|
29
|
-
|
|
30
|
-
- **`
|
|
31
|
-
- **`
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
- **
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
- **
|
|
69
|
-
- **
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
- **
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
-
### Meta
|
|
123
|
-
|
|
124
|
-
- **
|
|
125
|
-
|
|
126
|
-
## [1.5.
|
|
127
|
-
|
|
128
|
-
###
|
|
129
|
-
|
|
130
|
-
- **
|
|
131
|
-
- **
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
- **
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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
|
-
### Changed
|
|
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
|
-
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.5.206] - 2026-04-28
|
|
9
|
+
|
|
10
|
+
### Meta
|
|
11
|
+
|
|
12
|
+
- **Engine Sync**: Final hygiene and version synchronization (C14) before global release.
|
|
13
|
+
- **Validation**: All 18 core tests passed on Windows environment.
|
|
14
|
+
|
|
15
|
+
## [1.5.204] - 2026-04-25
|
|
16
|
+
|
|
17
|
+
### Fixed
|
|
18
|
+
|
|
19
|
+
- **`sync-docs.js`**: Removed greedy global `vX.Y.Z` regex that overwrote unrelated version mentions. Removed `today's date` from `CONTRIBUTING.md` footer (now uses latest source mtime). `## Sync Note` only refreshes when the matching workflow source hash changes or the engine version actually bumps. Adds `.magic/.docs-state.json` for per-workflow content tracking.
|
|
20
|
+
- **`sync-manifests.js`**: Replaced greedy `(\(v?\d+\.\d+\.\d+\))/g` README sweep with anchored `**Active Development** (vX.Y.Z)` and an optional `<!-- engine-version -->...<!-- /engine-version -->` marker. Added `installers/python/magic_spec/__init__.py` to the manifest set.
|
|
21
|
+
- **`update-project-meta.js`**: Made idempotent via SHA-256 structural digest stored in `.magic/.project-meta-state.json` (volatile fields stripped before hashing). Bump + history append now happen only on real change. Added Smart-History dedup (same-day same-message rows collapse into a version range). Fixed history insertion to honor newest-first table convention by anchoring to the matched header's slice instead of the file's first divider.
|
|
22
|
+
|
|
23
|
+
### Added
|
|
24
|
+
|
|
25
|
+
- **`validate-hardlinks.js`**: New script verifies `CLAUDE.md`, `GEMINI.md`, `QWEN.md`, `CODEX.md` share the same inode as `AGENTS.md`. Tolerant by default; pass `--strict` to fail on missing siblings.
|
|
26
|
+
- **`sync.js`**: Hardlink validation wired in as a pipeline step. New flags: `--skip-links`, `--strict-links`.
|
|
27
|
+
|
|
28
|
+
### Changed
|
|
29
|
+
|
|
30
|
+
- **`magic.dev.sync.md` workflow**: Rewritten to describe the actual pipeline (was claiming a "Hardlink Validation" step that did not exist).
|
|
31
|
+
- **`update-engine-meta.js`**: `.docs-state.json` and `.project-meta-state.json` now ignored by drift detection (volatile state caches, not engine logic).
|
|
32
|
+
|
|
33
|
+
## [1.5.198] - 2026-04-24
|
|
34
|
+
|
|
35
|
+
### Fixed
|
|
36
|
+
|
|
37
|
+
- **Version Parity**: Synchronized metadata, documentation, and installers across the repository.
|
|
38
|
+
- **Hardlink Validation**: Verified agent link integrity.
|
|
39
|
+
|
|
40
|
+
## [1.5.171] - 2026-04-24
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
|
|
44
|
+
- **Spec Graph extraction cache** (`.magic/scripts/graph-cache.js`): Per-file SHA-256 cache of parsed spec metadata (refs, parent, conventions). Frontmatter-aware hashing for Markdown — metadata-only edits (`Version`, `Last Updated`, `Status`) do not invalidate cache. Cache lives at `$designDir/.graph-cache/` (gitignored). 100% hit rate on unchanged re-runs.
|
|
45
|
+
- **Spec Graph Wiki export** (`.magic/scripts/export-wiki.js`): Generates an agent-navigable Markdown wiki at `$designDir/wiki/` — `index.md` + one page per workspace + one article per spec, with Obsidian-style `[[wiki-links]]` between them. Surfaces god nodes, knowledge gaps, and implements chains. Usage: `node .magic/scripts/executor.js export-wiki [--from-file graph.json] [--out dir]`.
|
|
46
|
+
- **Token-budget truncation on MCP `query_graph`**: The `query_graph` tool in `serve-spec-graph.js` now accepts a `token_budget` argument (default 2000). Output is truncated at `chars = budget × 4` with an explicit sentinel, preventing unbounded responses as the graph grows.
|
|
47
|
+
- **Spec**: `.design/engine/specifications/l2-spec-graph-memory.md` — Layer 2 specification adapting three memory / token-economy mechanisms from the external project.
|
|
48
|
+
|
|
49
|
+
### Changed
|
|
50
|
+
|
|
51
|
+
- **`build-spec-graph.js`**: Integrated extraction cache via `graph-cache.js`. Added `--no-cache` flag. Summary now reports cache hits/misses.
|
|
52
|
+
- **`.design/engine/INDEX.md`**: Registered `l2-spec-graph-memory.md` (engine registry → v1.8.0).
|
|
53
|
+
|
|
54
|
+
### Meta
|
|
55
|
+
|
|
56
|
+
- **Engine version**: `1.5.195` → `1.5.197` (C14 auto-bump: initial scripts, then post-review fixes).
|
|
57
|
+
- **Package version**: `1.5.170` → `1.5.171`.
|
|
58
|
+
|
|
59
|
+
## [1.5.176] - 2026-04-23
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
|
|
63
|
+
- **Specification Knowledge Graph** (`build-spec-graph.js`): Full `extract → build → analyze → export` pipeline over `.design/` SDD artifacts. Produces workspace/spec/file/convention/phase nodes with edges. Outputs human-readable summary (default), `--json` for machine-readable, `--html` for interactive vis.js visualization. Includes God Nodes, orphaned files, missing Implements, bridge specs, and per-workspace coverage stats.
|
|
64
|
+
- **Community Detection** (`detect-communities.js`): Label Propagation algorithm (pure JS, no deps) on a multi-layer dependency graph (JS `require()`, Python imports, Markdown cross-references). Computes cohesion, modularity, and Jaccard alignment against `workspace.json`. Flags oversized communities with BFS-based split suggestions. Use `--include-md` for richer 8-community structure.
|
|
65
|
+
- **Incremental SHA256 Cache** (`cache-utils.js`): Shared cache module with atomic writes, frontmatter-stripped hashing for `.md` files, dead-entry pruning, and OS-agnostic path keys. Ready for use by any analyze script via `require('./cache-utils')`.
|
|
66
|
+
- **Graph Diff** (`diff-spec-graph.js`): Retrospective structural diff between two `build-spec-graph --json` snapshots. Surfaces node/edge additions and removals, degree changes, god node evolution, per-workspace coverage deltas, and orphan/convention drift.
|
|
67
|
+
- **MCP Server** (`serve-spec-graph.js`): stdio MCP server (JSON-RPC 2.0) exposing the SDD graph as 7 AI-agent tools: `query_graph`, `get_node`, `get_neighbors`, `find_gaps`, `shortest_path`, `get_coverage`, `god_nodes`. Builds the graph on startup via `build-spec-graph --json`.
|
|
68
|
+
- **Token Benchmark** (`benchmark.js`): Quantitative token efficiency measurement — raw corpus (238K tokens), spec layer (16K, 14.5× cheaper), BFS graph query (2.2K avg, 107.9× cheaper). Provides evidence of SDD's context economy.
|
|
69
|
+
- **Confidence Taxonomy** (`analyze-coverage.js`): Four-level file coverage classification (EXTRACTED / INFERRED / AMBIGUOUS / UNCOVERED) integrated into Mode B/C of `magic.analyze`.
|
|
70
|
+
- **Rationale Extraction** (`extract-rationale.js`): Scans source files for structured design markers (`NOTE`, `WHY`, `HACK`, `IMPORTANT`, `TODO`, etc.) and identifies Shadow Logic — design decisions not captured in any spec.
|
|
71
|
+
|
|
72
|
+
### Changed
|
|
73
|
+
|
|
74
|
+
- **`magic.analyze` Mode C** (Ventilation): Added steps 6 (Specification Knowledge Graph via `build-spec-graph`) and 7 (Workspace Boundary Analysis via `detect-communities --include-md`). Updated completion checklist with two new items.
|
|
75
|
+
- **`magic.retrospective`**: Added Graph Snapshot (`build-spec-graph --json`) and Graph Diff (`diff-spec-graph`) to the Collect step. Updated Retrospective Completion Checklist with two new items.
|
|
76
|
+
|
|
77
|
+
### Meta
|
|
78
|
+
|
|
79
|
+
- **Engine version**: bumped to `1.5.176` (eight new scripts auto-detected and checksummed by C14).
|
|
80
|
+
|
|
81
|
+
## [1.5.170] - 2026-04-19
|
|
82
|
+
|
|
83
|
+
### Fixed
|
|
84
|
+
|
|
85
|
+
- **Read-Only Invariant (sync orchestrator)**: `node .magic/scripts/executor.js sync --dry-run` previously performed real writes because `sync.js` silently ignored unknown flags and sub-scripts had no dry-run support. All sync sub-scripts (`sync-manifests`, `sync-docs`, `update-project-meta`, `update-engine-meta`, `generate-checksums`, `sync-skills`) now honor `MAGIC_DRY_RUN=1` via shared helpers in `utils.js` (`writeFileSafe`, `appendFileSafe`, `mkdirSafe`).
|
|
86
|
+
- **Strict CLI Contract**: `sync.js` now rejects unknown flags with exit code `2` and an explicit accepted-flags list, preventing silent-ignore regressions.
|
|
87
|
+
|
|
88
|
+
### Added
|
|
89
|
+
|
|
90
|
+
- **`utils.js` safe-writer helpers**: `isDryRun()`, `writeFileSafe()`, `appendFileSafe()`, `mkdirSafe()` — centralize the filesystem mutation gate so future scripts inherit dry-run support by default.
|
|
91
|
+
|
|
92
|
+
## [1.5.169] - 2026-04-18
|
|
93
|
+
|
|
94
|
+
### Added
|
|
95
|
+
|
|
96
|
+
- **Core Workflow Documentation**: Added documentation and metadata files to `.magic/` for all core workflows.
|
|
97
|
+
- **Engine Hardening**: Improved engine integrity checks and metadata synchronization robustness.
|
|
98
|
+
|
|
99
|
+
### Changed
|
|
100
|
+
|
|
101
|
+
- **Agent References**: Fixed typos and updated tool references in `.agents/` documentation.
|
|
102
|
+
- **Gitignore**: Added `.kilocode` to project ignore list.
|
|
103
|
+
|
|
104
|
+
### Meta
|
|
105
|
+
|
|
106
|
+
- **Engine Sync**: Full project hygiene sync; validated engine metadata (C14 parity).
|
|
107
|
+
|
|
108
|
+
## [1.5.160] - 2026-04-11
|
|
109
|
+
|
|
110
|
+
### Added
|
|
111
|
+
|
|
112
|
+
- **Hierarchical History**: Organized `.magic/history` into logical subfolders (`workflows`, `scripts`, `tests`, `skills`, `.agents/workflows`).
|
|
113
|
+
- **Engine Core Expansion**: Updated `update-engine-meta.js` and `generate-checksums.js` to scan and track all core engine directories, including root `workflows/` and `.agents/workflows/` (C14 parity).
|
|
114
|
+
- **Comprehensive Tracking**: All `.md` files and scripts within engine directories now have automated hierarchical history tracking.
|
|
115
|
+
|
|
116
|
+
### Meta
|
|
117
|
+
|
|
118
|
+
- **Engine Sync**: Performed project hygiene sync, organized history, and validated engine metadata (C14 parity).
|
|
119
|
+
|
|
120
|
+
## [1.5.159] - 2026-04-10
|
|
121
|
+
|
|
122
|
+
### Meta
|
|
123
|
+
|
|
124
|
+
- **Engine Sync**: Performed project hygiene sync, updated documentation, and validated engine metadata (C14 parity).
|
|
125
|
+
|
|
126
|
+
## [1.5.143] - 2026-04-09
|
|
127
|
+
|
|
128
|
+
### Added
|
|
129
|
+
|
|
130
|
+
- **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`.
|
|
131
|
+
- **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.
|
|
132
|
+
- **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.
|
|
133
|
+
- **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.
|
|
134
|
+
- **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.
|
|
135
|
+
- **Context Quality Tiers**: Adaptive agent behaviour guidance (PEAK/GOOD/DEGRADING/POOR) based on context window utilization. Added to `task.md` workflow header.
|
|
136
|
+
- **Resume Detection**: Integrated into `context.md` Post-Resolution chain (Priority 3-4). Automatically detects paused sessions and resumes from recorded position.
|
|
137
|
+
- **Pause Propagation**: `run.md` Logic Guard that auto-saves state when all phase tasks are blocked.
|
|
138
|
+
|
|
139
|
+
### Changed
|
|
140
|
+
|
|
141
|
+
- **`context.md`**: Extended Post-Resolution chain with STATE.md loading (Priority 3) and Resume Detection (Priority 4).
|
|
142
|
+
- **`init.md`**: STATE.md creation added to init steps, structure map, and completion checklist.
|
|
143
|
+
- **`run.md`**: Added Live Memory invariant (2.5), STATE Sync in Update step, Frontmatter Update in Phase Completion, and Pause Propagation guard.
|
|
144
|
+
- **`task.md`**: Added Context Quality Guidance, Phase Frontmatter generation instructions, State Init/Update step, and Dependency Read from frontmatter.
|
|
145
|
+
- **`analyze.md`**: Added `CANONICAL_MISSING` audit check for Stable specs without Canonical References section.
|
|
146
|
+
- **`spec.md`**: Added Canonical References validation to Task Completion Checklist — blocks Stable promotion if section is empty.
|
|
147
|
+
|
|
148
|
+
## [1.5.142] - 2026-04-09
|
|
149
|
+
|
|
150
|
+
### Changed
|
|
151
|
+
|
|
152
|
+
- **License**: Changed project license from MIT to Apache License 2.0.
|
|
153
|
+
|
|
154
|
+
## [1.5.141] - 2026-04-08
|
|
155
|
+
|
|
156
|
+
### Removed
|
|
157
|
+
|
|
158
|
+
- **CODEX.toml**: Completely removed `CODEX.toml` from the engine initialization scripts and placeholders as it is not required by any supported agent.
|
|
159
|
+
|
|
160
|
+
## [1.5.140] - 2026-04-08
|
|
161
|
+
|
|
162
|
+
### Fixed
|
|
163
|
+
|
|
164
|
+
- **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.
|
|
165
|
+
- **Git Index Integrity**: Fixed a bug in `magic.dev:init` where development workflows (`magic.dev.*`) were incorrectly removed from the git index during setup.
|
|
166
|
+
|
|
167
|
+
## [1.5.139] - 2026-04-07
|
|
168
|
+
|
|
169
|
+
### Added
|
|
170
|
+
|
|
171
|
+
- **Universal Skill Wrappers**: Implemented `sync-skills.js` to automatically project workflows into universal agent skills (`SKILL.md`).
|
|
172
|
+
- **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.
|
|
173
|
+
- **Regression Testing**: Added `T190 — Skill Projection Parity` to the test suite.
|
|
174
|
+
|
|
175
|
+
## [1.5.136] - 2026-04-07
|
|
176
|
+
|
|
177
|
+
### Added
|
|
178
|
+
|
|
179
|
+
- **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.
|
|
180
|
+
- **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.
|
|
181
|
+
|
|
182
|
+
## [1.5.135] - 2026-04-07
|
|
183
|
+
|
|
184
|
+
### Meta
|
|
185
|
+
|
|
186
|
+
- **Engine Sync**: Performed project hygiene sync, updated documentation, and validated hardlink integrity (C14).
|
|
187
|
+
|
|
188
|
+
## [1.5.134] - 2026-04-07
|
|
189
|
+
|
|
190
|
+
### Added
|
|
191
|
+
|
|
192
|
+
- **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).
|
|
193
|
+
- **Distribution Guide**: Created `docs/distribution.md` documenting the separation between User Bundle, Dev Instruments, and Internal Engine files.
|
|
194
|
+
|
|
195
|
+
### Changed
|
|
196
|
+
|
|
197
|
+
- **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.
|
|
198
|
+
- **Agent Rules (AGENTS.md)**: Updated Project Anatomy to include the `skills/` compatibility layer and corrected the hardlink integrity check (now 5 files).
|
|
199
|
+
|
|
200
|
+
## [1.5.132] - 2026-04-04
|
|
201
|
+
|
|
202
|
+
### Changed
|
|
203
|
+
|
|
204
|
+
- **Internationalization (En-En)**: Translated remaining Russian instructions in `docs/checksums.md` to English.
|
|
205
|
+
- **Engine Versioning**: Synchronized all manifest files with the base version `1.5.132` (C14).
|
|
206
|
+
|
|
207
|
+
## [1.5.131] - 2026-04-04
|
|
208
|
+
|
|
209
|
+
### Changed
|
|
210
|
+
|
|
211
|
+
- **Internationalization (En-En)**: Fixed remaining Russian examples in `.magic/analyze.md` that were missed in the previous version sync.
|
|
212
|
+
- **Engine Versioning**: Synchronized all manifest files with the base version `1.5.131` (C14).
|
|
213
|
+
|
|
214
|
+
## [1.5.130] - 2026-04-04
|
|
215
|
+
|
|
216
|
+
### Changed
|
|
217
|
+
|
|
218
|
+
- **Internationalization (En-En)**: Translated all remaining Russian examples and rule titles to English across the engine core (`.magic/`) to ensure a consistent, professional English-only codebase (Rule 3.1).
|
|
219
|
+
- Translated constitutional rule titles in `RULES.md` (e.g., `C12 — Quarantine Cascade`).
|
|
220
|
+
- Updated simulation test suite (`suite.md`) to reflect translated inputs and expected output strings.
|
|
221
|
+
|
|
222
|
+
### Meta
|
|
223
|
+
|
|
224
|
+
- **Automated Update**: Engine version bumped to `1.5.130`, history updated, and checksums regenerated (C14).
|
|
225
|
+
|
|
226
|
+
## [1.5.129] - 2026-04-03
|
|
227
|
+
|
|
228
|
+
### Changed
|
|
229
|
+
|
|
230
|
+
- **Structural Harmonization**: Refactored `retrospective.md` to use header-based logic. This resolves `MD029` (ordered list prefix) and `MD007` (list indentation) warnings caused by complex content and personification blocks (C24) breaking list continuity. Fixed sequential numbering (1, 2, 3, 4, 5, 2 -> 1, 2, 3, 4, 5, 6, 7).
|
|
231
|
+
- **C24 Independent Analyst**: Upgraded the persona block in `retrospective.md` to a dedicated sub-heading for better visibility and structural compliance.
|
|
232
|
+
|
|
233
|
+
### Meta
|
|
234
|
+
|
|
235
|
+
- **Automated Update**: Engine version bumped to `1.5.129`, history updated, and checksums regenerated (C14).
|
|
236
|
+
|
|
237
|
+
## [1.5.128] - 2026-04-03
|
|
238
|
+
|
|
239
|
+
### Fixed
|
|
240
|
+
|
|
241
|
+
- **Markdown Lint (MD012)**: Fixed a recurring issue where `CONTRIBUTING.md` would be regenerated with multiple consecutive blank lines. Added `.trim()` to `{{workflows_table}}` placeholder in `sync-docs.js` to ensure proper spacing between the table and the following section.
|
|
242
|
+
- **Engine Versioning**: Synchronized engine version across all manifests and documentation (C14).
|
|
243
|
+
|
|
244
|
+
## [1.5.126] - 2026-04-03
|
|
245
|
+
|
|
246
|
+
### Added
|
|
247
|
+
|
|
248
|
+
- **C24 — Unified Role-Switching Gate**: Expanded the mandatory internal review system into a unified constitutional rule across all key SDD workflows (Spec, Task, Run, Retro, Analyze, Rule, Simulate).
|
|
249
|
+
- **Workflow Personas**: Integrated 7 specialized personas (Critic, Skeptic, QA, Analyst, Auditor, Reviewer) to eliminate cognitive bias and ensure rigorous evidence-based verification before any artifact is finalized.
|
|
250
|
+
- **Structural Harmonization**: Refactored workflow steps in `analyze.md`, `rule.md`, and `simulate.md` to use header-based logic, resolving deep-seated markdown lint errors caused by intervening non-list elements.
|
|
251
|
+
|
|
252
|
+
## [1.5.120] - 2026-04-03
|
|
253
|
+
|
|
254
|
+
### Added
|
|
255
|
+
|
|
256
|
+
- **C24 — Unified Role-Switching Gate**: Expanded the mandatory internal review system into a unified constitutional rule across all key SDD workflows. This forces the agent to adopt specialized personas to eliminate cognitive bias before artifacts are finalized:
|
|
257
|
+
- **Spec Workflow**: Persona **Project Critic** (L1 tech-neutrality, invariant completeness).
|
|
258
|
+
- **Task Workflow**: Persona **Planning Skeptic** (Optimism bias detection, dependency risk analysis).
|
|
259
|
+
- **Run Workflow**: Persona **QA Tester** (Invariant verification, boundary condition audit).
|
|
260
|
+
- **Workflow Integration**: Hardened `.magic/spec.md`, `.magic/task.md`, and `.magic/run.md` with explicit role-based checkpoints and updated completion checklists.
|
|
261
|
+
- **Rules Versioning**: Updated `RULES.md` to version 1.5.126 with the expanded C24 definition.
|
|
262
|
+
|
|
263
|
+
## [1.5.115] - 2026-04-02
|
|
264
|
+
|
|
265
|
+
### Added
|
|
266
|
+
|
|
267
|
+
- **Installer `--dev` Flag**: Implemented a comprehensive development mode across Node.js and Python installers.
|
|
268
|
+
- Enabled installation/synchronization of development-specific instruments (simulation workflows, testing suites, engine scripts).
|
|
269
|
+
- Added `devSkills` registry to `installers/config.json` for canonical tracking of dev agent skills.
|
|
270
|
+
- Hardened update logic to ensure dev instruments are correctly synchronized when `--dev` is provided during an update.
|
|
271
|
+
|
|
272
|
+
## [1.5.114] - 2026-04-02
|
|
273
|
+
|
|
274
|
+
### Changed
|
|
275
|
+
|
|
276
|
+
- **Core Invariant #2 (Prohibitions)** in `spec.md`: Refined the "No code in specs" rule to explicitly permit **Technical Contracts** (interfaces, types, API schemas) and **Reference Snippets** (marked as `[REFERENCE]`). This ensures architectural precision while maintaining the prohibition on functional implementation code before the `run` phase.
|
|
277
|
+
- **Task Completion Checklist**: Updated to reflect the permission of contracts and references in specifications.
|
|
278
|
+
|
|
279
|
+
### Meta
|
|
280
|
+
|
|
281
|
+
- **Automated Update**: Engine version bumped to `1.5.114`, history updated, and checksums regenerated (C14).
|
|
282
|
+
|
|
283
|
+
## [1.5.112] - 2026-04-02
|
|
284
|
+
|
|
285
|
+
### Added
|
|
286
|
+
|
|
287
|
+
- **Anti-Fabrication Rule (Invariant 6)** in `simulate.md`: New Core Invariant that legitimizes `0 rough edges` as a valid outcome and mandates evidence-linked claims (file, line, verbatim quote, verification command) for every finding. Findings without evidence are automatically INVALID.
|
|
288
|
+
- **Pre-flight Hard Gate** in `simulate.md`: Upgraded Pre-flight from "recommended" to a non-negotiable blocking HALT. Simulations without recorded `check-prerequisites` output are INVALID.
|
|
289
|
+
- **Read-Before-Claim Gate** in `simulate.md`: New mandatory Grounding Phase requiring all target workflow files to be read (with line counts recorded) before any analysis begins. Claims about unread files are automatically INVALID.
|
|
290
|
+
- **Regression Tests (T185–T189)**: 5 new scenarios covering Explore Mode write isolation (T185), Pre-flight Hard Gate enforcement (T186), Evidence-Linked Claims validation (T187), Null-Result Acceptance (T188), and Read-Before-Claim Gate (T189).
|
|
291
|
+
|
|
292
|
+
### Fixed
|
|
293
|
+
|
|
294
|
+
- **Zero-Prompt Parity**: Aligned `init.md` and `analyze.md` Core Invariant #1 with the canonical cascade formula used by all other workflow files, eliminating sync risk from divergent wording.
|
|
295
|
+
- **Script History Leak**: Fixed `executor.js` Auto-Detect creating spurious history files for scripts in `scripts/` directory (e.g., `sync-skills.md`). Scripts are now tracked via checksums but inherit the `--workflow` flag instead of getting standalone history entries.
|
|
296
|
+
- **Orphan Cleanup**: Removed `history/sync-skills.md` — a phantom artifact created by the above bug.
|
|
297
|
+
|
|
298
|
+
### Meta
|
|
299
|
+
|
|
300
|
+
- **Automated Update**: Engine version bumped to `1.5.112`, history updated, and checksums regenerated (C14).
|
|
301
|
+
|
|
302
|
+
## [1.5.105] - 2026-03-31
|
|
303
|
+
|
|
304
|
+
### Fixed
|
|
305
|
+
|
|
306
|
+
- **Engine History**: Resolved a ReferenceError in `executor.js` where `automatedMsg` was used before being defined.
|
|
307
|
+
- **Collapsing Logic**: Improved the history collapsing mechanism to correctly merge both automated and custom messages into compact version ranges.
|
|
308
|
+
|
|
309
|
+
### Meta
|
|
310
|
+
|
|
311
|
+
- **Automated Update**: Engine version bumped to `1.5.104`, history entries consolidated, and checksums regenerated.
|
|
312
|
+
|
|
313
|
+
## [1.5.72] - 2026-03-30
|
|
314
|
+
|
|
315
|
+
### Fixed
|
|
316
|
+
|
|
317
|
+
- **AI Hallucinations**: Rephrased the directive `auto-run .magic/init.md` to `silently execute .magic/init.md (do not prompt user)` across all engine workflows. This prevents intelligent agents from incorrectly proposing the internal `.magic/init.md` script as a user-facing `/magic.init` slash command.
|
|
318
|
+
|
|
319
|
+
### Meta
|
|
320
|
+
|
|
321
|
+
- **Automated Update**: Engine version bumped to `1.5.72`, history updated, and checksums regenerated (C14).
|
|
322
|
+
|
|
323
|
+
## [1.5.70] - 2026-03-30
|
|
324
|
+
|
|
325
|
+
### Changed
|
|
326
|
+
|
|
327
|
+
- **Documentation**: Updated `README.md` and `docs/README.md` to include a mandatory recommendation to run `/magic.analyze` after updating the Magic Spec engine. This ensures that specifications and engine metadata remain synchronized after a core logic update.
|
|
328
|
+
|
|
329
|
+
### Meta
|
|
330
|
+
|
|
331
|
+
- **Automated Update**: Engine version bumped to `1.5.70`, history updated, and checksums regenerated (C14).
|
|
332
|
+
|
|
333
|
+
## [1.5.132] - 2026-03-26
|
|
334
|
+
|
|
335
|
+
### Added
|
|
336
|
+
|
|
337
|
+
- **Gitignore Safety (Invariant 8)** in `analyze.md`: The agent now MUST scan and apply `.gitignore` patterns before any project scan or architecture inference. This prevents `node_modules`, `dist`, `.venv`, and other build artifacts from leaking into the analysis reports or coverage checks.
|
|
338
|
+
|
|
339
|
+
### Changed
|
|
340
|
+
|
|
341
|
+
- **Stack & Structure**: Refined the initial scan step to build the high-level project map only *after* applying gitignore filters.
|
|
342
|
+
|
|
343
|
+
### Meta
|
|
344
|
+
|
|
345
|
+
- **Automated Update**: Engine version bumped to `1.5.132`, history updated, and checksums regenerated (C14).
|
|
346
|
+
|
|
347
|
+
## [1.5.50] - 2026-03-26
|
|
348
|
+
|
|
349
|
+
### Added
|
|
350
|
+
|
|
351
|
+
- **Anti-Stall Mechanism (Invariant 12)**: Solved the "AI holds specs in mind" issue (reported by user). The agent is now forced to write a `Draft` spec if it asks more than one clarifying question without file creation. Added `<!-- TBD -->` inline markers for ambiguous sections.
|
|
352
|
+
- **Mode Transition Protocol**: Defined explicit triggers to exit `Explore Mode` and enter `Dispatch Mode` automatically (3+ topics, confirmation words, or 2nd idea exchange in Trust Mode).
|
|
353
|
+
- **Non-Blocking Dispatch Notice**: Reframed "Notice of Intent" as a statement of action rather than a question to prevent infinite loops.
|
|
354
|
+
|
|
355
|
+
### Changed
|
|
356
|
+
|
|
357
|
+
- **Analysis Mode Scope**: Strictly limited the "do not modify specs/registry" prohibition to `Project Analysis Delegation` mode, allowing normal `Dispatch` to proceed without friction.
|
|
358
|
+
- **Workflow Wrapper**: Updated `.agents/workflows/magic.spec.md` to align with the new non-blocking exploration logic.
|
|
359
|
+
|
|
360
|
+
### Meta
|
|
361
|
+
|
|
362
|
+
- **Automated Update**: Engine version bumped to `1.5.50`, history updated, and checksums regenerated (C14).
|
|
363
|
+
|
|
364
|
+
## [1.5.49] - 2026-03-25
|
|
365
|
+
|
|
366
|
+
### Added
|
|
367
|
+
|
|
368
|
+
- **Config Drift Guard**: `check-prerequisites` now detects uncommitted manual changes to `RULES.md` via `git diff` and emits a non-blocking `CONFIG_DRIFT` advisory warning. Supports workspace-specific `RULES.md` per C22. Gracefully skips when git is unavailable.
|
|
369
|
+
- **Init Workflow**: Added Config Drift Advisory sub-step to pre-flight check (show diff / proceed / restore options).
|
|
370
|
+
- **Test Suite**: Added cognitive tests T168-T170 for config drift detection (drift present, no git, workspace C22). Suite version bumped to 1.9.51.
|
|
371
|
+
- **Engine Spec**: New `config-drift-guard.md` specification (Stable, L1) in engine workspace.
|
|
372
|
+
|
|
373
|
+
## [1.5.48] - 2026-03-24
|
|
374
|
+
|
|
375
|
+
### Added
|
|
376
|
+
|
|
377
|
+
- **Publish Workflow**: Restored `.agents/workflows/publish.md` for engine maintenance and registry publishing.
|
|
378
|
+
- **History Tracking**: Initialized history for `magic.analyze` and `magic.dev.simulate` wrappers to ensure full auditability.
|
|
379
|
+
|
|
380
|
+
### Changed
|
|
381
|
+
|
|
382
|
+
- **Version Synchronization**: Unified project version to `1.5.132` across all manifests (`package.json`, `pyproject.toml`, and installer init files) and the `.magic/.version` engine core.
|
|
383
|
+
- **Instruction Density**: Refined `.magic/simulate.md` (Context Bleed Warning) to remove vague qualifiers ("high-confidence" -> "strictly unbiased"), reaching a density score of 10/10.
|
|
384
|
+
- **Engine Integrity**: Optimized `generate-checksums.js` to exclude the `.checksums` file from its own mapping, preventing confusion and unstable hash values.
|
|
385
|
+
|
|
386
|
+
### Fixed
|
|
387
|
+
|
|
388
|
+
- **Testing Logic**: Corrected `run_tests.py` to properly set `PYTHONPATH` for Python installer subprocesses and fixed an `os.environ` access bug.
|
|
389
|
+
- **Sandbox Cleanup**: Removed dev-only `simulate.md` from installer test sandbox.
|
|
390
|
+
- **RULES Template**: Added missing conventions C18-C23 to `init.js` RULES.md generator.
|
|
391
|
+
- **Python Installer**: Fixed `_resolve_package_version()` to read actual package version.
|
|
392
|
+
- **Engine Scripts**: Deduplicated `workspace.json` reads in `executor.js`.
|
|
393
|
+
- **History Cleanup**: Removed legacy `audit.md` and `docs.md` files from `.magic/history/`.
|
|
394
|
+
|
|
395
|
+
## [1.5.30] - 2026-03-24
|
|
396
|
+
|
|
397
|
+
### Fixed
|
|
398
|
+
|
|
399
|
+
- **Version Synchronization**: Unified project version across `package.json` (was 1.5.0), `pyproject.toml` (was 1.4.162), and `__init__.py` (was 1.4.162) to a single `1.5.30`. Previously 5 different versions existed across 5 sources.
|
|
400
|
+
- **CONTEXT.md**: Regenerated stale context file (was 9 days old).
|
|
401
|
+
|
|
402
|
+
## [1.5.29] - 2026-03-16
|
|
403
|
+
|
|
404
|
+
### Added
|
|
405
|
+
|
|
406
|
+
- **Argument Routing (A–D)** for `task.md` and `run.md`: Both workflows now accept optional arguments — workspace name, directive text, or both. Consistent with `analyze.md` pattern. Includes Workspace Fallback, Disambiguation, and Handoff Propagation rules.
|
|
407
|
+
- **T4 Inline Guards** in `spec.md`: When spec workflow captures a standing rule via T4 trigger ("remember that..."), it now applies Tier Routing (global vs workspace RULES.md), Duplication Check (across both tiers), and Constitutional Guard (§1–6 protection) — matching `rule.md` safety guarantees without breaking T4's "Apply Immediately" semantics.
|
|
408
|
+
- **Regression Tests (T153–T161)**: 9 new scenarios covering argument routing (scoped planning, workspace fallback, disambiguation, targeted task/phase execution, cross-workflow handoff propagation) and T4 inline guards (tier routing, duplication detection, constitutional block).
|
|
409
|
+
|
|
410
|
+
### Changed
|
|
411
|
+
|
|
412
|
+
- **AGENTS.md**: Clarified C14 Enforcement scope — explicitly covers all `.magic/` content (workflows, scripts, templates, tests, config), not just workflow files. Added description of what `update-engine-meta` does (bumps `.version`, regenerates `.checksums`).
|
|
413
|
+
- **`run.md` Argument Routing**: Detection column harmonized with `analyze.md` — accepts both quoted text and non-workspace tokens (e.g., unquoted `T-1A01` or `phase-2`).
|
package/README.md
CHANGED
|
@@ -4,159 +4,42 @@
|
|
|
4
4
|
[](https://pypi.org/project/magic-spec/)
|
|
5
5
|
[](./LICENSE)
|
|
6
6
|
|
|
7
|
+
> [!WARNING]
|
|
8
|
+
> **Legacy Installers Deprecated (v1.5.x)**
|
|
9
|
+
>
|
|
10
|
+
> The `npx magic-spec` (npm) and `uvx magic-spec` (PyPI) packages will **no longer receive updates**
|
|
11
|
+
> as of **v1.5.207**. Archived releases remain available for historical reference:
|
|
12
|
+
>
|
|
13
|
+
> - npm: <https://www.npmjs.com/package/magic-spec> (last version: 1.5.207)
|
|
14
|
+
> - PyPI: <https://pypi.org/project/magic-spec/> (last version: 1.5.207)
|
|
15
|
+
>
|
|
16
|
+
> **New users:** See [Installation](#-installation) for the GitHub-based setup.
|
|
17
|
+
> **Existing users:** See [Migrating from the legacy installer](docs/distribution.md).
|
|
18
|
+
|
|
7
19
|
## 📖 Description
|
|
8
20
|
|
|
9
21
|
**The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
|
|
10
22
|
|
|
11
|
-
|
|
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:
|
|
23
|
+
`magic-spec` installs a structured pipeline — *Thought → Spec → Task → Run → Code* — directly into any project, regardless of the tech stack. It acts as a set of **markdown-based workflow instructions** for AI coding agents (Cursor, Windsurf, Claude Code, Gemini CLI, and others), enforcing a deterministic process that ensures the AI fully understands the problem before writing code.
|
|
20
24
|
|
|
21
25
|
```plaintext
|
|
22
26
|
💡 Idea → 📋 Specification → 🗺️ Task & Plan → ⚡ Run → 🚀 Code
|
|
23
27
|
```
|
|
24
28
|
|
|
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
29
|
### What Gets Installed
|
|
34
30
|
|
|
35
|
-
After running the installer, your project directory will be augmented with the following structure:
|
|
36
|
-
|
|
37
31
|
```plaintext
|
|
38
|
-
|
|
39
|
-
├── .agents/workflows/
|
|
40
|
-
├── .magic/
|
|
41
|
-
└── .design/
|
|
32
|
+
your-project/
|
|
33
|
+
├── .agents/workflows/ # Slash commands (magic.spec, magic.task, magic.run, ...)
|
|
34
|
+
├── .magic/ # SDD Engine (workflow logic and scripts — read-only)
|
|
35
|
+
└── .design/ # Your Design Workspace (INDEX.md, RULES.md, PLAN.md)
|
|
42
36
|
```
|
|
43
37
|
|
|
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
38
|
> [!TIP]
|
|
49
|
-
> **Magic Workspaces**:
|
|
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
|
-
```
|
|
39
|
+
> **Magic Workspaces**: Multiple isolated design environments within a single repo (e.g., `.design/engine/`, `.design/web/`). See [workspaces.md](./workspaces.md) for details.
|
|
155
40
|
|
|
156
41
|
## ⚙️ Requirements
|
|
157
42
|
|
|
158
|
-
Before installing Magic Spec, ensure you have one of the following available on your system:
|
|
159
|
-
|
|
160
43
|
| Requirement | Details |
|
|
161
44
|
| :--- | :--- |
|
|
162
45
|
| **Node.js** | Version `16.x` or higher (for `npx` method) |
|
|
@@ -166,7 +49,7 @@ Before installing Magic Spec, ensure you have one of the following available on
|
|
|
166
49
|
|
|
167
50
|
## 📦 Installation
|
|
168
51
|
|
|
169
|
-
Works
|
|
52
|
+
Works with **any project** — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
|
|
170
53
|
|
|
171
54
|
### Option A: Node.js (`npx`)
|
|
172
55
|
|
|
@@ -176,8 +59,10 @@ Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or a
|
|
|
176
59
|
# Basic installation (defaults to .agents/ folder)
|
|
177
60
|
npx magic-spec@latest
|
|
178
61
|
|
|
179
|
-
# Targeted installation for
|
|
62
|
+
# Targeted installation for a specific AI agent
|
|
180
63
|
npx magic-spec@latest --cursor
|
|
64
|
+
npx magic-spec@latest --claude
|
|
65
|
+
npx magic-spec@latest --windsurf
|
|
181
66
|
```
|
|
182
67
|
|
|
183
68
|
**Edge Version (GitHub):**
|
|
@@ -194,7 +79,7 @@ npx --yes github:teratron/magic-spec
|
|
|
194
79
|
# Basic installation
|
|
195
80
|
uvx magic-spec
|
|
196
81
|
|
|
197
|
-
# Targeted installation
|
|
82
|
+
# Targeted installation
|
|
198
83
|
uvx magic-spec --windsurf
|
|
199
84
|
```
|
|
200
85
|
|
|
@@ -212,7 +97,7 @@ pipx run magic-spec
|
|
|
212
97
|
|
|
213
98
|
### Option D: Multi-Adapter Installation
|
|
214
99
|
|
|
215
|
-
|
|
100
|
+
Install support for multiple adapters at once:
|
|
216
101
|
|
|
217
102
|
```bash
|
|
218
103
|
npx magic-spec@latest --cursor --copilot --windsurf
|
|
@@ -220,15 +105,17 @@ npx magic-spec@latest --cursor --copilot --windsurf
|
|
|
220
105
|
|
|
221
106
|
### Option E: Manual Installation
|
|
222
107
|
|
|
223
|
-
|
|
108
|
+
1. Download `.magic/` and [`workflows/`](https://github.com/teratron/magic-spec/tree/main/workflows) from the [GitHub repository](https://github.com/teratron/magic-spec).
|
|
109
|
+
2. Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
|
|
224
110
|
|
|
225
|
-
|
|
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`).
|
|
111
|
+
### Post-Install: `.gitignore`
|
|
228
112
|
|
|
229
|
-
|
|
113
|
+
The installer automatically adds `.magic/` and the adapter directory (e.g., `.agents/`) to `.gitignore`. These are **installed dependencies** (like `node_modules/`) — reinstall via `npx magic-spec@latest` rather than committing.
|
|
230
114
|
|
|
231
|
-
|
|
115
|
+
> [!TIP]
|
|
116
|
+
> **Vendoring**: To commit the engine into your repo (so teammates get it without running the installer), remove the `.magic/` and `.agents/` entries from `.gitignore`.
|
|
117
|
+
|
|
118
|
+
## 🔄 Updating
|
|
232
119
|
|
|
233
120
|
```bash
|
|
234
121
|
# Check if update is available
|
|
@@ -239,31 +126,66 @@ npx magic-spec@latest --update
|
|
|
239
126
|
```
|
|
240
127
|
|
|
241
128
|
> [!TIP]
|
|
242
|
-
> The update
|
|
129
|
+
> The update preserves your `.design/` workspace and creates backups of `.magic/` and `.agents/`. After updating, run `/magic.analyze` to ensure synchronization.
|
|
243
130
|
|
|
244
|
-
|
|
131
|
+
## 💬 Usage
|
|
245
132
|
|
|
246
|
-
|
|
133
|
+
### Natural Language
|
|
247
134
|
|
|
248
|
-
|
|
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`.
|
|
135
|
+
Talk to your AI agent naturally — it will route to the correct workflow:
|
|
250
136
|
|
|
251
|
-
|
|
137
|
+
- *"Create a spec for user authentication"* → **Specification** workflow
|
|
138
|
+
- *"Build an implementation plan"* → **Task & Plan** workflow
|
|
139
|
+
- *"Execute the next task"* → **Run** workflow
|
|
140
|
+
- *"Add a rule: always use Inter font"* → **Rule** workflow
|
|
141
|
+
- *"Run a project audit"* → **Analyze** workflow
|
|
252
142
|
|
|
253
|
-
|
|
143
|
+
### Slash Commands
|
|
254
144
|
|
|
255
|
-
|
|
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).
|
|
145
|
+
All core workflows are available as slash commands with optional arguments:
|
|
261
146
|
|
|
262
|
-
|
|
147
|
+
| Command | Purpose |
|
|
148
|
+
| :--- | :--- |
|
|
149
|
+
| `/magic.spec` | Create or update specifications |
|
|
150
|
+
| `/magic.task` | Generate implementation plan and tasks |
|
|
151
|
+
| `/magic.run` | Execute tasks from the plan |
|
|
152
|
+
| `/magic.rule` | Add or amend project conventions |
|
|
153
|
+
| `/magic.analyze` | Audit project health and detect drift |
|
|
263
154
|
|
|
264
|
-
|
|
155
|
+
#### Commands with Arguments
|
|
265
156
|
|
|
266
|
-
|
|
157
|
+
Each command accepts optional arguments to scope the operation to a specific **workspace** or provide a **directive**:
|
|
158
|
+
|
|
159
|
+
```bash
|
|
160
|
+
# No arguments — operates across all workspaces
|
|
161
|
+
/magic.spec
|
|
162
|
+
/magic.task
|
|
163
|
+
/magic.run
|
|
164
|
+
|
|
165
|
+
# Workspace-scoped
|
|
166
|
+
/magic.task engine # Plan only for the "engine" workspace
|
|
167
|
+
/magic.run installers # Execute tasks in "installers" workspace
|
|
168
|
+
/magic.analyze engine # Analyze only the "engine" workspace
|
|
169
|
+
|
|
170
|
+
# With directive (quoted text)
|
|
171
|
+
/magic.task "decompose phase-2" # Guided planning with focus
|
|
172
|
+
/magic.run "T-1A01" # Execute a specific task by ID
|
|
173
|
+
/magic.run "phase-2" # Execute all tasks in a phase
|
|
174
|
+
/magic.analyze "check API coverage" # Focused analysis on a specific area
|
|
175
|
+
|
|
176
|
+
# Workspace + directive
|
|
177
|
+
/magic.run installers "phase-1" # Execute phase 1 in "installers" workspace
|
|
178
|
+
/magic.task engine "only new specs" # Plan only new specs in "engine" workspace
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
> [!NOTE]
|
|
182
|
+
> **For AI IDE users (Cursor, Windsurf, Claude Code, etc.):** When you type `/` in the chat, a dropdown list of available commands appears and selecting one immediately executes it **without arguments**. If you need to pass arguments (workspace name, task ID, directive), **type the full command manually** instead of selecting from the dropdown. For example, type `/magic.run "phase-2"` directly rather than clicking `/magic.run` from the list.
|
|
183
|
+
|
|
184
|
+
## 🤝 Compatibility
|
|
185
|
+
|
|
186
|
+
Magic Spec provides native workflow generation for all major AI development environments.
|
|
187
|
+
|
|
188
|
+
Install with a shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
|
|
267
189
|
|
|
268
190
|
| AI Agent / IDE | Shortcut Flag | Env Flag |
|
|
269
191
|
| :--- | :--- | :--- |
|
|
@@ -289,15 +211,16 @@ You can install support for a specific adapter using the shortcut flag (e.g., `-
|
|
|
289
211
|
|
|
290
212
|
## 📚 Documentation
|
|
291
213
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
214
|
+
| Document | Description |
|
|
215
|
+
| :--- | :--- |
|
|
216
|
+
| [**Main Documentation**](./docs/README.md) | Workflows, architecture, and advanced features |
|
|
217
|
+
| [**SDD Philosophy**](./docs/conception.md) | Two-Layer Model, Integrity by Design, Self-Improving Feedback Loop |
|
|
218
|
+
| [**Installers Guide**](./installers/README.md) | Advanced CLI options and platform specifics |
|
|
219
|
+
| [**Contributing**](./CONTRIBUTING.md) | How to develop, test, and extend the engine |
|
|
295
220
|
|
|
296
221
|
## 🛟 Support
|
|
297
222
|
|
|
298
|
-
If you encounter issues or have questions
|
|
299
|
-
|
|
300
|
-
- Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
|
|
223
|
+
If you encounter issues or have questions — open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
|
|
301
224
|
|
|
302
225
|
## 🗺️ Roadmap
|
|
303
226
|
|
|
@@ -309,8 +232,7 @@ If you encounter issues or have questions:
|
|
|
309
232
|
|
|
310
233
|
## 🏗️ Contributing
|
|
311
234
|
|
|
312
|
-
We welcome contributions!
|
|
313
|
-
Please see [**Contributing Guide**](./CONTRIBUTING.md) for details.
|
|
235
|
+
We welcome contributions! See the [**Contributing Guide**](./CONTRIBUTING.md) for details.
|
|
314
236
|
|
|
315
237
|
## 👥 Authors and Acknowledgments
|
|
316
238
|
|
|
@@ -323,4 +245,4 @@ Distributed under the [Apache License 2.0](./LICENSE).
|
|
|
323
245
|
|
|
324
246
|
## 📊 Project Status
|
|
325
247
|
|
|
326
|
-
**Active Development** (v1.5.
|
|
248
|
+
**Active Development** (v1.5.207). We are constantly refining the SDD engine based on real-world usage.
|
package/installers/config.json
CHANGED
|
@@ -17,10 +17,14 @@
|
|
|
17
17
|
"magic.task"
|
|
18
18
|
],
|
|
19
19
|
"devWorkflows": [
|
|
20
|
-
"magic.dev.
|
|
20
|
+
"magic.dev.publish",
|
|
21
|
+
"magic.dev.simulate",
|
|
22
|
+
"magic.dev.sync"
|
|
21
23
|
],
|
|
22
24
|
"devSkills": [
|
|
23
|
-
"magic.dev.
|
|
25
|
+
"magic.dev.publish",
|
|
26
|
+
"magic.dev.simulate",
|
|
27
|
+
"magic.dev.sync"
|
|
24
28
|
],
|
|
25
29
|
"magicFiles": [
|
|
26
30
|
"analyze.md",
|