@clawplays/ospec-cli 0.3.5 → 0.3.7

package/README.md

@@ -31,21 +31,24 @@ OSpec is a document-driven workflow for AI-assisted development, helping you def
   <a href="https://github.com/clawplays/ospec/issues">Issues</a>
 </p>
 
-## Install With npm
+## Why OSpec?
 
-```bash
-npm install -g @clawplays/ospec-cli
-```
+AI coding assistants are powerful, but requirements that live only in chat history are hard to inspect, review, and close out cleanly. OSpec adds a lightweight workflow layer so the repository can hold the change context before code is written and after the work ships.
 
-Update inside your project directory:
+- Align before code — keep proposal, tasks, state, verification, and review visible in the repo
+- Keep each requirement explicit — the default path moves one requirement through one active change
+- Stay lightweight — keep the normal flow short with `init -> change -> verify/finalize`
+- Use the assistants you already have — OSpec is built for Codex, Claude Code, and direct CLI workflows
+
+## Install With npm
 
 ```bash
-ospec update
+npm install -g @clawplays/ospec-cli
 ```
 
-## Recommended Prompts
+## Quick Start
 
-Most teams only need 3 steps to use OSpec:
+OSpec only takes 3 steps:
 
 1. initialize OSpec in your project directory
 2. create and advance one change for a requirement, document update, or bug fix
@@ -56,13 +59,13 @@ Most teams only need 3 steps to use OSpec:
 Recommended prompt:
 
 ```text
-Use OSpec to initialize this project.
+OSpec, initialize this project.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to initialize this project.
+$ospec initialize this project.
 ```
 
 <details>
@@ -96,17 +99,15 @@ Use this for requirement delivery, documentation updates, refactors, and bug fix
 Recommended prompt:
 
 ```text
-Use OSpec to create and advance a change for this requirement.
+OSpec, create and advance a change for this requirement.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec-change to create and advance a change for this requirement.
+$ospec-change create and advance a change for this requirement.
 ```
 
-![OSpec Change slash command example](docs/assets/ospecchange-slash-command.en.svg)
-
 <details>
 <summary>Command line</summary>
 
@@ -125,13 +126,13 @@ After the requirement has passed deployment, testing, QA, or other acceptance ch
 Recommended prompt:
 
 ```text
-Use OSpec to archive this accepted change.
+OSpec, archive this accepted change.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to archive this accepted change.
+$ospec archive this accepted change.
 ```
 
 <details>
@@ -151,12 +152,20 @@ Archive notes:
 
 </details>
 
+## Update With npm
+
+For an existing OSpec project, after upgrading the CLI with npm, run this in the project directory to refresh the project's OSpec files:
+
+```bash
+ospec update
+```
+
 ## How The OSpec Workflow Works
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
 │  1. USER REQUEST                                               │
-│     "Use OSpec to create and advance a change for this task."  │
+│     "OSpec, create and advance a change for this task."       │
 └─────────────────────────────────────────────────────────────────┘
                               │
                               ▼
@@ -224,13 +233,13 @@ Use Stitch for page design review and preview collaboration, especially for land
 AI conversation:
 
 ```text
-Use OSpec to enable the Stitch plugin.
+OSpec, enable the Stitch plugin and connect using Codex/Gemini.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to enable the Stitch plugin.
+$ospec enable the Stitch plugin and connect using Codex/Gemini.
 ```
 
 <details>
@@ -249,13 +258,13 @@ Use Checkpoint for app flow validation and automated checks, especially for subm
 AI conversation:
 
 ```text
-Use OSpec to enable the Checkpoint plugin.
+OSpec, enable the Checkpoint plugin.
 ```
 
 Claude / Codex skill mode:
 
 ```text
-Use $ospec to enable the Checkpoint plugin.
+$ospec enable the Checkpoint plugin.
 ```
 
 <details>

package/dist/cli.js

@@ -224,7 +224,7 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.3.5';
+const CLI_VERSION = '0.3.7';
 
 function showInitUsage() {
     console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language en-US|zh-CN|ja-JP|ar]');

package/dist/commands/ChangesCommand.js

@@ -21,6 +21,9 @@ class ChangesCommand extends BaseCommand_1.BaseCommand {
                     console.log(`Total: ${report.totalActiveChanges}`);
                     console.log(`Queued: ${queuedChanges.length}`);
                     console.log(`PASS ${report.totals.pass} | WARN ${report.totals.warn} | FAIL ${report.totals.fail}`);
+                    if (report.totalActiveChanges > 1) {
+                        console.log('WORKFLOW WARN multiple active changes detected. The default workflow expects one active change, and queue runner commands will fail until the repository is back to single-active mode.');
+                    }
                     console.log('');
                     if (report.changes.length === 0) {
                         console.log('No active changes.');

package/dist/commands/InitCommand.js

@@ -37,6 +37,7 @@ exports.InitCommand = void 0;
 const os_1 = require("os");
 const path = __importStar(require("path"));
 const services_1 = require("../services");
+const helpers_1 = require("../utils/helpers");
 const BaseCommand_1 = require("./BaseCommand");
 const SkillCommand_1 = require("./SkillCommand");
 class InitCommand extends BaseCommand_1.BaseCommand {
@@ -73,7 +74,7 @@ class InitCommand extends BaseCommand_1.BaseCommand {
             if (result.firstChangeSuggestion) {
                 this.info(`  Suggested first change: ${result.firstChangeSuggestion.name}`);
             }
-            this.info(`  Next: ospec new <change-name> ${targetDir}`);
+            this.info(`  Next: ${(0, helpers_1.formatCliCommand)('ospec', 'new', '<change-name>', targetDir)}`);
         }
         catch (error) {
             this.error(`Failed to initialize project: ${error}`);

package/dist/commands/NewCommand.js

@@ -37,6 +37,7 @@ exports.NewCommand = void 0;
 const path = __importStar(require("path"));
 const constants_1 = require("../core/constants");
 const services_1 = require("../services");
+const helpers_1 = require("../utils/helpers");
 const PathUtils_1 = require("../utils/PathUtils");
 const PluginWorkflowComposer_1 = require("../workflow/PluginWorkflowComposer");
 const BaseCommand_1 = require("./BaseCommand");
@@ -50,6 +51,7 @@ class NewCommand extends BaseCommand_1.BaseCommand {
             const featureDir = PathUtils_1.PathUtils.getChangeDir(targetDir, placement, featureName);
             this.logger.info(`Creating ${placement === constants_1.DIR_NAMES.QUEUED ? 'queued change' : 'change'}: ${featureName}`);
             await this.ensureChangeNameAvailable(targetDir, featureName);
+            await this.ensureSingleActiveMode(targetDir, placement, featureName);
             await services_1.services.fileService.ensureDir(path.join(targetDir, constants_1.DIR_NAMES.CHANGES, placement));
             await services_1.services.fileService.ensureDir(featureDir);
             const config = await services_1.services.configManager.loadConfig(targetDir);
@@ -229,6 +231,24 @@ class NewCommand extends BaseCommand_1.BaseCommand {
         }
         throw new Error(`Change ${featureName} already exists in ${conflicts.join(' and ')}. Continue the existing change instead of creating a duplicate.`);
     }
+    async ensureSingleActiveMode(targetDir, placement, featureName) {
+        if (placement !== constants_1.DIR_NAMES.ACTIVE) {
+            return;
+        }
+        const activeNames = await services_1.services.projectService.listActiveChangeNames(targetDir);
+        if (activeNames.length === 0) {
+            return;
+        }
+        if (activeNames.length === 1) {
+            const activeName = activeNames[0];
+            const activeChangePath = path.join(targetDir, constants_1.DIR_NAMES.CHANGES, constants_1.DIR_NAMES.ACTIVE, activeName);
+            const progressCommand = (0, helpers_1.formatCliCommand)('ospec', 'progress', activeChangePath);
+            const queueCommand = (0, helpers_1.formatCliCommand)('ospec', 'queue', 'add', featureName, targetDir);
+            throw new Error(`A single active change is the default workflow, but "${activeName}" is already active. Continue it with "${progressCommand}" or create queued work explicitly with "${queueCommand}".`);
+        }
+        const queueCommand = (0, helpers_1.formatCliCommand)('ospec', 'queue', 'add', featureName, targetDir);
+        throw new Error(`A single active change is the default workflow, but ${activeNames.length} active changes already exist: ${activeNames.join(', ')}. Resolve the repository back to one active change before creating another, or add new work with "${queueCommand}".`);
+    }
     async writePluginArtifacts(featureDir, activatedSteps) {
         const checkpointSteps = activatedSteps.filter(step => step === 'checkpoint_ui_review' || step === 'checkpoint_flow_check');
         if (checkpointSteps.length > 0) {

package/dist/commands/PluginsCommand.js

@@ -5,6 +5,7 @@ const child_process_1 = require("child_process");
 const path = require("path");
 const gray_matter_1 = require("gray-matter");
 const constants_1 = require("../core/constants");
+const helpers_1 = require("../utils/helpers");
 const BaseCommand_1 = require("./BaseCommand");
 const services_1 = require("../services");
 const subcommandHelp_1 = require("../utils/subcommandHelp");
@@ -162,7 +163,7 @@ class PluginsCommand extends BaseCommand_1.BaseCommand {
                 if (plugin.runner.extraEnvCount > 0) {
                     console.log(`    Extra env entries: ${plugin.runner.extraEnvCount}`);
                 }
-                console.log(`    Doctor: ospec plugins doctor ${plugin.name} ${projectPath}`);
+                console.log(`    Doctor: ${(0, helpers_1.formatCliCommand)('ospec', 'plugins', 'doctor', plugin.name, projectPath)}`);
             }
             console.log();
         });
@@ -231,7 +232,7 @@ class PluginsCommand extends BaseCommand_1.BaseCommand {
                 this.info(`  codex model: ${this.getStitchCodexConfig(nextConfig.plugins.stitch).model || '(cli default)'}`);
                 if (enabled) {
                     this.info(`  token env: ${nextConfig.plugins.stitch.runner.token_env || '(not required)'}`);
-                    this.info(`  doctor: ospec plugins doctor stitch ${projectPath}`);
+                    this.info(`  doctor: ${(0, helpers_1.formatCliCommand)('ospec', 'plugins', 'doctor', 'stitch', projectPath)}`);
                 }
                 this.info('  Affects new changes by default; update existing changes manually if needed');
                 return;
@@ -311,7 +312,7 @@ class PluginsCommand extends BaseCommand_1.BaseCommand {
                 this.info(`  runner.command: ${nextConfig.plugins.checkpoint.runner.command || '(built-in adapter)'}`);
                 this.info(`  stitch integration: ${nextConfig.plugins.checkpoint.stitch_integration.enabled ? 'enabled' : 'disabled'}`);
                 if (enabled) {
-                    this.info(`  doctor: ospec plugins doctor checkpoint ${projectPath}`);
+                    this.info(`  doctor: ${(0, helpers_1.formatCliCommand)('ospec', 'plugins', 'doctor', 'checkpoint', projectPath)}`);
                 }
                 this.info('  Affects new changes by default; update existing changes manually if needed');
                 return;

package/dist/commands/SkillCommand.js

@@ -16,6 +16,8 @@ const path_1 = __importDefault(require("path"));
 
 const services_1 = require("../services");
 
+const helpers_1 = require("../utils/helpers");
+
 const subcommandHelp_1 = require("../utils/subcommandHelp");
 
 const BaseCommand_1 = require("./BaseCommand");
@@ -554,7 +556,7 @@ class SkillCommand extends BaseCommand_1.BaseCommand {
 
                     if (!result.inSync) {
 
-                        console.log(`\nRecommendation: run "ospec skill ${this.getInstallAction(provider)} ${result.skillName}${selection.targetDir ? ` ${selection.targetDir}` : ''}" to sync this skill.`);
+                        console.log(`\nRecommendation: run "${(0, helpers_1.formatCliCommand)('ospec', 'skill', this.getInstallAction(provider), result.skillName, selection.targetDir)}" to sync this skill.`);
 
                     }
 

package/dist/commands/StatusCommand.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StatusCommand = void 0;
+const path = require("path");
 const services_1 = require("../services");
+const helpers_1 = require("../utils/helpers");
 const BaseCommand_1 = require("./BaseCommand");
 class StatusCommand extends BaseCommand_1.BaseCommand {
     async execute(projectPath) {
@@ -85,6 +87,9 @@ class StatusCommand extends BaseCommand_1.BaseCommand {
                 console.log(`  ${status}: ${count}`);
             }
             console.log(`Protocol summary: PASS ${changes.totals.pass} | WARN ${changes.totals.warn} | FAIL ${changes.totals.fail}`);
+            if (execution.totalActiveChanges > 1) {
+                console.log('Workflow warning: multiple active changes detected. The default workflow expects one active change unless you are explicitly managing extra work as queued changes.');
+            }
             if (execution.activeChanges.length > 0) {
                 console.log('\nCurrent changes:');
                 for (const change of execution.activeChanges) {
@@ -120,37 +125,46 @@ class StatusCommand extends BaseCommand_1.BaseCommand {
         }
     }
     getRecommendedNextSteps(projectPath, structure, docs, execution, queuedChanges, runReport) {
+        const formatCommand = (...args) => (0, helpers_1.formatCliCommand)('ospec', ...args);
         if (!structure.initialized) {
             return [
-                `Run "ospec init ${projectPath}" to initialize the repository to a change-ready state.`,
+                `Run "${formatCommand('init', projectPath)}" to initialize the repository to a change-ready state.`,
             ];
         }
         if (docs.missingRequired.length > 0 || docs.coverage < 100) {
             return [
                 'The repository is initialized, but the project knowledge layer is still incomplete.',
-                `Run "ospec init ${projectPath}" to reconcile the repository back to change-ready state and regenerate missing project knowledge docs.`,
-                `If you only want to refresh or repair docs without rerunning full init messaging, use "ospec docs generate ${projectPath}".`,
+                `Run "${formatCommand('init', projectPath)}" to reconcile the repository back to change-ready state and regenerate missing project knowledge docs.`,
+                `If you only want to refresh or repair docs without rerunning full init messaging, use "${formatCommand('docs', 'generate', projectPath)}".`,
             ];
         }
         if (execution.totalActiveChanges === 0 && queuedChanges.length === 0) {
             return [
-                `Or run "ospec new <change-name> ${projectPath}" if you want to create the first change from CLI.`,
+                `Or run "${formatCommand('new', '<change-name>', projectPath)}" if you want to create the first change from CLI.`,
             ];
         }
         if (execution.totalActiveChanges === 0 && queuedChanges.length > 0) {
             return [
                 `There is no active change right now, but ${queuedChanges.length} queued change(s) are waiting.`,
-                `Run "ospec queue next ${projectPath}" if you want to activate the next queued change manually.`,
-                `Or run "ospec run start ${projectPath}" to begin explicit queue tracking.`,
+                `Run "${formatCommand('queue', 'next', projectPath)}" if you want to activate the next queued change manually.`,
+                `Or run "${formatCommand('run', 'start', projectPath)}" to begin explicit queue tracking.`,
+            ];
+        }
+        if (execution.totalActiveChanges > 1) {
+            return [
+                `Multiple active changes are present. The default workflow expects one active change, but ${execution.totalActiveChanges} were found.`,
+                `Resolve the repository back to a single active change before using "${formatCommand('run', 'start', projectPath)}".`,
+                `For additional work, create queued changes explicitly with "${formatCommand('queue', 'add', '<change-name>', projectPath)}".`,
             ];
         }
         const currentChange = execution.activeChanges[0];
+        const currentChangePath = path.join(projectPath, 'changes', 'active', currentChange.name);
         const nextSteps = [
-            `Continue the active change "${currentChange.name}" with "ospec progress ${projectPath}/changes/active/${currentChange.name}".`,
-            `Run "ospec verify ${projectPath}/changes/active/${currentChange.name}" before trying to archive it.`,
+            `Continue the active change "${currentChange.name}" with "${formatCommand('progress', currentChangePath)}".`,
+            `Run "${formatCommand('verify', currentChangePath)}" before trying to archive it.`,
         ];
         if (queuedChanges.length > 0) {
-            nextSteps.push(`There are ${queuedChanges.length} queued change(s) waiting behind the active one. Use "ospec run ${runReport.currentRun ? 'step' : 'start'} ${projectPath}" when you want explicit queue progression.`);
+            nextSteps.push(`There are ${queuedChanges.length} queued change(s) waiting behind the active one. Use "${formatCommand('run', runReport.currentRun ? 'step' : 'start', projectPath)}" when you want explicit queue progression.`);
         }
         return nextSteps;
     }

package/dist/utils/helpers.d.ts

@@ -1,5 +1,3 @@
-/**
- * 工具函数
- * TODO: 实现辅助函数
- */
-//# sourceMappingURL=helpers.d.ts.map
+export declare function quoteCliArg(value: string): string;
+export declare function formatCliCommand(...args: Array<string | null | undefined>): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/utils/helpers.js

@@ -1,6 +1,22 @@
 "use strict";
-/**
- * 工具函数
- * TODO: 实现辅助函数
- */
-//# sourceMappingURL=helpers.js.map
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatCliCommand = exports.quoteCliArg = void 0;
+function quoteCliArg(value) {
+    const text = String(value ?? '');
+    if (text.length === 0) {
+        return '""';
+    }
+    return /\s/.test(text) ? `"${text.replace(/"/g, '\\"')}"` : text;
+}
+exports.quoteCliArg = quoteCliArg;
+function formatCliCommand(...args) {
+    return args
+        .filter((arg) => arg !== undefined && arg !== null && arg !== '')
+        .map((arg, index) => {
+        const text = String(arg);
+        return index === 0 ? text : quoteCliArg(text);
+    })
+        .join(' ');
+}
+exports.formatCliCommand = formatCliCommand;
+//# sourceMappingURL=helpers.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,6 +21,7 @@
     "index:rebuild": "node dist/tools/build-index.js",
     "validate": "node dist/cli/commands/validate.js",
     "release:smoke": "node scripts/release-smoke.js",
+    "release:notes": "node scripts/release-notes.js",
     "release:sync-version": "node scripts/sync-version.js",
     "release:bump:patch": "npm version patch --no-git-tag-version",
     "release:bump:minor": "npm version minor --no-git-tag-version",