@jtf19/vibecoding-kit 0.1.0

package/adapters/pi/extension.ts

@@ -0,0 +1,56 @@
+export const VIBECODING_PI_EXTENSION_CONTRACT = Object.freeze({
+  name: 'vibecoding-kit',
+  resources: {
+    skillPaths: ['.vibecoding/skills'],
+    entrySkill: 'using-vibecoding',
+  },
+  strictBootstrapAcceptance: {
+    profile: 'superpowers-parity',
+    bootstrap_marker: 'vibecoding:using-vibecoding bootstrap',
+    dedupe_marker: 'vibecoding:using-vibecoding bootstrap',
+    cache_policy: 'extension-local bootstrap context may be cached for a session',
+    session_compact_reinjects: true,
+    injectsFullSkill: false,
+    tool_mapping: {
+      invokeSkill: 'Pi native skill loading or explicit /skill:name',
+      taskList: 'Pi task tool when available, otherwise local plan tracking',
+      readFiles: 'Pi read tool',
+      editFiles: 'Pi write/edit tool',
+      shell: 'Pi bash tool with explicit user-controlled commands',
+      subagent: 'manual only unless an installed Pi subagent tool is explicitly authorized',
+    },
+  },
+  sessionStartBootstrap: {
+    command: 'node .vibecoding/hooks/session-start/session-start.mjs --format pi',
+    contextShape: 'hookSpecificOutput.additionalContext',
+    injectsFullSkill: false,
+    writesRuntimeState: false,
+    autoRunsNextSkill: false,
+  },
+  boundaries: {
+    hiddenExecution: false,
+    runtimeStateWrite: false,
+    platformApi: false,
+    modelInvocation: false,
+    gitWrite: false,
+    sourceWrite: false,
+  },
+});
+
+export function resources_discover() {
+  return {
+    skillPaths: VIBECODING_PI_EXTENSION_CONTRACT.resources.skillPaths,
+    entrySkill: VIBECODING_PI_EXTENSION_CONTRACT.resources.entrySkill,
+  };
+}
+
+export function session_start() {
+  return {
+    additionalContext: {
+      summary: 'For development tasks, read .vibecoding/skills/using-vibecoding/SKILL.md by file path; missing native skill registration is not a missing entry.',
+      bootstrap_command: VIBECODING_PI_EXTENSION_CONTRACT.sessionStartBootstrap.command,
+      strict_bootstrap_acceptance: VIBECODING_PI_EXTENSION_CONTRACT.strictBootstrapAcceptance,
+      boundaries: VIBECODING_PI_EXTENSION_CONTRACT.boundaries,
+    },
+  };
+}

package/adapters/pi/install.md

@@ -0,0 +1,95 @@
+# Pi Adapter
+
+## 作用
+
+提供 Pi extension bootstrap adapter 合同示例。
+
+## 文件
+
+```text
+plugin.json
+extension.ts
+install.md
+```
+
+## 接入方式
+
+1. 保留 `.vibecoding/skills/`，并通过 `resources_discover` 暴露 `skillPaths`。
+2. 使用 `extension.ts` 中的 `session_start` 合同示例生成 bootstrap context。
+3. 会话入口只提示轻量路由：按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`；如果平台原生 skill registry 未注册，不应判定入口缺失。
+4. `legacy-workflow-discipline` 只增强入口纪律摘要，不默认注入完整 skill。
+
+## 业务项目降级交互协议
+
+Pi bootstrap 保持轻量产品体验：会话入口只提供任务分流、skill-loading guidance 和安全边界提醒，完整 workflow 只在风险、阶段切换或交接需要时进入。不要把 runtime stage 长表或源码仓库维护者路线图注入普通业务会话。
+
+## 摘要优先入口
+
+Pi adapter 使用摘要优先入口。会话开始或任务开始时，如果使用 `workflow --start` 辅助判断，先读取 `workflow_start.entry_summary`：它给出入口分类、预期 state gap 和下一步人工动作。当 `entry_summary.state_gap_is_expected=true` 时，底层 `blocked_reasons` 只用于排障，不应把无状态规划请求解释为 runtime failure。
+
+完成或判断能否交付时，先读取 `completion_evidence.task_completion_summary`，再按需下钻 readiness gates、evidence inventory 和 closeout detail。
+
+这些摘要只改变阅读顺序，不授予隐藏执行、自动写入、自动测试、subagent、平台 API、git、push、PR 或 merge 权限。
+
+## 首次会话验收
+
+P56 安装后首次会话验收只读取本地入口文本、session-start shape 或人工导出的 transcript，不连接平台 API、不执行 hook 之外的业务命令、不运行 workflow skill。验收通过应看到：按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`、轻量分流、可见下一步、`injectsFullSkill=false`、`no_auto_execution`、`subagent=false`、`platform_api=false`、`git=false`。
+
+## Bootstrap 合同
+
+```bash
+node .vibecoding/hooks/session-start/session-start.mjs --format pi
+```
+
+该 bootstrap 只输出项目已安装 Vibecoding、配置路径、轻量路由和边界说明；不会注入完整 skill、写 `.vibecoding-state/`、调用 runtime、subagent、MCP、daemon、平台 API、git 或 worktree。
+
+## Strict bootstrap acceptance
+
+`legacy-workflow-discipline` 可读取 `strictBootstrapAcceptance`：`bootstrap_marker` / `dedupe_marker` 用于识别一次会话中的 Vibecoding 入口，`cache_policy` 允许 extension 在会话内缓存入口摘要，`session_compact_reinjects=true` 表示压缩后可以重新放回同一入口摘要，`tool_mapping` 只说明 Pi 工具等价关系。
+
+该合同保持 `injectsFullSkill=false`。它提供 skill-loading guidance 和去重证据，不自动执行 skill、不调用 subagent、不调用平台 API、不写 `.vibecoding-state/`、不写源码、不触碰 git。
+
+## Transcript export 示例
+
+Adapter 可以手动记录或导出本地 transcript JSON，供只读 intake 检查使用。该导出只包含文本 turn、本地 artifact ref、观察到的 marker 和边界字段；不连接 Pi 平台 API、不执行 skill、不调用 subagent/MCP/model、不运行命令、不触碰 git。
+
+最小形状：
+
+```json
+{
+  "platform": "pi",
+  "source": {
+    "export_kind": "manual_local_transcript_json"
+  },
+  "turns": [
+    { "role": "assistant", "content": "using-vibecoding lightweight route selected" }
+  ],
+  "observed": {
+    "commands": [],
+    "markers": ["using-vibecoding", "validation_strategy_present"]
+  },
+  "artifact_refs": [],
+  "boundary_assertions": {
+    "platform_api": false,
+    "command_execution": false,
+    "skill_execution": false,
+    "subagent": false,
+    "git": false
+  },
+  "export_digest": "0000000000000000000000000000000000000000000000000000000000000000"
+}
+```
+
+完整示例主题由 `tools/vibe-runtime/runtime-platform-transcript-example-pack.mjs` 覆盖：session-start、workflow entry、SDD brief/report/review chain、review blocker、resume dedupe、completion evidence。保存到项目内本地 JSON 后，只能通过 `evals --transcript-intake --from-file <json> --json --root <project-root>` 读取验证；runtime 不会执行 transcript 中出现的命令文本。
+
+## Distribution maturity
+
+P62 `p62_adapter_plugin_maturity` 要求 Pi adapter 在分发检查中保持 marker 稳定：`adapter_packaging_consistency`、`install_experience_score`、`dry_run_auditable=true`、`adapter_marker_drift=false`、`platform_api=false`、`npm_publish=false`、`git_tag=false`、`github_release=false`、`marketplace_upload=false`。
+
+该成熟度只说明 plugin draft 可由 `vibe-plugin-pack --dry-run` 审计、可由 `--check` 回比 `adapters/pi/`；不表示发布、上传、调用 Pi API、项目级安装或自动执行。
+
+## Runtime Bridge 边界
+
+`plugin.json` 声明 `runtimeBridge` capability：`mode` 固定为 `manual`，可读取只读 dispatch intent 或人工确认产生的 sidecar，但不能自动执行 skill、调用 subagent、调用平台 API 或触碰 git。
+
+Pi adapter-ready 只表示可以人工读取 intent 或 sidecar 后继续目标 workflow skill；不表示 Pi 自动调用平台 API、自动执行 skill、修改源码或写 git。

package/adapters/pi/plugin.json

@@ -0,0 +1,58 @@
+{
+  "name": "vibe-coding-kit",
+  "displayName": "Vibecoding Kit",
+  "description": "Workflow skills and lightweight session bootstrap contract for Pi.",
+  "version": "0.1.0",
+  "author": {
+    "name": "vibe-coding-kit"
+  },
+  "license": "MIT",
+  "keywords": [
+    "vibecoding",
+    "skills",
+    "planning",
+    "debugging",
+    "verification",
+    "workflow"
+  ],
+  "skills": "../../skills/",
+  "installedSkills": ".vibecoding/skills/",
+  "layout": {
+    "repoSkills": "../../skills/",
+    "installedSkills": ".vibecoding/skills/",
+    "installedAdapter": ".vibecoding/adapters/pi/",
+    "entryFile": "AGENTS.md"
+  },
+  "runtimeBridge": {
+    "supported": true,
+    "mode": "manual",
+    "canReadDispatchIntent": true,
+    "canAutoExecuteSkill": false,
+    "canCallSubagent": false,
+    "canTouchGit": false
+  },
+  "strictBootstrapAcceptance": {
+    "profile": "superpowers-parity",
+    "bootstrap_marker": "vibecoding:using-vibecoding bootstrap",
+    "dedupe_marker": "vibecoding:using-vibecoding bootstrap",
+    "cache_policy": "extension-local bootstrap context may be cached for a session",
+    "session_compact_reinjects": true,
+    "injectsFullSkill": false,
+    "tool_mapping": [
+      "invokeSkill",
+      "taskList",
+      "readFiles",
+      "editFiles",
+      "shell",
+      "subagent"
+    ]
+  },
+  "sessionStartBootstrap": {
+    "supported": true,
+    "command": "node .vibecoding/hooks/session-start/session-start.mjs --format pi",
+    "injectsFullSkill": false,
+    "writesRuntimeState": false,
+    "autoRunsNextSkill": false
+  },
+  "platformSample": "./extension.ts"
+}

package/bin/vibe-cli-usage.mjs

@@ -0,0 +1,43 @@
+// Top-level CLI usage contract mirrors package command routing and tools/vibe-runtime/README.md install docs.
+
+export function usage() {
+  return `Vibecoding Kit CLI
+
+Usage:
+  vibe init [--target <path>] [--platform claude|codex|cursor|opencode|pi|all|auto] [--automation-profile default|superpowers-parity] [--with-docs] [--with-runtime] [--dry-run] [--check] [--merge=preview|append|replace|manual] [--yes]
+  vibe doctor [--root <path>] [--workflow-entry]
+  vibe update [--root <path>] [--platform claude|codex|cursor|opencode|pi|all|auto] [--with-docs] [--dry-run] [--confirm]
+  vibe repair [--root <path>] [--platform claude|codex|cursor|opencode|pi|all|auto] [--with-docs] [--dry-run] [--confirm]
+  vibe uninstall [--root <path>] [--dry-run] [--confirm]
+  vibe profile [--root <path>] --show [--json]
+  vibe profile [--root <path>] --explain [--json]
+  vibe profile [--root <path>] --set default|superpowers-parity|execution-enabled [--dry-run|--confirm] [--json]
+  vibe plugin pack [--platform claude|codex|cursor|opencode|pi|all] [--out <path>] [--dry-run] [--check]
+
+Commands:
+  init       Install Vibecoding Kit into a project. Defaults --target to the current directory.
+  doctor     Check a Vibecoding Kit source repo or installed project. Defaults root to the current directory.
+  update     Refresh installed .vibecoding/ assets and existing managed blocks. Dry-run by default.
+  repair     Add missing installed assets and restore missing managed entries. Dry-run by default.
+  uninstall  Remove managed blocks and .vibecoding/. Preserves .vibecoding-state/. Dry-run by default.
+  profile    Show or switch installed automation profile. Only writes .vibecoding/config.json with --confirm.
+  plugin     Platform plugin draft packaging commands. Currently supports: plugin pack.
+
+Examples:
+  vibe init
+  vibe init --platform cursor
+  vibe init --platform all --dry-run
+  vibe init --merge=preview
+  vibe init --merge=append --yes
+  vibe doctor
+  vibe doctor --root .
+  vibe repair --dry-run
+  vibe uninstall --dry-run
+  vibe profile --root ../my-project --show
+  vibe profile --root ../my-project --explain
+  vibe profile --root ../my-project --set superpowers-parity --dry-run
+  vibe profile --root ../my-project --set superpowers-parity --confirm
+  vibe plugin pack --platform all --out .tmp/vibe-plugins --dry-run
+  vibe plugin pack --platform all --out .tmp/vibe-plugins --check
+`;
+}

package/bin/vibe.mjs

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { usage } from './vibe-cli-usage.mjs';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+function hasValueOption(argv, name) {
+  return argv.includes(name);
+}
+
+function expandEqualsOptions(argv, optionNames) {
+  return argv.flatMap((arg) => {
+    const optionName = optionNames.find((name) => arg.startsWith(`${name}=`));
+    if (!optionName) return [arg];
+
+    return [optionName, arg.slice(optionName.length + 1)];
+  });
+}
+
+function normalizeInitArgs(argv) {
+  const expanded = expandEqualsOptions(argv, ['--target', '--platform', '--automation-profile', '--merge']);
+
+  if (expanded.includes('--help') || expanded.includes('-h') || hasValueOption(expanded, '--target')) {
+    return expanded;
+  }
+
+  return ['--target', process.cwd(), ...expanded];
+}
+
+function normalizeDoctorArgs(argv) {
+  const normalized = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--root') {
+      const root = argv[index + 1];
+      if (!root) throw new Error('--root requires a path.');
+      normalized.push(root);
+      index += 1;
+    } else if (arg.startsWith('--root=')) {
+      const root = arg.slice('--root='.length);
+      if (!root) throw new Error('--root requires a path.');
+      normalized.push(root);
+    } else {
+      normalized.push(arg);
+    }
+  }
+
+  return normalized;
+}
+
+function runScript(relativeScriptPath, argv) {
+  const scriptPath = path.join(repoRoot, relativeScriptPath);
+  const result = spawnSync(process.execPath, [scriptPath, ...argv], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+    windowsHide: true,
+  });
+
+  if (result.error) {
+    throw result.error;
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+function main(argv) {
+  const [command, ...commandArgs] = argv;
+
+  if (!command || command === '--help' || command === '-h') {
+    console.log(usage());
+    return;
+  }
+
+  if (command === 'init') {
+    runScript('tools/vibe-init/index.mjs', normalizeInitArgs(commandArgs));
+    return;
+  }
+
+  if (command === 'doctor') {
+    runScript('tools/vibe-doctor/index.mjs', normalizeDoctorArgs(commandArgs));
+    return;
+  }
+
+  if (['update', 'repair', 'uninstall'].includes(command)) {
+    runScript('tools/vibe-lifecycle/index.mjs', [command, ...commandArgs]);
+    return;
+  }
+
+  if (command === 'profile') {
+    runScript('tools/vibe-profile/index.mjs', commandArgs);
+    return;
+  }
+
+  if (command === 'plugin') {
+    const [pluginCommand, ...pluginArgs] = commandArgs;
+    if (pluginCommand === 'pack') {
+      runScript('tools/vibe-plugin-pack/index.mjs', pluginArgs);
+      return;
+    }
+
+    throw new Error(`Unknown plugin command: ${pluginCommand || '(missing)'}`);
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+try {
+  main(process.argv.slice(2));
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  console.error('');
+  console.error(usage());
+  process.exit(1);
+}