magic-spec 1.2.3 → 1.3.2

package/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.3.2] - 2026-02-28
+
+### Added
+
+- **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.
+- **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.
+- **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.
+
+### Changed
+
+- 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.
+
+## [1.3.1] - 2026-02-27### Added
+
+- **Workflow Test Suite** (`.magic/tests/suite.md`): 16 predefined regression test scenarios covering all 8 engine workflows. Run via `/magic.simulate test`.
+- **Test Suite mode** in `simulate.md`: reads `suite.md` and reports PASS/FAIL for each scenario.
+- **Template directory** (`.magic/templates/`): extracted inline templates from core workflow files:
+  - `specification.md` — Specification Template (from `spec.md`)
+  - `plan.md` — PLAN.md Template (from `task.md`)
+  - `tasks.md` — TASKS.md + phase-{n}.md Templates (from `task.md`)
+  - `retrospective.md` — RETROSPECTIVE.md Template (from `retrospective.md`)
+
+### Changed
+
+- **AOP Optimization**: Compressed verbose prose in `spec.md` (Post-Update Review, Audit/Consistency Reports). ~17% token reduction across core workflows.
+- **Stress-test hardening** across all workflows:
+  - `spec.md`: Intra-input self-contradiction guard, Deprecation Cascade (scan Related Specs for stale refs)
+  - `task.md`: Circular Dependency Guard, Phantom Done-task preservation (Archive not Cancel), Deprecated Done-task preservation, Convention Sync wording fix
+  - `run.md`: Mode Guard — HALT if execution mode not in RULES.md §7
+  - `rule.md`: Duplication Guard, convention-not-found handler, Workflow Dependency Check in Remove Impact Analysis
+  - `simulate.md`: Checksums mismatch upgraded to HALT, Checksum Rule (generate after approval only)
+  - `onboard.md`: Production collision HALT with backup/cancel, re-entry checks production PLAN.md
+  - `init.md`: Expanded post-init verification to all 5 artifacts, Maintainer Note for hardcoded RULES.md sync
+
+### Fixed
+
+- Template references now explicitly point to `.magic/templates/*.md` in creation steps of `spec.md`, `task.md`, `retrospective.md`, and `onboard.md`.
+
+## [1.3.0] - 2026-02-25
+
+### Added
+
+- **Full support for abstract environment templates** with automatic resolution (`{ARGUMENTS}`) across all CLIs.
+- **Introduced `.magicrc`** for persistence of selected environments and their auto-detection.
+- **Two-level automatic Changelog generation** (by accumulating `Changes` blocks within tasks).
+- **Added new CLI commands:** `info`, `--check`, `--list-envs`, and `--eject`.
+- **Introduced core version tracking** within the project via the `.magic/.version` file.
+
+### Changed
+
+- **Architecture:** Restructured the repository into a two-level model (root = source of truth + installers), and removed the `core/` folder to eliminate duplication.
+- **Node Installer:** Completely overhauled the installation mechanism (it now uses compiled files from NPM instead of downloading them from GitHub, eliminating Path Traversal vulnerabilities).
+- **Python Installer:** Implemented an isolated package based on `hatchling` (via shared-data) without external dependencies on GitHub.
+- **Documentation:** Separated `README.md` strategies (different focuses for GitHub, NPM package, and PyPI package).
+- **Update Logic:** Improved `.magic` update logic to be safer (old folders are now moved to `.magic/archives/` rather than simply deleted).
+
+## [1.3.0] - 2026-02-23
+
+### Added
+
+- **Handoff integrations** (`magic.*.md`): Introduced explicit handoff blocks across all agent workflow wrappers to guide next-steps effortlessly.
+- **Task Engine Enhancement:** Integrated User Stories generation parsing into `.magic/task.md` and suppressed user priority prompts using `RULES.md C4`.
+- **System Automation Hooks:** Added `generate-context` script hooks into `task.md` and `run.md` post-write triggers.
+- **Context Automation Script:** Created `generate-context.sh` and `generate-context.ps1` to assemble `CONTEXT.md` from PLAN, workspace trees, and changelogs.
+- **Spec Engine Protections:** Added strict Explore Mode Safety rules and Delta Editing constraints for spec updates over 200 lines to `.magic/spec.md`.
+- **Explore Hints:** Updated `.agent/workflows/magic.spec.md` UI wrapper with tips to use Delta Constraints and strict read-only explore mode.
+- **CLI Doctor Command (Node/Python):** Implemented `--doctor` and `--check` parsing in installers, executing the prerequisite script and outputting a formatted terminal validation report.
+- **Interactive Onboarding Script:** Created `.magic/onboard.md` to guide new developers through building a toy "console logger" specification.
+- **Onboarding Wrapper:** Added `.agent/workflows/magic.onboard.md` to trigger the interactive onboarding tutorial seamlessly.
+- **Prerequisite Validation:** Created `check-prerequisites.sh` and `check-prerequisites.ps1` parsing `INDEX.md` and returning valid JSON results.

package/README.md

@@ -1,112 +1,54 @@
 # 🪄 Magic Spec
 
-[![NPM version](https://img.shields.io/npm/v/magic-spec)](https://www.npmjs.com/package/magic-spec)
-[![PyPI version](https://img.shields.io/pypi/v/magic-spec)](https://pypi.org/project/magic-spec/)
+[![NPM version](https://img.shields.io/npm/v/magic-spec?color=green&label=npm)](https://www.npmjs.com/package/magic-spec)
+[![PyPI version](https://img.shields.io/pypi/v/magic-spec?color=blue&label=pypi)](https://pypi.org/project/magic-spec/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
-**Specification-Driven Development (SDD) workflow for AI coding agents.**
+## 📖 Description
 
-Stop your AI from writing code before it understands the problem.  
-`magic-spec` installs a structured pipeline — *Thought → Spec → Task → Run → Code* — directly into any project, regardless of stack.
+**The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
 
-## ✨ What is Magic Spec?
+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.
 
-`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:
+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.
 
-```
-💡 Idea  →  📋 Specification  →  🗺️ Task & Plan  →  ⚡ Run  →  🚀 Code
-```
-
-Once installed, your AI agent will automatically:
-
-- Convert raw thoughts into structured specification files.
-- Build a phased implementation plan from approved specs.
-- Decompose the plan into atomic, trackable tasks.
-- Analyze its own workflow and suggest improvements — automatically, at phase completion.
-
-**No code is written until a specification exists. No spec is implemented without a plan.**
-
-## 🚀 Quick Start
+### The Core Concept
 
-Works with **any project** — Rust, Go, Python, JavaScript, or anything else.  
-No runtime lock-in. Requires only Node.js *or* Python to install.
+`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.
 
-### Option A — Node.js (npx)
+Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
 
-```bash
-npx magic-spec@latest
-```
-
-### Option B — Python (uvx)
-
-```bash
-uvx magic-spec
+```plaintext
+💡 Idea  →  📋 Specification  →  🗺️ Task & Plan  →  ⚡ Run  →  🚀 Code
 ```
 
-Both commands do exactly the same thing:
+Once initialized, your AI agent will automatically:
 
-1. Copy `.magic/` (the SDD engine) into your project.
-2. Copy `.agent/workflows/magic.*.md` (agent trigger wrappers) into your project.
-3. Run the init script — creates your `.design/` workspace with `INDEX.md` and `RULES.md`.
+- Formulate a strong conceptual and technical specification.
+- Build a phased implementation plan with hierarchical dependencies.
+- Decompose the plan into prioritized, atomic, trackable tasks.
+- Facilitate safe architectural brainstorming via **Explore Mode**.
+- Analyze its own workflow and suggest improvements via Auto-Retrospectives.
 
-## 🧭 Core Philosophy
-
-| Principle | Description |
-| :--- | :--- |
-| **Specs First, Code Later** | The agent is forbidden from writing code from raw input. All ideas become specs first. |
-| **Deterministic Process** | A strict pipeline is enforced: *Thought → Spec → Task → Run → Code*. |
-| **Constitution-Driven** | All project decisions live in `.design/RULES.md` — the project's living constitution. |
-| **Self-Improving** | After each phase and at plan completion, the Task workflow automatically runs a retrospective and generates improvement recommendations. |
+### What Gets Installed
 
-## 🩺 System Health (CLI Doctor)
+After running the installer, your project directory will be augmented with the following structure:
 
-You can check if your SDD workspace is properly initialized and healthy without invoking the AI. Just append the `--doctor` (or `--check`) flag:
-
-```bash
-npx magic-spec@latest --doctor
-# or
-uvx magic-spec --doctor
+```plaintext
+root-project/
+├── .agent/workflows/         # Slash commands wrapper (e.g., magic.spec, magic.task)
+├── .magic/                   # The SDD Engine (workflow logic and scripts - read-only)
+└── .design/                  # Your Project Design Workspace (INDEX.md, RULES.md, PLAN.md)
 ```
 
-This returns a visually formatted validation report of your project's `.design` structure, preventing broken context before you start coding.
+1. **`.magic/`**: Deploys the core SDD engine.
+2. **`.agent/`**: Sets up workflows for your AI.
+3. **`.design/`**: Initializes your project's workspace for Specifications, Rules, and Plans.
+4. **Onboarding**: An interactive tutorial (`magic.onboard`) helps you and your AI get started smoothly.
 
-## 📁 What Gets Installed
+## 🖼️ Visuals
 
-After running `npx magic-spec@latest` in your project root:
-
-```plaintext
-your-project/
-│
-├── .agent/workflows/               # Agent entry points (slash commands)
-│   ├── magic.onboard.md        # Interactive tutorial for new devs
-│   ├── magic.rule.md
-│   ├── magic.run.md
-│   ├── magic.spec.md
-│   └── magic.task.md
-│
-├── .magic/                     # SDD Engine (workflow logic, read-only)
-│   ├── init.md
-│   ├── onboard.md              # Onboarding script payload
-│   ├── retrospective.md
-│   ├── rule.md
-│   ├── run.md
-│   ├── spec.md
-│   ├── task.md
-│   └── scripts/
-│       ├── check-prerequisites.*  # Used by --doctor
-│       ├── generate-context.*     # Auto-compiles CONTEXT.md
-│       ├── init.sh             # Init for macOS / Linux
-│       └── init.ps1            # Init for Windows
-│
-└── .design/                    # Your project workspace (generated)
-    ├── INDEX.md                # Spec registry
-    ├── RULES.md                # Project constitution
-    ├── PLAN.md                 # Implementation plan
-    ├── specifications/         # Your specification files
-    └── tasks/                  # Task breakdowns per phase
-```
-
-## 🔗 The Workflow Pipeline
+The engine operates on a smart, self-correcting feedback loop:
 
 ```mermaid
 graph TD
@@ -121,76 +63,133 @@ graph TD
     RETRO -.->|Feedback loop| SPEC
 ```
 
-### Core Workflows
+## ⚙️ Requirements
 
-| # | Workflow | Purpose |
-| :--- | :--- | :--- |
-| 1 | **Specification** | Converts raw thoughts into structured specs. Verifies specs against project state. Manages statuses: `Draft → RFC → Stable → Deprecated`. |
-| 2 | **Task** | Reads Stable specs, builds a dependency graph, produces a phased `PLAN.md`, and decomposes into atomic tasks. |
-| 3 | **Run** | Executes tasks with sequential and parallel tracks. Automatically runs a retrospective at phase and plan completion. |
+Before installing Magic Spec, ensure you have one of the following available on your system:
 
-### Auxiliary Workflows
-
-| Workflow | Purpose |
+| Requirement | Details |
 | :--- | :--- |
-| **Rule** | Manages the project constitution (`RULES.md §7`). Add, amend, or remove conventions. |
-| **Onboard** | Interactive tutorial guiding new developers through their first Magic SDD cycle. |
+| **Node.js** | Version `16.x` or higher (for `npx` method) |
+| **Python** | Version `3.8` or higher (for `uvx` or `pipx` methods) |
+| **Git** | Required for installing edge versions directly from GitHub |
+| **Terminal** | `tar` utility (pre-installed on Windows/Linux/macOS) |
 
-> **Retrospective** runs automatically inside the Run workflow — at phase completion (snapshot) and plan completion (full analysis). No manual command needed.
+## 📦 Installation
 
-## 💬 How to Use (with any AI agent)
+Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
 
-Just talk to your AI agent naturally. Initialization is **automatic** — no setup command required.
+### Option A: Node.js (`npx`)
 
-```plaintext
-"Dispatch this thought into specs: I want a user auth system with JWT and Redis..."
-→ Runs Specification workflow
+**Stable Release:**
 
-"Create an implementation plan"
-→ Runs Task workflow
+```bash
+npx magic-spec@latest
+```
 
-"Generate tasks for Phase 1"
-→ Runs Task workflow
+**Edge Version (GitHub):**
 
-"Execute the next task"
-→ Runs Run workflow
+```bash
+npx --yes github:teratron/magic-spec
+```
 
-"Add rule: always use snake_case for file names"
-→ Runs Rule workflow
+### Option B: Python (`uvx`)
 
-"Check if specs match the actual project state"
-→ Runs Specification workflow (Consistency Check)
+**Stable Release:**
 
-"Start the interactive tutorial"
-→ Runs Onboard workflow
+```bash
+uvx magic-spec
 ```
 
-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.** ✨
+**Edge Version (GitHub):**
 
-## 🔄 Updating
+```bash
+uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
+```
 
-Pull the latest engine improvements without touching your project data:
+### Option C: Python (`pipx`)
 
 ```bash
-# Node.js
-npx magic-spec@latest --update
-
-# Python
-uvx magic-spec --update
+pipx run magic-spec
 ```
 
-The update overwrites `.magic/` (the engine) but **never touches** `.design/` (your specs, plans, and tasks).
+### Option D: Manual Installation
+
+If automated installers do not fit your environment:
+
+1. **Engine**: Download the `.magic/` folder from the [GitHub repository](https://github.com/teratron/magic-spec).
+2. **Workflows**: Download command wrappers from [`.agent/workflows/`](https://github.com/teratron/magic-spec/tree/main/.agent/workflows).
+3. **Deploy**: Place files into your AI agent's instruction directory (e.g., `.cursor/commands`).
+
+## 🚀 Usage
+
+Just talk to your AI agent naturally in your prompt interface. No complex commands to learn:
+
+- *"Dispatch this thought into specs..."* → Triggers **Specification** workflow.
+- *"Create an implementation plan"* → Triggers **Task & Plan** workflow.
+- *"Execute the next task"* → Triggers **Run** workflow.
+- *"Add a rule: always use Inter font"* → Triggers **Rule** workflow.
 
-## 🤝 Compatibility
+### 🤝 Compatibility
 
-Works with any AI coding agent that can read markdown workflow files:
+Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments:
 
-- [Cursor](https://cursor.sh) (`.cursorrules` + Agent mode)
-- [Claude](https://claude.ai) (Projects)
-- [Gemini](https://gemini.google.com) (via Gemini Code)
-- [GitHub Copilot](https://github.com/features/copilot) (Agent mode)
-- Any terminal-based or API-driven agent
+| AI Agent / IDE | Installation Flag |
+| :--- | :--- |
+| [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` |
+| [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` |
+| [**Claude Code**](https://claude.ai/code) | `--claude` |
+| [**Gemini CLI**](https://gemini.google.com) | `--gemini` |
+| [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` |
+| **Roo Code** | `--roo` |
+| **Amp** | `--amp` |
+| **Amazon Q Developer** | `--q` |
+| **Kilo Code** | `--kilocode` |
+| **Qwen Code** | `--qwen` |
+| **OpenCode** | `--opencode` |
+| **SHAI (OVHcloud)** | `--shai` |
+| **IBM Bob** | `--bob` |
+| **CodeBuddy** | `--codebuddy` |
+| **Qoder IDE** | `--qoder` |
+| **Codex CLI** | `--codex` |
+| **Auggie CLI** | `--augment` |
+| **Antigravity IDE** | `--antigravity` |
+| **Lingma IDE** | `--lingma` |
+
+## 📚 Documentation
+
+- [**Main Documentation**](./docs/README.md) — Detailed guide on workflows, architecture, and advanced features.
+- [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
+- [**Contributing**](./docs/contributing.md) — How to develop, test, and extend the engine.
+
+## 🛟 Support
+
+If you encounter issues or have questions:
+
+- Open an [Issue](https://github.com/teratron/magic-spec/issues) on GitHub.
+- Run `magic.onboard` in your agent to restart the interactive tutorial.
+
+## 🗺️ Roadmap
+
+- [x] Multi-agent adapter system.
+- [x] Phased implementation planning.
+- [ ] Extended support for local-first LLM agents.
+- [ ] Advanced visual dashboard for project health.
+- [ ] Integration with CI/CD for automated spec validation.
+
+## 🤝 Contributing
+
+We welcome contributions! Whether it's a bug fix, a new adapter, or an improvement to the workflow logic.
+Please see [**Contributing Guide**](./docs/contributing.md) for details.
+
+## 👥 Authors and Acknowledgments
+
+- **Oleg Alexandrov** — Creator and Lead Maintainer.
+- Special thanks to the AI agent community for inspiration and testing.
 
 ## 📄 License
 
-[MIT](./LICENSE) © 2026 Oleg Alexandrov
+Distributed under the [MIT License](./LICENSE).
+
+## 📊 Project Status
+
+**Active Development** (v1.x). We are constantly refining the SDD engine based on real-world usage.

package/installers/config.json

@@ -0,0 +1,69 @@
+{
+    "githubRepo": "teratron/magic-spec",
+    "packageName": "magic-spec",
+    "removePrefix": "magic.",
+    "engineDir": ".magic",
+    "agentDir": ".agent",
+    "workflowsDir": "workflows",
+    "defaultExt": ".md",
+    "workflows": [
+        "magic.onboard",
+        "magic.rule",
+        "magic.run",
+        "magic.simulate",
+        "magic.spec",
+        "magic.task"
+    ],
+    "magicFiles": [
+        "analyze.md",
+        "onboard.md",
+        "retrospective.md",
+        "rule.md",
+        "run.md",
+        "simulate.md",
+        "spec.md",
+        "task.md",
+        ".version",
+        ".checksums",
+        "scripts/check-prerequisites.ps1",
+        "scripts/check-prerequisites.sh",
+        "scripts/executor.js",
+        "scripts/generate-context.ps1",
+        "scripts/generate-context.sh",
+        "scripts/init.ps1",
+        "scripts/init.sh",
+        "templates/plan.md",
+        "templates/retrospective.md",
+        "templates/specification.md",
+        "templates/tasks.md"
+    ],
+    "download": {
+        "timeoutMs": 60000,
+        "tempPrefix": "magic-spec-"
+    },
+    "userAgent": {
+        "node": "magic-spec-node",
+        "python": "magic-spec-cli"
+    },
+    "eject": {
+        "targets": [
+            ".magic",
+            ".agent",
+            ".magic.bak",
+            ".agent.bak"
+        ]
+    },
+    "publish": {
+        "versionFiles": [
+            "pyproject.toml",
+            "installers/python/magic_spec/__init__.py",
+            "package.json",
+            ".magic/.version"
+        ],
+        "docsTargets": [
+            "README.md",
+            "CHANGELOG.md"
+        ],
+        "docsDir": "docs"
+    }
+}