magic-spec 1.2.3 β†’ 1.3.0

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 +39 -0
  2. package/README.md +40 -158
  3. package/installers/config.json +38 -0
  4. package/installers/node/index.js +839 -275
  5. package/package.json +8 -9
package/CHANGELOG.md ADDED
@@ -0,0 +1,39 @@
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.3.0] - 2026-02-25
9
+
10
+ ### Added
11
+
12
+ - **Full support for abstract environment templates** with automatic resolution (`{ARGUMENTS}`) across all CLIs.
13
+ - **Introduced `.magicrc`** for persistence of selected environments and their auto-detection.
14
+ - **Two-level automatic Changelog generation** (by accumulating `Changes` blocks within tasks).
15
+ - **Added new CLI commands:** `info`, `--check`, `--list-envs`, and `--eject`.
16
+ - **Introduced core version tracking** within the project via the `.magic/.version` file.
17
+
18
+ ### Changed
19
+
20
+ - **Architecture:** Restructured the repository into a two-level model (root = source of truth + installers), and removed the `core/` folder to eliminate duplication.
21
+ - **Node Installer:** Completely overhauled the installation mechanism (it now uses compiled files from NPM instead of downloading them from GitHub, eliminating Path Traversal vulnerabilities).
22
+ - **Python Installer:** Implemented an isolated package based on `hatchling` (via shared-data) without external dependencies on GitHub.
23
+ - **Documentation:** Separated `README.md` strategies (different focuses for GitHub, NPM package, and PyPI package).
24
+ - **Update Logic:** Improved `.magic` update logic to be safer (old folders are now moved to `.magic/archives/` rather than simply deleted).
25
+
26
+ ## [1.3.0] - 2026-02-23
27
+
28
+ ### Added
29
+
30
+ - **Handoff integrations** (`magic.*.md`): Introduced explicit handoff blocks across all agent workflow wrappers to guide next-steps effortlessly.
31
+ - **Task Engine Enhancement:** Integrated User Stories generation parsing into `.magic/task.md` and suppressed user priority prompts using `RULES.md C4`.
32
+ - **System Automation Hooks:** Added `generate-context` script hooks into `task.md` and `run.md` post-write triggers.
33
+ - **Context Automation Script:** Created `generate-context.sh` and `generate-context.ps1` to assemble `CONTEXT.md` from PLAN, workspace trees, and changelogs.
34
+ - **Spec Engine Protections:** Added strict Explore Mode Safety rules and Delta Editing constraints for spec updates over 200 lines to `.magic/spec.md`.
35
+ - **Explore Hints:** Updated `.agent/workflows/magic.spec.md` UI wrapper with tips to use Delta Constraints and strict read-only explore mode.
36
+ - **CLI Doctor Command (Node/Python):** Implemented `--doctor` and `--check` parsing in installers, executing the prerequisite script and outputting a formatted terminal validation report.
37
+ - **Interactive Onboarding Script:** Created `.magic/onboard.md` to guide new developers through building a toy "console logger" specification.
38
+ - **Onboarding Wrapper:** Added `.agent/workflows/magic.onboard.md` to trigger the interactive onboarding tutorial seamlessly.
39
+ - **Prerequisite Validation:** Created `check-prerequisites.sh` and `check-prerequisites.ps1` parsing `INDEX.md` and returning valid JSON results.
package/README.md CHANGED
@@ -1,196 +1,78 @@
1
1
  # πŸͺ„ Magic Spec
2
2
 
3
- [![NPM version](https://img.shields.io/npm/v/magic-spec)](https://www.npmjs.com/package/magic-spec)
4
- [![PyPI version](https://img.shields.io/pypi/v/magic-spec)](https://pypi.org/project/magic-spec/)
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
5
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
6
6
 
7
- **Specification-Driven Development (SDD) workflow for AI coding agents.**
7
+ **The Specification-Driven Development (SDD) Operating System for AI Agents.**
8
8
 
9
- Stop your AI from writing code before it understands the problem.
10
- `magic-spec` installs a structured pipeline β€” *Thought β†’ Spec β†’ Task β†’ Run β†’ Code* β€” directly into any project, regardless of stack.
9
+ Stop your AI from writing code before it understands the problem. `magic-spec` installs a high-performance, structured pipeline β€” *Thought β†’ Spec β†’ Task β†’ Run β†’ Code* β€” directly into any project.
11
10
 
12
- ## ✨ What is Magic Spec?
11
+ ---
13
12
 
14
- `magic-spec` is a set of **markdown-based workflow instructions** for AI coding agents (Cursor, Claude, Gemini, Copilot, etc.). It acts as an operating system for agentic development, enforcing a rigorous, structured pipeline:
13
+ ## ✨ Features
15
14
 
16
- ```
17
- πŸ’‘ Idea β†’ πŸ“‹ Specification β†’ πŸ—ΊοΈ Task & Plan β†’ ⚑ Run β†’ πŸš€ Code
18
- ```
19
-
20
- Once installed, your AI agent will automatically:
21
-
22
- - Convert raw thoughts into structured specification files.
23
- - Build a phased implementation plan from approved specs.
24
- - Decompose the plan into atomic, trackable tasks.
25
- - Analyze its own workflow and suggest improvements β€” automatically, at phase completion.
15
+ - πŸ—οΈ **Deterministic Pipeline**: Forced structure ensures architectural integrity.
16
+ - 🎯 **Multi-Agent Core**: Works with Cursor, Windsurf, Claude, Gemini, and more.
17
+ - πŸ” **Auto-Retrospective**: Built-in self-analysis engine that improves your workflow automatically.
18
+ - πŸ“¦ **Thin-Client Installers**: Lightweight Node.js and Python installers for zero-friction setup.
19
+ - πŸ—ΊοΈ **Phased Planning**: Intelligent dependency tracking and implementation roadmaps.
26
20
 
27
- **No code is written until a specification exists. No spec is implemented without a plan.**
21
+ ---
28
22
 
29
23
  ## πŸš€ Quick Start
30
24
 
31
- Works with **any project** β€” Rust, Go, Python, JavaScript, or anything else.
32
- No runtime lock-in. Requires only Node.js *or* Python to install.
25
+ Works with **any project** β€” Rust, Go, Python, JavaScript, C++, or anything else.
33
26
 
34
- ### Option A β€” Node.js (npx)
27
+ ### Option A: Node.js (npx)
35
28
 
36
29
  ```bash
37
30
  npx magic-spec@latest
38
31
  ```
39
32
 
40
- ### Option B β€” Python (uvx)
33
+ ### Option B: Python (uvx)
41
34
 
42
35
  ```bash
43
36
  uvx magic-spec
44
37
  ```
45
38
 
46
- Both commands do exactly the same thing:
47
-
48
- 1. Copy `.magic/` (the SDD engine) into your project.
49
- 2. Copy `.agent/workflows/magic.*.md` (agent trigger wrappers) into your project.
50
- 3. Run the init script β€” creates your `.design/` workspace with `INDEX.md` and `RULES.md`.
51
-
52
- ## 🧭 Core Philosophy
53
-
54
- | Principle | Description |
55
- | :--- | :--- |
56
- | **Specs First, Code Later** | The agent is forbidden from writing code from raw input. All ideas become specs first. |
57
- | **Deterministic Process** | A strict pipeline is enforced: *Thought β†’ Spec β†’ Task β†’ Run β†’ Code*. |
58
- | **Constitution-Driven** | All project decisions live in `.design/RULES.md` β€” the project's living constitution. |
59
- | **Self-Improving** | After each phase and at plan completion, the Task workflow automatically runs a retrospective and generates improvement recommendations. |
60
-
61
- ## 🩺 System Health (CLI Doctor)
62
-
63
- You can check if your SDD workspace is properly initialized and healthy without invoking the AI. Just append the `--doctor` (or `--check`) flag:
64
-
65
- ```bash
66
- npx magic-spec@latest --doctor
67
- # or
68
- uvx magic-spec --doctor
69
- ```
70
-
71
- This returns a visually formatted validation report of your project's `.design` structure, preventing broken context before you start coding.
72
-
73
- ## πŸ“ What Gets Installed
74
-
75
- After running `npx magic-spec@latest` in your project root:
76
-
77
- ```plaintext
78
- your-project/
79
- β”‚
80
- β”œβ”€β”€ .agent/workflows/ # Agent entry points (slash commands)
81
- β”‚ β”œβ”€β”€ magic.onboard.md # Interactive tutorial for new devs
82
- β”‚ β”œβ”€β”€ magic.rule.md
83
- β”‚ β”œβ”€β”€ magic.run.md
84
- β”‚ β”œβ”€β”€ magic.spec.md
85
- β”‚ └── magic.task.md
86
- β”‚
87
- β”œβ”€β”€ .magic/ # SDD Engine (workflow logic, read-only)
88
- β”‚ β”œβ”€β”€ init.md
89
- β”‚ β”œβ”€β”€ onboard.md # Onboarding script payload
90
- β”‚ β”œβ”€β”€ retrospective.md
91
- β”‚ β”œβ”€β”€ rule.md
92
- β”‚ β”œβ”€β”€ run.md
93
- β”‚ β”œβ”€β”€ spec.md
94
- β”‚ β”œβ”€β”€ task.md
95
- β”‚ └── scripts/
96
- β”‚ β”œβ”€β”€ check-prerequisites.* # Used by --doctor
97
- β”‚ β”œβ”€β”€ generate-context.* # Auto-compiles CONTEXT.md
98
- β”‚ β”œβ”€β”€ init.sh # Init for macOS / Linux
99
- β”‚ └── init.ps1 # Init for Windows
100
- β”‚
101
- └── .design/ # Your project workspace (generated)
102
- β”œβ”€β”€ INDEX.md # Spec registry
103
- β”œβ”€β”€ RULES.md # Project constitution
104
- β”œβ”€β”€ PLAN.md # Implementation plan
105
- β”œβ”€β”€ specifications/ # Your specification files
106
- └── tasks/ # Task breakdowns per phase
107
- ```
108
-
109
- ## πŸ”— The Workflow Pipeline
110
-
111
- ```mermaid
112
- graph TD
113
- IDEA["πŸ’‘ Idea"] --> INIT{"πŸ—οΈ Auto-Init"}
114
- INIT -->|.design/ exists| SPEC
115
- INIT -->|.design/ missing| CREATE["Create .design/ structure"] --> SPEC
116
- SPEC["πŸ“‹ Specification"] <--> RULE["πŸ“œ Rule"]
117
- SPEC --> TASK["πŸ—ΊοΈ Task & Plan"]
118
- TASK --> RUN["⚑ Run"]
119
- RUN --> CODE["πŸš€ Code"]
120
- RUN -.->|"auto: phase done"| RETRO["πŸ” Retrospective"]
121
- RETRO -.->|Feedback loop| SPEC
122
- ```
123
-
124
- ### Core Workflows
125
-
126
- | # | Workflow | Purpose |
127
- | :--- | :--- | :--- |
128
- | 1 | **Specification** | Converts raw thoughts into structured specs. Verifies specs against project state. Manages statuses: `Draft β†’ RFC β†’ Stable β†’ Deprecated`. |
129
- | 2 | **Task** | Reads Stable specs, builds a dependency graph, produces a phased `PLAN.md`, and decomposes into atomic tasks. |
130
- | 3 | **Run** | Executes tasks with sequential and parallel tracks. Automatically runs a retrospective at phase and plan completion. |
131
-
132
- ### Auxiliary Workflows
133
-
134
- | Workflow | Purpose |
135
- | :--- | :--- |
136
- | **Rule** | Manages the project constitution (`RULES.md Β§7`). Add, amend, or remove conventions. |
137
- | **Onboard** | Interactive tutorial guiding new developers through their first Magic SDD cycle. |
138
-
139
- > **Retrospective** runs automatically inside the Run workflow β€” at phase completion (snapshot) and plan completion (full analysis). No manual command needed.
140
-
141
- ## πŸ’¬ How to Use (with any AI agent)
142
-
143
- Just talk to your AI agent naturally. Initialization is **automatic** β€” no setup command required.
144
-
145
- ```plaintext
146
- "Dispatch this thought into specs: I want a user auth system with JWT and Redis..."
147
- β†’ Runs Specification workflow
39
+ **What happens next?**
148
40
 
149
- "Create an implementation plan"
150
- β†’ Runs Task workflow
41
+ 1. Magic Spec deploys the `.magic/` engine and `.agent/` workflows.
42
+ 2. An interactive onboarding tutorial (`magic.onboard`) helps you and your AI get started.
43
+ 3. Your project gains a dedicated `.design/` workspace for Specifications, Rules, and Plans.
151
44
 
152
- "Generate tasks for Phase 1"
153
- β†’ Runs Task workflow
45
+ ---
154
46
 
155
- "Execute the next task"
156
- β†’ Runs Run workflow
47
+ ## 🧭 The Workflow
157
48
 
158
- "Add rule: always use snake_case for file names"
159
- β†’ Runs Rule workflow
49
+ 1. **Specification**: Convert raw ideas into formal, versioned specs.
50
+ 2. **Task & Plan**: Generate a phased roadmap with atomic, trackable tasks.
51
+ 3. **Run**: Execute the plan with automatic progress tracking and quality gates.
52
+ 4. **Rule**: Manage project conventions in a central `RULES.md` constitution.
160
53
 
161
- "Check if specs match the actual project state"
162
- β†’ Runs Specification workflow (Consistency Check)
54
+ ---
163
55
 
164
- "Start the interactive tutorial"
165
- β†’ Runs Onboard workflow
166
- ```
167
-
168
- The AI reads the corresponding `.magic/*.md` workflow file and executes the request within the bounds of the SDD system. **No code escapes the pipeline.** ✨
169
-
170
- ## πŸ”„ Updating
171
-
172
- Pull the latest engine improvements without touching your project data:
56
+ ## πŸ“– Documentation & Guides
173
57
 
174
- ```bash
175
- # Node.js
176
- npx magic-spec@latest --update
177
-
178
- # Python
179
- uvx magic-spec --update
180
- ```
58
+ - [**Main Documentation**](./docs/README.md) β€” Detailed guide on workflows and architecture.
59
+ - [**Installers Guide**](./installers/README.md) β€” Advanced CLI options and platform specifics.
60
+ - [**Contributing**](./docs/contributing.md) β€” How to develop and extend the engine.
181
61
 
182
- The update overwrites `.magic/` (the engine) but **never touches** `.design/` (your specs, plans, and tasks).
62
+ ---
183
63
 
184
64
  ## 🀝 Compatibility
185
65
 
186
- Works with any AI coding agent that can read markdown workflow files:
66
+ Magic Spec is optimized for the world's most powerful AI development environments:
67
+
68
+ - [**Cursor**](https://cursor.com) (Rule definitions & Agent Mode)
69
+ - [**Windsurf**](https://codeium.com/windsurf) (Cascade & Flows)
70
+ - [**GitHub Copilot**](https://github.com/features/copilot) (Custom Instructions)
71
+ - [**Claude**](https://claude.ai) (Project context)
187
72
 
188
- - [Cursor](https://cursor.sh) (`.cursorrules` + Agent mode)
189
- - [Claude](https://claude.ai) (Projects)
190
- - [Gemini](https://gemini.google.com) (via Gemini Code)
191
- - [GitHub Copilot](https://github.com/features/copilot) (Agent mode)
192
- - Any terminal-based or API-driven agent
73
+ ---
193
74
 
194
75
  ## πŸ“„ License
195
76
 
196
- [MIT](./LICENSE) Β© 2026 Oleg Alexandrov
77
+ Distributed under the [MIT License](./LICENSE).
78
+ © 2026 Oleg Alexandrov & teratron. ✨
package/installers/config.json ADDED
@@ -0,0 +1,38 @@
1
+ {
2
+ "githubRepo": "teratron/magic-spec",
3
+ "packageName": "magic-spec",
4
+ "removePrefix": "magic.",
5
+ "engineDir": ".magic",
6
+ "agentDir": ".agent",
7
+ "workflowsDir": "workflows",
8
+ "defaultExt": ".md",
9
+ "download": {
10
+ "timeoutMs": 60000,
11
+ "tempPrefix": "magic-spec-"
12
+ },
13
+ "userAgent": {
14
+ "node": "magic-spec-node",
15
+ "python": "magic-spec-cli"
16
+ },
17
+ "eject": {
18
+ "targets": [
19
+ ".magic",
20
+ ".agent",
21
+ ".magic.bak",
22
+ ".agent.bak"
23
+ ]
24
+ },
25
+ "publish": {
26
+ "versionFiles": [
27
+ "pyproject.toml",
28
+ "installers/python/magic_spec/__init__.py",
29
+ "package.json",
30
+ ".magic/.version"
31
+ ],
32
+ "docsTargets": [
33
+ "README.md",
34
+ "CHANGELOG.md"
35
+ ],
36
+ "docsDir": "docs"
37
+ }
38
+ }