@fission-ai/openspec 1.14.0 → 1.14.2

package/README.md

@@ -33,11 +33,6 @@ Our philosophy:
 → scalable from personal projects to enterprises
 ```
 
-> [!TIP]
-> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
->
-> 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.
 </p>
@@ -112,13 +107,13 @@ OpenSpec is built with OpenSpec — browse this repo's live [specs](openspec/spe
 
 Solo, OpenSpec keeps you and your AI honest on a single repo. On a team, the hard part moves: a feature spans the API server, the web app, and a shared library; requirements are owned by one team and consumed by others; planning starts before any code exists.
 
-**[Stores](docs/stores-beta/user-guide.md)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
+**[Stores](https://openspec.dev/docs/stores)** are the answer — planning in a repo of its own. The same `openspec/` shape you already know (specs and changes), shared by `git push` like anything else. One source of truth your whole team and every coding agent can read, across every repo.
 
 - **Cross-repo features** — one change, one plan, even when the code lands in three repos.
 - **Shared requirements** — a platform team owns the specs; product teams reference them read-only, right where their coding agent can read them. No drifting wiki.
 - **Plan before code** — capture the plan in the store now; the code repos catch up later.
 
-> Stores are in **beta**. Start with the [Stores User Guide](docs/stores-beta/user-guide.md).
+> Stores are in **beta**. Start with the [Stores guide](https://openspec.dev/docs/stores).
 
 ## Quick Start
 
@@ -143,44 +138,33 @@ cd your-project
 openspec init
 ```
 
-> **Want your AI to do it?** Paste the [setup prompt](docs-lab/start/installation.md#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
+> **Want your AI to do it?** Paste the [setup prompt](https://openspec.dev/docs/installation#install-with-your-ai-assistant) into your coding assistant — it installs the CLI, runs `openspec init`, and verifies the result.
 
 Now talk to your AI:
 
-- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. ([Explore guide](docs/explore.md))
+- **Not sure what to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before any code gets written. ([Quickstart](https://openspec.dev/docs/quickstart))
 - **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>`.
 
 Both are in the default profile. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
 
-`/opsx:propose` is the canonical name; your tool may spell it `/opsx-propose` (Cursor, GitHub Copilot), `@opsx-propose` (Amazon Q) or `$openspec-propose` (Codex). `openspec init` prints the right form for the tools you picked — see [How To Invoke](docs/supported-tools.md#how-to-invoke).
+`/opsx:propose` is the canonical name; your tool may spell it `/opsx-propose` (Cursor, GitHub Copilot), `@opsx-propose` (Amazon Q) or `$openspec-propose` (Codex). `openspec init` prints the right form for the tools you picked — see [Supported Tools](https://openspec.dev/docs/supported-tools).
 
 > [!NOTE]
-> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 30+ tools and growing.
+> Not sure if your tool is supported? [View the full list](https://openspec.dev/docs/supported-tools) – we support 30+ tools and growing.
 >
-> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](docs-lab/start/installation.md).
+> Also works with Homebrew, pnpm, yarn, bun, and Nix. [See installation options](https://openspec.dev/docs/installation).
 
 ## Docs
 
-**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
-
-→ **[Getting Started](docs/getting-started.md)**: first steps<br>
-→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
-→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
-→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
-→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
-→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
-→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
-→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
-→ **[Commands](docs/commands.md)**: slash commands & skills<br>
-→ **[CLI](docs/cli.md)**: terminal reference<br>
-→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<br>
-→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
-→ **[Concepts](docs/concepts.md)**: how it all fits<br>
-→ **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
-→ **[Customization](docs/customization.md)**: make it yours<br>
-→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec<br>
-→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
+Full documentation lives at **[openspec.dev/docs](https://openspec.dev/docs)**.
 
+→ **[Quickstart](https://openspec.dev/docs/quickstart)**: your first change, start to finish<br>
+→ **[Set up your project](https://openspec.dev/docs/setup)**: what `openspec init` installs<br>
+→ **[CLI](https://openspec.dev/docs/cli)**: terminal reference<br>
+→ **[Supported Tools](https://openspec.dev/docs/supported-tools)**: tool integrations & install paths<br>
+→ **[Customize](https://openspec.dev/docs/customize)**: profiles, project config, and schemas<br>
+→ **[Stores](https://openspec.dev/docs/stores)**: plan in a separate repo, shared across your team (beta)<br>
+→ **[Community Showcase](docs/community.md)**: projects and resources built with and for OpenSpec
 
 ## Community schemas
 

package/dist/cli/commands/config.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * Register the config command and all its subcommands.
+ *
+ * @param program - The Commander program instance
+ */
+export declare function registerConfigCommand(program: Command): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/cli/commands/config.js

@@ -0,0 +1,88 @@
+/**
+ * Register the config command and all its subcommands.
+ *
+ * @param program - The Commander program instance
+ */
+export function registerConfigCommand(program) {
+    const configCmd = program
+        .command('config')
+        .description('View and modify global OpenSpec configuration')
+        .option('--scope <scope>', 'Config scope (only "global" supported currently)')
+        .hook('preAction', (thisCommand) => {
+        const opts = thisCommand.opts();
+        if (opts.scope && opts.scope !== 'global') {
+            console.error('Error: Project-local config is not yet implemented');
+            process.exit(1);
+        }
+    });
+    // config path
+    configCmd
+        .command('path')
+        .description('Show config file location')
+        .action(async () => {
+        const { configPathCommand } = await import('../../commands/config.js');
+        configPathCommand();
+    });
+    // config list
+    configCmd
+        .command('list')
+        .description('Show all current settings')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        const { configListCommand } = await import('../../commands/config.js');
+        configListCommand(options);
+    });
+    // config get
+    configCmd
+        .command('get <key>')
+        .description('Get a specific value (raw, scriptable)')
+        .action(async (key) => {
+        const { configGetCommand } = await import('../../commands/config.js');
+        configGetCommand(key);
+    });
+    // config set
+    configCmd
+        .command('set <key> <value>')
+        .description('Set a value (auto-coerce types)')
+        .option('--string', 'Force value to be stored as string')
+        .option('--allow-unknown', 'Allow setting unknown keys')
+        .action(async (key, value, options) => {
+        const { configSetCommand } = await import('../../commands/config.js');
+        configSetCommand(key, value, options);
+    });
+    // config unset
+    configCmd
+        .command('unset <key>')
+        .description('Remove a key (revert to default)')
+        .action(async (key) => {
+        const { configUnsetCommand } = await import('../../commands/config.js');
+        configUnsetCommand(key);
+    });
+    // config reset
+    configCmd
+        .command('reset')
+        .description('Reset configuration to defaults')
+        .option('--all', 'Reset all configuration (required)')
+        .option('-y, --yes', 'Skip confirmation prompts')
+        .action(async (options) => {
+        const { configResetCommand } = await import('../../commands/config.js');
+        await configResetCommand(options);
+    });
+    // config edit
+    configCmd
+        .command('edit')
+        .description('Open config in $EDITOR')
+        .action(async () => {
+        const { configEditCommand } = await import('../../commands/config.js');
+        await configEditCommand();
+    });
+    // config profile [preset]
+    configCmd
+        .command('profile [preset]')
+        .description('Configure workflow profile (interactive picker or preset shortcut)')
+        .action(async (preset) => {
+        const { configProfileCommand } = await import('../../commands/config.js');
+        await configProfileCommand(preset);
+    });
+}
+//# sourceMappingURL=config.js.map

package/dist/cli/commands/context.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerContextCommand(program: Command): void;
+//# sourceMappingURL=context.d.ts.map

package/dist/cli/commands/context.js

@@ -0,0 +1,20 @@
+import { Option } from 'commander';
+import { COMMAND_REGISTRY } from '../../core/completions/command-registry.js';
+import { COMMON_FLAGS } from '../../core/completions/shared-flags.js';
+export function registerContextCommand(program) {
+    const description = COMMAND_REGISTRY.find((entry) => entry.name === 'context')?.description ??
+        'Print the working context for the resolved OpenSpec root';
+    program
+        .command('context')
+        .description(description)
+        .option('--store <id>', COMMON_FLAGS.store.description)
+        .addOption(new Option('--store-path <path>', 'Removed; register the store and use --store').hideHelp())
+        .option('--json', 'Output the agent brief as JSON')
+        .option('--code-workspace <path>', 'Also write a VS Code workspace file for the set')
+        .option('--force', 'Overwrite an existing --code-workspace file')
+        .action(async (options) => {
+        const { contextCommand } = await import('../../commands/context.js');
+        await contextCommand(options);
+    });
+}
+//# sourceMappingURL=context.js.map

package/dist/cli/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerDoctorCommand(program: Command): void;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/cli/commands/doctor.js

@@ -0,0 +1,18 @@
+import { Option } from 'commander';
+import { COMMAND_REGISTRY } from '../../core/completions/command-registry.js';
+import { COMMON_FLAGS } from '../../core/completions/shared-flags.js';
+export function registerDoctorCommand(program) {
+    const description = COMMAND_REGISTRY.find((entry) => entry.name === 'doctor')?.description ??
+        'Report relationship health for the resolved OpenSpec root';
+    program
+        .command('doctor')
+        .description(description)
+        .option('--store <id>', COMMON_FLAGS.store.description)
+        .addOption(new Option('--store-path <path>', 'Removed; register the store and use --store').hideHelp())
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        const { doctorCommand } = await import('../../commands/doctor.js');
+        await doctorCommand(options);
+    });
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/schema.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+/**
+ * Register the schema command and all its subcommands.
+ */
+export declare function registerSchemaCommand(program: Command): void;
+//# sourceMappingURL=schema.d.ts.map

package/dist/cli/commands/schema.js

@@ -0,0 +1,57 @@
+/**
+ * Register the schema command and all its subcommands.
+ */
+export function registerSchemaCommand(program) {
+    const schemaCmd = program
+        .command('schema')
+        .description('Manage workflow schemas [experimental]');
+    // Experimental warning
+    schemaCmd.hook('preAction', () => {
+        console.error('Note: Schema commands are experimental and may change.');
+    });
+    // schema which
+    schemaCmd
+        .command('which [name]')
+        .description('Show where a schema resolves from')
+        .option('--json', 'Output as JSON')
+        .option('--all', 'List all schemas with their resolution sources')
+        .action(async (name, options) => {
+        const { schemaWhichCommand } = await import('../../commands/schema.js');
+        await schemaWhichCommand(name, options);
+    });
+    // schema validate
+    schemaCmd
+        .command('validate [name]')
+        .description('Validate a schema structure and templates')
+        .option('--json', 'Output as JSON')
+        .option('--verbose', 'Show detailed validation steps')
+        .action(async (name, options) => {
+        const { schemaValidateCommand } = await import('../../commands/schema.js');
+        await schemaValidateCommand(name, options);
+    });
+    // schema fork
+    schemaCmd
+        .command('fork <source> [name]')
+        .description('Copy an existing schema to project for customization')
+        .option('--json', 'Output as JSON')
+        .option('--force', 'Overwrite existing destination')
+        .action(async (source, name, options) => {
+        const { schemaForkCommand } = await import('../../commands/schema.js');
+        await schemaForkCommand(source, name, options);
+    });
+    // schema init
+    schemaCmd
+        .command('init <name>')
+        .description('Create a new project-local schema')
+        .option('--json', 'Output as JSON')
+        .option('--description <text>', 'Schema description')
+        .option('--artifacts <list>', 'Comma-separated artifact IDs (proposal,specs,design,tasks)')
+        .option('--default', 'Set as project default schema')
+        .option('--no-default', 'Do not prompt to set as default')
+        .option('--force', 'Overwrite existing schema')
+        .action(async (name, options) => {
+        const { schemaInitCommand } = await import('../../commands/schema.js');
+        await schemaInitCommand(name, options);
+    });
+}
+//# sourceMappingURL=schema.js.map

package/dist/cli/commands/spec.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerSpecCommand(rootProgram: Command): Command;
+//# sourceMappingURL=spec.d.ts.map

package/dist/cli/commands/spec.js

@@ -0,0 +1,42 @@
+export function registerSpecCommand(rootProgram) {
+    const specCommand = rootProgram
+        .command('spec')
+        .description('Manage and view OpenSpec specifications');
+    // Deprecation notice for noun-based commands
+    specCommand.hook('preAction', () => {
+        console.error('Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").');
+    });
+    specCommand
+        .command('show [spec-id]')
+        .description('Display a specific specification')
+        .option('--json', 'Output as JSON')
+        .option('--requirements', 'JSON only: Show only requirements (exclude scenarios)')
+        .option('--no-scenarios', 'JSON only: Exclude scenario content')
+        .option('-r, --requirement <id>', 'JSON only: Show specific requirement by ID (1-based)')
+        .option('--no-interactive', 'Disable interactive prompts')
+        .action(async (specId, options) => {
+        const { specShowCommand } = await import('../../commands/spec.js');
+        await specShowCommand(specId, options);
+    });
+    specCommand
+        .command('list')
+        .description('List all available specifications')
+        .option('--json', 'Output as JSON')
+        .option('--long', 'Show id and title with counts')
+        .action(async (options) => {
+        const { specListCommand } = await import('../../commands/spec.js');
+        await specListCommand(options);
+    });
+    specCommand
+        .command('validate [spec-id]')
+        .description('Validate a specification structure')
+        .option('--strict', 'Enable strict validation mode')
+        .option('--json', 'Output validation report as JSON')
+        .option('--no-interactive', 'Disable interactive prompts')
+        .action(async (specId, options) => {
+        const { specValidateCommand } = await import('../../commands/spec.js');
+        await specValidateCommand(specId, options);
+    });
+    return specCommand;
+}
+//# sourceMappingURL=spec.js.map

package/dist/cli/commands/store.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerStoreCommand(program: Command): void;
+//# sourceMappingURL=store.d.ts.map

package/dist/cli/commands/store.js

@@ -0,0 +1,130 @@
+import { COMMAND_REGISTRY } from '../../core/completions/command-registry.js';
+import { printJson } from '../../commands/shared-output.js';
+async function loadStoreCommand() {
+    const { StoreCommand } = await import('../../commands/store.js');
+    return new StoreCommand();
+}
+export function registerStoreCommand(program) {
+    // One source for the locked group one-liner: the completions registry
+    // entry, which shell completion scripts also consume.
+    const storeGroupDescription = COMMAND_REGISTRY.find((entry) => entry.name === 'store')?.description ??
+        'Create and manage stores - standalone OpenSpec repos you register on this machine';
+    const store = program.command('store').description(storeGroupDescription);
+    store
+        .command('setup [id]')
+        .description('Create and register a local store')
+        .option('--path <path>', 'Folder where the store should live (for example ~/openspec/<id>)')
+        .option('--init-git', 'Initialize a Git repository with an initial commit (default)')
+        .option('--no-init-git', 'Skip every Git action: no init, no initial commit')
+        .option('--remote <url>', 'Canonical clone source recorded in store.yaml')
+        .option('--json', 'Output as JSON')
+        .action(async (id, options) => {
+        const storeCommand = await loadStoreCommand();
+        await storeCommand.setup(id, options);
+    });
+    store
+        .command('register [path]')
+        .description('Register an existing local store')
+        .option('--id <id>', 'Store id; defaults to metadata or folder name')
+        .option('--yes', 'Confirm creating store identity metadata for a healthy OpenSpec root')
+        .option('--json', 'Output as JSON')
+        .action(async (inputPath, options) => {
+        const storeCommand = await loadStoreCommand();
+        await storeCommand.register(inputPath, options);
+    });
+    store
+        .command('unregister <id>')
+        .description('Forget a local store registration without deleting files')
+        .option('--json', 'Output as JSON')
+        .action(async (id, options) => {
+        const storeCommand = await loadStoreCommand();
+        await storeCommand.unregister(id, options);
+    });
+    store
+        .command('remove <id>')
+        .description('Forget a local store registration and delete its local folder')
+        .option('--yes', 'Confirm local store folder deletion')
+        .option('--json', 'Output as JSON')
+        .action(async (id, options) => {
+        const storeCommand = await loadStoreCommand();
+        await storeCommand.remove(id, options);
+    });
+    store
+        .command('list')
+        .alias('ls')
+        .description('List locally registered stores')
+        .option('--json', 'Output as JSON')
+        .action(async (options) => {
+        const storeCommand = await loadStoreCommand();
+        await storeCommand.list(options);
+    });
+    store
+        .command('doctor [id]')
+        .description('Check local store registration and metadata')
+        .option('--json', 'Output as JSON')
+        .action(async (id, options) => {
+        const storeCommand = await loadStoreCommand();
+        await storeCommand.doctor(id, options);
+    });
+    const lifecycleRedirects = new Set(COMMAND_REGISTRY.filter((entry) => entry.flags.some((flag) => flag.name === 'store') ||
+        (entry.subcommands ?? []).some((subcommand) => subcommand.flags.some((flag) => flag.name === 'store'))).map((entry) => entry.name));
+    const storeSubcommandsLine = store.commands
+        .map((subcommand) => {
+        const aliases = subcommand.aliases();
+        return aliases.length > 0 ? `${subcommand.name()} (${aliases.join(', ')})` : subcommand.name();
+    })
+        .join(', ');
+    // One group action owns missing AND unknown subcommands. Known
+    // subcommands dispatch above; everything else — including a bare
+    // `store --json` with no operand — lands here, so the handler owns the
+    // entire message and exit path (same text for human and --json). The
+    // permissive flags route unknown operands/options here instead of
+    // letting Commander emit a raw error before the action runs. We detect
+    // `--json` in the residual args rather than declaring a group option,
+    // which would otherwise shadow each subcommand's own `--json` flag.
+    store.allowExcessArguments(true);
+    store.allowUnknownOption(true);
+    store.action(() => {
+        const operands = store.args;
+        // Flag values are indistinguishable from operands without a full
+        // parse, so the verbatim echo only applies to plain-operand input.
+        const attempted = operands.filter((operand) => !operand.startsWith('-'));
+        const hasFlagLikeToken = operands.some((operand) => operand.startsWith('-'));
+        // The agent contract: --json failures emit one JSON document.
+        if (operands.includes('--json')) {
+            const message = attempted.length > 0
+                ? `Unknown command '${attempted[0]}' for 'openspec store'. Store subcommands: ${storeSubcommandsLine}.`
+                : `Missing subcommand for 'openspec store'. Store subcommands: ${storeSubcommandsLine}.`;
+            printJson({
+                status: [
+                    {
+                        severity: 'error',
+                        code: 'unknown_store_subcommand',
+                        message,
+                        fix: 'Run a store subcommand, or use the lifecycle command with --store <id>.',
+                    },
+                ],
+            });
+            process.exitCode = 1;
+            return;
+        }
+        let example = 'openspec new change <change-id> --store <id>';
+        if (!hasFlagLikeToken && attempted.length > 0 && lifecycleRedirects.has(attempted[0])) {
+            if (attempted[0] === 'new') {
+                const changeId = attempted[1] === 'change' && attempted[2] ? attempted[2] : '<change-id>';
+                example = `openspec new change ${changeId} --store <id>`;
+            }
+            else {
+                example = `openspec ${attempted.join(' ')} --store <id>`;
+            }
+        }
+        console.error(attempted.length > 0
+            ? `Error: unknown command '${attempted[0]}' for 'openspec store'.`
+            : "Error: missing subcommand for 'openspec store'.");
+        console.error(`Store subcommands manage store registration: ${storeSubcommandsLine}.`);
+        console.error('To create or work on a change in a store, use the normal command with --store, for example:');
+        console.error(`  ${example}`);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=store.js.map

package/dist/cli/commands/workset.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerWorksetCommand(program: Command): void;
+//# sourceMappingURL=workset.d.ts.map

package/dist/cli/commands/workset.js

@@ -0,0 +1,96 @@
+import { Option } from 'commander';
+import { COMMAND_REGISTRY } from '../../core/completions/command-registry.js';
+import { printJson } from '../../commands/shared-output.js';
+async function loadWorksetCommand() {
+    const { WorksetCommand } = await import('../../commands/workset.js');
+    return new WorksetCommand();
+}
+function collectMember(value, previous) {
+    return [...previous, value];
+}
+export function registerWorksetCommand(program) {
+    const groupDescription = COMMAND_REGISTRY.find((entry) => entry.name === 'workset')?.description ??
+        'Compose, keep, and open personal working views (purely local)';
+    const workset = program.command('workset').description(groupDescription);
+    // Parsed at the group level so `openspec workset --json` keeps the
+    // one-JSON-document contract instead of a raw Commander error. The
+    // parent option matches anywhere; actions read optsWithGlobals().
+    workset.addOption(new Option('--json', 'Output as JSON').hideHelp());
+    workset
+        .command('create [name]')
+        .description('Compose and save a named working view of folders you choose')
+        .option('--member <member>', 'Member folder as <path> or <name>=<path>; repeatable, first is the primary', collectMember, [])
+        .option('--tool <id>', 'Preferred tool to open this workset with')
+        .option('--json', 'Output as JSON')
+        .action(async (name, _options, command) => {
+        const worksetCommand = await loadWorksetCommand();
+        await worksetCommand.create(name, command.optsWithGlobals());
+    });
+    workset
+        .command('list')
+        .alias('ls')
+        .description('Show saved worksets with their members')
+        .option('--json', 'Output as JSON')
+        .action(async (_options, command) => {
+        const worksetCommand = await loadWorksetCommand();
+        await worksetCommand.list(command.optsWithGlobals());
+    });
+    workset
+        .command('open <name>')
+        .description('Open a saved workset in your tool (editor window or agent session)')
+        .option('--tool <id>', 'Open with this tool just this once')
+        .addOption(
+    // Parsed so Commander never owns the error; rejected in the
+    // action with one JSON document. Hidden because help should not
+    // advertise a mode that only rejects.
+    new Option('--json', 'Not supported for open').hideHelp())
+        .action(async (name, _options, command) => {
+        const worksetCommand = await loadWorksetCommand();
+        await worksetCommand.open(name, command.optsWithGlobals());
+    });
+    workset
+        .command('remove <name>')
+        .description('Delete a saved workset (member folders are never touched)')
+        .option('--yes', 'Confirm removal non-interactively')
+        .option('--json', 'Output as JSON')
+        .action(async (name, _options, command) => {
+        const worksetCommand = await loadWorksetCommand();
+        await worksetCommand.remove(name, command.optsWithGlobals());
+    });
+    const subcommandsLine = workset.commands
+        .map((subcommand) => {
+        const aliases = subcommand.aliases();
+        return aliases.length > 0
+            ? `${subcommand.name()} (${aliases.join(', ')})`
+            : subcommand.name();
+    })
+        .join(', ');
+    // One handler owns missing AND unknown subcommands: known
+    // subcommands dispatch above; everything else lands in this action
+    // (allowExcessArguments routes the unknown operand here), keeping
+    // the one-JSON-document contract for `--json` probes.
+    workset.allowExcessArguments(true);
+    workset.action(() => {
+        const attempted = workset.args.filter((operand) => !operand.startsWith('-'));
+        const message = attempted.length > 0
+            ? `Unknown command '${attempted[0]}' for 'openspec workset'. Workset subcommands: ${subcommandsLine}.`
+            : `Missing subcommand for 'openspec workset'. Workset subcommands: ${subcommandsLine}.`;
+        if (workset.opts().json) {
+            printJson({
+                status: [
+                    {
+                        severity: 'error',
+                        code: 'unknown_workset_subcommand',
+                        message,
+                        fix: 'Run one of the workset subcommands.',
+                    },
+                ],
+            });
+        }
+        else {
+            console.error(`Error: ${message}`);
+        }
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=workset.js.map

package/dist/cli/index.d.ts

@@ -27,6 +27,11 @@ export declare function isJsonRun(command: Command): boolean;
  * completions is noise, and `__complete` would burn the one-shot tip invisibly.
  */
 export declare function isCompletionRun(commandPath: string): boolean;
+/**
+ * True for the hidden `__complete` resolver alone. It runs on every Tab press,
+ * so the hooks skip telemetry and the completion tip for it entirely.
+ */
+export declare function isTabCompletionRun(commandPath: string): boolean;
 /**
  * True when the first-run completions tip must be deferred rather than shown.
  *