magic-spec 1.4.15 → 1.4.162

package/CHANGELOG.md

@@ -5,7 +5,41 @@ 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.4.15] - 2026-03-02
+## [1.4.162] - 2026-03-12
+
+### Added
+
+- **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.
+- **Multi-Workspace Support (C22)**: Enhanced `check-prerequisites.js` and `init.js` to support nested workspaces with inherited root rules.
+- **Model-Aware History**: Updated engine history schema to include AI Model information, improving auditability of generated code.
+
+### Changed
+
+- **Task Checklist Logic**: Consolidated implementation checklists into `TASKS.md` for better execution tracking and status reporting.
+- **Gitignore Resilience**: Improved installers to automatically manage `.gitignore` entries for `.magic/` and `.agent/` directories with idempotent updates.
+- **Onboarding Safety**: Added production data collision guards to `onboard.md` to prevent accidental overwrites of existing project plans.
+
+### Fixed
+
+- **Error Reporting**: Enhanced `check-prerequisites.js` with structured, actionable JSON error suggestions.
+- **Path Handling**: Fixed Windows-specific path issues in installer scripts.
+
+## [1.4.162] - 2026-03-03
+
+### Added
+
+- **Regression Test T85**: Verifies mandatory engine integrity HALT when `.magic/` files are tampered (C1 enforcement).
+
+### Changed
+
+- **Engine Integrity Halt**: Upgraded `check-prerequisites.js` to set `ok: false` on checksum mismatches, ensuring a hard HALT during pre-flight checks.
+- **History Auto-Heal**: Enhanced `executor.js` to automatically recreate the `.magic/history/` directory and missing history files if deleted.
+
+### Fixed
+
+- **Resilient Logic**: Improved `check-prerequisites.js` to distinguish between critical engine integrity (HALT) and project data drift (WARNING), preserving self-healing capabilities.
+
+## [1.4.162] - 2026-03-02
 
 ### Changed
 

package/README.md

@@ -1,258 +1,325 @@
-# 🪄 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)
-
-## 📖 Description
-
-**The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
-
-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.
-
-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.
-
-### The Core Concept
-
-`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.
-
-Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
-
-```plaintext
-💡 Idea  →  📋 Specification  →  🗺️ Task & Plan  →  ⚡ Run  →  🚀 Code
-```
-
-Once initialized, your AI agent will automatically:
-
-- 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.
-
-### What Gets Installed
-
-After running the installer, your project directory will be augmented with the following structure:
-
-```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)
-```
-
-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.
-
-> [!TIP]
-> **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.
-
-## 🖼️ Visuals
-
-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.
-
-```mermaid
-flowchart TB
-    IDEA(["💡 Idea"])
-
-    subgraph BOX ["Magic Spec"]
-        direction TB
-
-        SPEC["📋 Spec"]
-
-        subgraph TASK ["🗺️ Task"]
-            direction TB
-            PLAN["📐 Plan"]
-            TASKS["📌 Tasks"]
-            PLAN --> TASKS
-        end
-
-        RUN["⚡ Run"]
-
-        SPEC  --> PLAN
-        TASKS --> RUN
-    end
-
-    CODE(["🚀 Code"])
-
-    IDEA --> SPEC
-    RUN  --> CODE
-
-    style IDEA  fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
-    style CODE  fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
-
-    style BOX   fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
-
-    style SPEC  fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
-    style RUN   fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
-
-    style TASK  fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
-    style PLAN  fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
-    style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
-```
-
-## ⚙️ Requirements
-
-Before installing Magic Spec, ensure you have one of the following available on your system:
-
-| Requirement | Details |
-| :--- | :--- |
-| **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) |
-
-## 📦 Installation
-
-Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
-
-### Option A: Node.js (`npx`)
-
-**Stable Release:**
-
-```bash
-# Basic installation (defaults to .agent/ folder)
-npx magic-spec@latest
-
-# Targeted installation for Cursor
-npx magic-spec@latest --cursor
-```
-
-**Edge Version (GitHub):**
-
-```bash
-npx --yes github:teratron/magic-spec
-```
-
-### Option B: Python (`uvx`)
-
-**Stable Release:**
-
-```bash
-# Basic installation
-uvx magic-spec
-
-# Targeted installation for Windsurf
-uvx magic-spec --windsurf
-```
-
-**Edge Version (GitHub):**
-
-```bash
-uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
-```
-
-### Option C: Python (`pipx`)
-
-```bash
-pipx run magic-spec
-```
-
-### Option D: Multi-Adapter Installation
-
-You can install support for multiple adapters at once:
-
-```bash
-npx magic-spec@latest --cursor --copilot --windsurf
-```
-
-### Option E: 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`).
-
-## 🔄 Updating
-
-Keep your SDD engine up to date with the latest logic and features:
-
-```bash
-# Check if update is available
-npx magic-spec@latest --check
-
-# Perform the update
-npx magic-spec@latest --update
-```
-
-> [!TIP]
-> 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).
-
-## 💬 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
-
-Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
-
-You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
-
-| AI Agent / IDE | Shortcut Flag | Env Flag |
-| :--- | :--- | :--- |
-| [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
-| [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
-| [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
-| [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
-| [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
-| **Roo Code** | `--roo` | `--env roo` |
-| **Amp** | `--amp` | `--env amp` |
-| **Amazon Q Developer** | `--q` | `--env q` |
-| **Kilo Code** | `--kilocode` | `--env kilocode` |
-| **Qwen Code** | `--qwen` | `--env qwen` |
-| **OpenCode** | `--opencode` | `--env opencode` |
-| **SHAI (OVHcloud)** | `--shai` | `--env shai` |
-| **IBM Bob** | `--bob` | `--env bob` |
-| **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
-| **Qoder IDE** | `--qoder` | `--env qoder` |
-| **Codex CLI** | `--codex` | `--env codex` |
-| **Auggie CLI** | `--augment` | `--env augment` |
-| **Antigravity IDE** | `--antigravity` | `--env antigravity` |
-| **Lingma IDE** | `--lingma` | `--env 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
-
-Distributed under the [MIT License](./LICENSE).
-
-## 📊 Project Status
-
-**Active Development** (v1.x). We are constantly refining the SDD engine based on real-world usage.
+# 🪄 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)
+
+## 📖 Description
+
+**The Specification-Driven Development (SDD) Operating System for AI Coding Agents.**
+
+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.
+
+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.
+
+### The Core Concept
+
+`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.
+
+Instead of chaotic prompt-engineering, Magic Spec provides a rigorous pipeline:
+
+```plaintext
+💡 Idea  →  📋 Specification  →  🗺️ Task & Plan  →  ⚡ Run  →  🚀 Code
+```
+
+Once initialized, your AI agent will automatically:
+
+- 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.
+
+### What Gets Installed
+
+After running the installer, your project directory will be augmented with the following structure:
+
+```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)
+```
+
+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.
+
+> [!TIP]
+> **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.
+
+## 🧠 The SDD Philosophy
+
+> *"No code without a spec. No spec without a plan."*
+
+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.
+
+### Human-Minimal Engineering (Autonomous Partner)
+
+The core design goal is to **keep humans out of the loop as much as possible** — without sacrificing control over what actually matters. Magic Spec moves from manual "Status Gates" to an **Autonomous Partner** model.
+
+#### Trust Mode: Encapsulated Logic
+
+Once you describe what you want, the engine takes over:
+
+- **Type A — "AI Trust"**: You provide intent, the agent handles the rest (`Draft -> RFC -> Stable -> Plan -> Run`). The internal SDD ceremony is **encapsulated** — you only see the result and a final "Go" gate.
+- **Type B — "Expert Audit"**: You maintain full control. Inspect `.design/` at any time to review specifications and plans. The rigor is there for when you need it.
+
+#### Silent Orchestration
+
+- **Auto-Stabilization**: Specifications are drafted, reviewed, and promoted to `Stable` automatically if the logic is clear.
+- **Zero-Prompt Planning**: Tasks are decomposed, prioritized, and scheduled without interrupting your flow.
+- **Silent Operations**: Phases execute end-to-end: retrospectives, changelogs, and context regeneration happen silently.
+- **Single Execution Gate**: The only mandatory prompt is the final sign-off before implementation begins.
+
+Everything else is automated. The agent does the engineering. You approve the direction.
+
+### Two-Layer Specification Model
+
+Every specification in Magic Spec belongs to one of two layers, and this separation is strictly enforced:
+
+**Layer 1 — Concept** (`layer: concept`)
+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.
+
+**Layer 2 — Implementation** (`layer: implementation`)
+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`.
+
+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.
+
+> **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.
+
+### Integrity by Design
+
+The engine actively protects specification integrity throughout the project lifecycle:
+
+- **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.
+- **Session Isolation (Phase Gates)**: To prevent AI "hallucinations" and context bleed-over, major workflow transitions enforce a **Hard Stop** (e.g., from Specification to Planning). You are required to physically open a "New Chat" in your IDE to proceed. Simply telling the AI to "forget" does not clear its context window reliably.
+- **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.
+- **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.
+- **Engine Integrity**: Core engine files are checksummed. Any untracked modification halts all workflows until the engine state is reconciled.
+
+### Self-Improving Feedback Loop
+
+Magic Spec includes a built-in retrospective engine that runs automatically at two levels:
+
+- **Level 1** fires after every phase completes: captures a lightweight snapshot of spec health, task metrics, and signal status.
+- **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.
+
+These retrospectives feed back into the specification layer, closing the loop between what was planned and what was actually built.
+
+## 🖼️ Visuals
+
+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.
+
+```mermaid
+flowchart TB
+    IDEA(["💡 Idea"])
+
+    subgraph BOX ["Magic Spec"]
+        direction TB
+
+        SPEC["📋 Spec"]
+
+        subgraph TASK ["🗺️ Task"]
+            direction TB
+            PLAN["📐 Plan"]
+            TASKS["📌 Tasks"]
+            PLAN --> TASKS
+        end
+
+        RUN["⚡ Run"]
+
+        SPEC  --> PLAN
+        TASKS --> RUN
+    end
+
+    CODE(["🚀 Code"])
+
+    IDEA --> SPEC
+    RUN  --> CODE
+
+    style IDEA  fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
+    style CODE  fill:#1e1e2e,stroke:#a6e3a1,color:#cdd6f4
+
+    style BOX   fill:#181825,stroke:#fab387,stroke-width:3px,color:#fab387
+
+    style SPEC  fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
+    style RUN   fill:#1e1e2e,stroke:#89b4fa,color:#cdd6f4
+
+    style TASK  fill:#11111b,stroke:#89b4fa,stroke-dasharray:5 5,color:#89b4fa
+    style PLAN  fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
+    style TASKS fill:#1e1e2e,stroke:#45475a,stroke-dasharray:4 4,color:#cdd6f4
+```
+
+## ⚙️ Requirements
+
+Before installing Magic Spec, ensure you have one of the following available on your system:
+
+| Requirement | Details |
+| :--- | :--- |
+| **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) |
+
+## 📦 Installation
+
+Works perfectly with **any project** — Rust, Go, Python, JavaScript, C++, or anything else. No runtime lock-in.
+
+### Option A: Node.js (`npx`)
+
+**Stable Release:**
+
+```bash
+# Basic installation (defaults to .agent/ folder)
+npx magic-spec@latest
+
+# Targeted installation for Cursor
+npx magic-spec@latest --cursor
+```
+
+**Edge Version (GitHub):**
+
+```bash
+npx --yes github:teratron/magic-spec
+```
+
+### Option B: Python (`uvx`)
+
+**Stable Release:**
+
+```bash
+# Basic installation
+uvx magic-spec
+
+# Targeted installation for Windsurf
+uvx magic-spec --windsurf
+```
+
+**Edge Version (GitHub):**
+
+```bash
+uvx --from git+https://github.com/teratron/magic-spec.git magic-spec
+```
+
+### Option C: Python (`pipx`)
+
+```bash
+pipx run magic-spec
+```
+
+### Option D: Multi-Adapter Installation
+
+You can install support for multiple adapters at once:
+
+```bash
+npx magic-spec@latest --cursor --copilot --windsurf
+```
+
+### Option E: 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`).
+
+## 🔄 Updating
+
+Keep your SDD engine up to date with the latest logic and features:
+
+```bash
+# Check if update is available
+npx magic-spec@latest --check
+
+# Perform the update
+npx magic-spec@latest --update
+```
+
+> [!TIP]
+> 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).
+
+### Post-Install: `.gitignore`
+
+The installer automatically adds `.magic/` and the adapter directory (e.g., `.agent/`, `.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.
+
+> [!TIP]
+> **Vendoring**: If you prefer to commit the engine into your repository (so teammates get it without running the installer), simply remove the `.magic/` and `.agent/` entries from your `.gitignore`.
+
+## 💬 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.
+- *"Run a project audit"*, *"magic.analyze"* → Triggers **Analyze** (Ventilation) 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
+
+Magic Spec is heavily optimized and provides native workflow generation for the world's most powerful AI development environments.
+
+You can install support for a specific adapter using the shortcut flag (e.g., `--cursor`) or the environment flag (e.g., `--env cursor`).
+
+| AI Agent / IDE | Shortcut Flag | Env Flag |
+| :--- | :--- | :--- |
+| [**Cursor**](https://cursor.com) (Agent Mode) | `--cursor` | `--env cursor` |
+| [**Windsurf**](https://codeium.com/windsurf) (Cascade) | `--windsurf` | `--env windsurf` |
+| [**Claude Code**](https://claude.ai/code) | `--claude` | `--env claude` |
+| [**Gemini CLI**](https://gemini.google.com) | `--gemini` | `--env gemini` |
+| [**GitHub Copilot**](https://github.com/features/copilot) | `--copilot` | `--env copilot` |
+| **Roo Code** | `--roo` | `--env roo` |
+| **Amp** | `--amp` | `--env amp` |
+| **Amazon Q Developer** | `--q` | `--env q` |
+| **Kilo Code** | `--kilocode` | `--env kilocode` |
+| **Qwen Code** | `--qwen` | `--env qwen` |
+| **OpenCode** | `--opencode` | `--env opencode` |
+| **SHAI (OVHcloud)** | `--shai` | `--env shai` |
+| **IBM Bob** | `--bob` | `--env bob` |
+| **CodeBuddy** | `--codebuddy` | `--env codebuddy` |
+| **Qoder IDE** | `--qoder` | `--env qoder` |
+| **Codex CLI** | `--codex` | `--env codex` |
+| **Auggie CLI** | `--augment` | `--env augment` |
+| **Antigravity IDE** | `--antigravity` | `--env antigravity` |
+| **Lingma IDE** | `--lingma` | `--env 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
+
+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

@@ -5,8 +5,13 @@
     "engineDir": ".magic",
     "agentDir": ".agent",
     "workflowsDir": "workflows",
+    "designDir": ".design",
+    "versionFile": ".version",
+    "checksumsFile": ".checksums",
+    "historyDir": "history",
     "defaultExt": ".md",
     "workflows": [
+        "magic.analyze",
         "magic.onboard",
         "magic.rule",
         "magic.run",
@@ -32,7 +37,7 @@
         "scripts/init.js",
         "templates/plan.md",
         "templates/retrospective.md",
-        "templates/specification.md",
+        "templates/spec.md",
         "templates/tasks.md"
     ],
     "download": {
@@ -64,6 +69,9 @@
         ],
         "docsDir": "docs"
     },
+    "git": {
+        "defaultBranch": "master"
+    },
     "tests": {
         "sandboxDir": "installers/tests/sandbox",
         "adaptersJson": "installers/adapters.json",

package/installers/node/index.js

@@ -77,6 +77,11 @@ function loadInstallerConfig() {
         failConfig("field 'magicFiles' must be an array of strings");
     }
 
+    const designDir = requireNonEmptyString(parsed.designDir, 'designDir');
+    const versionFile = requireNonEmptyString(parsed.versionFile, 'versionFile');
+    const checksumsFile = requireNonEmptyString(parsed.checksumsFile, 'checksumsFile');
+    const historyDir = requireNonEmptyString(parsed.historyDir, 'historyDir');
+
     return {
         githubRepo,
         packageName,
@@ -84,6 +89,10 @@ function loadInstallerConfig() {
         engineDir,
         agentDir,
         workflowsDir,
+        designDir,
+        versionFile,
+        checksumsFile,
+        historyDir,
         defaultExt,
         workflows,
         magicFiles,
@@ -102,6 +111,10 @@ const WORKFLOWS_DIR = INSTALLER_CONFIG.workflowsDir;
 const DEFAULT_EXT = INSTALLER_CONFIG.defaultExt;
 const WORKFLOWS = INSTALLER_CONFIG.workflows;
 const MAGIC_FILES = INSTALLER_CONFIG.magicFiles;
+const DESIGN_DIR = INSTALLER_CONFIG.designDir;
+const VERSION_FILE = INSTALLER_CONFIG.versionFile;
+const CHECKSUMS_FILE = INSTALLER_CONFIG.checksumsFile;
+const HISTORY_DIR = INSTALLER_CONFIG.historyDir;
 const DEFAULT_REMOVE_PREFIX = INSTALLER_CONFIG.removePrefix;
 const DOWNLOAD_TIMEOUT_MS = INSTALLER_CONFIG.download.timeoutMs;
 const NODE_USER_AGENT = INSTALLER_CONFIG.userAgent.node;
@@ -178,6 +191,45 @@ function copyDir(src, dest) {
     fs.cpSync(src, dest, { recursive: true, force: true });
 }
 
+function appendToGitignore(entries) {
+    const gitignoreFile = path.join(cwd, '.gitignore');
+    let content = '';
+    if (fs.existsSync(gitignoreFile)) {
+        content = fs.readFileSync(gitignoreFile, 'utf8');
+    }
+
+    const added = [];
+    for (const entry of entries) {
+        // Normalize: ensure trailing slash for directories
+        const normalized = entry.endsWith('/') ? entry : entry + '/';
+        // Check if already present (with or without trailing slash)
+        const base = normalized.replace(/\/$/, '');
+        const alreadyPresent = content.split(/\r?\n/).some(line => {
+            const trimmed = line.trim();
+            return trimmed === base || trimmed === normalized;
+        });
+        if (!alreadyPresent) {
+            added.push(normalized);
+        }
+    }
+
+    if (added.length === 0) return;
+
+    // Append under a Magic Spec section header
+    const section = '\n# Magic Spec (engine & workflows — installed via npx/uvx)';
+    const hasSection = content.includes('# Magic Spec');
+    let appendBlock = '';
+    if (!hasSection) {
+        appendBlock = section + '\n';
+    }
+    appendBlock += added.join('\n');
+
+    content = content.trimEnd() + '\n' + appendBlock + '\n';
+    fs.writeFileSync(gitignoreFile, content, 'utf8');
+    console.log(`📝 Updated .gitignore: added ${added.join(', ')}`);
+    console.log(`   💡 To vendor engine files in your repo, remove these entries.`);
+}
+
 function convertToToml(content, description) {
     // Escape quotes and backslashes for TOML triple-quoted strings
     const escapedContent = content
@@ -327,7 +379,7 @@ function runDoctor() {
                 console.log(`✅ ${item.path || name} is present`);
             } else {
                 const hint = requiredHint ? ` (Hint: ${requiredHint})` : '';
-                console.log(`❌ .design/${name} is missing${hint}`);
+                console.log(`❌ ${DESIGN_DIR}/${name} is missing${hint}`);
             }
         };
 
@@ -363,12 +415,12 @@ function runInfo() {
     console.log('magic-spec installation status');
     console.log('────────────────────────────────');
 
-    const versionFile = path.join(cwd, '.magic', '.version');
+    const versionFilePath = path.join(cwd, ENGINE_DIR, VERSION_FILE);
     let installedVersion = 'none';
-    if (fs.existsSync(versionFile)) {
-        installedVersion = fs.readFileSync(versionFile, 'utf8').trim();
+    if (fs.existsSync(versionFilePath)) {
+        installedVersion = fs.readFileSync(versionFilePath, 'utf8').trim();
     }
-    console.log(`Installed version : ${installedVersion}  (.magic/.version)`);
+    console.log(`Installed version : ${installedVersion}  (${ENGINE_DIR}/${VERSION_FILE})`);
 
     const ADAPTERS_PATH = path.join(__dirname, '..', 'adapters.json');
     let activeEnvs = [];
@@ -387,8 +439,8 @@ function runInfo() {
     const enginePresent = fs.existsSync(path.join(cwd, ENGINE_DIR));
     console.log(`Engine            : ${ENGINE_DIR}/     ${enginePresent ? '✅ present' : '❌ missing'}`);
 
-    const designPresent = fs.existsSync(path.join(cwd, '.design'));
-    console.log(`Workspace         : .design/    ${designPresent ? '✅ present' : '❌ missing'}`);
+    const designPresent = fs.existsSync(path.join(cwd, DESIGN_DIR));
+    console.log(`Workspace         : ${DESIGN_DIR}/    ${designPresent ? '✅ present' : '❌ missing'}`);
 
     console.log('────────────────────────────────');
     console.log(`Run \`npx ${PACKAGE_NAME}@latest --update\` to refresh engine files.`);
@@ -396,9 +448,9 @@ function runInfo() {
 }
 
 function runCheck() {
-    const versionFile = path.join(cwd, ENGINE_DIR, '.version');
+    const versionFile = path.join(cwd, ENGINE_DIR, VERSION_FILE);
     if (!fs.existsSync(versionFile)) {
-        console.log(`⚠️  Not installed via magic-spec (no ${ENGINE_DIR}/.version file)`);
+        console.log(`⚠️  Not installed via magic-spec (no ${ENGINE_DIR}/${VERSION_FILE} file)`);
         process.exit(0);
     }
 
@@ -451,7 +503,7 @@ async function runEject() {
     console.log(`   -  ${ENGINE_DIR}/`);
     console.log(`   -  ${AGENT_DIR}/  (or active env adapter dir)`);
     console.log(`   -  ${ENGINE_DIR}.bak/  (if exists)`);
-    console.log('\n   Your .design/ workspace will NOT be affected.');
+    console.log(`\n   Your ${DESIGN_DIR}/ workspace will NOT be affected.`);
 
     let shouldRun = autoAccept;
     if (!shouldRun) {
@@ -500,10 +552,10 @@ function getDirectoryChecksums(dir, baseDir = dir) {
     for (const item of items) {
         const fullPath = path.join(dir, item.name);
         if (item.isDirectory()) {
-            if (item.name === '.checksums' || item.name === 'history') continue;
+            if (item.name === CHECKSUMS_FILE || item.name === HISTORY_DIR) continue;
             Object.assign(results, getDirectoryChecksums(fullPath, baseDir));
         } else {
-            if (item.name === '.checksums') continue;
+            if (item.name === CHECKSUMS_FILE) continue;
             const relPath = path.relative(baseDir, fullPath).replace(/\\/g, '/');
             results[relPath] = getFileChecksum(fullPath);
         }
@@ -512,22 +564,22 @@ function getDirectoryChecksums(dir, baseDir = dir) {
 }
 
 async function handleConflicts(cwd) {
-    const checksumsFile = path.join(cwd, '.magic', '.checksums');
-    if (!fs.existsSync(checksumsFile)) return;
+    const checksumsFilePath = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
+    if (!fs.existsSync(checksumsFilePath)) return;
 
     let storedChecksums = {};
     try {
-        storedChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
+        storedChecksums = JSON.parse(fs.readFileSync(checksumsFilePath, 'utf8'));
     } catch (e) {
         return;
     }
 
     const conflicts = [];
     for (const [relPath, storedHash] of Object.entries(storedChecksums)) {
-        if (relPath === '.checksums' || relPath === '.version') continue;
+        if (relPath === CHECKSUMS_FILE || relPath === VERSION_FILE) continue;
 
-        // Backward compatibility: try .magic first, then project root
-        let localPath = path.join(cwd, '.magic', relPath);
+        // Backward compatibility: try engine dir first, then project root
+        let localPath = path.join(cwd, ENGINE_DIR, relPath);
         if (!fs.existsSync(localPath)) {
             localPath = path.join(cwd, relPath);
         }
@@ -733,6 +785,7 @@ async function main() {
     }
 
     try {
+        let selectedEnvResolved = null;
         if (!isLocal) {
             sourceRoot = await downloadPayload(versionToFetch);
         }
@@ -863,8 +916,8 @@ async function main() {
         if (!isUpdate) {
             const isWindows = process.platform === 'win32';
             const initScript = isWindows
-                ? path.join(cwd, '.magic', 'scripts', 'init.ps1')
-                : path.join(cwd, '.magic', 'scripts', 'init.sh');
+                ? path.join(cwd, ENGINE_DIR, 'scripts', 'init.ps1')
+                : path.join(cwd, ENGINE_DIR, 'scripts', 'init.sh');
 
             if (fs.existsSync(initScript)) {
                 let shouldRun = true;
@@ -901,21 +954,36 @@ async function main() {
             console.log(`✅ ${PACKAGE_NAME} updated successfully!`);
         }
 
-        // 4. Write version file (.magic/.version) - [T-2B01]
+        // 4. Write version file - [T-2B01]
         try {
-            const versionFile = path.join(cwd, '.magic', '.version');
-            fs.writeFileSync(versionFile, version, 'utf8');
+            const versionFileDest = path.join(cwd, ENGINE_DIR, VERSION_FILE);
+            fs.writeFileSync(versionFileDest, version, 'utf8');
         } catch (vErr) {
-            console.warn(`⚠️  Failed to write .magic/.version: ${vErr.message}`);
+            console.warn(`⚠️  Failed to write ${ENGINE_DIR}/${VERSION_FILE}: ${vErr.message}`);
         }
 
+        // 5. Auto-update .gitignore
+        const gitignoreEntries = [ENGINE_DIR];
+        if (envValues.length > 0) {
+            for (const env of envValues) {
+                const adapter = ADAPTERS[env];
+                if (adapter && adapter.dest) {
+                    gitignoreEntries.push(adapter.dest);
+                }
+            }
+        } else if (selectedEnvResolved && ADAPTERS[selectedEnvResolved]) {
+            gitignoreEntries.push(ADAPTERS[selectedEnvResolved].dest);
+        } else {
+            gitignoreEntries.push(AGENT_DIR);
+        }
+        appendToGitignore(gitignoreEntries);
 
         // 6. Save checksums - [T-2C03]
         try {
-            const currentChecksums = getDirectoryChecksums(path.join(cwd, '.magic'));
+            const currentChecksums = getDirectoryChecksums(path.join(cwd, ENGINE_DIR));
 
             if (isUpdate) {
-                const checksumsFile = path.join(cwd, '.magic', '.checksums');
+                const checksumsFile = path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE);
                 if (fs.existsSync(checksumsFile)) {
                     try {
                         const oldChecksums = JSON.parse(fs.readFileSync(checksumsFile, 'utf8'));
@@ -930,7 +998,7 @@ async function main() {
 
             Object.assign(currentChecksums, adapterChecksums);
 
-            fs.writeFileSync(path.join(cwd, '.magic', '.checksums'), JSON.stringify(currentChecksums, null, 2), 'utf8');
+            fs.writeFileSync(path.join(cwd, ENGINE_DIR, CHECKSUMS_FILE), JSON.stringify(currentChecksums, null, 2), 'utf8');
         } catch (cErr) {
             console.warn(`⚠️  Failed to save checksums: ${cErr.message}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "magic-spec",
-  "version": "1.4.15",
+  "version": "1.4.162",
   "description": "Magic Specification-Driven Development (SDD) Workflow",
   "author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
   "license": "MIT",