@aipper/aiws-spec 0.0.41 → 0.0.43

package/templates/workspace/.opencode/skills/ws-frontend-design/SKILL.md

@@ -5,122 +5,93 @@ description: 使用时机：需要前端设计、UI/UX 实现时。触发词：
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
-目标：
-- 在 AIWS 约束下交付一个可运行、可验证、视觉方向明确的前端界面
-- 先做信息层级与构图，再做组件细节；避免“先堆卡片再补样式”
-- 在品牌页与产品页之间做正确取舍：品牌页重视觉锚点，产品页重可操作性
-
-非目标（强制）：
-- 不绕过 `$ws-preflight`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`
-- 不因为“追求设计感”而重写无关页面、改动无关设计系统或新增大面积依赖
-- 不默认把已有产品后台改成营销页；dashboard / admin / workspace 优先 utility copy
-- 不把 prompt 语言、设计说明、占位废话直接写进 UI
-
-适用场景：
-- 用户要做 landing page、品牌站、活动页、marketing 页面、demo、prototype、game UI
-- 用户要把现有前端界面做成“视觉主导、层级清晰、记忆点强”的版本
-- 用户明确要求美化、重做、提质、增强 art direction / hierarchy / motion
-
-前置（建议顺序）：
-1) 先运行 `$ws-preflight`。
-2) 判断任务类型（必须选一个）：
-   - `landing`：品牌/营销/活动页
-   - `app-ui`：dashboard / admin / workspace / 工具界面
-   - `polish-only`：不改信息架构，只做视觉提质
-3) 判断设计边界（必须说明）：
-   - `net-new`：全新页面，可建立完整视觉语言
-   - `existing-system`：已有设计系统/品牌规范，优先复用
-4) 若任务达到 medium / complex：先用 `$ws-plan` 落盘计划，再进入实现。
-
-开始编码前，先写三项（不要跳过）：
-- `Visual thesis:` 一句话写清 mood / material / energy
-- `Content plan:` `hero -> support -> detail -> final CTA`（若是 app-ui，则改为 `workspace -> nav -> context -> action`）
-- `Interaction thesis:` 2-3 个动效想法；说明它们如何改善层级/氛围/可感知性
-
-设计默认值：
+目标：在 AIWS 约束下交付可运行、可验证、视觉方向明确的前端界面。先信息层级与构图，再组件细节。品牌页重视觉锚点，产品页重可操作性。
+
+非目标（强制）：不绕过 `$ws-preflight` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`；不因"追求设计感"重写无关页面或新增大面积依赖；不默认改产品后台为营销页；不把 prompt 语言/设计说明/占位废话写进 UI。
+
+适用场景：landing / 品牌站 / 活动页 / marketing / demo / prototype / game UI；或把现有界面提质为"视觉主导、层级清晰"的版本。
+
+前置：
+1) 运行 `$ws-preflight`。
+2) 判断任务类型：`landing`（品牌/营销）| `app-ui`（dashboard/工具）| `polish-only`（仅视觉提质）
+3) 判断设计边界：`net-new`（全新视觉）| `existing-system`（优先复用已有规范）
+4) medium/complex：先用 `$ws-plan` 落盘计划。
+
+编码前先写三项（不要跳过）：
+- `Visual thesis:` 一句话 mood / material / energy
+- `Content plan:` hero → support → detail → final CTA（app-ui：workspace → nav → context → action）
+- `Interaction thesis:` 2-3 个动效想法及其如何改善层级/氛围/可感知性
+
+## 设计默认值
 - 从构图开始，不从组件库开始
-- 第一屏优先做成海报感（poster），不是文档感（document）
-- 默认先找一个强视觉锚点：大图、主视觉平面、关键产品画面、主数据工作区
-- 默认不做卡片墙；优先 section、column、divider、media block、list、plain layout
-- 默认最多两套字体、一种强调色；若已有品牌系统，优先跟随现有 token
+- 第一屏优先海报感（poster），不是文档感（document）
+- 默认先找强视觉锚点：大图、主视觉平面、关键产品画面、主数据工作区
+- 默认不做卡片墙；优先 section / column / divider / media block / list / plain layout
+- 默认最多两套字体、一种强调色；已有品牌系统则优先跟随
 - 优先靠留白、尺度、裁切、对比、对齐建立层级，再考虑装饰
 
-landing 规则：
-1) 默认结构：
-   - Hero：品牌/产品名、承诺、CTA、一个主视觉
-   - Support：一个具体能力 / 证明点 / offer
-   - Detail：氛围、流程、产品深度或故事
-   - Final CTA：开始、注册、联系、访问
-2) Hero 强约束：
-   - 一个 section 只承载一个 dominant idea
-   - 默认使用 full-bleed hero；只有内层文字列需要约束宽度
-   - 品牌名优先级高于 headline；headline 高于 body；body 高于 CTA
-   - 默认不要 hero cards、stat strips、logo clouds、pill soup、floating dashboards
-   - headline 在 desktop 约 2-3 行；mobile 一眼读完
-   - 若有固定 header，它占用首屏预算；不要让 header + hero 超出初始 viewport
-   - 若去掉主视觉后首屏仍几乎成立，说明图像太弱
-
-app-ui 规则：
-- 默认偏克制：少颜色、少 chrome、清晰栅格、密度适中、信息可扫读
-- 优先组织为：`primary workspace -> navigation -> secondary context/inspector -> action`
-- 只有当 card 本身就是交互容器时才用 card；否则尽量改回 plain layout
-- 不要把 routine product UI 做成营销落地页
-- 文案优先 orientation / status / action：
-  - 好例子：`Selected KPIs`、`Plan status`、`Last sync`
-  - 差例子：首页口号、情绪化隐喻、执行摘要横幅
-
-图像与媒体：
+## Landing 规则
+默认结构：
+- Hero：品牌/产品名、承诺、CTA、一个主视觉
+- Support：一个具体能力 / 证明点
+- Detail：氛围、流程、产品深度或故事
+- Final CTA：开始、注册、联系、访问
+Hero 强约束：
+- 一个 section 只承载一个 dominant idea
+- 默认 full-bleed hero；仅内层文字列约束宽度
+- 品牌名 > headline > body > CTA
+- 不要 hero cards / stat strips / logo clouds / pill soup / floating dashboards
+- headline desktop 约 2-3 行；mobile 一眼读完
+- 有固定 header 时占用首屏预算；header + hero 不超出 viewport
+- 若去掉主视觉后首屏仍几乎成立，说明图像太弱
+
+## App-UI 规则
+- 偏克制：少颜色、少 chrome、清晰栅格、密度适中、信息可扫读
+- 优先组织为 primary workspace → navigation → secondary context → action
+- card 只用作交互容器；否则改回 plain layout
+- 不要把常规产品 UI 做成营销落地页
+- 文案优先 orientation / status / action；不要首页口号 / 情绪隐喻 / 执行摘要横幅
+
+## 图像与媒体
 - 图像必须承担叙事任务，不能只是补背景
-- 品牌页/空间页/生活方式产品优先真实感强的图，而不是抽象 3D / 假 dashboard
-- 选图时优先有稳定明暗区，便于文字落位
-- 避免图里自带抢戏的 logo、signage、碎字、边框 UI
-- 若需要多个场景，优先多张图，不要拼贴大杂烩
+- 品牌页/空间页优先真实感强的图，不是抽象 3D / 假 dashboard
+- 选图时优先有稳定明暗区，便于文字落位；避免自带的抢戏 logo / signage / 碎字
+- 若需多个场景，多张图优于拼贴大杂烩
 
-文案：
+## 文案
 - 用产品语言，不用设计评论语言
-- headline 负责主要意义；supporting copy 通常一句话够了
+- headline 负责主要意义；supporting copy 通常一句话足够
 - 每个 section 只负责一件事：explain / prove / deepen / convert
-- 如果删掉 30% 文案后更清楚，就继续删
+- 如果删掉 30% 后更清楚，就继续删
 
-动效：
-- 视觉型页面至少给 2-3 个“有感但克制”的动效：
+## 动效
+- 视觉型页面至少 2-3 个"有感但克制"的动效：
   - 一个 hero 入场序列
   - 一个 scroll-linked / sticky / depth 效果
   - 一个 hover / reveal / layout transition
 - 动效必须改善层级或氛围，不能只是热闹
-- 要兼顾 mobile 流畅度；支持 `prefers-reduced-motion`
-
-工程约束（强制）：
-- 先读现有代码，再决定是否沿用已有 design tokens / 组件 / 动效库
-- `existing-system` 场景下，优先复用已有视觉语言；不要无故“整站改头换面”
-- 不新增字体、图片资源、动画库、运行时依赖，除非明确写出原因、来源、license/成本与回滚方式
-- 所有文字覆盖在图像上时，必须保证对比度与点击区域可用
-- 必须同时考虑 desktop / mobile；不要只调一个 viewport
-- 未运行不声称已运行；验证命令优先引用 `AI_WORKSPACE.md`
-
-硬规则：
-- No cards by default
-- No hero cards by default
-- No generic SaaS card grid as first impression
-- No more than one dominant idea per section
-- No more than two typefaces without a clear reason
-- No more than one accent color unless the existing product already has a strong system
-- No decorative gradients behind routine product UI
-- No busy imagery behind text
-- No filler copy
-
-实现检查（交付前自检）：
-- 第一屏能否一眼看出品牌/产品是什么
-- 是否存在一个明确视觉锚点
-- 只扫标题是否能理解页面
-- 每个 section 是否只有一个职责
-- card 是否真有必要
-- 动效是否真的提升层级/氛围
-- 去掉装饰阴影后，页面是否仍然成立
-
-输出要求：
+- 兼顾 mobile 流畅度；支持 `prefers-reduced-motion`
+
+## 工程约束（强制）
+- 先读现有代码；`existing-system` 下优先复用视觉语言，不无故"整站改头换面"
+- 不新增字体/图片/动画库/运行时依赖，除非写明原因、来源、license 与回滚方式
+- 图像上的文字必须保证对比度与点击区域可用
+- 必须同时考虑 desktop / mobile；验证命令优先引用 `AI_WORKSPACE.md`
+
+## 硬规则
+默认不堆卡片 / hero cards / SaaS card grid。每 section 一个 dominant idea。最多两套字体、一种强调色。产品 UI 后不加装饰渐变，图像后不堆文字，不用 filler copy。
+
+## 实现检查（交付前自检）
+- 第一屏能否一眼看出品牌/产品；是否有明确视觉锚点
+- 只扫标题能否理解页面；每个 section 是否只有一个职责
+- card 是否真有必要；动效是否真正提升层级/氛围
+- 去掉装饰阴影后页面是否仍成立
+
+## 输出要求
 - `Mode:` `landing | app-ui | polish-only`
 - `Visual thesis:` 一句话
 - `Changed:` 改动文件清单
 - `Verify:` 实际运行命令 + 预期结果
-- `Evidence:` 相关 `plan/...`、`.aiws/changes/<change-id>/...` 或截图/审计路径
+- `Evidence:` `plan/...`、`.aiws/changes/<change-id>/...` 或截图/审计路径
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

package/templates/workspace/.opencode/skills/ws-intake/SKILL.md

@@ -5,149 +5,76 @@ description: 使用时机：新需求需要逐条澄清、冻结问题时。触
 
 ## 配置
 
-本 skill 支持以下配置项，用户可在 `.opencode/opencode.json` 的 `skills.ws-intake` 中覆盖：
-
 | 配置项 | 类型 | 默认值 | 说明 |
 |---|---|---|---|
-| `recommendAnswers` | boolean | true | 提问时先给出推荐答案，用户确认即可。逐问题类型标注是否可推荐 |
-| `adversarial` | boolean | true | 启用对抗式审问：挑战假设 + 自动探查代码库寻找矛盾 |
+| `recommendAnswers` | boolean | true | 提问时先给出推荐答案 |
+| `adversarial` | boolean | true | 对抗式审问：挑战假设+代码库探查 |
 
 用中文输出（命令/路径/代码标识符保持原样不翻译）。
 
 目标：
-- 在进入 `/ws-plan` 前，把新需求或中大型变更里的待确认问题逐条澄清并冻结。
-- 采用“一题一线程”模式推进：每次只处理 1 个问题，允许该问题多轮往返，直到形成明确结论。
-- 产出一份可被 `/ws-plan` 消费的轻量草案：`plan/<timestamp>-<slug>.intake.md`。
+- 在 `/ws-plan` 前把新需求或中大型变更里的待确认问题逐条澄清并冻结。
+- "一题一线程"：每次只处理 1 个问题，允许多轮往返到形成明确结论。
+- 产出轻量草案：`plan/<timestamp>-<slug>.intake.md`。
 
 ## Deep Interview 层（前置探询）
 
-在逐题澄清前，先做一轮 Deep Interview 收集高维信息：
-
-### 1. Why 探询
-先问"为什么要做这个？背后的业务/用户价值是什么？"——理解动机后再谈方案。延伸探询：
-- "如果不做这个，会有什么后果？"（量化不做的代价，确认 urgency）
-- "这个需求最早是谁提出的？在什么场景下触发的？"（追溯原始 trigger，避免需求被转述变形）
-
-### 2. 非目标（Non-goals）
-显式记录什么不在本次范围内——防止 scope creep 和后续争论。
-例如："这次不做用户权限管理，只做内容展示层""这个版本不做国际化"。
-非目标与目标同等重要，需用户确认后写入 intake 草案。
-
-### 3. 影响面（Stakeholders）
-识别这个改动会影响谁：
-- 终端用户（使用行为是否会变？）
-- 其他模块或系统（API 耦合、数据依赖）
-- 其他团队（是否需要跨团队协调？谁需要参与评审？）
-
-### 4. 假设显式化
-从当前理解中识别隐含假设，逐条列出并请用户确认。例如：你假设了用户已登录/有权限；你假设了数据规模不超过 X；你假设了这个功能只有 Y 场景用到。
-
-### 5. 替代方案
-在选定方案前，先问"是否考虑过其他方案？为什么选了当前这个？"——记录已探明的替代路径和淘汰理由。
-如果用户明确没考虑过替代方案，在 intake 草案中标记 `Alternatives not explored` 作为风险项。
-
-### 6. 约束挑战
-对每条约束问"如果这条约束不存在会怎样？"——区分硬约束（不可变）和自设约束（可协商）。
-
-### 7. 优先级
-Must-have / Should-have / Nice-to-have 三层分类，明确 scope 底线。
-
-### 8. 成功度量
-不仅仅是"验收标准通过"，更要问"这个功能上线后，怎么判断它成功了？"——量化指标（DAU、转化率、响应时间、错误率等）。如果无法量化则记入风险。
+在逐题澄清前收集高维信息：
 
-### 9. 风险预判
-识别 3-5 个最关键风险（技术方案、时间窗口、外部依赖、安全合规），写入 intake 草案。
+1. **Why 探询**：问"为什么要做？不做有什么后果？"——理解动机，量化 urgency
+2. **非目标（Non-goals）**：显式记录什么不在本次范围内，防止 scope creep
+3. **影响面**：识别影响谁（终端用户、其他模块/系统、其他团队）
+4. **假设显式化**：列出隐含假设，请用户逐条确认
+5. **替代方案**：问"是否考虑过其他方案？为什么选当前这个？"
+6. **约束挑战**：区分硬约束（不可变）和自设约束（可协商）
+7. **优先级**：Must-have / Should-have / Nice-to-have
+8. **成功度量**：量化指标（DAU、转化率、响应时间等）；无法量化则记入风险
+9. **风险预判**：识别 3-5 个最关键风险
 
 输出：以上 9 项归入 intake 草案的 `Deep Interview` 小节。
 
 ## 发散-收敛两子阶段
 
-当需求模糊、方向不明确时，intake 分两子阶段推进：
+当需求模糊、方向不明确时：
 
 ### 发散阶段（Explore）
-- 目标：快速探索 2-3 个可能方向，不深入任何单一方向
-- 输出：每个方向的 1-2 段摘要 + 关键风险 + 依赖
-- 时限：不超过 3 轮对话
-- **探码前问**：在向用户提问前，先使用 `explore` agent 探查代码库中是否已有答案。需要探查的维度包括：
-  - 现有配置文件（`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`package.json`、`tsconfig.json` 等）
-  - 已有实现模式（grep 关键词、查找类似功能的实现文件）
-  - 已有文档或注释（相关模块的 README、代码注释）
-  - 已有测试文件（理解测试模式和边界条件）
-- 探查到的信息直接作为发散阶段的输入，不需要再向用户重复确认已经在代码库中找到的事实。
+- 快速探索 2-3 个方向（≤3 轮），输出每个方向的摘要+风险+依赖
+- **探码前问**：先用 `explore` agent 探查代码库（配置文件、已有实现、文档、测试），探查到的信息直接作为输入，不再重复确认
 
 ### 收敛阶段（Converge）
-- 目标：从发散结果中选择 1 个方向，逐条冻结具体问题
+- 从发散结果选 1 个方向，逐条冻结问题
 - 回到标准"一题一线程"模式
-- 把发散产出的摘要作为收敛的输入上下文
 
-触发条件：用户说"不确定"/"多个方向"/"帮我分析" 等模糊表达。
-非模糊需求不需要经过发散阶段，直接进入收敛。
+触发条件：用户说"不确定"/"多个方向"等模糊表达。非模糊需求直接进入收敛。
 
 ## 核心原则：一次一个问题
 
-- 每轮只推进 1 个 `Open Questions` 中的问题
-- 当前问题未标记 `frozen` 或 `deferred` 前，不进入下一题
+- 每轮只推进 1 个 `Open Questions`，未标记 `frozen/deferred` 前不进入下一题
 - 输出格式：`Current question → Why it matters → Options → Exit condition`
-- 用户选择后立即写盘更新草案，再进入下一题
+- 用户选择后立即写盘更新草案
 
-**队列保护**：若用户一次提出多个问题，必须显式建队（Queue），逐一处理——不可同时推进多个维度。队列格式：
-- Queue: [Q1: ..., Q2: ..., Q3: ...]
-- Current: Q1
-- Status: [open/in_discussion/frozen/deferred] per item
+**队列保护**：用户一次提出多个问题时建队处理：`Queue: [Q1, Q2, Q3]` / `Current: Q1` / `Status: [open/in_discussion/frozen/deferred]`
 
 执行要求：
-1) 先读 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，必要时先 `/ws-preflight`。
-2) 若存在最新 `plan/*.intake.md`，先续写它；否则新建一份 intake 草案。
-3) 把当前任务拆成 `Open Questions`，状态只允许 `open / in_discussion / frozen / deferred`。
-
-4) **对抗式探码后问**：在对每个 Open Question 提问前，先 spawn `explore` agent 探查代码库，执行以下三层操作：
-   a) **事实探查**：代码库中是否有足以回答该问题的信息？如果有，记录到 intake 草案并跳过提问。
-      - `codebase: answered` — 跳过提问
-      - `codebase: partial` — 补充提问未覆盖部分
-      - `user: required` — 必须问用户
-   b) **矛盾检索**：主动搜索代码库中与用户可能假设相矛盾的代码模式。例如用户说"这个功能很简单"，但代码库显示相关模块有 20 个调用点——这是一个矛盾信号，必须在提问时点出。
-   c) **边缘案例探测**：搜索边界条件模式——空值、并发写入、依赖不可用、超大输入等，在提问时自动补充边缘问题。
-
-5) 每次只推进 1 个当前问题，并显式输出：
-   - `Current question:`
-   - `Why it matters:`
-   - `Current options / current understanding:`
-   - `Recommended answer:` — 如果该问题类型可推荐（事实确认类、二选一/多选一、最佳实践类），先给出推荐答案。开放型/创意型问题标注 `recommendation: N/A`
-   - `Exit condition:`
-- 每个问题独立线程：在未标记 frozen/deferred 前，不进入下一题。问答往返不限轮数，但一次只处理一个维度的决策。
-- **推荐答案模式**：对事实确认类、二选一/多选一、最佳实践类问题，agent 先在 `Recommended answer` 中给出推荐，用户只需确认或修正。推荐答案必须来自代码库探查、规范文件或公认最佳实践，不做编造。若 `recommendAnswers: false`（配置关闭），则不显示推荐答案直接提问。
-6) **决策树分支遍历**（替代扁平队列）：
-   - 问题组织为树而非列表：每个答案可能产生子问题（分支），每个分支必须走到叶节点（无子问题）才算完成。
-   - 交互式遍历：用户回答后，根据答案展开对应子分支；下一个问题由当前回答决定，而非预定顺序。
-   - 追踪状态：使用缩进树格式维护当前遍历位置：
-     ```
-     Tree:
-       ├─ Q1 (frozen)
-       │  ├─ Q1.1 (frozen)
-       │  └─ Q1.2 ← current
-       ├─ Q2 (pending, blocked by Q1.2)
-       └─ Q3 (pending)
-     ```
-   - 分支耗尽判据：所有叶节点均标记 `frozen` 或 `deferred` 时，intake 完成。
-   - `UNRESOLVED_BRANCH`：如果某分支因外部依赖或信息不足无法继续，标记为 `UNRESOLVED_BRANCH` 并写入 intake 草案的 `Decision Tree` 小节。goal 文件会读取此标记作为阻塞项。
-   - 用户一次性提出多个问题仍需要排队，但队列中的问题按决策树优先级重排（先主干、再分支）。
-7) 每轮都要把 intake 草案写盘，至少包含：
-   - `Deep Interview` — 9 维分析：Why/非目标/影响面/假设/替代方案/约束/优先级/成功度量/风险
-   - `Context`
-   - `Codebase Knowns` — 来自代码库的已知信息：在提问前通过 explore 已确认的事实、现有模式、配置值等。标注每项的信息来源路径
-   - `Open Questions`
-   - `Resolved Questions`
-   - `Frozen Decisions`
-   - `Draft Scope`
-   - `Draft Verify`
-   - `Ready for ws-plan: yes/no`
-8) 错误状态节点（Error States）：
-   - 在 intake 草案中专设 `Error States` 小节，覆盖已知失败模式：
-     - 网络/超时/第三方依赖不可用时的系统行为
-     - 数据一致性（并发写入、部分失败、脏数据）
-     - 输入校验边界（空、超大、非预期类型）
-   - 若识别到需要回滚的场景：在 `Error States` 中写明回滚条件与回滚方式。
-9) 回滚规范（Rollback Spec）：
-   - 当 intake 涉及现有数据迁移、API 契约变更、配置漂移修复时，必须包含 `Rollback Plan` 小节。
-   - `Rollback Plan` 至少包含：触发条件、回滚步骤、验证回滚成功的方式、副作用清单。
-10) 若关键问题已冻结：`Next` 指向 `/ws-plan`；否则继续 `/ws-intake`。
+1) 先读真值文件，必要时 `/ws-preflight`
+2) 若存在 `plan/*.intake.md` 则续写，否则新建
+3) 拆解为 `Open Questions`，状态只允许 `open/in_discussion/frozen/deferred`
+4) **对抗式探码后问**：提问前 spawn `explore` agent：
+   - 事实探查：代码库已有答案则记录并跳过提问（`codebase: answered/partial` vs `user: required`）
+   - 矛盾检索：搜代码库中与用户假设矛盾的模式
+   - 边缘案例：空值、并发写入、依赖不可用等
+5) 每次只推进 1 个问题，显式输出 `Current question` / `Why it matters` / `Options` / `Recommended answer` / `Exit condition`
+6) **决策树分支遍历**：问题组织为树，每个答案可能产生子分支。使用缩进树格式追踪：
+   ```
+   ├─ Q1 (frozen)
+   │  ├─ Q1.1 (frozen)
+   │  └─ Q1.2 ← current
+   ├─ Q2 (pending)
+   ```
+   所有叶节点均 `frozen/deferred` 时 intake 完成。无法继续的分支标记 `UNRESOLVED_BRANCH`。
+7) 每轮写盘 intake 草案，至少包含：Deep Interview / Context / Codebase Knowns / Open Questions / Resolved Questions / Frozen Decisions / Draft Scope / Draft Verify / Ready for ws-plan
+8) **Error States**：覆盖已知失败模式（网络超时、数据一致性、输入校验边界），含回滚条件与方式
+9) **Rollback Plan**：涉及数据迁移、API 契约变更、配置漂移修复时，须包含触发条件、回滚步骤、验证方式、副作用
+10) 关键问题已冻结 → `Next: /ws-plan`；否则继续 `/ws-intake`
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

package/templates/workspace/.opencode/skills/ws-plan/SKILL.md

@@ -51,7 +51,7 @@ OpenCode + oMo 优先策略：
 1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
    - 若检测到 oMo：优先让 `planner-sisyphus` 生成 planning draft；若需要补结构探索，再委托 `@explore` / `@librarian`。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
-3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
+3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。Granularity gate：每步必须 ≤3 个原子操作（read/edit/write/run）。若某步超过此限，拆细后再写入计划。
  4) 识别或建立主索引 / change 上下文：
    - 若存在 `.aiws/changes/<change-id>/proposal.md`：读取其中 `Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Evidence_Path`
    - 若缺失关键绑定：先补齐 proposal（至少 `Change_ID`、`Req_ID|Problem_ID`、`Contract_Row`）再继续生成计划
@@ -71,7 +71,7 @@ OpenCode + oMo 优先策略：
    - `Goal`：要达成什么
    - `Non-goals`：明确不做什么（避免 scope creep）
    - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
-   - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
+    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）。每步必须 ≤3 个原子操作；若某步超限，拆成多步。
    - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
     - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
@@ -106,3 +106,5 @@ oMo 回退：
 - `Plan file:` <实际写入的路径>
 - `Change context:` <当前 change 分支或 worktree 路径；若新建了 worktree 需明确写出>
 - `Next:` 推荐下一步（先 `$ws-plan-verify`，通过后再 `$ws-dev`；或 `aiws change start <change-id> --hooks`，superproject + submodule 可用 `--worktree`）
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

package/templates/workspace/.opencode/skills/ws-quality-review/SKILL.md

@@ -39,7 +39,11 @@ OpenCode + oMo 优先策略：
 步骤（建议）：
 1) 先读取 `git diff`、验证结果与相关代码。
    - 若检测到 oMo：优先让 `@oracle` 做 quality review 草稿；必要时再调用 `@explore` 补代码路径上下文。
-2) 检查：
+2) **Change Scope Assessment**：在深入审查前，先获取变更上下文。
+   - 执行 `git diff --stat HEAD` 查看变更文件及行数
+   - 执行 `git log --oneline -3` 查看最近提交
+   - 使用此上下文将审查聚焦在变更区域，各 reviewer agent 无需独立发现变更范围
+3) 检查：
    - 行为是否可能回归
    - 边界条件 / 失败路径是否覆盖
    - 测试是否足以支撑改动
@@ -49,14 +53,14 @@ OpenCode + oMo 优先策略：
       - fake_comments：伪注释（表述代码行为但不解释 why，或与代码不一致）
       - over_defensive：过度防御（不必要的安全检查、对不可能情况的处理）
       - cargo_cult：货舱崇拜（照搬模式但不理解原因，如不必要的 observer/strategy）
-3) 将结论落盘到：
+4) 将结论落盘到：
    - 默认：`.aiws/changes/<change-id>/review/quality-review.md`
    - 回退：`.aiws/tmp/review/quality-review.md`
-4) 输出：
-   - `证据（Evidence）:`
-   - `主要发现（Findings）:`
+5) 输出：
+   - `证据（Evidence）:` — 按严重级别处理：**BLOCKER/HIGH** 附完整证据链（代码引用、影响分析）；**WARNING** 仅给 1 行结论；**INFO/通过项** 不输出或仅 "✓ 通过"
+   - `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
    - `测试缺口（Gaps）:`
-   - `下一步（Next）:`
+   - `下一步（Next）:` 最小修复项与回归命令
 
 重点：
 - 这是质量 / 回归 review，不替代 requirements / gate review。
@@ -66,3 +70,5 @@ OpenCode + oMo 优先策略：
 - 不打印 secrets。
 - 不执行破坏性命令。
 - 若 oMo agent 不可用，回退为当前 agent 本地 quality review。
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

package/templates/workspace/.opencode/skills/ws-review/SKILL.md

@@ -45,39 +45,43 @@ OpenCode + oMo 优先策略：
 步骤（建议）：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
    - 若检测到 oMo：优先让 `@oracle` 做独立审查；必要时再让 `@explore` / `@librarian` 补上下文。
-1.5) **Triage**：preflight 后立即判断本 change 是否需要双审查：
+2) **Change Scope Assessment**：在深入审查前，先获取变更上下文。
+   - 执行 `git diff --stat HEAD` 查看变更文件及行数
+   - 执行 `git log --oneline -3` 查看最近提交
+   - 使用此上下文将审查聚焦在变更区域，各 reviewer agent 无需独立发现变更范围
+3) **Triage**：preflight 后立即判断本 change 是否需要双审查：
    - 需要双审查的条件：改动涉及 REQUIREMENTS 真值、跨 3+ 文件、涉及安全/数据一致性、或准备 finish
-   - 若需要双审查：在步骤 3 开始时即标注 "dual-review: required"，并规划 spec-review + quality-review 两条并行路径
-    - 若不需要双审查：继续通用 review 流程，标注 "dual-review: not-required"
-    - **不得等到 step 6 才决定是否需要双审查**——风险判定必须前置
-   - **Triage 输出格式**：
-     ```
-     Triage: dual-review: required | not-required
-     Rationale: <one reason>
-     Spec review scope: <what to check> (if required)
-     Quality review scope: <what to check> (if required)
-     ```
-   - Findings 格式要求：每个 finding 必须有 [Critical/Warning/Info] 级别标签 + 归因到 SPEC/QUALITY/REGRESSION 类别
-3) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+   - 若需要双审查：在步骤 4 开始时即标注 "dual-review: required"，并规划 spec-review + quality-review 两条并行路径
+     - 若不需要双审查：继续通用 review 流程，标注 "dual-review: not-required"
+     - **不得等到 step 7 才决定是否需要双审查**——风险判定必须前置
+    - **Triage 输出格式**：
+      ```
+      Triage: dual-review: required | not-required
+      Rationale: <one reason>
+      Spec review scope: <what to check> (if required)
+      Quality review scope: <what to check> (if required)
+      ```
+    - Findings 格式要求：每个 finding 必须有 [Critical/Warning/Info] 级别标签 + 归因到 SPEC/QUALITY/REGRESSION 类别
+4) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据
    - 是否维护了 `.aiws/changes/<change-id>/` 或相关 `issues/*.csv`
    - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
-4) Workflow State Suffix 审计（检查 4 种后缀使用是否一致）：
+5) Workflow State Suffix 审计（检查 4 种后缀使用是否一致）：
    - `session` 后缀：只由 ws-dev-lite / ws-intake 写入，标记会话级进度（如 `[workflow-state:session:in_progress]`）
    - `gate` 后缀：由 ws-dev / ws-plan-verify 写入，标记计划/实现门禁结果（如 `[workflow-state:gate:plan_passed]`）
    - `plan` 后缀：由 ws-plan 写入，标记计划阶段状态（如 `[workflow-state:plan:in_progress]`）
    - `gateway` 后缀：由 ws-finish / ws-deliver 写入，标记交付门禁结果（如 `[workflow-state:gateway:finish_gate_ok]`）
    - 检查当前 change 中使用的后缀类型是否正确对应所在阶段；若出现混用（如 session 与 gate 在同一文件），在审计报告中标记异常并说明应该修正的方向。
-5) 将审计落盘到（目录不存在则创建）：
+6) 将审计落盘到（目录不存在则创建）：
    - 默认：`.aiws/changes/<change-id>/review/codex-review.md`
    - 回退：`.aiws/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
    - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
-6) 若 triage 标记为 `dual_review_required`，继续补齐 dual review gate：
+7) 若 triage 标记为 `dual_review_required`，继续补齐 dual review gate：
    - 运行/收敛 `$ws-spec-review`，落盘 `.aiws/changes/<change-id>/review/spec-review.md`（或回退 `.aiws/tmp/review/spec-review.md`）
    - 运行/收敛 `$ws-quality-review`，落盘 `.aiws/changes/<change-id>/review/quality-review.md`（或回退 `.aiws/tmp/review/quality-review.md`）
    - 不要把单个 `codex-review.md` 误当成 finish gate 已完成
-7) 回复中输出：
+8) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）
    - `下一步（Next）:` 最小修复清单 + 最小验证命令
@@ -86,3 +90,5 @@ OpenCode + oMo 优先策略：
 - 不打印 secrets。
 - 不执行破坏性命令。
 - 若 oMo agent 不可用，回退为当前 agent 本地 review，不阻断流程。
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`

package/templates/workspace/.opencode/skills/ws-spec-review/SKILL.md

@@ -40,19 +40,23 @@ OpenCode + oMo 优先策略：
 步骤（建议）：
 1) 先运行 `$ws-preflight`。
    - 若检测到 oMo：优先让 `@oracle` 做 spec review 草稿；需要补规范上下文时再调用 `@librarian`。
-2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+2) **Change Scope Assessment**：在深入审查前，先获取变更上下文。
+   - 执行 `git diff --stat HEAD` 查看变更文件及行数
+   - 执行 `git log --oneline -3` 查看最近提交
+   - 使用此上下文将审查聚焦在变更区域，各 reviewer agent 无需独立发现变更范围
+3) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
    - 当前改动能否归因到 `Req_ID` / `Problem_ID`
    - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否与改动保持一致
    - 是否存在越界目录改动、危险操作、未声明的非目标扩张
    - 是否已经准备好可复现验证入口
-3) 把结论落盘到：
+4) 把结论落盘到：
    - 默认：`.aiws/changes/<change-id>/review/spec-review.md`
    - 回退：`.aiws/tmp/review/spec-review.md`
-4) 输出：
-   - `证据（Evidence）:`
-   - `阻断项（Blockers）:`
+5) 输出：
+   - `证据（Evidence）:` — 按严重级别处理：**BLOCKER/HIGH** 附完整证据链（归因/路径引用）；**WARNING** 仅给 1 行结论；**通过项** 不输出或仅 "✓ 通过"
+   - `阻断项（Blockers）:` requirements 归因 / gate / evidence 缺口
    - `警告（Warnings）:`
-   - `下一步（Next）:`
+   - `下一步（Next）:` 修复项与最小验证命令
 
 重点：
 - 这是 spec / gate review，不是代码质量 review。
@@ -62,3 +66,5 @@ OpenCode + oMo 优先策略：
 - 不打印 secrets。
 - 不执行破坏性命令。
 - 若 oMo agent 不可用，回退为当前 agent 本地 spec review。
+
+> 运行时行为约束：`packages/spec/docs/run-behavior-guidelines.md`