magic-spec 1.0.0 → 1.2.0

package/README.md

@@ -1,180 +1,196 @@
-# 🪄 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/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
-
-**Specification-Driven Development (SDD) workflow for AI coding agents.**
-
-Stop your AI from writing code before it understands the problem.  
-`magic-spec` installs a structured pipeline — *Thought → Spec → Plan → Task → Code* — directly into any project, regardless of stack.
-
-## ✨ What is Magic Spec?
-
-`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:
-
-```
-💡 Idea  →  📋 Specification  →  🗺️ Plan  →  ⚡ Task  →  🚀 Code  →  🔍 Retrospective
-```
-
-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.
-
-**No code is written until a specification exists. No spec is implemented without a plan.**
-
-## 🚀 Quick Start
-
-Works with **any project** — Rust, Go, Python, JavaScript, or anything else.  
-No runtime lock-in. Requires only Node.js *or* Python to install.
-
-### Option A — Node.js (npx)
-
-```bash
-npx magic-spec@latest
-```
-
-### Option B — Python (uvx)
-
-```bash
-uvx magic-spec
-```
-
-Both commands do exactly the same thing:
-
-1. Copy `.magic/` (the SDD engine) into your project.
-2. Copy `.agent/workflows/magic/` (agent trigger wrappers) into your project.
-3. Run the init script — creates your `.design/` workspace with `INDEX.md` and `RULES.md`.
-
-## 🧭 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 → Plan → Task → Code*. |
-| **Constitution-Driven** | All project decisions live in `.design/RULES.md` — the project's living constitution. |
-| **Self-Improving** | The Retrospective workflow analyzes real usage and generates improvement recommendations. |
-
-## 📁 What Gets Installed
-
-After running `npx magic-spec@latest` in your project root:
-
-```plaintext
-your-project/
-│
-├── .agent/workflows/magic/     # Agent entry points (slash commands)
-│   ├── plan.md
-│   ├── retrospective.md
-│   ├── rule.md
-│   ├── specification.md
-│   └── task.md
-│
-├── .magic/                     # SDD Engine (workflow logic, read-only)
-│   ├── init.md
-│   ├── plan.md
-│   ├── retrospective.md
-│   ├── rule.md
-│   ├── specification.md
-│   ├── task.md
-│   └── scripts/
-│       ├── 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
-
-```mermaid
-graph TD
-    IDEA["💡 Idea"] --> INIT{"🏗️ Auto-Init"}
-    INIT -->|.design/ exists| SPEC
-    INIT -->|.design/ missing| CREATE["Create .design/ structure"] --> SPEC
-    SPEC["📋 Specification"] <--> RULE["📜 Rule"]
-    SPEC --> PLAN["🗺️ Plan"]
-    PLAN --> TASK["⚡ Task"]
-    TASK --> CODE["🚀 Code"]
-    CODE --> RETRO["🔍 Retrospective"]
-    RETRO -.->|Feedback loop| SPEC
-```
-
-### Core Workflows
-
-| # | Workflow | Purpose |
-| :--- | :--- | :--- |
-| 1 | **Specification** | Converts raw thoughts into structured specs. Manages statuses: `Draft → RFC → Stable → Deprecated`. |
-| 2 | **Plan** | Reads Stable specs, builds a dependency graph, and produces a phased `PLAN.md`. |
-| 3 | **Task** | Decomposes the plan into atomic tasks with sequential and parallel execution tracks. |
-
-### Auxiliary Workflows
-
-| Workflow | Purpose |
-| :--- | :--- |
-| **Rule** | Manages the project constitution (`RULES.md §7`). Add, amend, or remove conventions. |
-| **Retrospective** | Analyzes SDD usage, collects metrics, and generates improvement recommendations. |
-
-## 💬 How to Use (with any AI agent)
-
-Just talk to your AI agent naturally. Initialization is **automatic** — no setup command required.
-
-```plaintext
-"Dispatch this thought into specs: I want a user auth system with JWT and Redis..."
-→ Runs Specification workflow
-
-"Create an implementation plan"
-→ Runs Plan workflow
-
-"Generate tasks for Phase 1"
-→ Runs Task workflow
-
-"Execute the next task"
-→ Runs Task workflow (execution mode)
-
-"Add rule: always use snake_case for file names"
-→ Runs Rule workflow
-
-"Run retrospective"
-→ Runs Retrospective workflow
-```
-
-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.** ✨
-
-## 🔄 Updating
-
-Pull the latest engine improvements without touching your project data:
-
-```bash
-# Node.js
-npx magic-spec@latest --update
-
-# Python
-uvx magic-spec --update
-```
-
-The update overwrites `.magic/` (the engine) but **never touches** `.design/` (your specs, plans, and tasks).
-
-## 🤝 Compatibility
-
-Works with any AI coding agent that can read markdown workflow files:
-
-- [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
-
-## 📄 License
-
-[MIT](./LICENSE) © 2026 Oleg Alexandrov
-
----
-
-## TODO: Magic Spec
+# 🪄 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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+**Specification-Driven Development (SDD) workflow for AI coding agents.**
+
+Stop your AI from writing code before it understands the problem.  
+`magic-spec` installs a structured pipeline — *Thought → Spec → Plan → Task → Code* — directly into any project, regardless of stack.
+
+## ✨ What is Magic Spec?
+
+`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:
+
+```
+💡 Idea  →  📋 Specification  →  🗺️ Plan  →  ⚡ Task  →  🚀 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
+
+Works with **any project** — Rust, Go, Python, JavaScript, or anything else.  
+No runtime lock-in. Requires only Node.js *or* Python to install.
+
+### Option A — Node.js (npx)
+
+```bash
+npx magic-spec@latest
+```
+
+### Option B — Python (uvx)
+
+```bash
+uvx magic-spec
+```
+
+Both commands do exactly the same thing:
+
+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`.
+
+## 🧭 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 → Plan → Task → 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. |
+
+## 🩺 System Health (CLI Doctor)
+
+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
+```
+
+This returns a visually formatted validation report of your project's `.design` structure, preventing broken context before you start coding.
+
+## 📁 What Gets Installed
+
+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
+
+```mermaid
+graph TD
+    IDEA["💡 Idea"] --> INIT{"🏗️ Auto-Init"}
+    INIT -->|.design/ exists| SPEC
+    INIT -->|.design/ missing| CREATE["Create .design/ structure"] --> SPEC
+    SPEC["📋 Specification"] <--> RULE["📜 Rule"]
+    SPEC --> TASK["🗺️ Task & Plan"]
+    TASK --> RUN["⚡ Run"]
+    RUN --> CODE["🚀 Code"]
+    RUN -.->|"auto: phase done"| RETRO["🔍 Retrospective"]
+    RETRO -.->|Feedback loop| SPEC
+```
+
+### Core Workflows
+
+| # | 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. |
+
+### Auxiliary Workflows
+
+| Workflow | Purpose |
+| :--- | :--- |
+| **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. |
+
+> **Retrospective** runs automatically inside the Run workflow — at phase completion (snapshot) and plan completion (full analysis). No manual command needed.
+
+## 💬 How to Use (with any AI agent)
+
+Just talk to your AI agent naturally. Initialization is **automatic** — no setup command required.
+
+```plaintext
+"Dispatch this thought into specs: I want a user auth system with JWT and Redis..."
+→ Runs Specification workflow
+
+"Create an implementation plan"
+→ Runs Task workflow
+
+"Generate tasks for Phase 1"
+→ Runs Task workflow
+
+"Execute the next task"
+→ Runs Run workflow
+
+"Add rule: always use snake_case for file names"
+→ Runs Rule workflow
+
+"Check if specs match the actual project state"
+→ Runs Specification workflow (Consistency Check)
+
+"Start the interactive tutorial"
+→ Runs Onboard workflow
+```
+
+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.** ✨
+
+## 🔄 Updating
+
+Pull the latest engine improvements without touching your project data:
+
+```bash
+# Node.js
+npx magic-spec@latest --update
+
+# Python
+uvx magic-spec --update
+```
+
+The update overwrites `.magic/` (the engine) but **never touches** `.design/` (your specs, plans, and tasks).
+
+## 🤝 Compatibility
+
+Works with any AI coding agent that can read markdown workflow files:
+
+- [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
+
+## 📄 License
+
+[MIT](./LICENSE) © 2026 Oleg Alexandrov

package/installers/node/index.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const https = require('https');
+const os = require('os');
+const { version } = require('./package.json');
+
+const GITHUB_REPO = 'teratron/magic-spec';
+const cwd = process.cwd();
+
+const args = process.argv.slice(2);
+const isUpdate = args.includes('--update');
+const isDoctor = args.includes('--doctor') || args.includes('--check');
+const isFallbackMain = args.includes('--fallback-main');
+
+const envFlag = args.find(a => a.startsWith('--env'));
+const envValues = envFlag
+    ? envFlag.includes('=')
+        ? envFlag.split('=')[1].split(',')
+        : (args[args.indexOf(envFlag) + 1] || '').split(',').filter(Boolean)
+    : [];
+
+function copyDir(src, dest) {
+    if (!fs.existsSync(src)) {
+        console.warn(`⚠️  Source not found: ${src}`);
+        return;
+    }
+    fs.cpSync(src, dest, { recursive: true, force: true });
+}
+
+function installAdapter(sourceRoot, env, adapters) {
+    const adapter = adapters[env];
+    if (!adapter) {
+        console.warn(`⚠️  Unknown --env value: "${env}".`);
+        console.warn(`   Valid values: ${Object.keys(adapters).join(', ')}`);
+        console.warn(`   Falling back to default .agent/`);
+        copyDir(path.join(sourceRoot, '.agent'), path.join(cwd, '.agent'));
+        return;
+    }
+
+    const srcDir = path.join(sourceRoot, '.agent', 'workflows');
+    const destDir = path.join(cwd, adapter.dest);
+
+    if (!fs.existsSync(srcDir)) {
+        console.warn(`⚠️  Source .agent/workflows/ not found.`);
+        return;
+    }
+
+    fs.mkdirSync(destDir, { recursive: true });
+
+    const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.md'));
+    for (const file of files) {
+        const srcFile = path.join(srcDir, file);
+        let destName = file.replace(/\.md$/, adapter.ext);
+        if (adapter.removePrefix) {
+            destName = destName.replace(adapter.removePrefix, '');
+        }
+        const destFile = path.join(destDir, destName);
+        fs.copyFileSync(srcFile, destFile);
+    }
+
+    console.log(`✅ Adapter installed: ${env} → ${adapter.dest}/ (${adapter.ext})`);
+}
+
+function runDoctor() {
+    const isWindows = process.platform === 'win32';
+    const checkScript = isWindows
+        ? path.join(cwd, '.magic', 'scripts', 'check-prerequisites.ps1')
+        : path.join(cwd, '.magic', 'scripts', 'check-prerequisites.sh');
+
+    if (!fs.existsSync(checkScript)) {
+        console.error('❌ Error: SDD engine not initialized. Run magic-spec first.');
+        process.exit(1);
+    }
+
+    console.log('🔍 Magic-spec Doctor:');
+    try {
+        let result;
+        if (isWindows) {
+            result = spawnSync('powershell.exe', ['-ExecutionPolicy', 'Bypass', '-File', checkScript, '-json'], { encoding: 'utf-8' });
+        } else {
+            result = spawnSync('bash', [checkScript, '--json'], { encoding: 'utf-8' });
+        }
+
+        let jsonStr = result.stdout.trim();
+        const match = jsonStr.match(/\{[\s\S]*\}/);
+        if (match) {
+            jsonStr = match[0];
+        }
+
+        const data = JSON.parse(jsonStr);
+        const arts = data.artifacts || {};
+        const checkItem = (name, item, requiredHint) => {
+            if (item && item.exists) {
+                console.log(`✅ ${item.path || name} is present`);
+            } else {
+                const hint = requiredHint ? ` (Hint: ${requiredHint})` : '';
+                console.log(`❌ .design/${name} is missing${hint}`);
+            }
+        };
+
+        checkItem('INDEX.md', arts['INDEX.md'], 'Run /magic.spec');
+        checkItem('RULES.md', arts['RULES.md'], 'Created at init');
+
+        if (arts['PLAN.md']) {
+            checkItem('PLAN.md', arts['PLAN.md'], 'Run /magic.task');
+        }
+        if (arts['TASKS.md']) {
+            checkItem('TASKS.md', arts['TASKS.md'], 'Run /magic.task');
+        }
+
+        if (data.warnings && data.warnings.length > 0) {
+            data.warnings.forEach(warn => {
+                console.log(`⚠️  ${warn}`);
+            });
+        }
+
+        if (arts.specs) {
+            const { stable } = arts.specs;
+            if (stable > 0) console.log(`✅ ${stable} specifications are Stable`);
+        }
+
+    } catch (err) {
+        console.error('❌ Failed to parse doctor output', err.message);
+    }
+    process.exit(0);
+}
+
+async function downloadPayload(targetVersion) {
+    const url = targetVersion === 'main'
+        ? `https://github.com/${GITHUB_REPO}/archive/refs/heads/main.tar.gz`
+        : `https://github.com/${GITHUB_REPO}/archive/refs/tags/v${targetVersion}.tar.gz`;
+
+    console.log(`📥 Downloading magic-spec payload (${targetVersion}) from GitHub...`);
+
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'magic-spec-'));
+    const archivePath = path.join(tempDir, 'payload.tar.gz');
+
+    return new Promise((resolve, reject) => {
+        const file = fs.createWriteStream(archivePath);
+
+        const makeRequest = (requestUrl) => {
+            https.get(requestUrl, { headers: { 'User-Agent': 'magic-spec-node' } }, (response) => {
+                if (response.statusCode === 301 || response.statusCode === 302) {
+                    // Follow redirect
+                    return makeRequest(response.headers.location);
+                }
+
+                if (response.statusCode === 404) {
+                    console.error(`❌ Error: Release ${targetVersion} not found on GitHub.`);
+                    console.error('   (Use --fallback-main to pull from the main branch instead)');
+                    reject(new Error('Payload not found'));
+                    return;
+                }
+
+                if (response.statusCode !== 200) {
+                    reject(new Error(`Failed with status code: ${response.statusCode}`));
+                    return;
+                }
+
+                response.pipe(file);
+
+                file.on('finish', () => {
+                    file.close();
+                    console.log('📦 Extracting payload...');
+
+                    try {
+                        // Using spawnSync for tar extraction. Requires 'tar' available on system.
+                        // For a pure JS solution without dependencies, you would use a package like 'tar'
+                        const isWindows = process.platform === 'win32';
+
+                        let result;
+                        if (isWindows) {
+                            // Use PowerShell to extract tar on Windows 10+
+                            result = spawnSync('tar', ['-xzf', archivePath, '-C', tempDir]);
+                        } else {
+                            // Standard Linux/macOS tar
+                            result = spawnSync('tar', ['-xzf', archivePath, '-C', tempDir]);
+                        }
+
+                        if (result.error || result.status !== 0) {
+                            throw new Error('Tar extraction failed. ' + (result.stderr ? result.stderr.toString() : ''));
+                        }
+
+                        const items = fs.readdirSync(tempDir);
+                        const extractedFolder = items.find(item => {
+                            const p = path.join(tempDir, item);
+                            return item !== 'payload.tar.gz' && fs.statSync(p).isDirectory();
+                        });
+
+                        if (extractedFolder) {
+                            resolve(path.join(tempDir, extractedFolder));
+                        } else {
+                            resolve(tempDir);
+                        }
+
+                    } catch (err) {
+                        reject(err);
+                    }
+                });
+            }).on('error', (err) => {
+                fs.unlink(archivePath, () => reject(err));
+            });
+        };
+
+        makeRequest(url);
+    });
+}
+
+async function main() {
+    if (isDoctor) {
+        runDoctor();
+        return;
+    }
+
+    if (args.includes('--help') || args.includes('-h')) {
+        console.log("Usage: npx magic-spec [--env <adapter>] [--update] [--doctor | --check] [--fallback-main]");
+        process.exit(0);
+    }
+
+    console.log(isUpdate ? '🪄 Updating magic-spec (.magic only)...' : '🪄 Initializing magic-spec...');
+
+    const versionToFetch = isFallbackMain ? 'main' : version;
+
+    try {
+        const sourceRoot = await downloadPayload(versionToFetch);
+
+        let ADAPTERS = {};
+        try {
+            ADAPTERS = JSON.parse(fs.readFileSync(path.join(sourceRoot, 'installers', 'adapters.json'), 'utf8'));
+        } catch (e) { }
+
+        // 1. Copy .magic
+        copyDir(path.join(sourceRoot, '.magic'), path.join(cwd, '.magic'));
+
+        // 2. Adapters
+        if (!isUpdate) {
+            if (envValues.length > 0) {
+                for (const env of envValues) {
+                    installAdapter(sourceRoot, env, ADAPTERS);
+                }
+            } else {
+                copyDir(path.join(sourceRoot, '.agent'), path.join(cwd, '.agent'));
+            }
+        }
+
+        // 3. Init script
+        if (!isUpdate) {
+            const isWindows = process.platform === 'win32';
+            const initScript = isWindows
+                ? path.join(cwd, '.magic', 'scripts', 'init.ps1')
+                : path.join(cwd, '.magic', 'scripts', 'init.sh');
+
+            if (fs.existsSync(initScript)) {
+                if (isWindows) {
+                    spawnSync('powershell.exe', ['-ExecutionPolicy', 'Bypass', '-File', initScript], { stdio: 'inherit' });
+                } else {
+                    fs.chmodSync(initScript, '755');
+                    spawnSync('bash', [initScript], { stdio: 'inherit' });
+                }
+            }
+            console.log('✅ magic-spec initialized successfully!');
+        } else {
+            console.log('✅ magic-spec updated successfully!');
+        }
+
+    } catch (err) {
+        console.error('❌ magic-spec initialization failed:', err.message);
+        process.exit(1);
+    }
+}
+
+main();