bb-spec

本地 ultrareview——多代理、对抗验证、只读的 PR 级 review；默认 base=main；并发 5 个 finder（质量/安全/简洁/鲁棒性/文档同步），每条 🔴/🟡 发现交 3 个独立怀疑视角对抗验证、多数决去留；可选追加本次 review 重点，注入每个 finder 优先关注（不替代其他维度）。触发：/review、给当前分支做深度审查、PR 前 ultrareview。跳过：不在 git 仓库、当前分支=base。

产出修订（诊断→定向修正→回归验证）——对 spec→plan→exec 偏差做根因归类：spec-defect / impl-defect / requirement-change；先诊断再修正、改代码必先 Red 测试、最小影响只改必须改的层；已完成 plan 是历史审计快照禁止回改；启动先 worktree 感知定位修复现场（主仓库停在 main 时自动定位到进行中的 worktree）。触发：/revise、有 bug、结果不对、和预期不符、产出需要优化、review 发现违规需修复。跳过：纯新增需求（→/spec→/plan）、还没有 spec/plan/代码可对照。

本地 ultrareview——跨模型、多代理、对抗验证、只读的 PR 级 review（依赖 Workflow 工具，Claude Code ≥2.1.154）；默认 base=main；并发 6 个 finder（质量/安全/简洁/鲁棒性/文档同步/Codex 跨模型），每条 🔴/🟡 发现交 3 个独立怀疑视角对抗验证、多数决去留；可选追加本次 review 重点，注入每个 finder 优先关注（不替代其他维度）。触发：/review、给当前分支做深度审查、PR 前 ultrareview。跳过：无 Workflow 工具、不在 git 仓库、当前分支=base。

产出修订（诊断→定向修正→回归验证）——对 spec→plan→exec 偏差做根因归类：spec-defect / impl-defect / requirement-change；先诊断再修正、改代码必先 Red 测试、最小影响只改必须改的层；已完成 plan 是历史审计快照禁止回改；启动先 worktree 感知定位修复现场（主仓库停在 main 时自动定位到进行中的 worktree）。触发：/revise、有 bug、结果不对、和预期不符、产出需要优化、review 发现违规需修复。跳过：纯新增需求（→/spec→/plan）、还没有 spec/plan/代码可对照。

Git 开发流程纪律——禁 main 直接提交；新任务前扫工作区根，有 workspace 标记走多 repo 工作区，否则 `question` 工具 询问 worktree（默认）或切分支；worktree 一律落 `~/.bb-spec/worktrees/` 下、禁嵌套当前 repo / 禁放 sibling 目录；本地 commit 不立即 push、整功能验证完才推；合并后清理本地+远程。触发：开始改代码、提到开分支、要求 commit/push/开 PR、PR 合并后清理。跳过：纯咨询/阅读、极小打字纠错。

前端技术栈强制约束——默认 Vue 3 + TS + Vite + Tailwind；bun 是默认包管理器（新项目强制），既有项目跟随 lockfile 不迁移。触发：新建前端项目；编辑 package.json/vite.config/tailwind.config/.vue/.ts/.tsx；用户提到前端/vue/vite/tailwind。跳过：纯后端/CLI/工具项目；用户明确说用 React/Nuxt/Svelte 等。

PRD 头脑风暴与文档化——质疑→发散→收敛→产出 PRD；每个需求一个目录（不论大小）：OVERVIEW.md（背景/目标/子需求索引/整体端到端验证路径）+ 一份或多份小巧子需求文档（用户故事/用例/验收/子验证路径）+（如有）GLOSSARY.md 术语增量，互不引用、便于 agent 按需读取；术语只读复用 spec/GLOSSARY.md 权威源、新术语/新别名与用户对齐后随目录交付；写入 .bb-spec/docs/prd/ 供 /spec 消费，禁写技术方案。触发：/prd、头脑风暴需求、把想法整理成需求文档、拆解需求、写个 PRD。跳过：已有 spec 想改细节（→/revise）、纯技术方案讨论、要写实施计划（→/plan）。

全仓 spec/文档/代码一致性维护——扫描仓库内 spec、README、AGENTS.md/CLAUDE.md、plan 与代码，找出描述与实现的漂移；默认改 spec/文档让其追平代码现态，代码明显违背硬约束或存在不合理设计时停下用 `question` 工具 请用户裁决再改代码；落盘前汇总展示、过程中 INDEX 同步维护。触发：/doc-update、文档和代码不一致、spec 跟代码对不上、批量同步 spec 与现状、维护一下文档。跳过：还没有 spec 可对照（→/spec）、单点 bug 或定向修复（→/revise）、纯新增需求（→/spec→/plan）。

把一个或多个远程仓库 clone 到本地并落 .bb-spec.yaml——先 `question` 工具 询问「单 repo 还是多 repo 工作区」+「base_dir 用默认还是自定义」；多 repo 模式建统一父目录 + 各成员独立 clone（不嵌套）+ 可选生成 workspace 根文件；落盘后写入 .bb-spec.yaml（base_dir 字段）。触发：clone 一下、把项目拉下来、初始化本地副本、新机器拉代码、接入 bb-spec 工作流。跳过：仓库已存在于目标路径（应走 git pull / 重置而非重新 clone）、纯私有 fork 临时实验（用裸 git clone 更轻）。

推送本地代码到远程并开 PR 全流程——识别仓库→确认分支（worktree 模式自动定位目标分支）→跑全量测试→提交未暂存改动（禁 git add .）→若存在 spec INDEX.md 则 subagent 比对 spec 跑分支规范自查（违规走 /revise 循环复审）+起草 6 段 PR 描述→推送→创建 PR（origin+upstream 双 remote 时先问合并对象、默认 origin/main）→清理本地与远程。触发：push 一下、提个 PR、代码推上去、准备发 PR、开 PR 前自查、对照规范看分支。跳过：未本地验证完成的功能、main/master 上无新提交。

读 spec + 项目代码结构产出函数级实施计划——启动即进入只读对齐、方案获批后才落盘到 .bb-spec/docs/plan/<日期>.<主题>/；启动先 worktree 感知定位 plan 现场（主仓库停在 main 时自动定位到进行中的 worktree）；过程式只到函数级，声明式产物（DDL/API 契约/配置）必须内联完整成品。触发：/plan、生成实施计划、怎么落地这些 spec。跳过：还没 spec（→/spec）、spec 无变更。

需求拆解与文档化——通过对话「澄清→拆解→文档化」把模糊需求拆为一文一规则、≤100 行/份、互不重叠的小规则 spec，落盘 .bb-spec/docs/spec/；启动即进入只读对齐、方案获批后才写；INDEX.md 汇总索引、GLOSSARY.md 术语权威源仅由本 skill 维护（合入 PRD 增量、按需增补多语言别名）、禁跨文档引用、每文档结尾必有可测试的具体例子。触发：/spec、整理需求、把功能写成 spec、需求拆解、PRD 出来后要拆规则。跳过：还没想清楚要解决什么问题（→/prd）、已有 spec 想改细节（→/revise）。

后端 API e2e 验证——Docker 整栈拉起→md 用例渲染为单文件 TS runner→`bun run` 顺序跑完→报告与 /revise 闭环；时间敏感规则（token 过期 / 订单超时 / 积分过期）经协议契约 /test/advance-time、/test/backdate、/test/trigger-job 测，应用侧用什么语言/库实现自选；零 subagent、零并发；跑完无条件 docker compose down -v。触发：/test-api、跑后端接口测试、API e2e 验收、验证后端业务流。跳过：Docker 不可用、Bun 不可用、应用未暴露 /test/healthz 协议。

网页项目全量交互验证——Docker 整栈拉起→经浏览器 MCP（playwright/chrome-devtools）逐个跑完 webview 测试用例；每用例派隔离串行 subagent，主上下文只留 verdict 摘要；全程零并发；跑完无条件 docker compose down -v；失败转 /revise。触发：/test-webview、跑网页交互测试、端到端验证网页、webview 验收。跳过：无可用 HTTP 网页服务、无浏览器 MCP、Docker 不可用。

读 spec + 项目代码结构产出函数级实施计划——启动即 EnterPlanMode 只读对齐、批准后才落盘到 .bb-spec/docs/plan/<日期>.<主题>/；启动先 worktree 感知定位 plan 现场（主仓库停在 main 时自动定位到进行中的 worktree）；过程式只到函数级，声明式产物（DDL/API 契约/配置）必须内联完整成品。触发：/plan、生成实施计划、怎么落地这些 spec。跳过：还没 spec（→/spec）、spec 无变更。

REST API 设计规范——URL 用复数+kebab、HTTP 方法/状态码语义化、单资源直返不包 data、集合带 items/meta/links 分页、错误码 A-BBB-CCCC 结构化、版本管理与限流。触发：设计/审查 API 端点与契约、实现分页/过滤/排序、设计错误响应、规划 API 版本。跳过：GraphQL/gRPC/事件流（非 REST）、内部 RPC 协议、纯前端路由。

认证与会话约束（authN，不含 authZ）——双 token、refresh 原地轮换 + 重放即吊销、滑动续期、密码 argon2id。触发：实现/设计登录注册、token 签发/刷新/校验、会话或设备管理、密码哈希、登出/吊销、前端 token 携带与刷新。跳过：权限判定（→authz-constraints）、第三方 SSO 托管、与认证无关的业务端点。

授权（authZ）约束——默认拒绝/fail-close；后端必校、前端权限仅 UX；集中决策禁散落 `if role==`；两级检查 = 角色/权限 + 资源 ownership。触发：设计/实现权限校验、角色或权限模型、资源 ownership、多租户隔离、管理员鉴权。跳过：身份认证（→auth-constraints）、纯公开资源、与权限无关的业务逻辑。

后端配置载体三分——env/secret 装启动必需且不热更、yaml/configmap 装可热更且有默认值、DB+API 装业务方可改的动态配置；核心凭据默认只能 secret/KMS，下沉 DB 必须 envelope encryption；热更失败保留旧值 + 告警禁崩溃。触发：设计/实现配置加载、密钥存储、热更机制、新增 env/yaml/DB 配置项、k8s secret/configmap 编排。跳过：配置加载后的运行时治理（→service-constraints）、可观测性脱敏（→observability-constraints）。

关系型数据库 schema 与访问约定——UUIDv7 应用层主键；`deleted` 微秒时间戳软删 + UNIQUE 联合；created_at/updated_at 由 DB 管理；全链路 UTC。触发：编写/修改 .sql、migration、DDL；设计表结构或数据模型。跳过：非关系型存储（Redis/MongoDB/ES）、不动 schema 的查询调优、代码生成物。

Go 后端全生命周期规范——统一三层 handler→service→repository（禁 manager/facade/usecase）；事务只在 service；禁过度抽象、禁单实现 interface、禁过渡方案。触发：编辑 .go/go.mod/go.sum；写 Go 项目的文档/PRD/规划/设计/review。跳过：vendor、代码生成物（*_gen.go/protobuf）、非 Go 项目。

Go 测试惯用法（配合 tdd-workflow）——测试文件必须 1:1 对应实现文件（foo_test.go 必有 foo.go）；默认 table-driven + t.Run 子测试；独立测试 t.Parallel；benchmark/fuzz 用 testing 内置工具。触发：编写/审查 Go 函数或方法、新增 *_test.go、补充测试覆盖、创建 benchmark/fuzz test。跳过：生成代码、vendor、纯配置、非 Go 项目。

可观测性约束（日志/链路/指标）——三信号一处装配 + OTel 统一标准；JSON 日志 + trace_id 从 ctx 自动注入（无 trace 输出空串）；指标 `<domain>_<noun>_<unit>` + label 基数有限；body 凭证脱敏。触发：搭建/修改日志/链路/指标、新增指标或日志字段、接入 OTel/OTLP、设计日志级别或告警。跳过：前端埋点/RUM、纯三方托管 APM。

后端服务运行时治理——启动 fail-fast；优雅生命周期（SIGTERM→排空→超时强退→LIFO 释放）；非幂等写经幂等键；跨进程必设超时、重试仅幂等且退避。触发：启动/关闭、健康检查、写幂等、下游超时/重试、错误传播。跳过：配置载体与密钥分层（→config-constraints）、代码风格（→golang-constraints）、API 契约（→api-design）、可观测性（→observability）。

跨语言通用代码纪律——默认不写注释，仅 WHY 非显然时写；禁 spec 溯源/权威源复述/跨文件弱引用/时间性状态/表态口号/测试文件头模板/boilerplate 自证；禁未要求的功能/抽象/防御、外科手术式改动、反历史包袱。触发：编写或审查实现/测试代码；被 impl-engineer/test-engineer/spec-reviewer 及 /revise 轻量修复显式加载。跳过：纯文档、纯配置、生成代码、vendor/node_modules。

TDD 跨语言通用纪律——强制 Red-Green-Refactor：写失败测试→最小实现通过→测试保护下重构；新增/修改/删除三类变更均先动测试再动实现。触发：新增/修改/删除业务逻辑源文件（.go/.py/.ts/.tsx/.vue/.js/.rs/.java/.kt）、用户提到 TDD/写测试。跳过：纯 struct/interface/常量定义、生成代码、纯文档、纯配置、vendor/node_modules。

依赖引入与版本选择策略——官方库/标准库优先；新增第三方库必须先询问用户获同意；写版本号前必经官方渠道验证最新版，禁凭训练记忆。触发：编辑 package.json/go.mod/Cargo.toml/Dockerfile/CI workflow/Helm/Terraform 等钉死版本号的文件、新增拉新包的 import、用户要求升级/加库/bump/更新 Actions。跳过：仅改本地代码、仅删依赖、用户已指定具体版本。

前端工程约定（与 vue-constraints 互补）——env 全公开禁放 secret；统一 client 处理鉴权头/错误码/token 刷新；A-BBB-CCCC 错误码请求层单点解析集中映射 UI；路由守卫仅 UX；Pinia 只放共享态。触发：搭建请求层、路由守卫、Pinia store、表单校验、API 错误映射、前端环境变量。跳过：技术栈选型（→vue-constraints）、纯样式、与工程约定无关的组件逻辑。

三 Agent 隔离执行 plan——Test→Impl→Review 串行，三方各只看各的输入互不可见；每步立即持久化 PROGRESS.md，跨会话/新会话后从断点续接；启动先 worktree 感知定位执行现场（主仓库停在 main 时自动定位到进行中的 worktree）；commit 不自动 push、main 分支禁自动 commit。触发：/exec、开始实施 plan、继续执行 plan、从断点继续、按 plan 把代码做出来。跳过：还没 /plan 产出实施计划、纯调研/方案讨论、要改 spec 或 plan 本身（→/revise）。

推送本地代码到远程并开 PR 全流程——识别仓库→确认分支（worktree 模式自动定位目标分支）→跑全量测试→提交未暂存改动（禁 git add .）→若存在 spec INDEX.md 则 subagent 比对 spec 跑分支规范自查（违规走 /revise 循环复审）+起草 6 段 PR 描述→推送→创建 PR（origin+upstream 双 remote 时先问合并对象、默认 origin/main）→清理本地与远程。触发：push 一下、提个 PR、代码推上去、准备发 PR、开 PR 前自查、对照规范看分支。跳过：未本地验证完成的功能、main/master 上无新提交。

三 Agent 隔离执行 plan——Test→Impl→Review 串行，三方各只看各的输入互不可见；每步立即持久化 PROGRESS.md，跨会话/`/clear` 后从断点续接；启动先 worktree 感知定位执行现场（主仓库停在 main 时自动定位到进行中的 worktree）；commit 不自动 push、main 分支禁自动 commit。触发：/exec、开始实施 plan、继续执行 plan、从断点继续、按 plan 把代码做出来。跳过：还没 /plan 产出实施计划、纯调研/方案讨论、要改 spec 或 plan 本身（→/revise）。

网页项目全量交互验证——Docker 整栈拉起→经浏览器 MCP（playwright/chrome-devtools）逐个跑完 webview 测试用例；每用例派隔离串行 subagent，主上下文只留 verdict 摘要；全程零并发；跑完无条件 docker compose down -v；失败转 /revise。触发：/test-webview、跑网页交互测试、端到端验证网页、webview 验收。跳过：无可用 HTTP 网页服务、无浏览器 MCP、Docker 不可用。

PRD 头脑风暴与文档化——质疑→发散→收敛→产出 PRD；每个需求一个目录（不论大小）：OVERVIEW.md（背景/目标/子需求索引/整体端到端验证路径）+ 一份或多份小巧子需求文档（用户故事/用例/验收/子验证路径）+（如有）GLOSSARY.md 术语增量，互不引用、便于 agent 按需读取；术语只读复用 spec/GLOSSARY.md 权威源、新术语/新别名与用户对齐后随目录交付；写入 .bb-spec/docs/prd/ 供 /spec 消费，禁写技术方案。触发：/prd、头脑风暴需求、把想法整理成需求文档、拆解需求、写个 PRD。跳过：已有 spec 想改细节（→/revise）、纯技术方案讨论、要写实施计划（→/plan）。

需求拆解与文档化——通过对话「澄清→拆解→文档化」把模糊需求拆为一文一规则、≤100 行/份、互不重叠的小规则 spec，落盘 .bb-spec/docs/spec/；启动即 EnterPlanMode 只读对齐、批准后才写；INDEX.md 汇总索引、GLOSSARY.md 术语权威源仅由本 skill 维护（合入 PRD 增量、按需增补多语言别名）、禁跨文档引用、每文档结尾必有可测试的具体例子。触发：/spec、整理需求、把功能写成 spec、需求拆解、PRD 出来后要拆规则。跳过：还没想清楚要解决什么问题（→/prd）、已有 spec 想改细节（→/revise）。

全仓 spec/文档/代码一致性维护——扫描仓库内 spec、README、CLAUDE.md、plan 与代码，找出描述与实现的漂移；默认改 spec/文档让其追平代码现态，代码明显违背硬约束或存在不合理设计时停下用 AskUserQuestion 请用户裁决再改代码；落盘前汇总展示、过程中 INDEX 同步维护。触发：/doc-update、文档和代码不一致、spec 跟代码对不上、批量同步 spec 与现状、维护一下文档。跳过：还没有 spec 可对照（→/spec）、单点 bug 或定向修复（→/revise）、纯新增需求（→/spec→/plan）。

把一个或多个远程仓库 clone 到本地并落 .bb-spec.yaml——先 AskUserQuestion 询问「单 repo 还是多 repo 工作区」+「base_dir 用默认还是自定义」；多 repo 模式建统一父目录 + 各成员独立 clone（不嵌套）+ 可选生成 workspace 根文件；落盘后写入 .bb-spec.yaml（base_dir 字段）。触发：clone 一下、把项目拉下来、初始化本地副本、新机器拉代码、接入 bb-spec 工作流。跳过：仓库已存在于目标路径（应走 git pull / 重置而非重新 clone）、纯私有 fork 临时实验（用裸 git clone 更轻）。

跨语言通用代码纪律——默认不写注释，仅 WHY 非显然时写；禁 spec 溯源/权威源复述/跨文件弱引用/时间性状态/表态口号/测试文件头模板/boilerplate 自证；禁未要求的功能/抽象/防御、外科手术式改动、反历史包袱。触发：编写或审查实现/测试代码；被 impl-engineer/test-engineer/spec-reviewer 及 /revise 轻量修复显式加载。跳过：纯文档、纯配置、生成代码、vendor/node_modules。

Git 开发流程纪律——禁 main 直接提交；新任务前扫工作区根，有 workspace 标记走多 repo 工作区，否则 AskUserQuestion 询问 worktree（默认）或切分支；worktree 一律落 `~/.bb-spec/worktrees/` 下、禁嵌套当前 repo / 禁放 sibling 目录；本地 commit 不立即 push、整功能验证完才推；合并后清理本地+远程。触发：开始改代码、提到开分支、要求 commit/push/开 PR、PR 合并后清理。跳过：纯咨询/阅读、极小打字纠错。

关系型数据库 schema 与访问约定——UUIDv7 应用层主键；`deleted` 微秒时间戳软删 + UNIQUE 联合；created_at/updated_at 由 DB 管理；全链路 UTC。触发：编写/修改 .sql、migration、DDL；设计表结构或数据模型。跳过：非关系型存储（Redis/MongoDB/ES）、不动 schema 的查询调优、代码生成物。

后端 API e2e 验证——Docker 整栈拉起→md 用例渲染为单文件 TS runner→`bun run` 顺序跑完→报告与 /revise 闭环；时间敏感规则（token 过期 / 订单超时 / 积分过期）经协议契约 /test/advance-time、/test/backdate、/test/trigger-job 测，应用侧用什么语言/库实现自选；零 subagent、零并发；跑完无条件 docker compose down -v。触发：/test-api、跑后端接口测试、API e2e 验收、验证后端业务流。跳过：Docker 不可用、Bun 不可用、应用未暴露 /test/healthz 协议。