magic-spec 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ 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.0] - 2026-03-01
+
+### Added
+
+- **Smart Sync Optimization (AOP)** in `analyze.md`: Automated detection of manual renames during project re-analysis. If an orphaned specification matches a new uncovered directory (>80% similarity or title match), it triggers a `[RESCUE]` action instead of delete/create cycle.
+- **Manual Rename Rescue** in `spec.md`: Protocol to globally update references (INDEX, PLAN, TASKS) when a specification file is moved/renamed, preserving task progress.
+- **Regression Tests (T48–T51)**: Added coverage for Engine Integrity guards, Analysis Depth Control, and Smart Sync mechanisms.
+
+### Changed
+
+- **Test Suite Synchronization**: The `suite.md` version is now synchronized with the core engine version to prevent metadata confusion.
+
+## [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

package/README.md

@@ -1,78 +1,258 @@
-# 🪄 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)
-
-**The Specification-Driven Development (SDD) Operating System for AI Agents.**
-
-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.
-
----
-
-## ✨ Features
-
-- 🏗️ **Deterministic Pipeline**: Forced structure ensures architectural integrity.
-- 🎯 **Multi-Agent Core**: Works with Cursor, Windsurf, Claude, Gemini, and more.
-- 🔍 **Auto-Retrospective**: Built-in self-analysis engine that improves your workflow automatically.
-- 📦 **Thin-Client Installers**: Lightweight Node.js and Python installers for zero-friction setup.
-- 🗺️ **Phased Planning**: Intelligent dependency tracking and implementation roadmaps.
-
----
-
-## 🚀 Quick Start
-
-Works with **any project** — Rust, Go, Python, JavaScript, C++, or anything else.
-
-### Option A: Node.js (npx)
-
-```bash
-npx magic-spec@latest
-```
-
-### Option B: Python (uvx)
-
-```bash
-uvx magic-spec
-```
-
-**What happens next?**
-
-1. Magic Spec deploys the `.magic/` engine and `.agent/` workflows.
-2. An interactive onboarding tutorial (`magic.onboard`) helps you and your AI get started.
-3. Your project gains a dedicated `.design/` workspace for Specifications, Rules, and Plans.
-
----
-
-## 🧭 The Workflow
-
-1. **Specification**: Convert raw ideas into formal, versioned specs.
-2. **Task & Plan**: Generate a phased roadmap with atomic, trackable tasks.
-3. **Run**: Execute the plan with automatic progress tracking and quality gates.
-4. **Rule**: Manage project conventions in a central `RULES.md` constitution.
-
----
-
-## 📖 Documentation & Guides
-
-- [**Main Documentation**](./docs/README.md) — Detailed guide on workflows and architecture.
-- [**Installers Guide**](./installers/README.md) — Advanced CLI options and platform specifics.
-- [**Contributing**](./docs/contributing.md) — How to develop and extend the engine.
-
----
-
-## 🤝 Compatibility
-
-Magic Spec is optimized for the world's most powerful AI development environments:
-
-- [**Cursor**](https://cursor.com) (Rule definitions & Agent Mode)
-- [**Windsurf**](https://codeium.com/windsurf) (Cascade & Flows)
-- [**GitHub Copilot**](https://github.com/features/copilot) (Custom Instructions)
-- [**Claude**](https://claude.ai) (Project context)
-
----
-
-## 📄 License
-
-Distributed under the [MIT License](./LICENSE).  
-© 2026 Oleg Alexandrov & teratron. ✨
+# 🪄 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(["💡 Идея"])
+
+    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(["🚀 Код"])
+
+    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.

package/installers/config.json

@@ -6,6 +6,37 @@
     "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-"

package/installers/node/index.js

@@ -68,6 +68,14 @@ function loadInstallerConfig() {
     const agentDir = requireNonEmptyString(parsed.agentDir, 'agentDir');
     const workflowsDir = requireNonEmptyString(parsed.workflowsDir, 'workflowsDir');
     const defaultExt = requireNonEmptyString(parsed.defaultExt, 'defaultExt');
+    const workflows = Array.isArray(parsed.workflows) ? parsed.workflows : null;
+    if (!workflows) {
+        failConfig("field 'workflows' must be an array of strings");
+    }
+    const magicFiles = Array.isArray(parsed.magicFiles) ? parsed.magicFiles : null;
+    if (!magicFiles) {
+        failConfig("field 'magicFiles' must be an array of strings");
+    }
 
     return {
         githubRepo,
@@ -77,6 +85,8 @@ function loadInstallerConfig() {
         agentDir,
         workflowsDir,
         defaultExt,
+        workflows,
+        magicFiles,
         download: { timeoutMs, tempPrefix },
         userAgent: { node: nodeUserAgent },
         ejectTargets: parsed.eject.targets
@@ -90,6 +100,8 @@ const ENGINE_DIR = INSTALLER_CONFIG.engineDir;
 const AGENT_DIR = INSTALLER_CONFIG.agentDir;
 const WORKFLOWS_DIR = INSTALLER_CONFIG.workflowsDir;
 const DEFAULT_EXT = INSTALLER_CONFIG.defaultExt;
+const WORKFLOWS = INSTALLER_CONFIG.workflows;
+const MAGIC_FILES = INSTALLER_CONFIG.magicFiles;
 const DEFAULT_REMOVE_PREFIX = INSTALLER_CONFIG.removePrefix;
 const DOWNLOAD_TIMEOUT_MS = INSTALLER_CONFIG.download.timeoutMs;
 const NODE_USER_AGENT = INSTALLER_CONFIG.userAgent.node;
@@ -123,7 +135,7 @@ function collectEnvValues(argv) {
     return [...new Set(parsed)];
 }
 
-const envValues = collectEnvValues(args);
+let envValues = collectEnvValues(args);
 let selectedEnv = envValues.length > 0 ? envValues[0] : null;
 
 function runListEnvs(adapters) {
@@ -143,7 +155,7 @@ function runListEnvs(adapters) {
         const dest = `${adapter.dest}/`.padEnd(28);
         console.log(`  ${name}${padding}${dest}${adapter.description || ''}`);
     }
-    console.log('\nUsage: npx magic-spec@latest --env <name>');
+    console.log('\nUsage: npx magic-spec@latest --env <name>  OR  --<name> (e.g. --cursor)');
 }
 
 function askQuestion(query) {
@@ -197,9 +209,11 @@ function installAdapter(sourceRoot, env, adapters) {
 
     fs.mkdirSync(destDir, { recursive: true });
 
-    const files = fs.readdirSync(srcDir).filter(f => f.endsWith(DEFAULT_EXT));
-    for (const file of files) {
+    for (const wfName of WORKFLOWS) {
+        const file = wfName + DEFAULT_EXT;
         const srcFile = path.join(srcDir, file);
+        if (!fs.existsSync(srcFile)) continue;
+
         let destName = file.replace(new RegExp(`${DEFAULT_EXT.replace('.', '\\.')}$`), adapter.ext);
         const removePrefix = adapter.hasOwnProperty('removePrefix') ? adapter.removePrefix : DEFAULT_REMOVE_PREFIX;
         if (removePrefix) {
@@ -646,6 +660,7 @@ async function main() {
         console.log("  --eject              Remove magic-spec from project");
         console.log("\nOptions:");
         console.log("  --env <adapter>      Specify environment adapter");
+        console.log("  --<adapter>          Shortcut for --env <adapter> (e.g. --cursor)");
         console.log("  --update             Update engine files only");
         console.log("  --fallback-main      Pull payload from main branch");
         console.log("  --yes, -y            Auto-accept prompts");
@@ -685,6 +700,12 @@ async function main() {
         }
 
         // Determine environment
+        for (const env in ADAPTERS) {
+            if (args.includes(`--${env}`)) {
+                if (!envValues.includes(env)) envValues.push(env);
+            }
+        }
+
         let selectedEnvResolved = null;
         if (envValues.length > 0) {
             selectedEnvResolved = envValues[0];
@@ -719,22 +740,20 @@ async function main() {
             }
         }
 
-        // 1. Copy .magic
-        if (conflictsToSkip.length > 0) {
-            const srcMagic = path.join(sourceRoot, '.magic');
-            const destMagic = path.join(cwd, '.magic');
-            const items = fs.readdirSync(srcMagic, { withFileTypes: true });
-            for (const item of items) {
-                if (conflictsToSkip.includes(item.name)) continue;
-                if (item.name === '.checksums') continue;
-                if (item.isDirectory()) {
-                    copyDir(path.join(srcMagic, item.name), path.join(destMagic, item.name));
-                } else {
-                    fs.copyFileSync(path.join(srcMagic, item.name), path.join(destMagic, item.name));
-                }
+        // 1. Copy .magic (engine) - selective based on whitelist [T-3A01]
+        const srcMagic = path.join(sourceRoot, ENGINE_DIR);
+        const destMagic = path.join(cwd, ENGINE_DIR);
+        fs.mkdirSync(destMagic, { recursive: true });
+
+        for (const relPath of MAGIC_FILES) {
+            if (conflictsToSkip.includes(relPath)) continue;
+
+            const srcFile = path.join(srcMagic, relPath);
+            const destFile = path.join(destMagic, relPath);
+            if (fs.existsSync(srcFile)) {
+                fs.mkdirSync(path.dirname(destFile), { recursive: true });
+                fs.copyFileSync(srcFile, destFile);
             }
-        } else {
-            copyDir(path.join(sourceRoot, '.magic'), path.join(cwd, '.magic'));
         }
 
         // 2. Adapters
@@ -746,7 +765,30 @@ async function main() {
             } else if (selectedEnvResolved) {
                 installAdapter(sourceRoot, selectedEnvResolved, ADAPTERS);
             } else {
-                copyDir(path.join(sourceRoot, '.agent'), path.join(cwd, '.agent'));
+                // Default install
+                const srcEng = path.join(sourceRoot, AGENT_DIR);
+                const destEng = path.join(cwd, AGENT_DIR);
+                fs.mkdirSync(destEng, { recursive: true });
+                fs.mkdirSync(path.join(destEng, WORKFLOWS_DIR), { recursive: true });
+
+                for (const wfName of WORKFLOWS) {
+                    const file = wfName + DEFAULT_EXT;
+                    const srcWf = path.join(srcEng, WORKFLOWS_DIR, file);
+                    if (fs.existsSync(srcWf)) {
+                        fs.copyFileSync(srcWf, path.join(destEng, WORKFLOWS_DIR, file));
+                    }
+                }
+
+                // Copy other files in .agent if any (not workflows subfolder which we handled selectively)
+                const items = fs.readdirSync(srcEng, { withFileTypes: true });
+                for (const item of items) {
+                    if (item.name === WORKFLOWS_DIR) continue;
+                    if (item.isDirectory()) {
+                        copyDir(path.join(srcEng, item.name), path.join(destEng, item.name));
+                    } else {
+                        fs.copyFileSync(path.join(srcEng, item.name), path.join(destEng, item.name));
+                    }
+                }
             }
         }
 

package/package.json

@@ -1,10 +1,14 @@
 {
   "name": "magic-spec",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Magic Specification-Driven Development (SDD) Workflow",
   "author": "Oleg Alexandrov <alexandrovoleg.ru@gmail.com>",
   "license": "MIT",
   "homepage": "https://github.com/teratron/magic-spec",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/teratron/magic-spec.git"
+  },
   "main": "installers/node/index.js",
   "bin": {
     "magic-spec": "installers/node/index.js"