From f8129bc6394a03a2aedeb498122b4e578732c922 Mon Sep 17 00:00:00 2001 From: dafang Date: Fri, 19 Jun 2026 13:50:34 +0800 Subject: [PATCH] feat: add roadmap and design review gates --- README.en.md | 4 +- README.md | 4 +- SKILL_CATALOG.en.md | 8 +- SKILL_CATALOG.md | 8 +- WORKFLOW.en.md | 7 +- WORKFLOW.md | 7 +- cs-feat-design-review/SKILL.md | 261 ++++++++++++++++++ cs-feat-design-review/agents/openai.yaml | 4 + .../scripts/detect-review-agent.py | 141 ++++++++++ cs-feat-design/SKILL.md | 32 ++- cs-feat-design/reference.md | 6 +- cs-feat/SKILL.md | 15 +- cs-onboard/reference/shared-conventions.md | 12 +- cs-onboard/reference/system-overview.md | 8 +- cs-roadmap-impl-goal/SKILL.md | 38 +-- cs-roadmap-impl-goal/agents/openai.yaml | 2 +- cs-roadmap-review/SKILL.md | 257 +++++++++++++++++ cs-roadmap-review/agents/openai.yaml | 4 + .../scripts/detect-review-agent.py | 141 ++++++++++ cs-roadmap/SKILL.md | 26 +- cs-roadmap/reference.md | 8 +- cs/SKILL.md | 8 +- 22 files changed, 938 insertions(+), 63 deletions(-) create mode 100644 cs-feat-design-review/SKILL.md create mode 100644 cs-feat-design-review/agents/openai.yaml create mode 100755 cs-feat-design-review/scripts/detect-review-agent.py create mode 100644 cs-roadmap-review/SKILL.md create mode 100644 cs-roadmap-review/agents/openai.yaml create mode 100755 cs-roadmap-review/scripts/detect-review-agent.py diff --git a/README.en.md b/README.en.md index cde2d27..f8fe9d3 100644 --- a/README.en.md +++ b/README.en.md @@ -12,7 +12,7 @@ Tired of OpenSpec's flimsiness, Oh-My-OpenAgent's over-engineering, and Superpow

Status - Skills + CodeStable Skills License

@@ -106,7 +106,7 @@ CodeStable models real coding work as **6 entities** and **3 flows**. | Flow | Key skill chain | Notes | |------|------------|------| -| **Feature delivery** | `cs-feat` → `cs-feat-design` → `cs-feat-impl` → `cs-feat-accept` | Think it through → integrated design → step-by-step coding → acceptance. Whatever order suits you | +| **Feature delivery** | `cs-feat` → `cs-feat-design` → `cs-feat-design-review` → `cs-feat-impl` → `cs-feat-review` → `cs-feat-qa` → `cs-feat-accept` | Think it through → design review → step-by-step coding → code review → QA → acceptance | | **Issue fixing** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | Tell AI what's wrong → AI finds the root cause → AI fixes precisely | | **Refactoring** | `cs-refactor` (beta) | Architectural rot doesn't happen overnight. AI assists, but **humans refactor**. Still iterating — feedback welcome | diff --git a/README.md b/README.md index ff40390..ad3eebc 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@

Status - Skills + CodeStable Skills License

@@ -107,7 +107,7 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 | 流程 | 关键技能链 | 说明 | |------|------------|------| -| **特性引入** | `cs-feat` → `cs-feat-design` → `cs-feat-impl` → `cs-feat-accept` | 想清楚 → 综合架构设计 → 逐步编码 → 验收测试。各位程序员怎么顺手怎么来 | +| **特性引入** | `cs-feat` → `cs-feat-design` → `cs-feat-design-review` → `cs-feat-impl` → `cs-feat-review` → `cs-feat-qa` → `cs-feat-accept` | 想清楚 → 方案审查 → 逐步编码 → 代码审查 → QA → 验收闭环 | | **问题修改** | `cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` | 跟 AI 说哪里有问题 → 让 AI 分析根因 → 让 AI 定点修复 | | **代码重构** | `cs-refactor` (beta) | 软件架构腐化不是一蹴而就的。AI 辅助重构，但**终归是人在重构**——还在迭代中，欢迎赐教 | diff --git a/SKILL_CATALOG.en.md b/SKILL_CATALOG.en.md index 48c002e..7721955 100644 --- a/SKILL_CATALOG.en.md +++ b/SKILL_CATALOG.en.md @@ -7,11 +7,15 @@ | Requirement and architecture | `cs-req` | Curate and accumulate raw requirement docs | | Requirement and architecture | `cs-arch` | Draft or update architecture docs under `codestable/architecture/` | | Roadmap | `cs-roadmap` | Plan big work up front: high-level design, interface contracts, sub-feature breakdown | -| Roadmap | `cs-roadmap-impl` | Advance the next executable item in an existing roadmap, initialize its feature, and hand off to design / impl / accept | +| Roadmap | `cs-roadmap-review` | Independent planning review gate before human roadmap approval | +| Roadmap | `cs-roadmap-impl-goal` | Turn an approved roadmap into a runnable goal that executes impl / review / QA / accept per feature | | Discussion entry | `cs-brainstorm` | Triage fuzzy ideas: direct design, feature brainstorm, or roadmap | | Feature flow | `cs-feat` | Sub-flow entry for new features | | Feature flow | `cs-feat-design` | Draft `{slug}-design.md` as the single input for what follows | +| Feature flow | `cs-feat-design-review` | Independent feature design review gate before human approval | | Feature flow | `cs-feat-impl` | Code in the order the design lays out | +| Feature flow | `cs-feat-review` | Read-only code review gate after implementation | +| Feature flow | `cs-feat-qa` | Local QA verification gate after code review | | Feature flow | `cs-feat-accept` | Verify implementation against the design and close the loop | | Feature flow | `cs-feat-ff` | Ultra-light lane: no design, no phases, direct implementation | | Issue flow | `cs-issue` | Sub-flow entry for issue fixing | @@ -23,6 +27,8 @@ | Knowledge sink | `cs-learn` | Sink pitfalls or good practices into learning docs | | Knowledge sink | `cs-trick` | Curate reusable patterns or library usage as prescriptive references | | Knowledge sink | `cs-decide` | Record settled tech choices, architectural decisions, and long-term constraints | +| Knowledge sink | `cs-note` | Append one-line startup notes to `.codestable/attention.md` | | Explore and docs | `cs-explore` | Targeted code exploration; sink “ask -> read -> conclude” into evidence | +| Explore and docs | `cs-audit` | Audit code for bug, security, performance, maintainability, and architecture risks | | Explore and docs | `cs-guide` | Write outward-facing developer guides | | Explore and docs | `cs-libdoc` | Generate reference docs for public library surfaces | diff --git a/SKILL_CATALOG.md b/SKILL_CATALOG.md index a1e2124..9081e6f 100644 --- a/SKILL_CATALOG.md +++ b/SKILL_CATALOG.md @@ -7,11 +7,15 @@ | 需求与架构 | `cs-req` | 整理和沉淀原始需求文档 | | 需求与架构 | `cs-arch` | 起草或更新 `codestable/architecture/` 下的架构文档 | | 路线图 | `cs-roadmap` | 为大需求做事前规划：概设、接口契约、子 feature 拆解 | -| 路线图 | `cs-roadmap-impl` | 推进已有 roadmap 的下一条可执行 item，初始化 feature 并衔接 design / impl / accept | +| 路线图 | `cs-roadmap-review` | roadmap 人工确认前的独立规划审查 gate | +| 路线图 | `cs-roadmap-impl-goal` | 把已确认 roadmap 编排成可直接运行的 goal，逐个 feature 执行 impl / review / QA / accept | | 讨论入口 | `cs-brainstorm` | 想法模糊时分诊：直接 design、进入 feature brainstorm，或移交 roadmap | | 特性流程 | `cs-feat` | 新特性子流程入口 | | 特性流程 | `cs-feat-design` | 起草 `{slug}-design.md` 作为后续唯一输入 | +| 特性流程 | `cs-feat-design-review` | feature design 人工确认前的独立方案审查 gate | | 特性流程 | `cs-feat-impl` | 按 design 的推进顺序写代码 | +| 特性流程 | `cs-feat-review` | 实现完成后的只读代码审查 gate | +| 特性流程 | `cs-feat-qa` | 代码审查通过后的本地 QA 验证 gate | | 特性流程 | `cs-feat-accept` | 对照 design 核对实现并完成验收闭环 | | 特性流程 | `cs-feat-ff` | 超轻量通道：不写 design、不分阶段，直接实现 | | 问题流程 | `cs-issue` | 问题修复子流程入口 | @@ -23,6 +27,8 @@ | 知识沉淀 | `cs-learn` | 把踩过的坑或好做法沉淀成 learning 文档 | | 知识沉淀 | `cs-trick` | 把可复用模式或库用法整理成处方性参考 | | 知识沉淀 | `cs-decide` | 把已拍板的技术选型、架构决定、长期约束记成永久文档 | +| 知识沉淀 | `cs-note` | 把一两行启动必读的项目注意事项追加到 `.codestable/attention.md` | | 探索与文档 | `cs-explore` | 定向代码探索，把“提问 → 读代码 → 得结论”沉淀成证据 | +| 探索与文档 | `cs-audit` | 主动审计代码中的 bug 隐患、安全、性能、可维护性和架构偏离 | | 探索与文档 | `cs-guide` | 编写对外开发者指南 | | 探索与文档 | `cs-libdoc` | 为库的公开表面生成参考文档 | diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md index 3298665..6955d46 100644 --- a/WORKFLOW.en.md +++ b/WORKFLOW.en.md @@ -9,11 +9,12 @@ cs └── cs-onboard ├── cs-req / cs-arch ├── cs-roadmap - │ └── cs-roadmap-impl - ├── cs-feat-design -> cs-feat-impl -> cs-feat-accept + │ ├── cs-roadmap-review + │ └── cs-roadmap-impl-goal + ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-feat-review -> cs-feat-qa -> cs-feat-accept ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix ├── cs-refactor / cs-refactor-ff - └── cs-learn / cs-trick / cs-decide / cs-explore + └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note ``` Vertical means layers, not strict time order. Long-lived archives are refreshed repeatedly; the roadmap layer is entered for large needs. Execution is event-driven: new capability goes to feature flow, bugs go to issue flow, and code rot goes to refactor flow. The cross-cut layer is the knowledge flywheel. diff --git a/WORKFLOW.md b/WORKFLOW.md index 7a044bb..1027124 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -9,11 +9,12 @@ cs └── cs-onboard ├── cs-req / cs-arch ├── cs-roadmap - │ └── cs-roadmap-impl - ├── cs-feat-design -> cs-feat-impl -> cs-feat-accept + │ ├── cs-roadmap-review + │ └── cs-roadmap-impl-goal + ├── cs-feat-design -> cs-feat-design-review -> cs-feat-impl -> cs-feat-review -> cs-feat-qa -> cs-feat-accept ├── cs-issue-report -> cs-issue-analyze -> cs-issue-fix ├── cs-refactor / cs-refactor-ff - └── cs-learn / cs-trick / cs-decide / cs-explore + └── cs-learn / cs-trick / cs-decide / cs-explore / cs-note ``` 纵向是层次，不是严格时间顺序。长效档案层会反复刷新，规划层只在大需求时进入。第 3 层是事件入口：新需求走 feature，bug 走 issue，腐化走 refactor。横切层是知识飞轮：任何流程都可以把值得复用的经验沉淀到 compound。 diff --git a/cs-feat-design-review/SKILL.md b/cs-feat-design-review/SKILL.md new file mode 100644 index 0000000..2287918 --- /dev/null +++ b/cs-feat-design-review/SKILL.md @@ -0,0 +1,261 @@ +--- +name: cs-feat-design-review +description: feature design 人工确认前的方案审查 gate。对照 {slug}-design.md、{slug}-checklist.yaml、相关 roadmap / requirement / architecture / compound / 代码事实做只读 review，产出 {slug}-design-review.md；优先检测 Paseo 并启动独立 audit subagent（编写者是 Codex 且不同 agent 可用时必须用 Claude 等不同 agent；不可用则记录降级和残余风险）辅助审查，主 agent 等待结果、事实核验并合并定级。触发：用户说"review 这个 design"、"feature design 人审前先独立审查"、"跑 cs-feat-design-review"、"方案审查"。 +--- + +# cs-feat-design-review + +## 启动必读 + +开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 + +本阶段是 feature design 交给用户人工确认前的方案审查 gate。它只读 design、checklist、相关文档和必要代码事实，只写 `{slug}-design-review.md`，不直接改 design/checklist、不替用户批准 design、不进入实现。 + +目标不是替用户做产品判断，而是确认这份 design 已经具备让用户有效 review 和让下游稳定执行的条件：需求边界可核对、名词层和编排层有代码事实支撑、steps 可独立验证、checks 能回到 design 证据、风险 / 基线 / 交付物 / 清洁度可被后续 implement、code review、QA 和 acceptance 消费。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。feature design 模板看 `cs-feat-design/reference.md`。 + +--- + +## 输入 + +进入 review 前必须读取： + +- `.codestable/attention.md` +- `.codestable/features/{feature}/{slug}-design.md` +- `.codestable/features/{feature}/{slug}-checklist.yaml` +- 同目录的 `{slug}-intent.md` / `{slug}-brainstorm.md`（如果存在） +- design frontmatter 指向的 requirement 文档 +- design frontmatter 指向的 roadmap 主文档和 items.yaml（如果有 `roadmap` / `roadmap_item`） +- design 第 4 节指向的 architecture 文档 +- 相关 compound 沉淀：用项目搜索工具按 feature 关键词检索 decision / learning / explore / trick +- design 中引用到的关键代码位置、接口、类型、组件、命令、配置 +- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer） + +没有代码引用时不强行扫全仓库；但 design 声称复用、修改、挂载或约束某个现有模块时，必须读对应代码或文档事实核验。 + +--- + +## 启动检查 + +1. design 存在，frontmatter `doc_type=feature-design`，`feature` 与目录一致，`status` 通常是 `draft`；复审已 approved 设计时要确认用户确实要求重新审查。 +2. checklist 存在，`feature` 与目录一致，`steps` 非空，`checks` 非空；缺 checklist 时报告 `blocked`，回 `cs-feat-design` 生成 review candidate checklist。 +3. checklist 的 `steps.status` 和 `checks.status` 在人审前都应是 `pending`；已有 `done/passed` 说明阶段混乱，报告 `blocked`。 +4. 从 roadmap 起头时，roadmap item 必须能在 items.yaml 中找到，design 的 `roadmap_item` 与 feature slug 对齐。 +5. 如果已有 `{slug}-design-review.md`： + - `status: passed` 且 design/checklist 未变化：提示可进入用户整体 review。 + - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。 + - design/checklist 已变化：重新 review，并在报告里记录轮次。 + +--- + +## 独立 reviewer 增强项 + +本阶段默认由当前 agent 做本地方案审查；独立 reviewer 是增强项，不是硬依赖。检测不到外部 agent、Paseo 不可用、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。 + +但一旦本轮已经启动 independent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 independent reviewer 返回前定稿 `{slug}-design-review.md`、不能给出 `passed`、不能把 design 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 + +先运行本 skill 自带检测脚本。按已加载的 `SKILL.md` 所在目录解析脚本路径，不要按业务仓库根目录猜路径： + +```bash +python scripts/detect-review-agent.py --pretty +``` + +脚本只输出能力 JSON，不启动 agent、不改文件。 + +优先级： + +1. **Paseo 可用**：优先用 Paseo 启动 `audit` 类 subagent 做只读独立审查。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。编写 design 的主 agent 是 Codex 且 `providers.audit` 指向 Claude / Opus 等不同 agent 时，必须使用该独立 reviewer；如果只能用同类 agent，在报告里记录降级和残余风险。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 +2. **只有 claude / gemini / aider 等 CLI 可见**：不要自动调用。直接本地 review，除非用户显式要求使用某个 CLI。 +3. **没有外部 reviewer**：本地 review。 + +Paseo subagent prompt 必须只给原始材料和边界，不透露本地 review 结论： + +```text +你是 CodeStable feature design 的独立方案审查 agent。只读，不修改文件，不更新 design/checklist。 + +请读取： +- .codestable/attention.md +- {design_path} +- {checklist_path} +- 同目录 intent / brainstorm（如有） +- 相关 roadmap / requirement / architecture / compound 文档 +- design 引用到的关键代码、接口、类型、组件、命令入口 + +按 cs-feat-design-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 +重点审查：需求边界、术语冲突、名词层现状→变化、编排层流程、挂载点可卸载性、结构健康度、验收契约、steps 原子性、checks 来源、基线与验证命令、交付物、清洁度、roadmap 接口契约遵守情况。 +每条 finding 必须有 design/checklist/doc/code 事实证据、影响、建议修复边界。 +不要写 {slug}-design-review.md；只把审查结果回传给主 agent。 +``` + +主 agent 仍是最终审查责任方：必须逐条核验 independent reviewer 的 finding，去重、定级、合并进 `{slug}-design-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 + +--- + +## 审查流程 + +### 1. 范围与事实 + +- 用 design 第 0/1 节确认术语、需求摘要、明确不做、复杂度档位、关键决策。 +- 用第 2.1 / 2.2 节确认名词层和编排层是否都有"现状 → 变化"，且现状指向真实代码 / 文档。 +- 用第 2.3 节确认挂载点是否按"删掉 feature 是否消失"收紧。 +- 用第 2.4 节和 checklist steps 对齐推进策略、退出信号和验证动作。 +- 用第 2.5 节确认结构健康度评估覆盖文件级 + 目录级，微重构只做"只搬不改行为"。 +- 用第 3/4 节确认验收契约、架构回写预判、证据类型。 +- 从 roadmap 起头时，额外核对 roadmap 第 4 节接口契约是硬约束，design 没有私自绕开。 + +### 2. 独立审查合并 + +- 记录 detection 结果：`paseo-subagent` / `local-review-with-agent-cli-available` / `local-review`。 +- 没有启动 independent reviewer 时，记录原因，本地 review 可以定稿。 +- 启动 Paseo subagent 后，最终 verdict 必须等 reviewer 返回。 +- reviewer 返回后逐条做本地事实核验；能用 design / checklist / 文档 / 代码证据支撑才合并。 +- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 + +### 3. 方案审查 + +至少覆盖： + +- 需求边界：用户目标、核心行为、成功标准、明确不做是否可核对。 +- 术语与现状：关键术语是否与代码 / 架构 / 历史 feature 冲突；现状描述是否真实。 +- 名词层：值对象、实体、接口、类型、组件 props/events 是否讲清变化。 +- 编排层：主流程图、分支、错误语义、幂等、并发、可观测点是否能跑通。 +- 挂载点：是否列了真实对外注册点，而不是内部改动文件清单。 +- 结构健康度：微重构是否必要且边界安全；目录 convention 候选是否合理。 +- 验收契约：正常 / 边界 / 错误路径是否覆盖，是否有证据类型。 +- checklist：steps 是否独立可验证，exit_signal 是否 yes/no，checks 是否都能追溯到 design。 +- 基线与验证：必跑命令、预检策略、基线红灯归因是否写清。 +- 交付物与清洁度：acceptance 是否能从仓库事实核验；调试输出、TODO、死 import 等规则是否明确。 + +--- + +## 严重度 + +- `blocking`：必须先修。会导致 design 不能被用户有效 review、实现无稳定契约、roadmap 契约被绕开、steps/checks 无法执行、验收不可证伪、关键风险没有验证路径。 +- `important`：应该修；若用户决定延后，必须在 design review 和用户 review 摘要中明确记录。 +- `nit`：小的清晰度或一致性建议，不阻塞。 +- `suggestion`：替代设计思路或补强建议，不要求本次采用。 +- `learning`：知识性说明，不要求动作。 +- `praise`：记录值得保留的设计做法；少量即可。 +- `residual-risk`：review 无法完全消除的不确定性，需要用户 review、implementation、code review、QA 或 acceptance 重点复核。 + +不要把个人偏好的实现写法升级成 blocking。blocking 必须能用 design 契约、checklist、roadmap/req/arch、代码事实或可靠工程原则支撑。 + +--- + +## 报告模板 + +报告路径：`.codestable/features/{feature}/{slug}-design-review.md`。 + +```markdown +--- +doc_type: feature-design-review +feature: {feature} +status: passed|changes-requested|blocked +reviewed: YYYY-MM-DD +round: 1 +--- + +# {slug} feature design 审查报告 + +## 1. Scope And Inputs + +- Design: {path} +- Checklist: {path} +- Intent / brainstorm: {path / none} +- Roadmap: {path / none} +- Related docs: {requirements / architecture / compound} +- Code facts checked: {paths / none} + +### Independent Review + +- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked +- Detection: paseo-subagent|local-review-with-agent-cli-available|local-review|skipped +- Provider / agent: {providers.audit / agent id / none} +- Raw output: {摘要 / 路径 / none} +- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿} +- Gate effect: {none | blocks final verdict until completed / user-approved downgrade} + +## 2. Design Summary + +- Goal: {摘要} +- Key contracts: {名词层 / 编排层摘要} +- Steps: {数量 + 风险热点} +- Checks: {数量 + 来源完整性} +- Baseline / validation: {摘要} + +## 3. Findings + +### blocking + +- [ ] FDR-001 `{path#section|checklist.step|file:line}` {问题} + - Evidence: {事实} + - Impact: {为什么阻塞用户 review / implement} + - Expected fix scope: {修复边界} + +### important + +- [ ] FDR-00N `{证据位置}` {问题} + - Evidence: {事实} + - Impact: {影响} + +### nit + +- [ ] FDR-00N `{证据位置}` {建议} + +### suggestion + +- [ ] FDR-00N {建议} + +### learning + +- {可复用设计经验或注意点} + +### praise + +- {值得保留的做法} + +## 4. User Review Focus + +- 用户需要重点拍板：{决策 / 假设 / 不做范围} +- implement 需要重点遵守：{契约 / steps / 验证} +- code review / QA / acceptance 需要重点复核：{风险 / 证据} + +## 5. Residual Risk + +- {风险 + 下游如何处理；没有写 none} + +## 6. Verdict + +- Status: passed|changes-requested|blocked +- Next: 交给用户整体 review | 回 `cs-feat-design` 修订后重跑 `cs-feat-design-review` | 等 independent reviewer 完成 / 用户确认降级后重跑 +``` + +没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 + +--- + +## 退出条件 + +- [ ] 已读取 attention、design、checklist、相关 intent / brainstorm / roadmap / req / arch / compound。 +- [ ] 已按 design 声明核验必要代码、接口、类型、组件或命令事实。 +- [ ] 已确认 checklist 可解析，steps/checks 都可追溯。 +- [ ] 已运行 independent reviewer 检测，或记录为什么跳过。 +- [ ] 如果启动了 independent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 +- [ ] 已审查需求边界、术语、名词层、编排层、挂载点、结构健康度、验收契约、steps/checks、基线、交付物、清洁度。 +- [ ] 已写 `.codestable/features/{feature}/{slug}-design-review.md`。 +- [ ] 有 blocking / 未处理 important 时指向 `cs-feat-design` 修订并重跑 review。 +- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 feature design 人工 review。 + +--- + +## 容易踩的坑 + +- 把 design review 做成文案润色，没审 steps/checks 是否能执行。 +- 只读 design，不核对 checklist 来源。 +- roadmap 起头时不检查接口契约，导致 feature 偷偷绕开 roadmap。 +- 现状段没读代码就放过，implement 阶段才发现设计站不住。 +- steps 出现"和 / 以及 / 同时"却不复查是否该拆。 +- 启动 independent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 +- 外部 reviewer 的结论没经本地事实核验就照抄。 +- review 报告没有落盘，导致用户 review 和后续实现没有可追溯输入。 diff --git a/cs-feat-design-review/agents/openai.yaml b/cs-feat-design-review/agents/openai.yaml new file mode 100644 index 0000000..a3aac2f --- /dev/null +++ b/cs-feat-design-review/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "CodeStable Feature Design Review" + short_description: "Feature design 人审前的独立 agent 审查" + default_prompt: "使用 $cs-feat-design-review 在人工确认前审查 feature design 和 checklist。" diff --git a/cs-feat-design-review/scripts/detect-review-agent.py b/cs-feat-design-review/scripts/detect-review-agent.py new file mode 100755 index 0000000..a6c7f97 --- /dev/null +++ b/cs-feat-design-review/scripts/detect-review-agent.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +"""Detect optional independent reviewer capabilities for cs-feat-design-review.""" + +from __future__ import annotations + +import argparse +import json +import os +import platform +import shutil +import urllib.error +import urllib.request +from pathlib import Path + + +def find_paseo_cli() -> str | None: + candidates: list[str] = [] + found = shutil.which("paseo") + if found: + candidates.append(found) + + system = platform.system() + if system == "Darwin": + candidates.extend( + [ + "/Applications/Paseo.app/Contents/Resources/bin/paseo", + str(Path.home() / ".local/bin/paseo"), + ] + ) + elif system == "Linux": + candidates.append(str(Path.home() / ".local/bin/paseo")) + elif system == "Windows": + candidates.append(r"C:\Program Files\Paseo\resources\bin\paseo.cmd") + + for candidate in candidates: + path = Path(candidate).expanduser() + if path.exists() and os.access(path, os.X_OK): + return str(path) + return None + + +def paseo_health() -> dict[str, object]: + listen = os.environ.get("PASEO_LISTEN", "127.0.0.1:6767") + url = listen if listen.startswith(("http://", "https://")) else f"http://{listen}" + if not url.endswith("/api/health"): + url = f"{url.rstrip('/')}/api/health" + + try: + with urllib.request.urlopen(url, timeout=0.8) as response: + return { + "ok": 200 <= response.status < 500, + "url": url, + "status": response.status, + } + except (OSError, urllib.error.URLError) as exc: + return {"ok": False, "url": url, "error": str(exc)} + + +def read_paseo_preferences() -> dict[str, object]: + paseo_home = Path(os.environ.get("PASEO_HOME", str(Path.home() / ".paseo"))).expanduser() + path = paseo_home / "orchestration-preferences.json" + result: dict[str, object] = { + "path": str(path), + "exists": path.exists(), + "audit_provider": None, + "preferences": [], + "error": None, + } + if not path.exists(): + return result + + try: + data = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + result["error"] = str(exc) + return result + + providers = data.get("providers") if isinstance(data, dict) else None + if isinstance(providers, dict) and isinstance(providers.get("audit"), str): + result["audit_provider"] = providers["audit"] + + preferences = data.get("preferences") if isinstance(data, dict) else None + if isinstance(preferences, list): + result["preferences"] = [item for item in preferences if isinstance(item, str)] + + return result + + +def detect_direct_agent_clis() -> list[dict[str, str]]: + names = ["claude", "gemini", "opencode", "aider"] + found = [] + for name in names: + path = shutil.which(name) + if path: + found.append({"name": name, "path": path}) + return found + + +def build_result() -> dict[str, object]: + paseo_cli = find_paseo_cli() + health = paseo_health() + preferences = read_paseo_preferences() + direct_agents = detect_direct_agent_clis() + + if paseo_cli or health.get("ok"): + mode = "paseo-subagent" + reason = "Paseo is available; use an audit subagent when the runtime exposes Paseo tools." + elif direct_agents: + mode = "local-review-with-agent-cli-available" + reason = "Direct agent CLIs exist, but cs-feat-review should not invoke them automatically." + else: + mode = "local-review" + reason = "No managed independent reviewer was detected." + + return { + "paseo": { + "cli": paseo_cli, + "health": health, + "preferences": preferences, + }, + "direct_agent_clis": direct_agents, + "recommendation": { + "mode": mode, + "audit_provider": preferences.get("audit_provider"), + "reason": reason, + }, + } + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON output.") + args = parser.parse_args() + + result = build_result() + print(json.dumps(result, ensure_ascii=False, indent=2 if args.pretty else None)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/cs-feat-design/SKILL.md b/cs-feat-design/SKILL.md index 0920fb7..048ac86 100644 --- a/cs-feat-design/SKILL.md +++ b/cs-feat-design/SKILL.md @@ -1,6 +1,6 @@ --- name: cs-feat-design -description: feature 流程阶段 1——为新功能起草 {slug}-design.md 作为后续实现、代码审查、QA 和验收的唯一输入，拍板后抽出 checklist。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。 +description: feature 流程阶段 1——为新功能起草 {slug}-design.md 和 {slug}-checklist.yaml，先交给 cs-feat-design-review 做人审前方案审查，再由用户整体确认为 approved。触发：用户说"开始设计方案"、"写 design doc"、"准备实现 XX"，前提是已知道做什么、为谁、怎么算成功。 --- # cs-feat-design @@ -9,7 +9,7 @@ description: feature 流程阶段 1——为新功能起草 {slug}-design.md 作 开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 -这一阶段的产出是一份方案文件 `{slug}-design.md`，加上从中抽出的行动清单 `{slug}-checklist.yaml`。这两份东西后面会被四个阶段消费——implement 照着推进、review 照着审查、QA 照着验证、acceptance 照着核对，所以这里写错或写漏，下游就跟着错。 +这一阶段的产出是一份方案文件 `{slug}-design.md`，加上从中抽出的行动清单 `{slug}-checklist.yaml`，以及人审前的 `{slug}-design-review.md`。这些东西后面会被 implement / code review / QA / acceptance 消费，所以这里写错或写漏，下游就跟着错。 > 共享路径和命名约定看 `.codestable/reference/shared-conventions.md`。本阶段一般 feature 目录已经由 brainstorm 创建好了；没有的话在这一步建。 @@ -77,7 +77,7 @@ description: feature 流程阶段 1——为新功能起草 {slug}-design.md 作 - **必读主文档第 3 节"模块拆分"和第 4 节"接口契约 / 共享协议"**——这是本 feature 的硬约束输入。契约不合理 / 漏了 → 停下来建议回 `cs-roadmap update` 改，**不要在 design 里偷偷绕开** 2. **slug 从 roadmap 取**，feature 目录 `YYYY-MM-DD-{roadmap 条目 slug}`，不另起 3. **走"流程"一节**，frontmatter 加 `roadmap` / `roadmap_item` 两字段 -4. **落盘 `status: approved` 同时回写 items.yaml**：对应条目 `status: in-progress` + `feature: YYYY-MM-DD-{slug}`，用 `validate-yaml.py` 校验 +4. **候选落盘时回写 items.yaml**：对应条目 `status: in-progress` + `feature: YYYY-MM-DD-{slug}`，用 `validate-yaml.py` 校验；design 先保持 `status: draft`，通过 `cs-feat-design-review` 且用户确认后才改 `approved` 完整衔接协议看 `.codestable/reference/shared-conventions.md` 第 2.5 节。 @@ -146,7 +146,7 @@ design 只管"编排-计算分离"里的编排那一侧：**这次 feature 在 1. **续作检查**——Glob `{slug}-design.md` / `{slug}-intent.md` / `{slug}-brainstorm.md`： - intent / brainstorm：当作输入读入，不重复问已讲清的部分 - - design `status=draft` 各节基本完整 → 跳到本流程"5. 整体 review" + - design `status=draft` 各节基本完整 → 若 checklist 存在则跳到本流程"5. 独立 design review gate"，否则先生成 checklist - design 部分节缺失 → 补缺失节，汇报"上次写到 X，补齐统一给你 review" - design `status=approved` → 别默认覆盖，问用户接着改还是另起 slug 2. **扫 .codestable/ 全局输入**——Glob `.codestable/` 发现可用目录和文档类型，按类取用： @@ -199,11 +199,11 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 - **design 只做安全的微重构，边界严格守住**："只搬不改行为"——文件级靠 IDE rename / move + 编译器校验，目录级靠纯文件移动 + import 路径更新 + 编译器校验。一旦涉及改函数签名 / 改返回值结构 / 改调用关系语义 / 模块拆合，就**超出 design 范围**：写进第 2.5 节末尾的"超出范围的观察"里提示用户"建议后续走 `cs-refactor` 处理"，**不阻塞本 feature、不作为前置依赖**。是否真去做、什么时候做由用户在 feature 之外决定 - **第 2.5 节随整稿一起 review，不单独确认**——和功能方案打包给用户一次过，避免拆成两轮把节奏拖长 -### 4. 补齐剩下各节，整稿一次性给 review +### 4. 补齐剩下各节，生成 review candidate 按 reference.md 模板补齐剩余节（第 0 / 3 / 4 节）。初稿 frontmatter `status: draft`。 -整稿成型后才交给用户看，**不分批 review**——分批用户只看到局部，发现不了"第 1 节范围跟第 2 节变化对不上"这种跨节问题。 +整稿成型后先落盘 draft design，并从 `{slug}-design.md` 抽出 candidate `{slug}-checklist.yaml`。checklist 的 steps/checks 初始都保持 `pending`，用 `validate-yaml.py` 校验。不要等用户确认后才生成 checklist，因为人审前的 `cs-feat-design-review` 需要同时审 design 和 checklist 是否对齐。 第 3 节"验收契约"提示：每条写成"输入 / 触发 → 期望可观察结果"，覆盖正常 + 边界 + 错误。不写测试代码 / framework / mock。 @@ -236,17 +236,25 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 6. **交付物可核验性**：acceptance 是否能从 git diff / 文件系统 / 配置 / 文档状态看到每个承诺产物？ 7. **清洁度覆盖**：是否明确禁止临时调试输出、TODO、死 import、注释掉代码，并说明必要例外？ -### 5. 整体 review +### 5. 独立 design review gate -发一次整体 review 提示（提示词在 reference.md 第 5 节），同时附上 Top 3 风险、关键假设、以及自我批判结论（clean 或已改哪些点）。用户提意见就改，反复直到放行，把 `status` 从 `draft` 改 `approved`。 +运行 `cs-feat-design-review`： -### 6. 生成 {slug}-checklist.yaml +- `passed`：才能把 design + checklist + design-review 报告交给用户整体 review。 +- `changes-requested`：按 finding 修 design/checklist，重新校验 yaml 并重跑 `cs-feat-design-review`。 +- `blocked`：补齐输入、等待 independent reviewer，或让用户明确降级 local-only 后重跑。 -方案确认后从 `{slug}-design.md` 抽出 `steps` + `checks` 落到 `{slug}-checklist.yaml`。完整格式、提取规则、典型节奏看 reference.md 第 3 节。 +### 6. 用户整体 review + +发一次整体 review 提示（提示词在 reference.md 第 5 节），同时附上 Top 3 风险、关键假设、自我批判结论和 `{slug}-design-review.md` 摘要。用户提意见就改；如果修改影响名词层、编排层、验收契约、steps/checks、roadmap 契约或风险策略，必须同步更新 checklist 并回到 Phase 5 重跑 design review。用户明确放行后，把 `status` 从 `draft` 改 `approved`。 + +### 7. 确认 checklist + +确认 `{slug}-checklist.yaml` 已与最终 approved design 同步。完整格式、提取规则、典型节奏看 reference.md 第 3 节。 落盘后 `python .codestable/tools/validate-yaml.py --file {path} --yaml-only` 校验。 -### 7. 退出 +### 8. 退出 按下文退出条件核对，引导用户进入阶段 2。 @@ -269,6 +277,7 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 - [ ] 必跑验证命令 / 基线风险 / 预检要求已写清 - [ ] 交付物清单可被 acceptance 从仓库事实核验 - [ ] 清洁度规则已写清：调试输出、临时 TODO/FIXME、注释掉代码、无用 import 的处理口径明确 +- [ ] `{slug}-design-review.md` 已通过 `cs-feat-design-review`，没有 unresolved blocking finding - [ ] `{slug}-checklist.yaml` 已落盘并通过 `validate-yaml.py` 校验 - [ ] roadmap 起头时 items.yaml 已回写（`status: in-progress` + `feature` 填上） @@ -283,6 +292,7 @@ AI 默认翻车的姿势是**不思考就往眼前最顺手的文件里加**。 - 在 design 写测试代码 / framework / mock / 函数级落点——这些归 implement 自决 - 强行画图——模块 ≤ 2 个、调用线性时画图反而模糊重点 - 只给半份文档先 review——用户看不出全局一致性 +- 跳过 `cs-feat-design-review` 直接让用户拍板——用户只能看到方案表面，看不到 checklist、契约、验收策略的独立审查结论 - 在需求摘要里偷偷扩范围——验收时对不上 - 验收场景写成"体验良好 / 状态完整 / 逻辑正确"——acceptance 无法判定，只能靠感觉 - checklist step 只有下一步完成后才能验证——说明切片不独立，执行中失败时无法定位 diff --git a/cs-feat-design/reference.md b/cs-feat-design/reference.md index ed33904..59c1ce4 100644 --- a/cs-feat-design/reference.md +++ b/cs-feat-design/reference.md @@ -52,7 +52,7 @@ checks: status: pending ``` -`steps`（design 阶段产出）： +`steps`（design draft 成型后先产出，供 `cs-feat-design-review` 和用户 review；用户确认后随 design 一起进入实现）： - 粒度是 paradigm 维度，**不写 file:line / 函数级**——具体落点是 implement 的事 - 切片顺序"最简 Workflow 先行 → 逐个节点填充"： @@ -61,7 +61,7 @@ checks: - 4-8 步；每步必须有可独立验证的退出信号 - 第 2.5 节结论是"微重构"时，**第 1 步固定是"按第 2.5 节方案做微重构（只搬不改行为）"**，独立退出信号（如"全部测试通过 + 编译绿灯 + 行为相关 diff 为零"），跑通后再进 feature 主体步骤 -`checks`（design 阶段产出，提取来源）： +`checks`（design draft 成型后先产出，提取来源）： - 名词契约 ← 第 2.1 节关键接口签名 - 编排骨架 / 流程级约束 ← 第 2.2 节主流程关键步骤、流程级约束 @@ -238,3 +238,5 @@ implement 完成的判据，acceptance 核对的依据。**不写测试代码 / > 7. 第 3 节验收场景：覆盖正常 + 边界 + 错误路径了吗？ > > 有修改意见直接说，确认后进入实现阶段。 + +> 人工 review 前必须先有 `{slug}-design-review.md` 且 `status: passed`。用户修改 design/checklist 后，实质变化要重跑 `cs-feat-design-review`。 diff --git a/cs-feat/SKILL.md b/cs-feat/SKILL.md index c69b735..0f02ae6 100644 --- a/cs-feat/SKILL.md +++ b/cs-feat/SKILL.md @@ -1,6 +1,6 @@ --- name: cs-feat -description: 新功能开发的子流程入口，把"加个 X 能力"从想法走到验收闭环。触发：用户说"做新功能"、"加个 X"、"实现 XX"。只做路由，根据已有产物决定走 brainstorm / design / fastforward / implement / review / QA / acceptance。不处理 bug。 +description: 新功能开发的子流程入口，把"加个 X 能力"从想法走到验收闭环。触发：用户说"做新功能"、"加个 X"、"实现 XX"。只做路由，根据已有产物决定走 brainstorm / design / design-review / fastforward / implement / code-review / QA / acceptance。不处理 bug。 --- # cs-feat @@ -28,6 +28,7 @@ brainstorm 是讨论层独立入口，会分诊：case 1（清楚 → 直接 des ├── {slug}-brainstorm.md ← 阶段 0 产物（仅 case 2 落盘） ├── {slug}-intent.md ← 阶段 1 可选前置草稿（用户自己写半成品） ├── {slug}-design.md ← 阶段 1 方案文件 +├── {slug}-design-review.md ← 阶段 1.5 人审前方案审查报告 ├── {slug}-checklist.yaml ← 阶段 1 生成 steps + checks，2/3 阶段更新 status ├── {slug}-review.md ← 阶段 2.5 代码审查报告 ├── {slug}-qa.md ← 阶段 2.6 QA 验证报告 @@ -42,24 +43,25 @@ brainstorm 是讨论层独立入口，会分诊：case 1（清楚 → 直接 des --- -## 五个阶段 +## 标准阶段 | 阶段 | 子技能 | 产出 | 谁主导 | |---|---|---|---| | 0 brainstorm（可选，独立入口） | `cs-brainstorm` | case 2 时产出 brainstorm note | AI 思考伙伴，用户拍板 | -| 1 方案设计 | `cs-feat-design` | design.md + checklist.yaml | AI 起草，用户整体 review | +| 1 方案设计 | `cs-feat-design` | design.md + checklist.yaml | AI 起草候选方案 | +| 1.5 方案审查 | `cs-feat-design-review` | design-review.md | 独立 agent / AI 人审前审查 | | 2 分步实现 | `cs-feat-impl` | 代码 + 阶段汇报 | AI 按方案执行 | | 2.5 代码审查 | `cs-feat-review` | review.md | AI 只读审查，用户决定是否修 | | 2.6 QA 验证 | `cs-feat-qa` | qa.md | AI 运行证据，用户确认风险 | | 3 验收闭环 | `cs-feat-accept` | acceptance.md | AI 逐层核对，用户终审 | -阶段间有人工 checkpoint。上一阶段没拿到用户明确放行，下一阶段别开始——防止 AI 一口气从需求跑到代码、跑出来才发现走偏。 +阶段间有 gate 和人工 checkpoint。方案先过 design-review，再交给用户整体确认；用户没明确放行，下一阶段别开始——防止 AI 一口气从需求跑到代码、跑出来才发现走偏。 阶段 0 可选且是 feature 流程的**外部入口**——`cs-brainstorm` 同时服务 feature 和 roadmap。case 3（大需求）讨论被移交给 `cs-roadmap` 不再回 feature 流程；roadmap 拆出子 feature 后从 `cs-feat-design` 的"从 roadmap 条目起头"入口进来。 ### Fastforward 模式 -需求清楚 + 范围小时走完整五阶段太啰嗦。fastforward 把 design 压成 4 节（需求摘要 / 设计方案 / 验收标准 / 推进步骤），用户一次确认后直接实现。触发："快速模式"、"fastforward"、"直接开干"、"别那么多步骤"，去 `cs-feat-ff`。 +需求清楚 + 范围小时走标准流程太啰嗦。fastforward 把 design 压成 4 节（需求摘要 / 设计方案 / 验收标准 / 推进步骤），用户一次确认后直接实现。触发："快速模式"、"fastforward"、"直接开干"、"别那么多步骤"，去 `cs-feat-ff`。 **别走** fastforward：跨多个子系统、有术语冲突风险、推进步骤超过 4 步——这些情况跳过 design 意味着 AI 和用户没共同确认过同一份方案，实现完容易发现彼此理解不一样。 @@ -78,6 +80,9 @@ brainstorm 是讨论层独立入口，会分诊：case 1（清楚 → 直接 des | `{slug}-intent.md` 已填好 | `cs-feat-design`（读 intent 作输入） | | 用户说"快速模式 / fastforward" | `cs-feat-ff` | | `{slug}-brainstorm.md` 已存在，要进设计 | `cs-feat-design` | +| `{slug}-design.md` 是 draft 且没有 `{slug}-design-review.md` | `cs-feat-design-review` | +| `{slug}-design-review.md` changes-requested / blocked | `cs-feat-design` 修订后重跑 `cs-feat-design-review` | +| `{slug}-design-review.md` passed，但 design 还没 approved | 交给用户整体 review，确认后回 `cs-feat-design` 标 approved | | `{slug}-design.md` 已 approved、代码没动 | `cs-feat-impl` | | fastforward design 已确认 | `cs-feat-impl` | | 代码已写完但没有 `{slug}-review.md` | `cs-feat-review` | diff --git a/cs-onboard/reference/shared-conventions.md b/cs-onboard/reference/shared-conventions.md index c817a4c..d1825a0 100644 --- a/cs-onboard/reference/shared-conventions.md +++ b/cs-onboard/reference/shared-conventions.md @@ -23,14 +23,18 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： │ └── {slug}/ 一个大需求一个子目录（cs-roadmap 产出） │ ├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分 / 接口契约 / 子 feature 清单 / 排期 │ ├── {slug}-items.yaml 机器可读子 feature 清单，acceptance 回写状态 +│ ├── {slug}-roadmap-review.md 人工确认前的规划审查报告 │ └── drafts/ 可选 ├── features/ feature spec 聚合根 │ └── YYYY-MM-DD-{slug}/ 每个 feature 一个目录 │ ├── {slug}-brainstorm.md （可选，case 2 时产出） │ ├── {slug}-design.md （标准流程） │ ├── {slug}-checklist.yaml （标准流程） +│ ├── {slug}-design-review.md（人审前方案审查） +│ ├── {slug}-review.md （实现后代码审查） +│ ├── {slug}-qa.md （代码审查后 QA gate） │ ├── {slug}-acceptance.md （标准流程） -│ └── {slug}-ff-note.md （fastforward 通道唯一产物，与上面四份互斥） +│ └── {slug}-ff-note.md （fastforward 通道唯一产物，与标准流程产物互斥） ├── issues/ issue spec 聚合根 │ └── YYYY-MM-DD-{slug}/ │ ├── {slug}-report.md @@ -103,7 +107,7 @@ onboard 完成后骨架（`cs-onboard` 负责搭建）： ## 2. {slug}-checklist.yaml 生命周期 - 是 feature 工作流的唯一执行清单 -- 由 `cs-feat-design` 在 design 确认通过后一次生成 `steps` + `checks` +- 由 `cs-feat-design` 在 draft design 成型后先生成 `steps` + `checks`，供 `cs-feat-design-review` 和用户 review；用户确认后随 design 一起进入实现 - `cs-feat-ff` **不生成** checklist（也不写 design / acceptance），是跳过 spec 流程直接写代码的超轻量通道；唯一留下的痕迹是动手后回写的 `{slug}-ff-note.md`（轻量回顾，参与 scoped-commit、可被 cs-arch / cs-req backfill 检索到） `steps` 的粒度是 **编排-计算分离维度的切片策略**——按"先编排骨架、后计算节点、最后持久化与测试"写（最简 Workflow 先行 → 逐个节点填充），**不下沉到 file:line / 函数级**。具体改哪个文件由 implement 阶段决定。 @@ -141,12 +145,16 @@ planned → dropped （cs-roadmap update 模式，用户决定不做时改 **cs-roadmap 的职责**：生成和维护 roadmap 主文档 + items.yaml；把 `planned` 改 `dropped`（用户放弃时）；不改 `in-progress` / `done`（feature 技能负责）。 +**cs-roadmap-review 的职责**：在人审前只读审查 roadmap 主文档 + items.yaml + 相关事实，写 `{slug}-roadmap-review.md`；不修改 roadmap，不替用户批准。 + **cs-feat-design 的职责**（从 roadmap 起头时）： 1. design.md frontmatter 加 `roadmap: {roadmap-slug}` + `roadmap_item: {子 feature slug}` 2. items.yaml 对应条目 `status: in-progress` + `feature: YYYY-MM-DD-{slug}` 3. 校验 yaml +**cs-feat-design-review 的职责**：在人审前只读审查 design + checklist + 相关事实，写 `{slug}-design-review.md`；不修改 design/checklist，不替用户批准。 + 直接起 feature（非 roadmap 来）两字段留空，不触发 roadmap 写。 **cs-feat-accept 的职责**： diff --git a/cs-onboard/reference/system-overview.md b/cs-onboard/reference/system-overview.md index 2c4cb86..c431425 100644 --- a/cs-onboard/reference/system-overview.md +++ b/cs-onboard/reference/system-overview.md @@ -15,7 +15,7 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 **做事**——从一段模糊想法走到上线的功能、或者从一份错误报告走到修好的 bug: -- `cs-feat` — 新功能,design → implement → review → QA → acceptance（想法还模糊时先走讨论层 `cs-brainstorm` 做分诊，不属于 feature 流程内部） +- `cs-feat` — 新功能,design → design-review → implement → code-review → QA → acceptance（想法还模糊时先走讨论层 `cs-brainstorm` 做分诊，不属于 feature 流程内部） - `cs-issue` — 修 bug,report → analyze → fix - `cs-refactor` — 代码优化(行为不变、结构/性能/可读性变),scan → design → apply @@ -39,7 +39,9 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 - `cs-req` — 起草或刷新 `.codestable/requirements/` 下的需求文档——系统的能力愿景层，覆盖过去/现在/未来 - `cs-arch` — 架构相关一站式:起草新架构文档 / 刷新已有文档 / 做架构体检(含 design 自洽 / design↔代码一致 / architecture 目录多份文档间一致)。architecture 只记现状 - `cs-roadmap` — 把一块装不进单个 feature 的大需求拆成带依赖和状态的子 feature 清单,作为后续多次 feature 流程的种子和排期依据;独立于需求 / 架构档案 +- `cs-roadmap-review` — roadmap 人工确认前的只读规划审查 gate - `cs-roadmap-impl-goal` — 把已确认 roadmap 编排成可直接运行的 goal,逐个 feature 衔接 design / impl / review / QA / accept +- `cs-feat-design-review` — feature design 人工确认前的只读方案审查 gate - `cs-guide` — 写给外部读者的开发者指南 / 用户指南 - `cs-libdoc` — 为库的公开 API 逐条目生成参考文档 @@ -58,7 +60,9 @@ CodeStable 把这几类场景各配一套子技能，产物放进统一的目录 | 补 / 更新需求文档 | `cs-req` | | 补 / 更新 / 检查架构文档 | `cs-arch` | | 大需求拆解 / 排期规划 | `cs-roadmap` | +| roadmap 人审前规划审查 | `cs-roadmap-review` | | 推进已有 roadmap / 执行整个 roadmap | `cs-roadmap-impl-goal` | +| feature design 人审前方案审查 | `cs-feat-design-review` | | 技术选型 / 约束 / 规约 | `cs-decide` | | 踩坑回顾、经验总结 | `cs-learn` | | 可复用的编程模式、库用法 | `cs-trick` | @@ -94,7 +98,7 @@ learning / trick / decision / explore 都是存档文档类型,区别在记录 ## feature 和 issue 的阶段不可跳 -feature 走 brainstorm(可选) → design → implement → review → QA → acceptance,issue 走 report → analyze → fix。每个阶段有退出条件,上一个没满足,下一个不开始。 +feature 走 brainstorm(可选) → design → design-review → implement → code-review → QA → acceptance,issue 走 report → analyze → fix。每个阶段有退出条件,上一个没满足,下一个不开始。 AI 最常见的问题是一口气铺几百行代码才让人看——等发现问题已经很难中止。阶段间的人工 checkpoint 就是为了早一步中止。每个 checkpoint 具体检查什么,对应子技能里讲。 diff --git a/cs-roadmap-impl-goal/SKILL.md b/cs-roadmap-impl-goal/SKILL.md index 9b3c768..d1b80a6 100644 --- a/cs-roadmap-impl-goal/SKILL.md +++ b/cs-roadmap-impl-goal/SKILL.md @@ -1,6 +1,6 @@ --- name: cs-roadmap-impl-goal -description: CodeStable 大需求端到端 goal 编排技能。用于用户给出一个较大软件需求，并希望先用 cs-roadmap 沉淀 roadmap，再为 roadmap items 中每个子 feature 完成 cs-feat-design/checklist，经过用户确认后输出一条可直接粘贴的 /goal 指令，由 goal 会话循环逐个 feature 执行 cs-feat-impl、cs-feat-review、cs-feat-qa 和 cs-feat-accept，直到整个 roadmap 验收完成。触发：用户说“做完整个 roadmap”、“把这个大需求拆完并自动推进”、“生成 goal 指令跑完整个 CodeStable roadmap”、“像 supergoal 一样规划并执行这些 features”、“一次性跑完 roadmap 里的所有 feature”等。 +description: CodeStable 大需求端到端 goal 编排技能。用于用户给出一个较大软件需求，并希望先用 cs-roadmap 沉淀 roadmap，经 cs-roadmap-review 通过后用户确认，再为 roadmap items 中每个子 feature 完成 cs-feat-design/checklist 和 cs-feat-design-review，经过用户确认后输出一条可直接粘贴的 /goal 指令，由 goal 会话循环逐个 feature 执行 cs-feat-impl、cs-feat-review、cs-feat-qa 和 cs-feat-accept，直到整个 roadmap 验收完成。触发：用户说“做完整个 roadmap”、“把这个大需求拆完并自动推进”、“生成 goal 指令跑完整个 CodeStable roadmap”、“像 supergoal 一样规划并执行这些 features”、“一次性跑完 roadmap 里的所有 feature”等。 --- # cs-roadmap-impl-goal @@ -13,8 +13,8 @@ description: CodeStable 大需求端到端 goal 编排技能。用于用户给 把一个大需求变成可审阅、可恢复、可自动推进的 CodeStable roadmap 执行包： -1. 先按 `cs-roadmap` 规范澄清需求并创建 / 更新一份 roadmap。 -2. 用户确认 roadmap 后，为 roadmap items 里的每个子 feature 运行 `cs-feat-design`，生成 design + checklist。 +1. 先按 `cs-roadmap` 规范澄清需求并创建 / 更新一份 roadmap，运行 `cs-roadmap-review` 并处理到通过。 +2. 用户确认 roadmap 后，为 roadmap items 里的每个子 feature 运行 `cs-feat-design`，生成 design + checklist，运行 `cs-feat-design-review` 并处理到通过。 3. 用户确认所有 feature design 后，输出一条可直接粘贴的 `/goal` 指令。 4. `/goal` 会话按顺序循环执行每个 feature：`cs-feat-impl` → `cs-feat-review` → 必要时 review-fix → `cs-feat-qa` → 必要时 qa-fix 后重跑 review/QA → `cs-feat-accept` → 更新状态 → 下一个 feature。 5. 全部 feature 验收后，做整个 roadmap 的最终审计；只有审计通过才打印完成标记。 @@ -33,6 +33,7 @@ description: CodeStable 大需求端到端 goal 编排技能。用于用户给 .codestable/roadmap/{slug}/ ├── {slug}-roadmap.md ├── {slug}-items.yaml +├── {slug}-roadmap-review.md ├── goal-plan.md # 本次 goal 执行总览：假设 / 风险 / feature 顺序 / 验证命令 ├── goal-state.yaml # goal 会话实时状态 ├── goal-protocol.md # 从本技能 references/protocol.md 复制并按 slug 落地 @@ -46,6 +47,7 @@ description: CodeStable 大需求端到端 goal 编排技能。用于用户给 .codestable/features/{YYYY-MM-DD}-{feature-slug}/ ├── {feature-slug}-design.md ├── {feature-slug}-checklist.yaml +├── {feature-slug}-design-review.md ├── {feature-slug}-review.md # goal 执行时生成 ├── {feature-slug}-qa.md # goal 执行时生成 └── {feature-slug}-acceptance.md # goal 执行时生成 @@ -59,13 +61,14 @@ description: CodeStable 大需求端到端 goal 编排技能。用于用户给 ### 第一次确认：roadmap -先完成 `cs-roadmap` 的 new / update 流程： +先完成 `cs-roadmap` 的 new / update 流程，并通过人审前 review gate： - 澄清大需求目标、范围、明确不做、成功标准。 - 读取 `.codestable/attention.md`、相关 requirements / architecture / compound / history features。 - 写 `{slug}-roadmap.md` 和 `{slug}-items.yaml`。 - 自查模块拆分、接口契约、依赖 DAG、最小闭环、safety net / polish / harden、验证入口、交付物、知识回写候选。 -- 把完整 roadmap 给用户 review。 +- 运行 `cs-roadmap-review`，如果有 blocking / blocked，先修订或等待 reviewer；不要把未通过 review gate 的 roadmap 给用户确认。 +- 把完整 roadmap + items.yaml + `{slug}-roadmap-review.md` 给用户 review。 只有用户明确确认 roadmap 后，才进入所有 feature design 阶段。 @@ -76,10 +79,11 @@ description: CodeStable 大需求端到端 goal 编排技能。用于用户给 - 创建 feature 目录。 - 写 `{feature-slug}-design.md`，frontmatter 带 `roadmap` / `roadmap_item`。 - 写 `{feature-slug}-checklist.yaml`。 +- 运行 `cs-feat-design-review`；有 blocking / blocked 时先修订或等待 reviewer，不进入用户二次确认。 - 按现有 `cs-feat-design` 约定，把 items.yaml 对应条目更新为 `in-progress` 并填写 `feature` 字段。 - design 必须包含：基线预检、必跑验证命令、交付物、验收场景证据类型、清洁度规则、可独立验证 steps。 -全部 feature design 都写完后，一次性给用户 review。用户可能反复修改任意一个 design；每次修改后同步更新 checklist、goal-plan、goal-features。只有用户明确确认所有 design 后，才输出 `/goal`。 +全部 feature design 都写完且 design-review 都 passed 后，一次性给用户 review。用户可能反复修改任意一个 design；每次修改后同步更新 checklist，并对实质变化重跑 `cs-feat-design-review`。只有用户明确确认所有 design 后，才输出 `/goal`。 用户确认所有 design 后，先把每份 `{feature-slug}-design.md` 的 frontmatter `status` 从 `draft` 改为 `approved`，再生成 goal 执行包。`cs-feat-impl` 和 `cs-feat-accept` 都要求 design 已 approved；不要把 draft design 交给 goal 会话。 @@ -133,7 +137,7 @@ features: 每个 feature 一份，包含： - 对应 roadmap item -- design / checklist / review / QA / acceptance 路径 +- design / checklist / design-review / review / QA / acceptance 路径 - 依赖项 - 必跑命令 - 验收证据 @@ -149,15 +153,17 @@ features: 1. roadmap items 是否 DAG，无循环依赖。 2. 每个 item 是否已有 design + checklist。 -3. 每份 design 是否已 `status: approved`，且 frontmatter 的 `roadmap` / `roadmap_item` 与 items.yaml 一致。 -4. 每个 checklist step 是否可独立验证，且初始 `steps.status` 为 `pending`、`checks.status` 为 `pending`。 -5. 每个 feature 是否有必跑命令 / 基线风险 / 交付物 / 清洁度规则。 -6. 每个 goal-feature spec 是否写明 review / QA / acceptance 产物路径，以及 review blocking / QA failed 的返回路径。 -7. `goal-state.yaml` 是否能断点恢复。 -8. 最终审计是否能从仓库事实核验每个交付物。 -9. 用户是否已明确确认 roadmap 和所有 feature design。 -10. `goal-protocol.md` 是否没有把 roadmap slug 误替换进 feature 标记；`Feature:` 行必须使用 `` 或真实当前 feature slug。 -11. 验证命令如果依赖外部测试工具，goal-plan / goal-feature spec 是否说明真实 runner 或依赖安装方式；不能通过新增 `pytest.py`、`jest`、`go` 等同名 shim 绕过。 +3. roadmap review 是否存在且 `status: passed`，没有 unresolved blocking finding。 +4. 每个 item 是否已有 design-review 且 `status: passed`，没有 unresolved blocking finding。 +5. 每份 design 是否已 `status: approved`，且 frontmatter 的 `roadmap` / `roadmap_item` 与 items.yaml 一致。 +6. 每个 checklist step 是否可独立验证，且初始 `steps.status` 为 `pending`、`checks.status` 为 `pending`。 +7. 每个 feature 是否有必跑命令 / 基线风险 / 交付物 / 清洁度规则。 +8. 每个 goal-feature spec 是否写明 design-review / review / QA / acceptance 产物路径，以及 review blocking / QA failed 的返回路径。 +9. `goal-state.yaml` 是否能断点恢复。 +10. 最终审计是否能从仓库事实核验每个交付物。 +11. 用户是否已明确确认 roadmap 和所有 feature design。 +12. `goal-protocol.md` 是否没有把 roadmap slug 误替换进 feature 标记；`Feature:` 行必须使用 `` 或真实当前 feature slug。 +13. 验证命令如果依赖外部测试工具，goal-plan / goal-feature spec 是否说明真实 runner 或依赖安装方式；不能通过新增 `pytest.py`、`jest`、`go` 等同名 shim 绕过。 --- diff --git a/cs-roadmap-impl-goal/agents/openai.yaml b/cs-roadmap-impl-goal/agents/openai.yaml index bdccbf5..e919b19 100644 --- a/cs-roadmap-impl-goal/agents/openai.yaml +++ b/cs-roadmap-impl-goal/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "CodeStable Roadmap Goal" short_description: "把大需求编排成 roadmap goal" - default_prompt: "使用 $cs-roadmap-impl-goal 把这个大需求沉淀成 CodeStable roadmap、全部 feature design，并输出可直接粘贴的 goal 指令。" + default_prompt: "使用 $cs-roadmap-impl-goal 把这个大需求沉淀成 CodeStable roadmap，跑 roadmap/design review gate，完成全部 feature design，并输出可直接粘贴的 goal 指令。" diff --git a/cs-roadmap-review/SKILL.md b/cs-roadmap-review/SKILL.md new file mode 100644 index 0000000..3dccf3b --- /dev/null +++ b/cs-roadmap-review/SKILL.md @@ -0,0 +1,257 @@ +--- +name: cs-roadmap-review +description: roadmap 人工确认前的规划审查 gate。对照 roadmap 主文档、items.yaml、相关 requirement / architecture / compound / 代码事实做只读 review，产出 {slug}-roadmap-review.md；优先检测 Paseo 并启动独立 audit subagent（编写者是 Codex 且不同 agent 可用时必须用 Claude 等不同 agent；不可用则记录降级和残余风险）辅助审查，主 agent 等待结果、事实核验并合并定级。触发：用户说"review 这个 roadmap"、"roadmap 人审前先独立审查"、"跑 cs-roadmap-review"、"规划审查"。 +--- + +# cs-roadmap-review + +## 启动必读 + +开始任何判断或动作前，先读取 `.codestable/attention.md`；缺失则视为骨架不完整，提示先补齐或运行 `cs-onboard`，不要回退到外部 AI 入口文件。 + +本阶段是 roadmap 交给用户人工确认前的规划审查 gate。它只读 roadmap、items、相关文档和必要代码事实，只写 `{slug}-roadmap-review.md`，不直接改 roadmap、不替用户批准 roadmap、不推进 feature design。 + +目标不是追求"规划看起来完整"，而是确认这份 roadmap 已经具备让用户有效 review 的条件：目标可证伪、范围边界清楚、模块拆分与接口契约可执行、子 feature 可独立验证、依赖 DAG 合理、风险和验证策略提前暴露。 + +> 共享路径与命名约定看 `.codestable/reference/shared-conventions.md`。roadmap 模板看 `cs-roadmap/reference.md`。 + +--- + +## 输入 + +进入 review 前必须读取： + +- `.codestable/attention.md` +- `.codestable/roadmap/{slug}/{slug}-roadmap.md` +- `.codestable/roadmap/{slug}/{slug}-items.yaml` +- roadmap 目录下相关 `drafts/` 材料（只读与本次候选直接相关的） +- roadmap frontmatter 指向的 requirement / architecture 文档 +- roadmap 第 7 节观察项提到的相关文档 +- 相关 compound 沉淀：用项目搜索工具按大需求关键词检索 decision / learning / explore / trick +- items.yaml 中已存在 `feature` 字段的 feature design / acceptance（update 模式或复审时） +- roadmap 中接口契约或模块拆分引用到的关键代码位置 +- independent reviewer 输出（如果本轮启用了 Paseo 或其他外部 reviewer） + +没有代码引用时不强行扫全仓库；但 roadmap 声称复用现有模块、接口、命令、配置或数据结构时，必须读对应代码或文档事实核验。 + +--- + +## 启动检查 + +1. roadmap 主文档存在，frontmatter `doc_type=roadmap`，`slug` 与目录一致，`status` 是 `draft|active|paused|completed` 之一。 +2. items.yaml 存在，`roadmap` 与 slug 一致，`items` 非空。 +3. items.yaml 每条有 `slug` / `description` / `depends_on` / `status` / `feature` / `minimal_loop`。 +4. 依赖图能解析；有循环、自指、未知依赖时直接列 blocking。 +5. 如果已有 `{slug}-roadmap-review.md`： + - `status: passed` 且 roadmap/items 未变化：提示可进入用户 review。 + - `status: changes-requested` / `blocked`：读取旧 findings，确认是否复审。 + - roadmap/items 已变化：重新 review，并在报告里记录轮次。 + +--- + +## 独立 reviewer 增强项 + +本阶段默认由当前 agent 做本地规划审查；独立 reviewer 是增强项，不是硬依赖。检测不到外部 agent、Paseo 不可用、provider 未配置或用户明确要求快速完成时，可以继续本地 review，并在报告里记录 `Independent reviewer: local-only` / `skipped-by-user`。 + +但一旦本轮已经启动 independent reviewer，它就是本轮 review gate 的输入。主 agent 可以先做本地审查草稿，但不能在 independent reviewer 返回前定稿 `{slug}-roadmap-review.md`、不能给出 `passed`、不能把 roadmap 交给用户确认。reviewer 卡住、失败、权限阻塞或耗时过长时，只能把本轮标成 `blocked` / `independent-review-pending`，让用户决定继续等待、重试 reviewer，或明确降级为 local-only review。 + +先运行本 skill 自带检测脚本。按已加载的 `SKILL.md` 所在目录解析脚本路径，不要按业务仓库根目录猜路径： + +```bash +python scripts/detect-review-agent.py --pretty +``` + +脚本只输出能力 JSON，不启动 agent、不改文件。 + +优先级： + +1. **Paseo 可用**：优先用 Paseo 启动 `audit` 类 subagent 做只读独立审查。启动前先加载 / 读取 `paseo` skill 的当前说明，并遵守它的规则：读取 `~/.paseo/orchestration-preferences.json`，使用 `providers.audit`，不要硬编码 Claude 或 Codex。编写 roadmap 的主 agent 是 Codex 且 `providers.audit` 指向 Claude / Opus 等不同 agent 时，必须使用该独立 reviewer；如果只能用同类 agent，在报告里记录降级和残余风险。不要无限轮询运行中的 agent；如果 reviewer 已启动但结果未返回，停止在 review gate，记录 pending/blocked，等待通知或用户决定。 +2. **只有 claude / gemini / aider 等 CLI 可见**：不要自动调用。直接本地 review，除非用户显式要求使用某个 CLI。 +3. **没有外部 reviewer**：本地 review。 + +Paseo subagent prompt 必须只给原始材料和边界，不透露本地 review 结论： + +```text +你是 CodeStable roadmap 的独立规划审查 agent。只读，不修改文件，不更新 roadmap/items。 + +请读取： +- .codestable/attention.md +- {roadmap_path} +- {items_path} +- roadmap frontmatter 指向的 requirement / architecture 文档 +- roadmap 相关 compound / draft 材料 +- roadmap 引用到的关键代码或命令入口 + +按 cs-roadmap-review 的严重度语义输出：blocking / important / nit / suggestion / learning / praise / residual-risk。 +重点审查：目标完成信号、范围与明确不做、模块拆分、接口契约可执行性、子 feature 原子性、依赖 DAG、最小闭环、验证策略、风险缓解、知识回写点、用户是否能据此有效拍板。 +每条 finding 必须有 roadmap/items/doc/code 事实证据、影响、建议修复边界。 +不要写 {slug}-roadmap-review.md；只把审查结果回传给主 agent。 +``` + +主 agent 仍是最终审查责任方：必须逐条核验 independent reviewer 的 finding，去重、定级、合并进 `{slug}-roadmap-review.md`。未经本地事实核验的外部结论只能写 `residual-risk` 或忽略，不能直接升级成 `blocking`。 + +--- + +## 审查流程 + +### 1. 范围与事实 + +- 用 roadmap 第 1/2 节确认目标、覆盖范围、明确不做、关键假设。 +- 用第 3/4 节确认模块拆分和接口契约是否足够支撑多个 feature 共用。 +- 用第 5 节和 items.yaml 对齐所有子 feature：slug、描述、所属模块、依赖、状态、feature 绑定、minimal_loop。 +- 用相关 req / arch / compound 判断有没有冲突、重复规划或遗漏约束。 +- 用代码事实核验 roadmap 对现有模块、命令、接口、配置、数据结构的描述。 + +### 2. 独立审查合并 + +- 记录 detection 结果：`paseo-subagent` / `local-review-with-agent-cli-available` / `local-review`。 +- 没有启动 independent reviewer 时，记录原因，本地 review 可以定稿。 +- 启动 Paseo subagent 后，最终 verdict 必须等 reviewer 返回。 +- reviewer 返回后逐条做本地事实核验；能用文档 / 代码 / items 证据支撑才合并。 +- reviewer 失败、权限阻塞、超时或仍在运行时，不要默默降级；报告 `status: blocked`。 + +### 3. 规划审查 + +至少覆盖： + +- 目标完成信号：是否能观察、能验收、能判定完成 / 未完成。 +- 范围与明确不做：是否具体，能否防止后续 feature 偷偷扩范围。 +- 模块拆分：职责是否清楚，是否有重复模块、万能模块、遗漏模块。 +- 接口契约：是否写到函数签名 / 数据结构 / 协议字段 / 错误码级别；无跨模块接口时是否明确写明。 +- 子 feature 原子性：每条能否独立 design / implement / review / QA / accept；描述是否可证伪。 +- 依赖 DAG：是否无环，依赖理由是否具体，最弱依赖是否先验证。 +- 最小闭环：第一条或最小路径做完后是否能端到端演示。 +- 验证与基线：是否识别 build / typecheck / lint / test / e2e / 手工验证入口；基线不稳时是否安排 safety net。 +- 风险与恢复：Top 风险、外部依赖、迁移 / 权限 / 安全 / 回滚是否提前暴露。 +- 交付物与知识回写：后续 acceptance 是否能从仓库事实核验产物；稳定约定 / 坑点是否有沉淀候选。 + +--- + +## 严重度 + +- `blocking`：必须先修。会导致用户无法有效 review、feature 不能独立执行、接口契约不可用、依赖循环、明显违反 req / arch、关键风险未覆盖、验收不可证伪。 +- `important`：应该修；若用户决定延后，必须在 roadmap review 和用户 review 摘要中明确记录。 +- `nit`：小的清晰度或一致性建议，不阻塞。 +- `suggestion`：替代拆法或补强思路，不要求本次采用。 +- `learning`：知识性说明，不要求动作。 +- `praise`：记录值得保留的规划做法；少量即可。 +- `residual-risk`：review 无法完全消除的不确定性，需要用户 review 或后续 feature-design 重点复核。 + +不要把个人偏好的拆法升级成 blocking。blocking 必须能用 roadmap 契约、items 事实、相关文档、代码事实或可靠工程原则支撑。 + +--- + +## 报告模板 + +报告路径：`.codestable/roadmap/{slug}/{slug}-roadmap-review.md`。 + +```markdown +--- +doc_type: roadmap-review +roadmap: {slug} +status: passed|changes-requested|blocked +reviewed: YYYY-MM-DD +round: 1 +--- + +# {slug} roadmap 审查报告 + +## 1. Scope And Inputs + +- Roadmap: {path} +- Items: {path} +- Related docs: {requirements / architecture / compound / drafts} +- Code facts checked: {paths / none} + +### Independent Review + +- Status: not-available|skipped-by-user|local-only|pending|completed|failed|blocked +- Detection: paseo-subagent|local-review-with-agent-cli-available|local-review|skipped +- Provider / agent: {providers.audit / agent id / none} +- Raw output: {摘要 / 路径 / none} +- Merge policy: {已逐条核验 / 未启用原因 / pending 时不得定稿} +- Gate effect: {none | blocks final verdict until completed / user-approved downgrade} + +## 2. Roadmap Summary + +- Goal completion signal: {摘要} +- Module split: {摘要} +- Interface contracts: {摘要} +- Items: {数量 + minimal loop + 风险热点} +- Dependency shape: {DAG / 问题} + +## 3. Findings + +### blocking + +- [ ] RMR-001 `{path#section|items.slug|file:line}` {问题} + - Evidence: {事实} + - Impact: {为什么阻塞用户 review / 后续 feature} + - Expected fix scope: {修复边界} + +### important + +- [ ] RMR-00N `{证据位置}` {问题} + - Evidence: {事实} + - Impact: {影响} + +### nit + +- [ ] RMR-00N `{证据位置}` {建议} + +### suggestion + +- [ ] RMR-00N {建议} + +### learning + +- {可复用规划经验或注意点} + +### praise + +- {值得保留的做法} + +## 4. User Review Focus + +- 用户需要重点拍板：{决策 / 假设 / 优先级} +- 后续 feature-design 需要重点复核：{接口 / 风险 / 验证} +- 不能靠 roadmap review 完全确认的点：{列表} + +## 5. Residual Risk + +- {风险 + 用户 review / feature-design 如何处理；没有写 none} + +## 6. Verdict + +- Status: passed|changes-requested|blocked +- Next: 交给用户 review | 回 `cs-roadmap` 修订后重跑 `cs-roadmap-review` | 等 independent reviewer 完成 / 用户确认降级后重跑 +``` + +没有某类 finding 时写 `none`，不要删除章节；下一轮复审要能对比。 + +--- + +## 退出条件 + +- [ ] 已读取 attention、roadmap、items、相关 req / arch / compound / drafts。 +- [ ] 已按 roadmap 声明核验必要代码或命令事实。 +- [ ] 已确认 items.yaml 可解析，依赖图无未知节点；有问题已列 finding。 +- [ ] 已运行 independent reviewer 检测，或记录为什么跳过。 +- [ ] 如果启动了 independent reviewer，已等到 completed 并逐条本地核验合并 / 驳回 findings；否则报告 `status: blocked`，没有进入用户 review。 +- [ ] 已审查目标、范围、模块、接口、feature 原子性、依赖、最小闭环、验证、风险、知识回写。 +- [ ] 已写 `.codestable/roadmap/{slug}/{slug}-roadmap-review.md`。 +- [ ] 有 blocking / 未处理 important 时指向 `cs-roadmap` 修订并重跑 review。 +- [ ] 无 blocking 且 important 已处理或明确接受时，明确告诉用户下一步是 roadmap 人工 review。 + +--- + +## 容易踩的坑 + +- 把 roadmap review 做成语病检查，没审接口契约和依赖图。 +- 只读主文档，不核对 items.yaml。 +- 不读 requirement / architecture，导致规划和现状冲突没发现。 +- 接口契约写着"待定"也放过，后续每条 feature 各自发明接口。 +- 子 feature 里塞多个可独立验收的交付，却只当一条。 +- 启动 independent reviewer 后结果还没回来，就把本地 review 定稿为 passed。 +- 外部 reviewer 的结论没经本地事实核验就照抄。 +- review 报告没有落盘，导致用户 review 和后续 design 没有可追溯输入。 diff --git a/cs-roadmap-review/agents/openai.yaml b/cs-roadmap-review/agents/openai.yaml new file mode 100644 index 0000000..bbd672e --- /dev/null +++ b/cs-roadmap-review/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "CodeStable Roadmap Review" + short_description: "Roadmap 人审前的独立 agent 规划审查" + default_prompt: "使用 $cs-roadmap-review 在人工确认前审查已起草的 roadmap。" diff --git a/cs-roadmap-review/scripts/detect-review-agent.py b/cs-roadmap-review/scripts/detect-review-agent.py new file mode 100755 index 0000000..45d7869 --- /dev/null +++ b/cs-roadmap-review/scripts/detect-review-agent.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +"""Detect optional independent reviewer capabilities for cs-roadmap-review.""" + +from __future__ import annotations + +import argparse +import json +import os +import platform +import shutil +import urllib.error +import urllib.request +from pathlib import Path + + +def find_paseo_cli() -> str | None: + candidates: list[str] = [] + found = shutil.which("paseo") + if found: + candidates.append(found) + + system = platform.system() + if system == "Darwin": + candidates.extend( + [ + "/Applications/Paseo.app/Contents/Resources/bin/paseo", + str(Path.home() / ".local/bin/paseo"), + ] + ) + elif system == "Linux": + candidates.append(str(Path.home() / ".local/bin/paseo")) + elif system == "Windows": + candidates.append(r"C:\Program Files\Paseo\resources\bin\paseo.cmd") + + for candidate in candidates: + path = Path(candidate).expanduser() + if path.exists() and os.access(path, os.X_OK): + return str(path) + return None + + +def paseo_health() -> dict[str, object]: + listen = os.environ.get("PASEO_LISTEN", "127.0.0.1:6767") + url = listen if listen.startswith(("http://", "https://")) else f"http://{listen}" + if not url.endswith("/api/health"): + url = f"{url.rstrip('/')}/api/health" + + try: + with urllib.request.urlopen(url, timeout=0.8) as response: + return { + "ok": 200 <= response.status < 500, + "url": url, + "status": response.status, + } + except (OSError, urllib.error.URLError) as exc: + return {"ok": False, "url": url, "error": str(exc)} + + +def read_paseo_preferences() -> dict[str, object]: + paseo_home = Path(os.environ.get("PASEO_HOME", str(Path.home() / ".paseo"))).expanduser() + path = paseo_home / "orchestration-preferences.json" + result: dict[str, object] = { + "path": str(path), + "exists": path.exists(), + "audit_provider": None, + "preferences": [], + "error": None, + } + if not path.exists(): + return result + + try: + data = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError) as exc: + result["error"] = str(exc) + return result + + providers = data.get("providers") if isinstance(data, dict) else None + if isinstance(providers, dict) and isinstance(providers.get("audit"), str): + result["audit_provider"] = providers["audit"] + + preferences = data.get("preferences") if isinstance(data, dict) else None + if isinstance(preferences, list): + result["preferences"] = [item for item in preferences if isinstance(item, str)] + + return result + + +def detect_direct_agent_clis() -> list[dict[str, str]]: + names = ["claude", "gemini", "opencode", "aider"] + found = [] + for name in names: + path = shutil.which(name) + if path: + found.append({"name": name, "path": path}) + return found + + +def build_result() -> dict[str, object]: + paseo_cli = find_paseo_cli() + health = paseo_health() + preferences = read_paseo_preferences() + direct_agents = detect_direct_agent_clis() + + if paseo_cli or health.get("ok"): + mode = "paseo-subagent" + reason = "Paseo is available; use an audit subagent when the runtime exposes Paseo tools." + elif direct_agents: + mode = "local-review-with-agent-cli-available" + reason = "Direct agent CLIs exist, but cs-feat-review should not invoke them automatically." + else: + mode = "local-review" + reason = "No managed independent reviewer was detected." + + return { + "paseo": { + "cli": paseo_cli, + "health": health, + "preferences": preferences, + }, + "direct_agent_clis": direct_agents, + "recommendation": { + "mode": mode, + "audit_provider": preferences.get("audit_provider"), + "reason": reason, + }, + } + + +def main() -> int: + parser = argparse.ArgumentParser() + parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON output.") + args = parser.parse_args() + + result = build_result() + print(json.dumps(result, ensure_ascii=False, indent=2 if args.pretty else None)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/cs-roadmap/SKILL.md b/cs-roadmap/SKILL.md index f1cce90..6329d79 100644 --- a/cs-roadmap/SKILL.md +++ b/cs-roadmap/SKILL.md @@ -65,6 +65,7 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划 .codestable/roadmap/{slug}/ ├── {slug}-roadmap.md 主文档：背景 / 范围 / 模块拆分（概设）/ 接口契约（架构层详设）/ 子 feature 清单 / 排期 ├── {slug}-items.yaml 机器可读清单（feature-design 读、feature-acceptance 回写） +├── {slug}-roadmap-review.md 独立规划审查报告（人审前 gate） └── drafts/ 可选，调研 / 讨论 / 草稿 ``` @@ -121,7 +122,7 @@ description: 把"大到塞不进单个 feature"的需求做成完整事前规划 ### Phase 4：自查清单 -review 前自跑一遍汇报处理： +独立 review 前自跑一遍汇报处理： 1. 模块拆分讲清了吗？每个模块职责一句话能说出来？ 2. 接口契约写到可执行程度了吗？feature-design 看完不需要回来问就能直接照着实现？ @@ -141,15 +142,26 @@ review 前自跑一遍汇报处理： 16. **交付物自查**：每条做完后是否能从仓库事实看到产物，而不是只从汇报看到？ 17. **知识回写自查**：哪些规则或坑会影响后续 feature？是否放进观察项，等 acceptance 验证后触发对应沉淀流程？ -### Phase 5：用户 review +### Phase 5：候选落盘 + 独立 review gate -主文档 + items.yaml 完整贴给用户，并附上 Phase 4 自查结论、Top 3 风险与缓解、关键假设。改到用户明确"可以了"。 +先把候选稿写到标准 roadmap 目录，给 `cs-roadmap-review` 稳定输入： -### Phase 6：落盘 +- **new**：建 `.codestable/roadmap/{slug}/`；写主文档 `status: draft`；写 items.yaml（每条 `status: planned`、`feature: null`）；`validate-yaml.py` 校验。 +- **update**：直接更新主文档 / items.yaml 的候选内容，结构性改动文末加变更日志；重新校验 yaml。 -**new**：建 `.codestable/roadmap/{slug}/`；写主文档（`status: active` / `created` / `last_reviewed` 当天）；写 items.yaml（每条 `status: planned`、`feature: null`）；`validate-yaml.py` 校验。 +然后运行 `cs-roadmap-review`： -**update**：改主文档（`last_reviewed` 当天，结构性改动文末加变更日志）；改 items.yaml 对应条目（drop 不删，`status: dropped` 留存理由）；重新校验 yaml。 +- `passed`：才能把 roadmap 交给用户 review。 +- `changes-requested`：按 finding 修 roadmap/items，重新校验并重跑 `cs-roadmap-review`。 +- `blocked`：补齐输入、等待 independent reviewer，或让用户明确降级 local-only 后重跑。 + +### Phase 6：用户 review + +主文档 + items.yaml + `{slug}-roadmap-review.md` 完整贴给用户，并附上 Phase 4 自查结论、Top 3 风险与缓解、关键假设、review findings / residual risk。改到用户明确"可以了"。如果用户修改导致 roadmap/items 发生实质变化，回到 Phase 5 重跑 review gate。 + +### Phase 7：确认落盘 + +用户确认后，new 模式把主文档 `status` 改为 `active`、`last_reviewed` 改为当天；update 模式更新 `last_reviewed` 当天。重新校验 yaml。 **不改 requirements / architecture**——roadmap 是规划层，那两层只描述现状。拆解过程发现 req / 架构过时，在主文档"观察项"记一句给用户，不顺手改。 @@ -213,6 +225,7 @@ feature-design 发现接口契约不合理 / 漏了 / 描述不准 → **回 `cs - [ ] 需要后续沉淀的 convention / learning / guide / attention 候选已写入观察项 - [ ] items.yaml 通过 `validate-yaml.py` 校验 - [ ] Phase 4 自查清单逐条跑过并汇报 +- [ ] `{slug}-roadmap-review.md` 已通过 `cs-roadmap-review`，没有 unresolved blocking finding - [ ] 用户 review 通过 - [ ] 没有顺手改 req / arch / 代码 / 已有 feature @@ -245,3 +258,4 @@ feature-design 发现接口契约不合理 / 漏了 / 描述不准 → **回 `cs - drop 条目直接删——历史丢失 - roadmap 跑偏成给单条子 feature 写详细方案 - update 改接口契约不评估存量影响——已 in-progress / done 的 feature 没人看到契约变了 +- 跳过 `cs-roadmap-review` 直接让用户拍板——用户只能看到规划表面，看不到接口、依赖、验收策略的独立审查结论 diff --git a/cs-roadmap/reference.md b/cs-roadmap/reference.md index 0d034db..f8330c6 100644 --- a/cs-roadmap/reference.md +++ b/cs-roadmap/reference.md @@ -12,7 +12,7 @@ SKILL.md 只保留流程骨架，具体格式在这里。 --- doc_type: roadmap slug: permission-system -status: active # active | paused | completed +status: draft # draft | active | paused | completed created: YYYY-MM-DD last_reviewed: YYYY-MM-DD tags: [permission, auth] @@ -21,7 +21,7 @@ related_architecture: [] # 相关 architecture doc slug，可空 --- ``` -- `status`：`active` 进行中 / `paused` 暂停 / `completed` 所有条目 done 或 dropped +- `status`：`draft` 待独立 review 和用户确认 / `active` 进行中 / `paused` 暂停 / `completed` 所有条目 done 或 dropped - `related_requirements`：本大需求涉及的 req slug，帮助跳转到"为什么要有这个能力" - `related_architecture`：会被改到的 architecture doc slug，帮助理解"改了会触碰哪些现状" @@ -230,4 +230,6 @@ python .codestable/tools/validate-yaml.py --file .codestable/roadmap/{slug}/{slu > 8. "明确不做"有遗漏？ > 9. 排期顺序符合你的产品优先级？ > -> 有修改意见直接说，确认后落盘 roadmap 目录和 items.yaml。 +> 有修改意见直接说，确认后把 roadmap 从 `draft` 标为 `active`。 + +> 人工 review 前必须先有 `{slug}-roadmap-review.md` 且 `status: passed`。用户修改 roadmap/items 后，实质变化要重跑 `cs-roadmap-review`。 diff --git a/cs/SKILL.md b/cs/SKILL.md index 2e3f716..07de6e9 100644 --- a/cs/SKILL.md +++ b/cs/SKILL.md @@ -41,8 +41,8 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物 .codestable/ ├── requirements/ 需求实体（"为什么要有这个能力"，只记现状） ├── architecture/ 架构实体（"系统现在长什么样"，只记现状） -├── roadmap/ 规划层（"接下来怎么做这块大需求 + 模块切 + 接口定"） -├── features/ 新增能力 spec 聚合根（design / impl / review / qa / accept） +├── roadmap/ 规划层（roadmap / roadmap-review / goal 执行包） +├── features/ 新增能力 spec 聚合根（design / design-review / impl / review / qa / accept） ├── issues/ 修 bug spec 聚合根（report / analyze / fix） ├── refactors/ 重构 spec 聚合根（beta） ├── audits/ 审计实体（主动扫描发现清单，不定修） @@ -51,7 +51,7 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物 **三条流程**： -- **新增能力**：`cs-feat-design` → `cs-feat-impl` → `cs-feat-review` → `cs-feat-qa` → `cs-feat-accept`（想法模糊先 `cs-brainstorm` 分诊） +- **新增能力**：`cs-feat-design` → `cs-feat-design-review` → `cs-feat-impl` → `cs-feat-review` → `cs-feat-qa` → `cs-feat-accept`（想法模糊先 `cs-brainstorm` 分诊） - **修 bug**：`cs-issue-report` → `cs-issue-analyze` → `cs-issue-fix` - **重构**（beta）：`cs-refactor` / `cs-refactor-ff` @@ -79,7 +79,9 @@ CodeStable 把开发活动建模成 **7 个实体 + 3 个流程**，所有产物 | 补 / 更新需求文档 | `cs-req` | | 补 / 更新 / 检查架构文档 / "刷新架构 doc" / "做架构体检" | `cs-arch` | | 大需求拆解 / "我想要一个 X 系统" / 排期规划 / 模块拆分 + 接口契约 | `cs-roadmap` | +| roadmap 人工确认前的规划审查 / "review 这个 roadmap" | `cs-roadmap-review` | | 推进已有 roadmap / 执行整个 roadmap / "继续 roadmap" / "用 goal 稳步推进 roadmap" | `cs-roadmap-impl-goal` | +| feature design 人工确认前的方案审查 / "review 这个 design" | `cs-feat-design-review` | | 技术选型 / 长期约束 / 编码规约 | `cs-decide` | | 踩坑回顾 / 经验总结 / "值得记下来" | `cs-learn` | | 可复用编程模式 / 库用法 / "以后做 X 就该这样" | `cs-trick` |