magic-spec 1.4.162 → 1.5.48
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 +213 -171
- package/README.md +9 -11
- package/installers/config.json +13 -24
- package/installers/node/index.js +2 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,171 +1,213 @@
|
|
|
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.
|
|
9
|
-
|
|
10
|
-
### Added
|
|
11
|
-
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
- **
|
|
19
|
-
- **
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- **
|
|
25
|
-
- **
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
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
|
-
## [1.4.
|
|
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
|
-
## [1.3
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
- **
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|
-
-
|
|
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.48] - 2026-03-24
|
|
9
|
+
|
|
10
|
+
### Added
|
|
11
|
+
|
|
12
|
+
- **Publish Workflow**: Restored `.agents/workflows/publish.md` for engine maintenance and registry publishing.
|
|
13
|
+
- **History Tracking**: Initialized history for `magic.analyze` and `magic.dev.simulate` wrappers to ensure full auditability.
|
|
14
|
+
|
|
15
|
+
### Changed
|
|
16
|
+
|
|
17
|
+
- **Version Synchronization**: Unified project version to `1.5.47` across all manifests (`package.json`, `pyproject.toml`, `__init__.py`) and the `.magic/.version` engine core.
|
|
18
|
+
- **Instruction Density**: Refined `.magic/simulate.md` (Context Bleed Warning) to remove vague qualifiers ("high-confidence" -> "strictly unbiased"), reaching a density score of 10/10.
|
|
19
|
+
- **Engine Integrity**: Optimized `generate-checksums.js` to exclude the `.checksums` file from its own mapping, preventing confusion and unstable hash values.
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- **Testing Logic**: Corrected `run_tests.py` to properly set `PYTHONPATH` for Python installer subprocesses and fixed an `os.environ` access bug.
|
|
24
|
+
- **Sandbox Cleanup**: Removed dev-only `simulate.md` from installer test sandbox.
|
|
25
|
+
- **RULES Template**: Added missing conventions C18-C23 to `init.js` RULES.md generator.
|
|
26
|
+
- **Python Installer**: Fixed `_resolve_package_version()` to read actual package version.
|
|
27
|
+
- **Engine Scripts**: Deduplicated `workspace.json` reads in `executor.js`.
|
|
28
|
+
- **History Cleanup**: Removed legacy `audit.md` and `docs.md` files from `.magic/history/`.
|
|
29
|
+
|
|
30
|
+
## [1.5.30] - 2026-03-24
|
|
31
|
+
|
|
32
|
+
### Fixed
|
|
33
|
+
|
|
34
|
+
- **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.
|
|
35
|
+
- **CONTEXT.md**: Regenerated stale context file (was 9 days old).
|
|
36
|
+
|
|
37
|
+
## [1.5.29] - 2026-03-16
|
|
38
|
+
|
|
39
|
+
### Added
|
|
40
|
+
|
|
41
|
+
- **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.
|
|
42
|
+
- **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.
|
|
43
|
+
- **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).
|
|
44
|
+
|
|
45
|
+
### Changed
|
|
46
|
+
|
|
47
|
+
- **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`).
|
|
48
|
+
- **`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`).
|
|
49
|
+
|
|
50
|
+
## [1.4.162] - 2026-03-12
|
|
51
|
+
|
|
52
|
+
### Added
|
|
53
|
+
|
|
54
|
+
- **Session Isolation Rule (C17)**: Formalized the requirement for "New Chat" sessions between major workflow transitions (Spec → Task → Run) to prevent context bleed-over and hallucinations.
|
|
55
|
+
- **Multi-Workspace Support (C22)**: Enhanced `check-prerequisites.js` and `init.js` to support nested workspaces with inherited root rules.
|
|
56
|
+
- **Model-Aware History**: Updated engine history schema to include AI Model information, improving auditability of generated code.
|
|
57
|
+
|
|
58
|
+
### Changed
|
|
59
|
+
|
|
60
|
+
- **Task Checklist Logic**: Consolidated implementation checklists into `TASKS.md` for better execution tracking and status reporting.
|
|
61
|
+
- **Gitignore Resilience**: Improved installers to automatically manage `.gitignore` entries for `.magic/` and `.agents/` directories with idempotent updates.
|
|
62
|
+
- **Onboarding Safety**: Added production data collision guards to `onboard.md` to prevent accidental overwrites of existing project plans.
|
|
63
|
+
|
|
64
|
+
### Fixed
|
|
65
|
+
|
|
66
|
+
- **Error Reporting**: Enhanced `check-prerequisites.js` with structured, actionable JSON error suggestions.
|
|
67
|
+
- **Path Handling**: Fixed Windows-specific path issues in installer scripts.
|
|
68
|
+
|
|
69
|
+
## [1.4.162] - 2026-03-03
|
|
70
|
+
|
|
71
|
+
### Added
|
|
72
|
+
|
|
73
|
+
- **Regression Test T85**: Verifies mandatory engine integrity HALT when `.magic/` files are tampered (C1 enforcement).
|
|
74
|
+
|
|
75
|
+
### Changed
|
|
76
|
+
|
|
77
|
+
- **Engine Integrity Halt**: Upgraded `check-prerequisites.js` to set `ok: false` on checksum mismatches, ensuring a hard HALT during pre-flight checks.
|
|
78
|
+
- **History Auto-Heal**: Enhanced `executor.js` to automatically recreate the `.magic/history/` directory and missing history files if deleted.
|
|
79
|
+
|
|
80
|
+
### Fixed
|
|
81
|
+
|
|
82
|
+
- **Resilient Logic**: Improved `check-prerequisites.js` to distinguish between critical engine integrity (HALT) and project data drift (WARNING), preserving self-healing capabilities.
|
|
83
|
+
|
|
84
|
+
## [1.4.162] - 2026-03-02
|
|
85
|
+
|
|
86
|
+
### Changed
|
|
87
|
+
|
|
88
|
+
- **Executor Refactor**: Improved `executor.js` structure by replacing global `return` with an `else` block for better readability and standard Node.js practices.
|
|
89
|
+
- **Test Suite Cleanup**: Removed duplicate T54 "Spec Rename History Immutability" scenario from `suite.md`.
|
|
90
|
+
|
|
91
|
+
### Meta
|
|
92
|
+
|
|
93
|
+
- **Automated Update**: Sequential patch bump, history update, and checksum regeneration via `update-engine-meta`.
|
|
94
|
+
|
|
95
|
+
## [1.4.5] - 2026-03-01
|
|
96
|
+
|
|
97
|
+
### Added
|
|
98
|
+
|
|
99
|
+
- **Engine Versioning Protocol (C14)**: Established a mandatory convention requiring a patch version bump in `.magic/.version` whenever core engine files are modified. Integrated checkpoints into all primary workflows (`run.md`, `spec.md`, `rule.md`).
|
|
100
|
+
- **History Refactoring**: Extracted "Document History" from core workflow markdown files into a dedicated `.magic/history/` directory. This significantly reduces token consumption during agentic operations while preserving audit trials.
|
|
101
|
+
- **Node.js Script Transition**: Fully replaced legacy `.sh` and `.ps1` initialization and utility scripts with cross-platform Node.js implementations (`init.js`, `generate-context.js`, etc.).
|
|
102
|
+
|
|
103
|
+
### Changed
|
|
104
|
+
|
|
105
|
+
- **Installer Configuration**: Optimized `installers/config.json` to exclude history files from distribution and prioritize Node.js scripts.
|
|
106
|
+
- **Engine Security**: `generate-checksums.js` and `executor.js` now explicitly skip history files to prevent non-functional changes from triggering integrity warnings.
|
|
107
|
+
- **Template System**: `init.js` now automatically injects the new C14 protocol into target project constitution files (`RULES.md`).
|
|
108
|
+
|
|
109
|
+
### Fixed
|
|
110
|
+
|
|
111
|
+
- **Syntax Hygiene**: Cleaned up redundant markdown artifacts (terminal backticks) in core workflow files.
|
|
112
|
+
- **Workflow Integrity**: Fixed accidental history duplication in `spec.md`.
|
|
113
|
+
|
|
114
|
+
## [1.4.3] - 2026-03-01
|
|
115
|
+
|
|
116
|
+
### Added
|
|
117
|
+
|
|
118
|
+
- **Smart Adapter Updates**: Both Python and Node.js installers now seamlessly verify and update adapter `.mdc`/`.toml` wrapper files during `--update`.
|
|
119
|
+
- **Smart Update Conflict Resolution**: When users manually modify `.cursor/rules/*` wrapper files in their project, the `--update` command now detects the modifications. Users can intelligently choose to skip updates for specific conflicting adapter files, preserving their changes while updating the core `.magic` engine logic.
|
|
120
|
+
|
|
121
|
+
### Fixed
|
|
122
|
+
|
|
123
|
+
- **Updater Integrity**: Modified files that are bypassed during an update via `[s] Skip modified files` now persist their original hashes so they don't get silently overwritten in subsequent updates.
|
|
124
|
+
- **Testing Logic**: Fixed an issue in the `run_tests.py` exhaustive test suite section where failures during adapter testing cycles were mistakenly swallowed, reporting a false "All tests completed successfully".
|
|
125
|
+
|
|
126
|
+
## [1.4.1] - 2026-03-01
|
|
127
|
+
|
|
128
|
+
### Fixed
|
|
129
|
+
|
|
130
|
+
- **Localization**: Translated remaining Russian text in `README.md` Mermaid diagrams to English.
|
|
131
|
+
|
|
132
|
+
## [1.4.0] - 2026-03-01
|
|
133
|
+
|
|
134
|
+
### Added
|
|
135
|
+
|
|
136
|
+
- **Smart Sync Optimization (AOP)** in `analyze.md`: Automated detection of manual renames during project re-analysis. If an orphaned specification matches a new uncovered directory (>80% similarity or title match), it triggers a `[RESCUE]` action instead of delete/create cycle.
|
|
137
|
+
- **Manual Rename Rescue** in `spec.md`: Protocol to globally update references (INDEX, PLAN, TASKS) when a specification file is moved/renamed, preserving task progress.
|
|
138
|
+
- **Regression Tests (T48–T51)**: Added coverage for Engine Integrity guards, Analysis Depth Control, and Smart Sync mechanisms.
|
|
139
|
+
|
|
140
|
+
### Changed
|
|
141
|
+
|
|
142
|
+
- **Test Suite Synchronization**: The `suite.md` version is now synchronized with the core engine version to prevent metadata confusion.
|
|
143
|
+
|
|
144
|
+
## [1.3.2] - 2026-02-28
|
|
145
|
+
|
|
146
|
+
### Added
|
|
147
|
+
|
|
148
|
+
- **Project Analysis Workflow** (`.magic/analyze.md`): Powerful reverse-engineering tool. Delegated automatically from `spec.md` or directly via `/magic.analyze`. Supports scanning existing source code to generate structured proposals with paired Layer 1 (Concept) and Layer 2 (Implementation) specifications. Features Depth Control for massive codebases.
|
|
149
|
+
- **Bootstrapping Exemption**: Special rules added to bypass standard Draft/RFC phases and create "Stable" specs directly when adopting existing working code into the SDD system.
|
|
150
|
+
- **Improv Mode (Live Simulation)** in `simulate.md`: Added ability for the simulation workflow to synthesize "crisis scenarios" (e.g., INDEX.md desync) and perform full SDK lifecycle stress tests end-to-end on its own, functioning as a fallback if the static test suite is missing.
|
|
151
|
+
|
|
152
|
+
### Changed
|
|
153
|
+
|
|
154
|
+
- Expanded Test Suite (`.magic/tests/suite.md`) from 28 to 34 scenarios (+6), fully covering Analyze gap detection, L1/L2 generation asserts, depth control limits, and the missing test suite fallback.
|
|
155
|
+
|
|
156
|
+
## [1.3.1] - 2026-02-27### Added
|
|
157
|
+
|
|
158
|
+
- **Workflow Test Suite** (`.magic/tests/suite.md`): 16 predefined regression test scenarios covering all 8 engine workflows. Run via `/magic.dev.simulate test`.
|
|
159
|
+
- **Test Suite mode** in `simulate.md`: reads `suite.md` and reports PASS/FAIL for each scenario.
|
|
160
|
+
- **Template directory** (`.magic/templates/`): extracted inline templates from core workflow files:
|
|
161
|
+
- `specification.md` — Specification Template (from `spec.md`)
|
|
162
|
+
- `plan.md` — PLAN.md Template (from `task.md`)
|
|
163
|
+
- `tasks.md` — TASKS.md + phase-{n}.md Templates (from `task.md`)
|
|
164
|
+
- `retrospective.md` — RETROSPECTIVE.md Template (from `retrospective.md`)
|
|
165
|
+
|
|
166
|
+
### Changed
|
|
167
|
+
|
|
168
|
+
- **AOP Optimization**: Compressed verbose prose in `spec.md` (Post-Update Review, Audit/Consistency Reports). ~17% token reduction across core workflows.
|
|
169
|
+
- **Stress-test hardening** across all workflows:
|
|
170
|
+
- `spec.md`: Intra-input self-contradiction guard, Deprecation Cascade (scan Related Specs for stale refs)
|
|
171
|
+
- `task.md`: Circular Dependency Guard, Phantom Done-task preservation (Archive not Cancel), Deprecated Done-task preservation, Convention Sync wording fix
|
|
172
|
+
- `run.md`: Mode Guard — HALT if execution mode not in RULES.md §7
|
|
173
|
+
- `rule.md`: Duplication Guard, convention-not-found handler, Workflow Dependency Check in Remove Impact Analysis
|
|
174
|
+
- `simulate.md`: Checksums mismatch upgraded to HALT, Checksum Rule (generate after approval only)
|
|
175
|
+
- `onboard.md`: Production collision HALT with backup/cancel, re-entry checks production PLAN.md
|
|
176
|
+
- `init.md`: Expanded post-init verification to all 5 artifacts, Maintainer Note for hardcoded RULES.md sync
|
|
177
|
+
|
|
178
|
+
### Fixed
|
|
179
|
+
|
|
180
|
+
- Template references now explicitly point to `.magic/templates/*.md` in creation steps of `spec.md`, `task.md`, `retrospective.md`, and `onboard.md`.
|
|
181
|
+
|
|
182
|
+
## [1.3.0] - 2026-02-25
|
|
183
|
+
|
|
184
|
+
### Added
|
|
185
|
+
|
|
186
|
+
- **Full support for abstract environment templates** with automatic resolution (`{ARGUMENTS}`) across all CLIs.
|
|
187
|
+
- **Introduced `.magicrc`** for persistence of selected environments and their auto-detection.
|
|
188
|
+
- **Two-level automatic Changelog generation** (by accumulating `Changes` blocks within tasks).
|
|
189
|
+
- **Added new CLI commands:** `info`, `--check`, `--list-envs`, and `--eject`.
|
|
190
|
+
- **Introduced core version tracking** within the project via the `.magic/.version` file.
|
|
191
|
+
|
|
192
|
+
### Changed
|
|
193
|
+
|
|
194
|
+
- **Architecture:** Restructured the repository into a two-level model (root = source of truth + installers), and removed the `core/` folder to eliminate duplication.
|
|
195
|
+
- **Node Installer:** Completely overhauled the installation mechanism (it now uses compiled files from NPM instead of downloading them from GitHub, eliminating Path Traversal vulnerabilities).
|
|
196
|
+
- **Python Installer:** Implemented an isolated package based on `hatchling` (via shared-data) without external dependencies on GitHub.
|
|
197
|
+
- **Documentation:** Separated `README.md` strategies (different focuses for GitHub, NPM package, and PyPI package).
|
|
198
|
+
- **Update Logic:** Improved `.magic` update logic to be safer (old folders are now moved to `.magic/archives/` rather than simply deleted).
|
|
199
|
+
|
|
200
|
+
## [1.3.0] - 2026-02-23
|
|
201
|
+
|
|
202
|
+
### Added
|
|
203
|
+
|
|
204
|
+
- **Handoff integrations** (`magic.*.md`): Introduced explicit handoff blocks across all agent workflow wrappers to guide next-steps effortlessly.
|
|
205
|
+
- **Task Engine Enhancement:** Integrated User Stories generation parsing into `.magic/task.md` and suppressed user priority prompts using `RULES.md C4`.
|
|
206
|
+
- **System Automation Hooks:** Added `generate-context` script hooks into `task.md` and `run.md` post-write triggers.
|
|
207
|
+
- **Context Automation Script:** Created `generate-context.sh` and `generate-context.ps1` to assemble `CONTEXT.md` from PLAN, workspace trees, and changelogs.
|
|
208
|
+
- **Spec Engine Protections:** Added strict Explore Mode Safety rules and Delta Editing constraints for spec updates over 200 lines to `.magic/spec.md`.
|
|
209
|
+
- **Explore Hints:** Updated `.agents/workflows/magic.spec.md` UI wrapper with tips to use Delta Constraints and strict read-only explore mode.
|
|
210
|
+
- **CLI Doctor Command (Node/Python):** Implemented `--doctor` and `--check` parsing in installers, executing the prerequisite script and outputting a formatted terminal validation report.
|
|
211
|
+
- **Interactive Onboarding Script:** Created `.magic/onboard.md` to guide new developers through building a toy "console logger" specification.
|
|
212
|
+
- **Onboarding Wrapper:** Added `.agents/workflows/magic.onboard.md` to trigger the interactive onboarding tutorial seamlessly.
|
|
213
|
+
- **Prerequisite Validation:** Created `check-prerequisites.sh` and `check-prerequisites.ps1` parsing `INDEX.md` and returning valid JSON results.
|
package/README.md
CHANGED
|
@@ -36,15 +36,14 @@ After running the installer, your project directory will be augmented with the f
|
|
|
36
36
|
|
|
37
37
|
```plaintext
|
|
38
38
|
root-project/
|
|
39
|
-
├── .
|
|
39
|
+
├── .agents/workflows/ # Slash commands wrapper (e.g., magic.spec, magic.task)
|
|
40
40
|
├── .magic/ # The SDD Engine (workflow logic and scripts - read-only)
|
|
41
41
|
└── .design/ # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
|
|
42
42
|
```
|
|
43
43
|
|
|
44
44
|
1. **`.magic/`**: Deploys the core SDD engine.
|
|
45
|
-
2. **`.
|
|
45
|
+
2. **`.agents/`**: Sets up workflows for your AI.
|
|
46
46
|
3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
|
|
47
|
-
4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
|
|
48
47
|
|
|
49
48
|
> [!TIP]
|
|
50
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.
|
|
@@ -172,7 +171,7 @@ Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or a
|
|
|
172
171
|
**Stable Release:**
|
|
173
172
|
|
|
174
173
|
```bash
|
|
175
|
-
# Basic installation (defaults to .
|
|
174
|
+
# Basic installation (defaults to .agents/ folder)
|
|
176
175
|
npx magic-spec@latest
|
|
177
176
|
|
|
178
177
|
# Targeted installation for Cursor
|
|
@@ -222,7 +221,7 @@ npx magic-spec@latest --cursor --copilot --windsurf
|
|
|
222
221
|
If automated installers do not fit your environment:
|
|
223
222
|
|
|
224
223
|
1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
|
|
225
|
-
2. **Workflows**: Download command wrappers from [
|
|
224
|
+
2. **Workflows**: Download command wrappers from [`workflows/`](https://github.com/teratron/magic-spec/tree/main/workflows).
|
|
226
225
|
3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
|
|
227
226
|
|
|
228
227
|
## 🔄 Updating
|
|
@@ -238,14 +237,14 @@ npx magic-spec@latest --update
|
|
|
238
237
|
```
|
|
239
238
|
|
|
240
239
|
> [!TIP]
|
|
241
|
-
> The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.
|
|
240
|
+
> 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).
|
|
242
241
|
|
|
243
242
|
### Post-Install: `.gitignore`
|
|
244
243
|
|
|
245
|
-
The installer automatically adds `.magic/` and the adapter directory (e.g., `.
|
|
244
|
+
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.
|
|
246
245
|
|
|
247
246
|
> [!TIP]
|
|
248
|
-
> **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.
|
|
247
|
+
> **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`.
|
|
249
248
|
|
|
250
249
|
## 💬 Usage
|
|
251
250
|
|
|
@@ -289,14 +288,13 @@ You can install support for a specific adapter using the shortcut flag (e.g., `-
|
|
|
289
288
|
|
|
290
289
|
- [**Main Documentation**](./docs/README.md) — Detailed guide on workflows, architecture, and advanced features.
|
|
291
290
|
- [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
|
|
292
|
-
- [**Contributing**](./
|
|
291
|
+
- [**Contributing**](./CONTRIBUTING.md) — How to develop, test, and extend the engine.
|
|
293
292
|
|
|
294
293
|
## 🛟 Support
|
|
295
294
|
|
|
296
295
|
If you encounter issues or have questions:
|
|
297
296
|
|
|
298
297
|
- Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
|
|
299
|
-
- Run `magic.onboard` in your agent to restart the interactive tutorial.
|
|
300
298
|
|
|
301
299
|
## 🗺️ Roadmap
|
|
302
300
|
|
|
@@ -309,7 +307,7 @@ If you encounter issues or have questions:
|
|
|
309
307
|
## 🏗️ Contributing
|
|
310
308
|
|
|
311
309
|
We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
|
|
312
|
-
Please see [**Contributing Guide**](./
|
|
310
|
+
Please see [**Contributing Guide**](./CONTRIBUTING.md) for details.
|
|
313
311
|
|
|
314
312
|
## 👥 Authors and Acknowledgments
|
|
315
313
|
|
package/installers/config.json
CHANGED
|
@@ -1,31 +1,27 @@
|
|
|
1
1
|
{
|
|
2
2
|
"githubRepo": "teratron/magic-spec",
|
|
3
3
|
"packageName": "magic-spec",
|
|
4
|
-
"removePrefix": "magic.",
|
|
5
4
|
"engineDir": ".magic",
|
|
6
|
-
"agentDir": ".
|
|
5
|
+
"agentDir": ".agents",
|
|
7
6
|
"workflowsDir": "workflows",
|
|
7
|
+
"defaultExt": ".md",
|
|
8
8
|
"designDir": ".design",
|
|
9
9
|
"versionFile": ".version",
|
|
10
10
|
"checksumsFile": ".checksums",
|
|
11
11
|
"historyDir": "history",
|
|
12
|
-
"defaultExt": ".md",
|
|
13
12
|
"workflows": [
|
|
14
13
|
"magic.analyze",
|
|
15
|
-
"magic.onboard",
|
|
16
14
|
"magic.rule",
|
|
17
15
|
"magic.run",
|
|
18
|
-
"magic.simulate",
|
|
19
16
|
"magic.spec",
|
|
20
17
|
"magic.task"
|
|
21
18
|
],
|
|
22
19
|
"magicFiles": [
|
|
23
20
|
"analyze.md",
|
|
24
|
-
"
|
|
21
|
+
"init.md",
|
|
25
22
|
"retrospective.md",
|
|
26
23
|
"rule.md",
|
|
27
24
|
"run.md",
|
|
28
|
-
"simulate.md",
|
|
29
25
|
"spec.md",
|
|
30
26
|
"task.md",
|
|
31
27
|
".version",
|
|
@@ -41,39 +37,32 @@
|
|
|
41
37
|
"templates/tasks.md"
|
|
42
38
|
],
|
|
43
39
|
"download": {
|
|
44
|
-
"timeoutMs":
|
|
45
|
-
"tempPrefix": "magic-spec-"
|
|
40
|
+
"timeoutMs": 10000,
|
|
41
|
+
"tempPrefix": "magic-spec-tmp-"
|
|
46
42
|
},
|
|
47
43
|
"userAgent": {
|
|
48
|
-
"
|
|
49
|
-
"
|
|
44
|
+
"python": "magic-spec-python-installer/1.0",
|
|
45
|
+
"node": "magic-spec-node-installer/1.0"
|
|
50
46
|
},
|
|
51
47
|
"eject": {
|
|
52
48
|
"targets": [
|
|
53
49
|
".magic",
|
|
54
|
-
".
|
|
55
|
-
"
|
|
56
|
-
".agent.bak"
|
|
50
|
+
".agents",
|
|
51
|
+
"installers"
|
|
57
52
|
]
|
|
58
53
|
},
|
|
59
54
|
"publish": {
|
|
60
55
|
"versionFiles": [
|
|
61
|
-
"pyproject.toml",
|
|
62
|
-
"installers/python/magic_spec/__init__.py",
|
|
63
56
|
"package.json",
|
|
64
|
-
".
|
|
57
|
+
"pyproject.toml",
|
|
58
|
+
"installers/python/magic_spec/__init__.py"
|
|
65
59
|
],
|
|
66
60
|
"docsTargets": [
|
|
67
|
-
"README.md",
|
|
68
61
|
"CHANGELOG.md"
|
|
69
|
-
]
|
|
70
|
-
"docsDir": "docs"
|
|
71
|
-
},
|
|
72
|
-
"git": {
|
|
73
|
-
"defaultBranch": "master"
|
|
62
|
+
]
|
|
74
63
|
},
|
|
75
64
|
"tests": {
|
|
76
|
-
"sandboxDir": "
|
|
65
|
+
"sandboxDir": "tmp/sandbox",
|
|
77
66
|
"adaptersJson": "installers/adapters.json",
|
|
78
67
|
"pythonInstaller": "installers/python/magic_spec/__main__.py",
|
|
79
68
|
"nodeInstaller": "installers/node/index.js",
|
package/installers/node/index.js
CHANGED
|
@@ -297,7 +297,7 @@ function installAdapter(sourceRoot, env, adapters, conflictsToSkip = []) {
|
|
|
297
297
|
installedChecksums[relTarget] = crypto.createHash('sha256').update(finalContent).digest('hex');
|
|
298
298
|
}
|
|
299
299
|
|
|
300
|
-
// Copy other files in .
|
|
300
|
+
// Copy other files in .agents if any
|
|
301
301
|
const srcEng = path.join(sourceRoot, AGENT_DIR);
|
|
302
302
|
if (fs.existsSync(srcEng)) {
|
|
303
303
|
const items = fs.readdirSync(srcEng, { withFileTypes: true });
|
|
@@ -893,7 +893,7 @@ async function main() {
|
|
|
893
893
|
}
|
|
894
894
|
}
|
|
895
895
|
|
|
896
|
-
// Copy other files in .
|
|
896
|
+
// Copy other files in .agents if any (not workflows subfolder which we handled selectively)
|
|
897
897
|
if (fs.existsSync(srcEng)) {
|
|
898
898
|
const items = fs.readdirSync(srcEng, { withFileTypes: true });
|
|
899
899
|
for (const item of items) {
|