@kafka0102/onespec 0.1.2 → 0.1.14

package/assets/skills-en/onespec/references/fast.md

@@ -0,0 +1,110 @@
+# Fast Path
+
+Read on demand from `onespec` and the standalone `onespec-fast` entrypoint for the `fast` path. The goal is to skip the normal proposal approval gate, complexity check, implementation-path selection, and post-implementation archive choice. Once in the fast path, use native `OpenSpec apply` for the whole implementation and archive directly.
+
+## 1. Intake
+
+Recover state first:
+
+```bash
+ONESPEC_ENV="${ONESPEC_ENV:-$(find . "$HOME"/.codex "$HOME"/.claude "$HOME"/.cursor "$HOME"/.gemini "$HOME"/.copilot "$HOME"/.agents "$HOME"/.config -path '*/onespec/scripts/onespec-env.sh' -type f -print -quit 2>/dev/null)}"
+. "$ONESPEC_ENV"
+"$ONESPEC_BASH" "$ONESPEC_STATE" list
+```
+
+If a relevant change exists, run:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" recover <change-id>
+```
+
+Treat `recover` output as the execution contract. Read at least `phase`, `next_skill`, `next_reference`, `next_gate`, and `allowed_actions`.
+
+Use rules:
+
+- Use only when the user explicitly asks for `onespec-fast`, the fast path, fast apply, automatic OpenSpec proposal/implementation/archive, or automatic end-to-end execution.
+- Do not ask the user to name the change. Generate a short kebab-case `change-id`; append a numeric suffix if needed.
+- Read the minimum needed context: `openspec/config.yaml`, `openspec/project.md`, relevant `openspec/specs/**`, project entry docs, current branch, and workspace state.
+- Pause only when required OpenSpec context is too incomplete to produce a valid proposal, or project docs explicitly forbid automatic edits on the current branch.
+
+## 2. Direct Proposal
+
+The fast path skips the normal design phase pre-proposal user confirmation.
+
+Create the OpenSpec proposal artifacts directly:
+
+- `openspec/changes/<change-id>/proposal.md`
+- `openspec/changes/<change-id>/design.md`, only when it has real technical value
+- `openspec/changes/<change-id>/tasks.md`
+- required `specs/**/spec.md`
+
+Create state and handoff:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" init <change-id>
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase proposal-ready
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> ambiguity low
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> proposal --write
+```
+
+Do not show the normal proposal approval menu. `onespec-fast` means the user has authorized continuing with native `OpenSpec apply` implementation and archive.
+
+## 3. OpenSpec Automatic Apply and Archive
+
+After proposal creation, do not run a complexity check and do not switch to a Superpowers plan/subagent. Record the fast path directly and start implementation:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> implementation_path openspec-apply
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> execution_method native
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> workspace current-branch
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_branch "$(git branch --show-current || echo detached)"
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_path "$(pwd -P)"
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> origin_workspace_mode current-branch
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase approved
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase implementing
+```
+
+Implementation rules:
+
+- Use native `OpenSpec apply`; do not create a Superpowers plan and do not dispatch subagents.
+- Implement only incomplete tasks in `tasks.md`; do not expand proposal scope.
+- Work in the current workspace; do not auto-create a worktree, auto-push, or auto-merge.
+- If the current branch is `main`/`master`, record `origin_workspace_mode` as `main-override`, but pause only if project docs explicitly forbid direct edits on the main branch.
+- Track directly modified repo-relative paths in `.onespec.yaml`; prefer:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" track <change-id> <path>...
+```
+
+After implementation:
+
+- Check off completed tasks in `tasks.md`.
+- If implementation exposes a new design conflict, stop automatic implementation, fix OpenSpec artifacts, and stay on the OpenSpec proposal/apply path; switch to Superpowers only if the user explicitly asks.
+- Run project tests.
+- Run `openspec validate <change-id> --strict`.
+- Write the review handoff, but do not pause for user review:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_STATE" set <change-id> phase review
+"$ONESPEC_BASH" "$ONESPEC_HANDOFF" <change-id> review --write
+```
+
+Then archive directly without showing the archive phase closeout menu:
+
+```bash
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" related-dirty <change-id>
+"$ONESPEC_BASH" "$ONESPEC_COMMIT" commit-related <change-id> closeout
+"$ONESPEC_BASH" "$ONESPEC_CLOSEOUT" run-actions <change-id> archive-only
+```
+
+If `related-dirty` is empty, do not run `commit-related <change-id> closeout`. `run-actions` sets `phase archived` / `archive archived` and handles the post-archive commit plus runtime cleanup.
+
+## 4. Stop Conditions
+
+Pause if:
+
+- required OpenSpec context is missing and a valid proposal cannot be written
+- the request clearly spans multiple changes that should be split
+- tests or `openspec validate <change-id> --strict` fail and cannot be fixed inside the approved scope
+- implementation reveals scope expansion, design change, or spec semantic change
+- project docs explicitly forbid automatic implementation or automatic archive on the current branch

package/assets/skills-en/onespec-fast/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: onespec-fast
+description: Use when the user explicitly asks for the OneSpec fast path, onespec-fast, fast apply, automatic OpenSpec proposal/implementation/archive, or automatic end-to-end execution. This skill reuses `onespec/references/fast.md` and uses native OpenSpec apply throughout, with no complexity check and no Superpowers plan.
+---
+
+# OneSpec Fast
+
+This is the standalone entrypoint for the OneSpec fast path. It does not duplicate phase rules; it must reuse the main `onespec` skill's `references/fast.md`.
+
+Announce at the start:
+
+> I am using the `onespec-fast` fast path.
+
+## Entry Rules
+
+- Use only when the user explicitly asks for `onespec-fast`, the fast path, fast apply, automatic OpenSpec proposal/implementation/archive, or automatic end-to-end execution.
+- First read the sibling `../onespec/SKILL.md` and follow its recovery-first, shared-constraint, and reference-loading rules.
+- Then read `../onespec/references/fast.md` and execute those steps.
+- If the sibling path is unavailable, locate `*/onespec/references/fast.md` under the current project, `$HOME/.codex`, `$HOME/.claude`, `$HOME/.cursor`, `$HOME/.gemini`, `$HOME/.copilot`, `$HOME/.agents`, or `$HOME/.config`. If still missing, stop and ask the user to rerun `onespec init --overwrite`.
+- `references/fast.md` may reuse procedure sections from `design.md`, `execute.md`, and `archive.md`, but it overrides the normal proposal approval, review pause, and closeout-menu gates.
+
+Do not restate the fast-path steps in `onespec-fast/SKILL.md`; the full rules live only in `onespec/references/fast.md`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kafka0102/onespec",
-  "version": "0.1.2",
-  "description": "OpenSpec + Superpowers workflow skill installer for Codex",
+  "version": "0.1.14",
+  "description": "OpenSpec + Superpowers workflow skill installer for mainstream SKILL.md agents",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kafka0102/onespec.git"
@@ -11,6 +11,10 @@
     "superpowers",
     "skills",
     "codex",
+    "claude-code",
+    "cursor",
+    "gemini-cli",
+    "github-copilot",
     "workflow"
   ],
   "type": "module",

package/scripts/postinstall.js

@@ -16,9 +16,9 @@ function main() {
   }
 
   console.log('\nOneSpec installed. Next run:');
-  console.log('  onespec init --scope global --yes');
-  console.log('or for the current project:');
-  console.log('  onespec init . --scope project --yes\n');
+  console.log('  onespec init');
+  console.log('or non-interactive:');
+  console.log('  onespec init . --platform codex --scope project --yes\n');
 }
 
 try {

package/src/cli.js

@@ -1,20 +1,25 @@
-import { execFileSync } from 'node:child_process';
 import path from 'node:path';
 import readline from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
+import { readFile } from 'node:fs/promises';
 
 import { doctorProject } from './doctor.js';
-import { initProject, SUPPORTED_LANGUAGES } from './init.js';
-
-const OPEN_SPEC_CLI_PACKAGE = '@fission-ai/openspec@latest';
-const SUPERPOWERS_PACKAGE = 'obra/superpowers';
+import { SUPPORTED_LANGUAGES } from './init.js';
+import { getPlatform } from './platforms.js';
+import {
+  detectExistingOneSpecPlatforms,
+  detectPlatforms,
+  initWorkspace,
+  parsePlatformList,
+  SUPPORTED_PLATFORM_IDS,
+} from './setup.js';
 
 function parseArgs(argv) {
   const args = [...argv];
   const command = args.shift() ?? 'help';
   const options = {
     targetPath: process.cwd(),
-    platform: 'codex',
+    platforms: [],
     scope: undefined,
     language: undefined,
     yes: false,
@@ -43,7 +48,7 @@ function parseArgs(argv) {
         options.language = args.shift();
         break;
       case '--platform':
-        options.platform = args.shift() ?? 'codex';
+        options.platforms.push(args.shift() ?? '');
         break;
       default:
         if (arg?.startsWith('-')) {
@@ -57,34 +62,43 @@ function parseArgs(argv) {
   return { command, options };
 }
 
-function commandExists(command) {
-  try {
-    const checker = process.platform === 'win32' ? 'where' : 'which';
-    execFileSync(checker, [command], { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
+function normalizeYesNo(value) {
+  return ['y', 'yes', '是', '覆盖'].includes(value.trim().toLowerCase());
 }
 
 async function askInitOptions(options) {
+  const explicitPlatforms = parsePlatformList(options.platforms);
+  const detectedPlatforms = await detectPlatforms(options.targetPath);
+  const defaultPlatforms = explicitPlatforms.length > 0 ? explicitPlatforms : detectedPlatforms.length > 0 ? detectedPlatforms : ['codex'];
+
   if (options.yes) {
     return {
       ...options,
       scope: options.scope ?? 'project',
       language: options.language ?? 'zh',
-      installOpenSpecCli: false,
-      initOpenSpecProject: false,
-      installSuperpowers: false,
+      platforms: defaultPlatforms,
     };
   }
 
-  const preflight = await doctorProject(options.targetPath, {
-    platform: options.platform,
-    scope: options.scope ?? 'project',
-  });
   const rl = readline.createInterface({ input, output });
   try {
+    if (explicitPlatforms.length === 0) {
+      console.log('可选 AI 平台：');
+      for (const [index, platformId] of SUPPORTED_PLATFORM_IDS.entries()) {
+        const platform = getPlatform(platformId);
+        const detectedSuffix = detectedPlatforms.includes(platformId) ? ' [detected]' : '';
+        console.log(`  ${index + 1}. ${platform.name} (${platform.id})${detectedSuffix}`);
+      }
+      console.log('');
+    }
+
+    const platformAnswer =
+      explicitPlatforms.length > 0
+        ? explicitPlatforms.join(',')
+        : await rl.question(
+            `安装到哪些 AI 平台？输入编号或 id，逗号分隔（默认 ${defaultPlatforms.join(',')}）：`,
+          );
+    const selectedPlatforms = resolvePlatformSelection(platformAnswer, defaultPlatforms);
     const scopeAnswer =
       options.scope ??
       (await rl.question('安装范围？输入 project 或 global（默认 project）：'));
@@ -92,100 +106,103 @@ async function askInitOptions(options) {
     const languageAnswer =
       options.language ??
       (await rl.question('Skill 语言？输入 zh 或 en（默认 zh）：'));
-    const overwriteAnswer = options.overwrite
-      ? 'yes'
-      : await rl.question('如果 OneSpec skill 已存在，是否覆盖？输入 yes 或 no（默认 no）：');
-    const installOpenSpecCliAnswer =
-      preflight.openspecCli.available
+    const existingPlatforms = await detectExistingOneSpecPlatforms(
+      options.targetPath,
+      resolvedScope,
+      selectedPlatforms,
+    );
+    const overwriteAnswer =
+      options.overwrite || existingPlatforms.length === 0
         ? 'no'
         : await rl.question(
-            `未检测到 OpenSpec CLI。是否现在执行 npm install -g ${OPEN_SPEC_CLI_PACKAGE} ？输入 yes 或 no（默认 no）：`,
+            `检测到这些平台已存在 OneSpec skill：${existingPlatforms.join(', ')}。是否覆盖已存在项？输入 yes 或 no（默认 no）：`,
           );
-    const initOpenSpecProjectAnswer =
-      resolvedScope === 'project' && !preflight.hasOpenSpecProject
-        ? await rl.question(
-            '当前项目未初始化 OpenSpec。是否在安装 OneSpec 后执行 openspec init？输入 yes 或 no（默认 no）：',
-          )
-        : 'no';
-    const installSuperpowersAnswer = preflight.superpowers.available
-      ? 'no'
-      : await rl.question(
-          `未检测到 Superpowers。是否现在执行 npx skills add ${SUPERPOWERS_PACKAGE} -a codex${resolvedScope === 'global' ? ' -g' : ''} -y ？输入 yes 或 no（默认 no）：`,
-        );
 
     return {
       ...options,
+      platforms: selectedPlatforms,
       scope: resolvedScope,
       language: languageAnswer.trim() || 'zh',
-      overwrite: options.overwrite || ['y', 'yes', '是', '覆盖'].includes(overwriteAnswer.trim()),
-      installOpenSpecCli: ['y', 'yes', '是'].includes(installOpenSpecCliAnswer.trim()),
-      initOpenSpecProject: ['y', 'yes', '是'].includes(initOpenSpecProjectAnswer.trim()),
-      installSuperpowers: ['y', 'yes', '是'].includes(installSuperpowersAnswer.trim()),
+      overwrite: options.overwrite || normalizeYesNo(overwriteAnswer),
     };
   } finally {
     rl.close();
   }
 }
 
-function runCommand(command, args, cwd = process.cwd()) {
-  execFileSync(command, args, {
-    cwd,
-    stdio: 'inherit',
-    shell: process.platform === 'win32',
-  });
-}
-
-function getNpxExecutable() {
-  return process.platform === 'win32' ? 'npx.cmd' : 'npx';
-}
-
-async function ensureRequestedDependencies(targetPath, options, preflight) {
-  if (options.installOpenSpecCli && !preflight.openspecCli.available) {
-    runCommand('npm', ['install', '-g', OPEN_SPEC_CLI_PACKAGE]);
+function resolvePlatformSelection(answer, defaultPlatforms) {
+  const trimmed = answer.trim();
+  if (!trimmed) {
+    return defaultPlatforms;
   }
 
-  if (options.installSuperpowers && !preflight.superpowers.available) {
-    const args = ['skills', 'add', SUPERPOWERS_PACKAGE, '-a', 'codex', '-y'];
-    if (options.scope === 'global') {
-      args.push('-g');
-    }
-    runCommand(getNpxExecutable(), args, targetPath);
-  }
+  const numbered = trimmed
+    .split(',')
+    .map((value) => value.trim())
+    .filter(Boolean)
+    .map((value) => {
+      if (!/^\d+$/.test(value)) {
+        return value;
+      }
 
-  if (options.initOpenSpecProject && !preflight.hasOpenSpecProject) {
-    runCommand('openspec', ['init', targetPath], targetPath);
-  }
+      const index = Number.parseInt(value, 10) - 1;
+      if (index < 0 || index >= SUPPORTED_PLATFORM_IDS.length) {
+        throw new Error(`Unsupported platform selection: ${value}`);
+      }
+      return SUPPORTED_PLATFORM_IDS[index];
+    });
+
+  return parsePlatformList(numbered);
 }
 
 function printHelp() {
   console.log(`OneSpec Skill Installer
 
 用法：
-  onespec init [path] [--yes] [--overwrite] [--scope project|global] [--language zh|en]
-  onespec doctor [path] [--scope project|global]
+  onespec init [path] [--yes] [--overwrite] [--scope project|global] [--language zh|en] [--platform ${SUPPORTED_PLATFORM_IDS.join('|')}[,...]]
+  onespec doctor [path] [--scope project|global] [--platform ${SUPPORTED_PLATFORM_IDS.join('|')}]
 
 说明：
-  当前提供中英文 Skill bundle，暂仅支持 Codex 平台。
+  当前提供中英文 Skill bundle，官方支持 ${SUPPORTED_PLATFORM_IDS.join(' / ')}。
+  init 会引导选择 agent，并自动安装 OpenSpec / Superpowers / OneSpec。
 `);
 }
 
+let cachedVersion;
+
+async function getPackageVersion() {
+  if (cachedVersion) {
+    return cachedVersion;
+  }
+
+  const packageJsonPath = new URL('../package.json', import.meta.url);
+  const packageJson = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+  cachedVersion = packageJson.version;
+  return cachedVersion;
+}
+
 function printSummary(result) {
   console.log('\nOneSpec 初始化完成\n');
-  console.log(`安装位置：${result.skillPath}`);
+  console.log(`目标平台：${result.platformNames.join(', ')}`);
   console.log(`安装范围：${result.scope}`);
   console.log(`Skill 语言：${result.languageName} (${result.language})`);
-  console.log(`Skill 状态：${result.installedSkill ? '已安装/已覆盖' : '已存在，已跳过'}`);
-  console.log(`已安装 Skills：${result.installedSkills.join(', ') || '无'}`);
-  console.log(`已跳过 Skills：${result.skippedSkills.join(', ') || '无'}`);
-  console.log(`工作目录：${path.join(result.projectPath, 'docs', 'superpowers')}`);
-  console.log('\n环境检查：');
-  console.log(`OpenSpec CLI：${commandExists('openspec') ? '已找到' : '未找到，请先安装或运行 openspec init'}`);
-  console.log('Superpowers：请确认 Codex 可发现 brainstorming / writing-plans / using-git-worktrees 等 skills');
-  console.log('\n开始使用：在 Codex 中输入 “使用 onespec：<你的任务描述>”。\n');
+  console.log(`OpenSpec CLI：${result.openspecCli.status === 'installed' ? '已自动安装' : '已存在'}`);
+  console.log(`OpenSpec Tools：${result.openspec.toolIds.join(', ')}`);
+  console.log(`Superpowers Agents：${result.superpowers.agents.join(', ')}`);
+  for (const platformResult of result.results) {
+    const platformLabel = `${platformResult.platformName} (${platformResult.platform})`;
+    const skillStatus = platformResult.installedSkill ? '已安装/已覆盖' : '已存在，已跳过';
+    console.log(`- ${platformLabel}：${skillStatus} -> ${platformResult.skillPath}`);
+  }
+  if (result.scope === 'project') {
+    console.log(`工作目录：${path.join(result.projectPath, 'docs', 'superpowers')}`);
+  }
+  console.log('\n开始使用：重启对应 agent 会话后，直接输入 “使用 onespec：<你的任务描述>”。\n');
 }
 
 function printDoctor(report) {
   console.log('\nOneSpec 环境检查\n');
+  console.log(`目标平台：${report.platformName} (${report.platform})`);
   console.log(`OneSpec Skill：${report.onespec.installed ? '已安装' : '未安装'}`);
   console.log(`OneSpec 子 Skills：${report.onespec.installedSkills.join(', ') || '无'}`);
   console.log(`缺少 OneSpec 子 Skills：${report.onespec.missingSkills.join(', ') || '无'}`);
@@ -205,6 +222,10 @@ function printDoctor(report) {
 export async function main(argv = process.argv.slice(2)) {
   const { command, options } = parseArgs(argv);
 
+  if (command === 'version' || command === '--version' || command === '-v') {
+    console.log(await getPackageVersion());
+    return;
+  }
   if (command === 'help' || command === '--help' || command === '-h') {
     printHelp();
     return;
@@ -214,8 +235,9 @@ export async function main(argv = process.argv.slice(2)) {
   }
 
   if (command === 'doctor') {
+    const doctorPlatforms = parsePlatformList(options.platforms);
     const report = await doctorProject(options.targetPath, {
-      platform: options.platform,
+      platform: doctorPlatforms[0],
       scope: options.scope ?? 'project',
     });
     if (options.json) {
@@ -230,12 +252,7 @@ export async function main(argv = process.argv.slice(2)) {
   if (!SUPPORTED_LANGUAGES[initOptions.language]) {
     throw new Error(`Unsupported language: ${initOptions.language}`);
   }
-  const preflight = await doctorProject(initOptions.targetPath, {
-    platform: initOptions.platform,
-    scope: initOptions.scope ?? 'project',
-  });
-  await ensureRequestedDependencies(initOptions.targetPath, initOptions, preflight);
-  const result = await initProject(initOptions.targetPath, initOptions);
+  const result = await initWorkspace(initOptions.targetPath, initOptions);
   if (initOptions.json) {
     console.log(JSON.stringify(result, null, 2));
   } else {

package/src/doctor.js

@@ -3,8 +3,8 @@ import { access, readFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 
-import { BUNDLED_ONESPEC_SKILLS } from './init.js';
-import { getSkillDir, PLATFORMS } from './platforms.js';
+import { BUNDLED_ONESPEC_REFERENCE_FILES, BUNDLED_ONESPEC_SKILLS } from './init.js';
+import { getDiscoveryRoots, getPlatform, getSkillDir } from './platforms.js';
 
 const REQUIRED_SUPERPOWERS = [
   'brainstorming',
@@ -41,8 +41,12 @@ function defaultCommandChecker(command) {
 function defaultSkillRoots(projectPath, scope, platform) {
   return [
     getSkillDir(projectPath, scope, platform),
-    path.join(os.homedir(), '.codex', 'skills'),
+    ...getDiscoveryRoots(projectPath, platform),
+    path.join(os.homedir(), '.claude', 'skills'),
     path.join(os.homedir(), '.codex', 'superpowers', 'skills'),
+    path.join(os.homedir(), '.cursor', 'skills'),
+    path.join(os.homedir(), '.gemini', 'skills'),
+    path.join(os.homedir(), '.copilot', 'skills'),
     path.join(os.homedir(), '.agents', 'skills'),
   ];
 }
@@ -60,7 +64,9 @@ async function isChineseOneSpec(projectPath, scope, platform) {
   const skillsDir = getSkillDir(projectPath, scope, platform);
   const installedSkills = [];
   const missingSkills = [];
+  const missingFiles = [];
   const skillPaths = {};
+  const referencePaths = {};
 
   for (const skillName of BUNDLED_ONESPEC_SKILLS) {
     const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
@@ -72,14 +78,24 @@ async function isChineseOneSpec(projectPath, scope, platform) {
     }
   }
 
+  for (const referenceFile of BUNDLED_ONESPEC_REFERENCE_FILES) {
+    const referencePath = path.join(skillsDir, 'onespec', referenceFile);
+    referencePaths[referenceFile] = referencePath;
+    if (!(await exists(referencePath))) {
+      missingFiles.push(path.join('onespec', referenceFile));
+    }
+  }
+
   const routerPath = skillPaths.onespec;
   if (!(await exists(routerPath))) {
     return {
       installed: false,
       skillPath: routerPath,
       skillPaths,
+      referencePaths,
       installedSkills,
       missingSkills,
+      missingFiles,
       chinese: false,
     };
   }
@@ -88,11 +104,13 @@ async function isChineseOneSpec(projectPath, scope, platform) {
   const chinese = content.includes('OneSpec 工作流');
   const english = content.includes('# OneSpec Workflow');
   return {
-    installed: missingSkills.length === 0 && (chinese || english),
+    installed: missingSkills.length === 0 && missingFiles.length === 0 && (chinese || english),
     skillPath: routerPath,
     skillPaths,
+    referencePaths,
     installedSkills,
     missingSkills,
+    missingFiles,
     chinese,
     english,
     language: chinese ? 'zh' : english ? 'en' : 'unknown',
@@ -101,20 +119,16 @@ async function isChineseOneSpec(projectPath, scope, platform) {
 
 export async function doctorProject(projectPath, options = {}) {
   const resolvedProject = path.resolve(projectPath);
-  const platform = options.platform ?? 'codex';
+  const platform = getPlatform(options.platform ?? 'codex');
   const scope = options.scope ?? 'project';
   const commandChecker = options.commandChecker ?? defaultCommandChecker;
 
-  if (!PLATFORMS[platform]) {
-    throw new Error(`Unsupported platform "${platform}". Currently only "codex" is supported.`);
-  }
-
-  const onespec = await isChineseOneSpec(resolvedProject, scope, platform);
+  const onespec = await isChineseOneSpec(resolvedProject, scope, platform.id);
   const skillRoots =
     options.skillRoots ??
     [
       ...new Set([
-        ...defaultSkillRoots(resolvedProject, scope, platform),
+        ...defaultSkillRoots(resolvedProject, scope, platform.id),
         ...(options.extraSkillRoots ?? []),
       ]),
     ];
@@ -139,29 +153,41 @@ export async function doctorProject(projectPath, options = {}) {
   const nextSteps = [];
   if (onespec.missingSkills.length > 0) {
     nextSteps.push(
-      `缺少 OneSpec Skills：${onespec.missingSkills.join(', ')}。运行 \`onespec init --overwrite\` 补齐 OneSpec Skill bundle。`,
+      `缺少 OneSpec Skills：${onespec.missingSkills.join(', ')}。运行 \`onespec init --platform ${platform.id} --overwrite\` 补齐 OneSpec Skill bundle。`,
+    );
+  } else if (onespec.missingFiles.length > 0) {
+    nextSteps.push(
+      `缺少 OneSpec references：${onespec.missingFiles.join(', ')}。运行 \`onespec init --platform ${platform.id} --overwrite\` 补齐 OneSpec Skill bundle。`,
     );
   } else if (!onespec.installed) {
-    nextSteps.push('运行 `onespec init --yes` 安装 OneSpec Skill。');
+    nextSteps.push(`运行 \`onespec init --platform ${platform.id} --yes\` 安装 OneSpec Skill。`);
   } else if (!onespec.chinese && !onespec.english) {
-    nextSteps.push('当前 OneSpec Skill 无法识别语言版本，运行 `onespec init --overwrite` 覆盖安装。');
+    nextSteps.push(
+      `当前 OneSpec Skill 无法识别语言版本，运行 \`onespec init --platform ${platform.id} --overwrite\` 覆盖安装。`,
+    );
   }
   if (!openspecCli.available) {
-    nextSteps.push('未找到 OpenSpec CLI，请安装 OpenSpec CLI 并在目标项目运行 `openspec init`。');
+    nextSteps.push(
+      `未找到 OpenSpec CLI。运行 \`onespec init --platform ${platform.id} --scope ${scope}\` 让 OneSpec 自动安装并初始化 OpenSpec。`,
+    );
   } else if (scope === 'project' && !openSpecProjectInstalled) {
-    nextSteps.push('当前项目尚未初始化 OpenSpec，请先运行 `openspec init`。');
+    nextSteps.push(
+      `当前项目尚未初始化 OpenSpec。请重新运行 \`onespec init --platform ${platform.id} --scope project\` 让 OneSpec 自动补齐。`,
+    );
   }
   if (!superpowers.available) {
-    nextSteps.push(`缺少 Superpowers Skills：${missing.join(', ')}。请先安装 Superpowers。`);
+    nextSteps.push(
+      `缺少 Superpowers Skills：${missing.join(', ')}。运行 \`onespec init --platform ${platform.id} --scope ${scope}\` 让 OneSpec 自动补齐。`,
+    );
   }
   if (nextSteps.length === 0) {
-    nextSteps.push('环境检查通过。可以在 Codex 中使用 `onespec` 工作流。');
+    nextSteps.push(`环境检查通过。可以在 ${platform.name} 中使用 \`onespec\` 工作流。`);
   }
 
   return {
     projectPath: resolvedProject,
-    platform,
-    platformName: PLATFORMS[platform].name,
+    platform: platform.id,
+    platformName: platform.name,
     scope,
     onespec,
     openspecCli,