@jtf19/vibecoding-kit 0.1.0

package/docs/install.md

@@ -0,0 +1,119 @@
+# 安装指南
+
+适合：第一次把 Vibecoding Kit 接入业务项目的用户。
+
+不适合：维护 runtime 内部实现、release check 或 workflow skill 的开发者。
+
+## 你会得到什么
+
+安装后，业务项目根目录只保留平台会读取的轻量入口：
+
+```text
+CLAUDE.md          # Claude 入口，按平台生成
+AGENTS.md          # Cursor / Codex 入口，按平台生成
+.vibecoding/
+  VIBE-CODING.md   # 完整 Vibecoding 规则
+  config.json
+  skills/
+  adapters/
+  hooks/
+```
+
+你可以把它理解成一个受控 agent 沙盒：用户正常提需求，agent 负责按风险选择最小合适的工作方式。
+
+## 快速安装
+
+如果你只是把 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 写入目标项目的依赖。
+
+如果你正在维护本仓库或需要从源码运行，可以使用本地入口：
+
+```bash
+node bin/vibe.mjs init --target ../my-project --platform cursor
+node bin/vibe.mjs doctor --root ../my-project
+```
+
+## 平台选择
+
+| 平台 | 入口文件 | 安装命令 |
+| --- | --- | --- |
+| Claude | `CLAUDE.md` | `npx vibecoding-kit init --target ../my-project --platform claude` |
+| Cursor | `AGENTS.md` | `npx vibecoding-kit init --target ../my-project --platform cursor` |
+| Codex | `AGENTS.md` | `npx vibecoding-kit init --target ../my-project --platform codex` |
+| 全部 | `CLAUDE.md` + `AGENTS.md` | `npx vibecoding-kit init --target ../my-project --platform all` |
+
+## 已有入口文件
+
+如果目标项目已有 `CLAUDE.md` 或 `AGENTS.md`，先预览：
+
+```bash
+npx vibecoding-kit init --target ../my-project --platform auto --merge=preview
+```
+
+确认无冲突后追加 managed block：
+
+```bash
+npx vibecoding-kit init --target ../my-project --platform auto --merge=append
+```
+
+Vibecoding 不会覆盖用户已有内容；只管理 `<!-- vibecoding:start -->` 到 `<!-- vibecoding:end -->` 之间的块。
+
+## 验证安装
+
+```bash
+npx vibecoding-kit doctor --root ../my-project
+```
+
+`doctor` 使用 summary-first 输出：
+
+- `Health summary` 先显示 blocking、warning 和 info/pass 数量。
+- `Next manual action` 告诉你下一步是否需要修复。
+- `Blocking` 必须先处理；`Warnings` 通常是可解释的采用差异；`Info` 是通过项。
+
+期望看到 `Result: passed`，或只有可解释的 warning。
+
+## 生命周期命令
+
+安装后可以用 lifecycle 命令预览升级、修复或卸载。它们默认是 dry-run，不会写文件：
+
+```bash
+npx vibecoding-kit update --root ../my-project --dry-run
+npx vibecoding-kit repair --root ../my-project --dry-run
+npx vibecoding-kit uninstall --root ../my-project --dry-run
+```
+
+输出会先显示 `Impact summary` 和 `Safety boundary`，再按 `[planned]`、`[info]`、`[blocking]` 标注每个动作。只有确认计划符合预期时，才使用 `--confirm`。
+
+边界：生命周期命令只处理 `.vibecoding/` managed assets 和入口文件 managed block；不会覆盖非 managed 用户内容，也不会创建或删除 `.vibecoding-state/`。
+
+## 安装后怎么试用
+
+在目标项目里向 agent 输入：
+
+```text
+帮我确认这个项目的 Vibecoding 入口是否生效。
+```
+
+或直接开始一个小任务：
+
+```text
+帮我做一个小改动，完成前给出验证方式。
+```
+
+## 安全边界
+
+默认不会自动：
+
+- 提交、push、创建 PR 或 merge。
+- 调用平台 API、MCP、外部网络或模型。
+- 派发真实 subagent。
+- 运行隐藏后台任务。
+- 写 `.vibecoding-state/`。
+
+完整规则在目标项目的 `.vibecoding/VIBE-CODING.md`。

package/docs/maintainer-guide.md

@@ -0,0 +1,197 @@
+# Vibecoding Kit Maintainer Guide
+
+
+
+本文档面向 Vibecoding Kit 维护者、release owner 和 runtime 开发者。普通安装用户只需要阅读 `README.md`、`docs/user-guide.md` 和 `docs/quick-recipes.md`。
+
+
+
+## 产品模式命名
+
+
+
+默认真实模式是 **Vibe Guided**，配置值为 `automation_profile: "vibe-guided"`。
+
+
+
+命名原则：
+
+- `vibe-guided` 是当前项目自己的默认体验名称。
+- `default` 只作为旧配置兼容别名保留，新安装不再主动写入。
+- 旧实验命名不作为产品名使用；默认真实模式统一命名为 Vibe Guided。
+- external reference 只作为体验对比目标或竞品参照，不是项目来源、复刻对象或上游依赖。
+- README 和安装后的业务项目入口不应把 external reference 关系作为主表达，避免用户误解。
+
+## Profile 与权限边界
+
+
+
+Vibecoding Kit 把“行为模式”和“能力授权”拆开维护。
+
+
+
+| Profile | 面向对象 | 说明 |
+
+| --- | --- | --- |
+
+| `vibe-guided` | 默认安装、日常业务项目 | 轻量 task routing、skill-driven gate、完成前 evidence、人工确认 |
+
+| `default` | 旧配置兼容 | 解析时归一化为 `vibe-guided` |
+
+| `legacy-workflow-discipline` | 维护者对比和更强 workflow 纪律 | 只加强 skill-first、continuous gate、handoff 和 evidence 纪律；不授权执行 |
+
+| `execution-enabled` | 明确开启受控本地前台执行 gate | 只允许进入 preflight / candidate / approval / allowlist / evidence audit；不授权源码写入、git、subagent、平台 API 或后台链路 |
+
+
+
+能力授权仍然保持独立：
+
+
+
+- source write / business source write
+
+- command execution
+
+- local commit
+
+- push / PR / merge
+
+- platform API / external network / model invocation
+
+- real subagent session
+
+- daemon / watcher / hidden background chain
+
+
+
+这些能力不能因为 `vibe-guided` 或 `legacy-workflow-discipline` 自动打开。
+
+
+
+## README 职责边界
+
+
+
+`README.md` 只承担用户入口职责：
+
+
+
+- 说明 Vibe Guided 是默认体验。
+
+- 给出最短安装路径。
+
+- 说明直接对 agent 提需求即可。
+
+- 保留安全边界和常用文档入口。
+
+- 只链接维护者文档，不展开 runtime stage、release suite、architecture baseline 或长期路线。
+
+
+
+维护者内容应放在本文和已有 L3 文档中。
+
+## P55 用户采用漏斗
+
+README 只保留简化入口；维护者仍需维护 P55 用户采用漏斗：安装前理解边界 -> 首次 dry-run/install -> 首次会话轻量分流 -> 首次本地 evidence -> 首次完成前收口。
+
+判断本地任务是否 ready 时，优先看 `completion_evidence.task_completion_summary`，再下钻 evidence detail。
+
+## P63 profile 表达兼容
+
+P63 marker：`p63_legacy_workflow_discipline_expression_v2`。默认对外表达统一为 Vibe Guided，而历史 `safe governance mode`、`opt-in workflow governance/parity mode` 和 `legacy-workflow-discipline` 文案只保留为维护者兼容检查语境。
+
+`legacy-workflow-discipline` 不等于 `execution-enabled`；`execution-enabled` 仍不授权 `subagent=false`、`model_invocation=false`、`platform_api=false`、`git_write=false`、`business_source_write=false`、`hidden_execution=false` 这些边界外动作。
+
+## 维护者文档入口
+
+
+
+- Runtime roadmap：`docs/runtime-roadmap.md`
+
+- Runtime contract：`docs/runtime-contract.md`
+
+- Runtime README：`tools/vibe-runtime/README.md`
+
+- Release guide：`docs/release-guide.md`
+
+- Release check reference：`docs/release-check-reference.md`
+
+- Maintainer validation：`docs/runtime-maintainer-validation.md`
+
+- Install experience roadmap：`docs/install-experience-roadmap.md`
+
+- Install acceptance checklist：`docs/install-acceptance-checklist.md`
+
+- Workflow chaining：`docs/workflow-chaining.md`
+
+- Skill authoring：`docs/skill-authoring-guide.md`
+
+- Acceptance checklist：`docs/acceptance-checklist.md`
+
+- Submodule guide：`docs/submodule-guide.md`
+
+- Tool docs：`tools/vibe-init/README.md`、`tools/vibe-doctor/README.md`、`tools/vibe-plugin-pack/README.md`、`tools/vibe-runtime-check/README.md`、`tools/vibe-runtime/README.md`
+
+
+
+## 常用维护者验证命令
+
+
+
+```bash
+
+npm run check
+
+npm run check:arch
+
+npm run check:doctor
+
+npm run release:fast
+
+npm run release:install
+
+npm run release:runtime:experience
+
+```
+
+
+
+不要并发运行 release suites，避免 `.tmp` 清理互相影响。
+
+
+
+## Product/UI Delivery Artifact Gates
+
+
+
+产品和 UI 交付证据链仍属于维护者索引，不进入 README 主路径。
+
+
+
+相关模板：
+
+
+
+- `templates/product-discovery.md`
+
+- `templates/product-spec.md`
+
+- `templates/ui-design-contract.md`
+
+- `templates/architecture-design.md`
+
+- `templates/delivery-traceability.yaml`
+
+- `templates/implementation-plan.md`
+
+- `templates/product-acceptance.md`
+
+- `templates/scenario-acceptance.yaml`
+
+- `templates/evidence/test-evidence.json`
+
+- `templates/evidence/diff-coverage.json`
+
+
+
+关键检查点包括 `Implementation Task Registry`、`completion --evidence-bundle --from-product-discovery`、`--from-architecture` 和 `--from-commit-readiness`。完整 full-chain 示例见 `examples/full-chain/`；最小 team-mode 示例见 `examples/golden-path/`。