@clawplays/ospec-cli 1.0.1 → 1.0.2

package/README.md

@@ -94,6 +94,7 @@ CLI notes:
 - CLI language resolution order: explicit `--document-language` -> persisted project language in `.skillrc` -> existing project docs / managed `for-ai/*` guidance / asset manifest -> fallback `en-US`
 - OSpec persists the chosen project document language in `.skillrc` and reuses it for `for-ai` guidance, `ospec new`, and `ospec update`
 - new projects initialized by `ospec init` default to the nested layout: root `.skillrc` and `README.md`, with OSpec-managed files under `.ospec/`
+- plain init does not create optional knowledge maps such as `.ospec/knowledge/src/` or `.ospec/knowledge/tests/`; those appear only when a project already has legacy knowledge content to migrate or when future explicit knowledge-generation flows create them
 - CLI commands still accept shorthand like `changes/active/<change-name>`, but the physical path in nested projects is `.ospec/changes/active/<change-name>`
 - if you pass these values, OSpec uses them directly when generating project docs
 - if you do not pass them, OSpec reuses existing docs when possible and otherwise creates placeholder docs first
@@ -171,6 +172,7 @@ ospec update
 
 `ospec update` also migrates legacy root-level `build-index-auto.cjs` / `build-index-auto.js` tooling into `.ospec/tools/build-index-auto.cjs` and refreshes OSpec-managed hook entrypoints to use the new location.
 It also repairs older OSpec projects that still have an OSpec footprint but are missing newer core runtime directories, refreshes managed skills and archive layout metadata, and syncs project assets for already-enabled plugins.
+For nested projects that still carry legacy knowledge under `.ospec/src/` or `.ospec/tests/`, `ospec update` migrates those paths into `.ospec/knowledge/src/` and `.ospec/knowledge/tests/`.
 When an already-enabled plugin has a newer compatible npm package version available, `ospec update` upgrades that global plugin package automatically and prints the version transition.
 It does not upgrade the CLI itself, and it does not enable plugins or migrate active / queued changes automatically.
 It also does not switch a classic project layout to nested automatically.

package/SKILL.md

@@ -37,9 +37,10 @@ If the user intent is simply to initialize the project or current directory, tre
 Use this exact behavior:
 
 1. run `ospec init [path]` when the directory is uninitialized or not yet change-ready
-2. if AI assistance is available and the repository lacks usable project context, ask one concise follow-up for summary or tech stack before init when helpful
-3. verify the actual filesystem result before claiming initialization is complete
-4. stop before `ospec new` unless the user explicitly asks to create a change
+2. in AI-assisted init, map an explicit language request or the current conversation language to `--document-language`; do not assume a brand-new repo will infer it
+3. if AI assistance is available and the repository lacks usable project context, ask one concise follow-up for summary or tech stack before init when helpful
+4. verify the actual filesystem result before claiming initialization is complete
+5. stop before `ospec new` unless the user explicitly asks to create a change
 
 Never replace `ospec init` with manual directory creation or a hand-written approximation.
 
@@ -66,7 +67,7 @@ Required checks after `ospec init`:
 - `docs/project/module-map.md`
 - `docs/project/api-overview.md`
 
-During plain init, do not report `docs/SKILL.md`, `src/SKILL.md`, `tests/SKILL.md`, or business scaffold as if they were part of change-ready completion.
+During plain init, do not report `docs/SKILL.md`, optional knowledge maps such as `knowledge/src/SKILL.md` / `knowledge/tests/SKILL.md`, or business scaffold as if they were part of change-ready completion.
 
 ## Prompt Profiles
 
@@ -133,6 +134,7 @@ Use ospec to create a change queue and execute it explicitly with ospec run manu
 Always keep these rules:
 
 - `ospec init` should leave the repository in a change-ready state
+- in AI-assisted init, pass `--document-language` from the explicit language request or current conversation language when the project language is already apparent
 - AI-assisted init may ask one concise follow-up question for missing summary or tech stack; if the user declines, continue with placeholder docs
 - `ospec docs generate` refreshes, repairs, or backfills project knowledge docs after initialization
 - when the user asks to initialize, execute the CLI init command and verify the protocol-shell files and `docs/project/*` files on disk before declaring success
@@ -184,6 +186,7 @@ Do not fall back to the old `features/...` layout unless the target repository r
 ```bash
 ospec status [path]
 ospec init [path]
+ospec init [path] --document-language zh-CN
 ospec init [path] --summary "..." --tech-stack node,react
 ospec docs generate [path]
 ospec new <change-name> [path]

package/agents/openai.yaml

@@ -1,4 +1,4 @@
 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, do not create the first change automatically, and use ospec status or ospec changes status only when you need an explicit summary."
+  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, map an explicit language request or the current conversation language to --document-language during AI-assisted init instead of assuming a brand-new repo will infer it, 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, do not create the first change automatically, and use ospec status or ospec changes status only when you need an explicit summary."

package/dist/cli.js

@@ -55,7 +55,7 @@ const VerifyCommand_1 = require("./commands/VerifyCommand");
 const WorkflowCommand_1 = require("./commands/WorkflowCommand");
 const LayoutCommand_1 = require("./commands/LayoutCommand");
 const services_1 = require("./services");
-const CLI_VERSION = '1.0.1';
+const CLI_VERSION = '1.0.2';
 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/LayoutCommand.js

@@ -159,16 +159,16 @@ class LayoutCommand extends BaseCommand_1.BaseCommand {
             constants_1.FILE_NAMES.SKILL_INDEX,
             'changes',
             'for-ai',
+            'knowledge',
             'docs/project',
             'docs/design',
             'docs/planning',
             'docs/api',
             'docs/SKILL.md',
-            'tests/SKILL.md',
         ]) {
             plannedRelativePaths.add(relativePath);
         }
-        for (const baseDir of ['src', 'docs', 'tests']) {
+        for (const baseDir of ['knowledge', 'src', 'docs', 'tests']) {
             const absoluteBaseDir = path.join(rootDir, baseDir);
             if (!(await services_1.services.fileService.exists(absoluteBaseDir))) {
                 continue;

package/dist/commands/SkillCommand.js

@@ -16,7 +16,7 @@ const ACTION_SKILLS = [
         title: 'OSpec Init',
         description: 'Initialize an OSpec repository to change-ready state without creating the first change automatically.',
         shortDescription: 'Initialize OSpec to change-ready',
-        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.',
+        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. In AI-assisted init, map an explicit language request or the current conversation language to --document-language instead of assuming a brand-new repo will infer it. 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
 
 
@@ -31,6 +31,8 @@ Use this action when the user intent is initialization.
 
 - use \`ospec init [path]\` so the repository ends in change-ready state
 
+- in AI-assisted init, map an explicit language request or the current conversation language to \`--document-language\`
+
 - verify root \`.skillrc\` and \`README.md\`, plus managed OSpec files under \`.ospec/\` including \`.ospec/SKILL.md\`, \`.ospec/SKILL.index.json\`, \`.ospec/changes/\`, \`.ospec/tools/build-index-auto.cjs\`, \`.ospec/for-ai/\`, and \`.ospec/docs/project/\` on disk for new projects
 
 - 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
@@ -51,6 +53,8 @@ Use this action when the user intent is initialization.
 
 ospec init [path]
 
+ospec init [path] --document-language zh-CN
+
 ospec init [path] --summary "..." --tech-stack node,react
 
 ospec status [path]
@@ -841,7 +845,7 @@ interface:
 
   short_description: "Legacy alias for the OSpec skill"
 
-  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."
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: init should end in change-ready state, reuse existing docs when available, map an explicit language request or the current conversation language to --document-language during AI-assisted init instead of assuming a brand-new repo will infer it, 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."
 
 `,
             openaiYaml: `interface:
@@ -850,7 +854,7 @@ interface:
 
   short_description: "Legacy alias for the OSpec skill"
 
-  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."
+  default_prompt: "Use $ospec to initialize this directory according to OSpec rules: init should end in change-ready state, reuse existing docs when available, map an explicit language request or the current conversation language to --document-language during AI-assisted init instead of assuming a brand-new repo will infer it, 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/UpdateCommand.d.ts

@@ -5,6 +5,14 @@ export declare class UpdateCommand extends BaseCommand {
     private repairLegacyProjectForUpdate;
     private detectLegacyProjectMarkers;
     private syncProjectTooling;
+    private migrateLegacyKnowledgeLayout;
+    private syncProjectCliVersionMetadata;
+    private detectProjectCliVersion;
+    private isLegacyKnowledgeMigrationEligible;
+    private isCliVersionAtLeast;
+    private mergeLegacyKnowledgeDirectory;
+    private refreshMigratedKnowledgeLinks;
+    private rewriteFileIfChanged;
     private ensureEnabledPluginPackageAvailable;
     private maybeUpgradeEnabledPluginPackage;
     private refreshExternalPluginInstalledMetadata;

package/dist/commands/UpdateCommand.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UpdateCommand = void 0;
+const fs_1 = require("fs");
 const os_1 = require("os");
 const path_1 = require("path");
 const services_1 = require("../services");
@@ -22,12 +23,16 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
             throw new Error('Project is not initialized. Run "ospec init" first.');
         }
         this.info(`Updating OSpec project at ${targetPath}`);
+        const cliVersionMetadataSync = await this.syncProjectCliVersionMetadata(targetPath);
+        const legacyKnowledgeMigration = await this.migrateLegacyKnowledgeLayout(targetPath, cliVersionMetadataSync.effectiveProjectCliVersion);
         const protocolResult = await services_1.services.projectService.syncProtocolGuidance(targetPath);
         const toolingResult = await this.syncProjectTooling(targetPath, protocolResult.documentLanguage);
         const pluginResult = await this.syncEnabledPluginAssets(targetPath);
         const archiveResult = await this.syncArchiveLayout(targetPath);
         const skillResult = await this.syncInstalledSkills();
         const refreshedFiles = Array.from(new Set([
+            ...(cliVersionMetadataSync.configSaved ? ['.skillrc'] : []),
+            ...legacyKnowledgeMigration.refreshedFiles,
             ...protocolResult.refreshedFiles,
             ...toolingResult.refreshedFiles,
             ...pluginResult.refreshedFiles,
@@ -49,6 +54,20 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
                 this.info(`  legacy paths normalized: ${legacyRepair.refreshedPaths.join(', ')}`);
             }
         }
+        if (cliVersionMetadataSync.configSaved) {
+            this.info('  project CLI version metadata normalized: .skillrc');
+        }
+        if (legacyKnowledgeMigration.performed) {
+            if (legacyKnowledgeMigration.migratedPaths.length > 0) {
+                this.info(`  legacy knowledge migrated: ${legacyKnowledgeMigration.migratedPaths.join(', ')}`);
+            }
+            if (legacyKnowledgeMigration.refreshedFiles.length > 0) {
+                this.info(`  migrated knowledge links refreshed: ${legacyKnowledgeMigration.refreshedFiles.join(', ')}`);
+            }
+            if (legacyKnowledgeMigration.removedPaths.length > 0) {
+                this.info(`  legacy knowledge paths removed: ${legacyKnowledgeMigration.removedPaths.join(', ')}`);
+            }
+        }
         if (toolingResult.hookInstalledFiles.length > 0) {
             this.info(`  git hooks refreshed: ${toolingResult.hookInstalledFiles.join(', ')}`);
         }
@@ -205,6 +224,228 @@ class UpdateCommand extends BaseCommand_1.BaseCommand {
             removedLegacyFiles,
         };
     }
+    async migrateLegacyKnowledgeLayout(rootDir, effectiveProjectCliVersion) {
+        const config = await services_1.services.configManager.loadConfig(rootDir).catch(() => null);
+        if (!(await this.isLegacyKnowledgeMigrationEligible(rootDir, config, effectiveProjectCliVersion))) {
+            return {
+                performed: false,
+                migratedPaths: [],
+                refreshedFiles: [],
+                removedPaths: [],
+            };
+        }
+        const knowledgeRoot = (0, path_1.join)(rootDir, '.ospec', 'knowledge');
+        const migrations = [
+            {
+                sourcePath: (0, path_1.join)(rootDir, '.ospec', 'src'),
+                targetPath: (0, path_1.join)(knowledgeRoot, 'src'),
+                sourceRelativePath: '.ospec/src',
+                targetRelativePath: '.ospec/knowledge/src',
+            },
+            {
+                sourcePath: (0, path_1.join)(rootDir, '.ospec', 'tests'),
+                targetPath: (0, path_1.join)(knowledgeRoot, 'tests'),
+                sourceRelativePath: '.ospec/tests',
+                targetRelativePath: '.ospec/knowledge/tests',
+            },
+        ];
+        if (!(await Promise.all(migrations.map(item => services_1.services.fileService.exists(item.sourcePath)))).some(Boolean)) {
+            return {
+                performed: false,
+                migratedPaths: [],
+                refreshedFiles: [],
+                removedPaths: [],
+            };
+        }
+        await services_1.services.fileService.ensureDir(knowledgeRoot);
+        const migratedPaths = [];
+        const removedPaths = [];
+        for (const migration of migrations) {
+            if (!(await services_1.services.fileService.exists(migration.sourcePath))) {
+                continue;
+            }
+            if (!(await services_1.services.fileService.exists(migration.targetPath))) {
+                await services_1.services.fileService.move(migration.sourcePath, migration.targetPath);
+                migratedPaths.push(`${migration.sourceRelativePath} -> ${migration.targetRelativePath}`);
+                continue;
+            }
+            await this.mergeLegacyKnowledgeDirectory(migration.sourcePath, migration.targetPath);
+            await services_1.services.fileService.remove(migration.sourcePath);
+            migratedPaths.push(`${migration.sourceRelativePath} -> ${migration.targetRelativePath}`);
+            removedPaths.push(migration.sourceRelativePath);
+        }
+        const refreshedFiles = await this.refreshMigratedKnowledgeLinks(rootDir);
+        return {
+            performed: migratedPaths.length > 0 || refreshedFiles.length > 0 || removedPaths.length > 0,
+            migratedPaths,
+            refreshedFiles,
+            removedPaths,
+        };
+    }
+    async syncProjectCliVersionMetadata(rootDir) {
+        const config = await services_1.services.configManager.loadConfig(rootDir).catch(() => null);
+        if (!config) {
+            return {
+                configSaved: false,
+                effectiveProjectCliVersion: null,
+            };
+        }
+        const detectedProjectCliVersion = await this.detectProjectCliVersion(rootDir, config);
+        if (typeof config.ospecCliVersion === 'string' && config.ospecCliVersion.trim().length > 0) {
+            return {
+                configSaved: false,
+                effectiveProjectCliVersion: config.ospecCliVersion.trim(),
+            };
+        }
+        if (!detectedProjectCliVersion) {
+            return {
+                configSaved: false,
+                effectiveProjectCliVersion: null,
+            };
+        }
+        await services_1.services.configManager.saveConfig(rootDir, {
+            ...config,
+            ospecCliVersion: detectedProjectCliVersion,
+        });
+        return {
+            configSaved: true,
+            effectiveProjectCliVersion: detectedProjectCliVersion,
+        };
+    }
+    async detectProjectCliVersion(rootDir, config) {
+        if (typeof config?.ospecCliVersion === 'string' && config.ospecCliVersion.trim().length > 0) {
+            return config.ospecCliVersion.trim();
+        }
+        const assetManifestPath = (0, path_1.join)(rootDir, '.ospec', 'asset-sources.json');
+        if (await services_1.services.fileService.exists(assetManifestPath)) {
+            try {
+                const assetManifest = await services_1.services.fileService.readJSON(assetManifestPath);
+                if (typeof assetManifest?.ospecCliVersion === 'string' && assetManifest.ospecCliVersion.trim().length > 0) {
+                    return assetManifest.ospecCliVersion.trim();
+                }
+            }
+            catch {
+                return null;
+            }
+            return '1.0.0';
+        }
+        const legacyKnowledgeRoots = [
+            (0, path_1.join)(rootDir, '.ospec', 'src'),
+            (0, path_1.join)(rootDir, '.ospec', 'tests'),
+        ];
+        if ((await Promise.all(legacyKnowledgeRoots.map(target => services_1.services.fileService.exists(target)))).some(Boolean)) {
+            return '1.0.0';
+        }
+        return null;
+    }
+    async isLegacyKnowledgeMigrationEligible(rootDir, config, effectiveProjectCliVersion) {
+        if (config?.projectLayout !== 'nested') {
+            return false;
+        }
+        if (!effectiveProjectCliVersion || !this.isCliVersionAtLeast(effectiveProjectCliVersion, '1.0.0')) {
+            return false;
+        }
+        return true;
+    }
+    isCliVersionAtLeast(version, minimum) {
+        const parse = (value) => String(value || '')
+            .trim()
+            .replace(/^v/i, '')
+            .split('-', 1)[0]
+            .split('.')
+            .map(part => Number.parseInt(part, 10));
+        const left = parse(version);
+        const right = parse(minimum);
+        for (let index = 0; index < Math.max(left.length, right.length, 3); index += 1) {
+            const leftPart = Number.isFinite(left[index]) ? left[index] : 0;
+            const rightPart = Number.isFinite(right[index]) ? right[index] : 0;
+            if (leftPart > rightPart) {
+                return true;
+            }
+            if (leftPart < rightPart) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async mergeLegacyKnowledgeDirectory(sourceDir, targetDir) {
+        await services_1.services.fileService.ensureDir(targetDir);
+        const entries = await fs_1.promises.readdir(sourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const sourcePath = (0, path_1.join)(sourceDir, entry.name);
+            const targetPath = (0, path_1.join)(targetDir, entry.name);
+            if (entry.isDirectory()) {
+                await this.mergeLegacyKnowledgeDirectory(sourcePath, targetPath);
+                continue;
+            }
+            if (await services_1.services.fileService.exists(targetPath)) {
+                continue;
+            }
+            await services_1.services.fileService.move(sourcePath, targetPath);
+        }
+    }
+    async refreshMigratedKnowledgeLinks(rootDir) {
+        const refreshedFiles = [];
+        const knowledgeSourceRoot = (0, path_1.join)(rootDir, '.ospec', 'knowledge', 'src');
+        const rewrites = [
+            {
+                filePath: (0, path_1.join)(rootDir, '.ospec', 'SKILL.md'),
+                transform: content => content
+                    .replace(/\]\(src\/SKILL\.md\)/g, '](knowledge/src/SKILL.md)')
+                    .replace(/\]\(tests\/SKILL\.md\)/g, '](knowledge/tests/SKILL.md)'),
+            },
+            {
+                filePath: (0, path_1.join)(rootDir, '.ospec', 'docs', 'project', 'module-map.md'),
+                transform: content => content.replace(/\(src\/modules\//g, '(../../knowledge/src/modules/'),
+            },
+            {
+                filePath: (0, path_1.join)(knowledgeSourceRoot, 'SKILL.md'),
+                transform: content => content
+                    .replace(/src\/SKILL\.md/g, 'knowledge/src/SKILL.md')
+                    .replace(/`src\/modules\/<module>\/SKILL\.md`/g, '`knowledge/src/modules/<module>/SKILL.md`'),
+            },
+            {
+                filePath: (0, path_1.join)(knowledgeSourceRoot, 'core', 'SKILL.md'),
+                transform: content => content
+                    .replace(/src\/SKILL\.md/g, 'knowledge/src/SKILL.md')
+                    .replace(/\.\.\/\.\.\/docs\/project\//g, '../../../docs/project/'),
+            },
+        ];
+        for (const rewrite of rewrites) {
+            if (await this.rewriteFileIfChanged(rewrite.filePath, rewrite.transform)) {
+                refreshedFiles.push(this.toRelativePath(rootDir, rewrite.filePath));
+            }
+        }
+        const moduleSkillsRoot = (0, path_1.join)(knowledgeSourceRoot, 'modules');
+        if (!(await services_1.services.fileService.exists(moduleSkillsRoot))) {
+            return refreshedFiles;
+        }
+        const moduleEntries = await fs_1.promises.readdir(moduleSkillsRoot, { withFileTypes: true });
+        for (const entry of moduleEntries) {
+            if (!entry.isDirectory()) {
+                continue;
+            }
+            const skillPath = (0, path_1.join)(moduleSkillsRoot, entry.name, 'SKILL.md');
+            if (await this.rewriteFileIfChanged(skillPath, content => content
+                .replace(/src\/SKILL\.md/g, 'knowledge/src/SKILL.md')
+                .replace(/\.\.\/\.\.\/\.\.\/docs\/project\//g, '../../../../docs/project/'))) {
+                refreshedFiles.push(this.toRelativePath(rootDir, skillPath));
+            }
+        }
+        return refreshedFiles;
+    }
+    async rewriteFileIfChanged(filePath, transform) {
+        if (!(await services_1.services.fileService.exists(filePath))) {
+            return false;
+        }
+        const before = await services_1.services.fileService.readFile(filePath);
+        const after = transform(before);
+        if (after === before) {
+            return false;
+        }
+        await services_1.services.fileService.writeFile(filePath, after);
+        return true;
+    }
     async syncEnabledPluginAssets(rootDir) {
         const rawConfig = await services_1.services.fileService.readJSON((0, path_1.join)(rootDir, '.skillrc'));
         const config = await services_1.services.configManager.loadConfig(rootDir);

package/dist/core/constants.d.ts

@@ -19,6 +19,7 @@ export declare const DIR_NAMES: {
     CHANGES: string;
     ACTIVE: string;
     ARCHIVED: string;
+    KNOWLEDGE: string;
     FOR_AI: string;
     DOCS: string;
     PROJECT: string;

package/dist/core/constants.js

@@ -42,6 +42,7 @@ exports.DIR_NAMES = {
     RUNS: 'runs',
     HISTORY: 'history',
     LOGS: 'logs',
+    KNOWLEDGE: 'knowledge',
     FOR_AI: 'for-ai',
     DOCS: 'docs',
     PROJECT: 'project',

package/dist/core/types.d.ts

@@ -101,6 +101,7 @@ export interface ArchiveConfig {
 export interface SkillrcConfig {
     version: string;
     mode: ProjectMode;
+    ospecCliVersion?: string;
     projectLayout?: ProjectLayout;
     documentLanguage?: 'en-US' | 'zh-CN' | 'ja-JP' | 'ar';
     hooks: {

package/dist/services/ConfigManager.d.ts

@@ -8,6 +8,8 @@ export declare class ConfigManager {
     getMode(rootDir: string): Promise<ProjectMode>;
     isInitialized(rootDir: string): Promise<boolean>;
     createDefaultConfig(mode?: ProjectMode): Promise<SkillrcConfig>;
+    private normalizeCliVersion;
     private normalizeConfig;
+    private getPackageVersion;
 }
 export declare function createConfigManager(fileService: FileService): ConfigManager;

package/dist/services/ConfigManager.js

@@ -72,6 +72,7 @@ class ConfigManager {
         return {
             version: '4.0',
             mode,
+            ospecCliVersion: await this.getPackageVersion() || undefined,
             projectLayout: 'nested',
             hooks: {
                 'pre-commit': true,
@@ -257,6 +258,11 @@ class ConfigManager {
             ? input
             : undefined;
     }
+    normalizeCliVersion(input) {
+        return typeof input === 'string' && input.trim().length > 0
+            ? input.trim()
+            : undefined;
+    }
     normalizePluginsConfig(plugins) {
         const defaults = this.createDefaultPluginsConfig();
         const stitch = plugins?.stitch && typeof plugins.stitch === 'object' ? plugins.stitch : {};
@@ -640,6 +646,7 @@ class ConfigManager {
             ...config,
             version: config.version === '3.0' ? '4.0' : config.version,
             mode,
+            ospecCliVersion: this.normalizeCliVersion(config.ospecCliVersion),
             projectLayout: (0, ProjectLayout_1.normalizeProjectLayout)(config.projectLayout) || 'classic',
             documentLanguage: this.normalizeDocumentLanguage(config.documentLanguage),
             archive: {
@@ -659,6 +666,17 @@ class ConfigManager {
             workflow: config.workflow || ConfigurableWorkflow_1.WORKFLOW_PRESETS[mode],
         };
     }
+    async getPackageVersion() {
+        try {
+            const packageJson = await this.fileService.readJSON(path.join(path.resolve(__dirname, '../..'), 'package.json'));
+            return typeof packageJson.version === 'string' && packageJson.version.trim().length > 0
+                ? packageJson.version.trim()
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
 }
 exports.ConfigManager = ConfigManager;
 function createConfigManager(fileService) {

package/dist/services/ProjectAssetService.d.ts

@@ -4,6 +4,7 @@ import { ProjectLayout } from '../core/types';
 interface AssetManifestOptions {
     projectLayout?: ProjectLayout;
     documentLanguage?: string;
+    ospecCliVersion?: string;
     templateGeneratedPaths: string[];
     runtimeGeneratedPaths: string[];
 }
@@ -45,6 +46,7 @@ export declare class ProjectAssetService {
     private resolveStaticSourceHint;
     private normalizePaths;
     private getPackageRoot;
+    private getPackageVersion;
     private isOSpecManagedHook;
 }
 export declare const createProjectAssetService: (fileService: FileService) => ProjectAssetService;

package/dist/services/ProjectAssetService.js

@@ -170,6 +170,7 @@ class ProjectAssetService {
         const manifest = {
             version: '1.0',
             generatedAt: new Date().toISOString(),
+            ospecCliVersion: options.ospecCliVersion || (await this.getPackageVersion()) || undefined,
             projectLayout,
             documentLanguage: options.documentLanguage || 'en-US',
             assets,
@@ -226,6 +227,17 @@ class ProjectAssetService {
     getPackageRoot() {
         return path_1.default.resolve(__dirname, '../..');
     }
+    async getPackageVersion() {
+        try {
+            const packageJson = await this.fileService.readJSON(path_1.default.join(this.getPackageRoot(), 'package.json'));
+            return typeof packageJson.version === 'string' && packageJson.version.trim().length > 0
+                ? packageJson.version.trim()
+                : null;
+        }
+        catch {
+            return null;
+        }
+    }
     isOSpecManagedHook(content) {
         return (content.includes('.ospec/tools/build-index-auto.cjs') ||
             content.includes('build-index-auto.cjs') ||

package/dist/services/ProjectService.d.ts

@@ -187,6 +187,7 @@ export declare class ProjectService {
     private applyProjectScaffoldPhase;
     private getProtocolShellTemplateGeneratedPaths;
     private getFullBootstrapTemplateGeneratedPaths;
+    private getExistingOptionalKnowledgeGeneratedPaths;
     private getBootstrapAssetPlan;
     private renderProtocolShellRootSkill;
     private writeBootstrapSummary;

package/dist/services/ProjectService.js

@@ -57,8 +57,12 @@ class ProjectService {
         }
         await this.projectAssetService.writeAssetManifest(rootDir, {
             documentLanguage: normalized.documentLanguage,
+            ospecCliVersion: config.ospecCliVersion,
             projectLayout: this.getProjectLayout(config),
-            templateGeneratedPaths: this.getFullBootstrapTemplateGeneratedPaths(normalized),
+            templateGeneratedPaths: [
+                ...this.getFullBootstrapTemplateGeneratedPaths(normalized),
+                ...(await this.getExistingOptionalKnowledgeGeneratedPaths(rootDir, config)),
+            ],
             runtimeGeneratedPaths: [
                 constants_1.FILE_NAMES.SKILLRC,
                 constants_1.FILE_NAMES.SKILL_INDEX,
@@ -157,7 +161,12 @@ class ProjectService {
         ];
         await this.projectAssetService.writeAssetManifest(rootDir, {
             documentLanguage: normalized.documentLanguage,
-            templateGeneratedPaths: this.getFullBootstrapTemplateGeneratedPaths(normalized),
+            ospecCliVersion: config.ospecCliVersion,
+            projectLayout: this.getProjectLayout(config),
+            templateGeneratedPaths: [
+                ...this.getFullBootstrapTemplateGeneratedPaths(normalized),
+                ...(await this.getExistingOptionalKnowledgeGeneratedPaths(rootDir, config)),
+            ],
             runtimeGeneratedPaths: runtimeGeneratedFiles,
         });
         return {
@@ -230,7 +239,12 @@ class ProjectService {
         const assetPlan = this.getBootstrapAssetPlan(normalized.documentLanguage, normalized, { projectLayout: 'nested' });
         await this.projectAssetService.writeAssetManifest(rootDir, {
             documentLanguage: normalized.documentLanguage,
-            templateGeneratedPaths: assetPlan.templateGeneratedFiles,
+            ospecCliVersion: config.ospecCliVersion,
+            projectLayout: this.getProjectLayout(config),
+            templateGeneratedPaths: [
+                ...assetPlan.templateGeneratedFiles,
+                ...(await this.getExistingOptionalKnowledgeGeneratedPaths(rootDir, config)),
+            ],
             runtimeGeneratedPaths: assetPlan.runtimeGeneratedFiles,
         });
         return {
@@ -260,6 +274,8 @@ class ProjectService {
         }
         await this.projectAssetService.writeAssetManifest(rootDir, {
             documentLanguage: normalized.documentLanguage,
+            ospecCliVersion: config.ospecCliVersion,
+            projectLayout: this.getProjectLayout(config),
             templateGeneratedPaths: this.getProtocolShellTemplateGeneratedPaths(),
             runtimeGeneratedPaths: [
                 constants_1.FILE_NAMES.SKILLRC,
@@ -422,19 +438,30 @@ class ProjectService {
     }
     async scanModules(rootDir) {
         const config = await this.configManager.loadConfig(rootDir).catch(() => null);
-        const modulesDir = this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}`, config);
-        if (!(await this.fileService.exists(modulesDir))) {
-            return [];
+        const modules = new Map();
+        const moduleDirectoryCandidates = [
+            this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}`, config),
+            this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}`, config),
+        ];
+        for (const modulesDir of moduleDirectoryCandidates) {
+            if (!(await this.fileService.exists(modulesDir))) {
+                continue;
+            }
+            const entries = await fs_1.promises.readdir(modulesDir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory() || modules.has(entry.name)) {
+                    continue;
+                }
+                const skillPath = path_1.default.join(modulesDir, entry.name, constants_1.FILE_NAMES.SKILL_MD);
+                modules.set(entry.name, {
+                    name: entry.name,
+                    path: path_1.default.join(modulesDir, entry.name),
+                    skillPath,
+                    skillExists: (0, fs_1.existsSync)(skillPath),
+                });
+            }
         }
-        const entries = await fs_1.promises.readdir(modulesDir, { withFileTypes: true });
-        return entries
-            .filter(entry => entry.isDirectory())
-            .map(entry => ({
-            name: entry.name,
-            path: path_1.default.join(modulesDir, entry.name),
-            skillPath: path_1.default.join(modulesDir, entry.name, constants_1.FILE_NAMES.SKILL_MD),
-            skillExists: (0, fs_1.existsSync)(path_1.default.join(modulesDir, entry.name, constants_1.FILE_NAMES.SKILL_MD)),
-        }));
+        return Array.from(modules.values()).sort((left, right) => left.name.localeCompare(right.name));
     }
     async scanApiDocs(rootDir) {
         return this.scanDocsInDirectory(rootDir, constants_1.DIR_NAMES.API);
@@ -948,6 +975,31 @@ class ProjectService {
         await this.configManager.saveConfig(rootDir, config);
         return true;
     }
+    inferDocumentLanguageFromBootstrapInput(input) {
+        if (!input || this.normalizeDocumentLanguage(input.documentLanguage)) {
+            return undefined;
+        }
+        const descriptiveTexts = [
+            input.summary,
+            input.architecture,
+            ...(Array.isArray(input.apiAreas) ? input.apiAreas : []),
+            ...(Array.isArray(input.designDocs) ? input.designDocs : []),
+            ...(Array.isArray(input.planningDocs) ? input.planningDocs : []),
+            input.projectName,
+        ];
+        const descriptiveLanguage = this.detectDocumentLanguageFromTexts(descriptiveTexts);
+        if (descriptiveLanguage && descriptiveLanguage !== 'en-US') {
+            return descriptiveLanguage;
+        }
+        const localizedStructuralTexts = [
+            ...(Array.isArray(input.techStack) ? input.techStack : []),
+            ...(Array.isArray(input.modules) ? input.modules : []),
+        ].filter(item => {
+            const detected = this.detectDocumentLanguageFromText(item);
+            return detected && detected !== 'en-US';
+        });
+        return this.detectDocumentLanguageFromTexts(localizedStructuralTexts);
+    }
     detectDocumentLanguageFromTexts(contents) {
         const detectionCounts = new Map();
         const firstSeenOrder = new Map();
@@ -1080,7 +1132,7 @@ class ProjectService {
             apiAreas: normalized.apiAreas,
             designDocs: normalized.designDocs,
             planningDocs: normalized.planningDocs,
-            moduleSkillFiles: normalized.modulePlans.map(plan => plan.path),
+            moduleSkillFiles: [],
             moduleApiDocFiles: normalized.moduleApiPlans.map(plan => plan.path),
             apiDocFiles: normalized.apiAreaPlans.map(plan => plan.path),
             designDocFiles: normalized.designDocPlans.map(plan => plan.path),
@@ -1108,15 +1160,11 @@ class ProjectService {
                 `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.DESIGN}/README.md`,
                 `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PLANNING}/README.md`,
                 `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.API}/README.md`,
-                `${constants_1.DIR_NAMES.SRC}/${constants_1.FILE_NAMES.SKILL_MD}`,
-                `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}/${constants_1.FILE_NAMES.SKILL_MD}`,
-                `${constants_1.DIR_NAMES.TESTS}/${constants_1.FILE_NAMES.SKILL_MD}`,
                 `${constants_1.DIR_NAMES.FOR_AI}/${constants_1.FILE_NAMES.AI_GUIDE}`,
                 `${constants_1.DIR_NAMES.FOR_AI}/${constants_1.FILE_NAMES.EXECUTION_PROTOCOL}`,
                 '.ospec/asset-sources.json',
                 ...this.projectAssetService.getDirectCopyTargetPaths(),
                 ...(scaffoldPlan?.files || []).map(file => file.path),
-                ...normalized.modulePlans.map(plan => plan.path),
                 ...normalized.moduleApiPlans.map(plan => plan.path),
                 ...normalized.apiAreaPlans.map(plan => plan.path),
                 ...normalized.designDocPlans.map(plan => plan.path),
@@ -1140,9 +1188,6 @@ class ProjectService {
             this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.DESIGN}`, config),
             this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PLANNING}`, config),
             this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.API}`, config),
-            this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}`, config),
-            this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}`, config),
-            this.resolveManagedPath(rootDir, constants_1.DIR_NAMES.TESTS, config),
             this.resolveManagedPath(rootDir, constants_1.DIR_NAMES.FOR_AI, config),
         ];
     }
@@ -1161,9 +1206,6 @@ class ProjectService {
             this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.DESIGN}`, config),
             this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PLANNING}`, config),
             this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.API}`, config),
-            this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}`, config),
-            this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}`, config),
-            this.resolveManagedPath(rootDir, constants_1.DIR_NAMES.TESTS, config),
         ];
     }
     getMinimumRuntimeStructureDefinitions() {
@@ -1335,6 +1377,12 @@ class ProjectService {
             ...(await this.getBootstrapUpgradePlan(rootDir)),
             ...(input ?? {}),
         };
+        if (!this.normalizeDocumentLanguage(mergedInput.documentLanguage)) {
+            const inferredInputDocumentLanguage = this.inferDocumentLanguageFromBootstrapInput(input);
+            if (inferredInputDocumentLanguage) {
+                mergedInput.documentLanguage = inferredInputDocumentLanguage;
+            }
+        }
         const inferredDefaults = {
             modules: await this.inferBootstrapModules(rootDir),
         };
@@ -1352,9 +1400,6 @@ class ProjectService {
         const defaultLayout = this.getProjectLayout(config || { projectLayout: 'nested' });
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, constants_1.FILE_NAMES.SKILL_MD, defaultLayout), this.templateEngine.generateRootSkillTemplate(projectName, mode, normalized), result, { overwriteProtocolShellRootSkill: true });
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.FILE_NAMES.SKILL_MD}`, defaultLayout), this.templateEngine.generateDocsSkillTemplate(projectName, normalized), result);
-        await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.FILE_NAMES.SKILL_MD}`, defaultLayout), this.templateEngine.generateSrcSkillTemplate(projectName, normalized), result);
-        await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}/${constants_1.FILE_NAMES.SKILL_MD}`, defaultLayout), this.templateEngine.generateCoreSkillTemplate(projectName, normalized), result);
-        await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.TESTS}/${constants_1.FILE_NAMES.SKILL_MD}`, defaultLayout), this.templateEngine.generateTestsSkillTemplate(projectName, normalized), result);
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PROJECT}/overview.md`, defaultLayout), this.templateEngine.generateProjectOverviewTemplate(projectName, mode, normalized), result);
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PROJECT}/tech-stack.md`, defaultLayout), this.templateEngine.generateTechStackTemplate(projectName, normalized), result);
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PROJECT}/architecture.md`, defaultLayout), this.templateEngine.generateArchitectureTemplate(projectName, normalized), result);
@@ -1363,10 +1408,6 @@ class ProjectService {
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.DESIGN}/README.md`, defaultLayout), this.templateEngine.generateDesignDocsTemplate(projectName, normalized), result);
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PLANNING}/README.md`, defaultLayout), this.templateEngine.generatePlanningDocsTemplate(projectName, normalized), result);
         await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.API}/README.md`, defaultLayout), this.templateEngine.generateApiDocsTemplate(projectName, normalized), result);
-        for (const modulePlan of normalized.modulePlans) {
-            await this.fileService.ensureDir(this.resolveManagedPath(rootDir, `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}/${modulePlan.name}`, defaultLayout));
-            await this.writeGeneratedFile(rootDir, this.resolveManagedPath(rootDir, modulePlan.path, defaultLayout), this.templateEngine.generateModuleSkillTemplate(projectName, modulePlan.displayName, normalized, modulePlan.name), result);
-        }
         for (const moduleApiPlan of normalized.moduleApiPlans) {
             const moduleSlug = moduleApiPlan.name.replace(/^module-/, '');
             const modulePlan = normalized.modulePlans.find(plan => plan.name === moduleSlug);
@@ -1446,9 +1487,6 @@ class ProjectService {
             constants_1.FILE_NAMES.README,
             constants_1.FILE_NAMES.SKILL_MD,
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.FILE_NAMES.SKILL_MD}`,
-            `${constants_1.DIR_NAMES.SRC}/${constants_1.FILE_NAMES.SKILL_MD}`,
-            `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}/${constants_1.FILE_NAMES.SKILL_MD}`,
-            `${constants_1.DIR_NAMES.TESTS}/${constants_1.FILE_NAMES.SKILL_MD}`,
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PROJECT}/overview.md`,
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PROJECT}/tech-stack.md`,
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PROJECT}/architecture.md`,
@@ -1457,13 +1495,40 @@ class ProjectService {
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.DESIGN}/README.md`,
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.PLANNING}/README.md`,
             `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.API}/README.md`,
-            ...normalized.modulePlans.map(plan => plan.path),
             ...normalized.moduleApiPlans.map(plan => plan.path),
             ...normalized.apiAreaPlans.map(plan => plan.path),
             ...normalized.designDocPlans.map(plan => plan.path),
             ...normalized.planningDocPlans.map(plan => plan.path),
         ];
     }
+    async getExistingOptionalKnowledgeGeneratedPaths(rootDir, config = null) {
+        const paths = new Set();
+        const optionalKnowledgePaths = [
+            `${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.SRC}/${constants_1.FILE_NAMES.SKILL_MD}`,
+            `${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}/${constants_1.FILE_NAMES.SKILL_MD}`,
+            `${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.TESTS}/${constants_1.FILE_NAMES.SKILL_MD}`,
+            `${constants_1.DIR_NAMES.SRC}/${constants_1.FILE_NAMES.SKILL_MD}`,
+            `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.CORE}/${constants_1.FILE_NAMES.SKILL_MD}`,
+            `${constants_1.DIR_NAMES.TESTS}/${constants_1.FILE_NAMES.SKILL_MD}`,
+        ];
+        for (const relativePath of optionalKnowledgePaths) {
+            const absolutePath = this.resolveManagedPath(rootDir, relativePath, config);
+            if (await this.fileService.exists(absolutePath)) {
+                paths.add(relativePath);
+            }
+        }
+        const modules = await this.scanModules(rootDir);
+        for (const module of modules) {
+            const relativePath = this.toRelativePath(rootDir, module.skillPath)
+                .replace(/^\.ospec\//, '')
+                .replace(/\\/g, '/');
+            if (relativePath.startsWith(`${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}/`) ||
+                relativePath.startsWith(`${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}/`)) {
+                paths.add(relativePath);
+            }
+        }
+        return Array.from(paths).sort((left, right) => left.localeCompare(right));
+    }
     getBootstrapAssetPlan(documentLanguage, normalized, config = null) {
         const staticPlan = this.projectAssetService.getAssetPlan(documentLanguage, this.getProjectLayout(config || { projectLayout: 'nested' }));
         return {

package/dist/services/templates/ProjectTemplateBuilder.js

@@ -26,8 +26,7 @@ ${context.summary}
 
 - 根技能文档：\`SKILL.md\`
 - 文档中心：\`docs/SKILL.md\`
-- 源码地图：\`src/SKILL.md\`
-- 测试说明：\`tests/SKILL.md\`
+- 可选知识地图：\`knowledge/src/SKILL.md\`、\`knowledge/tests/SKILL.md\`
 - 语义索引：\`SKILL.index.json\`
 
 ## 执行层
@@ -49,8 +48,7 @@ ${context.summary}
 
 - Root skill: \`SKILL.md\`
 - Docs hub: \`docs/SKILL.md\`
-- Source map: \`src/SKILL.md\`
-- Test guide: \`tests/SKILL.md\`
+- Optional knowledge maps: \`knowledge/src/SKILL.md\`, \`knowledge/tests/SKILL.md\`
 - Index: \`SKILL.index.json\`
 
 ## Execution
@@ -72,8 +70,7 @@ ${context.summary}
 
 - ルート SKILL: \`SKILL.md\`
 - docs ハブ: \`docs/SKILL.md\`
-- ソースマップ: \`src/SKILL.md\`
-- テストガイド: \`tests/SKILL.md\`
+- 任意の知識マップ: \`knowledge/src/SKILL.md\`、\`knowledge/tests/SKILL.md\`
 - インデックス: \`SKILL.index.json\`
 
 ## 実行レイヤー
@@ -95,8 +92,7 @@ ${context.summary}
 
 - ملف SKILL الجذري: \`SKILL.md\`
 - مركز docs: \`docs/SKILL.md\`
-- خريطة المصدر: \`src/SKILL.md\`
-- دليل الاختبارات: \`tests/SKILL.md\`
+- خرائط معرفة اختيارية: \`knowledge/src/SKILL.md\` و \`knowledge/tests/SKILL.md\`
 - الفهرس: \`SKILL.index.json\`
 
 ## طبقة التنفيذ
@@ -128,9 +124,8 @@ ${context.architecture}
 ## 目录导航
 
 - 文档中心：[docs/SKILL.md](docs/SKILL.md)
-- 源码地图：[src/SKILL.md](src/SKILL.md)
-- 测试入口：[tests/SKILL.md](tests/SKILL.md)
 - AI 指南：[for-ai/ai-guide.md](for-ai/ai-guide.md)
+- 可选知识地图：\`knowledge/src/SKILL.md\`、\`knowledge/tests/SKILL.md\`
 
 ## 插件阻断
 
@@ -158,9 +153,8 @@ ${context.architecture}
 ## Navigation
 
 - Docs hub: [docs/SKILL.md](docs/SKILL.md)
-- Source map: [src/SKILL.md](src/SKILL.md)
-- Test guide: [tests/SKILL.md](tests/SKILL.md)
 - AI guide: [for-ai/ai-guide.md](for-ai/ai-guide.md)
+- Optional knowledge maps: \`knowledge/src/SKILL.md\`, \`knowledge/tests/SKILL.md\`
 
 ## Plugin Gates
 
@@ -188,9 +182,8 @@ ${context.architecture}
 ## ナビゲーション
 
 - docs ハブ: [docs/SKILL.md](docs/SKILL.md)
-- ソースマップ: [src/SKILL.md](src/SKILL.md)
-- テストガイド: [tests/SKILL.md](tests/SKILL.md)
 - AI ガイド: [for-ai/ai-guide.md](for-ai/ai-guide.md)
+- 任意の知識マップ: \`knowledge/src/SKILL.md\`、\`knowledge/tests/SKILL.md\`
 
 ## プラグインゲート
 
@@ -218,9 +211,8 @@ ${context.architecture}
 ## التنقل
 
 - مركز docs: [docs/SKILL.md](docs/SKILL.md)
-- خريطة المصدر: [src/SKILL.md](src/SKILL.md)
-- دليل الاختبارات: [tests/SKILL.md](tests/SKILL.md)
 - دليل الذكاء الاصطناعي: [for-ai/ai-guide.md](for-ai/ai-guide.md)
+- خرائط معرفة اختيارية: \`knowledge/src/SKILL.md\` و \`knowledge/tests/SKILL.md\`
 
 ## بوابات الإضافات
 
@@ -298,7 +290,9 @@ ${context.architecture}
         const context = this.getProjectContext(fallbackName, 'standard', input);
         const moduleLinks = this.formatLinkedList(context.modulePlans.map(plan => ({
             displayName: plan.displayName,
-            path: plan.path.replace(`${constants_1.DIR_NAMES.SRC}/`, ''),
+            path: plan.path
+                .replace(`${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.SRC}/`, '')
+                .replace(`${constants_1.DIR_NAMES.SRC}/`, ''),
         })), this.copy(context.documentLanguage, '待补充', 'TBD', '未定', 'قيد التحديد'));
         const body = this.copy(context.documentLanguage, `# 源码地图
 
@@ -307,7 +301,7 @@ ${context.architecture}
 ## 目录导航
 
 - 核心层：[core/SKILL.md](core/SKILL.md)
-- 模块层：\`src/modules/<module>/SKILL.md\`
+- 模块层：\`knowledge/src/modules/<module>/SKILL.md\`
 
 ## 模块说明
 
@@ -318,7 +312,7 @@ ${moduleLinks}`, `# Source Map
 ## Navigation
 
 - Core layer: [core/SKILL.md](core/SKILL.md)
-- Module layer: \`src/modules/<module>/SKILL.md\`
+- Module layer: \`knowledge/src/modules/<module>/SKILL.md\`
 
 ## Modules
 
@@ -329,7 +323,7 @@ ${moduleLinks}`, `# ソースマップ
 ## ナビゲーション
 
 - コア層: [core/SKILL.md](core/SKILL.md)
-- モジュール層: \`src/modules/<module>/SKILL.md\`
+- モジュール層: \`knowledge/src/modules/<module>/SKILL.md\`
 
 ## モジュール
 
@@ -340,7 +334,7 @@ ${moduleLinks}`, `# خريطة المصدر
 ## التنقل
 
 - الطبقة الأساسية: [core/SKILL.md](core/SKILL.md)
-- طبقة الوحدات: \`src/modules/<module>/SKILL.md\`
+- طبقة الوحدات: \`knowledge/src/modules/<module>/SKILL.md\`
 
 ## الوحدات
 
@@ -356,7 +350,7 @@ ${moduleLinks}`);
         const body = this.copy(context.documentLanguage, `# Core 核心层
 
 > 层级：第 3 层（核心模块）
-> 上层：[src/SKILL.md](../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../SKILL.md)
 
 ## 模块概述
 
@@ -366,10 +360,10 @@ ${moduleLinks}`);
 
 ## API 文档
 
-- 项目 API 总览：[../../docs/project/api-overview.md](../../docs/project/api-overview.md)`, `# Core Layer
+- 项目 API 总览：[../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`, `# Core Layer
 
 > Layer: core module
-> Parent: [src/SKILL.md](../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../SKILL.md)
 
 ## Module Overview
 
@@ -379,10 +373,10 @@ ${moduleLinks}`);
 
 ## API Docs
 
-- Project API overview: [../../docs/project/api-overview.md](../../docs/project/api-overview.md)`, `# コア層
+- Project API overview: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`, `# コア層
 
 > レイヤー: コアモジュール
-> 親: [src/SKILL.md](../SKILL.md)
+> 親: [knowledge/src/SKILL.md](../SKILL.md)
 
 ## モジュール概要
 
@@ -392,10 +386,10 @@ ${moduleLinks}`);
 
 ## API 文書
 
-- プロジェクト API 概要: [../../docs/project/api-overview.md](../../docs/project/api-overview.md)`, `# الطبقة الأساسية
+- プロジェクト API 概要: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`, `# الطبقة الأساسية
 
 > الطبقة: الوحدة الأساسية
-> الأصل: [src/SKILL.md](../SKILL.md)
+> الأصل: [knowledge/src/SKILL.md](../SKILL.md)
 
 ## نظرة عامة على الوحدة
 
@@ -405,7 +399,7 @@ ${moduleLinks}`);
 
 ## وثائق API
 
-- نظرة عامة على API للمشروع: [../../docs/project/api-overview.md](../../docs/project/api-overview.md)`);
+- نظرة عامة على API للمشروع: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`);
         return this.withFrontmatter({
             name: 'core',
             title: this.copy(context.documentLanguage, `${context.projectName} 核心层`, `${context.projectName} Core Layer`, `${context.projectName} コア層`, `${context.projectName} الطبقة الأساسية`),
@@ -878,7 +872,7 @@ ${apiDocs}`);
         const body = presetBody ?? this.copy(context.documentLanguage, `# ${moduleName} 模块
 
 > 层级：第 3 层（业务模块文档）
-> 上层：[src/SKILL.md](../../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../../SKILL.md)
 
 ## 模块概述
 
@@ -910,12 +904,12 @@ ${this.formatReferenceList(refs, '待补充')}
 
 ## 关联文档
 
-- 项目模块地图：[../../../docs/project/module-map.md](../../../docs/project/module-map.md)
-- API 总览：[../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)
+- 项目模块地图：[../../../../docs/project/module-map.md](../../../../docs/project/module-map.md)
+- API 总览：[../../../../docs/project/api-overview.md](../../../../docs/project/api-overview.md)
 - 模块源码入口：当前目录`, `# ${moduleName}
 
 > Layer: module document
-> Parent: [src/SKILL.md](../../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## Module Overview
 
@@ -947,11 +941,11 @@ ${this.formatReferenceList(refs, 'TBD')}
 
 ## Related Docs
 
-- Module map: [../../../docs/project/module-map.md](../../../docs/project/module-map.md)
-- API overview: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`, `# ${moduleName} モジュール
+- Module map: [../../../../docs/project/module-map.md](../../../../docs/project/module-map.md)
+- API overview: [../../../../docs/project/api-overview.md](../../../../docs/project/api-overview.md)`, `# ${moduleName} モジュール
 
 > レイヤー: モジュール文書
-> 親: [src/SKILL.md](../../SKILL.md)
+> 親: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## モジュール概要
 
@@ -983,11 +977,11 @@ ${this.formatReferenceList(refs, '未定')}
 
 ## 関連文書
 
-- モジュールマップ: [../../../docs/project/module-map.md](../../../docs/project/module-map.md)
-- API 概要: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`, `# وحدة ${moduleName}
+- モジュールマップ: [../../../../docs/project/module-map.md](../../../../docs/project/module-map.md)
+- API 概要: [../../../../docs/project/api-overview.md](../../../../docs/project/api-overview.md)`, `# وحدة ${moduleName}
 
 > الطبقة: وثيقة الوحدة
-> الأصل: [src/SKILL.md](../../SKILL.md)
+> الأصل: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## نظرة عامة على الوحدة
 
@@ -1019,8 +1013,8 @@ ${this.formatReferenceList(refs, 'قيد التحديد')}
 
 ## وثائق ذات صلة
 
-- خريطة الوحدات: [../../../docs/project/module-map.md](../../../docs/project/module-map.md)
-- نظرة عامة على API: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`);
+- خريطة الوحدات: [../../../../docs/project/module-map.md](../../../../docs/project/module-map.md)
+- نظرة عامة على API: [../../../../docs/project/api-overview.md](../../../../docs/project/api-overview.md)`);
         return this.withFrontmatter({
             name: slug,
             title: this.copy(context.documentLanguage, `${context.projectName} ${moduleName} 模块`, `${context.projectName} ${moduleName} Module`, `${context.projectName} ${moduleName} モジュール`, `${context.projectName} وحدة ${moduleName}`),
@@ -1601,16 +1595,16 @@ scan(rootDir)
         const moduleKey = slug.toLowerCase();
         const docsLink = this.formatReferenceList(refs, this.copy(context.documentLanguage, '待补充', 'TBD'));
         const relatedDocs = this.isEnglish(context.documentLanguage)
-            ? `- Module map: [../../../docs/project/module-map.md](../../../docs/project/module-map.md)
-- API overview: [../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`
-            : `- 项目模块地图：[../../../docs/project/module-map.md](../../../docs/project/module-map.md)
-- API 总览：[../../../docs/project/api-overview.md](../../../docs/project/api-overview.md)`;
+            ? `- Module map: [../../../../docs/project/module-map.md](../../../../docs/project/module-map.md)
+- API overview: [../../../../docs/project/api-overview.md](../../../../docs/project/api-overview.md)`
+            : `- 项目模块地图：[../../../../docs/project/module-map.md](../../../../docs/project/module-map.md)
+- API 总览：[../../../../docs/project/api-overview.md](../../../../docs/project/api-overview.md)`;
         const templates = {
             web: {
                 zh: `# ${moduleName} 模块
 
 > 层级：第 3 层（业务模块文档）
-> 上层：[src/SKILL.md](../../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../../SKILL.md)
 
 ## 模块定位
 
@@ -1646,7 +1640,7 @@ ${relatedDocs}`,
                 en: `# ${moduleName}
 
 > Layer: module document
-> Parent: [src/SKILL.md](../../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## Module Positioning
 
@@ -1684,7 +1678,7 @@ ${relatedDocs}`,
                 zh: `# ${moduleName} 模块
 
 > 层级：第 3 层（业务模块文档）
-> 上层：[src/SKILL.md](../../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../../SKILL.md)
 
 ## 模块定位
 
@@ -1720,7 +1714,7 @@ ${relatedDocs}`,
                 en: `# ${moduleName}
 
 > Layer: module document
-> Parent: [src/SKILL.md](../../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## Module Positioning
 
@@ -1758,7 +1752,7 @@ ${relatedDocs}`,
                 zh: `# ${moduleName} 模块
 
 > 层级：第 3 层（业务模块文档）
-> 上层：[src/SKILL.md](../../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../../SKILL.md)
 
 ## 模块定位
 
@@ -1794,7 +1788,7 @@ ${relatedDocs}`,
                 en: `# ${moduleName}
 
 > Layer: module document
-> Parent: [src/SKILL.md](../../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## Module Positioning
 
@@ -1832,7 +1826,7 @@ ${relatedDocs}`,
                 zh: `# ${moduleName} 模块
 
 > 层级：第 3 层（业务模块文档）
-> 上层：[src/SKILL.md](../../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../../SKILL.md)
 
 ## 模块定位
 
@@ -1868,7 +1862,7 @@ ${relatedDocs}`,
                 en: `# ${moduleName}
 
 > Layer: module document
-> Parent: [src/SKILL.md](../../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## Module Positioning
 
@@ -1906,7 +1900,7 @@ ${relatedDocs}`,
                 zh: `# ${moduleName} 模块
 
 > 层级：第 3 层（业务模块文档）
-> 上层：[src/SKILL.md](../../SKILL.md)
+> 上层：[knowledge/src/SKILL.md](../../SKILL.md)
 
 ## 模块定位
 
@@ -1942,7 +1936,7 @@ ${relatedDocs}`,
                 en: `# ${moduleName}
 
 > Layer: module document
-> Parent: [src/SKILL.md](../../SKILL.md)
+> Parent: [knowledge/src/SKILL.md](../../SKILL.md)
 
 ## Module Positioning
 

package/dist/services/templates/TemplateInputFactory.js

@@ -179,7 +179,7 @@ class TemplateInputFactory {
         const inferredFields = this.pickFieldKeys(fieldSources, 'inferred');
         const placeholderFields = this.pickFieldKeys(fieldSources, 'placeholder');
         const usedFallbacks = [...inferredFields, ...placeholderFields];
-        const modulePlans = this.buildPlannedFiles(modules, 'module', value => this.normalizeModuleDisplayName(value), slug => `${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}/${slug}/${constants_1.FILE_NAMES.SKILL_MD}`, displayName => displayName.toLowerCase() === 'core');
+        const modulePlans = this.buildPlannedFiles(modules, 'module', value => this.normalizeModuleDisplayName(value), slug => `${constants_1.DIR_NAMES.KNOWLEDGE}/${constants_1.DIR_NAMES.SRC}/${constants_1.DIR_NAMES.MODULES}/${slug}/${constants_1.FILE_NAMES.SKILL_MD}`, displayName => displayName.toLowerCase() === 'core');
         const moduleApiPlans = this.buildModuleApiPlans(modulePlans);
         const apiAreaPlans = this.buildPlannedFiles(apiAreas, 'api', value => this.normalizeDocDisplayName(value, constants_1.DIR_NAMES.API), slug => `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.API}/${slug}.md`);
         const designDocPlans = this.buildPlannedFiles(designDocs, 'design', value => this.normalizeDocDisplayName(value, constants_1.DIR_NAMES.DESIGN), slug => `${constants_1.DIR_NAMES.DOCS}/${constants_1.DIR_NAMES.DESIGN}/${slug}.md`);
@@ -314,6 +314,7 @@ class TemplateInputFactory {
     }
     normalizeModuleDisplayName(value) {
         return value
+            .replace(/^knowledge[\\/]+src[\\/]+modules[\\/]+/i, '')
             .replace(/^src[\\/]+modules[\\/]+/i, '')
             .replace(/^modules[\\/]+/i, '')
             .replace(/[\\/]+/g, ' ')

package/dist/utils/ProjectLayout.js

@@ -91,6 +91,7 @@ function resolveManagedInputPath(rootDir, candidatePath, input) {
     const normalizedCandidatePath = String(candidatePath || '').replace(/\\/g, '/').replace(/^\.\/+/, '');
     if (normalizedCandidatePath.startsWith('changes/') ||
         normalizedCandidatePath.startsWith('for-ai/') ||
+        normalizedCandidatePath.startsWith('knowledge/') ||
         normalizedCandidatePath.startsWith('docs/') ||
         normalizedCandidatePath.startsWith('src/') ||
         normalizedCandidatePath.startsWith('tests/') ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawplays/ospec-cli",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Official OSpec CLI package for spec-driven development (SDD) and document-driven development in AI coding agent and CLI workflows.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skill.yaml

@@ -7,7 +7,7 @@ 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."
+  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, map an explicit language request or the current conversation language to --document-language during AI-assisted init instead of assuming a brand-new repo will infer it, 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"