gmc-openspec 1.0.0 → 1.4.1

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

@@ -1,46 +1,27 @@
-/**
- * Common flags used across multiple commands
- */
-const COMMON_FLAGS = {
-    json: {
-        name: 'json',
-        description: 'Output as JSON',
-    },
-    jsonValidation: {
-        name: 'json',
-        description: 'Output validation results as JSON',
-    },
-    strict: {
-        name: 'strict',
-        description: 'Enable strict validation mode',
-    },
-    noInteractive: {
-        name: 'no-interactive',
-        description: 'Disable interactive prompts',
-    },
-    type: {
-        name: 'type',
-        description: 'Specify item type when ambiguous',
-        takesValue: true,
-        values: ['change', 'spec'],
-    },
-};
-/**
- * Registry of all OpenSpec CLI commands with their flags and metadata.
- * This registry is used to generate shell completion scripts.
- */
+import { COMMON_FLAGS } from './shared-flags.js';
 export const COMMAND_REGISTRY = [
     {
         name: 'init',
         description: 'Initialize OpenSpec in your project',
         acceptsPositional: true,
         positionalType: 'path',
+        positionals: [{ name: 'path', type: 'path', optional: true }],
         flags: [
             {
                 name: 'tools',
                 description: 'Configure AI tools non-interactively (e.g., "all", "none", or comma-separated tool IDs)',
                 takesValue: true,
             },
+            {
+                name: 'force',
+                description: 'Auto-cleanup legacy files without prompting',
+            },
+            {
+                name: 'profile',
+                description: 'Override global config profile (core or custom)',
+                takesValue: true,
+                values: ['core', 'custom'],
+            },
         ],
     },
     {
@@ -48,7 +29,13 @@ export const COMMAND_REGISTRY = [
         description: 'Update OpenSpec instruction files',
         acceptsPositional: true,
         positionalType: 'path',
-        flags: [],
+        positionals: [{ name: 'path', type: 'path', optional: true }],
+        flags: [
+            {
+                name: 'force',
+                description: 'Force update even when tools are up to date',
+            },
+        ],
     },
     {
         name: 'list',
@@ -62,6 +49,13 @@ export const COMMAND_REGISTRY = [
                 name: 'changes',
                 description: 'List changes explicitly (default)',
             },
+            {
+                name: 'sort',
+                description: 'Sort order: "recent" (default) or "name"',
+                takesValue: true,
+                values: ['recent', 'name'],
+            },
+            COMMON_FLAGS.json,
         ],
     },
     {
@@ -74,6 +68,7 @@ export const COMMAND_REGISTRY = [
         description: 'Validate changes and specs',
         acceptsPositional: true,
         positionalType: 'change-or-spec-id',
+        positionals: [{ name: 'item-name', type: 'change-or-spec-id', optional: true }],
         flags: [
             {
                 name: 'all',
@@ -103,6 +98,7 @@ export const COMMAND_REGISTRY = [
         description: 'Show a change or spec',
         acceptsPositional: true,
         positionalType: 'change-or-spec-id',
+        positionals: [{ name: 'item-name', type: 'change-or-spec-id', optional: true }],
         flags: [
             COMMON_FLAGS.json,
             COMMON_FLAGS.type,
@@ -136,6 +132,7 @@ export const COMMAND_REGISTRY = [
         description: 'Archive a completed change and update main specs',
         acceptsPositional: true,
         positionalType: 'change-id',
+        positionals: [{ name: 'change-name', type: 'change-id', optional: true }],
         flags: [
             {
                 name: 'yes',
@@ -152,6 +149,144 @@ export const COMMAND_REGISTRY = [
             },
         ],
     },
+    {
+        name: 'status',
+        description: 'Display artifact completion status for a change',
+        flags: [
+            {
+                name: 'change',
+                description: 'Change name to show status for',
+                takesValue: true,
+            },
+            {
+                name: 'schema',
+                description: 'Schema override',
+                takesValue: true,
+            },
+            COMMON_FLAGS.json,
+        ],
+    },
+    {
+        name: 'instructions',
+        description: 'Output enriched instructions for creating an artifact or applying tasks',
+        acceptsPositional: true,
+        positionals: [{ name: 'artifact', optional: true }],
+        flags: [
+            {
+                name: 'change',
+                description: 'Change name',
+                takesValue: true,
+            },
+            {
+                name: 'schema',
+                description: 'Schema override',
+                takesValue: true,
+            },
+            COMMON_FLAGS.json,
+        ],
+    },
+    {
+        name: 'templates',
+        description: 'Show resolved template paths for all artifacts in a schema',
+        flags: [
+            {
+                name: 'schema',
+                description: 'Schema to use',
+                takesValue: true,
+            },
+            COMMON_FLAGS.json,
+        ],
+    },
+    {
+        name: 'schemas',
+        description: 'List available workflow schemas with descriptions',
+        flags: [
+            COMMON_FLAGS.json,
+        ],
+    },
+    {
+        name: 'new',
+        description: 'Create new items',
+        flags: [],
+        subcommands: [
+            {
+                name: 'change',
+                description: 'Create a new change directory',
+                acceptsPositional: true,
+                positionals: [{ name: 'name' }],
+                flags: [
+                    {
+                        name: 'description',
+                        description: 'Description to add to README.md',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'goal',
+                        description: 'Workspace product goal to store with the change',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'areas',
+                        description: 'Comma-separated affected workspace link names',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'initiative',
+                        description: 'Link the repo-local change to an initiative',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store',
+                        description: 'Context store id for --initiative',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root for --initiative',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'schema',
+                        description: 'Workflow schema to use',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'set',
+        description: 'Set checked-in OpenSpec metadata',
+        flags: [],
+        subcommands: [
+            {
+                name: 'change',
+                description: 'Set repo-local change metadata',
+                acceptsPositional: true,
+                positionalType: 'change-id',
+                positionals: [{ name: 'name', type: 'change-id' }],
+                flags: [
+                    {
+                        name: 'initiative',
+                        description: 'Link the repo-local change to an initiative',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store',
+                        description: 'Context store id for --initiative',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root for --initiative',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+        ],
+    },
     {
         name: 'workspace',
         description: 'Set up and inspect coordination workspaces',
@@ -173,9 +308,9 @@ export const COMMAND_REGISTRY = [
                     },
                     {
                         name: 'opener',
-                        description: 'Preferred opener: codex, claude, github-copilot, or editor',
+                        description: 'Preferred opener: codex-cli, claude, github-copilot, or editor',
                         takesValue: true,
-                        values: ['codex', 'claude', 'github-copilot', 'editor'],
+                        values: ['codex-cli', 'claude', 'github-copilot', 'editor'],
                     },
                     {
                         name: 'tools',
@@ -205,20 +340,13 @@ export const COMMAND_REGISTRY = [
                 description: 'Link an existing repo or folder to a workspace',
                 acceptsPositional: true,
                 positionals: [
-                    {
-                        name: 'name-or-path',
-                        type: 'path',
-                        optional: true,
-                    },
-                    {
-                        name: 'path',
-                        type: 'path',
-                    },
+                    { name: 'name-or-path', type: 'path', optional: true },
+                    { name: 'path', type: 'path', optional: true },
                 ],
                 flags: [
                     {
                         name: 'workspace',
-                        description: 'Workspace name from the local workspace registry',
+                        description: 'Workspace name from local workspace views',
                         takesValue: true,
                     },
                     COMMON_FLAGS.json,
@@ -230,18 +358,13 @@ export const COMMAND_REGISTRY = [
                 description: 'Update the local path for an existing workspace link',
                 acceptsPositional: true,
                 positionals: [
-                    {
-                        name: 'name',
-                    },
-                    {
-                        name: 'path',
-                        type: 'path',
-                    },
+                    { name: 'name' },
+                    { name: 'path', type: 'path' },
                 ],
                 flags: [
                     {
                         name: 'workspace',
-                        description: 'Workspace name from the local workspace registry',
+                        description: 'Workspace name from local workspace views',
                         takesValue: true,
                     },
                     COMMON_FLAGS.json,
@@ -254,7 +377,7 @@ export const COMMAND_REGISTRY = [
                 flags: [
                     {
                         name: 'workspace',
-                        description: 'Workspace name from the local workspace registry',
+                        description: 'Workspace name from local workspace views',
                         takesValue: true,
                     },
                     COMMON_FLAGS.json,
@@ -263,18 +386,13 @@ export const COMMAND_REGISTRY = [
             },
             {
                 name: 'update',
-                description: 'Refresh workspace-local OpenSpec agent skills from the active global profile',
+                description: 'Refresh workspace-local OpenSpec guidance and agent skills',
                 acceptsPositional: true,
-                positionals: [
-                    {
-                        name: 'name',
-                        optional: true,
-                    },
-                ],
+                positionals: [{ name: 'name', optional: true }],
                 flags: [
                     {
                         name: 'workspace',
-                        description: 'Workspace name from the local workspace registry',
+                        description: 'Workspace name from local workspace views',
                         takesValue: true,
                     },
                     {
@@ -290,37 +408,305 @@ export const COMMAND_REGISTRY = [
                 name: 'open',
                 description: 'Open a workspace in an agent or VS Code editor',
                 acceptsPositional: true,
-                positionals: [
-                    {
-                        name: 'name',
-                        optional: true,
-                    },
-                ],
+                positionals: [{ name: 'name', optional: true }],
                 flags: [
                     {
                         name: 'workspace',
-                        description: 'Workspace name from the local workspace registry',
+                        description: 'Workspace name from local workspace views',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'initiative',
+                        description: 'Open an initiative as a local workspace view',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store',
+                        description: 'Context store id for --initiative',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root for --initiative',
                         takesValue: true,
                     },
                     {
                         name: 'agent',
-                        description: 'Use an agent for this session: codex, claude, or github-copilot',
+                        description: 'Use an agent for this session: codex-cli, claude, or github-copilot',
                         takesValue: true,
-                        values: ['codex', 'claude', 'github-copilot'],
+                        values: ['codex-cli', 'claude', 'github-copilot'],
                     },
                     {
                         name: 'editor',
                         description: 'Open the workspace in VS Code editor mode',
                     },
+                    {
+                        name: 'prepare-only',
+                        description: 'Unsupported: preview surfaces belong to a future context/query command',
+                    },
+                    COMMON_FLAGS.json,
+                    {
+                        name: 'change',
+                        description: 'Unsupported: change-scoped open belongs to future workspace change planning',
+                        takesValue: true,
+                    },
                     COMMON_FLAGS.noInteractive,
                 ],
             },
         ],
     },
+    {
+        name: 'jira',
+        description: 'Manage Jira intake setup, validation, and status',
+        flags: [],
+        subcommands: [
+            {
+                name: 'setup',
+                description: 'Set up Jira intake configuration and AI workflow artifacts',
+                acceptsPositional: true,
+                positionalType: 'path',
+                positionals: [{ name: 'path', type: 'path', optional: true }],
+                flags: [
+                    {
+                        name: 'tools',
+                        description: 'AI tools to configure: all, none, detected, or comma-separated tool IDs',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'provider',
+                        description: 'Jira provider',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'endpoint',
+                        description: 'Atlassian MCP endpoint',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'force',
+                        description: 'Overwrite existing Jira setup files when needed',
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'doctor',
+                description: 'Check Jira intake configuration and local MCP prerequisites',
+                acceptsPositional: true,
+                positionalType: 'path',
+                positionals: [{ name: 'path', type: 'path', optional: true }],
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'validate',
+                description: 'Validate a Jira intake folder before moving to the next stage',
+                acceptsPositional: true,
+                positionals: [{ name: 'jira-id' }],
+                flags: [
+                    {
+                        name: 'stage',
+                        description: 'Validation stage',
+                        takesValue: true,
+                        values: ['source', 'requirement', 'stories', 'propose'],
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'status',
+                description: 'Show Jira intake status and allowed next states',
+                acceptsPositional: true,
+                positionals: [{ name: 'jira-id' }],
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'context-store',
+        description: 'Set up and inspect context stores',
+        flags: [],
+        subcommands: [
+            {
+                name: 'setup',
+                description: 'Create or register a local context store',
+                acceptsPositional: true,
+                positionals: [{ name: 'id', optional: true }],
+                flags: [
+                    {
+                        name: 'path',
+                        description: 'Directory to use for the context store',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'init-git',
+                        description: 'Initialize a Git repository in the context store',
+                    },
+                    {
+                        name: 'no-init-git',
+                        description: 'Skip Git repository initialization',
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'register',
+                description: 'Register an existing context store directory',
+                acceptsPositional: true,
+                positionals: [{ name: 'path', type: 'path', optional: true }],
+                flags: [
+                    {
+                        name: 'id',
+                        description: 'Context store id',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'unregister',
+                description: 'Forget a local context-store registration without deleting files',
+                acceptsPositional: true,
+                positionals: [{ name: 'id' }],
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'remove',
+                description: 'Forget a local context-store registration and delete its local folder',
+                acceptsPositional: true,
+                positionals: [{ name: 'id' }],
+                flags: [
+                    {
+                        name: 'yes',
+                        description: 'Confirm local context-store folder deletion',
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'list',
+                description: 'List registered context stores',
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'ls',
+                description: 'List registered context stores',
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'doctor',
+                description: 'Check local context-store registration and metadata',
+                acceptsPositional: true,
+                positionals: [{ name: 'id', optional: true }],
+                flags: [
+                    COMMON_FLAGS.json,
+                ],
+            },
+        ],
+    },
+    {
+        name: 'initiative',
+        description: 'Create and list coordinated initiatives',
+        flags: [],
+        subcommands: [
+            {
+                name: 'create',
+                description: 'Create an initiative in a context store',
+                acceptsPositional: true,
+                positionals: [{ name: 'id', optional: true }],
+                flags: [
+                    {
+                        name: 'store',
+                        description: 'Context store id from the local context-store registry',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'title',
+                        description: 'Initiative title',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'summary',
+                        description: 'Initiative summary',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'show',
+                description: 'Show where an initiative lives and how to read it',
+                acceptsPositional: true,
+                positionals: [{ name: 'id' }],
+                flags: [
+                    {
+                        name: 'store',
+                        description: 'Context store id from the local context-store registry',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'list',
+                description: 'List initiatives across registered context stores',
+                flags: [
+                    {
+                        name: 'store',
+                        description: 'Context store id from the local context-store registry',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+            {
+                name: 'ls',
+                description: 'List initiatives across registered context stores',
+                flags: [
+                    {
+                        name: 'store',
+                        description: 'Context store id from the local context-store registry',
+                        takesValue: true,
+                    },
+                    {
+                        name: 'store-path',
+                        description: 'Existing local context store root',
+                        takesValue: true,
+                    },
+                    COMMON_FLAGS.json,
+                ],
+            },
+        ],
+    },
     {
         name: 'feedback',
         description: 'Submit feedback about OpenSpec',
         acceptsPositional: true,
+        positionals: [{ name: 'message' }],
         flags: [
             {
                 name: 'body',
@@ -339,6 +725,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Show a change proposal',
                 acceptsPositional: true,
                 positionalType: 'change-id',
+                positionals: [{ name: 'change-name', type: 'change-id', optional: true }],
                 flags: [
                     COMMON_FLAGS.json,
                     {
@@ -368,6 +755,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Validate a change proposal',
                 acceptsPositional: true,
                 positionalType: 'change-id',
+                positionals: [{ name: 'change-name', type: 'change-id', optional: true }],
                 flags: [
                     COMMON_FLAGS.strict,
                     COMMON_FLAGS.jsonValidation,
@@ -386,6 +774,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Show a specification',
                 acceptsPositional: true,
                 positionalType: 'spec-id',
+                positionals: [{ name: 'spec-id', type: 'spec-id', optional: true }],
                 flags: [
                     COMMON_FLAGS.json,
                     {
@@ -421,6 +810,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Validate a specification',
                 acceptsPositional: true,
                 positionalType: 'spec-id',
+                positionals: [{ name: 'spec-id', type: 'spec-id', optional: true }],
                 flags: [
                     COMMON_FLAGS.strict,
                     COMMON_FLAGS.jsonValidation,
@@ -439,6 +829,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Generate completion script for a shell (outputs to stdout)',
                 acceptsPositional: true,
                 positionalType: 'shell',
+                positionals: [{ name: 'shell', type: 'shell', optional: true }],
                 flags: [],
             },
             {
@@ -446,6 +837,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Install completion script for a shell',
                 acceptsPositional: true,
                 positionalType: 'shell',
+                positionals: [{ name: 'shell', type: 'shell', optional: true }],
                 flags: [
                     {
                         name: 'verbose',
@@ -458,6 +850,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Uninstall completion script for a shell',
                 acceptsPositional: true,
                 positionalType: 'shell',
+                positionals: [{ name: 'shell', type: 'shell', optional: true }],
                 flags: [
                     {
                         name: 'yes',
@@ -496,12 +889,14 @@ export const COMMAND_REGISTRY = [
                 name: 'get',
                 description: 'Get a specific value (raw, scriptable)',
                 acceptsPositional: true,
+                positionals: [{ name: 'key' }],
                 flags: [],
             },
             {
                 name: 'set',
                 description: 'Set a value (auto-coerce types)',
                 acceptsPositional: true,
+                positionals: [{ name: 'key' }, { name: 'value' }],
                 flags: [
                     {
                         name: 'string',
@@ -517,6 +912,7 @@ export const COMMAND_REGISTRY = [
                 name: 'unset',
                 description: 'Remove a key (revert to default)',
                 acceptsPositional: true,
+                positionals: [{ name: 'key' }],
                 flags: [],
             },
             {
@@ -542,6 +938,8 @@ export const COMMAND_REGISTRY = [
             {
                 name: 'profile',
                 description: 'Configure workflow profile (interactive picker or preset shortcut)',
+                acceptsPositional: true,
+                positionals: [{ name: 'preset', optional: true }],
                 flags: [],
             },
         ],
@@ -556,6 +954,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Show where a schema resolves from',
                 acceptsPositional: true,
                 positionalType: 'schema-name',
+                positionals: [{ name: 'name', type: 'schema-name', optional: true }],
                 flags: [
                     COMMON_FLAGS.json,
                     {
@@ -569,6 +968,7 @@ export const COMMAND_REGISTRY = [
                 description: 'Validate a schema structure and templates',
                 acceptsPositional: true,
                 positionalType: 'schema-name',
+                positionals: [{ name: 'name', type: 'schema-name', optional: true }],
                 flags: [
                     COMMON_FLAGS.json,
                     {
@@ -582,6 +982,10 @@ export const COMMAND_REGISTRY = [
                 description: 'Copy an existing schema to project for customization',
                 acceptsPositional: true,
                 positionalType: 'schema-name',
+                positionals: [
+                    { name: 'source', type: 'schema-name' },
+                    { name: 'name', optional: true },
+                ],
                 flags: [
                     COMMON_FLAGS.json,
                     {
@@ -594,6 +998,7 @@ export const COMMAND_REGISTRY = [
                 name: 'init',
                 description: 'Create a new project-local schema',
                 acceptsPositional: true,
+                positionals: [{ name: 'name' }],
                 flags: [
                     COMMON_FLAGS.json,
                     {