@clawplays/ospec-cli 0.3.2 → 0.3.4

package/dist/services/templates/TemplateBuilderBase.d.ts

@@ -3,7 +3,7 @@ type FrontmatterValue = string | number | boolean | string[];
 export declare abstract class TemplateBuilderBase {
     protected getCurrentDate(): string;
     protected isEnglish(language: TemplateDocumentLanguage): boolean;
-    protected copy(language: TemplateDocumentLanguage, zh: string, en: string): string;
+    protected copy(language: TemplateDocumentLanguage, zh: string, en: string, ja?: string, ar?: string): string;
     protected formatList(items: string[], emptyFallback: string): string;
     protected formatChecklist(items: string[], emptyFallback: string): string;
     protected formatLinkedList(items: Array<{
@@ -16,4 +16,4 @@ export declare abstract class TemplateBuilderBase {
     private toYamlValue;
 }
 export {};
-//# sourceMappingURL=TemplateBuilderBase.d.ts.map
+//# sourceMappingURL=TemplateBuilderBase.d.ts.map

package/dist/services/templates/TemplateBuilderBase.js

@@ -8,8 +8,17 @@ class TemplateBuilderBase {
     isEnglish(language) {
         return language === 'en-US';
     }
-    copy(language, zh, en) {
-        return this.isEnglish(language) ? en : zh;
+    copy(language, zh, en, ja = en, ar = en) {
+        if (language === 'zh-CN') {
+            return zh;
+        }
+        if (language === 'ja-JP') {
+            return ja;
+        }
+        if (language === 'ar') {
+            return ar;
+        }
+        return en;
     }
     formatList(items, emptyFallback) {
         const normalized = items.map(item => item.trim()).filter(Boolean);
@@ -57,4 +66,4 @@ class TemplateBuilderBase {
     }
 }
 exports.TemplateBuilderBase = TemplateBuilderBase;
-//# sourceMappingURL=TemplateBuilderBase.js.map
+//# sourceMappingURL=TemplateBuilderBase.js.map

package/dist/services/templates/TemplateInputFactory.js

@@ -4,14 +4,8 @@ exports.TemplateInputFactory = void 0;
 const constants_1 = require("../../core/constants");
 class TemplateInputFactory {
     normalizeFeatureTemplateInput(input) {
-        const englishDefaults = {
-            background: 'Why is this change needed? What problem exists today?',
-            goals: ['What problem is solved after this change? What do users or developers gain?'],
-            inScope: ['TBD'],
-            outOfScope: ['TBD'],
-            acceptanceCriteria: ['Acceptance item 1', 'Acceptance item 2'],
-        };
         if (typeof input === 'string') {
+            const englishDefaults = this.getFeatureDefaults('en-US');
             return {
                 feature: input,
                 mode: 'standard',
@@ -19,16 +13,17 @@ class TemplateInputFactory {
                 affects: [],
                 flags: [],
                 optionalSteps: [],
-                background: '为什么要做这个 change？当前存在哪些问题？',
-                goals: ['做完之后能解决什么问题？用户或开发者能得到什么？'],
-                inScope: ['待补充'],
-                outOfScope: ['待补充'],
-                acceptanceCriteria: ['条件一', '条件二'],
+                background: englishDefaults.background,
+                goals: [...englishDefaults.goals],
+                inScope: [...englishDefaults.inScope],
+                outOfScope: [...englishDefaults.outOfScope],
+                acceptanceCriteria: [...englishDefaults.acceptanceCriteria],
                 projectContext: this.normalizeFeatureProjectContext(),
-                documentLanguage: 'zh-CN',
+                documentLanguage: 'en-US',
             };
         }
         const documentLanguage = this.normalizeDocumentLanguage(input.documentLanguage);
+        const localizedDefaults = this.getFeatureDefaults(documentLanguage);
         const normalized = {
             feature: input.feature,
             mode: input.mode ?? 'standard',
@@ -36,35 +31,28 @@ class TemplateInputFactory {
             affects: input.affects ?? [],
             flags: input.flags ?? [],
             optionalSteps: input.optionalSteps ?? [],
-            background: input.background?.trim() || '为什么要做这个 change？当前存在哪些问题？',
-            goals: input.goals?.map(item => item.trim()).filter(Boolean) ?? [
-                '做完之后能解决什么问题？用户或开发者能得到什么？',
-            ],
-            inScope: input.inScope?.map(item => item.trim()).filter(Boolean) ?? ['待补充'],
-            outOfScope: input.outOfScope?.map(item => item.trim()).filter(Boolean) ?? ['待补充'],
-            acceptanceCriteria: input.acceptanceCriteria?.map(item => item.trim()).filter(Boolean) ?? [
-                '条件一',
-                '条件二',
-            ],
+            background: input.background?.trim() || localizedDefaults.background,
+            goals: input.goals?.map(item => item.trim()).filter(Boolean) ?? [...localizedDefaults.goals],
+            inScope: input.inScope?.map(item => item.trim()).filter(Boolean) ?? [...localizedDefaults.inScope],
+            outOfScope: input.outOfScope?.map(item => item.trim()).filter(Boolean) ?? [...localizedDefaults.outOfScope],
+            acceptanceCriteria: input.acceptanceCriteria?.map(item => item.trim()).filter(Boolean) ?? [...localizedDefaults.acceptanceCriteria],
             projectContext: this.normalizeFeatureProjectContext(input.projectContext),
             documentLanguage,
         };
-        if (documentLanguage === 'en-US') {
-            if (!input.background?.trim()) {
-                normalized.background = englishDefaults.background;
-            }
-            if (!input.goals?.some(item => item.trim().length > 0)) {
-                normalized.goals = [...englishDefaults.goals];
-            }
-            if (!input.inScope?.some(item => item.trim().length > 0)) {
-                normalized.inScope = [...englishDefaults.inScope];
-            }
-            if (!input.outOfScope?.some(item => item.trim().length > 0)) {
-                normalized.outOfScope = [...englishDefaults.outOfScope];
-            }
-            if (!input.acceptanceCriteria?.some(item => item.trim().length > 0)) {
-                normalized.acceptanceCriteria = [...englishDefaults.acceptanceCriteria];
-            }
+        if (!input.background?.trim()) {
+            normalized.background = localizedDefaults.background;
+        }
+        if (!input.goals?.some(item => item.trim().length > 0)) {
+            normalized.goals = [...localizedDefaults.goals];
+        }
+        if (!input.inScope?.some(item => item.trim().length > 0)) {
+            normalized.inScope = [...localizedDefaults.inScope];
+        }
+        if (!input.outOfScope?.some(item => item.trim().length > 0)) {
+            normalized.outOfScope = [...localizedDefaults.outOfScope];
+        }
+        if (!input.acceptanceCriteria?.some(item => item.trim().length > 0)) {
+            normalized.acceptanceCriteria = [...localizedDefaults.acceptanceCriteria];
         }
         return normalized;
     }
@@ -90,13 +78,10 @@ class TemplateInputFactory {
         const presetSummary = presetDefaults?.summary?.trim();
         const presetArchitecture = presetDefaults?.architecture?.trim();
         const documentLanguage = this.normalizeDocumentLanguage(input?.documentLanguage);
-        const placeholderText = documentLanguage === 'en-US' ? 'TBD' : '待补充';
-        const defaultSummary = documentLanguage === 'en-US'
-            ? `${fallbackName} has been initialized with OSpec and is ready for change-based delivery. Fill in the missing project context as the repository becomes clearer.`
-            : `${fallbackName} 已通过 OSpec 初始化，当前已具备按 change 推进交付的基础条件。请继续补充缺失的项目上下文。`;
-        const defaultArchitecture = documentLanguage === 'en-US'
-            ? 'OSpec initialized the protocol shell and baseline project knowledge docs. Refine the architecture details as the repository direction becomes clearer.'
-            : 'OSpec 已初始化协议壳和基础项目知识文档，后续可结合仓库实际方向继续细化架构。';
+        const localizedBootstrapDefaults = this.getBootstrapDefaults(documentLanguage, fallbackName);
+        const placeholderText = localizedBootstrapDefaults.placeholder;
+        const defaultSummary = localizedBootstrapDefaults.summary;
+        const defaultArchitecture = localizedBootstrapDefaults.architecture;
         const projectName = normalizedInputProjectName || fallbackName;
         const summary = normalizedInputSummary ||
             presetSummary ||
@@ -228,7 +213,10 @@ class TemplateInputFactory {
         };
     }
     normalizeDocumentLanguage(input) {
-        return input === 'en-US' ? 'en-US' : 'zh-CN';
+        if (input === 'zh-CN' || input === 'en-US' || input === 'ja-JP' || input === 'ar') {
+            return input;
+        }
+        return 'en-US';
     }
     pickFieldKeys(fieldSources, source) {
         return Object.entries(fieldSources)
@@ -239,11 +227,78 @@ class TemplateInputFactory {
         const normalized = value.trim().toLowerCase();
         return (normalized.length === 0 ||
             normalized === '待补充' ||
+            normalized === '未定' ||
+            normalized === 'قيد التحديد' ||
+            normalized === 'سيتم تحديده' ||
             normalized === 'todo' ||
             normalized === 'tbd' ||
             normalized.includes('<') ||
             normalized.includes('>'));
     }
+    getFeatureDefaults(documentLanguage) {
+        switch (documentLanguage) {
+            case 'zh-CN':
+                return {
+                    background: '为什么要做这个 change？当前存在哪些问题？',
+                    goals: ['做完之后能解决什么问题？用户或开发者能得到什么？'],
+                    inScope: ['待补充'],
+                    outOfScope: ['待补充'],
+                    acceptanceCriteria: ['条件一', '条件二'],
+                };
+            case 'ja-JP':
+                return {
+                    background: 'なぜこの change が必要ですか。現在どのような問題がありますか。',
+                    goals: ['この change の完了後に何が解決され、ユーザーや開発者は何を得られますか。'],
+                    inScope: ['未定'],
+                    outOfScope: ['未定'],
+                    acceptanceCriteria: ['受け入れ条件 1', '受け入れ条件 2'],
+                };
+            case 'ar':
+                return {
+                    background: 'لماذا نحتاج إلى هذا التغيير؟ ما المشكلة الموجودة حالياً؟',
+                    goals: ['ما المشكلة التي ستُحل بعد هذا التغيير؟ وما الفائدة للمستخدمين أو للمطورين؟'],
+                    inScope: ['قيد التحديد'],
+                    outOfScope: ['قيد التحديد'],
+                    acceptanceCriteria: ['معيار قبول 1', 'معيار قبول 2'],
+                };
+            default:
+                return {
+                    background: 'Why is this change needed? What problem exists today?',
+                    goals: ['What problem is solved after this change? What do users or developers gain?'],
+                    inScope: ['TBD'],
+                    outOfScope: ['TBD'],
+                    acceptanceCriteria: ['Acceptance item 1', 'Acceptance item 2'],
+                };
+        }
+    }
+    getBootstrapDefaults(documentLanguage, fallbackName) {
+        switch (documentLanguage) {
+            case 'zh-CN':
+                return {
+                    placeholder: '待补充',
+                    summary: `${fallbackName} 已通过 OSpec 初始化，当前已具备按 change 推进交付的基础条件。请继续补充缺失的项目上下文。`,
+                    architecture: 'OSpec 已初始化协议壳和基础项目知识文档，后续可结合仓库实际方向继续细化架构。',
+                };
+            case 'ja-JP':
+                return {
+                    placeholder: '未定',
+                    summary: `${fallbackName} は OSpec によって初期化され、change ベースで進めるための基本状態が整いました。リポジトリの方向性が明確になるにつれて不足しているプロジェクト文脈を補ってください。`,
+                    architecture: 'OSpec はプロトコルシェルと基本的なプロジェクト知識ドキュメントを初期化しました。リポジトリの方向性が明確になるにつれて、アーキテクチャ詳細を調整してください。',
+                };
+            case 'ar':
+                return {
+                    placeholder: 'قيد التحديد',
+                    summary: `تمت تهيئة ${fallbackName} بواسطة OSpec وأصبح جاهزاً مبدئياً للتسليم المعتمد على changes. أكمل سياق المشروع الناقص كلما أصبحت صورة المستودع أوضح.`,
+                    architecture: 'قام OSpec بتهيئة غلاف البروتوكول ووثائق معرفة المشروع الأساسية. حسّن تفاصيل المعمارية مع اتضاح اتجاه المستودع.',
+                };
+            default:
+                return {
+                    placeholder: 'TBD',
+                    summary: `${fallbackName} has been initialized with OSpec and is ready for change-based delivery. Fill in the missing project context as the repository becomes clearer.`,
+                    architecture: 'OSpec initialized the protocol shell and baseline project knowledge docs. Refine the architecture details as the repository direction becomes clearer.',
+                };
+        }
+    }
     slugify(value) {
         return value
             .toLowerCase()

package/dist/services/templates/templateTypes.d.ts

@@ -1,6 +1,6 @@
 import { ProjectMode } from '../../core/types';
 import { ProjectPresetId } from '../../presets/ProjectPresets';
-export type TemplateDocumentLanguage = 'zh-CN' | 'en-US';
+export type TemplateDocumentLanguage = 'zh-CN' | 'en-US' | 'ja-JP' | 'ar';
 export interface FeatureTemplateInput {
     feature: string;
     mode?: ProjectMode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "CLI tool for enforcing ospec workflow",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,8 +47,11 @@
   "files": [
     "dist/**",
     "assets/**",
+    "agents/openai.yaml",
     "scripts/postinstall.js",
     ".ospec/templates/hooks/**",
+    "SKILL.md",
+    "skill.yaml",
     "README.md",
     "README.zh-CN.md",
     "LICENSE"

package/skill.yaml

@@ -0,0 +1,151 @@
+name: ospec
+title: OSpec
+description: Document-driven OSpec workflow skill for AI-assisted development with Codex, Claude Code, and similar AI tools.
+version: 5.1.0
+author: OSpec Team
+license: MIT
+
+interface:
+  display_name: "OSpec"
+  short_description: "Inspect, initialize, and operate OSpec projects"
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: use ospec init so the repository ends in change-ready state, reuse existing project docs when available, ask one concise follow-up for missing summary or tech stack in AI-assisted flows, fall back to placeholder docs when the user skips that context, do not assume a web template when the project type is unclear, and do not create the first change automatically."
+
+requires_local:
+  node: ">=18.0.0"
+  npm: ">=8.0.0"
+
+protocol:
+  project_files:
+    - ".skillrc"
+    - "SKILL.md"
+    - "SKILL.index.json"
+    - "build-index-auto.cjs"
+    - "for-ai/ai-guide.md"
+    - "for-ai/execution-protocol.md"
+    - "for-ai/naming-conventions.md"
+    - "for-ai/skill-conventions.md"
+    - "for-ai/workflow-conventions.md"
+    - "for-ai/development-guide.md"
+  feature_files:
+    - "changes/active/<feature>/proposal.md"
+    - "changes/active/<feature>/tasks.md"
+    - "changes/active/<feature>/state.json"
+    - "changes/active/<feature>/verification.md"
+  feature_name_format: "kebab-case"
+
+commands:
+  - id: status
+    command: "ospec status [project-dir]"
+    purpose: "Show project knowledge, execution status, and the recommended next step."
+  - id: init
+    command: "ospec init [root-dir]"
+    purpose: "Initialize the repository to a change-ready state from CLI."
+  - id: docs_generate
+    command: "ospec docs generate [project-dir]"
+    purpose: "Refresh, repair, or backfill the project knowledge layer for an already initialized repository."
+  - id: new
+    command: "ospec new <feature-name> [root-dir]"
+    purpose: "Create a new change under changes/active with proposal/tasks/state/verification/review."
+  - id: changes_status
+    command: "ospec changes status [project-dir]"
+    purpose: "Show PASS/WARN/FAIL protocol status for every active change."
+  - id: docs_status
+    command: "ospec docs status [project-dir]"
+    purpose: "Show project-doc coverage and missing knowledge docs."
+  - id: skills_status
+    command: "ospec skills status [project-dir]"
+    purpose: "Show layered SKILL coverage, module skills, and index status."
+  - id: index_check
+    command: "ospec index check [project-dir]"
+    purpose: "Show whether the skill index exists, is stale, or needs rebuild."
+  - id: index_build
+    command: "ospec index build [project-dir]"
+    purpose: "Rebuild the project skill index."
+  - id: progress
+    command: "ospec progress [changes/active/<feature>]"
+    purpose: "Show progress for a single active feature."
+  - id: verify
+    command: "ospec verify [changes/active/<feature>]"
+    purpose: "Check protocol completeness and optional-step coverage."
+  - id: archive
+    command: "ospec archive [changes/active/<feature>] [--check]"
+    purpose: "Archive a completed change after gate checks; use --check for readiness only."
+  - id: finalize
+    command: "ospec finalize [changes/active/<feature>]"
+    purpose: "Run verify + index refresh + archive as the standard closeout flow before commit."
+  - id: workflow_show
+    command: "ospec workflow show"
+    purpose: "Show workflow configuration for the current project."
+  - id: workflow_flags
+    command: "ospec workflow list-flags"
+    purpose: "List supported workflow feature flags."
+  - id: skill_status
+    command: "ospec skill status"
+    purpose: "Check whether a Codex-installed OSpec skill is present and in sync. Managed defaults are ospec and ospec-change."
+  - id: skill_install
+    command: "ospec skill install"
+    purpose: "Install or sync one OSpec skill package into ~/.codex/skills/. Managed defaults are ospec and ospec-change."
+  - id: skill_status_claude
+    command: "ospec skill status-claude"
+    purpose: "Check whether a Claude Code-installed OSpec skill is present and in sync. Managed defaults are ospec and ospec-change."
+  - id: skill_install_claude
+    command: "ospec skill install-claude"
+    purpose: "Install or sync one OSpec skill package into ~/.claude/skills/. Managed defaults are ospec and ospec-change."
+
+workflow:
+  read_order:
+    - ".skillrc"
+    - "changes/active/<feature>/proposal.md"
+    - "changes/active/<feature>/tasks.md"
+    - "changes/active/<feature>/state.json"
+    - "changes/active/<feature>/verification.md"
+  archive_requirements:
+    - "state.json.status must be ready_to_archive"
+    - "verification.md must be fully passed"
+    - "activated optional steps must appear in tasks.md and verification.md"
+    - "activated optional steps must be listed in verification.md.passed_optional_steps"
+  preferred_entry:
+    - "Run ospec init [path] when the directory is uninitialized or not yet change-ready."
+    - "Pass --summary, --tech-stack, or --architecture during init when CLI users already know the missing project context."
+    - "Run your project deployment and validation flow before archiving the active change."
+    - "Run ospec verify [changes/active/<change>] before archiving."
+    - "Use ospec status [path] when you want an explicit textual summary or troubleshooting snapshot."
+    - "Run ospec docs generate [path] later when you only need a docs maintenance pass."
+    - "Create the first change explicitly instead of assuming initialization will do it."
+
+guardrails:
+  - "Treat init as change-ready initialization, not protocol-shell-only initialization."
+  - "If the user intent is simply to initialize the project or current directory, still trigger the mandatory init flow without asking for a longer prompt."
+  - "When the user asks to initialize, use ospec init to take the repository to change-ready state and verify the managed protocol-shell files plus docs/project/* on disk before declaring success."
+  - "In AI-assisted flows, ask at most one concise follow-up for missing summary or tech stack before init when that context is unavailable."
+  - "If the user declines or no AI follow-up is possible, continue with placeholder docs instead of blocking init."
+  - "Do not assume the project is a web or Next.js project unless the repository or user makes that explicit."
+  - "Do not apply business scaffold during plain init."
+  - "Do not generate docs/project/bootstrap-summary.md during plain init or docs generate."
+  - "Do not create the first change automatically unless the user explicitly asks for a change."
+  - "Treat presets as planning defaults, not as init-time templates."
+
+prompt_profiles:
+  minimal: "Initialize this project with ospec. Use ospec init and verify the managed files before saying it is initialized."
+  standard: "Initialize this project with ospec according to current OSpec rules. Use ospec init so the repository ends in change-ready state, and do not create the first change automatically."
+  guided_init: "Use ospec to initialize this project. If the repository lacks project context, ask me for a short summary or tech stack first. If I skip it, continue with placeholder docs."
+  knowledge_backfill: "Use ospec to refresh or repair the project knowledge layer for this directory. Focus on docs, layered skills, and index state. Do not create a change yet."
+  change_creation: "Use ospec to create and advance a change for this requirement. Respect the current project state and do not treat init as auto-change creation."
+
+usage:
+  new_project_flow:
+    - "Initialize the repository with ospec init [path]."
+    - "If AI can ask follow-up questions and project context is missing, provide a short summary or tech stack once, or skip it and let placeholder docs be generated."
+    - "Create the first active change explicitly."
+    - "Run your project deployment and validation flow, then use ospec verify [changes/active/<change>]."
+    - "Archive the validated change with ospec finalize [changes/active/<change>]."
+    - "Verify .skillrc, changes/, .ospec/, build-index-auto.cjs, for-ai docs, and docs/project/* before claiming init is complete."
+    - "Use presets only as planning defaults; scaffold still requires explicit intent."
+  prompt_shortcuts:
+    - "initialize this project"
+    - "initialize this directory"
+    - "initialize the current project"
+    - "使用 ospec 初始化项目"
+    - "使用 ospec 初始化这个目录"
+    - "use ospec to initialize this directory"
+    - "use ospec to refresh or repair the project knowledge layer"