@jtf19/vibecoding-kit 0.1.0

package/docs/skill-authoring-guide.md

@@ -0,0 +1,150 @@
+# Skill 编写规范
+
+## 目标
+
+保证 Vibecoding Kit 的 skill 短、硬、可执行，并能跨 Claude、Codex、Cursor 复用。
+
+## 标准结构
+
+每个 skill 使用以下结构：
+
+```text
+---
+name: skill-name
+description: Use when ...
+---
+
+# Skill Title
+
+## 目标
+
+## 适用场景
+
+## 输入
+
+## 工作流
+
+## 输出
+
+## 禁止事项
+
+## 示例输出结构
+```
+
+## 命名规范
+
+- 全部小写。
+- 单词之间用 `-`。
+- 使用明确 workflow 名称。
+- 不使用 `helper`、`general`、`best-practice` 这类宽泛名字。
+
+推荐：
+
+```text
+vibe-brainstorming
+vibe-product-discovery
+vibe-product-spec
+vibe-ui-design
+vibe-planning
+vibe-writing-skills
+vibe-writing-plans
+vibe-workspace-isolation
+vibe-subagent-driven-development
+vibe-dispatching-parallel-work
+vibe-test-driven-development
+vibe-executing-plans
+vibe-systematic-debugging
+vibe-verification-before-completion
+vibe-finishing-a-development-branch
+```
+
+不推荐：
+
+```text
+coding-helper
+smart-agent
+general-dev
+```
+
+## 内容规范
+
+每个 skill 必须说明：
+
+1. 什么时候使用。
+2. 输入是什么。
+3. 如何处理。
+4. 输出是什么。
+5. 禁止做什么。
+
+## external reference 映射 Skill 边界
+
+从 `fork/<external-reference>` 借鉴的 skill 应优先沉淀为可复用纪律，而不是复制平台 runtime。
+
+映射类 skill 必须说明：
+
+- 对应的开发阶段。
+- 与现有 `vibe-*` skill 的关系。
+- 进入和退出条件。
+- 是否允许 subagent 或自动编排。
+- 默认是否仍使用显式 `Workflow Handoff`。
+
+第一批、第二批、产品/UI 补齐和 review flow 映射 skill 保持默认显式推进，不启用 runtime 自动调用链：
+
+```text
+vibe-brainstorming
+vibe-product-discovery
+vibe-product-spec
+vibe-ui-design
+vibe-writing-skills
+vibe-writing-plans
+vibe-workspace-isolation
+vibe-subagent-driven-development
+vibe-dispatching-parallel-work
+vibe-test-driven-development
+vibe-executing-plans
+vibe-systematic-debugging
+vibe-requesting-code-review
+vibe-review
+vibe-receiving-code-review
+vibe-product-acceptance
+vibe-verification-before-completion
+vibe-finishing-a-development-branch
+```
+
+## Skill 编写同步清单
+
+新增或修改 workflow skill 前，先使用 `vibe-writing-skills` 明确触发场景、职责边界、输入输出、`next_skill`、`stop_condition` 和同步范围。
+
+默认同步范围：
+
+- `skills/using-vibecoding/SKILL.md`
+- `docs/workflow-chaining.md`
+- `CLAUDE.md`
+- `AGENTS.md`
+- `templates/CLAUDE.md`
+- `templates/AGENTS.md`
+- `README.md`
+- `docs/skill-authoring-guide.md`
+- `docs/acceptance-checklist.md`
+- `docs/release-guide.md`
+- `tools/vibe-doctor/index.mjs`
+- `tools/vibe-doctor/README.md`（如检查语义变化）
+
+`vibe-writing-skills` 只做轻量编写纪律，不引入 graphviz、skill 自动生成器、subagent 测试或 runtime 编排器。
+
+`vibe-workspace-isolation` 只做工作区隔离判断和手动确认建议，不自动创建 worktree，不切换分支，不修改 `.gitignore`，不清理用户变更。
+
+`vibe-subagent-driven-development` 只做 subagent 执行 gate、brief 要求和 review gate，不自动调用 subagent，不选择模型，不生成 review package，不引入 runtime 编排。
+
+`vibe-dispatching-parallel-work` 只做并行边界判断和任务 brief，不自动调用 subagent，不替代 `vibe-executing-plans`，不引入 agent graph 或 runtime 编排器。
+
+## 第一阶段边界
+
+第一阶段优先 workflow skill，不扩展业务域 skill。
+
+暂不加入：
+
+- 大规模 agent 编排。
+- 完整 MCP 使用说明。
+- 复杂 memory 策略。
+- 特定业务领域工作流。

package/docs/submodule-guide.md

@@ -0,0 +1,131 @@
+# Submodule 指南
+
+`fork/` 目录用于保存参考项目 submodule。它们服务于设计分析和后续演进参考，不属于 Vibecoding Kit runtime 资产。
+
+## 当前 submodule
+
+```text
+fork/distill        https://github.com/samuelfaj/distill.git
+fork/ECC            https://github.com/affaan-m/ECC.git
+fork/<external-reference>    https://github.com/obra/external reference.git
+fork/token-savior   https://github.com/Mibayy/token-savior.git
+```
+
+用途边界：
+
+- `fork/<external-reference>`：主参考，关注 skill 体系、跨平台插件结构和工作流方法论。
+- `fork/ECC`：次参考，关注 Claude Code 插件、命令、工作流和配置模式。
+- `fork/token-savior`：参考上下文压缩、召回和 token 节约理念。
+- `fork/distill`：参考命令输出压缩和总结思路。
+
+## 许可证边界
+
+Vibecoding Kit 自身采用 Apache-2.0，见根目录 `LICENSE`。
+
+`fork/` 下的 reference repositories 是 git submodule，不是 Vibecoding Kit 的 runtime dependency，也不进入 npm 发布包。它们的许可证不授予 Vibecoding Kit 对第三方源码的再分发权；如果某个参考项目启发了设计，只能把抽象后的结论沉淀到本仓库自有文档、skills、adapters 或 tools 中。
+
+当前仓库检查未在这些 submodule 根路径发现统一命名的 `LICENSE*`、`COPYING*` 或 `NOTICE*` 文件。因此开源发布时不要把 `fork/` 作为包内容或安装资产分发。
+
+## 新 clone 后初始化
+
+```bash
+git submodule update --init --recursive
+```
+
+如果只需要源码仓库本体、不需要研究参考项目，可以暂时不初始化 `fork/`。第一阶段和第二阶段首轮工具不依赖 `fork/` 内容运行。
+
+## 检查状态
+
+```bash
+git submodule status
+```
+
+常见状态：
+
+```text
+ 361c66b... fork/distill
+ ec92b52... fork/ECC
+```
+
+含义：
+
+- 前缀为空格：已初始化且工作区在父仓库记录的提交上。
+- 前缀为 `-`：未初始化。
+- 前缀为 `+`：子模块当前提交和父仓库记录不一致。
+- 前缀为 `U`：存在冲突，需要先处理 submodule 冲突。
+
+## 更新参考项目
+
+更新某个 submodule：
+
+```bash
+git -C fork/<external-reference> fetch
+git -C fork/<external-reference> checkout <commit>
+git status --short
+git diff --submodule
+```
+
+确认后在父仓库提交 gitlink 变更。
+
+不建议直接跟随远端最新分支。优先固定到明确 commit，保证分析结论和发布前检查可复现。
+
+## 发布包边界
+
+发布包不应包含 `fork/` 内容。
+
+发布包应包含：
+
+```text
+skills/
+adapters/
+hooks/
+templates/
+tools/
+docs/
+examples/
+README.md
+CLAUDE.md
+AGENTS.md
+```
+
+发布包不应包含：
+
+```text
+fork/
+.tmp/
+node_modules/
+.git/
+.cursor-local-assistant-v2/
+```
+
+`fork/` 的结论应沉淀到 `docs/`、`skills/`、`adapters/` 或 `tools/` 中，而不是把参考项目源码复制进 runtime 资产。
+
+## 与安装工具的关系
+
+`vibe-init` 不会复制 `fork/` 到业务项目。
+
+业务项目 installed layout 仍然是：
+
+```text
+CLAUDE.md
+AGENTS.md
+.vibecoding/
+  skills/
+  adapters/
+  hooks/
+  VIBE-CODING.md
+```
+
+## 发布前建议检查
+
+```bash
+git submodule status
+git check-ignore -v fork/distill fork/ECC fork/<external-reference> fork/token-savior
+node tools/vibe-doctor/index.mjs
+```
+
+期望：
+
+- `git submodule status` 能列出四个参考项目。
+- `fork/*` 不被 `.gitignore` 忽略。
+- `vibe-doctor` repo layout 检查通过。

package/docs/team-adoption.md

@@ -0,0 +1,113 @@
+# 团队采用指南
+
+适合：希望团队在常规功能交付中保留需求、计划、测试和 diff 证据的负责人。
+
+文档层级：L2 团队采用层。这里关注最小团队交付闭环，不要求一开始进入 full compliance；runtime stage、release suite 和 architecture baseline 属于 L3 维护者内容。
+
+不适合：第一次试用的个人用户。个人用户先看 `README.md` 和 `docs/install.md`。
+
+## 采用原则
+
+先用最小闭环，不要默认上 full compliance。
+
+```text
+Quickstart -> Team adoption -> Full compliance
+```
+
+团队日常功能交付通常只需要 Team adoption。
+
+## 团队采用漏斗
+
+P55 对团队的采用漏斗不是“马上 full compliance”，而是逐步增加证据密度：
+
+| 阶段 | 目标 | 最小产物 |
+| --- | --- | --- |
+| 安装前 | 让团队知道 Vibecoding 是安全边界和 evidence 约定，不是隐藏执行器 | README / install guide 约定 |
+| 首次安装 | 确认 managed block、adapter 和 doctor 都可解释 | `init --dry-run`、`doctor` 输出 |
+| 首次会话 | 让 agent 先做轻量分流，遇到不清楚任务先澄清 | 安装后的 `AGENTS.md` / `CLAUDE.md` 入口 |
+| 首次 evidence | 用最小四件套绑定目标、计划、测试和 diff | `product-spec.md`、`implementation-plan.md`、`test-evidence.json`、`diff-coverage.json` |
+| 首次收口 | 判断本地任务是否 ready，并解释 `ok=false` 是证据缺口还是失败 | `completion_evidence.task_completion_summary` |
+
+## Team adoption 最小资产
+
+```text
+product-spec.md
+implementation-plan.md
+test-evidence.json
+diff-coverage.json
+```
+
+含义：
+
+- `product-spec.md`：说明目标、范围和验收。
+- `implementation-plan.md`：说明任务、文件范围和风险。
+- `test-evidence.json`：记录用户或 CI 提供的测试结果。
+- `diff-coverage.json`：说明实际改动是否覆盖计划任务。
+
+可以从这些模板开始：
+
+```text
+templates/product-spec.md
+templates/implementation-plan.md
+templates/evidence/test-evidence.json
+templates/evidence/diff-coverage.json
+```
+
+## Starter kit 复制清单
+
+把团队最小闭环带到业务项目时，只复制这四类文件，不复制 full-chain fixture：
+
+```text
+product-spec.md              # 从 templates/product-spec.md 起草
+implementation-plan.md       # 从 templates/implementation-plan.md 起草
+test-evidence.json           # 从 templates/evidence/test-evidence.json 复制后替换真实测试结果
+diff-coverage.json           # 从 templates/evidence/diff-coverage.json 复制后替换真实 changed files
+```
+
+推荐顺序：
+
+1. 先用 `product-spec.md` 写清目标、范围和验收。
+2. 再用 `implementation-plan.md` 声明 task refs、预期文件和允许 operation。
+3. 用 `test-evidence.json` 绑定真实测试命令、退出码、时间戳、输出 digest 和 task refs。
+4. 用 `diff-coverage.json` 绑定实际变更文件、operation、digest 和 task coverage。
+5. 最后运行 completion evidence bundle，优先看 `completion_evidence.task_completion_summary`。
+
+## 快速验证示例
+
+在 Vibecoding Kit 仓库中运行：
+
+```bash
+npm run demo:golden-path
+```
+
+这个示例验证最小 team-mode readiness，不代表 full compliance。
+
+## 判断是否 ready
+
+优先看 `completion_evidence.task_completion_summary`：
+
+- `local_task_ready=true`
+- `minimum_local_evidence_missing=[]`
+
+满足这两个条件，说明 team mode 的本地任务证据已 ready。
+
+如果 `full_compliance_evidence_missing` 非空，只表示还没升级到发布审计模式，不一定是团队日常交付失败。
+
+## CI 接入
+
+团队可以先手动填写 evidence，再逐步升级到 CI 生成：
+
+- 手动填写：`docs/evidence-authoring.md`
+- CI 生成：`docs/ci-evidence-onboarding.md`
+- 排障：`docs/readiness-troubleshooting.md`
+
+## 何时升级 full compliance
+
+只有这些场景建议升级：
+
+- 高风险发布。
+- 跨团队交付。
+- 需要产品、UI、架构和验收审计。
+- 需要给 reviewer 或 release owner 完整证据包。
+
+不要为了形式完整让所有小改动都走 full compliance。

package/docs/user-guide.md

@@ -0,0 +1,108 @@
+# 用户指南
+
+适合：已经安装 Vibecoding Kit，想知道如何和 agent 协作的用户。
+
+文档层级：L1 用户入口层。这里只解释日常怎么提需求、agent 什么时候会反问、默认不会做什么；团队 evidence、runtime stage 和 release 治理属于 L2/L3 文档，只有需要时再读。
+
+核心心智：Vibecoding Kit 是一个受控 agent 沙盒。你正常提需求，agent 按风险决定是否直接做、先澄清、先排查或先验证。
+
+## 第一次使用路径
+
+按 P55 用户采用漏斗，第一次不要从 runtime stage 或 release gate 开始。按这五步走：
+
+1. 安装前：先确认默认安全边界，知道 agent 不会自动提交、push、创建 PR、调用平台 API 或派发 subagent。
+2. 首次安装：先 dry-run，再 doctor，确认将写入的是 managed assets。
+3. 首次会话：直接向 agent 提需求；如果目标不清，agent 应先澄清而不是直接实现。
+4. 首次 evidence：团队任务再准备 product spec、implementation plan、test evidence 和 diff coverage。
+5. 首次收口：完成前先看验证证据和 `completion_evidence.task_completion_summary`，不要把 `ok=false` 直接当系统失败。
+
+## 你只需要这样提需求
+
+### 小任务
+
+```text
+帮我把这个按钮文案改成“保存”。
+```
+
+agent 应该：
+
+- 找到职责归属。
+- 做最小修改。
+- 完成前说明验证方式或验证结果。
+
+### 新功能或重构
+
+```text
+给设置页加一个导出配置功能。
+```
+
+agent 应该先确认：
+
+- 目标是什么。
+- 范围包含哪些文件或模块。
+- 验收标准是什么。
+- 用什么方式验证。
+
+如果需求很清楚，agent 可以直接给出小计划并实现；如果不清楚，应该先问关键问题。
+
+### bug 或失败
+
+```text
+这个功能不工作，帮我排查。
+```
+
+agent 应该：
+
+- 先复现或收集证据。
+- 定位根因。
+- 再修改。
+- 修改后验证同一条失败路径。
+
+不要在根因不清时直接大范围改代码。
+
+### 交付前检查
+
+```text
+实现完成了，帮我确认能不能交付。
+```
+
+agent 应该优先看验证证据：
+
+- 测试或静态检查是否通过。
+- 是否有未解释的 diff。
+- 是否存在风险或阻塞。
+- 是否需要人工确认 git、PR 或发布动作。
+
+## agent 什么时候会反问
+
+通常是这些情况：
+
+- 目标、范围或验收不清。
+- 任务可能影响架构、状态、数据流或发布边界。
+- 需要调用 subagent、平台 API、git、PR 或其它高风险动作。
+- 现有证据不足以判断能否交付。
+
+## 你不需要一开始学习什么
+
+新用户不需要先理解：
+
+- runtime stage。
+- evidence bundle 细节。
+- digest。
+- workflow handoff 结构。
+- release check 全量清单。
+- subagent 调度协议。
+
+这些是团队采用或维护者内容，只有任务需要时再看。
+
+## 默认安全边界
+
+默认不自动：
+
+- 提交、push、创建 PR 或 merge。
+- 调用平台 API、MCP、外部网络或模型。
+- 派发真实 subagent。
+- 运行隐藏后台任务。
+- 写业务源码之外的状态目录。
+
+如果你需要这些动作，明确授权并要求 agent 说明风险和验证方式。