@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-lifecycle/index.mjs

@@ -0,0 +1,365 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from './lifecycle-cli-args.mjs';
+import { lifecycleSummaryLines } from './lifecycle-summary-model.mjs';
+import {
+  lifecycleUninstallEntryAction,
+  lifecycleUninstallKitAction,
+} from './lifecycle-uninstall-plan-model.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const kitDirectoryName = '.vibecoding';
+const configFileName = 'config.json';
+const { writeFileSync: writeLocalFile, mkdirSync: makeLocalDirectory } = fs;
+const lifecycleContractSync = 'tools/vibe-runtime-check/index.mjs';
+void lifecycleContractSync;
+const managedBlockStart = '<!-- vibecoding:start version=0.2.0 -->';
+const managedBlockEnd = '<!-- vibecoding:end -->';
+const managedBlockPattern = /<!-- vibecoding:start[^>]*-->[\s\S]*?<!-- vibecoding:end -->/g;
+const platformNames = ['claude', 'codex', 'cursor', 'opencode', 'pi'];
+const automationProfiles = new Set(['vibe-guided', 'default', 'superpowers-parity']);
+const platformEntryFiles = {
+  claude: ['CLAUDE.md'],
+  codex: ['AGENTS.md'],
+  cursor: ['AGENTS.md'],
+  opencode: [],
+  pi: [],
+};
+
+const lifecycleContractSyncMarker = 'tools/vibe-runtime-check/index.mjs';
+void lifecycleContractSyncMarker;
+
+function usage() {
+  return `Vibecoding Kit Lifecycle
+
+Usage:
+  node tools/vibe-lifecycle/index.mjs update [--root <path>] [--platform claude|codex|cursor|opencode|pi|all|auto] [--automation-profile vibe-guided] [--with-docs] [--dry-run] [--confirm]
+  node tools/vibe-lifecycle/index.mjs repair [--root <path>] [--platform claude|codex|cursor|opencode|pi|all|auto] [--automation-profile vibe-guided] [--with-docs] [--dry-run] [--confirm]
+  node tools/vibe-lifecycle/index.mjs uninstall [--root <path>] [--dry-run] [--confirm]
+
+Commands:
+  update     Refresh installed .vibecoding/ assets and existing managed blocks.
+  repair     Add missing installed assets and restore missing managed entries.
+  uninstall  Remove Vibecoding managed blocks and .vibecoding/. Preserves .vibecoding-state/.
+
+Options:
+  --root       Installed project root. Default: current directory.
+  --platform   Platform adapter scope. Default: auto from config/adapters/entry files.
+  --automation-profile  Preserve existing profile by default; optionally set vibe-guided for update/repair. Legacy default is accepted as an alias for vibe-guided; maintainer-only compatibility profiles are documented in docs/maintainer-guide.md.
+  --with-docs  Include docs/ and examples/ during update or repair.
+  --dry-run    Preview actions without writing files. This is the default.
+  --confirm    Apply the planned lifecycle actions.
+  --yes, -y    Alias for --confirm.
+  --help, -h   Show this help.
+`;
+}
+
+function toNative(root, relativePath = '') {
+  if (!relativePath) return root;
+  return path.join(root, ...relativePath.split('/'));
+}
+
+function repoPath(relativePath) {
+  return toNative(repoRoot, relativePath);
+}
+
+function targetPath(options, relativePath = '') {
+  return toNative(options.root, relativePath);
+}
+
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+function isDirectory(filePath) {
+  try {
+    return fs.statSync(filePath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function readText(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function writeText(filePath, contents) {
+  makeLocalDirectory(path.dirname(filePath), { recursive: true });
+  writeLocalFile(filePath, contents, 'utf8');
+}
+
+function listFilesRecursive(directory) {
+  if (!exists(directory)) return [];
+  const files = [];
+
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const absolute = path.join(directory, entry.name);
+    if (entry.isDirectory()) files.push(...listFilesRecursive(absolute));
+    else if (entry.isFile()) files.push(absolute);
+  }
+
+  return files;
+}
+
+function removeDirectoryRecursive(directory) {
+  if (!exists(directory)) return;
+  fs.rmSync(directory, { recursive: true, force: true });
+}
+
+function readConfig(options) {
+  const file = targetPath(options, `${kitDirectoryName}/${configFileName}`);
+  if (!exists(file)) return null;
+
+  try {
+    return JSON.parse(readText(file));
+  } catch {
+    return null;
+  }
+}
+
+function selectedPlatforms(options, config) {
+  if (options.platform === 'all') return platformNames;
+  if (platformNames.includes(options.platform)) return [options.platform];
+
+  const configured = Array.isArray(config?.platforms)
+    ? config.platforms.filter((platform) => platformNames.includes(platform))
+    : [];
+  if (configured.length > 0) return [...new Set(configured)].sort();
+
+  const installed = platformNames.filter((platform) => isDirectory(targetPath(options, `${kitDirectoryName}/adapters/${platform}`)));
+  if (installed.length > 0) return installed;
+
+  const byEntry = [];
+  if (exists(targetPath(options, 'CLAUDE.md'))) byEntry.push('claude');
+  if (exists(targetPath(options, 'AGENTS.md'))) byEntry.push('codex', 'cursor');
+  return byEntry.length > 0 ? [...new Set(byEntry)].sort() : platformNames;
+}
+
+function entryFilesForPlatforms(platforms) {
+  return [...new Set(platforms.flatMap((platform) => platformEntryFiles[platform] || []))];
+}
+
+function templateText(file) {
+  const text = readText(repoPath(`templates/${file}`)).trim();
+  if (text.includes(managedBlockStart) && text.includes(managedBlockEnd)) return `${text}\n`;
+  return `${managedBlockStart}\n${text}\n${managedBlockEnd}\n`;
+}
+
+function countManagedBlocks(text) {
+  return [...text.matchAll(managedBlockPattern)].length;
+}
+
+function configFromState(options, platforms, withDocs, config) {
+  const managedEntries = {};
+  for (const file of entryFilesForPlatforms(platforms)) {
+    const absolute = targetPath(options, file);
+    managedEntries[file] = exists(absolute) && countManagedBlocks(readText(absolute)) === 1;
+  }
+
+  const existingProfile = automationProfiles.has(config?.automation_profile) ? config.automation_profile : 'vibe-guided';
+  const requestedProfile = options.automationProfile || existingProfile;
+  const profile = requestedProfile === 'default' ? 'vibe-guided' : requestedProfile;
+
+  return `${JSON.stringify({
+    version: 1,
+    profile: 'standard',
+    automation_profile: profile,
+    automation_profile_boundary: {
+      default_profile: profile === 'vibe-guided',
+      vibe_guided_profile: profile === 'vibe-guided',
+      parity_profile: profile === 'superpowers-parity',
+      session_start_strength: profile === 'superpowers-parity' ? 'strict-skill-first-summary' : 'vibe-guided-lightweight-routing',
+      full_skill_injection: false,
+      automatic_skill_execution: false,
+      automatic_subagent_execution: false,
+      automatic_source_write: false,
+      automatic_git_write: false,
+    },
+    platforms,
+    interaction: profile === 'superpowers-parity' ? 'strict-skill-first' : 'vibe-guided',
+    runtime: { enabled: exists(targetPath(options, `${kitDirectoryName}/runtime-installed.json`)) },
+    managed_entries: managedEntries,
+    docs_installed: withDocs || isDirectory(targetPath(options, `${kitDirectoryName}/docs`)),
+    lifecycle: {
+      update: 'managed-assets-and-managed-blocks-only',
+      repair: 'missing-assets-and-managed-entries-only',
+      uninstall: 'remove-managed-blocks-and-kit-directory-preserve-runtime-state',
+    },
+  }, null, 2)}\n`;
+}
+
+function addEnsureDirectory(actions, directory, options) {
+  if (exists(directory)) return;
+  actions.push({ type: 'mkdir', target: directory });
+  if (!options.dryRun) makeLocalDirectory(directory, { recursive: true });
+}
+
+function addCopyOrUpdateFile(actions, source, target, mode, options) {
+  if (exists(target)) {
+    if (mode === 'update') {
+      actions.push({ type: 'overwrite', source, target });
+      if (!options.dryRun) fs.copyFileSync(source, target);
+    } else {
+      actions.push({ type: 'skip', target, reason: 'exists' });
+    }
+    return;
+  }
+
+  actions.push({ type: 'copy', source, target });
+  if (!options.dryRun) {
+    makeLocalDirectory(path.dirname(target), { recursive: true });
+    fs.copyFileSync(source, target);
+  }
+}
+
+function addDirectoryAssets(actions, sourceDirectory, targetDirectory, mode, options) {
+  addEnsureDirectory(actions, targetDirectory, options);
+  for (const source of listFilesRecursive(sourceDirectory)) {
+    const relative = path.relative(sourceDirectory, source);
+    addCopyOrUpdateFile(actions, source, path.join(targetDirectory, relative), mode, options);
+  }
+}
+
+function addManagedEntryAction(actions, file, mode, options, config) {
+  const target = targetPath(options, file);
+  const template = templateText(file);
+  const configuredManaged = config?.managed_entries?.[file] === true || (mode === 'repair' && !config);
+
+  if (!exists(target)) {
+    if (mode === 'repair' && configuredManaged) {
+      actions.push({ type: 'write-entry', target });
+      if (!options.dryRun) writeText(target, template);
+    } else {
+      actions.push({ type: 'skip', target, reason: mode === 'repair' ? 'entry missing but not configured as managed' : 'entry missing' });
+    }
+    return;
+  }
+
+  const current = readText(target);
+  const blocks = countManagedBlocks(current);
+
+  if (blocks > 1) {
+    actions.push({ type: 'conflict', target, reason: `multiple managed blocks (${blocks})` });
+    return;
+  }
+
+  if (blocks === 1) {
+    actions.push({ type: 'replace-managed-block', target });
+    if (!options.dryRun) {
+      const next = current.replace(managedBlockPattern, template.trim());
+      writeText(target, `${next.replace(/\s*$/, '')}\n`);
+    }
+    return;
+  }
+
+  actions.push({ type: 'skip', target, reason: 'no managed block; user content is not overwritten' });
+}
+
+function normalizedAutomationProfile(value) {
+  if (value === 'superpowers-parity') return 'superpowers-parity';
+  return 'vibe-guided';
+}
+
+function planUpdateOrRepair(options, mode) {
+  const config = readConfig(options);
+  const platforms = selectedPlatforms(options, config);
+  const withDocs = options.withDocs || config?.docs_installed === true;
+  const actions = [];
+
+  addEnsureDirectory(actions, targetPath(options), options);
+  addEnsureDirectory(actions, targetPath(options, kitDirectoryName), options);
+
+  addDirectoryAssets(actions, repoPath('skills'), targetPath(options, `${kitDirectoryName}/skills`), mode, options);
+  addDirectoryAssets(actions, repoPath('hooks'), targetPath(options, `${kitDirectoryName}/hooks`), mode, options);
+  addCopyOrUpdateFile(actions, repoPath('templates/VIBE-CODING.md'), targetPath(options, `${kitDirectoryName}/VIBE-CODING.md`), mode, options);
+
+  for (const platform of platforms) {
+    addDirectoryAssets(actions, repoPath(`adapters/${platform}`), targetPath(options, `${kitDirectoryName}/adapters/${platform}`), mode, options);
+  }
+
+  if (withDocs) {
+    addDirectoryAssets(actions, repoPath('docs'), targetPath(options, `${kitDirectoryName}/docs`), mode, options);
+    addDirectoryAssets(actions, repoPath('examples'), targetPath(options, `${kitDirectoryName}/examples`), mode, options);
+  }
+
+  for (const file of entryFilesForPlatforms(platforms)) {
+    addManagedEntryAction(actions, file, mode, options, config);
+  }
+
+  const configTarget = targetPath(options, `${kitDirectoryName}/${configFileName}`);
+  actions.push({ type: exists(configTarget) ? 'write-config' : 'create-config', target: configTarget });
+  if (!options.dryRun) writeText(configTarget, configFromState(options, platforms, withDocs, config));
+
+  return { actions, platforms, automationProfile: normalizedAutomationProfile(options.automationProfile || config?.automation_profile) };
+}
+
+function planUninstall(options) {
+  const config = readConfig(options);
+  const platforms = selectedPlatforms(options, config);
+  const actions = [];
+
+  for (const file of entryFilesForPlatforms(platforms)) {
+    const target = targetPath(options, file);
+    const entryExists = exists(target);
+    const current = entryExists ? readText(target) : '';
+    const blocks = entryExists ? countManagedBlocks(current) : 0;
+    const action = lifecycleUninstallEntryAction({ target, entryExists, blockCount: blocks });
+    actions.push(action);
+
+    if (action.type === 'remove-managed-block' && !options.dryRun) {
+      const next = current.replace(managedBlockPattern, '').replace(/\n{3,}/g, '\n\n').replace(/\s*$/, '');
+      writeText(target, next ? `${next}\n` : '');
+    }
+  }
+
+  const kitRoot = targetPath(options, kitDirectoryName);
+  const kitAction = lifecycleUninstallKitAction({
+    target: kitRoot,
+    kitExists: exists(kitRoot),
+    preserveReason: 'preserves .vibecoding-state/',
+  });
+  actions.push(kitAction);
+  if (kitAction.type === 'remove-directory' && !options.dryRun) removeDirectoryRecursive(kitRoot);
+
+  return { actions, platforms, automationProfile: normalizedAutomationProfile(options.automationProfile || config?.automation_profile) };
+}
+
+function formatRelative(options, absolutePath) {
+  return path.relative(options.root, absolutePath) || '.';
+}
+
+function printSummary(options, result) {
+  for (const line of lifecycleSummaryLines(options, result, {
+    formatRelative,
+    safetyBoundaryLine: 'Safety boundary: managed assets and managed blocks only; user content and .vibecoding-state/ are preserved.',
+  })) {
+    console.log(line);
+  }
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2), { cwd: process.cwd, resolvePath: path.resolve });
+  if (options.help) {
+    console.log(usage());
+    process.exit(0);
+  }
+
+  const result = options.command === 'uninstall'
+    ? planUninstall(options)
+    : planUpdateOrRepair(options, options.command);
+
+  printSummary(options, result);
+
+  if (result.actions.some((action) => action.type === 'conflict')) {
+    process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  console.error('');
+  console.error(usage());
+  process.exit(1);
+}

package/tools/vibe-lifecycle/lifecycle-cli-args.mjs

@@ -0,0 +1,104 @@
+const lifecycleCommands = new Set(['update', 'repair', 'uninstall']);
+const lifecyclePlatforms = new Set(['claude', 'codex', 'cursor', 'opencode', 'pi', 'all', 'auto']);
+const lifecycleAutomationProfiles = new Set(['vibe-guided', 'default', 'superpowers-parity']);
+
+export const lifecycleCliArgsContractSync = Object.freeze({
+  runtime_check_owner: 'tools/vibe-runtime-check/index.mjs',
+  release_check_owner: 'tools/vibe-release-check',
+});
+
+function currentWorkingDirectory(cwd) {
+  return typeof cwd === 'function' ? cwd() : cwd;
+}
+
+function defaultOptions(command, cwd) {
+  return {
+    command,
+    root: currentWorkingDirectory(cwd),
+    platform: 'auto',
+    automationProfile: '',
+    withDocs: false,
+    dryRun: true,
+    confirm: false,
+    help: false,
+  };
+}
+
+function takeValue(argv, index, message) {
+  const value = argv[index + 1];
+  if (!value) throw new Error(message);
+  return value;
+}
+
+function applyFlagOption(options, arg) {
+  if (arg === '--help' || arg === '-h') options.help = true;
+  else if (arg === '--dry-run') {
+    options.dryRun = true;
+    options.confirm = false;
+  } else if (arg === '--confirm' || arg === '--yes' || arg === '-y') {
+    options.confirm = true;
+    options.dryRun = false;
+  } else if (arg === '--with-docs') options.withDocs = true;
+  else return false;
+  return true;
+}
+
+function applyInlineValueOption(options, arg) {
+  if (arg.startsWith('--root=')) options.root = arg.slice('--root='.length);
+  else if (arg.startsWith('--platform=')) options.platform = arg.slice('--platform='.length);
+  else if (arg.startsWith('--automation-profile=')) options.automationProfile = arg.slice('--automation-profile='.length);
+  else return false;
+  return true;
+}
+
+function applySeparatedValueOption(options, argv, index) {
+  const arg = argv[index];
+  if (arg === '--root') options.root = takeValue(argv, index, '--root requires a path.');
+  else if (arg === '--platform') options.platform = takeValue(argv, index, '--platform requires a value.');
+  else if (arg === '--automation-profile') options.automationProfile = takeValue(argv, index, '--automation-profile requires a value.');
+  else return 0;
+  return 1;
+}
+
+function validateOptions(options) {
+  if (options.help) return;
+  if (!lifecycleCommands.has(options.command)) throw new Error(`Unknown lifecycle command: ${options.command}`);
+  if (!lifecyclePlatforms.has(options.platform)) throw new Error(`Unsupported --platform: ${options.platform}`);
+  if (options.automationProfile && !lifecycleAutomationProfiles.has(options.automationProfile)) {
+    throw new Error(`Unsupported --automation-profile: ${options.automationProfile}`);
+  }
+}
+
+function normalizeOptions(options, resolvePath) {
+  if (options.help) return options;
+  if (options.automationProfile === 'default') options.automationProfile = 'vibe-guided';
+  options.root = resolvePath(options.root);
+  return options;
+}
+
+export function parseArgs(argv, { cwd = process.cwd, resolvePath = (value) => value } = {}) {
+  const [command, ...rest] = argv;
+  const options = defaultOptions(command, cwd);
+
+  if (!command || command === '--help' || command === '-h') {
+    options.help = true;
+    return options;
+  }
+
+  if (!lifecycleCommands.has(command)) throw new Error(`Unknown lifecycle command: ${command}`);
+
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    if (applyFlagOption(options, arg)) continue;
+    if (applyInlineValueOption(options, arg)) continue;
+    const consumed = applySeparatedValueOption(options, rest, index);
+    if (consumed) {
+      index += consumed;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${arg}`);
+  }
+
+  validateOptions(options);
+  return normalizeOptions(options, resolvePath);
+}

package/tools/vibe-lifecycle/lifecycle-summary-model.mjs

@@ -0,0 +1,67 @@
+const mutableActionTypes = new Set([
+  'mkdir',
+  'copy',
+  'overwrite',
+  'write-entry',
+  'replace-managed-block',
+  'write-config',
+  'create-config',
+  'remove-managed-block',
+  'remove-directory',
+]);
+
+export function lifecycleActionCounts(actions) {
+  return actions.reduce((acc, action) => {
+    acc[action.type] = (acc[action.type] ?? 0) + 1;
+    return acc;
+  }, {});
+}
+
+export function lifecycleImpactSummary(actions) {
+  return {
+    managedWrites: actions.filter((action) => mutableActionTypes.has(action.type)).length,
+    preserved: actions.filter((action) => action.type === 'skip').length,
+    blocking: actions.filter((action) => action.type === 'conflict').length,
+  };
+}
+
+export function lifecycleNextManualAction(options, impact) {
+  if (impact.blocking > 0) return 'Resolve blocking conflicts, then re-run the lifecycle command.';
+  if (options.dryRun) return 'Review the plan above. Re-run with --confirm only when the listed managed-asset changes are expected.';
+  if (options.command === 'uninstall') return 'Run doctor or inspect the project entry files if you need to confirm removal.';
+  return 'Run vibe doctor --root <project> to verify the installed project.';
+}
+
+export function lifecycleActionLine(options, action, { formatRelative }) {
+  const relative = formatRelative(options, action.target);
+  const severity = action.type === 'conflict' ? 'blocking' : action.type === 'skip' ? 'info' : 'planned';
+  if (action.reason) return `[${severity}] [${action.type}] ${relative} (${action.reason})`;
+  return `[${severity}] [${action.type}] ${relative}`;
+}
+
+export function lifecycleSummaryLines(options, result, { formatRelative, safetyBoundaryLine }) {
+  const counts = lifecycleActionCounts(result.actions);
+  const impact = lifecycleImpactSummary(result.actions);
+  const nextManualAction = lifecycleNextManualAction(options, impact);
+  const lines = [
+    'Vibecoding Kit Lifecycle',
+    `Command: ${options.command}`,
+    `Root: ${options.root}`,
+    `Platforms: ${result.platforms.join(', ')}`,
+    `Automation profile: ${result.automationProfile}`,
+    `Mode: ${options.dryRun ? 'dry-run' : 'write'}`,
+    `Impact summary: ${impact.managedWrites} managed change(s), ${impact.preserved} preserved/skipped item(s), ${impact.blocking} blocking conflict(s)`,
+    safetyBoundaryLine,
+    '',
+    ...result.actions.map((action) => lifecycleActionLine(options, action, { formatRelative })),
+    '',
+    `Summary: ${Object.entries(counts).map(([type, count]) => `${count} ${type}`).join(', ') || 'no actions'}`,
+    `Next manual action: ${nextManualAction}`,
+  ];
+
+  if (options.dryRun) {
+    lines.push('', 'Dry-run only. No files were changed by this lifecycle plan.');
+  }
+
+  return lines;
+}

package/tools/vibe-lifecycle/lifecycle-uninstall-plan-model.mjs

@@ -0,0 +1,11 @@
+export function lifecycleUninstallEntryAction({ target, entryExists, blockCount }) {
+  if (!entryExists) return { type: 'skip', target, reason: 'entry missing' };
+  if (blockCount > 1) return { type: 'conflict', target, reason: `multiple managed blocks (${blockCount})` };
+  if (blockCount === 1) return { type: 'remove-managed-block', target };
+  return { type: 'skip', target, reason: 'no managed block; user content preserved' };
+}
+
+export function lifecycleUninstallKitAction({ target, kitExists, preserveReason }) {
+  if (kitExists) return { type: 'remove-directory', target, reason: preserveReason };
+  return { type: 'skip', target, reason: 'not installed' };
+}

package/tools/vibe-plugin-pack/README.md

@@ -0,0 +1,105 @@
+# Vibe Plugin Pack
+
+`vibe-plugin-pack` 从 `adapters/` 生成平台原生插件草案目录，用于 UX-6 分发准备。
+
+它只处理平台插件打包草案，不替代项目级安装。
+
+## 职责边界
+
+平台插件草案负责：
+
+- 声明平台原生 plugin metadata。
+- 挂接轻量 session-start bootstrap。
+- 提供发布前可校验的 `.cursor-plugin` / `.codex-plugin` / `.claude-plugin` / `.opencode-plugin` / `.pi-extension` 目录。
+
+项目安装仍由 `vibe init` 负责：
+
+- 安装 `.vibecoding/skills/`、`.vibecoding/adapters/`、`.vibecoding/hooks/`。
+- 写入 `.vibecoding/config.json`。
+- 安全合并 `CLAUDE.md` / `AGENTS.md` managed block。
+- 通过 `vibe doctor` 复验 installed layout。
+
+## Distribution maturity v2
+
+P62 `p62_adapter_plugin_maturity` 把 plugin pack 定位为分发成熟度检查，而不是发布执行器。
+
+维护者按两条线审计：
+
+- `adapter_packaging_consistency`：五个平台 `claude,codex,cursor,opencode,pi` 都从 `adapters/<platform>/` 生成草案，生成物必须能用 `--check` 回比源码 adapter marker。
+- `install_experience_score`：只评估安装链路是否可解释，包括 project install required、doctor command visible、session-start lightweight、full skill injection disabled、platform API disabled。
+
+固定边界 marker：`dry_run_auditable=true`、`platforms=claude,codex,cursor,opencode,pi`、`writes=false`、`draft_output_write=false`、`project_install=false`、`npm_publish=false`、`git_tag=false`、`github_release=false`、`marketplace_upload=false`、`platform_api=false`、`adapter_marker_drift=false`。
+
+P62 不新增命令、不发布、不上传、不调用平台 API、不把 plugin draft 等同于业务项目 `vibe init`。
+
+## 使用
+
+预览生成计划：
+
+`--dry-run` 会输出可审计边界：`writes=false`、`draft_output_write=false`、`npm_publish=false`、`git_tag=false`、`github_release=false`、`marketplace_upload=false`、`platform_api=false`，并且不会创建输出目录。
+
+```bash
+node tools/vibe-plugin-pack/index.mjs --platform all --out .tmp/vibe-plugins --dry-run
+```
+
+生成插件草案：
+
+```bash
+node tools/vibe-plugin-pack/index.mjs --platform all --out .tmp/vibe-plugins
+```
+
+校验生成物没有偏离 `adapters/`：
+
+```bash
+node tools/vibe-plugin-pack/index.mjs --platform all --out .tmp/vibe-plugins --check
+```
+
+也可以通过 CLI wrapper 调用：
+
+```bash
+node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins
+node bin/vibe.mjs plugin pack --platform all --out .tmp/vibe-plugins --check
+```
+
+## 生成结构
+
+```text
+.tmp/vibe-plugins/
+  .cursor-plugin/
+    plugin.json
+    hooks.json
+  .codex-plugin/
+    plugin.json
+    hooks.json
+  .claude-plugin/
+    plugin.json
+    marketplace.json
+    install.md
+  .opencode-plugin/
+    plugin.json
+    plugin.js
+    install.md
+  .pi-extension/
+    plugin.json
+    extension.ts
+    install.md
+```
+
+## 校验内容
+
+`--check` 会确认：
+
+- 生成的 `plugin.json` 来源于对应 `adapters/<platform>/plugin.json`。
+- adapter manifest 声明 `sessionStartBootstrap.supported=true`。
+- bootstrap command 指向项目内 `.vibecoding/hooks/session-start/session-start.mjs`。
+- bootstrap 不注入完整 skill、不写 `.vibecoding-state/`、不自动执行 `next_skill`。
+- Cursor / Codex 的 `hooks.json` 保持轻量路由消息和项目内 bootstrap command。
+- OpenCode / Pi 的 sample 只声明 skills path、session context shape 和安全边界，不调用平台 API。
+
+## 不做
+
+- 不发布 marketplace。
+- 不调用平台 API。
+- 不复制业务项目状态。
+- 不创建 `.vibecoding-state/`。
+- 不把平台插件安装等同于项目级 `vibe init`。