@jtf19/vibecoding-kit 0.1.0

package/skills/vibe-verification-before-completion/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: vibe-verification-before-completion
+description: Use before claiming work is complete, fixed, passing, ready to commit, or ready to ship.
+---
+
+# Vibe Verification Before Completion
+
+## 目标
+
+在声明完成、可交付、可提交或已修复前，先用当前回合的新鲜证据支撑结论。
+
+## Gate Contract
+
+```text
+gate_kind: completion_evidence_gate
+must_not_skip: before_claiming_complete_or_ready
+approval_required_before: completion_claim
+terminal_next_skill: vibe-finishing-a-development-branch | vibe-verification | vibe-systematic-debugging | vibe-implementation | vibe-planning | none
+review_blocker_stops_next_task: true
+completion_requires_evidence: true
+```
+
+## 适用场景
+
+- 实现完成后。
+- 修复完成后。
+- 执行计划完成后。
+- 准备提交、合并、PR 或发布前。
+- 用户询问是否完成、能否交付、是否通过。
+
+## 输入
+
+- 用户目标。
+- 修改范围。
+- 验收标准。
+- 应运行的检查。
+- 已运行的检查和输出。
+- 未运行检查及原因。
+- 已知风险。
+
+## 工作流
+
+1. 明确要证明的声明是什么。
+2. 找出能证明该声明的检查或人工验收信号。
+3. 如果源码结构发生变化，补充 Architecture Evidence：职责 owner、层级/依赖方向、数据流、状态生命周期、契约同步、影响面、风险等级、演进路径、复杂度压力和剩余架构债。
+4. 运行或引用当前回合刚得到的验证证据。
+5. 阅读输出和退出状态，不只看摘要。
+6. 区分已验证、未验证、失败和不适用。
+7. 如果证据不足，不声明完成，只说明实际状态。
+8. 证据充分后给出可交付判断。
+
+## 输出
+
+- 目标声明。
+- Architecture Evidence。
+- 已运行检查。
+- 证据。
+- 未运行检查。
+- 阻塞项。
+- 剩余风险。
+- 结论。
+
+## Architecture Evidence
+
+如果源码结构发生变化，完成声明必须补充架构证据：
+
+- `changed_files_and_responsibilities`：每个主要变更文件的职责。
+- `responsibility_owner_match`：修改是否落在正确 owner module。
+- `layer_and_dependency_direction`：层级关系和 import 方向是否没有反转。
+- `data_flow_clarity`：输入、转换、IO、输出和错误路径是否清晰。
+- `state_lifecycle_boundary`：状态创建、验证、消费、迁移是否仍在正确 owner；无状态写入时写 `none`。
+- `contract_sync`：CLI、JSON envelope、artifact、digest、README marker、doctor、runtime-check、release-check、template 或 skill 是否已同步或明确不适用。
+- `blast_radius`：影响到的命令、工具、文档、模板、测试和 release gate。
+- `risk_class`：低/中/高风险判断及原因。
+- `evolution_path`：本次结构是否让下一次同类扩展更容易。
+- `complexity_signal`：参数爆炸、反向依赖、跨 domain helper、长函数、数据流回溯是否被避免。
+- `remaining_architecture_debt`：仍存在但本轮不处理的架构债。
+
+如果架构证据不足，结论不能写 `verified`，只能写 `not verified` 或 `blocked`。
+
+## Evidence Gate
+
+完成声明必须绑定当前回合的新鲜证据。每条证据至少包含：
+
+- `category`：证据类别；至少使用 `static_check`、`test`、`manual_verification` 之一。涉及评审、TDD 或 diff coverage 时分别使用 `review`、`tdd_trace`、`diff_coverage`。
+- `source_digest`：本地证据文件、trace、review envelope 或 diff coverage envelope 的 digest；人工记录没有 digest 时写 `none` 并提供 artifact。
+- `claim`：这条证据支持的具体声明。
+- `command_or_check`：实际运行的命令、人工检查项或本地 artifact verify。
+- `exit_status`：命令退出状态；人工检查写 `manual`；未运行写 `not_run`。
+- `key_output`：能支撑结论的关键输出摘要，不写空泛描述。
+- `artifact`：相关本地产物、日志或文件路径；没有则写 `none`。
+- `freshness`：说明证据是否来自当前回合，旧证据只能作为背景，不能单独支撑完成声明。
+- `coverage`：覆盖了哪些验收项。
+- `gaps`：未覆盖项和原因。
+
+如果缺少新鲜证据、退出状态不明、输出未阅读、或验收项仍未覆盖，结论必须是 `blocked` 或 `not verified`，不能声明完成。
+
+完成声明至少要能绑定以下类别：
+
+- `static_check`：语法、lint、typecheck、release-check 或同等静态检查。
+- `test`：自动化测试、回归测试或明确的不适用证明。
+- `manual_verification`：人工验收记录、复现记录或本地观察结果。
+
+如果任务涉及评审、TDD 或 diff coverage，还必须分别绑定 `review`、`tdd_trace`、`diff_coverage`。缺任一必需类别时，结论必须是 `blocked` 或 `not verified`。
+
+如果任务进入 `legacy-workflow-discipline` closeout，还必须确认 P13 `closeout_readiness` 是否绑定 ledger、最终 review、test、diff 和 task commit readiness；缺任一项只能写 `blocked` 或 `not verified`。
+
+## 禁止事项
+
+- 不要没有新鲜证据就声明完成。
+- 不要说“应该通过”“看起来没问题”来替代验证。
+- 不要把旧验证结果当作当前结果。
+- 不要相信未复核的代理报告。
+- 不要把未运行检查包装成已验证。
+
+## 示例输出结构
+
+```text
+目标声明：
+Architecture Evidence：
+  - changed_files_and_responsibilities:
+  - responsibility_owner_match:
+  - layer_and_dependency_direction:
+  - data_flow_clarity:
+  - state_lifecycle_boundary:
+  - contract_sync:
+  - blast_radius:
+  - risk_class:
+  - evolution_path:
+  - complexity_signal:
+  - remaining_architecture_debt:
+已运行：
+证据：
+  - claim:
+    command_or_check:
+    exit_status:
+    key_output:
+    artifact:
+    freshness:
+    coverage:
+    gaps:
+未运行：
+阻塞：
+风险：
+结论：verified | not verified | blocked
+```
+
+## 下一步调用
+
+- 证据充分且无阻塞：`next_skill: vibe-finishing-a-development-branch`。
+- 证据不足但可以补验证：`next_skill: vibe-verification`。
+- 验证失败且原因不明：`next_skill: vibe-systematic-debugging`。
+- 验证失败且修复明确：`next_skill: vibe-implementation`。
+- 验收标准不清：`next_skill: vibe-planning`。
+
+## Workflow Handoff
+
+```text
+current_skill: vibe-verification-before-completion
+next_skill: vibe-finishing-a-development-branch | vibe-verification | vibe-systematic-debugging | vibe-implementation | vibe-planning | none
+reason:
+handoff:
+  goal:
+  scope:
+  key_decisions:
+  files:
+  risks:
+  acceptance:
+stop_condition:
+```

package/skills/vibe-workspace-isolation/SKILL.md

@@ -0,0 +1,158 @@
+---
+name: vibe-workspace-isolation
+description: Use before large changes, parallel work, risky refactors, or branch finishing when you need to decide whether the current workspace is safe to use in place or should be isolated first.
+---
+
+# Vibe Workspace Isolation
+
+## 目标
+
+在开始大改动、并行任务、风险性重构或分支收口前，判断当前工作区是否适合原地工作，是否已经处于可接受的隔离环境，或是否应先停止等待用户确认隔离方案。
+
+本 skill 只做工作区隔离判断、风险说明和 handoff，不自动创建 worktree，不切换分支，不修改 `.gitignore`，不清理用户变更，不接管 git 状态机。
+
+## 适用场景
+
+- 新功能、重构或架构调整预计会触及多个模块。
+- 实施计划包含多个潜在独立任务，可能需要与 `vibe-dispatching-parallel-work` 配合。
+- 当前工作区存在 staged、unstaged 或 untracked 变更，需要先判断是否会混入本批任务。
+- 分支收口、提交或 PR 前，需要确认工作区边界是否清楚。
+- 用户询问是否需要 worktree、临时分支、隔离目录或原地修改。
+
+## 输入
+
+- 当前任务目标、范围和风险等级。
+- 计划修改的文件、目录、状态或外部资源。
+- 当前 git 状态：staged、unstaged、untracked、当前分支、是否 detached。
+- 当前是否已处于隔离环境或用户指定的工作目录。
+- 用户对 worktree、分支、stash、提交和清理动作的授权边界。
+- 必须保留、禁止修改或疑似属于用户的变更。
+
+## 隔离判断
+
+### 可原地工作
+
+同时满足时，可以建议原地工作：
+
+- 任务范围小，文件边界清楚。
+- 当前工作区干净，或已有变更全部属于本批任务且边界明确。
+- 不需要并行执行多个写入同一仓库状态的任务。
+- 不涉及大规模重命名、迁移、生成物重写或发布目录变更。
+- 验证方式可以在当前目录稳定执行。
+
+### 建议隔离但需用户确认
+
+出现以下任一信号时，应建议隔离并停止等待确认：
+
+- 任务会跨多个模块、多个入口或多个平台同步修改。
+- 计划可能拆成多个并行任务，且多个任务都会写仓库内容。
+- 当前分支上有用户未收口变更，且与新任务范围可能交叉。
+- 重构、迁移、生成产物或依赖调整可能产生大量 diff。
+- 用户明确要求保护当前工作区或当前分支。
+
+### 已在可接受隔离环境
+
+如果已经处于用户指定的隔离目录、平台原生隔离环境、临时开发分支或明确的 worktree 中，并且当前变更边界清楚，可以继续规划或执行。
+
+不要因为已经在隔离环境中就再次建议创建新的 worktree。
+
+### 先收口当前工作区
+
+出现以下任一信号时，应优先进入收口，而不是开始新任务：
+
+- 当前有 staged / unstaged / untracked 混合状态，且无法归属到当前任务。
+- 当前有上一批未提交变更，用户尚未选择提交、保留或放弃。
+- 当前有临时目录、生成物或安装产物残留，可能污染后续判断。
+- 用户要求提交、PR、清理或结束当前批次。
+
+### 信息不足
+
+如果缺少 git 状态、任务范围、用户授权或当前目录来源，输出 `next_skill: none`，并列出需要补充的信息。
+
+## 工作流
+
+1. 确认任务目标、范围、风险和是否存在并行候选。
+2. 检查当前工作区边界：staged、unstaged、untracked、临时目录和当前分支状态。
+3. 判断当前是否已经在可接受的隔离环境中。
+4. 判断本任务应原地工作、建议隔离、先收口，还是停止等待更多信息。
+5. 如果建议隔离，只给出人工检查清单和用户确认问题，不执行创建、切换或清理。
+6. 输出建议后续 workflow 和 `Workflow Handoff`。
+
+## 输出
+
+必须输出：
+
+- 隔离判断：原地工作 / 建议隔离 / 已隔离可继续 / 先收口 / 信息不足。
+- 工作区状态摘要。
+- 与当前任务相关的风险。
+- 是否需要用户确认。
+- 手动隔离前检查清单。
+- 下一步 skill。
+- `Workflow Handoff`。
+
+## 手动隔离前检查清单
+
+```text
+当前分支：
+当前工作区状态：
+未提交变更归属：
+计划修改范围：
+隔离理由：
+用户是否确认：
+禁止自动动作：git worktree add / branch switch / stash / .gitignore 修改 / 清理用户文件
+```
+
+## 与其他 skill 的关系
+
+- `vibe-dispatching-parallel-work` 判断任务是否可以并行、如何写任务 brief。
+- `vibe-workspace-isolation` 判断这些任务是否应在当前工作区原地执行，或需要用户确认隔离环境。
+- `vibe-finishing-a-development-branch` 负责提交、PR、保留或清理前的交付收口。
+- `vibe-writing-plans` 负责把目标拆成可执行任务，不负责创建隔离工作区。
+
+## 禁止事项
+
+- 不要自动执行 `git worktree add`。
+- 不要自动切换分支、创建分支或移动目录。
+- 不要自动修改 `.gitignore`。
+- 不要自动 stash、commit、reset、checkout 或删除用户变更。
+- 不要自动创建 `.worktrees/`、`worktrees/` 或平台私有目录。
+- 不要把隔离判断写成所有任务的默认必经步骤。
+- 不要把建议隔离表述成已经隔离。
+- 不要引入 subagent runtime、MCP 或 agent graph。
+
+## 下一步调用
+
+- 当前任务可原地工作：`next_skill: vibe-writing-plans` 或 `next_skill: vibe-test-driven-development`。
+- 当前任务可原地工作、任务 brief 已完整且用户明确允许 subagent：`next_skill: vibe-subagent-driven-development`。
+- 当前已经在可接受隔离环境且任务还需拆解：`next_skill: vibe-writing-plans`。
+- 当前已经在可接受隔离环境、任务 brief 已完整且用户明确允许 subagent：`next_skill: vibe-subagent-driven-development`。
+- 当前已经在可接受隔离环境且验证策略可直接定义：`next_skill: vibe-test-driven-development`。
+- 当前工作区有未收口变更：`next_skill: vibe-finishing-a-development-branch`。
+- 建议创建隔离工作区但需要用户确认：`next_skill: none`。
+- 隔离判断所需信息不足：`next_skill: none`。
+
+## 示例输出结构
+
+```text
+隔离判断：
+工作区状态：
+任务风险：
+建议：
+需要用户确认：
+手动隔离前检查清单：
+下一步：
+
+## Workflow Handoff
+
+current_skill: vibe-workspace-isolation
+next_skill: vibe-writing-plans | vibe-subagent-driven-development | vibe-test-driven-development | vibe-finishing-a-development-branch | none
+reason:
+handoff:
+  goal:
+  scope:
+  key_decisions:
+  files:
+  risks:
+  acceptance:
+stop_condition:
+```

package/skills/vibe-writing-plans/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: vibe-writing-plans
+description: Use when requirements or a spec need to become an executable implementation plan before touching code.
+---
+
+# Vibe Writing Plans
+
+## 目标
+
+把已经明确的目标、规格或方案转成可执行计划，确保每个任务都有边界、依赖、验收信号和验证方式。
+
+## Gate Contract
+
+```text
+gate_kind: plan_gate
+must_not_skip: when_work_needs_executable_tasks
+approval_required_before: implementation
+terminal_next_skill: vibe-workspace-isolation | vibe-dispatching-parallel-work | vibe-test-driven-development | vibe-planning | none
+review_blocker_stops_next_task: false
+completion_requires_evidence: false
+```
+
+## 适用场景
+
+- `vibe-planning` 已明确目标和范围。
+- 用户要求把方案拆成实施计划。
+- 任务包含多个可独立交付的步骤。
+- 大改动、风险性重构或可能污染当前分支时，先进入 `vibe-workspace-isolation` 判断是否适合原地工作。
+- 任务可能适合并行时，先进入 `vibe-dispatching-parallel-work` 判断独立性和冲突边界。
+- 后续可进入 `vibe-test-driven-development`；subagent-driven development 保留为后续可选模式。
+
+## 输入
+
+- 目标或规格。
+- 当前范围和不做范围。
+- 相关文件或目录。
+- 关键决策。
+- 验收标准。
+- 平台、依赖、提交边界约束。
+
+## 工作流
+
+1. 先确认目标是否足够明确；不明确时返回 `next_skill: vibe-planning`。
+2. 先做 Architecture Decision Frame：判断职责 owner、层级/依赖方向、数据流、状态生命周期、契约同步、影响面、风险等级、演进路径、复杂度压力和验证信号。
+3. 列出会被创建或修改的文件范围。
+4. 按可独立验收的粒度拆分任务。
+5. 为每个任务写清输入、输出、依赖和验收信号。
+6. 为每个任务列出建议验证方式、预期输出标记和停止条件。
+7. 确认每个任务都绑定具体文件路径；不要只写目录或抽象模块名。
+8. 明确哪些任务可以顺序执行，哪些任务需要先判断并行边界，哪些需要先判断工作区隔离，哪些必须等待用户确认。
+9. 如果任务存在大范围改动、风险性重构或当前工作区污染风险，输出进入 `vibe-workspace-isolation` 的理由。
+10. 如果任务存在独立并行候选，输出进入 `vibe-dispatching-parallel-work` 的理由。
+11. 输出计划后进入工作区隔离判断、并行边界判断、测试或验证策略阶段。
+
+## Architecture Decision Frame
+
+计划必须说明代码归属和架构影响，而不是默认修改当前可见文件：
+
+- `responsibility_owner`：改动属于哪个职责 owner；没有 owner 时先设计新模块。
+- `layer_and_dependency_direction`：所属层级，以及依赖方向是否保持 `entry -> cli/dispatch -> command -> core -> state/check`。
+- `data_flow`：输入、转换、IO、输出和错误路径。
+- `state_lifecycle`：状态谁创建、验证、消费、迁移；没有状态写入时写 `none`。
+- `contract_sync`：CLI、JSON envelope、artifact、digest、README marker、doctor、runtime-check、release-check、template 或 skill 是否需要同步。
+- `blast_radius`：受影响的命令、工具、文档、模板、测试和 release gate。
+- `risk_class`：低风险 wrapper/helper、契约/验证中风险、执行/调度/daemon/source/merge/持久化状态高风险。
+- `evolution_path`：这次设计如何避免下一次继续复制、堆叠或扩张万能模块。
+- `complexity_pressure`：参数爆炸、反向依赖、跨 domain helper、长函数、数据流回溯等风险。
+- `architecture_signal`：用于验证架构没有退化的检查、diff 信号或人工审查点。
+
+如果计划无法识别 owner、依赖方向、状态生命周期或契约同步影响，不要进入实现；先提出模块边界或架构取舍。
+
+## 输出
+
+- 目标。
+- 文件范围。
+- Architecture Decision Frame：responsibility owner、layer/dependency direction、data flow、state lifecycle、contract sync、blast radius、risk class、evolution path、complexity pressure、architecture signal。
+- architecture artifact 引用：`architecture-design.md` 路径、digest 或 gate 复查命令。
+- delivery traceability 引用：建议输出或引用 `delivery-traceability.yaml`，把需求、产品、UI、架构、任务、测试、验收和 commit readiness 串成可复查 links；`links[].*_ref` 必须引用上游 artifact 的 `Reference Registry`、`scenarios[].id` 或 acceptance refs，避免只写无法验证的自由文本 ID。
+- implementation task registry：计划必须输出 `Implementation Task Registry`，每个任务绑定 `task_id`、`required`、`status`、`source_refs`、`expected_files` 或 `allowed_paths`、`expected_operations`、`required_scenario_refs`、`test_required`、`risk` 和 `rollback`，让后续 `diff-coverage.json` / `test-evidence.json` 能用 `task_refs` 做 deterministic completion alignment。
+- 任务列表。
+- 并行候选和顺序依赖。
+- 每个任务的验收信号。
+- 每个任务的验证命令。
+- 每个任务的预期输出标记。
+- 每个任务的停止条件。
+- 风险和阻塞。
+- 下一步 skill。
+
+## 禁止事项
+
+- 不要写 `TODO`、`TBD`、`稍后完善` 这类占位内容。
+- 不要用“完善逻辑”“优化结构”代替明确任务。
+- 不要把无法独立验收的杂项堆成一个任务。
+- 不要在需求不清时强行进入执行。
+- 不要默认启用 subagent 或 runtime 自动编排。
+
+## 示例输出结构
+
+```text
+目标：
+文件范围：
+任务：
+  - 名称：
+    范围：
+    文件：
+    依赖：
+    验收：
+    验证：
+    预期输出：
+    停止条件：
+风险：
+下一步：
+```
+
+## 下一步调用
+
+- 计划完整且可执行，并且没有工作区隔离或并行边界判断需求：`next_skill: vibe-test-driven-development`。
+- 任务存在大范围改动、风险性重构或当前工作区污染风险，需要先判断是否隔离：`next_skill: vibe-workspace-isolation`。
+- 任务存在独立并行候选，需要先判断冲突边界和任务 brief：`next_skill: vibe-dispatching-parallel-work`。
+- 需求或范围不清：`next_skill: vibe-planning`。
+- 缺少关键输入：`next_skill: none`。
+
+## Workflow Handoff
+
+```text
+current_skill: vibe-writing-plans
+next_skill: vibe-workspace-isolation | vibe-dispatching-parallel-work | vibe-test-driven-development | vibe-planning | none
+reason:
+handoff:
+  goal:
+  scope:
+  key_decisions:
+  files:
+  risks:
+  acceptance:
+stop_condition:
+```

package/skills/vibe-writing-skills/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: vibe-writing-skills
+description: Use when creating or modifying Vibecoding workflow skills to define trigger conditions, boundaries, outputs, next steps, documentation sync, and validation without introducing runtime automation.
+---
+
+# Vibe Writing Skills
+
+## 目标
+
+设计或修改 Vibecoding workflow skill 时，先明确它是否必要、负责什么、不负责什么、如何交接，以及需要同步哪些入口、文档和检查项。
+
+本 skill 只定义 skill 编写纪律，不自动生成 skill，不调用 subagent，不引入 graphviz，不实现 runtime 编排器。
+
+## 适用场景
+
+- 用户要求新增 Vibecoding skill。
+- 用户要求修改已有 skill 的职责、输出或下一跳。
+- 需要把参考项目能力沉淀为轻量 workflow 纪律。
+- 需要确认某个能力应成为独立 skill，还是合并进已有 skill。
+- 需要补齐 skill 的 handoff、验收或文档同步规则。
+
+## 输入
+
+- 目标能力或流程阶段。
+- 触发场景。
+- 与现有 `vibe-*` skill 的边界。
+- 预期输入、工作流和输出。
+- 下一跳关系。
+- 需要同步的入口、文档、工具和验收项。
+- 不做项和阶段边界。
+
+## 工作流
+
+1. 判断是否真的需要新增 skill；如果只是小范围补充，优先修改已有 skill。
+2. 定义 skill 名称、触发场景和退出条件。
+3. 明确与现有 skill 的职责边界，避免重复或调度器化。
+4. 定义输入、处理步骤、输出结构和禁止事项。
+5. 定义 `next_skill` 规则和 `stop_condition`。
+6. 列出同步清单：路由、workflow-chaining、入口文件、templates、README、authoring guide、acceptance checklist、release guide、doctor。
+7. 定义验证证据，确保新增 skill 不引入复杂 runtime 或平台私有依赖。
+
+## 输出
+
+必须输出：
+
+- skill 名称。
+- 是否新增 skill 或修改已有 skill。
+- 使用场景。
+- 职责边界。
+- 输入和输出。
+- `next_skill` 规则。
+- 同步清单。
+- 验收标准。
+- 不做项。
+- `Workflow Handoff`。
+
+## 同步清单
+
+新增或修改 workflow skill 时，默认检查：
+
+- `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`（如检查语义变化）
+
+## 禁止事项
+
+- 不要为单个项目私有习惯新增通用 skill。
+- 不要把 skill 写成复杂调度器。
+- 不要引入 graphviz、skill 自动生成器或 subagent 测试作为默认流程。
+- 不要复制参考项目的大型脚本或 prompt 资产作为 runtime 资产。
+- 不要省略 `Workflow Handoff`。
+- 不要让 `next_skill` 指向尚未实现的 workflow。
+- 不要让 doctor 做过严的内容审查，避免产生历史 skill 噪声。
+
+## 下一步调用
+
+- skill 设计明确且需要拆成实施任务：`next_skill: vibe-writing-plans`。
+- 只是小改已有 skill 且范围明确：`next_skill: vibe-test-driven-development`。
+- skill 边界、触发场景或验收不清：`next_skill: vibe-planning`。
+- 缺少关键输入：`next_skill: none`。
+
+## 示例输出结构
+
+```text
+skill 名称：
+新增或修改：
+使用场景：
+职责边界：
+输入：
+输出：
+next_skill 规则：
+同步清单：
+验收标准：
+不做项：
+
+## Workflow Handoff
+
+current_skill: vibe-writing-skills
+next_skill: vibe-writing-plans
+reason: skill 设计已明确，需要拆成可执行任务。
+handoff:
+  goal:
+  scope:
+  key_decisions:
+  files:
+  risks:
+  acceptance:
+stop_condition: none
+```

package/templates/AGENTS.md

@@ -0,0 +1,88 @@
+<!-- vibecoding:start version=0.2.0 -->
+# AGENTS.md
+
+本项目使用 Vibecoding Kit。你可以把它理解成一个受控 agent 沙盒：正常向 agent 提需求，agent 会先做轻量任务分流，再按风险选择最小合适流程，完成前绑定验证证据。
+
+默认真实模式是 **Vibe Guided**（`automation_profile: "vibe-guided"`）。`default` 是旧配置兼容别名；新安装使用 `vibe-guided`。
+
+## 你怎么用
+
+直接描述任务即可，例如：
+
+```text
+帮我实现这个小功能。
+先定位这个 bug 的原因。
+帮我确认这个分支能不能交付。
+```
+
+默认规则：
+
+- 小任务：直接处理，完成前做最小验证。
+- 不清楚或有风险的任务：先确认目标、范围、验收和验证方式。
+- bug 或失败：先复现并定位根因，再修改。
+- 交付或收口：先看验证证据，再判断能否交付。
+- review feedback：先分类，判断是否阻塞，再说明修复和验证路径。
+
+## 业务项目降级交互协议
+
+安装后的业务项目默认使用轻量产品体验：先做任务分流和证据判断，只有风险、阶段切换或交接需要时才显式进入完整 workflow。不要把源码仓库维护者路线图、runtime stage 长表或 release 内部检查强塞给普通业务任务。
+
+## 首次会话验收
+
+第一次会话只检查入口体验是否正确，不要求执行 workflow skill：
+
+- agent 先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，再做 `using-vibecoding` 轻量分流。
+- 目标不清时先澄清目标、范围和验收。
+- 输出可见下一步人工动作，而不是隐藏执行。
+- 不注入完整 skill 内容，不自动测试，不调用 subagent，不触碰 git / PR / push / merge。
+
+## Start Here Contract / Agent 入口
+
+workflow skills 位于 `.vibecoding/skills/`。处理开发任务前，先按文件路径读取 `.vibecoding/skills/using-vibecoding/SKILL.md`，并按其规则完成轻量 workflow 判断。不要只按平台原生 Skill registry 检索 `using-vibecoding`；如果该文件存在但 registry 未注册，不应提示入口缺失。
+
+Start Here Contract：入口只做轻量 route、当前人工下一步、验证策略或证据缺口；不注入完整 workflow skill 长表，不执行命令，不调用 subagent，不触碰 git。
+
+需要本地只读辅助时，可在 Vibecoding Kit 所在位置运行：
+
+```bash
+node tools/vibe-runtime/index.mjs workflow --start --prompt "<request>" --json --root <project-root>
+```
+
+摘要优先入口：先读 `workflow_start.entry_summary`。如果 `entry_summary.state_gap_is_expected=true`，说明当前请求适合先收敛目标、范围或验收，不是 runtime failure。
+
+`skill_route_registry_v1` 只用于检查 `using-vibecoding`、runtime route map、模板入口和 workflow 文档是否同步；它不授权执行、写源码、subagent、平台 API 或 git。
+
+## 入口上下文策略
+
+默认使用 `tiny_context`：只加载 `.vibecoding/skills/using-vibecoding/SKILL.md` 中的入口判断、当前人工下一步和安全边界，避免 `no_full_skill_injection_by_default` 退化。
+
+需要实现、排障或完成前验证时，可升级到 `balanced_context`：补充当前 profile、证据摘要和少量 recipe，但仍不展示完整 runtime stage 长表。
+
+`full_maintenance_context` 只给维护者显式使用，用于查看 runtime stage、release/check marker 或长期治理说明；业务项目默认不使用。
+
+判断能否交付时，先读 `completion_evidence.task_completion_summary`。只有摘要指出证据缺口时，再看 `blocked_reasons`、readiness gates 和底层 evidence detail。
+
+P61 marker：`p61_token_context_economy_v2`、`prompt_mutation=false`、`embeddings=false`、`remote_config=false`、`dynamic_tool_execution=false`、`model_invocation=false`、`command_execution=false`。
+
+## Installed Agent Experience Contract v2
+
+安装后的业务项目使用一屏可验收合同，而不是维护者 runtime stage 长表；机器可检合同 kind 为 `installed-agent-experience-contract-v2`。
+
+覆盖 prompt：`first_turn`、`continue_task`、`bug_debug`、`completion_closeout`、`review_feedback`。Stage 25 marker：`installed_business_ux_regression_pack` 要求默认 `tiny_context`、一屏轻量体验、`full_maintenance_context` 和维护者 runtime stage 长表不默认展示。
+
+固定禁止 marker：`hidden_execution=false`、`command_execution=false`、`skill_execution_claimed=false`、`subagent_dispatch_claimed=false`、`business_source_write=false`、`git_write_claimed=false`、`platform_api=false`、`model_invocation=false`。
+
+## Profile 说明
+
+默认安装后是轻量治理：`automation_profile` 使用 `vibe-guided`，`execution_profile` 使用 `manual`。这表示 agent 可以做任务分流和证据判断，但不获得自动执行、自动测试、业务源码写入或 git 写入许可。
+
+`execution-enabled` 需要用户显式配置才可用，并绑定 `controlled-local-runtime`。开启它只表示受控本地前台执行 gate 可进入 preflight / candidate / approval / allowlist / evidence audit；它不授权 source/git/subagent，不会自动写业务源码、commit、push、PR、merge、调用平台 API/model/MCP，或启动 daemon/watcher/hidden background chain。
+
+## 安全边界
+
+默认不授权自动执行命令、自动写源码、自动测试、调用 subagent、平台 API、git、push、PR 或 merge。
+
+只有用户明确允许，且 brief 完整、边界清楚时，才可以进入更强流程。
+
+完整规则见 `.vibecoding/VIBE-CODING.md`。
+<!-- vibecoding:end -->