@exodus/openspec 1.2.1 → 1.2.3

package/dist/core/config-prompts.js

@@ -29,6 +29,13 @@ export function serializeConfig(config) {
     lines.push('#       - Always include a "Non-goals" section');
     lines.push('#     tasks:');
     lines.push('#       - Break tasks into chunks of max 2 hours');
+    lines.push('');
+    lines.push('# CLI command (optional)');
+    lines.push('# Override the `openspec` command used in generated skill files.');
+    lines.push('# Useful when openspec is only installed at a monorepo root.');
+    lines.push('# Example:');
+    lines.push('#   cli: pnpm exec openspec');
+    lines.push('#   cli: npx @exodus/openspec');
     return lines.join('\n') + '\n';
 }
 //# sourceMappingURL=config-prompts.js.map

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

@@ -6,8 +6,8 @@ import { z } from 'zod';
 export declare const GlobalConfigSchema: z.ZodObject<{
     featureFlags: z.ZodDefault<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>>;
     profile: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
-        core: "core";
         custom: "custom";
+        core: "core";
     }>>>;
     delivery: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         commands: "commands";

package/dist/core/init.js

@@ -10,7 +10,8 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { transformToHyphenCommands } from '../utils/command-references.js';
+import { transformToHyphenCommands, createCliTransformer } from '../utils/command-references.js';
+import { readProjectConfig } from './project-config.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME, } from './config.js';
 import { PALETTE } from './styles/palette.js';
 import { isInteractive } from '../utils/interactive.js';
@@ -364,6 +365,9 @@ export class InitCommand {
         const profile = this.resolveProfileOverride() ?? globalConfig.profile ?? 'core';
         const delivery = globalConfig.delivery ?? 'both';
         const workflows = getProfileWorkflows(profile, globalConfig.workflows);
+        // Read project config for cli override
+        const projectConfig = readProjectConfig(projectPath);
+        const cliTransformer = createCliTransformer(projectConfig?.cli);
         // Get skill and command templates filtered by profile workflows
         const shouldGenerateSkills = delivery !== 'commands';
         const shouldGenerateCommands = delivery !== 'skills';
@@ -382,8 +386,11 @@ export class InitCommand {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
                         // Generate SKILL.md content with YAML frontmatter including generatedBy
-                        // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        // Use hyphen-based command references for OpenCode; apply cli override if set
+                        const toolTransformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = cliTransformer && toolTransformer
+                            ? (text) => cliTransformer(toolTransformer(text))
+                            : cliTransformer ?? toolTransformer;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         // Write the skill file
                         await FileSystemUtils.writeFile(skillFile, skillContent);

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

@@ -16,6 +16,7 @@ export declare const ProjectConfigSchema: z.ZodObject<{
     schema: z.ZodString;
     context: z.ZodOptional<z.ZodString>;
     rules: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
+    cli: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
 /**

package/dist/core/project-config.js

@@ -34,6 +34,14 @@ export const ProjectConfigSchema = z.object({
     )
         .optional()
         .describe('Per-artifact rules, keyed by artifact ID'),
+    // Optional: CLI command to use for openspec invocations in generated skills
+    // Useful when openspec is only installed at a monorepo root (e.g., pnpm workspaces)
+    // Example: "pnpm exec openspec" or "npx @exodus/openspec"
+    cli: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('CLI command used to invoke openspec in generated skill files'),
 });
 const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit
 /**
@@ -131,6 +139,17 @@ export function readProjectConfig(projectRoot) {
                 console.warn(`Invalid 'rules' field in config (must be object)`);
             }
         }
+        // Parse cli field using Zod
+        if (raw.cli !== undefined) {
+            const cliField = z.string().min(1);
+            const cliResult = cliField.safeParse(raw.cli);
+            if (cliResult.success) {
+                config.cli = cliResult.data;
+            }
+            else {
+                console.warn(`Invalid 'cli' field in config (must be non-empty string)`);
+            }
+        }
         // Return partial config even if some fields failed
         return Object.keys(config).length > 0 ? config : null;
     }

package/dist/core/templates/workflows/apply-change.js

@@ -13,7 +13,7 @@ export function getApplyChangeSkillTemplate() {
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run \`openspec list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, check for a workspace manifest (\`cat openspec/workspace.yaml 2>/dev/null\`). If it exists, run \`(cd <scope.path> && openspec list --json)\` for each scope and \`ls openspec/changes/ 2>/dev/null\` for umbrella changes; otherwise run \`openspec list --json\`. Aggregate all results and use the **AskUserQuestion tool** to let the user select, showing which scope each change belongs to
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 
@@ -196,7 +196,7 @@ export function getOpsxApplyCommandTemplate() {
    If a name is provided, use it. Otherwise:
    - Infer from conversation context if the user mentioned a change
    - Auto-select if only one active change exists
-   - If ambiguous, run \`openspec list --json\` to get available changes and use the **AskUserQuestion tool** to let the user select
+   - If ambiguous, check for a workspace manifest (\`cat openspec/workspace.yaml 2>/dev/null\`). If it exists, run \`(cd <scope.path> && openspec list --json)\` for each scope and \`ls openspec/changes/ 2>/dev/null\` for umbrella changes; otherwise run \`openspec list --json\`. Aggregate all results and use the **AskUserQuestion tool** to let the user select, showing which scope each change belongs to
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 

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

@@ -10,8 +10,24 @@ export function getArchiveChangeSkillTemplate() {
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Check for a workspace manifest:
+   \`\`\`bash
+   cat openspec/workspace.yaml 2>/dev/null
+   \`\`\`
+
+   If workspace.yaml exists, list changes across all scopes:
+   \`\`\`bash
+   (cd <scope.path> && openspec list --json)   # for each scope in workspace.yaml
+   ls openspec/changes/ 2>/dev/null             # umbrella changes at root
+   \`\`\`
+
+   Otherwise:
+   \`\`\`bash
+   openspec list --json
+   \`\`\`
 
+   Aggregate all results. Use the **AskUserQuestion tool** to let the user select.
+   In workspace mode, show which scope each change belongs to.
    Show only active changes (not already archived).
    Include the schema used for each change if available.
 
@@ -154,8 +170,24 @@ export function getOpsxArchiveCommandTemplate() {
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+   Check for a workspace manifest:
+   \`\`\`bash
+   cat openspec/workspace.yaml 2>/dev/null
+   \`\`\`
+
+   If workspace.yaml exists, list changes across all scopes:
+   \`\`\`bash
+   (cd <scope.path> && openspec list --json)   # for each scope in workspace.yaml
+   ls openspec/changes/ 2>/dev/null             # umbrella changes at root
+   \`\`\`
+
+   Otherwise:
+   \`\`\`bash
+   openspec list --json
+   \`\`\`
 
+   Aggregate all results. Use the **AskUserQuestion tool** to let the user select.
+   In workspace mode, show which scope each change belongs to.
    Show only active changes (not already archived).
    Include the schema used for each change if available.
 

package/dist/core/templates/workflows/continue-change.js

@@ -10,7 +10,23 @@ export function getContinueChangeSkillTemplate() {
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Check for a workspace manifest:
+   \`\`\`bash
+   cat openspec/workspace.yaml 2>/dev/null
+   \`\`\`
+
+   If workspace.yaml exists, list changes across all scopes:
+   \`\`\`bash
+   (cd <scope.path> && openspec list --json)   # for each scope in workspace.yaml
+   ls openspec/changes/ 2>/dev/null             # umbrella changes at root
+   \`\`\`
+
+   Otherwise:
+   \`\`\`bash
+   openspec list --json
+   \`\`\`
+
+   Aggregate all results sorted by most recently modified. Use the **AskUserQuestion tool** to let the user select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name
@@ -128,7 +144,23 @@ export function getOpsxContinueCommandTemplate() {
 
 1. **If no change name provided, prompt for selection**
 
-   Run \`openspec list --json\` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+   Check for a workspace manifest:
+   \`\`\`bash
+   cat openspec/workspace.yaml 2>/dev/null
+   \`\`\`
+
+   If workspace.yaml exists, list changes across all scopes:
+   \`\`\`bash
+   (cd <scope.path> && openspec list --json)   # for each scope in workspace.yaml
+   ls openspec/changes/ 2>/dev/null             # umbrella changes at root
+   \`\`\`
+
+   Otherwise:
+   \`\`\`bash
+   openspec list --json
+   \`\`\`
+
+   Aggregate all results sorted by most recently modified. Use the **AskUserQuestion tool** to let the user select which change to work on.
 
    Present the top 3-4 most recently modified changes as options, showing:
    - Change name

package/dist/core/update.js

@@ -10,7 +10,8 @@ import ora from 'ora';
 import * as fs from 'fs';
 import { createRequire } from 'module';
 import { FileSystemUtils } from '../utils/file-system.js';
-import { transformToHyphenCommands } from '../utils/command-references.js';
+import { transformToHyphenCommands, createCliTransformer } from '../utils/command-references.js';
+import { readProjectConfig } from './project-config.js';
 import { AI_TOOLS, OPENSPEC_DIR_NAME } from './config.js';
 import { generateCommands, CommandAdapterRegistry, } from './command-generation/index.js';
 import { getToolVersionStatus, getSkillTemplates, getCommandContents, generateSkillContent, getToolsWithSkillsDir, } from './shared/index.js';
@@ -106,6 +107,8 @@ export class UpdateCommand {
         }
         console.log();
         // 9. Determine what to generate based on delivery
+        const projectConfig = readProjectConfig(resolvedProjectPath);
+        const cliTransformer = createCliTransformer(projectConfig?.cli);
         const skillTemplates = shouldGenerateSkills ? getSkillTemplates(desiredWorkflows) : [];
         const commandContents = shouldGenerateCommands ? getCommandContents(desiredWorkflows) : [];
         // 10. Update tools (all if force, otherwise only those needing update)
@@ -128,8 +131,11 @@ export class UpdateCommand {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
-                        // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        // Use hyphen-based command references for OpenCode; apply cli override if set
+                        const toolTransformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = cliTransformer && toolTransformer
+                            ? (text) => cliTransformer(toolTransformer(text))
+                            : cliTransformer ?? toolTransformer;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }
@@ -489,6 +495,8 @@ export class UpdateCommand {
         const newlyConfigured = [];
         const shouldGenerateSkills = delivery !== 'commands';
         const shouldGenerateCommands = delivery !== 'skills';
+        const legacyProjectConfig = readProjectConfig(projectPath);
+        const legacyCliTransformer = createCliTransformer(legacyProjectConfig?.cli);
         const skillTemplates = shouldGenerateSkills ? getSkillTemplates(desiredWorkflows) : [];
         const commandContents = shouldGenerateCommands ? getCommandContents(desiredWorkflows) : [];
         for (const toolId of selectedTools) {
@@ -503,8 +511,11 @@ export class UpdateCommand {
                     for (const { template, dirName } of skillTemplates) {
                         const skillDir = path.join(skillsDir, dirName);
                         const skillFile = path.join(skillDir, 'SKILL.md');
-                        // Use hyphen-based command references for OpenCode
-                        const transformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        // Use hyphen-based command references for OpenCode; apply cli override if set
+                        const toolTransformer = tool.value === 'opencode' ? transformToHyphenCommands : undefined;
+                        const transformer = legacyCliTransformer && toolTransformer
+                            ? (text) => legacyCliTransformer(toolTransformer(text))
+                            : legacyCliTransformer ?? toolTransformer;
                         const skillContent = generateSkillContent(template, OPENSPEC_VERSION, transformer);
                         await FileSystemUtils.writeFile(skillFile, skillContent);
                     }

package/dist/utils/command-references.d.ts

@@ -15,4 +15,19 @@
  * transformToHyphenCommands('Use /opsx:apply to implement') // returns 'Use /opsx-apply to implement'
  */
 export declare function transformToHyphenCommands(text: string): string;
+/**
+ * Creates a transformer that replaces bare `openspec` CLI invocations with a custom command.
+ * Only replaces command invocations (backtick-quoted, after `&&`, or at line start),
+ * not path references like `openspec/changes/`.
+ *
+ * @param cli - The CLI command to use instead of bare `openspec`
+ * @returns Transformer function, or undefined if cli is not set
+ *
+ * @example
+ * const t = createCliTransformer('pnpm exec openspec');
+ * t('`openspec list --json`')        // '`pnpm exec openspec list --json`'
+ * t('openspec status --change "x"')  // 'pnpm exec openspec status --change "x"' (line-start)
+ * t('openspec/changes/foo')          // 'openspec/changes/foo' (path unchanged)
+ */
+export declare function createCliTransformer(cli: string | undefined): ((text: string) => string) | undefined;
 //# sourceMappingURL=command-references.d.ts.map

package/dist/utils/command-references.js

@@ -17,4 +17,26 @@
 export function transformToHyphenCommands(text) {
     return text.replace(/\/opsx:/g, '/opsx-');
 }
+/**
+ * Creates a transformer that replaces bare `openspec` CLI invocations with a custom command.
+ * Only replaces command invocations (backtick-quoted, after `&&`, or at line start),
+ * not path references like `openspec/changes/`.
+ *
+ * @param cli - The CLI command to use instead of bare `openspec`
+ * @returns Transformer function, or undefined if cli is not set
+ *
+ * @example
+ * const t = createCliTransformer('pnpm exec openspec');
+ * t('`openspec list --json`')        // '`pnpm exec openspec list --json`'
+ * t('openspec status --change "x"')  // 'pnpm exec openspec status --change "x"' (line-start)
+ * t('openspec/changes/foo')          // 'openspec/changes/foo' (path unchanged)
+ */
+export function createCliTransformer(cli) {
+    if (!cli)
+        return undefined;
+    return (text) => text
+        .replace(/`openspec\s/g, `\`${cli} `)
+        .replace(/&& openspec\s/g, `&& ${cli} `)
+        .replace(/^(\s*)openspec\s/gm, `$1${cli} `);
+}
 //# sourceMappingURL=command-references.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/openspec",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",