@fission-ai/openspec 0.8.0 → 0.9.0

package/README.md

@@ -15,7 +15,7 @@
   <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@fission-ai/openspec?style=flat-square" /></a>
   <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
   <a href="https://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
-  <a href="https://discord.gg/saTQQGQZ"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
+  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
 </p>
 
 <p align="center">
@@ -23,7 +23,7 @@
 </p>
 
 <p align="center">
-  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/saTQQGQZ">OpenSpec Discord</a> for help and questions.
+  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
 </p>
 
 # OpenSpec
@@ -40,6 +40,15 @@ Key outcomes:
 - Shared visibility into what's proposed, active, or archived.
 - Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else.
 
+## How OpenSpec compares (at a glance)
+
+- **Lightweight**: simple workflow, no API keys, minimal setup.
+- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
+- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
+- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
+
+See the full comparison in [How OpenSpec Compares](#how-openspec-compares).
+
 ## How It Works
 
 ```
@@ -86,6 +95,8 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 | **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) |
 | **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) |
+| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
+| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) |
 
 Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`.
 
@@ -94,7 +105,7 @@ These tools automatically read workflow instructions from `openspec/AGENTS.md`.
 
 | Tools |
 |-------|
-| Codex • Amp • Jules • Gemini CLI • GitHub Copilot • Others |
+| Amp • Jules • Gemini CLI • Others |
 
 ### Install & Initialize
 
@@ -198,7 +209,7 @@ Or run the command yourself in terminal:
 $ openspec archive add-profile-filters --yes  # Archive the completed change without prompts
 ```
 
-**Note:** Tools with native slash commands (Claude Code, Cursor) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
+**Note:** Tools with native slash commands (Claude Code, Cursor, Codex) can use the shortcuts shown. All other tools work with natural language requests to "create an OpenSpec proposal", "apply the OpenSpec change", or "archive the change".
 
 ## Command Reference
 
@@ -296,6 +307,9 @@ Deltas are "patches" that show how specs change:
 
 ## How OpenSpec Compares
 
+### vs. spec-kit
+OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features.
+
 ### vs. Kiro.dev
 OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder.
 

package/dist/core/config.js

@@ -9,6 +9,8 @@ export const AI_TOOLS = [
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode' },
     { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code' },
     { name: 'Windsurf', value: 'windsurf', available: true, successLabel: 'Windsurf' },
-    { name: 'AGENTS.md (works with Codex, Amp, VS Code, GitHub Copilot, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
+    { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex' },
+    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot' },
+    { name: 'AGENTS.md (works with Amp, VS Code, …)', value: 'agents', available: false, successLabel: 'your AGENTS.md-compatible assistant' }
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/configurators/slash/base.d.ts

@@ -12,6 +12,7 @@ export declare abstract class SlashCommandConfigurator {
     updateExisting(projectPath: string, _openspecDir: string): Promise<string[]>;
     protected abstract getRelativePath(id: SlashCommandId): string;
     protected abstract getFrontmatter(id: SlashCommandId): string | undefined;
-    private updateBody;
+    resolveAbsolutePath(projectPath: string, id: SlashCommandId): string;
+    protected updateBody(filePath: string, body: string): Promise<void>;
 }
 //# sourceMappingURL=base.d.ts.map

package/dist/core/configurators/slash/base.js

@@ -45,6 +45,12 @@ export class SlashCommandConfigurator {
         }
         return updated;
     }
+    // Resolve absolute path for a given slash command target. Subclasses may override
+    // to redirect to tool-specific locations (e.g., global directories).
+    resolveAbsolutePath(projectPath, id) {
+        const rel = this.getRelativePath(id);
+        return path.join(projectPath, rel);
+    }
     async updateBody(filePath, body) {
         const content = await FileSystemUtils.readFile(filePath);
         const startIndex = content.indexOf(OPENSPEC_MARKERS.start);

package/dist/core/configurators/slash/codex.d.ts

@@ -0,0 +1,14 @@
+import { SlashCommandConfigurator } from "./base.js";
+import { SlashCommandId } from "../../templates/index.js";
+export declare class CodexSlashCommandConfigurator extends SlashCommandConfigurator {
+    readonly toolId = "codex";
+    readonly isAvailable = true;
+    protected getRelativePath(id: SlashCommandId): string;
+    protected getFrontmatter(id: SlashCommandId): string | undefined;
+    private getGlobalPromptsDir;
+    generateAll(projectPath: string, _openspecDir: string): Promise<string[]>;
+    updateExisting(projectPath: string, _openspecDir: string): Promise<string[]>;
+    private updateFullFile;
+    resolveAbsolutePath(_projectPath: string, id: SlashCommandId): string;
+}
+//# sourceMappingURL=codex.d.ts.map

package/dist/core/configurators/slash/codex.js

@@ -0,0 +1,108 @@
+import path from "path";
+import os from "os";
+import { SlashCommandConfigurator } from "./base.js";
+import { TemplateManager } from "../../templates/index.js";
+import { FileSystemUtils } from "../../../utils/file-system.js";
+import { OPENSPEC_MARKERS } from "../../config.js";
+const FILE_PATHS = {
+    proposal: ".codex/prompts/openspec-proposal.md",
+    apply: ".codex/prompts/openspec-apply.md",
+    archive: ".codex/prompts/openspec-archive.md",
+};
+export class CodexSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = "codex";
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(id) {
+        // Codex supports YAML frontmatter with description and argument-hint fields,
+        // plus $ARGUMENTS to capture all arguments as a single string.
+        const frontmatter = {
+            proposal: `---
+description: Scaffold a new OpenSpec change and validate strictly.
+argument-hint: request or feature description
+---
+
+$ARGUMENTS`,
+            apply: `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+argument-hint: change-id
+---
+
+$ARGUMENTS`,
+            archive: `---
+description: Archive a deployed OpenSpec change and update specs.
+argument-hint: change-id
+---
+
+$ARGUMENTS`,
+        };
+        return frontmatter[id];
+    }
+    getGlobalPromptsDir() {
+        const home = (process.env.CODEX_HOME && process.env.CODEX_HOME.trim())
+            ? process.env.CODEX_HOME.trim()
+            : path.join(os.homedir(), ".codex");
+        return path.join(home, "prompts");
+    }
+    // Codex discovers prompts globally. Generate directly in the global directory
+    // and wrap shared body with markers.
+    async generateAll(projectPath, _openspecDir) {
+        const createdOrUpdated = [];
+        for (const target of this.getTargets()) {
+            const body = TemplateManager.getSlashCommandBody(target.id).trim();
+            const promptsDir = this.getGlobalPromptsDir();
+            const filePath = path.join(promptsDir, path.basename(target.path));
+            await FileSystemUtils.createDirectory(path.dirname(filePath));
+            if (await FileSystemUtils.fileExists(filePath)) {
+                await this.updateFullFile(filePath, target.id, body);
+            }
+            else {
+                const frontmatter = this.getFrontmatter(target.id);
+                const sections = [];
+                if (frontmatter)
+                    sections.push(frontmatter.trim());
+                sections.push(`${OPENSPEC_MARKERS.start}\n${body}\n${OPENSPEC_MARKERS.end}`);
+                await FileSystemUtils.writeFile(filePath, sections.join("\n") + "\n");
+            }
+            createdOrUpdated.push(target.path);
+        }
+        return createdOrUpdated;
+    }
+    async updateExisting(projectPath, _openspecDir) {
+        const updated = [];
+        for (const target of this.getTargets()) {
+            const promptsDir = this.getGlobalPromptsDir();
+            const filePath = path.join(promptsDir, path.basename(target.path));
+            if (await FileSystemUtils.fileExists(filePath)) {
+                const body = TemplateManager.getSlashCommandBody(target.id).trim();
+                await this.updateFullFile(filePath, target.id, body);
+                updated.push(target.path);
+            }
+        }
+        return updated;
+    }
+    // Update both frontmatter and body in an existing file
+    async updateFullFile(filePath, id, body) {
+        const content = await FileSystemUtils.readFile(filePath);
+        const startIndex = content.indexOf(OPENSPEC_MARKERS.start);
+        if (startIndex === -1) {
+            throw new Error(`Missing OpenSpec start marker in ${filePath}`);
+        }
+        // Replace everything before the start marker with the new frontmatter
+        const frontmatter = this.getFrontmatter(id);
+        const sections = [];
+        if (frontmatter)
+            sections.push(frontmatter.trim());
+        sections.push(`${OPENSPEC_MARKERS.start}\n${body}\n${OPENSPEC_MARKERS.end}`);
+        await FileSystemUtils.writeFile(filePath, sections.join("\n") + "\n");
+    }
+    // Resolve to the global prompts location for configuration detection
+    resolveAbsolutePath(_projectPath, id) {
+        const promptsDir = this.getGlobalPromptsDir();
+        const fileName = path.basename(FILE_PATHS[id]);
+        return path.join(promptsDir, fileName);
+    }
+}
+//# sourceMappingURL=codex.js.map

package/dist/core/configurators/slash/github-copilot.d.ts

@@ -0,0 +1,9 @@
+import { SlashCommandConfigurator } from './base.js';
+import { SlashCommandId } from '../../templates/index.js';
+export declare class GitHubCopilotSlashCommandConfigurator extends SlashCommandConfigurator {
+    readonly toolId = "github-copilot";
+    readonly isAvailable = true;
+    protected getRelativePath(id: SlashCommandId): string;
+    protected getFrontmatter(id: SlashCommandId): string;
+}
+//# sourceMappingURL=github-copilot.d.ts.map

package/dist/core/configurators/slash/github-copilot.js

@@ -0,0 +1,34 @@
+import { SlashCommandConfigurator } from './base.js';
+const FILE_PATHS = {
+    proposal: '.github/prompts/openspec-proposal.prompt.md',
+    apply: '.github/prompts/openspec-apply.prompt.md',
+    archive: '.github/prompts/openspec-archive.prompt.md'
+};
+const FRONTMATTER = {
+    proposal: `---
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+
+$ARGUMENTS`,
+    apply: `---
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---
+
+$ARGUMENTS`,
+    archive: `---
+description: Archive a deployed OpenSpec change and update specs.
+---
+
+$ARGUMENTS`
+};
+export class GitHubCopilotSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = 'github-copilot';
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=github-copilot.js.map

package/dist/core/configurators/slash/registry.js

@@ -3,6 +3,8 @@ import { CursorSlashCommandConfigurator } from './cursor.js';
 import { WindsurfSlashCommandConfigurator } from './windsurf.js';
 import { KiloCodeSlashCommandConfigurator } from './kilocode.js';
 import { OpenCodeSlashCommandConfigurator } from './opencode.js';
+import { CodexSlashCommandConfigurator } from './codex.js';
+import { GitHubCopilotSlashCommandConfigurator } from './github-copilot.js';
 export class SlashCommandRegistry {
     static configurators = new Map();
     static {
@@ -11,11 +13,15 @@ export class SlashCommandRegistry {
         const windsurf = new WindsurfSlashCommandConfigurator();
         const kilocode = new KiloCodeSlashCommandConfigurator();
         const opencode = new OpenCodeSlashCommandConfigurator();
+        const codex = new CodexSlashCommandConfigurator();
+        const githubCopilot = new GitHubCopilotSlashCommandConfigurator();
         this.configurators.set(claude.toolId, claude);
         this.configurators.set(cursor.toolId, cursor);
         this.configurators.set(windsurf.toolId, windsurf);
         this.configurators.set(kilocode.toolId, kilocode);
         this.configurators.set(opencode.toolId, opencode);
+        this.configurators.set(codex.toolId, codex);
+        this.configurators.set(githubCopilot.toolId, githubCopilot);
     }
     static register(configurator) {
         this.configurators.set(configurator.toolId, configurator);

package/dist/core/init.js

@@ -331,7 +331,7 @@ export class InitCommand {
                 kind: 'heading',
                 value: OTHER_TOOLS_HEADING_VALUE,
                 label: {
-                    primary: 'Other tools (use Universal AGENTS.md for Codex, Amp, VS Code, GitHub Copilot, …)',
+                    primary: 'Other tools (use Universal AGENTS.md for Amp, VS Code, GitHub Copilot, …)',
                 },
                 selectable: false,
             },
@@ -369,7 +369,8 @@ export class InitCommand {
         if (!slashConfigurator)
             return false;
         for (const target of slashConfigurator.getTargets()) {
-            if (await FileSystemUtils.fileExists(path.join(projectPath, target.path)))
+            const absolute = slashConfigurator.resolveAbsolutePath(projectPath, target.id);
+            if (await FileSystemUtils.fileExists(absolute))
                 return true;
         }
         return false;
@@ -470,6 +471,13 @@ export class InitCommand {
         console.log(PALETTE.lightGray('   "Please explain the OpenSpec workflow from openspec/AGENTS.md'));
         console.log(PALETTE.lightGray('    and how I should work with you on this project"'));
         console.log(PALETTE.darkGray('────────────────────────────────────────────────────────────\n'));
+        // Codex heads-up: prompts installed globally
+        const selectedToolIds = new Set(selectedTools.map((t) => t.value));
+        if (selectedToolIds.has('codex')) {
+            console.log(PALETTE.white('Codex setup note'));
+            console.log(PALETTE.midGray('Prompts installed to ~/.codex/prompts (or $CODEX_HOME/prompts).'));
+            console.log();
+        }
     }
     formatToolNames(tools) {
         const names = tools

package/dist/core/update.js

@@ -80,6 +80,7 @@ export class UpdateCommand {
             summaryParts.push(`Failed to update: ${failedItems.join(', ')}`);
         }
         console.log(summaryParts.join(' | '));
+        // No additional notes
     }
 }
 //# sourceMappingURL=update.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -62,7 +62,10 @@
     "test:watch": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
-    "release": "pnpm run build && pnpm exec changeset publish",
+    "check:pack-version": "node scripts/pack-version-check.mjs",
+    "release": "pnpm run release:ci",
+    "release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
+    "release:local": "pnpm exec changeset version && pnpm run check:pack-version && pnpm exec changeset publish",
     "changeset": "changeset"
   }
 }