@fission-ai/openspec 1.9.0 → 1.11.0

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

@@ -110,6 +110,21 @@ export class PowerShellInstaller {
         const profileDir = path.dirname(profilePath);
         return path.join(profileDir, 'OpenSpecCompletion.ps1');
     }
+    /**
+     * Check if a completion script is currently installed.
+     * Mirrors ZshInstaller.isInstalled so callers can ask any installer.
+     *
+     * @returns true if the completion script exists
+     */
+    async isInstalled() {
+        try {
+            // stat, not access: a directory at the install path is not a script.
+            return (await fs.stat(this.getInstallationPath())).isFile();
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Backup an existing completion file if it exists
      *

package/dist/core/completions/templates/fish-templates.d.ts

@@ -2,6 +2,6 @@
  * Static template strings for Fish completion scripts.
  * These are Fish-specific helper functions that never change.
  */
-export declare const FISH_STATIC_HELPERS = "# Helper function to check if a subcommand is present\nfunction __fish_openspec_using_subcommand\n    set -l cmd (commandline -opc)\n    set -e cmd[1]\n    for i in $argv\n        if contains -- $i $cmd\n            return 0\n        end\n    end\n    return 1\nend\n\nfunction __fish_openspec_no_subcommand\n    set -l cmd (commandline -opc)\n    test (count $cmd) -eq 1\nend";
+export declare const FISH_STATIC_HELPERS = "# Helper function to match the command path at the start of the invocation\nfunction __fish_openspec_using_command_path\n    set -l expected\n    set -l value_flags\n    set -l reading_value_flags 0\n    for argument in $argv\n        if test \"$argument\" = --\n            set reading_value_flags 1\n            continue\n        end\n        if test $reading_value_flags -eq 1\n            set -a value_flags $argument\n        else\n            set -a expected $argument\n        end\n    end\n\n    set -l tokens (commandline -opc)\n    set -e tokens[1]\n    set -l path\n    set -l skip 0\n    for token in $tokens\n        if test $skip -eq 1\n            set skip 0\n            continue\n        end\n        if test \"$token\" = --no-color\n            continue\n        end\n        if contains -- $token $value_flags\n            set skip 1\n            continue\n        end\n        if string match -q -- '-*' $token\n            continue\n        end\n        set -a path $token\n        if test (count $path) -eq (count $expected)\n            break\n        end\n    end\n    test (count $path) -eq (count $expected); or return 1\n    for index in (seq (count $expected))\n        test \"$path[$index]\" = \"$expected[$index]\"; or return 1\n    end\n    return 0\nend\n\nfunction __fish_openspec_no_subcommand\n    set -l tokens (commandline -opc)\n    set -e tokens[1]\n    for token in $tokens\n        if test \"$token\" != --no-color\n            return 1\n        end\n    end\n    return 0\nend\n\nfunction __fish_openspec_completing_option_value\n    set -l current (commandline -ct)\n    for option in $argv\n        if string match -q -- \"$option=*\" \"$current\"\n            return 0\n        end\n    end\n\n    set -l tokens (commandline -opc)\n    test (count $tokens) -gt 0; or return 1\n    contains -- $tokens[-1] $argv\nend\n\nfunction __fish_openspec_complete_attached_short_path\n    set -l option $argv[1]\n    set -l current (commandline -ct)\n    test \"$current\" != \"$option\"; or return 1\n    string match -q -- \"$option*\" \"$current\"; or return 1\n    set -l value (string sub -s (math (string length -- \"$option\") + 1) -- \"$current\")\n    __fish_complete_path \"$value\"\nend\n\nfunction __fish_openspec_positional_index\n    set -l target $argv[1]\n    set -l depth $argv[2]\n    set -l value_flags $argv[3..]\n    set -l tokens (commandline -opc)\n    set -e tokens[1]\n    set -l count 0\n    set -l options 1\n    set -l skip 0\n    for token in $tokens\n        if test $skip -eq 1\n            set skip 0\n            continue\n        end\n        if test $options -eq 1\n            if test \"$token\" = --\n                set options 0\n                continue\n            end\n            if contains -- $token $value_flags\n                set skip 1\n                continue\n            end\n            if string match -q -- '-*' $token\n                continue\n            end\n        end\n        set count (math $count + 1)\n    end\n    test $skip -eq 0; or return 1\n    test $count -eq (math $target + $depth)\nend";
 export declare const FISH_DYNAMIC_HELPERS = "# Dynamic completion helpers\n\nfunction __fish_openspec_changes\n    openspec __complete changes 2>/dev/null | while read -l id desc\n        printf '%s\\t%s\\n' \"$id\" \"$desc\"\n    end\nend\n\nfunction __fish_openspec_specs\n    openspec __complete specs 2>/dev/null | while read -l id desc\n        printf '%s\\t%s\\n' \"$id\" \"$desc\"\n    end\nend\n\nfunction __fish_openspec_items\n    __fish_openspec_changes\n    __fish_openspec_specs\nend\n\nfunction __fish_openspec_schemas\n    openspec __complete schemas 2>/dev/null | while read -l id desc\n        printf '%s\\t%s\\n' \"$id\" \"$desc\"\n    end\nend";
 //# sourceMappingURL=fish-templates.d.ts.map

package/dist/core/completions/templates/fish-templates.js

@@ -2,21 +2,118 @@
  * Static template strings for Fish completion scripts.
  * These are Fish-specific helper functions that never change.
  */
-export const FISH_STATIC_HELPERS = `# Helper function to check if a subcommand is present
-function __fish_openspec_using_subcommand
-    set -l cmd (commandline -opc)
-    set -e cmd[1]
-    for i in $argv
-        if contains -- $i $cmd
-            return 0
+export const FISH_STATIC_HELPERS = `# Helper function to match the command path at the start of the invocation
+function __fish_openspec_using_command_path
+    set -l expected
+    set -l value_flags
+    set -l reading_value_flags 0
+    for argument in $argv
+        if test "$argument" = --
+            set reading_value_flags 1
+            continue
+        end
+        if test $reading_value_flags -eq 1
+            set -a value_flags $argument
+        else
+            set -a expected $argument
         end
     end
-    return 1
+
+    set -l tokens (commandline -opc)
+    set -e tokens[1]
+    set -l path
+    set -l skip 0
+    for token in $tokens
+        if test $skip -eq 1
+            set skip 0
+            continue
+        end
+        if test "$token" = --no-color
+            continue
+        end
+        if contains -- $token $value_flags
+            set skip 1
+            continue
+        end
+        if string match -q -- '-*' $token
+            continue
+        end
+        set -a path $token
+        if test (count $path) -eq (count $expected)
+            break
+        end
+    end
+    test (count $path) -eq (count $expected); or return 1
+    for index in (seq (count $expected))
+        test "$path[$index]" = "$expected[$index]"; or return 1
+    end
+    return 0
 end
 
 function __fish_openspec_no_subcommand
-    set -l cmd (commandline -opc)
-    test (count $cmd) -eq 1
+    set -l tokens (commandline -opc)
+    set -e tokens[1]
+    for token in $tokens
+        if test "$token" != --no-color
+            return 1
+        end
+    end
+    return 0
+end
+
+function __fish_openspec_completing_option_value
+    set -l current (commandline -ct)
+    for option in $argv
+        if string match -q -- "$option=*" "$current"
+            return 0
+        end
+    end
+
+    set -l tokens (commandline -opc)
+    test (count $tokens) -gt 0; or return 1
+    contains -- $tokens[-1] $argv
+end
+
+function __fish_openspec_complete_attached_short_path
+    set -l option $argv[1]
+    set -l current (commandline -ct)
+    test "$current" != "$option"; or return 1
+    string match -q -- "$option*" "$current"; or return 1
+    set -l value (string sub -s (math (string length -- "$option") + 1) -- "$current")
+    __fish_complete_path "$value"
+end
+
+function __fish_openspec_positional_index
+    set -l target $argv[1]
+    set -l depth $argv[2]
+    set -l value_flags $argv[3..]
+    set -l tokens (commandline -opc)
+    set -e tokens[1]
+    set -l count 0
+    set -l options 1
+    set -l skip 0
+    for token in $tokens
+        if test $skip -eq 1
+            set skip 0
+            continue
+        end
+        if test $options -eq 1
+            if test "$token" = --
+                set options 0
+                continue
+            end
+            if contains -- $token $value_flags
+                set skip 1
+                continue
+            end
+            if string match -q -- '-*' $token
+                continue
+            end
+        end
+        set count (math $count + 1)
+    end
+    test $skip -eq 0; or return 1
+    test $count -eq (math $target + $depth)
 end`;
 export const FISH_DYNAMIC_HELPERS = `# Dynamic completion helpers
 

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

@@ -19,6 +19,10 @@ export interface FlagDefinition {
      * Whether the flag takes an argument value
      */
     takesValue?: boolean;
+    /**
+     * Completion type for the flag value.
+     */
+    completionType?: PositionalType;
     /**
      * Possible values for the flag (for completion suggestions)
      */

package/dist/core/config-prompts.js

@@ -9,16 +9,25 @@ export function serializeConfig(config) {
     // Schema (required)
     lines.push(`schema: ${config.schema}`);
     lines.push('');
-    // Context section with comments
-    lines.push('# Project context (optional)');
-    lines.push('# This is shown to AI when creating artifacts.');
-    lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
-    lines.push('# Example:');
-    lines.push('#   context: |');
-    lines.push('#     Tech stack: TypeScript, React, Node.js');
-    lines.push('#     We use conventional commits');
-    lines.push('#     Domain: e-commerce platform');
-    lines.push('');
+    if (config.context !== undefined) {
+        lines.push('context: |');
+        for (const line of config.context.split('\n')) {
+            lines.push(`  ${line}`);
+        }
+        lines.push('');
+    }
+    else {
+        // Context section with comments
+        lines.push('# Project context (optional)');
+        lines.push('# This is shown to AI when creating artifacts.');
+        lines.push('# Add your tech stack, conventions, style guides, domain knowledge, etc.');
+        lines.push('# Example:');
+        lines.push('#   context: |');
+        lines.push('#     Tech stack: TypeScript, React, Node.js');
+        lines.push('#     We use conventional commits');
+        lines.push('#     Domain: e-commerce platform');
+        lines.push('');
+    }
     // Rules section with comments
     lines.push('# Per-artifact rules (optional)');
     lines.push('# Add custom rules for specific artifacts.');

package/dist/core/config-schema.d.ts

@@ -19,6 +19,7 @@ export declare const GlobalConfigSchema: z.ZodObject<{
     telemetry: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$loose>>;
+    completionTipSeen: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$loose>;
 export type GlobalConfigType = z.infer<typeof GlobalConfigSchema>;
 /**

package/dist/core/config-schema.js

@@ -32,6 +32,8 @@ export const GlobalConfigSchema = z
     })
         .passthrough()
         .optional(),
+    // Runtime-managed (like telemetry.noticeSeen); not user-settable via CLI set.
+    completionTipSeen: z.boolean().optional(),
 })
     .passthrough();
 /**

package/dist/core/config.js

@@ -19,7 +19,12 @@ export const OPENSPEC_MARKERS = {
 };
 export const AI_TOOLS = [
     { name: 'Amazon Q Developer', value: 'amazon-q', available: true, successLabel: 'Amazon Q Developer', skillsDir: '.amazonq', requiresIdeRestart: true },
-    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agent', requiresIdeRestart: true },
+    // Antigravity moved workspace skills and workflows from `.agent` to the
+    // shared `.agents` root in v1.20.5. Detection keys off `.agent` and
+    // `.agents/workflows` rather than the bare `.agents` root: that root is
+    // shared with Codex, Zed, and the vendor-neutral target, so its presence
+    // alone says nothing about Antigravity.
+    { name: 'Antigravity', value: 'antigravity', available: true, successLabel: 'Antigravity', skillsDir: '.agents', legacySkillsDirs: ['.agent'], detectionPaths: ['.agent', '.agents/workflows'], requiresIdeRestart: true },
     { 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' },
@@ -54,6 +59,7 @@ export const AI_TOOLS = [
     { name: 'Rovo Dev CLI', value: 'rovodev', available: true, successLabel: 'Rovo Dev CLI', skillsDir: '.rovodev', detectionPaths: ['.rovodev/skills', '.rovodev'] },
     { name: 'Zoo Code', value: 'roocode', available: true, successLabel: 'Zoo Code', skillsDir: '.roo', requiresIdeRestart: true },
     { name: 'Trae', value: 'trae', available: true, successLabel: 'Trae', skillsDir: '.trae', requiresIdeRestart: true },
+    { name: 'Zed Agent', value: 'zed', available: true, successLabel: 'Zed Agent', skillsDir: '.agents', detectionPaths: ['.zed', '.agents/skills'] },
     { name: 'ZCode', value: 'zcode', available: true, successLabel: 'ZCode', skillsDir: '.zcode' },
     // Vendor-neutral target for assistants that read the shared `.agents` root.
     // Detection keys off `.agents/skills` rather than the bare root: frameworks use

package/dist/core/global-config.d.ts

@@ -26,6 +26,8 @@ export interface GlobalConfig {
     openers?: unknown;
     /** Anonymous usage analytics settings and identity. */
     telemetry?: TelemetryConfig;
+    /** Whether the first-run shell-completions tip has been shown. */
+    completionTipSeen?: boolean;
 }
 /**
  * Gets the global configuration directory path following XDG Base Directory Specification.

package/dist/core/init.d.ts

@@ -6,6 +6,7 @@
  */
 type InitCommandOptions = {
     tools?: string;
+    language?: string;
     force?: boolean;
     interactive?: boolean;
     profile?: string;
@@ -20,6 +21,7 @@ type InitCommandOptions = {
 };
 export declare class InitCommand {
     private readonly toolsArg?;
+    private readonly language?;
     private readonly force;
     private readonly interactiveOption?;
     private readonly profileOverride?;
@@ -85,6 +87,9 @@ export declare class InitCommand {
      * @returns Created, refreshed, and failed tools plus removed artifact counts
      */
     private generateSkillsAndCommands;
+    private normalizeLanguage;
+    private languageContext;
+    private assertLanguageCanBeApplied;
     private createConfig;
     private displaySuccessMessage;
     private startSpinner;

package/dist/core/init.js

@@ -10,7 +10,7 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { classifyOpenSpecDir, storePointerProblem } from './project-config.js';
+import { classifyOpenSpecDir, MAX_CONTEXT_SIZE, readProjectConfig, storePointerProblem, } from './project-config.js';
 import { findRepoPlanningRootSync } from './planning-home.js';
 import { getSkillReferenceTransformer, getTransformerForTool, usesNaturalLanguageSkillReferences } from '../utils/command-references.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME, resolveToolIdAlias, } from './config.js';
@@ -23,7 +23,7 @@ import { getToolsWithSkillsDir, getToolStates, getSkillTemplates, getCommandCont
 import { getGlobalConfig } from './global-config.js';
 import { getProfileWorkflows, ALL_WORKFLOWS } from './profiles.js';
 import { getAvailableTools } from './available-tools.js';
-import { writeSharedSkillTarget } from './shared-skill-target.js';
+import { resolveSharedSkillWriters, sharedSkillRootOwner, writeSharedSkillTarget, } from './shared-skill-target.js';
 import { migrateIfNeeded, migrateLegacyToolDirs, describeLegacyMigration, keptInPlaceNotice, hasMovableContent, scanInstalledWorkflows as scanInstalledWorkflowsShared } from './migration.js';
 import { resolveCommandSurfaceCapability, resolveCommandInvocation, shouldGenerateCommandsForTool, shouldGenerateSkillsForTool, shouldReconcileCommandFilesForTool, shouldRemoveSkillsForTool, } from './command-surface.js';
 import { writeCopilotCloudFiles, readCopilotCloudOptIn, hasExistingManagedCloudFiles, persistCopilotCloudOptIn, removeCopilotCloudFiles, findUnmanagedCloudFiles, listManagedCloudFiles, } from './github-copilot/cloud-agent.js';
@@ -33,6 +33,13 @@ const { version: OPENSPEC_VERSION } = require('../../package.json');
 // Constants
 // -----------------------------------------------------------------------------
 const DEFAULT_SCHEMA = 'spec-driven';
+function formatLanguageContext(language) {
+    return [
+        `Language: ${language}`,
+        `All artifacts must be written in ${language}.`,
+        'Keep OpenSpec structural headings and SHALL/MUST keywords in English.',
+    ].join('\n');
+}
 const PROGRESS_SPINNER = {
     interval: 80,
     frames: ['░░░', '▒░░', '▒▒░', '▒▒▒', '▓▒▒', '▓▓▒', '▓▓▓', '▒▓▓', '░▒▓'],
@@ -56,6 +63,7 @@ const WORKFLOW_TO_SKILL_DIR = {
 // -----------------------------------------------------------------------------
 export class InitCommand {
     toolsArg;
+    language;
     force;
     interactiveOption;
     profileOverride;
@@ -63,6 +71,7 @@ export class InitCommand {
     copilotCloudOption;
     constructor(options = {}) {
         this.toolsArg = options.tools;
+        this.language = this.normalizeLanguage(options.language);
         this.force = options.force ?? false;
         this.interactiveOption = options.interactive;
         this.profileOverride = options.profile;
@@ -97,6 +106,7 @@ export class InitCommand {
                 }
             }
         }
+        await this.assertLanguageCanBeApplied(projectPath, openspecPath);
         // Check for legacy artifacts and handle cleanup
         const deferredLegacyCleanup = await this.handleLegacyCleanup(projectPath, extendMode);
         // Migrate OpenSpec-managed skills left in renamed tool directories
@@ -516,14 +526,8 @@ export class InitCommand {
         return deduped;
     }
     validateTools(toolIds, toolStates, projectPath) {
-        const validatedTools = [];
-        const reconciledToolIds = toolIds.includes('codex') && toolIds.includes('agents')
-            ? toolIds.filter((toolId) => toolId !== 'agents')
-            : toolIds;
-        if (reconciledToolIds.length !== toolIds.length) {
-            console.log(chalk.dim('Codex and agents share .agents/skills; writing one tree with Codex and generic skill references.'));
-        }
-        for (const toolId of reconciledToolIds) {
+        const selectedTools = [];
+        for (const toolId of toolIds) {
             const tool = AI_TOOLS.find((t) => t.value === toolId);
             if (!tool) {
                 const validToolIds = getToolsWithSkillsDir();
@@ -533,6 +537,48 @@ export class InitCommand {
                 const validToolsWithSkills = getToolsWithSkillsDir();
                 throw new Error(`Tool '${toolId}' does not support skill generation.\nTools with skill generation support:\n  ${validToolsWithSkills.join('\n  ')}`);
             }
+            selectedTools.push(tool);
+        }
+        // A selected tool may share its physical skills root with an already
+        // configured owner. Include that owner in the refresh without dropping the
+        // selected tool: it may still have an independent command surface.
+        const generationTools = [...selectedTools];
+        const delivery = getGlobalConfig().delivery ?? 'both';
+        for (const selected of selectedTools) {
+            if (!selected.skillsDir)
+                continue;
+            const selectedOwner = selected.value === 'codex' ||
+                !shouldGenerateSkillsForTool(selected.value, delivery)
+                ? undefined
+                : sharedSkillRootOwner(projectPath, selected.value);
+            for (const candidate of AI_TOOLS) {
+                if (candidate.skillsDir === selected.skillsDir &&
+                    toolStates.get(candidate.value)?.configured &&
+                    candidate.value === selectedOwner &&
+                    !generationTools.includes(candidate)) {
+                    generationTools.push(candidate);
+                }
+            }
+        }
+        const skillWriters = resolveSharedSkillWriters(projectPath, generationTools);
+        const sharedRoots = new Map();
+        for (const tool of generationTools) {
+            if (!tool.skillsDir)
+                continue;
+            const group = sharedRoots.get(tool.skillsDir) ?? [];
+            group.push(tool);
+            sharedRoots.set(tool.skillsDir, group);
+        }
+        for (const [root, group] of sharedRoots) {
+            if (group.length < 2)
+                continue;
+            const owner = group.find((tool) => skillWriters.has(tool.value));
+            console.log(chalk.dim(`${group.map((tool) => tool.name).join(', ')} share ${root}/skills; writing one tree for ${owner?.value}.`));
+        }
+        const validatedTools = [];
+        for (const tool of generationTools) {
+            if (!toolSupportsSkills(tool))
+                continue;
             const preState = toolStates.get(tool.value);
             const skillsPath = resolveToolSkillsDir(projectPath, tool);
             const isGlobalSkillTarget = hasGlobalSkillTarget(tool);
@@ -545,6 +591,7 @@ export class InitCommand {
                 isGlobalSkillTarget,
                 wasConfigured: preState?.configured ?? false,
                 requiresIdeRestart: tool.requiresIdeRestart,
+                writesSkills: !tool.skillsDir || skillWriters.has(tool.value),
             });
         }
         return validatedTools;
@@ -618,7 +665,7 @@ export class InitCommand {
                 const shouldGenerateSkills = shouldGenerateSkillsForTool(tool.value, delivery);
                 const shouldGenerateCommands = shouldGenerateCommandsForTool(tool.value, delivery);
                 // Generate skill files if the selected delivery and tool capability allow skills
-                if (shouldGenerateSkills) {
+                if (shouldGenerateSkills && tool.writesSkills) {
                     // Create skill directories and SKILL.md files
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(tool.skillsPath, dirName);
@@ -632,7 +679,9 @@ export class InitCommand {
                     }
                     writeSharedSkillTarget(projectPath, tool.value);
                 }
-                if (shouldRemoveSkillsForTool(tool.value, delivery) && !tool.isGlobalSkillTarget) {
+                if (shouldRemoveSkillsForTool(tool.value, delivery) &&
+                    tool.writesSkills &&
+                    !tool.isGlobalSkillTarget) {
                     removedSkillCount += await this.removeSkillDirs(tool.skillsRoot, tool.skillsPath);
                     // Retain an explicit selection even when this delivery mode produces
                     // no skills, so a divergent legacy sibling cannot reclaim ownership.
@@ -699,6 +748,53 @@ export class InitCommand {
     // ═══════════════════════════════════════════════════════════
     // CONFIG FILE
     // ═══════════════════════════════════════════════════════════
+    normalizeLanguage(language) {
+        if (language === undefined)
+            return undefined;
+        const normalized = language.trim();
+        if (!normalized) {
+            throw new Error('The --language option requires a non-empty value.');
+        }
+        if (/\p{Cc}|\p{Bidi_Control}|[\u200B\u2028\u2029\uFEFF]/u.test(normalized)) {
+            throw new Error('The --language option must be a single line without control or invisible formatting characters.');
+        }
+        const serializedContext = `${formatLanguageContext(normalized)}\n`;
+        if (Buffer.byteLength(serializedContext, 'utf8') > MAX_CONTEXT_SIZE) {
+            throw new Error(`The --language option is too long for OpenSpec's ${MAX_CONTEXT_SIZE / 1024}KB project context limit.`);
+        }
+        return normalized;
+    }
+    languageContext() {
+        if (!this.language)
+            return undefined;
+        return formatLanguageContext(this.language);
+    }
+    async assertLanguageCanBeApplied(projectPath, openspecPath) {
+        const languageContext = this.languageContext();
+        if (!languageContext)
+            return;
+        const configPath = path.join(openspecPath, 'config.yaml');
+        const hasConfig = fs.existsSync(configPath) ||
+            fs.existsSync(path.join(openspecPath, 'config.yml'));
+        if (!hasConfig) {
+            try {
+                FileSystemUtils.assertProjectArtifactPath(projectPath, configPath);
+            }
+            catch (error) {
+                const reason = error instanceof Error ? `: ${error.message}` : '';
+                throw new Error(`Cannot create openspec/config.yaml for --language${reason}`);
+            }
+            if (!(await FileSystemUtils.canWriteFile(configPath))) {
+                throw new Error('Cannot create openspec/config.yaml for --language: the destination is not writable.');
+            }
+            return;
+        }
+        const existingContext = readProjectConfig(projectPath)?.context;
+        if (existingContext?.includes(languageContext))
+            return;
+        throw new Error('--language does not overwrite an existing OpenSpec config. ' +
+            'Add the language instruction to its context field instead.');
+    }
     async createConfig(openspecPath, extendMode) {
         const configPath = path.join(openspecPath, 'config.yaml');
         const configYmlPath = path.join(openspecPath, 'config.yml');
@@ -708,12 +804,19 @@ export class InitCommand {
             return 'exists';
         }
         try {
-            const yamlContent = serializeConfig({ schema: DEFAULT_SCHEMA });
+            const yamlContent = serializeConfig({
+                schema: DEFAULT_SCHEMA,
+                context: this.languageContext(),
+            });
             FileSystemUtils.assertProjectArtifactPath(path.dirname(openspecPath), configPath);
             await FileSystemUtils.writeFile(configPath, yamlContent);
             return 'created';
         }
-        catch {
+        catch (error) {
+            if (this.language) {
+                const reason = error instanceof Error ? `: ${error.message}` : '';
+                throw new Error(`Failed to create openspec/config.yaml for --language${reason}`);
+            }
             return 'skipped';
         }
     }

package/dist/core/legacy-cleanup.js

@@ -51,6 +51,12 @@ export const LEGACY_SLASH_COMMAND_PATHS = {
     'factory': { type: 'files', pattern: '.factory/commands/openspec-*.md' },
     'opencode': { type: 'files', pattern: ['.opencode/command/opsx-*.md', '.opencode/command/openspec-*.md'] },
     'continue': { type: 'files', pattern: '.continue/prompts/openspec-*.prompt' },
+    // Scoped to the pre-opsx filenames under Antigravity's former `.agent` root.
+    // The current `.agents/workflows/opsx-*.md` files postdate that rename, and
+    // the `.agent` copies of them are relocated by LEGACY_TOOL_ROOTS, which
+    // preserves a customized file instead of deleting it. These patterns are
+    // matched in every project, so a shared root like `.agents` is not listed:
+    // OpenSpec never wrote `openspec-*` files there, and a user might have.
     'antigravity': { type: 'files', pattern: '.agent/workflows/openspec-*.md' },
     'iflow': { type: 'files', pattern: '.iflow/commands/openspec-*.md' },
     'qwen': { type: 'files', pattern: ['.qwen/commands/opsx-*.toml', '.qwen/commands/openspec-*.toml'] },

package/dist/core/migration.js

@@ -34,6 +34,12 @@ export const LEGACY_TOOL_ROOTS = {
     // Codex now reads the canonical shared .agents root. Generate the current
     // replacement first so a divergent legacy file is preserved, not overwritten.
     codex: [{ root: '.codex', needsConsent: false, timing: 'after-generation' }],
+    // Antigravity v1.20.5 moved workspace skills and workflows to `.agents` and
+    // reads the old `.agent` root only as a fallback, so leaving a copy there
+    // just gives the agent two of everything. Same after-generation timing as
+    // Codex: the replacement is written first, so a divergent legacy file is
+    // reported and kept rather than overwritten.
+    antigravity: [{ root: '.agent', needsConsent: false, timing: 'after-generation' }],
 };
 function classifyManagedFile(source, destination) {
     if (isSamePath(source, destination))
@@ -121,7 +127,7 @@ function collectLegacyToolMigrations(projectPath, apply, toolIds, timing = 'befo
                 continue;
             }
             const skills = migrateSkillDirs(projectPath, tool.skillsDir, legacy.root, apply, legacyTiming === 'after-generation');
-            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply);
+            const commands = migrateCommandFiles(projectPath, tool, legacy.root, apply, legacyTiming === 'after-generation');
             if (apply) {
                 removeDirIfEmpty(path.join(legacyRootPath, 'skills'));
                 removeDirIfEmpty(path.join(legacyRootPath, 'workflows'));
@@ -201,7 +207,7 @@ function migrateSkillDirs(projectPath, currentRoot, legacyRoot, apply, requireDe
     }
     return { moved, kept };
 }
-function migrateCommandFiles(projectPath, tool, legacyRoot, apply) {
+function migrateCommandFiles(projectPath, tool, legacyRoot, apply, requireDestination = false) {
     const adapter = CommandAdapterRegistry.get(tool.value);
     if (!adapter || !tool.skillsDir)
         return { moved: 0, kept: 0 };
@@ -212,10 +218,16 @@ function migrateCommandFiles(projectPath, tool, legacyRoot, apply) {
         const legacyPath = legacyCommandPath(currentPath, tool.skillsDir, legacyRoot);
         if (!legacyPath)
             continue;
-        const source = path.join(projectPath, legacyPath);
+        const source = FileSystemUtils.resolveProjectArtifactPath(projectPath, legacyPath);
         if (!fs.existsSync(source))
             continue;
-        const destination = path.join(projectPath, currentPath);
+        const destination = FileSystemUtils.resolveProjectArtifactPath(projectPath, currentPath.split(/[\\/]/).join(path.sep));
+        // An after-generation move runs once the tool has written its replacement.
+        // No replacement means this command is not one OpenSpec installs now — a
+        // skills-only delivery or a deselected workflow — so relocating the legacy
+        // file would resurrect it under the current root.
+        if (requireDestination && !fs.existsSync(destination))
+            continue;
         if (!areProjectArtifacts(projectPath, source, destination)) {
             console.warn(`Skipping legacy ${legacyPath} migration because it resolves outside this project.`);
             continue;
@@ -332,7 +344,7 @@ function removeDirIfEmpty(dirPath) {
         // Missing or non-empty directory — nothing to do
     }
 }
-function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills = false) {
+function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacyRoots = false) {
     const installed = new Set();
     let hasSkills = false;
     let hasCommands = false;
@@ -345,7 +357,7 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills
         }
         else if (isSharedSkillTargetActive(projectPath, tool.value)) {
             skillsDirs.push(resolveToolSkillsDir(projectPath, tool));
-            if (includeLegacySkills) {
+            if (includeLegacyRoots) {
                 skillsDirs.push(...(tool.legacySkillsDirs ?? []).map((root) => path.join(projectPath, root, 'skills')));
             }
         }
@@ -362,14 +374,32 @@ function scanInstalledWorkflowArtifacts(projectPath, tools, includeLegacySkills
         const adapter = CommandAdapterRegistry.get(tool.value);
         if (!adapter)
             continue;
+        // A root the tool has moved away from still holds the command files the
+        // user installed there. Reading only the current root would report a
+        // commands install as skills-only, and delivery inferred from that answer
+        // deletes those commands on the next update.
+        const legacyRoots = includeLegacyRoots
+            ? (LEGACY_TOOL_ROOTS[tool.value] ?? []).map((legacy) => legacy.root)
+            : [];
         for (const workflowId of ALL_WORKFLOWS) {
             const commandPath = adapter.getFilePath(workflowId);
-            const fullPath = path.isAbsolute(commandPath)
-                ? commandPath
-                : path.join(projectPath, commandPath);
-            if (fs.existsSync(fullPath)) {
-                installed.add(workflowId);
-                hasCommands = true;
+            const candidates = [commandPath];
+            if (tool.skillsDir) {
+                for (const root of legacyRoots) {
+                    const legacyPath = legacyCommandPath(commandPath, tool.skillsDir, root);
+                    if (legacyPath)
+                        candidates.push(legacyPath);
+                }
+            }
+            for (const candidate of candidates) {
+                const fullPath = path.isAbsolute(candidate)
+                    ? candidate
+                    : path.join(projectPath, candidate);
+                if (fs.existsSync(fullPath)) {
+                    installed.add(workflowId);
+                    hasCommands = true;
+                    break;
+                }
             }
         }
     }

package/dist/core/parsers/requirement-blocks.d.ts

@@ -37,6 +37,7 @@ export interface DeltaPlan {
     added: RequirementBlock[];
     modified: RequirementBlock[];
     removed: string[];
+    removedBlocks: RequirementBlock[];
     renamed: Array<{
         from: string;
         to: string;