@fission-ai/openspec 1.9.0 → 1.10.0

package/dist/cli/index.d.ts

@@ -20,6 +20,23 @@ export declare function getCommandPath(command: Command): string;
  * non-JSON run, never lost, whereas printing it on a JSON run corrupts stdout.
  */
 export declare function isJsonRun(command: Command): boolean;
+/**
+ * True for the commands that exist to serve shell completions: the user-facing
+ * `openspec completion ...` group and the hidden `__complete` resolver that
+ * generated completion scripts call on every Tab press. Tipping either about
+ * completions is noise, and `__complete` would burn the one-shot tip invisibly.
+ */
+export declare function isCompletionRun(commandPath: string): boolean;
+/**
+ * True when the first-run completions tip must be deferred rather than shown.
+ *
+ * Deferring keeps the tip unconsumed, so it still reaches the user on a later
+ * run that can actually carry it. All three cases are runs nobody would read a
+ * hint from: JSON output, the completion machinery itself, and a stderr that is
+ * not a terminal — pipes and the agent-driven runs that dominate this CLI's
+ * usage would otherwise burn the user's one-shot tip into a log nobody opens.
+ */
+export declare function shouldDeferCompletionTip(command: Command, stderrIsTty: boolean): boolean;
 export { program };
 export declare function runCli(argv?: string[]): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.js

@@ -26,6 +26,7 @@ import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
 import { statusCommand, instructionsCommand, applyInstructionsCommand, archiveInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
+import { maybeShowCompletionTip } from '../core/completion-tip.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
 import { isInteractive } from '../utils/interactive.js';
 const STORE_OPTION_DESCRIPTION = COMMON_FLAGS.store.description;
@@ -90,6 +91,27 @@ export function isJsonRun(command) {
     return (command.optsWithGlobals().json === true ||
         command.args.includes('--json'));
 }
+/**
+ * True for the commands that exist to serve shell completions: the user-facing
+ * `openspec completion ...` group and the hidden `__complete` resolver that
+ * generated completion scripts call on every Tab press. Tipping either about
+ * completions is noise, and `__complete` would burn the one-shot tip invisibly.
+ */
+export function isCompletionRun(commandPath) {
+    return commandPath.split(':')[0] === 'completion' || commandPath === '__complete';
+}
+/**
+ * True when the first-run completions tip must be deferred rather than shown.
+ *
+ * Deferring keeps the tip unconsumed, so it still reaches the user on a later
+ * run that can actually carry it. All three cases are runs nobody would read a
+ * hint from: JSON output, the completion machinery itself, and a stderr that is
+ * not a terminal — pipes and the agent-driven runs that dominate this CLI's
+ * usage would otherwise burn the user's one-shot tip into a log nobody opens.
+ */
+export function shouldDeferCompletionTip(command, stderrIsTty) {
+    return isJsonRun(command) || isCompletionRun(getCommandPath(command)) || !stderrIsTty;
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
@@ -105,16 +127,32 @@ program.hook('preAction', async (thisCommand, actionCommand) => {
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
-    // Show first-run telemetry notice (if not seen). Suppress it whenever the run
-    // asked for JSON so stdout stays a single valid JSON document (see isJsonRun).
+    // Show first-run telemetry notice (if not seen). It's written to stderr, so it
+    // never pollutes stdout — but --json runs still defer it (see isJsonRun) so the
+    // very first invocation stays free of any incidental output on either stream.
     await maybeShowTelemetryNotice({ silent: isJsonRun(actionCommand) });
     // 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();
+program.hook('postAction', async (_thisCommand, actionCommand) => {
+    // Show the first-run shell-completions tip (on stderr, so piped stdout stays
+    // clean). postAction, not preAction: the tip trails the command's own output
+    // instead of pushing an error message or `init`'s setup summary down the
+    // screen. Deferred — not consumed — whenever nobody would read it: JSON runs,
+    // `openspec completion ...`, and a stderr that is not a terminal (agents and
+    // pipes would otherwise silently burn the user's one-shot tip).
+    try {
+        await maybeShowCompletionTip({
+            silent: shouldDeferCompletionTip(actionCommand, Boolean(process.stderr.isTTY)),
+        });
+    }
+    finally {
+        // The flush runs even if the hint throws: parse() is synchronous, so a
+        // rejection here has no catch anywhere above it.
+        await shutdown();
+    }
 });
 const availableToolIds = AI_TOOLS
     .filter((tool) => tool.skillsDir || tool.globalSkillsDir)
@@ -127,6 +165,7 @@ program
     .command('init [path]')
     .description('Initialize OpenSpec in your project')
     .option('--tools <tools>', toolsOptionDescription)
+    .option('--language <language>', 'Write new OpenSpec artifacts in this language')
     .option('--force', 'Auto-cleanup legacy files without prompting')
     .option('--profile <profile>', 'Override global config profile (core or custom)')
     .option('--no-animation', 'Show a static welcome screen instead of the animated one')
@@ -157,6 +196,7 @@ program
         const { InitCommand } = await import('../core/init.js');
         const initCommand = new InitCommand({
             tools: options?.tools,
+            language: options?.language,
             force: options?.force,
             profile: options?.profile,
             animation: options?.animation,
@@ -362,10 +402,12 @@ changeCmd
     .action(async (changeName, options) => {
     try {
         const changeCommand = new ChangeCommand();
+        // validate() already sets process.exitCode, and Node honours it at
+        // natural exit. Calling process.exit() here would skip commander's
+        // postAction hook — the same trap called out for `update` below — which
+        // kills the telemetry flush and the first-run completions tip on what is
+        // a routine outcome, not an error: a change that fails validation.
         await changeCommand.validate(changeName, options);
-        if (typeof process.exitCode === 'number' && process.exitCode !== 0) {
-            process.exit(process.exitCode);
-        }
     }
     catch (error) {
         console.error(`Error: ${error.message}`);

package/dist/commands/config.js

@@ -453,6 +453,7 @@ export function registerConfigCommand(program) {
                 delivery: currentState.delivery,
                 workflows: [...currentState.workflows],
             };
+            let workflowSelectionChanged = false;
             if (action === 'both' || action === 'delivery') {
                 const deliveryChoices = [
                     {
@@ -497,8 +498,11 @@ export function registerConfigCommand(program) {
                     };
                 };
                 const selectedWorkflows = await checkbox({
+                    // The `instructions` option was removed in @inquirer/checkbox v5.
+                    // Its replacement, the built-in keys help tip, renders
+                    // "↑↓ navigate • space select • ⏎ submit" by default — a superset of
+                    // the hint this used to pass — so no theme override is needed here.
                     message: 'Select workflows to make available:',
-                    instructions: 'Space to toggle, Enter to confirm',
                     pageSize: ALL_WORKFLOWS.length,
                     theme: {
                         icon: {
@@ -509,7 +513,12 @@ export function registerConfigCommand(program) {
                     choices: ALL_WORKFLOWS.map(formatWorkflowChoice),
                 });
                 nextState.workflows = selectedWorkflows;
-                nextState.profile = deriveProfileFromWorkflowSelection(selectedWorkflows);
+                workflowSelectionChanged =
+                    selectedWorkflows.length !== currentState.workflows.length ||
+                        selectedWorkflows.some((workflow) => !currentState.workflows.includes(workflow));
+                nextState.profile = workflowSelectionChanged
+                    ? deriveProfileFromWorkflowSelection(selectedWorkflows)
+                    : currentState.profile;
             }
             const diff = diffProfileState(currentState, nextState);
             if (!diff.hasChanges) {
@@ -524,7 +533,9 @@ export function registerConfigCommand(program) {
             console.log();
             config.profile = nextState.profile;
             config.delivery = nextState.delivery;
-            config.workflows = nextState.workflows;
+            if (currentState.profile !== 'custom' || workflowSelectionChanged) {
+                config.workflows = nextState.workflows;
+            }
             saveGlobalConfig(config);
             // Check if inside an OpenSpec project
             const projectDir = process.cwd();

package/dist/commands/feedback.js

@@ -2,6 +2,8 @@ import { execSync, execFileSync } from 'child_process';
 import { createRequire } from 'module';
 import os from 'os';
 const require = createRequire(import.meta.url);
+const MAX_TITLE_LENGTH = 72;
+const TITLE_PREFIX = 'Feedback: ';
 /**
  * Check if gh CLI is installed and available in PATH
  * Uses platform-appropriate command: 'where' on Windows, 'which' on Unix/macOS
@@ -69,18 +71,37 @@ Submitted via OpenSpec CLI
  * Format the feedback title
  */
 function formatTitle(message) {
-    return `Feedback: ${message}`;
+    const normalizedMessage = message.replace(/\s+/g, ' ').trim();
+    const title = `${TITLE_PREFIX}${normalizedMessage}`;
+    if (Array.from(title).length <= MAX_TITLE_LENGTH) {
+        return title;
+    }
+    const availableLength = MAX_TITLE_LENGTH - TITLE_PREFIX.length - 1;
+    let candidate = '';
+    let candidateLength = 0;
+    const segments = new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(normalizedMessage);
+    for (const { segment } of segments) {
+        const segmentLength = Array.from(segment).length;
+        if (candidateLength + segmentLength > availableLength) {
+            break;
+        }
+        candidate += segment;
+        candidateLength += segmentLength;
+    }
+    candidate = candidate.trimEnd();
+    const lastSpace = candidate.lastIndexOf(' ');
+    const summary = lastSpace > 0 ? candidate.slice(0, lastSpace) : candidate;
+    return `${TITLE_PREFIX}${summary}…`;
 }
 /**
  * Format the full feedback body
  */
-function formatBody(bodyText) {
-    const parts = [];
+function formatBody(message, bodyText) {
+    const parts = ['## Summary', '', message];
     if (bodyText) {
-        parts.push(bodyText);
-        parts.push(''); // Empty line before metadata
+        parts.push('', '## Details', '', bodyText);
     }
-    parts.push(generateMetadata());
+    parts.push('', generateMetadata());
     return parts.join('\n');
 }
 /**
@@ -216,7 +237,7 @@ export class FeedbackCommand {
     async execute(message, options) {
         // Format title and body once for all code paths
         const title = formatTitle(message);
-        const body = formatBody(options?.body);
+        const body = formatBody(message, options?.body);
         // Check if gh CLI is installed
         if (!isGhInstalled()) {
             handleFallback(title, body, 'missing');

package/dist/core/archive.js

@@ -46,6 +46,33 @@ export async function isRetirableSpec(specName, rebuilt) {
     return (errors.length > 0 &&
         errors.every((issue) => issue.message === VALIDATION_MESSAGES.SPEC_NO_REQUIREMENTS));
 }
+/**
+ * How much of one blocking line the abort is willing to show. A line long
+ * enough to fill the screen would push the way out of the abort off it.
+ */
+const UNACCOUNTED_LINE_MAX = 200;
+/**
+ * The first few lines a retirement would delete without being able to name
+ * them, quoted, with a count for the rest. Capped so a long tail cannot bury
+ * the rest of the abort.
+ *
+ * The lines are authored spec content printed verbatim to a terminal, so they
+ * get the same treatment as a change directory name (`describeChangeName`): a
+ * raw CR could forge a line of its own, and an ESC could redraw the screen.
+ * Truncation counts code points so a cut never leaves half a surrogate pair.
+ */
+function describeUnaccountedContent(lines) {
+    const shown = lines
+        .slice(0, 3)
+        .map((line) => {
+        const safe = [...line.replace(/[\u0000-\u001f\u007f]/g, '?')];
+        const clipped = safe.slice(0, UNACCOUNTED_LINE_MAX).join('');
+        return `"${safe.length > UNACCOUNTED_LINE_MAX ? `${clipped}\u2026` : clipped}"`;
+    })
+        .join(', ');
+    const rest = lines.length > 3 ? `, and ${lines.length - 3} more line(s)` : '';
+    return `${shown}${rest}`;
+}
 async function isRetirementCandidate(update, built, skipValidation) {
     return (!skipValidation &&
         built.noRequirementBlocks &&
@@ -1252,17 +1279,24 @@ export class ArchiveCommand {
                                 const specName = p.update.id;
                                 const report = await new Validator().validateSpecContent(specName, p.rebuilt);
                                 if (!report.valid) {
+                                    // This run is what emptied the capability, and "no
+                                    // requirements" is the only thing wrong with the spec that
+                                    // would be written - so retiring it is what archive would do,
+                                    // and what stands in the way of that is worth saying. Not
+                                    // always the *only* fix: a live requirement can be hiding in a
+                                    // second `## Requirements` section the validator never reaches,
+                                    // and merging the sections fixes that spec without a deletion.
+                                    const emptiedByThisRun = p.update.exists &&
+                                        p.counts.removed > 0 &&
+                                        p.noRequirementBlocks &&
+                                        (await isRetirableSpec(specName, p.rebuilt));
                                     // The dead end #1302 describes: the rebuilt spec is unwritable
                                     // for exactly one reason, and retiring the capability is the
                                     // fix - but only the author can authorise deleting the spec, so
                                     // the abort names the marker instead of just rejecting. Says so
                                     // only when the marker is the ONLY thing missing, so it never
                                     // sends someone after a marker that would not have helped.
-                                    const retirementWouldFix = !retirementDeclared &&
-                                        p.update.exists &&
-                                        p.counts.removed > 0 &&
-                                        (await isRetirementCandidate(p.update, p, false));
-                                    const retirementHint = retirementWouldFix
+                                    const retirementHint = !retirementDeclared && emptiedByThisRun && p.unaccountedContent.length === 0
                                         ? `This change removes the last requirement '${specName}' has. To retire the` +
                                             ` capability and delete its spec, add \`retire_capabilities: true\` to the` +
                                             ` change's ${METADATA_FILENAME} (alongside its \`schema:\`, which that file` +
@@ -1271,6 +1305,27 @@ export class ArchiveCommand {
                                                 ? ` The marker present now cannot be honored (${retirementMarker.invalidReason}).`
                                                 : '')
                                         : undefined;
+                                    // #1696: the marker is missing AND the file holds content a
+                                    // retirement cannot account for, so this abort said nothing at
+                                    // all - just "must have at least one requirement", with no way
+                                    // forward. It names the content instead of the marker, on
+                                    // purpose: the marker is only ever named when adding it would
+                                    // really let the archive through, and here it would not. Once
+                                    // the content is resolved the rerun names the marker.
+                                    const blockedRetirementHint = !retirementDeclared && emptiedByThisRun && p.unaccountedContent.length > 0
+                                        ? `This change removes the last requirement '${specName}' has, so the rebuilt ` +
+                                            `spec has none left and cannot be written. Retiring the capability is what ` +
+                                            `archive does instead, and it is refused while the spec holds content the ` +
+                                            `merge cannot safely account for and deleting the file would take with it: ` +
+                                            `${describeUnaccountedContent(p.unaccountedContent)}. ` +
+                                            'Move it into `## Purpose` or a canonical requirement, or delete the spec by hand, then rerun.' +
+                                            // Said here too, because an author looking at a marker they
+                                            // believe authorises the deletion should not have to clear
+                                            // the content first to find out it was never read.
+                                            (retirementMarker.invalidReason
+                                                ? ` The marker present now cannot be honored (${retirementMarker.invalidReason}).`
+                                                : '')
+                                        : undefined;
                                     // The marker was set and retirement was still refused. Saying
                                     // nothing left the author who did exactly what the docs asked
                                     // back in the original dead end with no signal that their
@@ -1282,13 +1337,13 @@ export class ArchiveCommand {
                                         (await isRetirableSpec(specName, p.rebuilt))
                                         ? `'${specName}' declares retire_capabilities, but the spec holds content the merge ` +
                                             `cannot safely account for and deleting the file would take with it: ` +
-                                            `${p.unaccountedContent.slice(0, 3).map((line) => `"${line}"`).join(', ')}` +
-                                            `${p.unaccountedContent.length > 3 ? `, and ${p.unaccountedContent.length - 3} more line(s)` : ''}. ` +
+                                            `${describeUnaccountedContent(p.unaccountedContent)}. ` +
                                             'Move it into `## Purpose` or a canonical requirement, or delete the spec by hand.'
                                         : undefined;
                                     if (json) {
                                         throw new ArchiveBlockedError('archive_spec_validation_failed', `Rebuilt spec for '${specName}' failed validation. No files were changed.`, refusalReason ??
                                             retirementHint ??
+                                            blockedRetirementHint ??
                                             `Run ${withStoreFlag(root, `openspec validate ${specName}`)} after fixing the change deltas.`);
                                     }
                                     console.log(chalk.red(`\nValidation errors in rebuilt spec for ${specName} (will not write changes):`));
@@ -1300,6 +1355,8 @@ export class ArchiveCommand {
                                     }
                                     if (retirementHint)
                                         console.log(chalk.yellow(`  → ${retirementHint}`));
+                                    if (blockedRetirementHint)
+                                        console.log(chalk.yellow(`  → ${blockedRetirementHint}`));
                                     if (refusalReason)
                                         console.log(chalk.yellow(`  → ${refusalReason}`));
                                     console.log('Aborted. No files were changed.');

package/dist/core/artifact-graph/instruction-loader.js

@@ -3,7 +3,7 @@ import * as path from 'node:path';
 import { getSchemaDir, resolveSchema, listSchemasWithInfo } from './resolver.js';
 import { ArtifactGraph } from './graph.js';
 import { detectCompleted } from './state.js';
-import { resolveArtifactOutputPath, resolveArtifactOutputs } from './outputs.js';
+import { isSpecsArtifactPath, resolveArtifactOutputPath, resolveArtifactOutputs, } from './outputs.js';
 import { readChangeMetadata, resolveSchemaForChange } from '../../utils/change-metadata.js';
 import { FileSystemUtils } from '../../utils/file-system.js';
 import { buildActionContext, buildNextSteps, summarizePlanningHome, } from '../change-status-policy.js';
@@ -92,12 +92,7 @@ export function loadChangeContext(projectRoot, changeName, schemaName, options =
     const skippedArtifacts = new Set();
     if (metadata?.skip_specs) {
         for (const artifact of graph.getAllArtifacts()) {
-            // A schema may write generates as './specs/...' - the globs treat that
-            // identically to 'specs/...', so the skip set must too, or validate
-            // would honor the marker while instructions tell the agent to create
-            // the very files the conflict gate polices.
-            const generates = artifact.generates.replace(/^(?:\.\/)+/, '');
-            if (generates.startsWith('specs/') && !completed.has(artifact.id)) {
+            if (isSpecsArtifactPath(artifact.generates) && !completed.has(artifact.id)) {
                 completed.add(artifact.id);
                 skippedArtifacts.add(artifact.id);
             }

package/dist/core/artifact-graph/outputs.d.ts

@@ -2,6 +2,10 @@
  * Checks if a path contains glob pattern characters.
  */
 export declare function isGlobPattern(pattern: string): boolean;
+/**
+ * Returns whether an artifact generates files under the change's specs/ tree.
+ */
+export declare function isSpecsArtifactPath(generates: string): boolean;
 export declare function resolveArtifactOutputPath(changeDir: string, generates: string): string;
 /**
  * Resolves an artifact's output path(s) to concrete files that currently exist.

package/dist/core/artifact-graph/outputs.js

@@ -8,6 +8,13 @@ import { FileSystemUtils } from '../../utils/file-system.js';
 export function isGlobPattern(pattern) {
     return pattern.includes('*') || pattern.includes('?') || pattern.includes('[');
 }
+/**
+ * Returns whether an artifact generates files under the change's specs/ tree.
+ */
+export function isSpecsArtifactPath(generates) {
+    const normalized = path.posix.normalize(FileSystemUtils.toPosixPath(generates));
+    return normalized.startsWith('specs/');
+}
 export function resolveArtifactOutputPath(changeDir, generates) {
     const outputPath = path.join(changeDir, generates);
     FileSystemUtils.assertPathWithin(changeDir, outputPath);

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

@@ -7,7 +7,8 @@ import type { ToolCommandAdapter } from '../types.js';
 /**
  * OpenCode adapter for command generation.
  * File path: .opencode/commands/opsx-<id>.md
- * Frontmatter: description
+ * Frontmatter: description. $ARGUMENTS is injected after the complete input
+ * contract because OpenCode only passes arguments through explicit placeholders.
  */
 export declare const opencodeAdapter: ToolCommandAdapter;
 //# sourceMappingURL=opencode.d.ts.map

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

@@ -5,10 +5,21 @@
  */
 import path from 'path';
 import { escapeYamlValue } from '../yaml.js';
+const OPENCODE_INPUT_BLOCK = /^\*\*Input\*\*:[^\r\n]*(?:\r?\n(?!\r?\n)[^\r\n]*)*/m;
+const OPENCODE_NO_INPUT = /^\*\*Input\*\*:\s*None required\b/im;
+const OPENCODE_ARGUMENT_PLACEHOLDER = /\$(?:ARGUMENTS\b|[1-9]\d*\b)/;
+function injectOpenCodeArgs(body) {
+    if (OPENCODE_ARGUMENT_PLACEHOLDER.test(body) || OPENCODE_NO_INPUT.test(body)) {
+        return body;
+    }
+    const eol = body.includes('\r\n') ? '\r\n' : '\n';
+    return body.replace(OPENCODE_INPUT_BLOCK, (input) => `${input}${eol}**Provided arguments**: $ARGUMENTS`);
+}
 /**
  * OpenCode adapter for command generation.
  * File path: .opencode/commands/opsx-<id>.md
- * Frontmatter: description
+ * Frontmatter: description. $ARGUMENTS is injected after the complete input
+ * contract because OpenCode only passes arguments through explicit placeholders.
  */
 export const opencodeAdapter = {
     toolId: 'opencode',
@@ -20,7 +31,7 @@ export const opencodeAdapter = {
 description: ${escapeYamlValue(content.description)}
 ---
 
-${content.body}
+${injectOpenCodeArgs(content.body)}
 `;
     },
 };

package/dist/core/completion-tip.d.ts

@@ -0,0 +1,15 @@
+export declare const COMPLETION_TIP_MESSAGE = "Tip: Run 'openspec completion install' for shell completions";
+export interface CompletionTipOptions {
+    /**
+     * Skip printing without marking the tip as seen, so it still appears on the
+     * user's first later run that can safely carry it. Used for runs nobody would
+     * read the tip from: JSON output, and stderr that is not a terminal.
+     */
+    silent?: boolean;
+}
+/**
+ * Print the completion tip once, the first time the CLI runs.
+ * Never throws — a hint must not break a command.
+ */
+export declare function maybeShowCompletionTip(options?: CompletionTipOptions): Promise<void>;
+//# sourceMappingURL=completion-tip.d.ts.map

package/dist/core/completion-tip.js

@@ -0,0 +1,133 @@
+/**
+ * First-run hint pointing users at opt-in shell completions.
+ *
+ * This hint used to be an npm `postinstall` script. Printing it from the CLI
+ * instead lets the package ship with no install scripts at all, so `npm install`
+ * no longer emits an `allow-scripts` warning. Completions stay opt-in: the tip
+ * only names the command, it never installs anything.
+ *
+ * The tip goes to stderr, never stdout, so it cannot contaminate piped command
+ * output.
+ *
+ * The tip is suppressed when:
+ * - CI is set (any value npm/telemetry would treat as CI)
+ * - OPENSPEC_NO_COMPLETIONS=1
+ * - completions are already installed, or the shell is one the installer would
+ *   reject
+ * - the caller passes `silent` — JSON runs, `openspec completion ...`, and
+ *   non-TTY runs, which are deferred rather than consumed (see `silent`)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { getGlobalConfigPath } from './global-config.js';
+import { isCiEnvironment } from '../utils/ci.js';
+import { detectShell } from '../utils/shell-detection.js';
+import { CompletionFactory } from './completions/factory.js';
+export const COMPLETION_TIP_MESSAGE = "Tip: Run 'openspec completion install' for shell completions";
+function isSuppressedByEnv() {
+    // isCiEnvironment, not a CI==='true' string check: providers set CI to "True",
+    // "yes", "on", and the tip should be as quiet in those builds as telemetry is.
+    return isCiEnvironment() || process.env.OPENSPEC_NO_COMPLETIONS === '1';
+}
+/**
+ * Whether the tip is worth showing, once we know it is owed and readable.
+ *
+ * "retire" consumes the tip without printing: the user either already has
+ * completions, or is on a shell `openspec completion install` would refuse.
+ *
+ * Without the installed check the tip tells people to install completions they
+ * installed long ago — including on the run right after `completion install`,
+ * whose own run only defers the tip. An undetected or unsupported shell retires
+ * it too: `completion install` exits 1 for those users, so pointing them at it
+ * is a dead end, and this tip is the only message about completions they would
+ * ever get.
+ *
+ * Not free: detectShell() forks `ps` to read the parent process (except on
+ * Windows), so this costs a spawn plus a stat. It runs only on interactive runs
+ * that still owe the tip, which is normally exactly one — but a config that
+ * cannot be written never records the flag, and then every interactive run pays
+ * it. On any unexpected error we show the tip rather than swallow it.
+ */
+async function decideTip() {
+    try {
+        const { shell } = detectShell();
+        if (!shell) {
+            return 'retire';
+        }
+        return (await CompletionFactory.createInstaller(shell).isInstalled())
+            ? 'retire'
+            : 'show';
+    }
+    catch {
+        return 'show';
+    }
+}
+/**
+ * Read the global config exactly as it sits on disk.
+ *
+ * Deliberately NOT `getGlobalConfig()`: that merges in defaults, and writing the
+ * merged result back would stamp `profile`/`delivery` into a file the user never
+ * set them in. `migrateIfNeeded` treats a raw `profile` as "already migrated",
+ * so that stamp would permanently suppress the one-time profile migration and
+ * cost users their installed workflow skills.
+ *
+ * Returns null when the file exists but cannot be read or parsed — a config we
+ * cannot understand is left strictly alone rather than overwritten.
+ */
+function readRawConfig() {
+    const configPath = getGlobalConfigPath();
+    if (!fs.existsSync(configPath)) {
+        return {};
+    }
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+/**
+ * Record the flag, re-reading the config first and replacing the file by rename.
+ *
+ * Deciding whether to show the tip costs a `ps` spawn and a stat, and a sibling
+ * `openspec` process can write the same file in that window — on a first run
+ * that is exactly when telemetry mints `anonymousId`. Re-reading here keeps the
+ * write down to this one key, and the rename keeps a reader from ever seeing a
+ * half-written config.
+ */
+function markTipSeen() {
+    const configPath = getGlobalConfigPath();
+    const current = readRawConfig() ?? {};
+    const tempPath = `${configPath}.${process.pid}.tmp`;
+    fs.mkdirSync(path.dirname(configPath), { recursive: true });
+    fs.writeFileSync(tempPath, JSON.stringify({ ...current, completionTipSeen: true }, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tempPath, configPath);
+}
+/**
+ * Print the completion tip once, the first time the CLI runs.
+ * Never throws — a hint must not break a command.
+ */
+export async function maybeShowCompletionTip(options = {}) {
+    if (isSuppressedByEnv()) {
+        return;
+    }
+    try {
+        const raw = readRawConfig();
+        if (raw === null || raw.completionTipSeen === true) {
+            return;
+        }
+        if (options.silent) {
+            return;
+        }
+        const decision = await decideTip();
+        // Record before printing: if the flag cannot be persisted, staying quiet
+        // beats reprinting the tip on every future run.
+        markTipSeen();
+        if (decision === 'show') {
+            console.error(`\n${COMPLETION_TIP_MESSAGE}`);
+        }
+    }
+    catch {
+        // Silent failure - a hint should never break the CLI.
+    }
+}
+//# sourceMappingURL=completion-tip.js.map

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

@@ -12,6 +12,11 @@ export const COMMAND_REGISTRY = [
                 description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
                 takesValue: true,
             },
+            {
+                name: 'language',
+                description: 'Write new OpenSpec artifacts in this language',
+                takesValue: true,
+            },
             {
                 name: 'force',
                 description: 'Auto-cleanup legacy files without prompting',

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

@@ -24,6 +24,17 @@ export interface CompletionInstaller {
         success: boolean;
         message: string;
     }>;
+    /**
+     * True when a completion script file is present at the install path.
+     *
+     * Deliberately just the script: bash and PowerShell also need a sourcing
+     * line in the user's profile, and `install()` adds that on a best-effort
+     * basis (it is skipped by OPENSPEC_NO_AUTO_CONFIG=1 or an unwritable
+     * profile, printing manual instructions instead). Someone in that state has
+     * already met the installer, so callers that use this to decide whether to
+     * *advertise* completions should not advertise again.
+     */
+    isInstalled(): Promise<boolean>;
 }
 /**
  * Factory for creating completion generators and installers

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

@@ -22,6 +22,13 @@ export declare class BashInstaller {
      * @returns Installation path
      */
     getInstallationPath(): Promise<string>;
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    isInstalled(): Promise<boolean>;
     /**
      * Backup an existing completion file if it exists
      *