@jtf19/vibecoding-kit 0.1.0

package/hooks/session-start/README.md

@@ -0,0 +1,112 @@
+# Session Start Hook
+
+## 目标
+
+在新会话开始时提供轻量入口提示，帮助 agent 判断用户请求是否需要 Vibecoding workflow。
+
+`session-start.mjs` 是跨平台可执行 bootstrap。它只输出轻量 additional context，不读取完整 skill 内容，不写 `.vibecoding-state/`，也不调用 runtime、subagent、MCP、daemon、平台 API、git 或 worktree。
+
+开发任务优先加载 `using-vibecoding`，再由它按任务类型路由到合适的 workflow skill。简单问答可以直接处理，不强制进入 workflow。
+
+## 覆盖范围
+
+该 hook 只覆盖新会话入口判断和 workflow 提醒：
+
+- 需求模糊、新功能、重构、架构调整：进入 `vibe-brainstorming` / `vibe-planning`。
+- 明确小任务或已有计划：进入 TDD / implementation / verification before completion 链路。
+- bug、失败、异常行为：进入系统化 debugging 链路。
+- 多任务计划：先判断是否需要 parallel work dispatch。
+- 高风险改动、并行工作、分支收口：先判断是否需要 workspace isolation。
+- subagent 请求：必须有完整 brief 和明确用户许可。
+- review / review feedback：进入对应 review 链路。
+- 长上下文或交接需要：进入 context compact 链路。
+
+## 启动前检查
+
+进入 workflow 前，先明确：
+
+- `goal`
+- `scope`
+- `risks`
+- `acceptance`
+- `evidence needed`
+- `next_skill`
+- `stop_condition`
+
+阶段结束时输出 `Workflow Handoff`，至少包含 `current_skill`、`next_skill`、`reason`、`handoff` 和 `stop_condition`。
+
+JSON handoff 是推荐格式；legacy handoff 仍保持兼容。
+
+## 可执行 bootstrap
+
+平台 hook 可以调用：
+
+```bash
+node .vibecoding/hooks/session-start/session-start.mjs --format auto
+```
+
+常用格式：
+
+```bash
+node .vibecoding/hooks/session-start/session-start.mjs --format cursor
+node .vibecoding/hooks/session-start/session-start.mjs --format claude
+node .vibecoding/hooks/session-start/session-start.mjs --format codex
+node .vibecoding/hooks/session-start/session-start.mjs --format text
+```
+
+输出只包含轻量上下文：项目已安装 Vibecoding、配置路径、平台、automation profile、interaction、是否启用 runtime、`using-vibecoding` 的相对路径和安全边界。
+
+它不会读取 `.vibecoding/skills/using-vibecoding/SKILL.md` 的完整内容。需要更多指导时，由 agent 按需读取该 skill。
+
+`automation_profile: "legacy-workflow-discipline"` 只增强入口纪律：要求先做 `using-vibecoding` 判断、说明 route、避免直接跳到实现。它仍不注册 hook、不执行 skill、不调用 subagent、不写源码、不碰 git。
+
+## Runtime 边界
+
+`vibe-runtime` 是可选的显式 ledger 工具，不属于 session-start hook 自动流程。
+
+本 hook 不会：
+
+- 自动调用工具。
+- 自动记录 `.vibecoding-state/`。
+- 自动执行 `next_skill`。
+- 自动调用 subagent、MCP、daemon 或 agent graph。
+- 自动执行 git、worktree、branch 或 stash 操作。
+- 强制切换 workflow。
+- 维护跨阶段状态机。
+
+workflow 进展仍由用户意图、skill 输出的 `next_skill` 和显式 `Workflow Handoff` 推进。
+
+## 建议提示
+
+```text
+Vibecoding Kit is installed for this project.
+
+At session start, use lightweight routing by default:
+- Small, clear tasks: answer or implement lightly, then verify before completion.
+- New features, refactors, architecture changes, unclear requests: route through brainstorming/planning when useful.
+- Bugs or failures: reproduce and locate root cause before fixing.
+- Long, risky, multi-stage, or handoff-heavy work: use the relevant Vibecoding workflow and produce a Workflow Handoff.
+
+If more guidance is needed, read `.vibecoding/skills/using-vibecoding/SKILL.md`.
+
+Runtime boundary:
+- Do not inject the full skill content at session start.
+- Do not auto-record `.vibecoding-state/`.
+- Do not auto-run `next_skill`.
+- Do not call runtime, subagents, MCP, daemon, platform APIs, git, or worktree actions from this hook.
+
+This hook is only a lightweight bootstrap. Workflow progress stays explicit through user intent, selected skill, and completion evidence.
+```
+
+## 验证
+
+修改该 hook 后至少运行：
+
+```bash
+node hooks/session-start/session-start.mjs --format text
+node tools/vibe-doctor/index.mjs
+node tools/vibe-release-check/index.mjs --quiet
+git diff --check
+```
+
+并确认 `.tmp/` 与 `.vibecoding-state/` 没有残留。

package/hooks/session-start/session-start-state-boundary-contract.mjs

@@ -0,0 +1,161 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+const scriptDirectory = path.dirname(fileURLToPath(import.meta.url));
+const installedProjectRoot = path.resolve(scriptDirectory, '..', '..', '..');
+const vibecodingDirectoryName = '.vibecoding';
+const stateDirectoryName = `${vibecodingDirectoryName}-state`;
+
+export function defaultSessionStartRoot() {
+  if (fs.existsSync(path.join(installedProjectRoot, vibecodingDirectoryName))) return installedProjectRoot;
+  return process.cwd();
+}
+
+export function sessionStartUsage() {
+  return `Vibecoding Session Start Bootstrap
+
+Usage:
+  node .vibecoding/hooks/session-start/session-start.mjs [--format auto|text|sdk|cursor|cursor-sdk|claude|codex|opencode|pi] [--root <project>]
+
+The bootstrap prints lightweight session context only. It does not read full skills, write ${stateDirectoryName}/, run runtime commands, call platform APIs, call subagents, or touch git/worktree.
+`;
+}
+
+export function parseSessionStartArgs(argv) {
+  const options = { format: 'auto', root: defaultSessionStartRoot(), help: false };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--format') {
+      options.format = argv[index + 1];
+      index += 1;
+    } else if (arg.startsWith('--format=')) {
+      options.format = arg.slice('--format='.length);
+    } else if (arg === '--root') {
+      options.root = path.resolve(argv[index + 1]);
+      index += 1;
+    } else if (arg.startsWith('--root=')) {
+      options.root = path.resolve(arg.slice('--root='.length));
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  if (!['auto', 'text', 'sdk', 'cursor', 'cursor-sdk', 'claude', 'codex', 'opencode', 'pi'].includes(options.format)) {
+    throw new Error(`Unsupported --format: ${options.format}`);
+  }
+
+  return options;
+}
+
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function relativeFromRoot(root, filePath) {
+  return path.relative(root, filePath).replaceAll(path.sep, '/');
+}
+
+function automationProfile(config) {
+  if (config?.automation_profile === 'superpowers-parity') return 'superpowers-parity';
+  return 'default';
+}
+
+function routingLines(profile) {
+  if (profile !== 'superpowers-parity') {
+    return [
+      'Default routing:',
+      '- selected_skill=using-vibecoding.',
+      '- visible_route=lightweight route: read the entry skill by file path, classify risk, then choose the minimum suitable workflow only when needed.',
+      '- next_manual_action=read .vibecoding/skills/using-vibecoding/SKILL.md, state the route, and name the validation strategy or evidence gap before changing source.',
+      '- context_policy=tiny_context by default; use balanced_context only for implementation, debugging, or completion evidence.',
+      '- Small, clear tasks: answer or implement lightly, then verify before completion.',
+      '- New features, refactors, architecture changes, unclear requests: use lightweight routing first; escalate to brainstorming/planning when needed.',
+      '- Bugs or failures: reproduce and locate root cause before fixing.',
+      '- Long, risky, multi-stage, or handoff-heavy work: use the relevant Vibecoding workflow and produce a Workflow Handoff.',
+    ];
+  }
+
+  return [
+    'Superpowers-parity routing:',
+    '- selected_skill=using-vibecoding.',
+    '- visible_route=strict skill-first visible route: read the entry skill by file path, classify risk, and state the selected workflow before implementation.',
+    '- next_manual_action=read using-vibecoding, classify the user request, then read the selected workflow skill only if it applies.',
+    '- context_policy=tiny_context first; use balanced_context only when implementation, debugging, or completion evidence needs more local context.',
+    '- This is still task routing context; only the entry discipline is stronger than the default lightweight path.',
+    '- Before implementation, make an explicit using-vibecoding decision and state the selected route.',
+    '- If there is any reasonable chance a workflow skill applies, read the relevant skill before coding.',
+    '- For unclear work, plan or clarify first; do not jump directly to source changes.',
+    '- For multi-task plans, keep progress explicit and review each task before moving to the next one.',
+    '- High-risk actions still require separate user authorization and evidence gates.',
+  ];
+}
+
+function skillFirstReceiptLines(profile) {
+  if (profile !== 'superpowers-parity') return [];
+  return [
+    '',
+    'Skill-first visible receipt:',
+    '- Selected entry skill: using-vibecoding.',
+    '- Route reason: superpowers-parity requires visible routing before implementation.',
+    '- Next gate: read using-vibecoding, classify the user request, then read the selected workflow skill only if it applies.',
+    '- Must not do yet: do not claim skill execution, run workflow commands, call subagents, use platform APIs, write business source, or perform git/worktree actions from session-start.',
+  ];
+}
+
+function boundaryLines() {
+  return [
+    'Boundaries:',
+    '- Do not inject the full skill content at session start.',
+    `- Do not create or modify ${stateDirectoryName}/ from this bootstrap.`,
+    '- Do not auto-run next_skill, runtime, subagents, MCP, daemon, platform APIs, git, or worktree actions.',
+    '- hidden_execution=false; command_execution=false; skill_execution_claimed=false; subagent_dispatch_claimed=false; git_write_claimed=false; platform_api=false; model_invocation=false; business_source_write=false.',
+  ];
+}
+
+export function sessionStartBootstrapContext(options) {
+  const root = options.root;
+  const config = readJson(path.join(root, vibecodingDirectoryName, 'config.json'));
+  const platforms = Array.isArray(config?.platforms) && config.platforms.length > 0
+    ? config.platforms.join(', ')
+    : 'unknown';
+  const profile = automationProfile(config);
+  const interaction = typeof config?.interaction === 'string' ? config.interaction : profile === 'superpowers-parity' ? 'strict-skill-first' : 'lightweight';
+  const runtimeEnabled = config?.runtime?.enabled === true;
+  const skillRelativePath = relativeFromRoot(root, path.join(root, vibecodingDirectoryName, 'skills', 'using-vibecoding', 'SKILL.md'));
+  const configRelativePath = relativeFromRoot(root, path.join(root, vibecodingDirectoryName, 'config.json'));
+  const hasUsingVibecoding = fs.existsSync(path.join(root, skillRelativePath));
+
+  return [
+    'Vibecoding Kit is installed for this project.',
+    '',
+    `Install config: ${configRelativePath}`,
+    `Platforms: ${platforms}`,
+    `Automation profile: ${profile}`,
+    `Interaction: ${interaction}`,
+    `Runtime enabled: ${runtimeEnabled ? 'true' : 'false'}`,
+    '',
+    ...routingLines(profile),
+    ...skillFirstReceiptLines(profile),
+    '',
+    `If more guidance is needed, read ${skillRelativePath}${hasUsingVibecoding ? '' : ' (missing; run vibe repair)'}.`,
+    '',
+    ...boundaryLines(),
+  ].join('\n');
+}
+
+export function autoSessionStartFormat() {
+  if (process.env.CURSOR_PLUGIN_ROOT) return 'cursor';
+  if (process.env.CLAUDE_PLUGIN_ROOT) return 'claude';
+  if (process.env.CODEX_HOME || process.env.CODEX_ENV) return 'codex';
+  return 'sdk';
+}

package/hooks/session-start/session-start.md

@@ -0,0 +1,29 @@
+Vibecoding Kit is installed for this project.
+
+Treat it as a controlled agent sandbox: users can ask for normal coding work, while the agent chooses the smallest safe workflow for the task.
+
+At session start, use lightweight routing by default:
+- `selected_skill=using-vibecoding`.
+- `visible_route=lightweight route`: read the entry skill by file path, classify risk, then choose the minimum suitable workflow only when needed.
+- `next_manual_action=read .vibecoding/skills/using-vibecoding/SKILL.md`, state the route, and name the validation strategy or evidence gap before changing source.
+- `context_policy=tiny_context` by default; use `balanced_context` only for implementation, debugging, or completion evidence.
+- Small, clear tasks: answer or implement lightly, then verify before completion.
+- New features, refactors, architecture changes, unclear requests: route through brainstorming/planning when useful.
+- Bugs or failures: reproduce and locate root cause before fixing.
+- Long, risky, multi-stage, or handoff-heavy work: use the relevant Vibecoding workflow and produce a Workflow Handoff.
+
+If more guidance is needed, read `.vibecoding/skills/using-vibecoding/SKILL.md`.
+
+Runtime boundary:
+- Do not inject the full skill content at session start.
+- Do not auto-record `.vibecoding-state/`.
+- Do not auto-run `next_skill`.
+- Do not call runtime, subagents, MCP, daemon, platform APIs, git, or worktree actions from this hook.
+- `hidden_execution=false`; `command_execution=false`; `skill_execution_claimed=false`; `subagent_dispatch_claimed=false`; `git_write_claimed=false`; `platform_api=false`; `model_invocation=false`; `business_source_write=false`.
+
+This hook is only a lightweight bootstrap. Workflow progress stays explicit through user intent, selected skill, and completion evidence.
+
+Optional `legacy-workflow-discipline` profile:
+- `.vibecoding/config.json` may set `automation_profile` to `legacy-workflow-discipline`.
+- In that profile, session-start strengthens skill-first routing and asks the agent to state the selected route before implementation.
+- It still does not inject full skill content, create `.vibecoding-state/`, auto-run skills, call subagents, modify source, or touch git.

package/hooks/session-start/session-start.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import {
+  autoSessionStartFormat,
+  parseSessionStartArgs,
+  sessionStartBootstrapContext,
+  sessionStartUsage,
+} from './session-start-state-boundary-contract.mjs';
+
+function printContext(format, context) {
+  if (format === 'text') {
+    console.log(context);
+    return;
+  }
+
+  if (format === 'cursor' || format === 'opencode') {
+    console.log(JSON.stringify({ additional_context: context }, null, 2));
+    return;
+  }
+
+  if (format === 'claude' || format === 'pi') {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: context,
+      },
+    }, null, 2));
+    return;
+  }
+
+  console.log(JSON.stringify({ additionalContext: context }, null, 2));
+}
+
+try {
+  const options = parseSessionStartArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(sessionStartUsage());
+    process.exit(0);
+  }
+
+  const format = options.format === 'auto' ? autoSessionStartFormat() : options.format;
+  printContext(format, sessionStartBootstrapContext(options));
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  console.error('');
+  console.error(sessionStartUsage());
+  process.exit(1);
+}

package/hooks/workflow-handoff/README.md

@@ -0,0 +1,44 @@
+# Workflow Handoff Hook
+
+## 目标
+
+在一个 workflow 阶段结束后，提醒 agent 检查 `Workflow Handoff`，并根据 `next_skill` 明确下一步是否继续。
+
+## 辅助自动化边界
+
+该 hook 是提示模板，不是 runtime 编排器。
+
+它可以提醒：
+
+- 当前输出是否包含 `Workflow Handoff`。
+- 是否写明 `current_skill` 和 `next_skill`。
+- `handoff` 是否包含目标、范围、关键决策、文件、风险和验收标准。
+- `stop_condition` 是否明确。
+- 如果 `next_skill` 是 `none`，是否应该停止等待用户。
+
+它不能：
+
+- 自动执行下一个 skill。
+- 自动调用工具。
+- 自动跳过用户确认。
+- 自动维护跨会话状态。
+
+## 建议提示
+
+```text
+Workflow stage finished.
+
+Before continuing, check:
+- current_skill is present
+- next_skill is present
+- handoff includes goal, scope, key decisions, files, risks, and acceptance
+- stop_condition is clear
+
+If next_skill is none, stop and wait.
+If next_skill is set, explicitly ask or continue only when the user request allows it.
+Do not run an automatic workflow chain.
+```
+
+## 与 workflow-chaining 的关系
+
+`docs/workflow-chaining.md` 定义流程状态和下一跳规则，本 hook 只把这些规则变成阶段结束时的提示。真实推进仍由用户请求、agent 判断和 `Workflow Handoff` 显式完成。

package/hooks/workflow-handoff/workflow-handoff.md

@@ -0,0 +1,11 @@
+Workflow stage finished.
+
+Before continuing, check:
+- current_skill is present
+- next_skill is present
+- handoff includes goal, scope, key decisions, files, risks, and acceptance
+- stop_condition is clear
+
+If next_skill is none, stop and wait.
+If next_skill is set, explicitly ask or continue only when the user request allows it.
+Do not run an automatic workflow chain.

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@jtf19/vibecoding-kit",
+  "version": "0.1.0",
+  "description": "Workflow skills and install tooling for safe, evidence-driven coding agents.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "Vibecoding Kit contributors",
+  "homepage": "https://github.com/jtf19/vibe-coding#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jtf19/vibe-coding.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jtf19/vibe-coding/issues"
+  },
+  "keywords": [
+    "agent",
+    "ai-agent",
+    "coding-agent",
+    "workflow",
+    "vibecoding",
+    "developer-tools",
+    "governance",
+    "evidence"
+  ],
+  "bin": {
+    "vibe": "./bin/vibe.mjs"
+  },
+  "files": [
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "CLAUDE.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "README.md",
+    "SECURITY.md",
+    "adapters/",
+    "bin/",
+    "docs/",
+    "examples/",
+    "hooks/",
+    "skills/",
+    "templates/",
+    "tools/"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "vibe": "node bin/vibe.mjs",
+    "doctor": "node tools/vibe-doctor/index.mjs",
+    "check": "node tools/vibe-runtime-check/index.mjs",
+    "check:arch": "node tools/vibe-architecture-check/index.mjs --root . --json",
+    "check:doctor": "node tools/vibe-doctor/index.mjs",
+    "release:fast": "node tools/vibe-release-check/index.mjs --suite fast --quiet",
+    "release:runtime": "node tools/vibe-release-check/index.mjs --suite runtime --quiet",
+    "release:runtime:experience": "node tools/vibe-release-check/index.mjs --suite runtime:experience --quiet --timing",
+    "release:runtime:execution": "node tools/vibe-release-check/index.mjs --suite runtime:execution-boundary --quiet --timing",
+    "release:runtime:state": "node tools/vibe-release-check/index.mjs --suite runtime:state-ledger --quiet --timing",
+    "release:install": "node tools/vibe-release-check/index.mjs --suite install --quiet",
+    "release:learning": "node tools/vibe-release-check/index.mjs --suite learning --quiet",
+    "release:tokens": "node tools/vibe-release-check/index.mjs --suite tokens --quiet",
+    "release:behavior": "node tools/vibe-release-check/index.mjs --suite behavior --quiet",
+    "demo:golden-path": "node tools/vibe-release-check/index.mjs --suite golden-path --quiet",
+    "demo:full-chain": "node tools/vibe-release-check/index.mjs --suite full-chain --quiet",
+    "pack:dry-run": "npm pack --dry-run --json"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}