magic-spec 1.4.3 β†’ 1.4.77

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +46 -1
  2. package/README.md +309 -258
  3. package/installers/config.json +4 -6
  4. package/installers/node/index.js +1 -1
  5. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.4.77] - 2026-03-03
9
+
10
+ ### Added
11
+
12
+ - **Regression Test T85**: Verifies mandatory engine integrity HALT when `.magic/` files are tampered (C1 enforcement).
13
+
14
+ ### Changed
15
+
16
+ - **Engine Integrity Halt**: Upgraded `check-prerequisites.js` to set `ok: false` on checksum mismatches, ensuring a hard HALT during pre-flight checks.
17
+ - **History Auto-Heal**: Enhanced `executor.js` to automatically recreate the `.magic/history/` directory and missing history files if deleted.
18
+
19
+ ### Fixed
20
+
21
+ - **Resilient Logic**: Improved `check-prerequisites.js` to distinguish between critical engine integrity (HALT) and project data drift (WARNING), preserving self-healing capabilities.
22
+
23
+ ## [1.4.77] - 2026-03-02
24
+
25
+ ### Changed
26
+
27
+ - **Executor Refactor**: Improved `executor.js` structure by replacing global `return` with an `else` block for better readability and standard Node.js practices.
28
+ - **Test Suite Cleanup**: Removed duplicate T54 "Spec Rename History Immutability" scenario from `suite.md`.
29
+
30
+ ### Meta
31
+
32
+ - **Automated Update**: Sequential patch bump, history update, and checksum regeneration via `update-engine-meta`.
33
+
34
+ ## [1.4.5] - 2026-03-01
35
+
36
+ ### Added
37
+
38
+ - **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`).
39
+ - **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.
40
+ - **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.).
41
+
42
+ ### Changed
43
+
44
+ - **Installer Configuration**: Optimized `installers/config.json` to exclude history files from distribution and prioritize Node.js scripts.
45
+ - **Engine Security**: `generate-checksums.js` and `executor.js` now explicitly skip history files to prevent non-functional changes from triggering integrity warnings.
46
+ - **Template System**: `init.js` now automatically injects the new C14 protocol into target project constitution files (`RULES.md`).
47
+
48
+ ### Fixed
49
+
50
+ - **Syntax Hygiene**: Cleaned up redundant markdown artifacts (terminal backticks) in core workflow files.
51
+ - **Workflow Integrity**: Fixed accidental history duplication in `spec.md`.
52
+
8
53
  ## [1.4.3] - 2026-03-01
9
54
 
10
55
  ### Added
@@ -17,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
17
62
  - **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.
18
63
  - **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".
19
64
 
20
- ## [1.4.3] - 2026-03-01
65
+ ## [1.4.1] - 2026-03-01
21
66
 
22
67
  ### Fixed
23
68
 
package/README.md CHANGED
@@ -1,258 +1,309 @@
1
- # πŸͺ„ Magic Spec
2
-
3
- [![NPM version](https://img.shields.io/npm/v/magic-spec?color=green&label=npm)](https://www.npmjs.com/package/magic-spec)
4
- [![PyPI version](https://img.shields.io/pypi/v/magic-spec?color=blue&label=pypi)](https://pypi.org/project/magic-spec/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
6
-
7
- ## πŸ“– Description
8
-
9
- **The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
10
-
11
- Stop your AI from writing fragile code before it fully understands the problem. `magic-spec` installs a high-performance, structured pipeline β€” *Thought β†’ Spec β†’ Task β†’ Run β†’ Code* β€” directly into any project, regardless of the tech stack.
12
-
13
- Whether you are a **coding novice** building your first application or a **senior engineer** architecting enterprise systems, Magic Spec brings **maximum automation** and professional rigor to your development process. It enforces a deterministic workflow that ensures your AI agent perfectly aligns with your vision before writing a single line of code.
14
-
15
- ### The Core Concept
16
-
17
- `magic-spec` is a set of **markdown-based workflow instructions** specifically designed for AI coding agents like Cursor, Windsurf, Claude, and Gemini. It acts as a project-level operating system that orchestrates agentic development.
18
-
19
- Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
20
-
21
- ```plaintext
22
- πŸ’‘ Idea β†’ πŸ“‹ Specification β†’ πŸ—ΊοΈ Task & Plan β†’ ⚑ Run β†’ πŸš€ Code
23
- ```
24
-
25
- Once initialized, your AI agent will automatically:
26
-
27
- - Formulate a strong conceptual and technical specification.
28
- - Build a phased implementation plan with hierarchical dependencies.
29
- - Decompose the plan into prioritized, atomic, trackable tasks.
30
- - Facilitate safe architectural brainstorming via **Explore Mode**.
31
- - Analyze its own workflow and suggest improvements via Auto-Retrospectives.
32
-
33
- ### What Gets Installed
34
-
35
- After running the installer, your project directory will be augmented with the following structure:
36
-
37
- ```plaintext
38
- root-project/
39
- β”œβ”€β”€ .agent/workflows/ # Slash commands wrapper (e.g., magic.spec, magic.task)
40
- β”œβ”€β”€ .magic/ # The SDD Engine (workflow logic and scripts - read-only)
41
- └── .design/ # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
42
- ```
43
-
44
- 1. **`.magic/`**: Deploys the core SDD engine.
45
- 2. **`.agent/`**: Sets up workflows for your AI.
46
- 3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
47
- 4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
48
-
49
- > [!TIP]
50
- > **Magic Workspaces**: Magic Spec supports multiple, isolated design environments within a single repository (e.g., `.design/engine/`, `.design/installers/`). This allows you to manage fundamentally different project domains without specification overlap, while sharing a single core engine. See [workspaces.md](./workspaces.md) for details.
51
-
52
- ## πŸ–ΌοΈ Visuals
53
-
54
- The engine enforces a rigorous, unskippable pipeline: **Idea β†’ Specification β†’ Task & Plan β†’ Code**. AI agents are prevented from jumping straight to coding. They must first formally specify the solution, then break it down into a concrete plan and tasks, and only then proceed to execution.
55
-
56
- ```mermaid
57
- flowchart TB
58
- IDEA(["πŸ’‘ Idea"])
59
-
60
- subgraph BOX ["Magic Spec"]
61
- direction TB
62
-
63
- SPEC["πŸ“‹ Spec"]
64
-
65
- subgraph TASK ["πŸ—ΊοΈ Task"]
66
- direction TB
67
- PLAN["πŸ“ Plan"]
68
- TASKS["πŸ“Œ Tasks"]
69
- PLAN --> TASKS
70
- end
71
-
72
- RUN["⚑ Run"]
73
-
74
- SPEC --> PLAN
75
- TASKS --> RUN
76
- end
77
-
78
- CODE(["πŸš€ Code"])
79
-
80
- IDEA --> SPEC
81
- RUN --> CODE
82
-
83
- style IDEA fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
84
- style CODE fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
85
-
86
- style BOX fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
87
-
88
- style SPEC fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
89
- style RUN fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
90
-
91
- style TASK fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
92
- style PLAN fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
93
- style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
94
- ```
95
-
96
- ## βš™οΈ Requirements
97
-
98
- Before installing Magic Spec, ensure you have one of the following available on your system:
99
-
100
- | Requirement | Details |
101
- | :--- | :--- |
102
- | **Node.js** | Version `16.x` or higher (for `npx` method) |
103
- | **Python** | Version `3.8` or higher (for `uvx` or `pipx` methods) |
104
- | **Git** | Required for installing edge versions directly from GitHub |
105
- | **Terminal** | `tar` utility (pre-installed on Windows/Linux/macOS) |
106
-
107
- ## πŸ“¦ Installation
108
-
109
- Works perfectly with **any project** β€” Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
110
-
111
- ### Option A: Node.js (`npx`)
112
-
113
- **Stable Release:**
114
-
115
- ```bash
116
- # Basic installation (defaults to .agent/ folder)
117
- npx magic-spec@latest
118
-
119
- # Targeted installation for Cursor
120
- npx magic-spec@latest --cursor
121
- ```
122
-
123
- **Edge Version (GitHub):**
124
-
125
- ```bash
126
- npx --yes github:teratron/magic-spec
127
- ```
128
-
129
- ### Option B: Python (`uvx`)
130
-
131
- **Stable Release:**
132
-
133
- ```bash
134
- # Basic installation
135
- uvx magic-spec
136
-
137
- # Targeted installation for Windsurf
138
- uvx magic-spec --windsurf
139
- ```
140
-
141
- **Edge Version (GitHub):**
142
-
143
- ```bash
144
- uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
145
- ```
146
-
147
- ### Option C: Python (`pipx`)
148
-
149
- ```bash
150
- pipx run magic-spec
151
- ```
152
-
153
- ### Option D: Multi-Adapter Installation
154
-
155
- You can install support for multiple adapters at once:
156
-
157
- ```bash
158
- npx magic-spec@latest --cursor --copilot --windsurf
159
- ```
160
-
161
- ### Option E: Manual Installation
162
-
163
- If automated installers do not fit your environment:
164
-
165
- 1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
166
- 2. **Workflows**: Download command wrappers from [`.agent/workflows/`](https://github.com/teratron/magic-spec/tree/main/.agent/workflows).
167
- 3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
168
-
169
- ## πŸ”„ Updating
170
-
171
- Keep your SDD engine up to date with the latest logic and features:
172
-
173
- ```bash
174
- # Check if update is available
175
- npx magic-spec@latest --check
176
-
177
- # Perform the update
178
- npx magic-spec@latest --update
179
- ```
180
-
181
- > [!TIP]
182
- > The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agent/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort).
183
-
184
- ## πŸ’¬ Usage
185
-
186
- Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
187
-
188
- - *"Dispatch this thought into specs..."* β†’ Triggers **Specification** workflow.
189
- - *"Create an implementation plan"* β†’ Triggers **Task & Plan** workflow.
190
- - *"Execute the next task"* β†’ Triggers **Run** workflow.
191
- - *"Add a rule: always use Inter font"* β†’ Triggers **Rule** workflow.
192
-
193
- ### 🀝 Compatibility
194
-
195
- Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
196
-
197
- You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
198
-
199
- | AI Agent / IDE | Shortcut Flag | Env Flag |
200
- | :--- | :--- | :--- |
201
- | [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
202
- | [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
203
- | [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
204
- | [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
205
- | [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
206
- | **Roo Code** | `--roo` | `--env roo` |
207
- | **Amp** | `--amp` | `--env amp` |
208
- | **Amazon Q Developer** | `--q` | `--env q` |
209
- | **Kilo Code** | `--kilocode` | `--env kilocode` |
210
- | **Qwen Code** | `--qwen` | `--env qwen` |
211
- | **OpenCode** | `--opencode` | `--env opencode` |
212
- | **SHAI (OVHcloud)** | `--shai` | `--env shai` |
213
- | **IBM Bob** | `--bob` | `--env bob` |
214
- | **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
215
- | **Qoder IDE** | `--qoder` | `--env qoder` |
216
- | **Codex CLI** | `--codex` | `--env codex` |
217
- | **Auggie CLI** | `--augment` | `--env augment` |
218
- | **Antigravity IDE** | `--antigravity` | `--env antigravity` |
219
- | **Lingma IDE** | `--lingma` | `--env lingma` |
220
-
221
- ## πŸ“š Documentation
222
-
223
- - [**Main Documentation**](./docs/README.md) β€” Detailed guide on workflows, architecture, and advanced features.
224
- - [**Installers Guide**](./installers/README.md) β€” Advanced CLI options and platform specifics.
225
- - [**Contributing**](./docs/contributing.md) β€” How to develop, test, and extend the engine.
226
-
227
- ## πŸ›Ÿ Support
228
-
229
- If you encounter issues or have questions:
230
-
231
- - Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
232
- - Run `magic.onboard` in your agent to restart the interactive tutorial.
233
-
234
- ## πŸ—ΊοΈ Roadmap
235
-
236
- - [x] Multi-agent adapter system.
237
- - [x] Phased implementation planning.
238
- - [ ] Extended support for local-first LLM agents.
239
- - [ ] Advanced visual dashboard for project health.
240
- - [ ] Integration with CI/CD for automated spec validation.
241
-
242
- ## πŸ—οΈ Contributing
243
-
244
- We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
245
- Please see [**Contributing Guide**](./docs/contributing.md) for details.
246
-
247
- ## πŸ‘₯ Authors and Acknowledgments
248
-
249
- - **Oleg Alexandrov** β€” Creator and Lead Maintainer.
250
- - Special thanks to the AI agent community for inspiration and testing.
251
-
252
- ## πŸ“„ License
253
-
254
- Distributed under the [MIT License](./LICENSE).
255
-
256
- ## πŸ“Š Project Status
257
-
258
- **Active Development** (v1.x). We are constantly refining the SDD engine based on real-world usage.
1
+ # πŸͺ„ Magic Spec
2
+
3
+ [![NPM version](https://img.shields.io/npm/v/magic-spec?color=green&label=npm)](https://www.npmjs.com/package/magic-spec)
4
+ [![PyPI version](https://img.shields.io/pypi/v/magic-spec?color=blue&label=pypi)](https://pypi.org/project/magic-spec/)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
6
+
7
+ ## πŸ“– Description
8
+
9
+ **The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
10
+
11
+ Stop your AI from writing fragile code before it fully understands the problem. `magic-spec` installs a high-performance, structured pipeline β€” *Thought β†’ Spec β†’ Task β†’ Run β†’ Code* β€” directly into any project, regardless of the tech stack.
12
+
13
+ Whether you are a **coding novice** building your first application or a **senior engineer** architecting enterprise systems, Magic Spec brings **maximum automation** and professional rigor to your development process. It enforces a deterministic workflow that ensures your AI agent perfectly aligns with your vision before writing a single line of code.
14
+
15
+ ### The Core Concept
16
+
17
+ `magic-spec` is a set of **markdown-based workflow instructions** specifically designed for AI coding agents like Cursor, Windsurf, Claude, and Gemini. It acts as a project-level operating system that orchestrates agentic development.
18
+
19
+ Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
20
+
21
+ ```plaintext
22
+ πŸ’‘ Idea β†’ πŸ“‹ Specification β†’ πŸ—ΊοΈ Task & Plan β†’ ⚑ Run β†’ πŸš€ Code
23
+ ```
24
+
25
+ Once initialized, your AI agent will automatically:
26
+
27
+ - Formulate a strong conceptual and technical specification.
28
+ - Build a phased implementation plan with hierarchical dependencies.
29
+ - Decompose the plan into prioritized, atomic, trackable tasks.
30
+ - Facilitate safe architectural brainstorming via **Explore Mode**.
31
+ - Analyze its own workflow and suggest improvements via Auto-Retrospectives.
32
+
33
+ ### What Gets Installed
34
+
35
+ After running the installer, your project directory will be augmented with the following structure:
36
+
37
+ ```plaintext
38
+ root-project/
39
+ β”œβ”€β”€ .agent/workflows/ # Slash commands wrapper (e.g., magic.spec, magic.task)
40
+ β”œβ”€β”€ .magic/ # The SDD Engine (workflow logic and scripts - read-only)
41
+ └── .design/ # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
42
+ ```
43
+
44
+ 1. **`.magic/`**: Deploys the core SDD engine.
45
+ 2. **`.agent/`**: Sets up workflows for your AI.
46
+ 3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
47
+ 4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
48
+
49
+ > [!TIP]
50
+ > **Magic Workspaces**: Magic Spec supports multiple, isolated design environments within a single repository (e.g., `.design/engine/`, `.design/installers/`). This allows you to manage fundamentally different project domains without specification overlap, while sharing a single core engine. See [workspaces.md](./workspaces.md) for details.
51
+
52
+ ## 🧠 The SDD Philosophy
53
+
54
+ > *"No code without a spec. No spec without a plan."*
55
+
56
+ Magic Spec is built around a single conviction: **AI agents write better code when they are forced to think before they act.** Left unconstrained, they jump straight to implementation β€” producing code that is fragile, misaligned, and expensive to refactor. Magic Spec installs a structured pipeline that makes this impossible.
57
+
58
+ ### Human-Minimal Engineering
59
+
60
+ The core design goal is to **keep humans out of the loop as much as possible** β€” without sacrificing control over what actually matters.
61
+
62
+ Once you describe what you want, the engine takes over:
63
+
64
+ - Specifications are drafted, reviewed, and promoted through their lifecycle automatically.
65
+ - Tasks are decomposed, prioritized, and assigned default values without prompting.
66
+ - Phases execute end-to-end: retrospective snapshots fire, changelogs are compiled, and context files are regenerated β€” all silently.
67
+ - The only moments requiring human input are deliberate gates: approving a spec before implementation begins, and signing off on an external release changelog.
68
+
69
+ Everything else is automated. The agent does the engineering. You approve the direction.
70
+
71
+ ### Two-Layer Specification Model
72
+
73
+ Every specification in Magic Spec belongs to one of two layers, and this separation is strictly enforced:
74
+
75
+ **Layer 1 β€” Concept** (`layer: concept`)
76
+ 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.
77
+
78
+ **Layer 2 β€” Implementation** (`layer: implementation`)
79
+ 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`.
80
+
81
+ 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.
82
+
83
+ > **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.
84
+
85
+ ### Integrity by Design
86
+
87
+ The engine actively protects specification integrity throughout the project lifecycle:
88
+
89
+ - **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.
90
+ - **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.
91
+ - **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.
92
+ - **Engine Integrity**: Core engine files are checksummed. Any untracked modification halts all workflows until the engine state is reconciled.
93
+
94
+ ### Self-Improving Feedback Loop
95
+
96
+ Magic Spec includes a built-in retrospective engine that runs automatically at two levels:
97
+
98
+ - **Level 1** fires after every phase completes: captures a lightweight snapshot of spec health, task metrics, and signal status.
99
+ - **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.
100
+
101
+ These retrospectives feed back into the specification layer, closing the loop between what was planned and what was actually built.
102
+
103
+ ## πŸ–ΌοΈ Visuals
104
+
105
+ 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.
106
+
107
+ ```mermaid
108
+ flowchart TB
109
+ IDEA(["πŸ’‘ Idea"])
110
+
111
+ subgraph BOX ["Magic Spec"]
112
+ direction TB
113
+
114
+ SPEC["πŸ“‹ Spec"]
115
+
116
+ subgraph TASK ["πŸ—ΊοΈ Task"]
117
+ direction TB
118
+ PLAN["πŸ“ Plan"]
119
+ TASKS["πŸ“Œ Tasks"]
120
+ PLAN --> TASKS
121
+ end
122
+
123
+ RUN["⚑ Run"]
124
+
125
+ SPEC --> PLAN
126
+ TASKS --> RUN
127
+ end
128
+
129
+ CODE(["πŸš€ Code"])
130
+
131
+ IDEA --> SPEC
132
+ RUN --> CODE
133
+
134
+ style IDEA fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
135
+ style CODE fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
136
+
137
+ style BOX fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
138
+
139
+ style SPEC fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
140
+ style RUN fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
141
+
142
+ style TASK fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
143
+ style PLAN fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
144
+ style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
145
+ ```
146
+
147
+ ## βš™οΈ Requirements
148
+
149
+ Before installing Magic Spec, ensure you have one of the following available on your system:
150
+
151
+ | Requirement | Details |
152
+ | :--- | :--- |
153
+ | **Node.js** | Version `16.x` or higher (for `npx` method) |
154
+ | **Python** | Version `3.8` or higher (for `uvx` or `pipx` methods) |
155
+ | **Git** | Required for installing edge versions directly from GitHub |
156
+ | **Terminal** | `tar` utility (pre-installed on Windows/Linux/macOS) |
157
+
158
+ ## πŸ“¦ Installation
159
+
160
+ Works perfectly with **any project** β€” Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
161
+
162
+ ### Option A: Node.js (`npx`)
163
+
164
+ **Stable Release:**
165
+
166
+ ```bash
167
+ # Basic installation (defaults to .agent/ folder)
168
+ npx magic-spec@latest
169
+
170
+ # Targeted installation for Cursor
171
+ npx magic-spec@latest --cursor
172
+ ```
173
+
174
+ **Edge Version (GitHub):**
175
+
176
+ ```bash
177
+ npx --yes github:teratron/magic-spec
178
+ ```
179
+
180
+ ### Option B: Python (`uvx`)
181
+
182
+ **Stable Release:**
183
+
184
+ ```bash
185
+ # Basic installation
186
+ uvx magic-spec
187
+
188
+ # Targeted installation for Windsurf
189
+ uvx magic-spec --windsurf
190
+ ```
191
+
192
+ **Edge Version (GitHub):**
193
+
194
+ ```bash
195
+ uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
196
+ ```
197
+
198
+ ### Option C: Python (`pipx`)
199
+
200
+ ```bash
201
+ pipx run magic-spec
202
+ ```
203
+
204
+ ### Option D: Multi-Adapter Installation
205
+
206
+ You can install support for multiple adapters at once:
207
+
208
+ ```bash
209
+ npx magic-spec@latest --cursor --copilot --windsurf
210
+ ```
211
+
212
+ ### Option E: Manual Installation
213
+
214
+ If automated installers do not fit your environment:
215
+
216
+ 1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
217
+ 2. **Workflows**: Download command wrappers from [`.agent/workflows/`](https://github.com/teratron/magic-spec/tree/main/.agent/workflows).
218
+ 3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
219
+
220
+ ## πŸ”„ Updating
221
+
222
+ Keep your SDD engine up to date with the latest logic and features:
223
+
224
+ ```bash
225
+ # Check if update is available
226
+ npx magic-spec@latest --check
227
+
228
+ # Perform the update
229
+ npx magic-spec@latest --update
230
+ ```
231
+
232
+ > [!TIP]
233
+ > The update process preserves your `.design/` workspace and automatically creates backups of `.magic/` and `.agent/` folders. If you have modified core engine files, the installer will detect conflicts and ask for your preference (overwrite, skip, or abort).
234
+
235
+ ## πŸ’¬ Usage
236
+
237
+ Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
238
+
239
+ - *"Dispatch this thought into specs..."* β†’ Triggers **Specification** workflow.
240
+ - *"Create an implementation plan"* β†’ Triggers **Task & Plan** workflow.
241
+ - *"Execute the next task"* β†’ Triggers **Run** workflow.
242
+ - *"Add a rule: always use Inter font"* β†’ Triggers **Rule** workflow.
243
+
244
+ ### 🀝 Compatibility
245
+
246
+ Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
247
+
248
+ You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
249
+
250
+ | AI Agent / IDE | Shortcut Flag | Env Flag |
251
+ | :--- | :--- | :--- |
252
+ | [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
253
+ | [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
254
+ | [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
255
+ | [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
256
+ | [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
257
+ | **Roo Code** | `--roo` | `--env roo` |
258
+ | **Amp** | `--amp` | `--env amp` |
259
+ | **Amazon Q Developer** | `--q` | `--env q` |
260
+ | **Kilo Code** | `--kilocode` | `--env kilocode` |
261
+ | **Qwen Code** | `--qwen` | `--env qwen` |
262
+ | **OpenCode** | `--opencode` | `--env opencode` |
263
+ | **SHAI (OVHcloud)** | `--shai` | `--env shai` |
264
+ | **IBM Bob** | `--bob` | `--env bob` |
265
+ | **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
266
+ | **Qoder IDE** | `--qoder` | `--env qoder` |
267
+ | **Codex CLI** | `--codex` | `--env codex` |
268
+ | **Auggie CLI** | `--augment` | `--env augment` |
269
+ | **Antigravity IDE** | `--antigravity` | `--env antigravity` |
270
+ | **Lingma IDE** | `--lingma` | `--env lingma` |
271
+
272
+ ## πŸ“š Documentation
273
+
274
+ - [**Main Documentation**](./docs/README.md) β€” Detailed guide on workflows, architecture, and advanced features.
275
+ - [**Installers Guide**](./installers/README.md) β€” Advanced CLI options and platform specifics.
276
+ - [**Contributing**](./docs/contributing.md) β€” How to develop, test, and extend the engine.
277
+
278
+ ## πŸ›Ÿ Support
279
+
280
+ If you encounter issues or have questions:
281
+
282
+ - Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
283
+ - Run `magic.onboard` in your agent to restart the interactive tutorial.
284
+
285
+ ## πŸ—ΊοΈ Roadmap
286
+
287
+ - [x] Multi-agent adapter system.
288
+ - [x] Phased implementation planning.
289
+ - [ ] Extended support for local-first LLM agents.
290
+ - [ ] Advanced visual dashboard for project health.
291
+ - [ ] Integration with CI/CD for automated spec validation.
292
+
293
+ ## πŸ—οΈ Contributing
294
+
295
+ We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
296
+ Please see [**Contributing Guide**](./docs/contributing.md) for details.
297
+
298
+ ## πŸ‘₯ Authors and Acknowledgments
299
+
300
+ - **Oleg Alexandrov** β€” Creator and Lead Maintainer.
301
+ - Special thanks to the AI agent community for inspiration and testing.
302
+
303
+ ## πŸ“„ License
304
+
305
+ Distributed under the [MIT License](./LICENSE).
306
+
307
+ ## πŸ“Š Project Status
308
+
309
+ **Active Development** (v1.x). We are constantly refining the SDD engine based on real-world usage.
package/installers/config.json CHANGED
@@ -25,13 +25,11 @@
25
25
  "task.md",
26
26
  ".version",
27
27
  ".checksums",
28
- "scripts/check-prerequisites.ps1",
29
- "scripts/check-prerequisites.sh",
28
+ "scripts/check-prerequisites.js",
30
29
  "scripts/executor.js",
31
- "scripts/generate-context.ps1",
32
- "scripts/generate-context.sh",
33
- "scripts/init.ps1",
34
- "scripts/init.sh",
30
+ "scripts/generate-checksums.js",
31
+ "scripts/generate-context.js",
32
+ "scripts/init.js",
35
33
  "templates/plan.md",
36
34
  "templates/retrospective.md",
37
35
  "templates/specification.md",
package/installers/node/index.js CHANGED
@@ -500,7 +500,7 @@ function getDirectoryChecksums(dir, baseDir = dir) {
500
500
  for (const item of items) {
501
501
  const fullPath = path.join(dir, item.name);
502
502
  if (item.isDirectory()) {
503
- if (item.name === '.checksums') continue;
503
+ if (item.name === '.checksums' || item.name === 'history') continue;
504
504
  Object.assign(results, getDirectoryChecksums(fullPath, baseDir));
505
505
  } else {
506
506
  if (item.name === '.checksums') continue;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "magic-spec",
3
- "version": "1.4.3",
3
+ "version": "1.4.77",
4
4
  "description": "Magic Specification-Driven Development (SDD) Workflow",
5
5
  "author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
6
6
  "license": "MIT",