@fission-ai/openspec 0.18.0 → 0.19.0

package/README.md

@@ -26,6 +26,10 @@
   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>
 
+<p align="center">
+  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
+</p>
+
 # OpenSpec
 
 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.**
@@ -99,6 +103,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) |
 | **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) |
 | **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) |
+| **Continue** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.continue/prompts/`) |
 | **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)|
 | **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) |
 | **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
@@ -368,6 +373,53 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 2. **Refresh agent instructions**
    - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
 
+## Experimental Features
+
+<details>
+<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
+
+**Why this exists:**
+- Standard workflow is locked down — you can't tweak instructions or customize
+- When AI output is bad, you can't improve the prompts yourself
+- Same workflow for everyone, no way to match how your team works
+
+**What's different:**
+- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild
+- **Granular** — each artifact has its own instructions, test and tweak individually
+- **Customizable** — define your own workflows, artifacts, and dependencies
+- **Fluid** — no phase gates, update any artifact anytime
+
+```
+You can always go back:
+
+  proposal ──→ specs ──→ design ──→ tasks ──→ implement
+     ▲           ▲          ▲                    │
+     └───────────┴──────────┴────────────────────┘
+```
+
+| Command | What it does |
+|---------|--------------|
+| `/opsx:new` | Start a new change |
+| `/opsx:continue` | Create the next artifact (based on what's ready) |
+| `/opsx:ff` | Fast-forward (all planning artifacts at once) |
+| `/opsx:apply` | Implement tasks, updating artifacts as needed |
+| `/opsx:archive` | Archive when done |
+
+**Setup:** `openspec artifact-experimental-setup`
+
+[Full documentation →](docs/experimental-workflow.md)
+
+</details>
+
+<details>
+<summary><strong>Telemetry</strong> – OpenSpec collects anonymous usage stats (opt-out: <code>OPENSPEC_TELEMETRY=0</code>)</summary>
+
+We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI.
+
+**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1`
+
+</details>
+
 ## Contributing
 
 - Install dependencies: `pnpm install`

package/dist/cli/index.js

@@ -15,21 +15,51 @@ import { ShowCommand } from '../commands/show.js';
 import { CompletionCommand } from '../commands/completion.js';
 import { registerConfigCommand } from '../commands/config.js';
 import { registerArtifactWorkflowCommands } from '../commands/artifact-workflow.js';
+import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
+/**
+ * Get the full command path for nested commands.
+ * For example: 'change show' -> 'change:show'
+ */
+function getCommandPath(command) {
+    const names = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        // Skip the root 'openspec' command
+        if (name && name !== 'openspec') {
+            names.unshift(name);
+        }
+        current = current.parent;
+    }
+    return names.join(':') || 'openspec';
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
     .version(version);
 // Global options
 program.option('--no-color', 'Disable color output');
-// Apply global flags before any command runs
-program.hook('preAction', (thisCommand) => {
+// Apply global flags and telemetry before any command runs
+// Note: preAction receives (thisCommand, actionCommand) where:
+// - thisCommand: the command where hook was added (root program)
+// - actionCommand: the command actually being executed (subcommand)
+program.hook('preAction', async (thisCommand, actionCommand) => {
     const opts = thisCommand.opts();
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
+    // Show first-run telemetry notice (if not seen)
+    await maybeShowTelemetryNotice();
+    // Track command execution (use actionCommand to get the actual subcommand)
+    const commandPath = getCommandPath(actionCommand);
+    await trackCommand(commandPath, version);
+});
+// Shutdown telemetry after command completes
+program.hook('postAction', async () => {
+    await shutdown();
 });
 const availableToolIds = AI_TOOLS.filter((tool) => tool.available).map((tool) => tool.value);
 const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;

package/dist/commands/artifact-workflow.js

@@ -14,7 +14,7 @@ import path from 'path';
 import * as fs from 'fs';
 import { loadChangeContext, formatChangeStatus, generateInstructions, listSchemas, listSchemasWithInfo, getSchemaDir, resolveSchema, ArtifactGraph, } from '../core/artifact-graph/index.js';
 import { createChange, validateChangeName } from '../utils/change-utils.js';
-import { getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate } from '../core/templates/skill-templates.js';
+import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate } from '../core/templates/skill-templates.js';
 import { FileSystemUtils } from '../utils/file-system.js';
 const DEFAULT_SCHEMA = 'spec-driven';
 /**
@@ -580,6 +580,7 @@ async function artifactExperimentalSetupCommand() {
         const skillsDir = path.join(projectRoot, '.claude', 'skills');
         const commandsDir = path.join(projectRoot, '.claude', 'commands', 'opsx');
         // Get skill templates
+        const exploreSkill = getExploreSkillTemplate();
         const newChangeSkill = getNewChangeSkillTemplate();
         const continueChangeSkill = getContinueChangeSkillTemplate();
         const applyChangeSkill = getApplyChangeSkillTemplate();
@@ -587,6 +588,7 @@ async function artifactExperimentalSetupCommand() {
         const syncSpecsSkill = getSyncSpecsSkillTemplate();
         const archiveChangeSkill = getArchiveChangeSkillTemplate();
         // Get command templates
+        const exploreCommand = getOpsxExploreCommandTemplate();
         const newCommand = getOpsxNewCommandTemplate();
         const continueCommand = getOpsxContinueCommandTemplate();
         const applyCommand = getOpsxApplyCommandTemplate();
@@ -595,6 +597,7 @@ async function artifactExperimentalSetupCommand() {
         const archiveCommand = getOpsxArchiveCommandTemplate();
         // Create skill directories and SKILL.md files
         const skills = [
+            { template: exploreSkill, dirName: 'openspec-explore' },
             { template: newChangeSkill, dirName: 'openspec-new-change' },
             { template: continueChangeSkill, dirName: 'openspec-continue-change' },
             { template: applyChangeSkill, dirName: 'openspec-apply-change' },
@@ -620,6 +623,7 @@ ${template.instructions}
         }
         // Create slash command files
         const commands = [
+            { template: exploreCommand, fileName: 'explore.md' },
             { template: newCommand, fileName: 'new.md' },
             { template: continueCommand, fileName: 'continue.md' },
             { template: applyCommand, fileName: 'apply.md' },
@@ -672,6 +676,7 @@ ${template.content}
         console.log('  • "Implement the tasks for this change"');
         console.log();
         console.log('  ' + chalk.cyan('Slash Commands') + ' for explicit invocation:');
+        console.log('  • /opsx:explore - Think through ideas, investigate problems');
         console.log('  • /opsx:new - Start a new change');
         console.log('  • /opsx:continue - Create the next artifact');
         console.log('  • /opsx:apply - Implement tasks');

package/dist/commands/completion.js

@@ -107,8 +107,24 @@ export class CompletionCommand {
                     if (result.backupPath) {
                         console.log(`  Backup created: ${result.backupPath}`);
                     }
-                    if (result.zshrcConfigured) {
-                        console.log(`  ~/.zshrc configured automatically`);
+                    // Check if any shell config was updated
+                    const configWasUpdated = result.zshrcConfigured || result.bashrcConfigured || result.profileConfigured;
+                    if (configWasUpdated) {
+                        const configPaths = {
+                            zsh: '~/.zshrc',
+                            bash: '~/.bashrc',
+                            fish: '~/.config/fish/config.fish',
+                            powershell: '$PROFILE',
+                        };
+                        const configPath = configPaths[shell] || 'config file';
+                        console.log(`  ${configPath} configured automatically`);
+                    }
+                }
+                // Display warnings if present
+                if (result.warnings && result.warnings.length > 0) {
+                    console.log('');
+                    for (const warning of result.warnings) {
+                        console.log(warning);
                     }
                 }
                 // Print instructions (only shown if .zshrc wasn't auto-configured)
@@ -118,9 +134,21 @@ export class CompletionCommand {
                         console.log(instruction);
                     }
                 }
-                else if (result.zshrcConfigured) {
-                    console.log('');
-                    console.log('Restart your shell or run: exec zsh');
+                else {
+                    // Check if any shell config was updated (InstallationResult has: zshrcConfigured, bashrcConfigured, profileConfigured)
+                    const configWasUpdated = result.zshrcConfigured || result.bashrcConfigured || result.profileConfigured;
+                    if (configWasUpdated) {
+                        console.log('');
+                        // Shell-specific reload instructions
+                        const reloadCommands = {
+                            zsh: 'exec zsh',
+                            bash: 'exec bash',
+                            fish: 'exec fish',
+                            powershell: '. $PROFILE',
+                        };
+                        const reloadCmd = reloadCommands[shell] || `restart your ${shell} shell`;
+                        console.log(`Restart your shell or run: ${reloadCmd}`);
+                    }
                 }
             }
             else {
@@ -142,8 +170,16 @@ export class CompletionCommand {
         // Prompt for confirmation unless --yes flag is provided
         if (!skipConfirmation) {
             const { confirm } = await import('@inquirer/prompts');
+            // Get shell-specific config file path
+            const configPaths = {
+                zsh: '~/.zshrc',
+                bash: '~/.bashrc',
+                fish: 'Fish configuration', // Fish doesn't modify profile, just removes script file
+                powershell: '$PROFILE',
+            };
+            const configPath = configPaths[shell] || `${shell} configuration`;
             const confirmed = await confirm({
-                message: 'Remove OpenSpec configuration from ~/.zshrc?',
+                message: `Remove OpenSpec configuration from ${configPath}?`,
                 default: false,
             });
             if (!confirmed) {

package/dist/core/completions/command-registry.js

@@ -281,7 +281,13 @@ export const COMMAND_REGISTRY = [
                 description: 'Uninstall completion script for a shell',
                 acceptsPositional: true,
                 positionalType: 'shell',
-                flags: [],
+                flags: [
+                    {
+                        name: 'yes',
+                        short: 'y',
+                        description: 'Skip confirmation prompts',
+                    },
+                ],
             },
         ],
     },

package/dist/core/completions/factory.d.ts

@@ -1,6 +1,20 @@
 import { CompletionGenerator } from './types.js';
-import { InstallationResult } from './installers/zsh-installer.js';
 import { SupportedShell } from '../../utils/shell-detection.js';
+/**
+ * Common installation result interface
+ */
+export interface InstallationResult {
+    success: boolean;
+    installedPath?: string;
+    backupPath?: string;
+    message: string;
+    instructions?: string[];
+    warnings?: string[];
+    isOhMyZsh?: boolean;
+    zshrcConfigured?: boolean;
+    bashrcConfigured?: boolean;
+    profileConfigured?: boolean;
+}
 /**
  * Interface for completion installers
  */
@@ -11,7 +25,6 @@ export interface CompletionInstaller {
         message: string;
     }>;
 }
-export type { InstallationResult };
 /**
  * Factory for creating completion generators and installers
  * This design makes it easy to add support for additional shells

package/dist/core/completions/factory.js

@@ -1,11 +1,17 @@
 import { ZshGenerator } from './generators/zsh-generator.js';
+import { BashGenerator } from './generators/bash-generator.js';
+import { FishGenerator } from './generators/fish-generator.js';
+import { PowerShellGenerator } from './generators/powershell-generator.js';
 import { ZshInstaller } from './installers/zsh-installer.js';
+import { BashInstaller } from './installers/bash-installer.js';
+import { FishInstaller } from './installers/fish-installer.js';
+import { PowerShellInstaller } from './installers/powershell-installer.js';
 /**
  * Factory for creating completion generators and installers
  * This design makes it easy to add support for additional shells
  */
 export class CompletionFactory {
-    static SUPPORTED_SHELLS = ['zsh'];
+    static SUPPORTED_SHELLS = ['zsh', 'bash', 'fish', 'powershell'];
     /**
      * Create a completion generator for the specified shell
      *
@@ -17,6 +23,12 @@ export class CompletionFactory {
         switch (shell) {
             case 'zsh':
                 return new ZshGenerator();
+            case 'bash':
+                return new BashGenerator();
+            case 'fish':
+                return new FishGenerator();
+            case 'powershell':
+                return new PowerShellGenerator();
             default:
                 throw new Error(`Unsupported shell: ${shell}`);
         }
@@ -32,6 +44,12 @@ export class CompletionFactory {
         switch (shell) {
             case 'zsh':
                 return new ZshInstaller();
+            case 'bash':
+                return new BashInstaller();
+            case 'fish':
+                return new FishInstaller();
+            case 'powershell':
+                return new PowerShellInstaller();
             default:
                 throw new Error(`Unsupported shell: ${shell}`);
         }

package/dist/core/completions/generators/bash-generator.d.ts

@@ -0,0 +1,32 @@
+import { CompletionGenerator, CommandDefinition } from '../types.js';
+/**
+ * Generates Bash completion scripts for the OpenSpec CLI.
+ * Follows Bash completion conventions using complete builtin and COMPREPLY array.
+ */
+export declare class BashGenerator implements CompletionGenerator {
+    readonly shell: "bash";
+    /**
+     * Generate a Bash completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Bash completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+    /**
+     * Generate completion case logic for a command
+     */
+    private generateCommandCase;
+    /**
+     * Generate argument completion (flags and positional arguments)
+     */
+    private generateArgumentCompletion;
+    /**
+     * Generate positional argument completion based on type
+     */
+    private generatePositionalCompletion;
+    /**
+     * Escape command/subcommand names for safe use in Bash scripts
+     */
+    private escapeCommandName;
+}
+//# sourceMappingURL=bash-generator.d.ts.map

package/dist/core/completions/generators/bash-generator.js

@@ -0,0 +1,174 @@
+import { BASH_DYNAMIC_HELPERS } from '../templates/bash-templates.js';
+/**
+ * Generates Bash completion scripts for the OpenSpec CLI.
+ * Follows Bash completion conventions using complete builtin and COMPREPLY array.
+ */
+export class BashGenerator {
+    shell = 'bash';
+    /**
+     * Generate a Bash completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Bash completion script as a string
+     */
+    generate(commands) {
+        // Build command list for top-level completions
+        const commandList = commands.map(c => this.escapeCommandName(c.name)).join(' ');
+        // Build command cases using push() for loop clarity
+        const caseLines = [];
+        for (const cmd of commands) {
+            caseLines.push(`    ${cmd.name})`);
+            caseLines.push(...this.generateCommandCase(cmd, '      '));
+            caseLines.push('      ;;');
+        }
+        const commandCases = caseLines.join('\n');
+        // Dynamic completion helpers from template
+        const helpers = BASH_DYNAMIC_HELPERS;
+        // Assemble final script with template literal
+        return `# Bash completion script for OpenSpec CLI
+# Auto-generated - do not edit manually
+
+_openspec_completion() {
+  local cur prev words cword
+
+  # Use _init_completion if available (from bash-completion package)
+  # The -n : option prevents colons from being treated as word separators
+  # (important for spec/change IDs that may contain colons)
+  # Otherwise, fall back to manual initialization
+  if declare -F _init_completion >/dev/null 2>&1; then
+    _init_completion -n : || return
+  else
+    # Manual fallback when bash-completion is not installed
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    words=("\${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+  fi
+
+  local cmd="\${words[1]}"
+  local subcmd="\${words[2]}"
+
+  # Top-level commands
+  if [[ $cword -eq 1 ]]; then
+    local commands="${commandList}"
+    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
+    return 0
+  fi
+
+  # Command-specific completion
+  case "$cmd" in
+${commandCases}
+  esac
+
+  return 0
+}
+
+${helpers}
+complete -F _openspec_completion openspec
+`;
+    }
+    /**
+     * Generate completion case logic for a command
+     */
+    generateCommandCase(cmd, indent) {
+        const lines = [];
+        // Handle subcommands
+        if (cmd.subcommands && cmd.subcommands.length > 0) {
+            // First, check if user is typing a flag for the parent command
+            if (cmd.flags.length > 0) {
+                lines.push(`${indent}if [[ "$cur" == -* ]]; then`);
+                const flags = cmd.flags.map(f => {
+                    const parts = [];
+                    if (f.short)
+                        parts.push(`-${f.short}`);
+                    parts.push(`--${f.name}`);
+                    return parts.join(' ');
+                }).join(' ');
+                lines.push(`${indent}  local flags="${flags}"`);
+                lines.push(`${indent}  COMPREPLY=($(compgen -W "$flags" -- "$cur"))`);
+                lines.push(`${indent}  return 0`);
+                lines.push(`${indent}fi`);
+                lines.push('');
+            }
+            lines.push(`${indent}if [[ $cword -eq 2 ]]; then`);
+            lines.push(`${indent}  local subcommands="` + cmd.subcommands.map(s => this.escapeCommandName(s.name)).join(' ') + '"');
+            lines.push(`${indent}  COMPREPLY=($(compgen -W "$subcommands" -- "$cur"))`);
+            lines.push(`${indent}  return 0`);
+            lines.push(`${indent}fi`);
+            lines.push('');
+            lines.push(`${indent}case "$subcmd" in`);
+            for (const subcmd of cmd.subcommands) {
+                lines.push(`${indent}  ${subcmd.name})`);
+                lines.push(...this.generateArgumentCompletion(subcmd, indent + '    '));
+                lines.push(`${indent}    ;;`);
+            }
+            lines.push(`${indent}esac`);
+        }
+        else {
+            // No subcommands, just complete arguments
+            lines.push(...this.generateArgumentCompletion(cmd, indent));
+        }
+        return lines;
+    }
+    /**
+     * Generate argument completion (flags and positional arguments)
+     */
+    generateArgumentCompletion(cmd, indent) {
+        const lines = [];
+        // Check for flag completion
+        if (cmd.flags.length > 0) {
+            lines.push(`${indent}if [[ "$cur" == -* ]]; then`);
+            const flags = cmd.flags.map(f => {
+                const parts = [];
+                if (f.short)
+                    parts.push(`-${f.short}`);
+                parts.push(`--${f.name}`);
+                return parts.join(' ');
+            }).join(' ');
+            lines.push(`${indent}  local flags="${flags}"`);
+            lines.push(`${indent}  COMPREPLY=($(compgen -W "$flags" -- "$cur"))`);
+            lines.push(`${indent}  return 0`);
+            lines.push(`${indent}fi`);
+            lines.push('');
+        }
+        // Handle positional completions
+        if (cmd.acceptsPositional) {
+            lines.push(...this.generatePositionalCompletion(cmd.positionalType, indent));
+        }
+        return lines;
+    }
+    /**
+     * Generate positional argument completion based on type
+     */
+    generatePositionalCompletion(positionalType, indent) {
+        const lines = [];
+        switch (positionalType) {
+            case 'change-id':
+                lines.push(`${indent}_openspec_complete_changes`);
+                break;
+            case 'spec-id':
+                lines.push(`${indent}_openspec_complete_specs`);
+                break;
+            case 'change-or-spec-id':
+                lines.push(`${indent}_openspec_complete_items`);
+                break;
+            case 'shell':
+                lines.push(`${indent}local shells="zsh bash fish powershell"`);
+                lines.push(`${indent}COMPREPLY=($(compgen -W "$shells" -- "$cur"))`);
+                break;
+            case 'path':
+                lines.push(`${indent}COMPREPLY=($(compgen -f -- "$cur"))`);
+                break;
+        }
+        return lines;
+    }
+    /**
+     * Escape command/subcommand names for safe use in Bash scripts
+     */
+    escapeCommandName(name) {
+        // Escape shell metacharacters to prevent command injection
+        return name.replace(/["\$`\\]/g, '\\$&');
+    }
+}
+//# sourceMappingURL=bash-generator.js.map

package/dist/core/completions/generators/fish-generator.d.ts

@@ -0,0 +1,32 @@
+import { CompletionGenerator, CommandDefinition } from '../types.js';
+/**
+ * Generates Fish completion scripts for the OpenSpec CLI.
+ * Follows Fish completion conventions using the complete command.
+ */
+export declare class FishGenerator implements CompletionGenerator {
+    readonly shell: "fish";
+    /**
+     * Generate a Fish completion script
+     *
+     * @param commands - Command definitions to generate completions for
+     * @returns Fish completion script as a string
+     */
+    generate(commands: CommandDefinition[]): string;
+    /**
+     * Generate completions for a specific command
+     */
+    private generateCommandCompletions;
+    /**
+     * Generate flag completion
+     */
+    private generateFlagCompletion;
+    /**
+     * Generate positional argument completion
+     */
+    private generatePositionalCompletion;
+    /**
+     * Escape description text for Fish
+     */
+    private escapeDescription;
+}
+//# sourceMappingURL=fish-generator.d.ts.map