@jtf19/vibecoding-kit 0.1.0

package/AGENTS.md

@@ -0,0 +1,84 @@
+# AGENTS.md
+
+本项目使用 Vibecoding Kit，为 coding agents 提供统一工作流。
+
+## 资产位置
+
+源码仓库中，workflow skills 位于 `skills/`。
+
+通过 `vibe-init` 安装到业务项目后，workflow skills 位于 `.vibecoding/skills/`。根目录只保留 `AGENTS.md` 作为 Codex / Cursor 入口。
+
+## Start Here
+
+处理开发任务前，先加载 `using-vibecoding` 并完成轻量 workflow 判断。需要本地只读辅助时，优先使用：
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "<request>" --json
+```
+
+该命令只生成入口合同、可见 skill 回执、驾驶舱和下一步建议；不执行 workflow skill、不调用 subagent、不写源码、不创建状态目录。`workflow_start.workflow_discipline_summary` 必须保持 `tiny_context`、`full_skill_injection=false`、`skill_execution_claimed=false`、`command_execution_claimed=false`、`subagent_dispatch_claimed=false`、`git_write_claimed=false`。
+
+- 不要声称已使用某个 skill，除非当前响应实际按该 skill 的目标、边界和 handoff 要求执行。
+- subagent 只有在用户明确允许、brief 完整、边界清楚时才使用。
+
+## 交互协议分层
+
+本源码仓库保留完整 workflow 表，用于维护 workflow skills、验证方法论和生成安装模板。
+
+安装到业务项目后的 `templates/AGENTS.md` 使用降级交互协议：默认轻量分流，只有风险、阶段或交接需要时才显式进入完整 workflow。
+
+## 源码仓库默认入口
+
+在本仓库处理开发任务前，先根据任务类型选择 workflow：
+
+- 新功能、产品功能、重构、架构调整：`vibe-brainstorming` -> `vibe-product-discovery`（需要时） -> `vibe-product-spec`（需要时） -> `vibe-ui-design`（需要时） -> `vibe-planning` -> `vibe-writing-plans` -> `vibe-test-driven-development` -> `vibe-executing-plans` -> `vibe-product-acceptance`（需要时） -> `vibe-verification-before-completion` -> `vibe-finishing-a-development-branch`
+- 计划包含多个潜在独立任务：`vibe-writing-plans` -> `vibe-dispatching-parallel-work` -> `vibe-test-driven-development`
+- 大改动、并行任务、风险性重构或分支收口前：`vibe-workspace-isolation` -> `vibe-writing-plans` 或 `vibe-subagent-driven-development` 或 `vibe-test-driven-development` 或 `vibe-finishing-a-development-branch`
+- 独立任务 brief 完整且用户明确允许 subagent 时：`vibe-subagent-driven-development` -> `vibe-verification-before-completion` 或 `vibe-executing-plans`
+- 明确小任务：`vibe-test-driven-development` -> `vibe-implementation` -> `vibe-verification-before-completion`
+- bug、失败、异常行为：`vibe-systematic-debugging` -> `vibe-test-driven-development` -> `vibe-implementation` -> `vibe-verification-before-completion`
+- 新增或修改 Vibecoding skill：`vibe-writing-skills` -> `vibe-writing-plans` -> `vibe-test-driven-development`
+- 审查或合并前检查：`vibe-requesting-code-review` -> `vibe-review`
+- 处理 review feedback：`vibe-receiving-code-review`
+- 上下文过长或需要交接：`vibe-context-compact`
+
+## Architecture-first coding
+
+修改源码前，先做轻量 `Architecture Decision Frame` 判断；简单任务可以用一句话完成，但不能跳过职责归属：
+
+1. `owner`：先找到拥有该职责的 owner module；不要因为文件当前打开或最近修改，就默认写进去。
+2. `layer`：标清改动属于 entry、dispatcher、command wrapper、domain core、state、validation、presentation、test/smoke、config/docs 中哪一层。
+3. `dependency direction`：依赖只能指向更低或同层稳定模块；core 不反向依赖 CLI、command、doctor、check。
+4. `data flow`：确认输入、转换、IO、输出和错误 envelope 的路径清楚，不把跨层数据回溯塞进调用方。
+5. `state lifecycle`：确认状态由谁创建、验证、消费、迁移和持久化；不在非 owner 模块临时写状态。
+6. `contract sync`：CLI 参数、JSON envelope、artifact、digest、README marker、template、doctor/runtime-check/release-check 需要同步时一并纳入范围。
+7. `blast radius`：说明影响是局部、跨模块还是触及执行链路；高风险链路先停下来确认计划。
+8. `evolution path`：新增概念、命令、验证族或 smoke 组时，优先创建/扩展具名模块，而不是扩张大文件。
+9. `complexity containment`：避免参数爆炸、万能 helper、跨 domain common、长函数和隐式共享状态。
+10. `risk class`：涉及 execution、scheduler、daemon、source apply、merge、retry、queue、lease、persistent state 时，按高风险处理并要求更强验证。
+
+## 优先规则
+
+- 本源码仓库可以使用完整 workflow；业务项目模板默认使用降级交互协议。
+- 只要有 1% 可能适用 workflow，就先判断 workflow；判断可以很轻量，但不要直接跳到实现、排查、提交或 review。
+- 用户显式规则优先；当用户规则与默认 workflow 冲突时，先说明冲突并选择不越权的最小下一步。
+- 不要声称已使用某个 skill，除非当前响应实际按该 skill 的目标、边界和 handoff 要求执行。
+- 需求模糊时先进入 `vibe-brainstorming`。
+- 产品问题、目标用户、场景或价值假设不清时，先进入 `vibe-product-discovery`。
+- 产品方向明确但缺少 PRD、用户故事、功能要求或验收标准时，先进入 `vibe-product-spec`。
+- 规格涉及界面、交互、文案、UI 状态、响应式或可访问性时，先进入 `vibe-ui-design`。
+- 已有方案需要拆解时先进入 `vibe-writing-plans`。
+- 计划包含多个潜在独立任务时，先进入 `vibe-dispatching-parallel-work` 判断并行边界和任务 brief。
+- 大改动、并行任务、风险性重构或分支收口前，先进入 `vibe-workspace-isolation` 判断是否适合原地工作。
+- 独立任务 brief 完整且用户明确允许 subagent 时，进入 `vibe-subagent-driven-development` 判断执行 gate 和 review gate。
+- 实现前先用 `vibe-test-driven-development` 明确测试或验证策略。
+- 按计划落地时使用 `vibe-executing-plans` 保留任务级验收。
+- bug 未复现或未定位根因时不要修。
+- 实现后如果存在产品规格或 UI contract，完成前先进入 `vibe-product-acceptance` 补充产品体验验收。
+- 实现完成后必须进入完成前验证。
+- 准备提交、PR 或收口时进入 `vibe-finishing-a-development-branch`。
+- 设计或修改 workflow skill 前先进入 `vibe-writing-skills` 明确边界、handoff 和同步清单。
+- 请求 review 前先进入 `vibe-requesting-code-review` 整理目标、范围和证据。
+- 处理 review feedback 时先进入 `vibe-receiving-code-review`，不要盲修。
+- review 优先输出阻塞和高风险问题。
+- 不引入第一阶段范围外的大型工具链。

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to Vibecoding Kit will be documented in this file.
+
+This project follows Semantic Versioning before 1.0 with the following interpretation:
+
+- Minor versions may introduce new workflow contracts, CLI surfaces, templates, or evidence envelopes.
+- Patch versions are for fixes, documentation improvements, and compatible release-check coverage.
+- Breaking changes before 1.0 are still called out explicitly when they affect installed layout, CLI arguments, JSON envelopes, or workflow skill contracts.
+
+## [0.1.0] - 2026-08-03
+
+### Added
+
+- Initial Vibecoding Kit source layout with workflow skills, adapters, hooks, templates, docs, examples, and local Node.js tooling.
+- `vibe` CLI wrapper for `init`, `doctor`, lifecycle, profile, and plugin packaging commands.
+- Safe governance mode as the default installed-project behavior.
+- `legacy-workflow-discipline` profile as explicit opt-in workflow discipline without hidden execution privileges.
+- Runtime, runtime-check, doctor, and release-check scripts for local evidence and release readiness.
+- Golden path and full-chain examples for team-mode and full-compliance readiness.
+
+### Security
+
+- Default boundaries prohibit hidden command execution, automatic git operations, platform API calls, real subagent dispatch, and implicit business source writes.
+
+### Open source readiness
+
+- Added Apache-2.0 licensing, contribution guidance, security policy, code of conduct, package publishing metadata, GitHub templates, and CI entry points.

package/CLAUDE.md

@@ -0,0 +1,137 @@
+# CLAUDE.md
+
+本项目使用 Vibecoding Kit。
+
+## 资产位置
+
+源码仓库中，workflow skills 位于 `skills/`。
+
+通过 `vibe-init` 安装到业务项目后，workflow skills 位于 `.vibecoding/skills/`。根目录只保留 `CLAUDE.md` 作为 Claude 入口。
+
+新会话或开发任务开始时，优先加载 `using-vibecoding`。
+
+## Start Here
+
+处理开发任务前，先加载 `using-vibecoding` 并完成轻量 workflow 判断。需要本地只读辅助时，优先使用：
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "<request>" --json
+```
+
+该命令只生成入口合同、可见 skill 回执、驾驶舱和下一步建议；不执行 workflow skill、不调用 subagent、不写源码、不创建状态目录。`workflow_start.workflow_discipline_summary` 必须保持 `tiny_context`、`full_skill_injection=false`、`skill_execution_claimed=false`、`command_execution_claimed=false`、`subagent_dispatch_claimed=false`、`git_write_claimed=false`。
+
+- 不要声称已使用某个 skill，除非当前响应实际按该 skill 的目标、边界和 handoff 要求执行。
+- subagent 只有在用户明确允许、brief 完整、边界清楚时才使用。
+
+## 交互协议分层
+
+本源码仓库保留完整 workflow 表，用于维护 workflow skills、验证方法论和生成安装模板。
+
+安装到业务项目后的 `templates/CLAUDE.md` 使用降级交互协议：默认轻量分流，只有风险、阶段或交接需要时才显式进入完整 workflow。
+
+## 源码仓库工作流
+
+新功能、产品功能、重构、架构调整：
+
+1. `vibe-brainstorming`
+2. `vibe-product-discovery`（产品问题、用户、场景或价值假设不清时）
+3. `vibe-product-spec`（需要 PRD / capability spec 时）
+4. `vibe-ui-design`（涉及界面、交互、文案、UI 状态或可访问性时）
+5. `vibe-planning`
+6. `vibe-writing-plans`
+7. `vibe-test-driven-development`
+8. `vibe-executing-plans`
+9. `vibe-product-acceptance`（存在产品规格或 UI contract 时）
+10. `vibe-verification-before-completion`
+11. `vibe-finishing-a-development-branch`
+
+计划包含多个潜在独立任务：
+
+1. `vibe-writing-plans`
+2. `vibe-dispatching-parallel-work`
+3. `vibe-test-driven-development`
+
+大改动、并行任务、风险性重构或分支收口前：
+
+1. `vibe-workspace-isolation`
+2. `vibe-writing-plans` 或 `vibe-subagent-driven-development` 或 `vibe-test-driven-development` 或 `vibe-finishing-a-development-branch`
+
+独立任务 brief 完整且用户明确允许 subagent 时：
+
+1. `vibe-subagent-driven-development`
+2. `vibe-verification-before-completion` 或 `vibe-executing-plans`
+
+明确小任务：
+
+1. `vibe-test-driven-development`
+2. `vibe-implementation`
+3. `vibe-verification-before-completion`
+
+bug、失败、异常行为：
+
+1. `vibe-systematic-debugging`
+2. `vibe-test-driven-development`
+3. `vibe-implementation`
+4. `vibe-verification-before-completion`
+
+新增或修改 Vibecoding skill：
+
+1. `vibe-writing-skills`
+2. `vibe-writing-plans`
+3. `vibe-test-driven-development`
+
+审查或合并前检查：
+
+1. `vibe-requesting-code-review`
+2. `vibe-review`
+
+处理 review feedback：
+
+1. `vibe-receiving-code-review`
+
+上下文过长或需要交接：
+
+1. `vibe-context-compact`
+
+## Architecture-first coding
+
+修改源码前，先做轻量 `Architecture Decision Frame` 判断；简单任务可以用一句话完成，但不能跳过职责归属：
+
+1. `owner`：先找到拥有该职责的 owner module；不要因为文件当前打开或最近修改，就默认写进去。
+2. `layer`：标清改动属于 entry、dispatcher、command wrapper、domain core、state、validation、presentation、test/smoke、config/docs 中哪一层。
+3. `dependency direction`：依赖只能指向更低或同层稳定模块；core 不反向依赖 CLI、command、doctor、check。
+4. `data flow`：确认输入、转换、IO、输出和错误 envelope 的路径清楚，不把跨层数据回溯塞进调用方。
+5. `state lifecycle`：确认状态由谁创建、验证、消费、迁移和持久化；不在非 owner 模块临时写状态。
+6. `contract sync`：CLI 参数、JSON envelope、artifact、digest、README marker、template、doctor/runtime-check/release-check 需要同步时一并纳入范围。
+7. `blast radius`：说明影响是局部、跨模块还是触及执行链路；高风险链路先停下来确认计划。
+8. `evolution path`：新增概念、命令、验证族或 smoke 组时，优先创建/扩展具名模块，而不是扩张大文件。
+9. `complexity containment`：避免参数爆炸、万能 helper、跨 domain common、长函数和隐式共享状态。
+10. `risk class`：涉及 execution、scheduler、daemon、source apply、merge、retry、queue、lease、persistent state 时，按高风险处理并要求更强验证。
+
+## 优先规则
+
+- 本源码仓库可以使用完整 workflow；业务项目模板默认使用降级交互协议。
+- 只要有 1% 可能适用 workflow，就先判断 workflow；判断可以很轻量，但不要直接跳到实现、排查、提交或 review。
+- 用户显式规则优先；当用户规则与默认 workflow 冲突时，先说明冲突并选择不越权的最小下一步。
+- 不要声称已使用某个 skill，除非当前响应实际按该 skill 的目标、边界和 handoff 要求执行。
+- 需求模糊时先进入 `vibe-brainstorming`。
+- 产品问题、目标用户、场景或价值假设不清时，先进入 `vibe-product-discovery`。
+- 产品方向明确但缺少 PRD、用户故事、功能要求或验收标准时，先进入 `vibe-product-spec`。
+- 规格涉及界面、交互、文案、UI 状态、响应式或可访问性时，先进入 `vibe-ui-design`。
+- 已有方案需要拆解时先进入 `vibe-writing-plans`。
+- 计划包含多个潜在独立任务时，先进入 `vibe-dispatching-parallel-work` 判断并行边界和任务 brief。
+- 大改动、并行任务、风险性重构或分支收口前，先进入 `vibe-workspace-isolation` 判断是否适合原地工作。
+- 独立任务 brief 完整且用户明确允许 subagent 时，进入 `vibe-subagent-driven-development` 判断执行 gate 和 review gate。
+- 实现前先用 `vibe-test-driven-development` 明确测试或验证策略。
+- 按计划落地时使用 `vibe-executing-plans` 保留任务级验收。
+- bug 未复现或未定位根因时不要修。
+- 实现后如果存在产品规格或 UI contract，完成前先进入 `vibe-product-acceptance` 补充产品体验验收。
+- 实现完成后必须进入完成前验证。
+- 准备提交、PR 或收口时进入 `vibe-finishing-a-development-branch`。
+- 设计或修改 workflow skill 前先进入 `vibe-writing-skills` 明确边界、handoff 和同步清单。
+- 请求 review 前先进入 `vibe-requesting-code-review` 整理目标、范围和证据。
+- 处理 review feedback 时先进入 `vibe-receiving-code-review`，不要盲修。
+
+## 边界
+
+第一阶段不使用大型 MCP、复杂 memory、完整 codebase index 或大规模 agents 编排。

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in Vibecoding Kit a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+## Our standards
+
+Positive behavior includes:
+
+- Using welcoming and inclusive language.
+- Respecting different viewpoints and experience levels.
+- Giving constructive feedback focused on the work.
+- Accepting responsibility and learning from mistakes.
+- Prioritizing the safety and usefulness of the community.
+
+Unacceptable behavior includes:
+
+- Harassment, insults, personal attacks, or sexualized language.
+- Publishing private information without explicit permission.
+- Trolling or sustained disruption of discussions.
+- Pressuring maintainers or contributors to bypass safety, review, or licensing boundaries.
+
+## Enforcement
+
+Maintainers may remove, edit, or reject comments, commits, issues, and pull requests that are not aligned with this Code of Conduct. Maintainers may also temporarily or permanently ban contributors for behavior that is inappropriate, threatening, offensive, or harmful.
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 2.1.

package/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to Vibecoding Kit
+
+Thanks for considering a contribution. Vibecoding Kit is a workflow governance toolkit for coding agents, so changes should preserve clear boundaries, explicit user approval, and verifiable evidence.
+
+## Development setup
+
+Requirements:
+
+- Node.js 18 or newer.
+- No package install is required for the current toolchain.
+
+Useful commands from the repository root:
+
+```bash
+npm run check
+npm run check:arch
+npm run check:doctor
+npm run release:fast
+npm run release:install
+```
+
+Use focused checks while developing, then run the broader checks before opening a pull request.
+
+## Architecture rules
+
+Before changing source files, identify the owner layer:
+
+- `skills/`: workflow skill content and handoff discipline.
+- `adapters/`: platform-specific adapter metadata and install guidance.
+- `hooks/`: session-start and handoff bootstrap assets.
+- `templates/`: installed-project entry templates and evidence artifacts.
+- `tools/vibe-runtime/`: runtime CLI and local evidence/state envelopes.
+- `tools/vibe-runtime-check/`: read-only contract checks.
+- `tools/vibe-release-check/`: release and smoke suites.
+- `tools/vibe-init/`, `tools/vibe-doctor/`, `tools/vibe-lifecycle/`: installation, diagnostics, and lifecycle commands.
+
+Keep dependency direction stable: runtime core must not depend on GitHub, npm publishing, CI, doctor, runtime-check, or release-check.
+
+## Pull request expectations
+
+A good pull request includes:
+
+- A narrow scope and clear owner module.
+- The user-facing reason for the change.
+- Validation commands and results.
+- Any changed contract surface: CLI flags, JSON envelopes, templates, docs, package files, or release checks.
+- A note if the change touches execution, scheduler, daemon, source apply, merge, retry, queue, lease, or persistent state.
+
+## Commit style
+
+Use concise conventional commits when possible, for example:
+
+```text
+feat(init): add platform merge preview
+fix(runtime): preserve readonly workflow boundary
+chore(release): add package boundary smoke
+```
+
+## Submodules
+
+The `fork/` directory contains reference submodules. They are research inputs, not runtime assets and not npm package contents. Do not copy third-party reference source into runtime assets. If a conclusion from a reference project is useful, document the distilled design in `docs/`, `skills/`, `adapters/`, or `tools/`.
+
+## Security-sensitive changes
+
+Changes that affect command execution, platform calls, git operations, state writes, or approval gates require stronger evidence. Prefer a small design note and targeted release-check coverage before implementation.
+
+## License
+
+By contributing, you agree that your contribution is licensed under the Apache License 2.0.

package/LICENSE

@@ -0,0 +1,67 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" or "Your" shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work.
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on or derived from the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link or bind by name to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution alone or by combination of their Contribution with the Work to which such Contribution was submitted. If You institute patent litigation against any entity alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within that NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
+
+You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort, contract, or otherwise, unless required by applicable law or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages arising as a result of this License or out of the use or inability to use the Work, even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. Do not include the brackets. The text should be enclosed in the appropriate comment syntax for the file format.
+
+Copyright 2026 Vibecoding Kit contributors
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,162 @@
+# Vibecoding Kit
+
+Vibecoding Kit 让 coding agent 以更安全、可验证的方式工作。
+
+默认体验叫 **Vibe Guided**。它是 Vibecoding Kit 的默认真实模式：让 agent 在写代码、排障、收口和处理 review feedback 时，先做轻量任务分流，再按风险选择最小合适流程，并在完成前给出验证证据。
+
+你可以把它理解成一个受控 agent 沙盒：
+
+- 你正常提需求。
+- agent 先判断任务类型和风险。
+- 小任务直接处理，完成前做最小验证。
+- 不清楚或高风险的任务先确认目标、范围、验收和验证方式。
+- bug 或失败先复现并定位根因，再修改。
+- 交付或收口先看验证证据，再判断能否交付。
+- 默认不会偷偷提交、推送、创建 PR、调用外部平台、派发 subagent 或执行隐藏任务。
+
+## 快速开始
+
+如果你只是把 Vibecoding Kit 安装到业务项目，优先使用 `npx` 从 npm 临时执行 CLI：
+
+```bash
+npx vibecoding-kit init --target ../my-project --platform cursor
+npx vibecoding-kit doctor --root ../my-project
+```
+
+`npx` 会执行发布包里的 `vibe` 命令，不会把 Vibecoding Kit 写入目标项目的依赖。
+
+平台参数：
+
+
+| 平台       | 入口文件                                 | 命令参数                  |
+| -------- | ------------------------------------ | --------------------- |
+| Claude   | `CLAUDE.md`                          | `--platform claude`   |
+| Cursor   | `AGENTS.md`                          | `--platform cursor`   |
+| Codex    | `AGENTS.md`                          | `--platform codex`    |
+| OpenCode | `.vibecoding/adapters/opencode/`     | `--platform opencode` |
+| Pi       | `.vibecoding/adapters/pi/`           | `--platform pi`       |
+| 全部       | `CLAUDE.md` + `AGENTS.md` + adapters | `--platform all`      |
+
+
+第一次安装建议先预览：
+
+```bash
+npx vibecoding-kit init --target ../my-project --platform all --dry-run
+```
+
+已有 `CLAUDE.md` 或 `AGENTS.md` 时，先看合并预览：
+
+```bash
+npx vibecoding-kit init --target ../my-project --platform auto --merge=preview
+```
+
+确认后追加 Vibecoding managed block：
+
+```bash
+npx vibecoding-kit init --target ../my-project --platform auto --merge=append
+```
+
+如果你正在维护本仓库或需要从源码运行，可以使用本地入口：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+需要只读入口判断时，可以从 Vibecoding Kit 所在位置运行：
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "帮我确认下一步" --json --root ../my-project
+```
+
+这条上手路径默认不创建 `.vibecoding-state/`，不运行隐藏任务，不写业务源码，也不做 git 写入。
+
+## 怎么使用
+
+安装后直接对 agent 提需求：
+
+```text
+帮我实现这个小功能。
+先定位这个 bug 的原因。
+帮我确认这个分支能不能交付。
+```
+
+Vibe Guided 会让 agent 按任务风险选择最小合适流程：
+
+
+| 场景              | agent 应该怎么做           |
+| --------------- | --------------------- |
+| 小任务             | 直接处理，完成前做最小验证         |
+| 新功能 / 重构        | 先确认目标、边界、验收和验证方式      |
+| bug / 失败        | 先复现并定位根因，再修改          |
+| 交付前检查           | 先看验证证据和风险，再判断能否交付     |
+| review feedback | 先分类，判断是否阻塞，再说明修复和验证路径 |
+
+## 默认模式
+
+Vibe Guided 是默认真实模式，对应安装配置里的 `automation_profile: "vibe-guided"`。
+
+它会启用这些行为约束：
+
+- 先读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，做轻量任务分流。
+- 默认只展示当前 route、下一步人工动作、验证策略或证据缺口。
+- 不把维护者 runtime stage 长表强塞给普通业务任务。
+- 不声称已经执行 workflow skill，除非当前响应真的按该 skill 的目标、边界和 handoff 要求执行。
+- 完成前先给验证证据，或明确说明无法验证。
+
+`default` 仍作为旧配置的兼容别名被接受，但新安装会写入 `vibe-guided`。
+
+## 安全边界
+
+默认边界：
+
+- 不自动提交、push、创建 PR 或 merge。
+- 不自动调用平台 API、MCP、外部网络或模型。
+- 不自动派发真实 subagent。
+- 不自动运行隐藏测试或后台 daemon。
+- 不默认写业务源码或 `.vibecoding-state/`。
+
+需要更强动作时，必须由用户明确授权，并且保留可复验的证据。允许改源码、允许运行本地命令、本地 commit、push、PR、merge 是分开的权限，不会因为进入 Vibe Guided 就自动获得。
+
+## 安装后结构
+
+业务项目默认只保留轻量入口，复杂规则放到 `.vibecoding/`：
+
+```text
+CLAUDE.md          # Claude 入口，按平台生成
+AGENTS.md          # Cursor / Codex 入口，按平台生成
+.vibecoding/
+  VIBE-CODING.md   # 完整 Vibecoding 规则
+  config.json
+  skills/
+  adapters/
+  hooks/
+```
+
+`docs/` 和 `examples/` 默认不安装；需要时使用 `--with-docs` 安装到 `.vibecoding/`。
+
+## 常用文档
+
+| 你要做什么                                  | 入口                                            |
+| -------------------------------------- | --------------------------------------------- |
+| 快速试用和安全 recipe                         | `docs/quick-recipes.md`                       |
+| 用户指南                                   | `docs/user-guide.md`                          |
+| 安装说明                                   | `docs/install.md`                             |
+| 安装 CLI 参考                              | `tools/vibe-init/README.md`、`tools/vibe-doctor/README.md` |
+| 插件打包                                   | `tools/vibe-plugin-pack/README.md`            |
+| runtime 检查和只读入口                         | `tools/vibe-runtime-check/README.md`、`tools/vibe-runtime/README.md` |
+| 团队交付最小闭环                               | `docs/team-adoption.md`、`docs/golden-path.md` |
+| evidence 填写                            | `docs/evidence-authoring.md`、`docs/ci-evidence-onboarding.md` |
+| `ok=false` 和 readiness 解读              | `docs/readiness-interpretation.md`、`docs/readiness-troubleshooting.md` |
+| 验收和发布                                  | `docs/acceptance-checklist.md`、`docs/release-guide.md` |
+| 安装体验路线                                 | `docs/install-experience-roadmap.md`          |
+| 维护 runtime、profile、release/check 和内部路线 | `docs/maintainer-guide.md`、`docs/runtime-roadmap.md`、`docs/runtime-contract.md` |
+
+## Open source
+
+- License: Apache-2.0, see `LICENSE`.
+- Contributing guide: `CONTRIBUTING.md`.
+- Security policy: `SECURITY.md`.
+- Changelog: `CHANGELOG.md`.
+- Architecture overview: `docs/architecture.md`.
+- Development guide: `docs/development.md`.

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Supported versions
+
+Vibecoding Kit is pre-1.0. Security fixes are applied to the current `main` or `master` branch and included in the next release.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a suspected vulnerability.
+
+Use GitHub private vulnerability reporting if it is enabled for the repository. If private reporting is not available yet, open a minimal public issue that says a private security contact is needed, without exploit details, secrets, payloads, or logs.
+
+Include:
+
+- Affected version or commit.
+- A minimal reproduction path.
+- Expected and observed behavior.
+- Whether the issue can trigger command execution, state writes, git operations, platform API calls, secret exposure, or hidden agent actions.
+
+## Security boundary
+
+Vibecoding Kit is designed around explicit approval and local evidence. By default it must not:
+
+- Run hidden commands or tests.
+- Call platform APIs, MCP servers, external networks, or model providers.
+- Dispatch real subagents without explicit user permission.
+- Commit, push, create pull requests, merge, tag, or modify git state.
+- Write business source or `.vibecoding-state/` unless the command explicitly permits it.
+
+Any regression in those boundaries should be treated as security-sensitive.
+
+## Dependency posture
+
+The current package has no runtime third-party npm dependencies. Keep new dependencies minimal, justified, and covered by release checks.