@fission-ai/openspec 0.2.0 → 0.4.0

package/README.md

@@ -15,6 +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/discord/1411657095639601154?logo=discord&logoColor=white&style=flat-square" /></a>
 </p>
 
 <p align="center">
@@ -22,134 +23,187 @@
 </p>
 
 <p align="center">
-  Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates.
+  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.
 </p>
 
 # OpenSpec
 
-**Supported AI Tools:** ✅ Claude Code | 🔜 Cursor (coming soon) | ✅ AGENTS.md instructions
-
-Create **alignment** between humans and AI coding assistants through spec-driven development. **No API keys required.**
-
-OpenSpec ensures you and your AI assistant agree on what to build before any code is written. By discussing and refining specifications first, you bring determinism to AI code generation, getting exactly what you want, not what the AI thinks you might want.
+OpenSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
 
 ## Why OpenSpec?
 
-**The Problem:** AI coding assistants are powerful but unpredictable. Without clear specifications, they generate code based on assumptions, often missing requirements or adding unwanted features. Teams waste time in review cycles because humans and AI aren't aligned on what to build.
+AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs.
 
-**The Solution:** OpenSpec creates alignment BEFORE code is written:
-- **Human-AI Alignment** - You and your AI agree on specifications before implementation
-- **Deterministic, Predictable Output** - Clear specs lead to reliable, repeatable code generation
-- **Team Alignment via Spec Reviews** - Everyone reviews intentions, not code surprises
-- **Clear Feature Scope** - Know exactly what you're building—and what you're not
-- **Progress Tracking** - See what's proposed, in progress, or completed at a glance
-- **Living Documentation** - Specs evolve with your code as a natural byproduct
-- **Universal Tool Support** - Works with any AI assistant (Claude Code, Cursor, and more)
-- **No API Keys Required** - Integrates through context rules, not external services
+Key outcomes:
+- Human and AI stakeholders agree on specs before work begins.
+- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
+- 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 It Works
 
 ```
-┌─────────────┐       ┌─────────────┐       ┌──────────────┐
-│    SPECS    │       │   CHANGES   │       │   ARCHIVE    │
-│   (Truth)   │◀──────│ (Proposals) │──────▶│ (Completed)  │
-└─────────────┘       └─────────────┘       └──────────────┘
-      ▲                      │                      │
-      │                      ▼                      │
-      │               ┌─────────────┐               │
-      └───────────────│    CODE     │◀──────────────┘
-                      └─────────────┘
-
-1. SPECS define current capabilities (what IS built)
-2. CHANGES propose modifications using deltas (what SHOULD change)  
-3. CODE implements the changes following tasks
-4. ARCHIVE preserves completed changes after deployment
+┌────────────────────┐
+│ Draft Change       │
+│ Proposal           │
+└────────┬───────────┘
+         │ share intent with your AI
+         ▼
+┌────────────────────┐
+│ Review & Align     │
+│ (edit specs/tasks) │◀──── feedback loop ──────┐
+└────────┬───────────┘                          │
+         │ approved plan                        │
+         ▼                                      │
+┌────────────────────┐                          │
+│ Implement Tasks    │──────────────────────────┘
+│ (AI writes code)   │
+└────────┬───────────┘
+         │ ship the change
+         ▼
+┌────────────────────┐
+│ Archive & Update   │
+│ Specs (source)     │
+└────────────────────┘
+
+1. Draft a change proposal that captures the spec updates you want.
+2. Review the proposal with your AI assistant until everyone agrees.
+3. Implement tasks that reference the agreed specs.
+4. Archive the change to merge the approved updates back into the source-of-truth specs.
 ```
 
-## Installation
+## Getting Started
+
+### Supported AI Tools
+
+#### Native Slash Commands
+These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted.
 
-### Prerequisites
+| Tool | Commands |
+|------|----------|
+| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
+| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
 
-- Node.js >= 20.19.0
+#### AGENTS.md Compatible
+These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
 
-### Install OpenSpec
+| Tools |
+|-------|
+| Codex • Amp • Jules • Gemini CLI • GitHub Copilot • Others |
 
-Install globally:
+### Install & Initialize
+
+#### Prerequisites
+- **Node.js >= 20.19.0** - Check your version with `node --version`
+
+#### Step 1: Install the CLI globally
 
 ```bash
-npm install -g @fission-ai/openspec
+npm install -g @fission-ai/openspec@latest
 ```
 
-## Getting Started
+Verify installation:
+```bash
+openspec --version
+```
 
-### 1. Initialize OpenSpec in Your Project
+#### Step 2: Initialize OpenSpec in your project
 
+Navigate to your project directory:
 ```bash
-# Navigate to your project
 cd my-project
+```
 
-# Initialize OpenSpec
+Run the initialization:
+```bash
 openspec init
+```
 
-# Select your AI tool (more coming soon!):
-# "Which AI tool do you use?"
-#   > Claude Code
-#     Cursor (coming soon)
+**What happens during initialization:**
+- You'll be prompted to select your AI tool (Claude Code, Cursor, etc.)
+- OpenSpec automatically configures slash commands or `AGENTS.md` based on your selection
+- A new `openspec/` directory structure is created in your project
 
-# This creates:
-# openspec/
-#   ├── specs/       # Current specifications (truth)
-#   ├── changes/     # Proposed changes
-#   └── AGENTS.md    # AI instructions for your tool
-```
+**After setup:**
+- Primary AI tools can trigger `/openspec` workflows without additional configuration
+- Run `openspec list` to verify the setup and view any active changes
 
-### 2. Create Your First Change
+### Create Your First Change
 
-Jump straight into creating a change proposal with your AI assistant (works with Claude Code, Cursor, or any AI tool):
+Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically.
 
-```markdown
-// Quick win - Add a simple new feature:
-You: "I want to add a user profile API endpoint.
-      Please create an OpenSpec change proposal for this."
-
-AI: "I'll create an OpenSpec change proposal for the user profile API..."
-    *Creates openspec/changes/add-user-profile-api/ with:*
-    - proposal.md (why this feature is needed)
-    - tasks.md (implementation checklist)
-    - design.md (API design decisions)
-    - specs/user-profile/spec.md (new requirements)
-
-You: "The proposal looks good. Let's implement it."
-
-AI: "Following the tasks in openspec/changes/add-user-profile-api/tasks.md:
-     Task 1.1: Create user profile model..."
-    *Implements each task systematically*
+#### 1. Draft the Proposal
+Start by asking your AI to create a change proposal:
+
+```text
+You: Create an OpenSpec change proposal for adding profile search filters by role and team
+     (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters)
+
+AI:  I'll create an OpenSpec change proposal for profile filters.
+     *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.*
 ```
 
-### 3. Track Your Work
+#### 2. Verify & Review
+Check that the change was created correctly and review the proposal:
 
 ```bash
-# View active changes (what's being worked on)
-openspec list
+$ openspec list                             # Confirm the change folder exists
+$ openspec validate add-profile-filters     # Validate spec formatting
+$ openspec show add-profile-filters         # Review proposal, tasks, and spec delta
+```
+
+#### 3. Refine the Specs
+Iterate on the specifications until they match your needs:
 
-# Validate your changes are properly formatted
-openspec validate add-2fa --strict
+```text
+You: Can you add acceptance criteria for the role and team filters?
 
-# After deployment, archive the completed change
-openspec archive add-2fa
-# This moves the change to archive/ and updates specs/
+AI:  I'll update the spec delta with scenarios for role and team filters.
+     *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.*
 ```
 
-## Common Commands
+#### 4. Implement the Change
+Once specs look good, start implementation:
 
+```text
+You: The specs look good. Let's implement this change.
+     (Shortcut for tools with slash commands: /openspec:apply add-profile-filters)
+
+AI:  I'll work through the tasks in the add-profile-filters change.
+     *Implements tasks from openspec/changes/add-profile-filters/tasks.md*
+     *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...*
+```
+
+#### 5. Archive the Completed Change
+After implementation is complete, archive the change:
+
+```text
+AI:  All tasks are complete. The implementation is ready.
+
+You: Please archive the change
+     (Shortcut for tools with slash commands: /openspec:archive add-profile-filters)
+
+AI:  I'll archive the add-profile-filters change.
+     *Runs: openspec archive add-profile-filters*
+     ✓ Change archived successfully. Specs updated. Ready for the next feature!
+```
+
+Or run the command yourself in terminal:
 ```bash
-# Most used:
-openspec list              # See what changes you're working on
-openspec archive <change>  # Mark a change as complete after deployment
+$ openspec archive add-profile-filters  # Archive the completed change
+```
 
-# Also useful:
-openspec validate <change> # Check formatting before committing
-openspec show <change>     # View change details
+**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".
+
+## Command Reference
+
+```bash
+openspec list               # View active change folders
+openspec view               # Interactive dashboard of specs and changes
+openspec show <change>      # Display change details (proposal, tasks, spec updates)
+openspec validate <change>  # Check spec formatting and structure
+openspec archive <change>   # Move a completed change into archive/
 ```
 
 ## Example: How AI Creates OpenSpec Files
@@ -236,46 +290,38 @@ Deltas are "patches" that show how specs change:
 - Every requirement needs at least one `#### Scenario:` block
 - Use SHALL/MUST in requirement text
 
-
-## Why OpenSpec Works
-
-OpenSpec creates **alignment** between you and your AI coding assistant:
-
-1. **You describe** what you want to build
-2. **AI creates specs** before writing any code
-3. **You review and adjust** the specifications
-4. **AI implements** exactly what was specified
-5. **Everyone understands** what's being built through clear specs
-
-**True Interoperability:** OpenSpec is designed to be universal. No API keys, no vendor lock-in. It works by adding context rules to ANY AI coding tool - whether you use Claude Code today, switch to Cursor tomorrow, or adopt the next breakthrough AI assistant. Your specs remain portable and your workflow stays consistent.
-
-
 ## How OpenSpec Compares
 
 ### vs. Kiro.dev
-OpenSpec groups all changes for a feature in one place (`openspec/changes/feature-name/`), making it easy to track what needs to be done. Kiro spreads changes across multiple spec folders, making feature tracking harder.
+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.
 
 ### vs. No Specs
-Without specs, AI coding assistants generate code based on vague prompts, often missing requirements or adding unwanted features. OpenSpec ensures alignment before any code is written.
+Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written.
 
 ## Team Adoption
 
-### Getting Started with Your Team
+1. **Initialize OpenSpec** – Run `openspec init` in your repo.
+2. **Start with new features** – Ask your AI to capture upcoming work as change proposals.
+3. **Grow incrementally** – Each change archives into living specs that document your system.
+4. **Stay flexible** – Different teammates can use Claude Code, Cursor, or any AGENTS.md-compatible tool while sharing the same specs.
 
-1. **Initialize OpenSpec** - Run `openspec init` in your project
-2. **Start with new features** - Use OpenSpec for your next change proposal
-3. **Build incrementally** - Each new feature adds to your spec library
-4. **Future capability** - We're working on tools to generate specs from existing code
+Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings.
 
-**Tool Freedom:** Your team can use different AI assistants. One developer might use Claude Code while another uses Cursor - OpenSpec keeps everyone aligned through shared specifications. Run `openspec update` to configure for any supported tool without affecting others.
+## Updating OpenSpec
 
+1. **Upgrade the package**
+   ```bash
+   npm install -g @fission-ai/openspec@latest
+   ```
+2. **Refresh agent instructions**
+   - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
 
 ## Contributing
 
-- Install dependencies: `npm install`
-- Build: `npm run build`
-- Test: `npm test`
-- Develop CLI locally: `npm run dev` or `npm run dev:cli`
+- Install dependencies: `pnpm install`
+- Build: `pnpm run build`
+- Test: `pnpm test`
+- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
 - Conventional commits (one-line): `type(scope): subject`
 
 ## License

package/dist/core/config.d.ts

@@ -1,14 +1,16 @@
 export declare const OPENSPEC_DIR_NAME = "openspec";
-export interface OpenSpecConfig {
-    aiTools: string[];
-}
 export declare const OPENSPEC_MARKERS: {
     start: string;
     end: string;
 };
-export declare const AI_TOOLS: {
+export interface OpenSpecConfig {
+    aiTools: string[];
+}
+export interface AIToolOption {
     name: string;
     value: string;
     available: boolean;
-}[];
+    successLabel?: string;
+}
+export declare const AI_TOOLS: AIToolOption[];
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -4,9 +4,9 @@ export const OPENSPEC_MARKERS = {
     end: '<!-- OPENSPEC:END -->'
 };
 export const AI_TOOLS = [
-    { name: 'Claude Code', value: 'claude', available: true },
-    { name: 'Cursor', value: 'cursor', available: true },
-    { name: 'Aider', value: 'aider', available: false },
-    { name: 'Continue', value: 'continue', available: false }
+    { name: 'Claude Code (✅ OpenSpec custom slash commands available)', value: 'claude', available: true, successLabel: 'Claude Code' },
+    { name: 'Cursor (✅ OpenSpec custom slash commands available)', value: 'cursor', available: true, successLabel: 'Cursor' },
+    { name: 'OpenCode (✅ OpenSpec custom slash commands available)', value: 'opencode', available: true, successLabel: 'OpenCode' },
+    { name: 'AGENTS.md (works with Codex, Amp, Copilot, …)', value: 'agents', available: true, successLabel: 'your AGENTS.md-compatible assistant' }
 ];
 //# sourceMappingURL=config.js.map

package/dist/core/configurators/agents.d.ts

@@ -0,0 +1,8 @@
+import { ToolConfigurator } from './base.js';
+export declare class AgentsStandardConfigurator implements ToolConfigurator {
+    name: string;
+    configFileName: string;
+    isAvailable: boolean;
+    configure(projectPath: string, _openspecDir: string): Promise<void>;
+}
+//# sourceMappingURL=agents.d.ts.map

package/dist/core/configurators/agents.js

@@ -0,0 +1,15 @@
+import path from 'path';
+import { FileSystemUtils } from '../../utils/file-system.js';
+import { TemplateManager } from '../templates/index.js';
+import { OPENSPEC_MARKERS } from '../config.js';
+export class AgentsStandardConfigurator {
+    name = 'AGENTS.md standard';
+    configFileName = 'AGENTS.md';
+    isAvailable = true;
+    async configure(projectPath, _openspecDir) {
+        const filePath = path.join(projectPath, this.configFileName);
+        const content = TemplateManager.getAgentsStandardTemplate();
+        await FileSystemUtils.updateFileWithMarkers(filePath, content, OPENSPEC_MARKERS.start, OPENSPEC_MARKERS.end);
+    }
+}
+//# sourceMappingURL=agents.js.map

package/dist/core/configurators/registry.js

@@ -1,10 +1,13 @@
 import { ClaudeConfigurator } from './claude.js';
+import { AgentsStandardConfigurator } from './agents.js';
 export class ToolRegistry {
     static tools = new Map();
     static {
         const claudeConfigurator = new ClaudeConfigurator();
+        const agentsConfigurator = new AgentsStandardConfigurator();
         // Register with the ID that matches the checkbox value
         this.tools.set('claude', claudeConfigurator);
+        this.tools.set('agents', agentsConfigurator);
     }
     static register(tool) {
         this.tools.set(tool.name.toLowerCase().replace(/\s+/g, '-'), tool);

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

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

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

@@ -0,0 +1,36 @@
+import { SlashCommandConfigurator } from "./base.js";
+const FILE_PATHS = {
+    proposal: ".opencode/command/openspec-proposal.md",
+    apply: ".opencode/command/openspec-apply.md",
+    archive: ".opencode/command/openspec-archive.md",
+};
+const FRONTMATTER = {
+    proposal: `---
+agent: build
+description: Scaffold a new OpenSpec change and validate strictly.
+---
+The user has requested the following change proposal. Use the openspec instructions to create their change proposal.
+<UserRequest>
+  $ARGUMENTS
+</UserRequest>
+`,
+    apply: `---
+agent: build
+description: Implement an approved OpenSpec change and keep tasks in sync.
+---`,
+    archive: `---
+agent: build
+description: Archive a deployed OpenSpec change and update specs.
+---`,
+};
+export class OpenCodeSlashCommandConfigurator extends SlashCommandConfigurator {
+    toolId = "opencode";
+    isAvailable = true;
+    getRelativePath(id) {
+        return FILE_PATHS[id];
+    }
+    getFrontmatter(id) {
+        return FRONTMATTER[id];
+    }
+}
+//# sourceMappingURL=opencode.js.map

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

@@ -1,12 +1,15 @@
 import { ClaudeSlashCommandConfigurator } from './claude.js';
 import { CursorSlashCommandConfigurator } from './cursor.js';
+import { OpenCodeSlashCommandConfigurator } from './opencode.js';
 export class SlashCommandRegistry {
     static configurators = new Map();
     static {
         const claude = new ClaudeSlashCommandConfigurator();
         const cursor = new CursorSlashCommandConfigurator();
+        const opencode = new OpenCodeSlashCommandConfigurator();
         this.configurators.set(claude.toolId, claude);
         this.configurators.set(cursor.toolId, cursor);
+        this.configurators.set(opencode.toolId, opencode);
     }
     static register(configurator) {
         this.configurators.set(configurator.toolId, configurator);

package/dist/core/init.d.ts

@@ -1,10 +1,38 @@
+type ToolLabel = {
+    primary: string;
+    annotation?: string;
+};
+type ToolWizardChoice = {
+    value: string;
+    label: ToolLabel;
+    configured: boolean;
+};
+type ToolWizardConfig = {
+    extendMode: boolean;
+    baseMessage: string;
+    choices: ToolWizardChoice[];
+    initialSelected?: string[];
+};
+type ToolSelectionPrompt = (config: ToolWizardConfig) => Promise<string[]>;
+type InitCommandOptions = {
+    prompt?: ToolSelectionPrompt;
+};
 export declare class InitCommand {
+    private readonly prompt;
+    constructor(options?: InitCommandOptions);
     execute(targetPath: string): Promise<void>;
     private validate;
     private getConfiguration;
+    private promptForAITools;
+    private getExistingToolStates;
+    private isToolConfigured;
     private createDirectoryStructure;
     private generateFiles;
     private configureAITools;
     private displaySuccessMessage;
+    private formatToolNames;
+    private renderBanner;
+    private startSpinner;
 }
+export {};
 //# sourceMappingURL=init.d.ts.map