@fission-ai/openspec 1.2.0 → 1.3.0

package/README.md

@@ -36,7 +36,7 @@ Our philosophy:
 > [!TIP]
 > **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
 >
-> Run `/opsx:onboard` to get started. → [Learn more here](docs/opsx.md)
+> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
 
 <p align="center">
   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.
@@ -46,17 +46,14 @@ Our philosophy:
 
 Using OpenSpec in a team? [Email here](mailto:teams@openspec.dev) for access to our Slack channel.
 
-<!-- TODO: Add GIF demo of /opsx:new → /opsx:archive workflow -->
+<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
 
 ## See it in action
 
 ```text
-You: /opsx:new add-dark-mode
+You: /opsx:propose add-dark-mode
 AI:  Created openspec/changes/add-dark-mode/
-     Ready to create: proposal
-
-You: /opsx:ff   # "fast-forward" - generate all planning docs
-AI:  ✓ proposal.md — why we're doing this, what's changing
+     ✓ proposal.md — why we're doing this, what's changing
      ✓ specs/       — requirements and scenarios
      ✓ design.md    — technical approach
      ✓ tasks.md     — implementation checklist
@@ -101,10 +98,12 @@ cd your-project
 openspec init
 ```
 
-Now tell your AI: `/opsx:new <what-you-want-to-build>`
+Now tell your AI: `/opsx:propose <what-you-want-to-build>`
+
+If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:sync`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
 > [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 20+ tools and growing.
+> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
 >
 > Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
 

package/dist/commands/workflow/shared.d.ts

@@ -37,6 +37,11 @@ export declare function getStatusColor(status: 'done' | 'ready' | 'blocked'): (t
  * Gets the status indicator for an artifact.
  */
 export declare function getStatusIndicator(status: 'done' | 'ready' | 'blocked'): string;
+/**
+ * Returns the list of available change directory names under openspec/changes/.
+ * Excludes the archive directory and hidden directories.
+ */
+export declare function getAvailableChanges(projectRoot: string): Promise<string[]>;
 /**
  * Validates that a change exists and returns available changes if not.
  * Checks directory existence directly to support scaffolded changes (without proposal.md).

package/dist/commands/workflow/shared.js

@@ -52,26 +52,31 @@ export function getStatusIndicator(status) {
             return color('[-]');
     }
 }
+/**
+ * Returns the list of available change directory names under openspec/changes/.
+ * Excludes the archive directory and hidden directories.
+ */
+export async function getAvailableChanges(projectRoot) {
+    const changesPath = path.join(projectRoot, 'openspec', 'changes');
+    try {
+        const entries = await fs.promises.readdir(changesPath, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isDirectory() && e.name !== 'archive' && !e.name.startsWith('.'))
+            .map((e) => e.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
 /**
  * Validates that a change exists and returns available changes if not.
  * Checks directory existence directly to support scaffolded changes (without proposal.md).
  */
 export async function validateChangeExists(changeName, projectRoot) {
-    const changesPath = path.join(projectRoot, 'openspec', 'changes');
-    // Get all change directories (not just those with proposal.md)
-    const getAvailableChanges = async () => {
-        try {
-            const entries = await fs.promises.readdir(changesPath, { withFileTypes: true });
-            return entries
-                .filter((e) => e.isDirectory() && e.name !== 'archive' && !e.name.startsWith('.'))
-                .map((e) => e.name);
-        }
-        catch {
-            return [];
-        }
-    };
     if (!changeName) {
-        const available = await getAvailableChanges();
+        const available = await getAvailableChanges(projectRoot);
         if (available.length === 0) {
             throw new Error('No changes found. Create one with: openspec new change <name>');
         }
@@ -83,10 +88,10 @@ export async function validateChangeExists(changeName, projectRoot) {
         throw new Error(`Invalid change name '${changeName}': ${nameValidation.error}`);
     }
     // Check directory existence directly
-    const changePath = path.join(changesPath, changeName);
+    const changePath = path.join(projectRoot, 'openspec', 'changes', changeName);
     const exists = fs.existsSync(changePath) && fs.statSync(changePath).isDirectory();
     if (!exists) {
-        const available = await getAvailableChanges();
+        const available = await getAvailableChanges(projectRoot);
         if (available.length === 0) {
             throw new Error(`Change '${changeName}' not found. No changes exist. Create one with: openspec new change <name>`);
         }

package/dist/commands/workflow/status.js

@@ -6,7 +6,7 @@
 import ora from 'ora';
 import chalk from 'chalk';
 import { loadChangeContext, formatChangeStatus, } from '../../core/artifact-graph/index.js';
-import { validateChangeExists, validateSchemaExists, getStatusIndicator, getStatusColor, } from './shared.js';
+import { validateChangeExists, validateSchemaExists, getAvailableChanges, getStatusIndicator, getStatusColor, } from './shared.js';
 // -----------------------------------------------------------------------------
 // Command Implementation
 // -----------------------------------------------------------------------------
@@ -14,6 +14,23 @@ export async function statusCommand(options) {
     const spinner = ora('Loading change status...').start();
     try {
         const projectRoot = process.cwd();
+        // Handle no-changes case gracefully — status is informational,
+        // so "no changes" is a valid state, not an error.
+        if (!options.change) {
+            const available = await getAvailableChanges(projectRoot);
+            if (available.length === 0) {
+                spinner.stop();
+                if (options.json) {
+                    console.log(JSON.stringify({ changes: [], message: 'No active changes.' }, null, 2));
+                    return;
+                }
+                console.log('No active changes. Create one with: openspec new change <name>');
+                return;
+            }
+            // Changes exist but --change not provided
+            spinner.stop();
+            throw new Error(`Missing required option --change. Available changes:\n  ${available.join('\n  ')}`);
+        }
         const changeName = await validateChangeExists(options.change, projectRoot);
         // Validate schema if explicitly provided
         if (options.schema) {

package/dist/core/available-tools.d.ts

@@ -9,8 +9,9 @@ import { type AIToolOption } from './config.js';
  * Scans the project path for AI tool configuration directories and returns
  * the tools that are present.
  *
- * Checks for each tool's `skillsDir` (e.g., `.claude/`, `.cursor/`) at the
- * project root. Only tools with a `skillsDir` property are considered.
+ * For tools with `detectionPaths`, checks those specific paths (files or
+ * directories). Otherwise checks for the tool's `skillsDir` directory at
+ * the project root. Only tools with a `skillsDir` property are considered.
  */
 export declare function getAvailableTools(projectPath: string): AIToolOption[];
 //# sourceMappingURL=available-tools.d.ts.map

package/dist/core/available-tools.js

@@ -11,13 +11,26 @@ import { AI_TOOLS } from './config.js';
  * Scans the project path for AI tool configuration directories and returns
  * the tools that are present.
  *
- * Checks for each tool's `skillsDir` (e.g., `.claude/`, `.cursor/`) at the
- * project root. Only tools with a `skillsDir` property are considered.
+ * For tools with `detectionPaths`, checks those specific paths (files or
+ * directories). Otherwise checks for the tool's `skillsDir` directory at
+ * the project root. Only tools with a `skillsDir` property are considered.
  */
 export function getAvailableTools(projectPath) {
     return AI_TOOLS.filter((tool) => {
         if (!tool.skillsDir)
             return false;
+        if (tool.detectionPaths && tool.detectionPaths.length > 0) {
+            // statSync without .isDirectory() — detection paths can be files or directories
+            return tool.detectionPaths.some((p) => {
+                try {
+                    fs.statSync(path.join(projectPath, p));
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
         const dirPath = path.join(projectPath, tool.skillsDir);
         try {
             return fs.statSync(dirPath).isDirectory();

package/dist/core/command-generation/adapters/bob.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Bob Shell Command Adapter
+ *
+ * Formats commands for Bob Shell following its markdown specification.
+ * Commands are stored in .bob/commands/ directory.
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * Bob Shell adapter for command generation.
+ * File path: .bob/commands/opsx-<id>.md
+ * Frontmatter: description, argument-hint
+ */
+export declare const bobAdapter: ToolCommandAdapter;
+//# sourceMappingURL=bob.d.ts.map

package/dist/core/command-generation/adapters/bob.js

@@ -0,0 +1,45 @@
+/**
+ * Bob Shell Command Adapter
+ *
+ * Formats commands for Bob Shell following its markdown specification.
+ * Commands are stored in .bob/commands/ directory.
+ */
+import path from 'path';
+import { transformToHyphenCommands } from '../../../utils/command-references.js';
+/**
+ * Escapes a string value for safe YAML output.
+ * Quotes the string if it contains special YAML characters.
+ */
+function escapeYamlValue(value) {
+    // Check if value needs quoting (contains special YAML characters or starts/ends with whitespace)
+    const needsQuoting = /[:\n\r#{}[\],&*!|>'"%@`]|^\s|\s$/.test(value);
+    if (needsQuoting) {
+        // Use double quotes and escape internal double quotes and backslashes
+        const escaped = value.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n');
+        return `"${escaped}"`;
+    }
+    return value;
+}
+/**
+ * Bob Shell adapter for command generation.
+ * File path: .bob/commands/opsx-<id>.md
+ * Frontmatter: description, argument-hint
+ */
+export const bobAdapter = {
+    toolId: 'bob',
+    getFilePath(commandId) {
+        return path.join('.bob', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        // Transform command references from colon to hyphen format for Bob
+        const transformedBody = transformToHyphenCommands(content.body);
+        return `---
+description: ${escapeYamlValue(content.description)}
+argument-hint: command arguments
+---
+
+${transformedBody}
+`;
+    },
+};
+//# sourceMappingURL=bob.js.map

package/dist/core/command-generation/adapters/index.d.ts

@@ -6,6 +6,7 @@
 export { amazonQAdapter } from './amazon-q.js';
 export { antigravityAdapter } from './antigravity.js';
 export { auggieAdapter } from './auggie.js';
+export { bobAdapter } from './bob.js';
 export { claudeAdapter } from './claude.js';
 export { clineAdapter } from './cline.js';
 export { codexAdapter } from './codex.js';
@@ -18,11 +19,13 @@ export { factoryAdapter } from './factory.js';
 export { geminiAdapter } from './gemini.js';
 export { githubCopilotAdapter } from './github-copilot.js';
 export { iflowAdapter } from './iflow.js';
+export { junieAdapter } from './junie.js';
 export { kilocodeAdapter } from './kilocode.js';
 export { kiroAdapter } from './kiro.js';
 export { opencodeAdapter } from './opencode.js';
 export { piAdapter } from './pi.js';
 export { qoderAdapter } from './qoder.js';
+export { lingmaAdapter } from './lingma.js';
 export { qwenAdapter } from './qwen.js';
 export { roocodeAdapter } from './roocode.js';
 export { windsurfAdapter } from './windsurf.js';

package/dist/core/command-generation/adapters/index.js

@@ -6,6 +6,7 @@
 export { amazonQAdapter } from './amazon-q.js';
 export { antigravityAdapter } from './antigravity.js';
 export { auggieAdapter } from './auggie.js';
+export { bobAdapter } from './bob.js';
 export { claudeAdapter } from './claude.js';
 export { clineAdapter } from './cline.js';
 export { codexAdapter } from './codex.js';
@@ -18,11 +19,13 @@ export { factoryAdapter } from './factory.js';
 export { geminiAdapter } from './gemini.js';
 export { githubCopilotAdapter } from './github-copilot.js';
 export { iflowAdapter } from './iflow.js';
+export { junieAdapter } from './junie.js';
 export { kilocodeAdapter } from './kilocode.js';
 export { kiroAdapter } from './kiro.js';
 export { opencodeAdapter } from './opencode.js';
 export { piAdapter } from './pi.js';
 export { qoderAdapter } from './qoder.js';
+export { lingmaAdapter } from './lingma.js';
 export { qwenAdapter } from './qwen.js';
 export { roocodeAdapter } from './roocode.js';
 export { windsurfAdapter } from './windsurf.js';

package/dist/core/command-generation/adapters/junie.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Junie Command Adapter
+ *
+ * Formats commands for Junie following its frontmatter specification.
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * Junie adapter for command generation.
+ * File path: .junie/commands/opsx-<id>.md
+ * Frontmatter: description
+ */
+export declare const junieAdapter: ToolCommandAdapter;
+//# sourceMappingURL=junie.d.ts.map

package/dist/core/command-generation/adapters/junie.js

@@ -0,0 +1,26 @@
+/**
+ * Junie Command Adapter
+ *
+ * Formats commands for Junie following its frontmatter specification.
+ */
+import path from 'path';
+/**
+ * Junie adapter for command generation.
+ * File path: .junie/commands/opsx-<id>.md
+ * Frontmatter: description
+ */
+export const junieAdapter = {
+    toolId: 'junie',
+    getFilePath(commandId) {
+        return path.join('.junie', 'commands', `opsx-${commandId}.md`);
+    },
+    formatFile(content) {
+        return `---
+description: ${content.description}
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=junie.js.map

package/dist/core/command-generation/adapters/lingma.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lingma Command Adapter
+ *
+ * Formats commands for Lingma following its frontmatter specification.
+ */
+import type { ToolCommandAdapter } from '../types.js';
+/**
+ * Lingma adapter for command generation.
+ * File path: .lingma/commands/opsx/<id>.md
+ * Frontmatter: name, description, category, tags
+ */
+export declare const lingmaAdapter: ToolCommandAdapter;
+//# sourceMappingURL=lingma.d.ts.map

package/dist/core/command-generation/adapters/lingma.js

@@ -0,0 +1,30 @@
+/**
+ * Lingma Command Adapter
+ *
+ * Formats commands for Lingma following its frontmatter specification.
+ */
+import path from 'path';
+/**
+ * Lingma adapter for command generation.
+ * File path: .lingma/commands/opsx/<id>.md
+ * Frontmatter: name, description, category, tags
+ */
+export const lingmaAdapter = {
+    toolId: 'lingma',
+    getFilePath(commandId) {
+        return path.join('.lingma', 'commands', 'opsx', `${commandId}.md`);
+    },
+    formatFile(content) {
+        const tagsStr = content.tags.join(', ');
+        return `---
+name: ${content.name}
+description: ${content.description}
+category: ${content.category}
+tags: [${tagsStr}]
+---
+
+${content.body}
+`;
+    },
+};
+//# sourceMappingURL=lingma.js.map

package/dist/core/command-generation/adapters/opencode.d.ts

@@ -6,7 +6,7 @@
 import type { ToolCommandAdapter } from '../types.js';
 /**
  * OpenCode adapter for command generation.
- * File path: .opencode/command/opsx-<id>.md
+ * File path: .opencode/commands/opsx-<id>.md
  * Frontmatter: description
  */
 export declare const opencodeAdapter: ToolCommandAdapter;

package/dist/core/command-generation/adapters/opencode.js

@@ -7,13 +7,13 @@ import path from 'path';
 import { transformToHyphenCommands } from '../../../utils/command-references.js';
 /**
  * OpenCode adapter for command generation.
- * File path: .opencode/command/opsx-<id>.md
+ * File path: .opencode/commands/opsx-<id>.md
  * Frontmatter: description
  */
 export const opencodeAdapter = {
     toolId: 'opencode',
     getFilePath(commandId) {
-        return path.join('.opencode', 'command', `opsx-${commandId}.md`);
+        return path.join('.opencode', 'commands', `opsx-${commandId}.md`);
     },
     formatFile(content) {
         // Transform command references from colon to hyphen format for OpenCode

package/dist/core/command-generation/adapters/pi.d.ts

@@ -9,6 +9,10 @@ import type { ToolCommandAdapter } from '../types.js';
  * Pi adapter for prompt template generation.
  * File path: .pi/prompts/opsx-<id>.md
  * Frontmatter: description
+ *
+ * Pi uses the filename (minus .md) as the slash command name, so
+ * opsx-propose.md → /opsx-propose. Command references in the body
+ * are transformed from /opsx: to /opsx- for consistency.
  */
 export declare const piAdapter: ToolCommandAdapter;
 //# sourceMappingURL=pi.d.ts.map

package/dist/core/command-generation/adapters/pi.js

@@ -5,6 +5,14 @@
  * Pi prompt templates live in .pi/prompts/*.md with description frontmatter.
  */
 import path from 'path';
+import { transformToHyphenCommands } from '../../../utils/command-references.js';
+const PI_INPUT_HEADING = /^\*\*Input\*\*:[^\n]*$/m;
+function injectPiArgs(body) {
+    if (body.includes('$@') || body.includes('$ARGUMENTS')) {
+        return body;
+    }
+    return body.replace(PI_INPUT_HEADING, (heading) => `${heading}\n**Provided arguments**: $@`);
+}
 /**
  * Escapes a string value for safe YAML output.
  * Quotes the string if it contains special YAML characters.
@@ -23,6 +31,10 @@ function escapeYamlValue(value) {
  * Pi adapter for prompt template generation.
  * File path: .pi/prompts/opsx-<id>.md
  * Frontmatter: description
+ *
+ * Pi uses the filename (minus .md) as the slash command name, so
+ * opsx-propose.md → /opsx-propose. Command references in the body
+ * are transformed from /opsx: to /opsx- for consistency.
  */
 export const piAdapter = {
     toolId: 'pi',
@@ -30,11 +42,13 @@ export const piAdapter = {
         return path.join('.pi', 'prompts', `opsx-${commandId}.md`);
     },
     formatFile(content) {
+        // Transform /opsx: references to /opsx- and inject $@ for template args
+        const transformedBody = transformToHyphenCommands(content.body);
         return `---
 description: ${escapeYamlValue(content.description)}
 ---
 
-${content.body}
+${injectPiArgs(transformedBody)}
 `;
     },
 };

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

@@ -7,6 +7,7 @@
 import { amazonQAdapter } from './adapters/amazon-q.js';
 import { antigravityAdapter } from './adapters/antigravity.js';
 import { auggieAdapter } from './adapters/auggie.js';
+import { bobAdapter } from './adapters/bob.js';
 import { claudeAdapter } from './adapters/claude.js';
 import { clineAdapter } from './adapters/cline.js';
 import { codexAdapter } from './adapters/codex.js';
@@ -19,11 +20,13 @@ import { factoryAdapter } from './adapters/factory.js';
 import { geminiAdapter } from './adapters/gemini.js';
 import { githubCopilotAdapter } from './adapters/github-copilot.js';
 import { iflowAdapter } from './adapters/iflow.js';
+import { junieAdapter } from './adapters/junie.js';
 import { kilocodeAdapter } from './adapters/kilocode.js';
 import { kiroAdapter } from './adapters/kiro.js';
 import { opencodeAdapter } from './adapters/opencode.js';
 import { piAdapter } from './adapters/pi.js';
 import { qoderAdapter } from './adapters/qoder.js';
+import { lingmaAdapter } from './adapters/lingma.js';
 import { qwenAdapter } from './adapters/qwen.js';
 import { roocodeAdapter } from './adapters/roocode.js';
 import { windsurfAdapter } from './adapters/windsurf.js';
@@ -37,6 +40,7 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(amazonQAdapter);
         CommandAdapterRegistry.register(antigravityAdapter);
         CommandAdapterRegistry.register(auggieAdapter);
+        CommandAdapterRegistry.register(bobAdapter);
         CommandAdapterRegistry.register(claudeAdapter);
         CommandAdapterRegistry.register(clineAdapter);
         CommandAdapterRegistry.register(codexAdapter);
@@ -49,11 +53,13 @@ export class CommandAdapterRegistry {
         CommandAdapterRegistry.register(geminiAdapter);
         CommandAdapterRegistry.register(githubCopilotAdapter);
         CommandAdapterRegistry.register(iflowAdapter);
+        CommandAdapterRegistry.register(junieAdapter);
         CommandAdapterRegistry.register(kilocodeAdapter);
         CommandAdapterRegistry.register(kiroAdapter);
         CommandAdapterRegistry.register(opencodeAdapter);
         CommandAdapterRegistry.register(piAdapter);
         CommandAdapterRegistry.register(qoderAdapter);
+        CommandAdapterRegistry.register(lingmaAdapter);
         CommandAdapterRegistry.register(qwenAdapter);
         CommandAdapterRegistry.register(roocodeAdapter);
         CommandAdapterRegistry.register(windsurfAdapter);

package/dist/core/completions/installers/powershell-installer.d.ts

@@ -10,6 +10,20 @@ export declare class PowerShellInstaller {
      */
     private readonly PROFILE_MARKERS;
     constructor(homeDir?: string);
+    /**
+     * Detect the encoding of a file by inspecting its BOM (Byte Order Mark).
+     * Returns the Node.js BufferEncoding and the raw BOM bytes to preserve on write.
+     */
+    private detectEncoding;
+    /**
+     * Read a profile file, preserving its encoding metadata for round-trip writes.
+     * Throws if the file uses UTF-16 BE (unsupported by Node).
+     */
+    private readProfileFile;
+    /**
+     * Write a profile file, preserving the original BOM and encoding.
+     */
+    private writeProfileFile;
     /**
      * Get PowerShell profile path
      * Prefers $PROFILE environment variable, falls back to platform defaults

package/dist/core/completions/installers/powershell-installer.js

@@ -17,6 +17,44 @@ export class PowerShellInstaller {
     constructor(homeDir = os.homedir()) {
         this.homeDir = homeDir;
     }
+    /**
+     * Detect the encoding of a file by inspecting its BOM (Byte Order Mark).
+     * Returns the Node.js BufferEncoding and the raw BOM bytes to preserve on write.
+     */
+    detectEncoding(buffer) {
+        // UTF-16 LE BOM: FF FE
+        if (buffer.length >= 2 && buffer[0] === 0xff && buffer[1] === 0xfe) {
+            return { encoding: 'utf16le', bom: Buffer.from([0xff, 0xfe]) };
+        }
+        // UTF-16 BE BOM: FE FF — not natively supported by Node
+        if (buffer.length >= 2 && buffer[0] === 0xfe && buffer[1] === 0xff) {
+            throw new Error('File is encoded as UTF-16 BE which is not supported. ' +
+                'Please re-save as UTF-8 or UTF-16 LE, then retry.');
+        }
+        // UTF-8 BOM: EF BB BF
+        if (buffer.length >= 3 && buffer[0] === 0xef && buffer[1] === 0xbb && buffer[2] === 0xbf) {
+            return { encoding: 'utf-8', bom: Buffer.from([0xef, 0xbb, 0xbf]) };
+        }
+        // No BOM → default UTF-8
+        return { encoding: 'utf-8', bom: Buffer.alloc(0) };
+    }
+    /**
+     * Read a profile file, preserving its encoding metadata for round-trip writes.
+     * Throws if the file uses UTF-16 BE (unsupported by Node).
+     */
+    async readProfileFile(filePath) {
+        const raw = await fs.readFile(filePath);
+        const { encoding, bom } = this.detectEncoding(raw);
+        const content = raw.subarray(bom.length).toString(encoding);
+        return { content, encoding, bom };
+    }
+    /**
+     * Write a profile file, preserving the original BOM and encoding.
+     */
+    async writeProfileFile(filePath, content, encoding, bom) {
+        const body = Buffer.from(content, encoding);
+        await fs.writeFile(filePath, Buffer.concat([bom, body]));
+    }
     /**
      * Get PowerShell profile path
      * Prefers $PROFILE environment variable, falls back to platform defaults
@@ -120,11 +158,24 @@ export class PowerShellInstaller {
                 const profileDir = path.dirname(profilePath);
                 await fs.mkdir(profileDir, { recursive: true });
                 let profileContent = '';
+                let fileEncoding = 'utf-8';
+                let fileBom = Buffer.alloc(0);
                 try {
-                    profileContent = await fs.readFile(profilePath, 'utf-8');
+                    const file = await this.readProfileFile(profilePath);
+                    profileContent = file.content;
+                    fileEncoding = file.encoding;
+                    fileBom = file.bom;
                 }
-                catch {
-                    // Profile doesn't exist yet, that's fine
+                catch (err) {
+                    // If the file doesn't exist that's fine — we'll create it as UTF-8.
+                    // Any other read error (permissions, unsupported encoding, etc.) → skip this profile.
+                    if (err?.code === 'ENOENT') {
+                        // keep defaults
+                    }
+                    else {
+                        console.warn(`Warning: Skipping ${profilePath}: ${err?.message ?? String(err)}`);
+                        continue;
+                    }
                 }
                 // Check if already configured
                 const scriptLine = `. "${scriptPath}"`;
@@ -140,7 +191,7 @@ export class PowerShellInstaller {
                     '',
                 ].join('\n');
                 const newContent = profileContent + openspecBlock;
-                await fs.writeFile(profilePath, newContent, 'utf-8');
+                await this.writeProfileFile(profilePath, newContent, fileEncoding, fileBom);
                 anyConfigured = true;
             }
             catch (error) {
@@ -161,13 +212,22 @@ export class PowerShellInstaller {
         let anyRemoved = false;
         for (const profilePath of profilePaths) {
             try {
-                // Read profile content
+                // Read profile content with encoding detection
                 let profileContent;
+                let fileEncoding = 'utf-8';
+                let fileBom = Buffer.alloc(0);
                 try {
-                    profileContent = await fs.readFile(profilePath, 'utf-8');
+                    const file = await this.readProfileFile(profilePath);
+                    profileContent = file.content;
+                    fileEncoding = file.encoding;
+                    fileBom = file.bom;
                 }
-                catch {
-                    continue; // Profile doesn't exist, nothing to remove
+                catch (err) {
+                    if (err?.code === 'ENOENT') {
+                        continue; // Profile doesn't exist, nothing to remove
+                    }
+                    console.warn(`Warning: Could not read ${profilePath}: ${err?.message ?? String(err)}`);
+                    continue;
                 }
                 // Remove OPENSPEC:START -> OPENSPEC:END block
                 const startMarker = '# OPENSPEC:START';
@@ -186,7 +246,7 @@ export class PowerShellInstaller {
                 const afterBlock = profileContent.substring(endIndex + endMarker.length);
                 // Clean up extra newlines
                 const newContent = (beforeBlock.trimEnd() + '\n' + afterBlock.trimStart()).trim() + '\n';
-                await fs.writeFile(profilePath, newContent, 'utf-8');
+                await this.writeProfileFile(profilePath, newContent, fileEncoding, fileBom);
                 anyRemoved = true;
             }
             catch (error) {

package/dist/core/config.d.ts

@@ -12,6 +12,7 @@ export interface AIToolOption {
     available: boolean;
     successLabel?: string;
     skillsDir?: string;
+    detectionPaths?: string[];
 }
 export declare const AI_TOOLS: AIToolOption[];
 //# sourceMappingURL=config.d.ts.map

package/dist/core/config.js

@@ -7,9 +7,11 @@ export const AI_TOOLS = [
     { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq' },
     { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent' },
     { name: 'Auggie (Augment CLI)', value: 'auggie', available: true, successLabel: 'Auggie', skillsDir: '.augment' },
+    { name: 'Bob Shell', value: 'bob', available: true, successLabel: 'Bob Shell', skillsDir: '.bob' },
     { name: 'Claude Code', value: 'claude', available: true, successLabel: 'Claude Code', skillsDir: '.claude' },
     { name: 'Cline', value: 'cline', available: true, successLabel: 'Cline', skillsDir: '.cline' },
     { name: 'Codex', value: 'codex', available: true, successLabel: 'Codex', skillsDir: '.codex' },
+    { name: 'ForgeCode', value: 'forgecode', available: true, successLabel: 'ForgeCode', skillsDir: '.forge' },
     { name: 'CodeBuddy Code (CLI)', value: 'codebuddy', available: true, successLabel: 'CodeBuddy Code', skillsDir: '.codebuddy' },
     { name: 'Continue', value: 'continue', available: true, successLabel: 'Continue (VS Code / JetBrains / Cli)', skillsDir: '.continue' },
     { name: 'CoStrict', value: 'costrict', available: true, successLabel: 'CoStrict', skillsDir: '.cospec' },
@@ -17,13 +19,15 @@ export const AI_TOOLS = [
     { name: 'Cursor', value: 'cursor', available: true, successLabel: 'Cursor', skillsDir: '.cursor' },
     { name: 'Factory Droid', value: 'factory', available: true, successLabel: 'Factory Droid', skillsDir: '.factory' },
     { name: 'Gemini CLI', value: 'gemini', available: true, successLabel: 'Gemini CLI', skillsDir: '.gemini' },
-    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github' },
+    { name: 'GitHub Copilot', value: 'github-copilot', available: true, successLabel: 'GitHub Copilot', skillsDir: '.github', detectionPaths: ['.github/copilot-instructions.md', '.github/instructions', '.github/workflows/copilot-setup-steps.yml', '.github/prompts', '.github/agents', '.github/skills', '.github/.mcp.json'] },
     { name: 'iFlow', value: 'iflow', available: true, successLabel: 'iFlow', skillsDir: '.iflow' },
+    { name: 'Junie', value: 'junie', available: true, successLabel: 'Junie', skillsDir: '.junie' },
     { name: 'Kilo Code', value: 'kilocode', available: true, successLabel: 'Kilo Code', skillsDir: '.kilocode' },
     { name: 'Kiro', value: 'kiro', available: true, successLabel: 'Kiro', skillsDir: '.kiro' },
     { name: 'OpenCode', value: 'opencode', available: true, successLabel: 'OpenCode', skillsDir: '.opencode' },
     { name: 'Pi', value: 'pi', available: true, successLabel: 'Pi', skillsDir: '.pi' },
     { name: 'Qoder', value: 'qoder', available: true, successLabel: 'Qoder', skillsDir: '.qoder' },
+    { name: 'Lingma', value: 'lingma', available: true, successLabel: 'Lingma', skillsDir: '.lingma' },
     { name: 'Qwen Code', value: 'qwen', available: true, successLabel: 'Qwen Code', skillsDir: '.qwen' },
     { name: 'RooCode', value: 'roocode', available: true, successLabel: 'RooCode', skillsDir: '.roo' },
     { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae' },

package/dist/core/init.js

@@ -138,17 +138,13 @@ export class InitCommand {
         console.log(formatDetectionSummary(detection));
         console.log();
         const canPrompt = this.canPromptInteractively();
-        if (this.force) {
-            // --force flag: proceed with cleanup automatically
+        if (this.force || !canPrompt) {
+            // --force flag or non-interactive mode: proceed with cleanup automatically.
+            // Legacy slash commands are 100% OpenSpec-managed, and config file cleanup
+            // only removes markers (never deletes files), so auto-cleanup is safe.
             await this.performLegacyCleanup(projectPath, detection);
             return;
         }
-        if (!canPrompt) {
-            // Non-interactive mode without --force: abort
-            console.log(chalk.red('Legacy files detected in non-interactive mode.'));
-            console.log(chalk.dim('Run interactively to upgrade, or use --force to auto-cleanup.'));
-            process.exit(1);
-        }
         // Interactive mode: prompt for confirmation
         const { confirm } = await import('@inquirer/prompts');
         const shouldCleanup = await confirm({
@@ -383,8 +379,8 @@ export class InitCommand {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Generate SKILL.md content with YAML frontmatter including generatedBy
-                        // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        // Use hyphen-based command references for tools where filename = command name
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         // Write the skill file
                         await FileSystemUtils.writeFile(skillFile, skillContent);

package/dist/core/legacy-cleanup.d.ts

@@ -19,7 +19,7 @@ export declare const LEGACY_SLASH_COMMAND_PATHS: Record<string, LegacySlashComma
 export interface LegacySlashCommandPattern {
     type: 'directory' | 'files';
     path?: string;
-    pattern?: string;
+    pattern?: string | string[];
 }
 /**
  * Result of legacy artifact detection

package/dist/core/legacy-cleanup.js

@@ -30,6 +30,7 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     'claude': { type: 'directory', path: '.claude/commands/openspec' },
     'codebuddy': { type: 'directory', path: '.codebuddy/commands/openspec' },
     'qoder': { type: 'directory', path: '.qoder/commands/openspec' },
+    'lingma': { type: 'directory', path: '.lingma/commands/openspec' },
     'crush': { type: 'directory', path: '.crush/commands/openspec' },
     'gemini': { type: 'directory', path: '.gemini/commands/openspec' },
     'costrict': { type: 'directory', path: '.cospec/openspec/commands' },
@@ -44,10 +45,11 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     'roocode': { type: 'files', pattern: '.roo/commands/openspec-*.md' },
     'auggie': { type: 'files', pattern: '.augment/commands/openspec-*.md' },
     'factory': { type: 'files', pattern: '.factory/commands/openspec-*.md' },
-    'opencode': { type: 'files', pattern: '.opencode/command/openspec-*.md' },
+    'opencode': { type: 'files', pattern: ['.opencode/command/opsx-*.md', '.opencode/command/openspec-*.md'] },
     'continue': { type: 'files', pattern: '.continue/prompts/openspec-*.prompt' },
     'antigravity': { type: 'files', pattern: '.agent/workflows/openspec-*.md' },
     'iflow': { type: 'files', pattern: '.iflow/commands/openspec-*.md' },
+    'junie': { type: 'files', pattern: ['.junie/commands/opsx-*.md', '.junie/commands/openspec-*.md'] },
     'qwen': { type: 'files', pattern: '.qwen/commands/openspec-*.toml' },
     'codex': { type: 'files', pattern: '.codex/prompts/openspec-*.md' },
 };
@@ -132,8 +134,11 @@ export async function detectLegacySlashCommands(projectPath) {
         }
         else if (pattern.type === 'files' && pattern.pattern) {
             // For file-based patterns, check for individual files
-            const foundFiles = await findLegacySlashCommandFiles(projectPath, pattern.pattern);
-            files.push(...foundFiles);
+            const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
+            for (const p of patterns) {
+                const foundFiles = await findLegacySlashCommandFiles(projectPath, p);
+                files.push(...foundFiles);
+            }
         }
     }
     return { directories, files };
@@ -466,14 +471,21 @@ export function getToolsFromLegacyArtifacts(detection) {
             if (pattern.type === 'files' && pattern.pattern) {
                 // Convert glob pattern to regex for matching
                 // e.g., '.cursor/commands/openspec-*.md' -> /^\.cursor\/commands\/openspec-.*\.md$/
-                const regexPattern = pattern.pattern
-                    .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
-                    .replace(/\*/g, '.*'); // Replace * with .*
-                const regex = new RegExp(`^${regexPattern}$`);
-                if (regex.test(normalizedFile)) {
-                    tools.add(toolId);
-                    break;
+                const patterns = Array.isArray(pattern.pattern) ? pattern.pattern : [pattern.pattern];
+                let matched = false;
+                for (const p of patterns) {
+                    const regexPattern = p
+                        .replace(/[.+^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
+                        .replace(/\*/g, '.*'); // Replace * with .*
+                    const regex = new RegExp(`^${regexPattern}$`);
+                    if (regex.test(normalizedFile)) {
+                        tools.add(toolId);
+                        matched = true;
+                        break;
+                    }
                 }
+                if (matched)
+                    break;
             }
         }
     }

package/dist/core/templates/workflows/bulk-archive-change.js

@@ -77,7 +77,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    \`\`\`
-   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
@@ -323,7 +323,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    \`\`\`
-   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |

package/dist/core/templates/workflows/explore.js

@@ -49,10 +49,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│   ┌────────┐         ┌────────┐        │
-│   │ State  │────────▶│ State  │        │
-│   │   A    │         │   B    │        │
-│   └────────┘         └────────┘        │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -107,14 +107,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-   | Insight Type | Where to Capture |
-   |--------------|------------------|
-   | New requirement discovered | \`specs/<capability>/spec.md\` |
-   | Requirement changed | \`specs/<capability>/spec.md\` |
-   | Design decision made | \`design.md\` |
-   | Scope changed | \`proposal.md\` |
-   | New work identified | \`tasks.md\` |
-   | Assumption invalidated | Relevant artifact |
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | \`specs/<capability>/spec.md\` |
+    | Requirement changed        | \`specs/<capability>/spec.md\` |
+    | Design decision made       | \`design.md\`                  |
+    | Scope changed              | \`proposal.md\`                |
+    | New work identified        | \`tasks.md\`                   |
+    | Assumption invalidated     | Relevant artifact              |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"
@@ -220,7 +220,7 @@ User: A CLI tool that tracks local dev environments
 You: That changes everything.
 
      ┌─────────────────────────────────────────────────┐
-     │         CLI TOOL DATA STORAGE                  │
+     │          CLI TOOL DATA STORAGE                  │
      └─────────────────────────────────────────────────┘
 
      Key constraints:
@@ -344,10 +344,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│   ┌────────┐         ┌────────┐        │
-│   │ State  │────────▶│ State  │        │
-│   │   A    │         │   B    │        │
-│   └────────┘         └────────┘        │
+│      ┌────────┐         ┌────────┐      │
+│      │ State  │────────▶│ State  │      │
+│      │   A    │         │   B    │      │
+│      └────────┘         └────────┘      │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -404,14 +404,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-   | Insight Type | Where to Capture |
-   |--------------|------------------|
-   | New requirement discovered | \`specs/<capability>/spec.md\` |
-   | Requirement changed | \`specs/<capability>/spec.md\` |
-   | Design decision made | \`design.md\` |
-   | Scope changed | \`proposal.md\` |
-   | New work identified | \`tasks.md\` |
-   | Assumption invalidated | Relevant artifact |
+    | Insight Type               | Where to Capture               |
+    |----------------------------|--------------------------------|
+    | New requirement discovered | \`specs/<capability>/spec.md\` |
+    | Requirement changed        | \`specs/<capability>/spec.md\` |
+    | Design decision made       | \`design.md\`                  |
+    | Scope changed              | \`proposal.md\`                |
+    | New work identified        | \`tasks.md\`                   |
+    | Assumption invalidated     | Relevant artifact              |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"

package/dist/core/templates/workflows/onboard.js

@@ -468,21 +468,21 @@ This same rhythm works for any size change—a small fix or a major feature.
 
 **Core workflow:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:propose\` | Create a change and generate all artifacts |
-| \`/opsx:explore\` | Think through problems before/during work |
-| \`/opsx:apply\` | Implement tasks from a change |
-| \`/opsx:archive\` | Archive a completed change |
+ | Command           | What it does                               |
+ |-------------------|--------------------------------------------|
+ | \`/opsx:propose\` | Create a change and generate all artifacts |
+ | \`/opsx:explore\` | Think through problems before/during work  |
+ | \`/opsx:apply\`   | Implement tasks from a change              |
+ | \`/opsx:archive\` | Archive a completed change                 |
 
 **Additional commands:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:new\` | Start a new change, step through artifacts one at a time |
-| \`/opsx:continue\` | Continue working on an existing change |
-| \`/opsx:ff\` | Fast-forward: create all artifacts at once |
-| \`/opsx:verify\` | Verify implementation matches artifacts |
+ | Command            | What it does                                             |
+ |--------------------|----------------------------------------------------------|
+ | \`/opsx:new\`      | Start a new change, step through artifacts one at a time |
+ | \`/opsx:continue\` | Continue working on an existing change                   |
+ | \`/opsx:ff\`       | Fast-forward: create all artifacts at once               |
+ | \`/opsx:verify\`   | Verify implementation matches artifacts                  |
 
 ---
 
@@ -520,21 +520,21 @@ If the user says they just want to see the commands or skip the tutorial:
 
 **Core workflow:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:propose <name>\` | Create a change and generate all artifacts |
-| \`/opsx:explore\` | Think through problems (no code changes) |
-| \`/opsx:apply <name>\` | Implement tasks |
-| \`/opsx:archive <name>\` | Archive when done |
+ | Command                  | What it does                               |
+ |--------------------------|--------------------------------------------|
+ | \`/opsx:propose <name>\` | Create a change and generate all artifacts |
+ | \`/opsx:explore\`        | Think through problems (no code changes)   |
+ | \`/opsx:apply <name>\`   | Implement tasks                            |
+ | \`/opsx:archive <name>\` | Archive when done                          |
 
 **Additional commands:**
 
-| Command | What it does |
-|---------|--------------|
-| \`/opsx:new <name>\` | Start a new change, step by step |
-| \`/opsx:continue <name>\` | Continue an existing change |
-| \`/opsx:ff <name>\` | Fast-forward: all artifacts at once |
-| \`/opsx:verify <name>\` | Verify implementation |
+ | Command                   | What it does                        |
+ |---------------------------|-------------------------------------|
+ | \`/opsx:new <name>\`      | Start a new change, step by step    |
+ | \`/opsx:continue <name>\` | Continue an existing change         |
+ | \`/opsx:ff <name>\`       | Fast-forward: all artifacts at once |
+ | \`/opsx:verify <name>\`   | Verify implementation               |
 
 Try \`/opsx:propose\` to start your first change.
 \`\`\`

package/dist/core/update.js

@@ -129,7 +129,7 @@ export class UpdateCommand {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
@@ -504,7 +504,7 @@ export class UpdateCommand {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = (tool.value === 'opencode' || tool.value === 'pi') ? transformToHyphenCommands : undefined;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

package/scripts/postinstall.js

@@ -1,9 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * Postinstall script for auto-installing shell completions
+ * Postinstall script that hints about shell completions
  *
- * This script runs automatically after npm install unless:
+ * Completion installation is opt-in: the user must run
+ * `openspec completion install` explicitly. This script only
+ * prints a one-line tip after npm install.
+ *
+ * The tip is suppressed when:
  * - CI=true environment variable is set
  * - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
  * - dist/ directory doesn't exist (dev setup scenario)
@@ -48,65 +52,6 @@ async function distExists() {
   }
 }
 
-/**
- * Detect the user's shell
- */
-async function detectShell() {
-  try {
-    const { detectShell } = await import('../dist/utils/shell-detection.js');
-    const result = detectShell();
-    return result.shell;
-  } catch (error) {
-    // Fail silently if detection module doesn't exist
-    return undefined;
-  }
-}
-
-/**
- * Install completions for the detected shell
- */
-async function installCompletions(shell) {
-  try {
-    const { CompletionFactory } = await import('../dist/core/completions/factory.js');
-    const { COMMAND_REGISTRY } = await import('../dist/core/completions/command-registry.js');
-
-    // Check if shell is supported
-    if (!CompletionFactory.isSupported(shell)) {
-      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
-      return;
-    }
-
-    // Generate completion script
-    const generator = CompletionFactory.createGenerator(shell);
-    const script = generator.generate(COMMAND_REGISTRY);
-
-    // Install completion script
-    const installer = CompletionFactory.createInstaller(shell);
-    const result = await installer.install(script);
-
-    if (result.success) {
-      // Show success message based on installation type
-      if (result.isOhMyZsh) {
-        console.log(`✓ Shell completions installed`);
-        console.log(`  Restart shell: exec zsh`);
-      } else if (result.zshrcConfigured) {
-        console.log(`✓ Shell completions installed and configured`);
-        console.log(`  Restart shell: exec zsh`);
-      } else {
-        console.log(`✓ Shell completions installed to ~/.zsh/completions/`);
-        console.log(`  Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)`);
-        console.log(`  Then: exec zsh`);
-      }
-    } else {
-      // Installation failed, show tip for manual install
-      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
-    }
-  } catch (error) {
-    // Fail gracefully - show tip for manual install
-    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
-  }
-}
-
 /**
  * Main function
  */
@@ -124,19 +69,10 @@ async function main() {
       return;
     }
 
-    // Detect shell
-    const shell = await detectShell();
-    if (!shell) {
-      console.log(`\nTip: Run 'openspec completion install' for shell completions`);
-      return;
-    }
-
-    // Install completions
-    await installCompletions(shell);
+    // Completions are opt-in — just print a hint
+    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
   } catch (error) {
     // Fail gracefully - never break npm install
-    // Show tip for manual install
-    console.log(`\nTip: Run 'openspec completion install' for shell completions`);
   }
 }