ostacky 0.5.9 → 0.6.0

package/assets/commands/install-stack.md

@@ -5,11 +5,11 @@ agent: build
 
 Instala el stack tecnológico de desarrollo para OpenCode. **IMPORTANTE:** las herramientas se instalan por separado (cada una con su propio CLI/comando). `npx ostacky install` solo instala el agente y commands de Ostacky en `.opencode/`. Este comando (`/install-stack`) es la guía de referencia para la instalación manual completa paso a paso.
 
-**Nota:** A partir de v0.5.9, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, Context7, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
+**Nota:** A partir de v0.6.0, `npx ostacky install` ya instala automáticamente el stack completo (CodeGraph, OpenSpec, Engram, Context7, MCPs bundleados) además del agente y skills. Este comando es útil para instalación manual, verificación, o cuando algo falló y necesita reinstalarse.
 
 **RESTRICCIÓN ABSOLUTA:** instalar ÚNICAMENTE para OpenCode. Está terminantemente prohibido crear o modificar archivos en `.claude/`, `.kiro/`, `.cursor/`, `.gemini/`, `.codex/`, `.antigravity/`, `.windsurf/` o cualquier otro directorio de plataformas externas.
 
-**Origen del set curado:** el set de skills (6 Superpowers + 4 OpenSpec) referenciado en `assets/agents/ostacky.md` está bundleado en `assets/skills/` dentro del paquete npm. Context7 agrega su propio skill vía `npx ctx7 setup --opencode`. La definición del set y su trazabilidad viven en `manifest.json` y `.opencode/ostacky-lock.json`.
+**Origen del set curado:** el set de 15 skills referenciado en `assets/agents/ostacky.md` está bundleado en `assets/skills/` dentro del paquete npm. Context7 agrega su propio skill vía `npx ctx7 setup --opencode`. La definición del set y su trazabilidad viven en `manifest.json` y `.opencode/ostacky-lock.json`.
 
 ---
 
@@ -70,11 +70,6 @@ El controller MCP se configura como server local en `opencode.json`. Si el contr
 ```json
 {
     "mcp": {
-        "ask-user-server": {
-            "type": "local",
-            "command": ["node", ".opencode/mcp/ask-user-server/index.js"],
-            "enabled": true
-        },
         "ostacky-controller": {
             "type": "local",
             "command": ["node", ".opencode/mcp/ostacky-controller/index.js"],
@@ -87,9 +82,9 @@ El controller MCP se configura como server local en `opencode.json`. Si el contr
 **Notas:**
 
 - El controller no es obligatorio para operar Ostacky — es un refuerzo de disciplina.
-- Sin controller, Ostacky usa las mismas reglas en lenguaje natural pero sin validación de transiciones ni persistencia de estado.
+- Sin controller, Ostacky usa las mismas reglas en lenguaje natural pero sin validación de transiciones ni persistencia de estado. El agente detecta automáticamente si el controller está disponible y opera en modo degraded si no.
 - El controller nunca autoriza subagentes sin confirmación explícita del usuario.
-- Los MCP servers se copian como archivos autocontenidos (bundleados en `dist/mcp/` durante el build). No requieren `npm install` ni `bun install` — cada `index.js` es un único archivo con todas las dependencias inlined.
+- Los MCP servers se copian como archivos autocontenidos (bundleados en `dist/mcp/` durante el build). No requieren `npm install` ni `bun install` — cada `index.js` es un único archivo autocontenido sin dependencias externas.
 - El installer maneja `opencode.jsonc` (con comentarios) correctamente — strippea comentarios antes de parsear y escribe JSON válido de vuelta.
 - Si CodeGraph crea un `AGENTS.md` en la raíz del proyecto, el installer lo mueve a `.opencode/tools/codegraph/AGENTS.md` automáticamente.
 
@@ -97,23 +92,19 @@ El controller MCP se configura como server local en `opencode.json`. Si el contr
 
 ## Paso 2 — Skills curadas (bundleadas)
 
-Las **11 skills curadas del set base** (6 Superpowers + 4 OpenSpec + 1 Ostacky) están bundleadas dentro del paquete Ostacky en `assets/skills/`. No se descargan ni clonan; ya vienen en el paquete npm. Context7 agrega su propia skill aparte (Paso 6).
+Las **15 skills curadas** están bundleadas dentro del paquete Ostacky en `assets/skills/`. No se descargan ni clonan; ya vienen en el paquete npm. Context7 agrega su propia skill aparte (Paso 6).
 
 Copiá cada skill bundleada a `.opencode/skills/<nombre>/` preservando la estructura interna (incluyendo `SKILL.md` y cualquier subdirectorio como `scripts/` o `references/`):
 
 ```bash
-# Ejemplo para una skill; aplicar a las 11
-mkdir -p .opencode/skills/thinking
-cp -r assets/skills/thinking/* .opencode/skills/thinking/
+# Ejemplo para una skill; aplicar a las 15
+mkdir -p .opencode/skills/brainstorming
+cp -r assets/skills/brainstorming/* .opencode/skills/brainstorming/
 ```
 
-**Set curado (referenciado en `assets/agents/ostacky.md`):**
-
-**Superpowers (6):** `thinking`, `writing-plans`, `tdd`, `subagent-driven-development`, `dispatching-parallel-agents`, `review`
+**Set curado (15 skills, referenciado en `assets/agents/ostacky.md`):**
 
-**OpenSpec (3):** `openspec-propose`, `openspec-apply-change`, `openspec-archive-change`
-
-**Ostacky (1):** `execution-mode-evaluation` — análisis de modo de ejecución (INLINE vs SUBAGENT_DRIVEN)
+`brainstorming`, `writing-plans`, `tdd`, `review`, `execution-mode-evaluation`, `subagent-driven-development`, `dispatching-parallel-agents`, `openspec-propose`, `openspec-apply-change`, `openspec-archive-change`, `receiving-code-review`, `using-git-worktrees`, `using-superpowers`, `writing-skills`, `graceful-degradation`
 
 **NO se requiere** el plugin `superpowers@git+...` en `opencode.json`. Las skills viven en `.opencode/skills/` y OpenCode las descubre automáticamente desde ahí.
 
@@ -148,11 +139,6 @@ Leé `opencode.json` (o `opencode.jsonc`) en la raíz del proyecto.
             "url": "https://mcp.context7.com/mcp",
             "enabled": true
         },
-        "ask-user-server": {
-            "type": "local",
-            "command": ["node", ".opencode/mcp/ask-user-server/index.js"],
-            "enabled": true
-        },
         "ostacky-controller": {
             "type": "local",
             "command": ["node", ".opencode/mcp/ostacky-controller/index.js"],
@@ -166,38 +152,48 @@ Leé `opencode.json` (o `opencode.jsonc`) en la raíz del proyecto.
 
 ---
 
-## Paso 4 — OpenSpec
+## Paso 4 — OpenSpec (MCP Server local)
+
+OpenSpec se instala como MCP server local en `.opencode/mcp/openspec/`. El server provee tools para proposal, apply, archive y sync de cambios.
 
-Inicializá OpenSpec configurándolo exclusivamente para OpenCode:
+### Verificar instalación
 
 ```bash
-bunx openspec init --tools opencode --force
+.opencode/mcp/openspec/index.js --version 2>/dev/null || echo "no-instalado"
 ```
 
-El flag `--tools opencode` garantiza que solo se generen archivos en `.opencode/skills/` y `.opencode/commands/`. El flag `--force` limpia archivos legacy de inicializaciones anteriores que hayan podido configurar otras plataformas.
+### Configurar en opencode.json
 
-Si OpenSpec ya estaba correctamente inicializado para opencode, ejecutá en su lugar:
-
-```bash
-bunx openspec update
+```json
+{
+    "mcp": {
+        "openspec": {
+            "type": "local",
+            "command": ["node", ".opencode/mcp/openspec/index.js"],
+            "enabled": true
+        }
+    }
+}
 ```
 
-**IMPORTANTE:** verificar después de la ejecución que no existan carpetas `.claude/`, `.kiro/`, `.cursor/` ni similares generadas por OpenSpec. Si existen, eliminalas.
+**Notas:**
 
-### Desinstalar OpenSpec
+- OpenSpec MCP server es autocontenido — no requiere `npm install` ni `bun install`.
+- El server provee las tools: `openspec_propose`, `openspec_list`, `openspec_archive`, `openspec_get_change`.
+- Los changes se almacenan en `openspec/changes/` y se archivan en `openspec/archive/`.
 
-Para remover los archivos de OpenSpec del proyecto:
+### Desinstalar OpenSpec
 
 ```bash
-# Eliminar skills y commands de OpenSpec generados en .opencode/
-rm -rf .opencode/skills/thinking .opencode/skills/openspec-propose \
-       .opencode/skills/openspec-apply-change .opencode/skills/openspec-archive-change
-# Los specs y changes viven en openspec/ — eliminarlos si no los necesitás:
+# Remover el MCP server
+rm -rf .opencode/mcp/openspec/
+
+# Remover la entrada MCP de opencode.json (editar el archivo)
+
+# Remover cambios archivados (opcional)
 rm -rf openspec/
 ```
 
-Esto no desinstala el CLI de OpenSpec (que se ejecuta via `npx`), solo limpia los artefactos del proyecto.
-
 ---
 
 ## Paso 5 — Engram
@@ -245,19 +241,15 @@ chmod +x .opencode/tools/engram/bin/engram  # Unix only
 
 ### Configurar para OpenCode
 
-Una vez que Engram está descargado localmente, ejecutá el setup que instala el plugin de OpenCode:
-
-```bash
-.opencode/tools/engram/bin/engram setup opencode
-```
+Una vez que Engram está descargado localmente, el plugin se copia automáticamente de `assets/plugins/` a `.opencode/plugins/` durante la instalación. No necesitás correr ningún comando adicional.
 
 Este comando:
 
-- Instala el plugin de Engram para OpenCode en `~/.config/opencode/plugins/`
+- Copia el plugin de Engram para OpenCode a `.opencode/plugins/`
 - **NO** agrega la entrada MCP al `opencode.json` del proyecto — eso lo hace `npx ostacky install` automáticamente
 - **NO** toca `.claude/`, `.cursor/`, `.gemini/` ni ninguna otra plataforma
 
-Verificá que `opencode.json` contenga la entrada MCP de Engram apuntando al binario local (agregada por el installer de Ostacky, no por `engram setup`):
+Verificá que `opencode.json` contenga la entrada MCP de Engram apuntando al binario local (agregada por el installer de Ostacky):
 
 ```json
 {
@@ -281,7 +273,7 @@ El plugin de Engram para OpenCode usa `engram serve` para session tracking y rec
 engram serve
 ```
 
-Corre en el puerto 7437 por defecto. Los datos se almacenan en `~/.engram/engram.db` (SQLite local).
+Corre en el puerto 7437 por defecto. Los datos se almacenan en `~/.engram/engram.db` (SQLite local). **Nota:** esta ruta está hardcoded en el binario de Engram y no es configurable por Ostacky.
 
 ### Desinstalar Engram del proyecto
 
@@ -290,14 +282,15 @@ Para remover la configuración de Engram del proyecto (sin borrar los datos):
 ```bash
 # Remover la entrada mcp.engram de opencode.json (editar el archivo)
 # Remover el plugin de Engram de OpenCode:
-rm -f ~/.config/opencode/plugins/engram.ts
+rm -f .opencode/plugins/engram.ts
 # Remover el binario local
 rm -rf .opencode/tools/engram/
 ```
 
-Para borrar todos los datos de Engram (CUIDADO: borra toda la memoria persistente):
+Para borrar todos los datos de Engram (**OPCIONAL** — esto borra la memoria persistente de TODOS los proyectos que usen Engram):
 
 ```bash
+# ⚠️ Solo si querés borrar toda la memoria de Engram
 rm -rf ~/.engram/
 ```
 
@@ -411,26 +404,31 @@ Cada herramienta se instala en su propia carpeta dentro de `.opencode/` para man
 │   ├── opsx-archive.md       # Generado por OpenSpec
 │   ├── opsx-explore.md       # Generado por OpenSpec
 │   └── opsx-propose.md       # Generado por OpenSpec
-├── mcp/             # MCP servers bundleados (con node_modules)
-│   ├── ask-user-server/
+├── mcp/             # MCP servers bundleados (autocontenidos, sin dependencias externas)
+│   ├── ostacky-controller/
 │   │   ├── index.js
 │   │   ├── package.json
 │   │   └── node_modules/
-│   └── ostacky-controller/
+│   └── openspec/            # NUEVO: MCP server local
 │       ├── index.js
 │       ├── package.json
 │       └── node_modules/
-├── skills/          # Skills bundleadas
-│   ├── thinking/
+├── skills/          # Skills bundleadas (15)
+│   ├── brainstorming/
 │   ├── writing-plans/
 │   ├── tdd/
+│   ├── review/
+│   ├── execution-mode-evaluation/
 │   ├── subagent-driven-development/
 │   ├── dispatching-parallel-agents/
-│   ├── review/
 │   ├── openspec-propose/
 │   ├── openspec-apply-change/
 │   ├── openspec-archive-change/
-│   └── execution-mode-evaluation/
+│   ├── receiving-code-review/
+│   ├── using-git-worktrees/
+│   ├── using-superpowers/
+│   ├── writing-skills/
+│   └── graceful-degradation/
 ├── tools/           # Config y archivos de herramientas externas
 │   ├── codegraph/   # Config de CodeGraph (AGENTS.md si codegraph lo crea)
 │   ├── engram/      # Config project-local de Engram
@@ -444,22 +442,95 @@ Cada herramienta se instala en su propia carpeta dentro de `.opencode/` para man
 - El binario de CodeGraph es **local al proyecto** en `.opencode/tools/codegraph/bin/codegraph` (con su runtime Node vendored en `.opencode/tools/codegraph/node`). No se instala globalmente.
 - El binario de Engram es **local al proyecto** en `.opencode/tools/engram/bin/engram`. No se instala globalmente.
 - Context7 se registra como MCP remoto en `opencode.jsonc`. Su skill opcional se instala via `npx ctx7 setup --opencode` en `.opencode/skills/context7/`.
-- Los MCP servers bundleados tienen sus `node_modules/` instalados localmente dentro de `.opencode/mcp/<name>/`.
+- Los MCP servers bundleados son autocontenidos (un solo `index.js` sin dependencias externas).
 
 ## Verificación final
 
 Confirmá que:
 
-1. `.opencode/skills/` contiene las skills curadas (6 Superpowers + 4 OpenSpec + 1 Ostacky `execution-mode-evaluation`) y opcionalmente `context7/` si se instaló con `npx ctx7 setup --opencode`
-2. `.opencode/commands/` contiene los commands bundleados por Ostacky (`install-stack`, `opsx-sync`) y los 4 commands generados por OpenSpec (`opsx-apply`, `opsx-archive`, `opsx-explore`, `opsx-propose`) si OpenSpec fue inicializado en el Paso 4
-3. `opencode.json` (o `.jsonc`) tiene los bloques `mcp.codegraph` (apuntando a `.opencode/tools/codegraph/bin/codegraph`), `mcp.engram` (apuntando a `.opencode/tools/engram/bin/engram`), `mcp.context7` y los MCP bundleados (`ask-user-server`, `ostacky-controller`) — sin campo `plugin`
+1. `.opencode/skills/` contiene las 15 skills curadas y opcionalmente `context7/` si se instaló con `npx ctx7 setup --opencode`
+2. `.opencode/commands/` contiene los commands bundleados por Ostacky (`install-stack`, `opsx-sync`) y los 4 commands generados por OpenSpec (`opsx-apply`, `opsx-archive`, `opsx-explore`, `opsx-propose`) si OpenSpec fue inicializado
+3. `opencode.json` (o `.jsonc`) tiene los bloques MCP: `codegraph`, `engram`, `context7`, `ostacky-controller`, `openspec` — sin campo `plugin`
 4. `.codegraph/` existe en la raíz del proyecto (índice local de CodeGraph)
 5. `.opencode/tools/codegraph/bin/codegraph --version` funciona (binario local)
 6. `.opencode/tools/engram/bin/engram --version` funciona (binario local)
 7. Context7 configurado: `mcp.context7` presente en `opencode.jsonc` y/o `.opencode/skills/context7/SKILL.md` existe
-8. Los MCP bundleados tienen sus dependencias instaladas en `.opencode/mcp/*/node_modules/`
-9. `.opencode/tools/` contiene subdirectorios para `codegraph/`, `engram/` y `context7/`
-10. **NO existen** archivos generados en `.claude/`, `.kiro/`, `.cursor/`, `.gemini/`, `.codex/` ni ningún directorio de otra plataforma
-11. **NO existe** `AGENTS.md` en la raíz del proyecto (si CodeGraph lo creó, el installer lo mueve a `.opencode/tools/codegraph/`)
+8. `.opencode/mcp/openspec/index.js` existe (MCP server local)
+9. Los MCP bundleados tienen sus dependencias instaladas en `.opencode/mcp/*/node_modules/`
+10. `.opencode/tools/` contiene subdirectorios para `codegraph/`, `engram/` y `context7/`
+11. **NO existen** archivos generados en `.claude/`, `.kiro/`, `.cursor/`, `.gemini/`, `.codex/` ni ningún directorio de otra plataforma
+12. **NO existe** `AGENTS.md` en la raíz del proyecto (si CodeGraph lo creó, el installer lo mueve a `.opencode/tools/codegraph/`)
 
 Reportá el estado de cada componente con ✓ o ✗.
+
+## Troubleshooting
+
+### MCP Server no responde
+
+Si el controller o openspec MCP server no responde después de la instalación:
+
+1. **Verificar que el archivo existe:**
+
+    ```bash
+    ls -la .opencode/mcp/ostacky-controller/index.js
+    ls -la .opencode/mcp/openspec/index.js
+    ```
+
+2. **Verificar que Node.js está disponible:**
+
+    ```bash
+    node --version
+    ```
+
+3. **Testear el MCP server directamente:**
+
+    ```bash
+    echo '{"jsonrpc":"2.0","id":1,"method":"ping","params":{}}' | node .opencode/mcp/ostacky-controller/index.js
+    ```
+
+4. **Si falla, reinstalar:**
+    ```bash
+    npx ostacky install-stack
+    ```
+
+### CodeGraph no indexa
+
+1. **Verificar que el binario funciona:**
+
+    ```bash
+    .opencode/tools/codegraph/bin/codegraph --version
+    ```
+
+2. **Re-inicializar el índice:**
+
+    ```bash
+    .opencode/tools/codegraph/bin/codegraph init -i
+    ```
+
+3. **Si el binario no existe, reinstalar:**
+    ```bash
+    npx ostacky install-stack
+    ```
+
+### Engram no inicia
+
+1. **Verificar que el binario funciona:**
+
+    ```bash
+    .opencode/tools/engram/bin/engram --version
+    ```
+
+2. **Verificar que el plugin está instalado:**
+
+    ```bash
+    ls -la .opencode/plugins/engram.ts
+    ```
+
+3. **Re-instalar el plugin:**
+    ```bash
+    cp assets/plugins/engram.ts .opencode/plugins/engram.ts
+    ```
+
+### Degradación graceful
+
+Si múltiples tools fallan, Ostacky opera en modo degraded. Ver `assets/skills/graceful-degradation/SKILL.md` para los flujos alternativos disponibles.

package/assets/mcp/openspec/bun.lock

@@ -0,0 +1,20 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "openspec-mcp",
+      "dependencies": {
+        "@modelcontextprotocol/server": "^2.0.0-beta.5",
+        "zod": "^4.0.0",
+      },
+    },
+  },
+  "packages": {
+    "@modelcontextprotocol/core": ["@modelcontextprotocol/core@2.0.0-beta.5", "", { "dependencies": { "zod": "^4.2.0" } }, "sha512-HKbY9XTbsDy1Y6r2I55TGE3JEapM0vg96e1MUmBIF9LGjos5gjhcIrTz1yvBPLg2aFKHjwhUAQfRdrCEnPxNew=="],
+
+    "@modelcontextprotocol/server": ["@modelcontextprotocol/server@2.0.0-beta.5", "", { "dependencies": { "@modelcontextprotocol/core": "2.0.0-beta.5", "zod": "^4.2.0" } }, "sha512-i1E5l75rQKsgY/AKAIspgMBH1vEL7dqiK7tHr0L+raYcb0SWOziqNGJXGIG6NY4AlXDWIKGJQGB7Nqfs3oUi5g=="],
+
+    "zod": ["zod@4.4.3", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
+  }
+}

package/assets/mcp/openspec/index.js

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/server';
+import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
+import * as z from 'zod/v4';
+import {
+    readFileSync,
+    writeFileSync,
+    existsSync,
+    mkdirSync,
+    readdirSync,
+    renameSync,
+    unlinkSync,
+} from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+
+const PROJECT_ROOT = process.cwd();
+const OPENSPEC_DIR = join(PROJECT_ROOT, 'openspec');
+
+function safeJsonStringify(obj, indent = 2) {
+    const seen = new WeakSet();
+    return JSON.stringify(obj, (key, value) => {
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) return '[Circular]';
+            seen.add(value);
+        }
+        if (typeof value === 'bigint') return value.toString();
+        if (value instanceof Error) return { message: value.message, stack: value.stack, name: value.name };
+        return value;
+    }, indent);
+}
+
+function log(event, data) {
+    const ts = new Date().toISOString();
+    const payload = data ? ` ${safeJsonStringify(data)}` : '';
+    console.error(`[${ts}] ${event}${payload}`);
+}
+
+/**
+ * Cleans up stale .tmp.* files from a previous crash.
+ */
+function cleanupTmpFiles(dir) {
+    if (!dir || !existsSync(dir)) return;
+    try {
+        for (const entry of readdirSync(dir)) {
+            if (entry.includes('.tmp.')) {
+                try {
+                    unlinkSync(join(dir, entry));
+                } catch {
+                    /* best-effort */
+                }
+            }
+        }
+    } catch {
+        /* best-effort */
+    }
+}
+
+/**
+ * Atomic write: write to tmp file, then rename.
+ * Prevents corruption on crash.
+ */
+function atomicWriteSync(filePath, content) {
+    const dir = dirname(filePath);
+    mkdirSync(dir, { recursive: true });
+    const tmp = filePath + '.tmp.' + process.pid;
+    writeFileSync(tmp, content, 'utf-8');
+    renameSync(tmp, filePath);
+}
+
+function safeHandler(fn) {
+    return async (params) => {
+        try {
+            const result = await fn(params);
+            return { content: [{ type: 'text', text: safeJsonStringify(result) }] };
+        } catch (error) {
+            log('tool:error', {
+                name: fn.name || 'anonymous',
+                error: error.message,
+                stack: error.stack,
+            });
+            return {
+                content: [{ type: 'text', text: safeJsonStringify({ error: error.message }) }],
+                isError: true,
+            };
+        }
+    };
+}
+
+// ── Input Validation ─────────────────────────────────────────────────────────
+
+function validateChangeId(changeId) {
+    if (!changeId || typeof changeId !== 'string') {
+        return 'changeId is required and must be a non-empty string';
+    }
+    if (/[\/\\]/.test(changeId) || changeId === '.' || changeId === '..') {
+        return 'changeId contains invalid characters';
+    }
+    return null;
+}
+
+function validateProposalInput({ title, description, scope }) {
+    if (!title || typeof title !== 'string' || title.trim().length === 0) {
+        return 'title is required and must be a non-empty string';
+    }
+    if (!description || typeof description !== 'string' || description.trim().length === 0) {
+        return 'description is required and must be a non-empty string';
+    }
+    if (!scope || typeof scope !== 'string' || scope.trim().length === 0) {
+        return 'scope is required and must be a non-empty string';
+    }
+    return null;
+}
+
+// ── OpenSpec State Manager ──────────────────────────────────────────────────
+
+class OpenSpecManager {
+    #changesDir;
+
+    constructor() {
+        this.#changesDir = join(OPENSPEC_DIR, 'changes');
+        if (!existsSync(this.#changesDir)) {
+            mkdirSync(this.#changesDir, { recursive: true });
+        }
+        // Clean up stale tmp files from previous crashes
+        cleanupTmpFiles(this.#changesDir);
+    }
+
+    listChanges() {
+        if (!existsSync(this.#changesDir)) return [];
+        return readdirSync(this.#changesDir).filter(f =>
+            existsSync(join(this.#changesDir, f, 'proposal.md'))
+        );
+    }
+
+    getChange(changeId) {
+        const changeDir = join(this.#changesDir, changeId);
+        if (!existsSync(changeDir)) return null;
+
+        const proposal = existsSync(join(changeDir, 'proposal.md'))
+            ? readFileSync(join(changeDir, 'proposal.md'), 'utf-8')
+            : null;
+        const design = existsSync(join(changeDir, 'design.md'))
+            ? readFileSync(join(changeDir, 'design.md'), 'utf-8')
+            : null;
+        const tasks = existsSync(join(changeDir, 'tasks.md'))
+            ? readFileSync(join(changeDir, 'tasks.md'), 'utf-8')
+            : null;
+
+        return { changeId, proposal, design, tasks };
+    }
+
+    createProposal({ title, description, scope }) {
+        const changeId = `change-${Date.now()}`;
+        const changeDir = join(this.#changesDir, changeId);
+        mkdirSync(changeDir, { recursive: true });
+
+        const proposal = `# ${title}
+
+## Description
+${description}
+
+## Scope
+${scope}
+
+## Status
+- Created: ${new Date().toISOString()}
+- Phase: proposal
+`;
+
+        atomicWriteSync(join(changeDir, 'proposal.md'), proposal);
+        log('proposal:created', { changeId, title });
+        return { changeId, status: 'created' };
+    }
+
+    archiveChange({ changeId }) {
+        const changeDir = join(this.#changesDir, changeId);
+        if (!existsSync(changeDir)) {
+            return { error: `Change ${changeId} not found` };
+        }
+
+        // Move to archive
+        const archiveDir = join(OPENSPEC_DIR, 'archive');
+        if (!existsSync(archiveDir)) {
+            mkdirSync(archiveDir, { recursive: true });
+        }
+
+        renameSync(changeDir, join(archiveDir, changeId));
+        log('change:archived', { changeId });
+        return { changeId, status: 'archived' };
+    }
+}
+
+const manager = new OpenSpecManager();
+
+// ── MCP Server ──────────────────────────────────────────────────────────────
+
+const server = new McpServer({
+    name: 'openspec',
+    version: '0.6.0',
+});
+
+server.registerTool(
+    'openspec_list',
+    {
+        description: 'List all active changes',
+        inputSchema: z.object({}),
+    },
+    safeHandler(async () => {
+        log('tool:openspec_list');
+        const changes = manager.listChanges();
+        return { changes };
+    })
+);
+
+server.registerTool(
+    'openspec_propose',
+    {
+        description: 'Create a new change proposal',
+        inputSchema: z.object({
+            title: z.string().min(1).describe('Change title'),
+            description: z.string().min(1).describe('Change description'),
+            scope: z.string().min(1).describe('Change scope'),
+        }),
+    },
+    safeHandler(async ({ title, description, scope }) => {
+        log('tool:openspec_propose', { title });
+        return manager.createProposal({ title, description, scope });
+    })
+);
+
+server.registerTool(
+    'openspec_archive',
+    {
+        description: 'Archive a completed change',
+        inputSchema: z.object({
+            changeId: z.string().min(1).describe('Change ID to archive'),
+        }),
+    },
+    safeHandler(async ({ changeId }) => {
+        const validationError = validateChangeId(changeId);
+        if (validationError) return { error: validationError };
+        log('tool:openspec_archive', { changeId });
+        return manager.archiveChange({ changeId });
+    })
+);
+
+server.registerTool(
+    'openspec_get_change',
+    {
+        description: 'Get change details (proposal, design, tasks)',
+        inputSchema: z.object({
+            changeId: z.string().min(1).describe('Change ID'),
+        }),
+    },
+    safeHandler(async ({ changeId }) => {
+        const validationError = validateChangeId(changeId);
+        if (validationError) return { error: validationError };
+        log('tool:openspec_get_change', { changeId });
+        return manager.getChange(changeId);
+    })
+);
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+    log('Starting openspec MCP...');
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    log('openspec MCP connected and ready');
+}
+
+async function shutdown(signal) {
+    log('mcp:shutdown', { signal });
+    try {
+        await server.close();
+    } catch (err) {
+        log('mcp:shutdown:error', { error: err.message });
+    }
+    process.exit(0);
+}
+
+process.on('SIGINT', () => shutdown('SIGINT'));
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('uncaughtException', (error) => {
+    log('mcp:uncaughtException', { error: error.message, stack: error.stack });
+    shutdown('uncaughtException');
+});
+
+const isDirectRun =
+    process.argv[1] && (process.argv[1].endsWith('/index.js') || process.argv[1].endsWith('\\index.js'));
+
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error('Fatal error:', error);
+        process.exit(1);
+    });
+}
+
+export { OpenSpecManager };