@clawplays/ospec-cli 0.1.1 → 0.3.0

package/dist/cli.js

@@ -224,7 +224,98 @@ const services_1 = require("./services");
 
 
 
-const CLI_VERSION = '0.1.1';
+const CLI_VERSION = '0.3.0';
+
+function showInitUsage() {
+    console.log('Usage: ospec init [root-dir] [--summary "..."] [--tech-stack node,react] [--architecture "..."] [--document-language zh-CN|en-US]');
+}
+
+function parseInitCommandArgs(commandArgs) {
+    let rootDir;
+    const options = {};
+    for (let index = 0; index < commandArgs.length; index += 1) {
+        const arg = commandArgs[index];
+        if (arg === '--help' || arg === '-h' || arg === 'help') {
+            showInitUsage();
+            process.exit(0);
+        }
+        if (arg === '--summary') {
+            const value = commandArgs[index + 1];
+            if (!value || value.startsWith('--')) {
+                console.error('Error: --summary requires a value');
+                showInitUsage();
+                process.exit(1);
+            }
+            options.summary = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--summary=')) {
+            options.summary = arg.slice('--summary='.length).trim();
+            continue;
+        }
+        if (arg === '--tech-stack') {
+            const value = commandArgs[index + 1];
+            if (!value || value.startsWith('--')) {
+                console.error('Error: --tech-stack requires a comma-separated value');
+                showInitUsage();
+                process.exit(1);
+            }
+            options.techStack = value.split(',').map(item => item.trim()).filter(Boolean);
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--tech-stack=')) {
+            options.techStack = arg.slice('--tech-stack='.length).split(',').map(item => item.trim()).filter(Boolean);
+            continue;
+        }
+        if (arg === '--architecture') {
+            const value = commandArgs[index + 1];
+            if (!value || value.startsWith('--')) {
+                console.error('Error: --architecture requires a value');
+                showInitUsage();
+                process.exit(1);
+            }
+            options.architecture = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--architecture=')) {
+            options.architecture = arg.slice('--architecture='.length).trim();
+            continue;
+        }
+        if (arg === '--document-language' || arg === '--lang') {
+            const value = commandArgs[index + 1];
+            if (!value || value.startsWith('--')) {
+                console.error('Error: --document-language requires a value');
+                showInitUsage();
+                process.exit(1);
+            }
+            options.documentLanguage = value.trim();
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('--document-language=')) {
+            options.documentLanguage = arg.slice('--document-language='.length).trim();
+            continue;
+        }
+        if (arg.startsWith('--lang=')) {
+            options.documentLanguage = arg.slice('--lang='.length).trim();
+            continue;
+        }
+        if (!rootDir) {
+            rootDir = arg;
+            continue;
+        }
+        console.error(`Error: unexpected argument "${arg}"`);
+        showInitUsage();
+        process.exit(1);
+    }
+    return {
+        rootDir,
+        options,
+    };
+}
 
 
 
@@ -432,7 +523,9 @@ async function main() {
 
 
 
-                await initCmd.execute(commandArgs[0]);
+                const { rootDir, options } = parseInitCommandArgs(commandArgs);
+
+                await initCmd.execute(rootDir, options);
 
 
 
@@ -927,7 +1020,7 @@ OSpec CLI v${CLI_VERSION}
 Usage: ospec <command> [options]
 
 Commands:
-  init [root-dir]           Initialize the OSpec protocol shell
+  init [root-dir]           Initialize OSpec to a change-ready state
   new <change-name> [root]  Create a new change (supports --flags)
   verify [path]             Verify change completion
   progress [path]           Show workflow progress
@@ -941,7 +1034,7 @@ Commands:
   docs [action] [path]      Docs helpers (status, generate)
   skills [action] [path]    Skills status helpers (status)
   plugins [action] [path]   Plugin helpers (list, status, enable, disable, approve, reject)
-  skill [action] [skill] [dir] Skill package helpers (default skill is ospec-change)
+  skill [action] [skill] [dir] Skill package helpers (managed skills: ospec, ospec-change)
   index [action] [path]     Index helpers (check, build)
   workflow [action]         Workflow configuration (show, list-flags)
   update [path]             Refresh protocol docs, tooling, hooks, and installed skills; does not enable or migrate plugins
@@ -950,6 +1043,7 @@ Commands:
 
 Examples:
   ospec init
+  ospec init . --summary "Internal admin portal" --tech-stack node,react,postgres
   ospec new onboarding-flow
   ospec new landing-refresh . --flags ui_change,page_design
   ospec verify ./changes/active/onboarding-flow
@@ -972,11 +1066,13 @@ Examples:
   ospec plugins enable checkpoint . --base-url http://127.0.0.1:3000
   ospec plugins run checkpoint ./changes/active/onboarding-flow
   ospec plugins approve stitch ./changes/active/onboarding-flow
-  ospec skill status
-  ospec skill install
+  ospec skill status ospec
+  ospec skill install ospec
+  ospec skill status ospec-change
+  ospec skill install ospec-change
   ospec skill install ospec-init
-  ospec skill status-claude
-  ospec skill install-claude
+  ospec skill status-claude ospec
+  ospec skill install-claude ospec
   ospec index build
   ospec batch stats
   ospec changes status

package/dist/commands/DocsCommand.js

@@ -19,8 +19,8 @@ class DocsCommand extends BaseCommand_1.BaseCommand {
                         throw new Error('Project is not initialized. Run "ospec init" first.');
                     }
                     const result = await services_1.services.projectService.generateProjectKnowledge(targetPath);
-                    console.log('\nProject Knowledge Generated');
-                    console.log('=========================\n');
+                    console.log('\nProject Knowledge Synced');
+                    console.log('======================\n');
                     console.log(`Project: ${result.projectName}`);
                     console.log(`Mode: ${result.mode}`);
                     console.log(`Created files: ${result.createdFiles.length}`);
@@ -29,6 +29,7 @@ class DocsCommand extends BaseCommand_1.BaseCommand {
                     console.log(`Direct-copy assets created: ${result.directCopyCreatedFiles.length}`);
                     console.log(`Hooks installed: ${result.hookInstalledFiles.length}`);
                     console.log(`Runtime-generated files: ${result.runtimeGeneratedFiles.join(', ') || '-'}`);
+                    console.log('Purpose: refresh, repair, or backfill project knowledge docs after initialization');
                     console.log('Business scaffold: not applied by docs generate');
                     console.log('Bootstrap summary: not generated by docs generate');
                     if (result.firstChangeSuggestion) {

package/dist/commands/InitCommand.js

@@ -34,32 +34,90 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.InitCommand = void 0;
+const os_1 = require("os");
 const path = __importStar(require("path"));
 const services_1 = require("../services");
 const BaseCommand_1 = require("./BaseCommand");
+const SkillCommand_1 = require("./SkillCommand");
 class InitCommand extends BaseCommand_1.BaseCommand {
-    async execute(rootDir) {
+    async execute(rootDir, input = {}) {
         try {
             const targetDir = rootDir || process.cwd();
             this.logger.info(`Initializing OSpec project at ${targetDir}`);
             const structure = await services_1.services.projectService.detectProjectStructure(targetDir);
-            if (structure.initialized) {
-                this.warn('Project already initialized');
-                return;
+            let protocolShellCreated = false;
+            if (!structure.initialized) {
+                const config = await services_1.services.configManager.createDefaultConfig('full');
+                await services_1.services.projectService.initializeProtocolShellProject(targetDir, config.mode, {
+                    projectName: path.basename(targetDir),
+                    ...input,
+                });
+                protocolShellCreated = true;
             }
-            const config = await services_1.services.configManager.createDefaultConfig('full');
-            await services_1.services.projectService.initializeProtocolShellProject(targetDir, config.mode, {
-                projectName: path.basename(targetDir),
-            });
-            this.success(`${structure.initialized ? 'Protocol shell refreshed' : 'Protocol shell initialized'} at ${targetDir}`);
-            this.info(`  Created OSpec protocol shell for ${path.basename(targetDir)}`);
-            this.info('  Added .skillrc, changes/, .ospec/, for-ai protocol docs, root SKILL.md, and SKILL.index.json');
+            else {
+                this.info('  Protocol shell already present; reconciling the repository to a change-ready state');
+            }
+            const result = await services_1.services.projectService.generateProjectKnowledge(targetDir, input);
+            const skillResult = await this.syncInstalledSkills();
+            this.success(`Project initialized to change-ready state at ${targetDir}`);
+            this.info(`  Protocol shell: ${protocolShellCreated ? 'created' : 'already present'}`);
+            this.info(`  Project knowledge: ${result.createdFiles.length} created, ${result.refreshedFiles.length} refreshed, ${result.skippedFiles.length} skipped`);
+            this.info(`  Document language: ${result.documentLanguage}`);
+            this.info(`  Codex skills: ${this.formatManagedSkills(skillResult.codex)}`);
+            if (skillResult.claude.length > 0) {
+                this.info(`  Claude skills: ${this.formatManagedSkills(skillResult.claude)}`);
+            }
+            if (input.summary || (Array.isArray(input.techStack) && input.techStack.length > 0) || input.architecture) {
+                this.info('  Applied user-provided project context to the generated knowledge docs');
+            }
+            if (result.firstChangeSuggestion) {
+                this.info(`  Suggested first change: ${result.firstChangeSuggestion.name}`);
+            }
+            this.info(`  Next: ospec new <change-name> ${targetDir}`);
         }
         catch (error) {
             this.error(`Failed to initialize project: ${error}`);
             throw error;
         }
     }
+    getManagedSkillNames() {
+        return ['ospec', 'ospec-change'];
+    }
+    formatManagedSkills(results) {
+        return results.map(result => result.skillName).join(', ');
+    }
+    async syncInstalledSkills() {
+        const skillCommand = new SkillCommand_1.SkillCommand();
+        const codex = [];
+        for (const skillName of this.getManagedSkillNames()) {
+            codex.push(await skillCommand.installSkill('codex', skillName));
+        }
+        const claude = [];
+        if (await this.shouldSyncClaudeSkills()) {
+            for (const skillName of this.getManagedSkillNames()) {
+                claude.push(await skillCommand.installSkill('claude', skillName));
+            }
+        }
+        return { codex, claude };
+    }
+    resolveProviderHome(provider) {
+        const envHome = provider === 'claude'
+            ? String(process.env.CLAUDE_HOME || '').trim()
+            : String(process.env.CODEX_HOME || '').trim();
+        if (envHome) {
+            return path.resolve(envHome);
+        }
+        return provider === 'claude'
+            ? path.join((0, os_1.homedir)(), '.claude')
+            : path.join((0, os_1.homedir)(), '.codex');
+    }
+    async shouldSyncClaudeSkills() {
+        const claudeHome = this.resolveProviderHome('claude');
+        if (String(process.env.CLAUDE_HOME || '').trim()) {
+            return true;
+        }
+        return services_1.services.fileService.exists(claudeHome);
+    }
 }
 exports.InitCommand = InitCommand;
 //# sourceMappingURL=InitCommand.js.map

package/dist/commands/SkillCommand.js

@@ -28,11 +28,11 @@ const ACTION_SKILLS = [
 
         title: 'OSpec Init',
 
-        description: 'Initialize the OSpec protocol shell for a directory without assuming stack templates or creating the first change.',
+        description: 'Initialize an OSpec repository to change-ready state without creating the first change automatically.',
 
-        shortDescription: 'Initialize OSpec protocol shell',
+        shortDescription: 'Initialize OSpec to change-ready',
 
-        defaultPrompt: 'Use $ospec-init to inspect the target directory, run ospec status first, initialize the protocol shell with ospec init when needed, and verify the protocol-shell files on disk. Do not create docs backfill, business scaffold, or the first change automatically.',
+        defaultPrompt: 'Use $ospec-init to initialize the target directory with ospec init so the repository ends in change-ready state. Reuse existing project docs when available. If the repository lacks a usable project overview and you are in an AI-assisted flow, ask one concise question for project summary or tech stack before calling ospec init with those inputs; if the user declines, run plain ospec init and allow placeholder docs. Verify the protocol-shell files and project knowledge docs on disk. Do not create the first change automatically.',
 
         markdown: `# OSpec Init
 
@@ -46,15 +46,17 @@ Use this action when the user intent is initialization.
 
 
 
-- run \`ospec status [path]\` first
+- use \`ospec init [path]\` so the repository ends in change-ready state
 
-- use \`ospec init [path]\` for plain initialization
+- verify \`.skillrc\`, \`.ospec/\`, \`changes/\`, \`SKILL.md\`, \`SKILL.index.json\`, \`build-index-auto.cjs\`, \`for-ai/\`, and \`docs/project/\` files on disk
 
-- verify \`.skillrc\`, \`.ospec/\`, \`changes/\`, \`SKILL.md\`, \`SKILL.index.json\`, \`build-index-auto.cjs\`, and \`for-ai/\` files on disk
+- if project overview context is missing and AI can ask follow-up questions, ask for a brief summary or tech stack before initialization; if the user declines, fall back to placeholder docs
+
+- use \`ospec status [path]\` only when you want an explicit summary or troubleshooting snapshot
 
 - do not assume a web template when the project type is unclear
 
-- do not backfill docs or create the first change unless explicitly requested
+- do not create the first change unless explicitly requested
 
 
 
@@ -64,10 +66,12 @@ Use this action when the user intent is initialization.
 
 \`\`\`bash
 
-ospec status [path]
-
 ospec init [path]
 
+ospec init [path] --summary "..." --tech-stack node,react
+
+ospec status [path]
+
 \`\`\`
 
 `,
@@ -130,17 +134,17 @@ ospec changes status [path]
 
         title: 'OSpec Backfill',
 
-        description: 'Backfill the project knowledge layer after protocol-shell init without applying business scaffold or creating a change.',
+        description: 'Refresh or repair the project knowledge layer for an initialized repository without creating a change.',
 
-        shortDescription: 'Backfill project knowledge layer',
+        shortDescription: 'Refresh project knowledge layer',
 
-        defaultPrompt: 'Use $ospec-backfill to backfill the project knowledge layer after protocol-shell init. Prefer ospec docs generate, keep scaffold explicit, and do not create the first change automatically.',
+        defaultPrompt: 'Use $ospec-backfill to refresh, repair, or backfill the project knowledge layer for an initialized repository. Prefer ospec docs generate when you only need docs maintenance, keep scaffold explicit, and do not create the first change automatically.',
 
         markdown: `# OSpec Backfill
 
 
 
-Use this action after the protocol shell already exists and the repository still lacks project knowledge.
+Use this action after the repository is already initialized and the project knowledge docs need maintenance.
 
 
 
@@ -148,7 +152,7 @@ Use this action after the protocol shell already exists and the repository still
 
 
 
-- require the protocol shell first
+- require an initialized repository first
 
 - prefer \`ospec docs generate [path]\`
 
@@ -787,7 +791,7 @@ class SkillCommand extends BaseCommand_1.BaseCommand {
 
             title: 'OSpec',
 
-            description: 'Protocol-shell-first OSpec workflow for initialization, project knowledge backfill, change execution, verification, and archive readiness.',
+            description: 'Protocol-shell-first OSpec workflow for inspection, change-ready initialization, docs maintenance, change execution, verification, and archive readiness.',
 
             shortDescription: 'Inspect, initialize, and operate OSpec projects',
 
@@ -1025,7 +1029,7 @@ ${markdownBody.trimStart()}`;
 
         if (/^---\r?\n/.test(definition.markdown)) {
 
-            return definition.markdown;
+            return this.ensureFrontmatterDescription(definition.markdown, definition.description);
 
         }
 
@@ -1045,6 +1049,24 @@ ${definition.markdown.trimStart()}`;
 
     }
 
+    ensureFrontmatterDescription(markdown, description) {
+
+        if (!/^---\r?\n/.test(markdown)) {
+
+            return markdown;
+
+        }
+
+        if (/^---\r?\n[\s\S]*?\r?\ndescription:\s+/m.test(markdown)) {
+
+            return markdown;
+
+        }
+
+        return markdown.replace(/^---\r?\n/, `---\ndescription: ${description}\n`);
+
+    }
+
     escapeYaml(value) {
 
         return value.replace(/"/g, '\\"');
@@ -1091,7 +1113,7 @@ Prefer this prompt style for new work:
 
 2. \`Use ospec to inspect this repository\`
 
-3. \`Use ospec to backfill the project knowledge layer\`
+3. \`Use ospec to refresh or repair the project knowledge layer\`
 
 4. \`Use ospec to create and advance a change for this requirement\`
 
@@ -1157,7 +1179,7 @@ interface:
 
   short_description: "Legacy alias for the OSpec skill"
 
-  default_prompt: "Use $ospec to inspect and initialize this directory according to OSpec rules: protocol shell first, explicit knowledge backfill, no assumed web template when the project type is unclear, and no automatic first change."
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: init should end in change-ready state, reuse existing docs when available, ask for missing summary or tech stack in AI-assisted flows before falling back to placeholder docs, avoid assumed web templates when the project type is unclear, and do not create the first change automatically."
 
 `,
 
@@ -1167,7 +1189,7 @@ interface:
 
   short_description: "Legacy alias for the OSpec skill"
 
-  default_prompt: "Use $ospec to inspect and initialize this directory according to OSpec rules: protocol shell first, explicit knowledge backfill, no assumed web template when the project type is unclear, and no automatic first change."
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: init should end in change-ready state, reuse existing docs when available, ask for missing summary or tech stack in AI-assisted flows before falling back to placeholder docs, avoid assumed web templates when the project type is unclear, and do not create the first change automatically."
 
 `,
 

package/dist/commands/StatusCommand.js

@@ -8,22 +8,40 @@ class StatusCommand extends BaseCommand_1.BaseCommand {
         try {
             const targetPath = projectPath || process.cwd();
             this.logger.info(`Getting status for ${targetPath}`);
-            const [structure, summary, docs, skills, execution, changes, queuedChanges, runReport] = await Promise.all([
-                services_1.services.projectService.detectProjectStructure(targetPath),
+            const structure = await services_1.services.projectService.detectProjectStructure(targetPath);
+            const [summary, docs, skills, queuedChanges] = await Promise.all([
                 services_1.services.projectService.getProjectSummary(targetPath),
                 services_1.services.projectService.getDocsStatus(targetPath),
                 services_1.services.projectService.getSkillsStatus(targetPath),
-                services_1.services.projectService.getExecutionStatus(targetPath),
-                services_1.services.projectService.getActiveChangeStatusReport(targetPath),
                 services_1.services.queueService.getQueuedChanges(targetPath),
-                services_1.services.runService.getStatusReport(targetPath),
             ]);
+            let execution = {
+                totalActiveChanges: summary.activeChangeCount,
+                byStatus: {},
+                activeChanges: [],
+            };
+            let changes = {
+                totals: { pass: 0, warn: 0, fail: 0 },
+            };
+            let runReport = {
+                currentRun: undefined,
+                stage: undefined,
+                nextInstruction: undefined,
+            };
+            if (structure.initialized) {
+                [execution, changes, runReport] = await Promise.all([
+                    services_1.services.projectService.getExecutionStatus(targetPath),
+                    services_1.services.projectService.getActiveChangeStatusReport(targetPath),
+                    services_1.services.runService.getStatusReport(targetPath),
+                ]);
+            }
             console.log('\nProject Status');
             console.log('==============\n');
             console.log(`Name: ${summary.name}`);
             console.log(`Path: ${summary.path}`);
             console.log(`Mode: ${summary.mode ?? 'uninitialized'}`);
             console.log(`Initialized: ${summary.initialized ? 'yes' : 'no'}`);
+            console.log(`Change Ready: ${summary.initialized && docs.missingRequired.length === 0 ? 'yes' : 'no'}`);
             console.log(`Structure Level: ${summary.structureLevel}`);
             console.log(`Active Changes: ${summary.activeChangeCount}`);
             console.log(`Queued Changes: ${queuedChanges.length}`);
@@ -104,13 +122,14 @@ class StatusCommand extends BaseCommand_1.BaseCommand {
     getRecommendedNextSteps(projectPath, structure, docs, execution, queuedChanges, runReport) {
         if (!structure.initialized) {
             return [
-                `Run "ospec init ${projectPath}" to initialize the OSpec protocol shell.`,
+                `Run "ospec init ${projectPath}" to initialize the repository to a change-ready state.`,
             ];
         }
         if (docs.missingRequired.length > 0 || docs.coverage < 100) {
             return [
-                'The OSpec protocol shell is ready, but the project knowledge layer is still incomplete.',
-                `Run "ospec docs generate ${projectPath}" to backfill the default project knowledge layer. This still will not apply business scaffold or generate docs/project/bootstrap-summary.md.`,
+                '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}".`,
             ];
         }
         if (execution.totalActiveChanges === 0 && queuedChanges.length === 0) {

package/dist/commands/UpdateCommand.js

@@ -30,9 +30,9 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         if (toolingResult.hookInstalledFiles.length > 0) {
             this.info(`  git hooks refreshed: ${toolingResult.hookInstalledFiles.join(', ')}`);
         }
-        this.info(`  codex skill: ${skillResult.codex.targetDir}`);
-        if (skillResult.claude) {
-            this.info(`  claude skill: ${skillResult.claude.targetDir}`);
+        this.info(`  codex skills: ${this.formatManagedSkills(skillResult.codex)}`);
+        if (skillResult.claude.length > 0) {
+            this.info(`  claude skills: ${this.formatManagedSkills(skillResult.claude)}`);
         }
         if (pluginResult.enabledPlugins.length > 0) {
             this.info(`  plugin assets refreshed: ${pluginResult.enabledPlugins.join(', ')}`);
@@ -222,10 +222,24 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
         }
         return { createdFiles, skippedFiles };
     }
+    getManagedSkillNames() {
+        return ['ospec', 'ospec-change'];
+    }
+    formatManagedSkills(results) {
+        return results.map(result => result.skillName).join(', ');
+    }
     async syncInstalledSkills() {
         const skillCommand = new SkillCommand_1.SkillCommand();
-        const codex = await skillCommand.installSkill('codex', 'ospec-change');
-        const claude = (await this.shouldSyncClaudeSkills()) ? await skillCommand.installSkill('claude', 'ospec-change') : null;
+        const codex = [];
+        for (const skillName of this.getManagedSkillNames()) {
+            codex.push(await skillCommand.installSkill('codex', skillName));
+        }
+        const claude = [];
+        if (await this.shouldSyncClaudeSkills()) {
+            for (const skillName of this.getManagedSkillNames()) {
+                claude.push(await skillCommand.installSkill('claude', skillName));
+            }
+        }
         return { codex, claude };
     }
     resolveProviderHome(provider) {