@aipper/aiws-spec 0.0.24 → 0.0.26

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

@@ -0,0 +1,126 @@
+---
+name: ws-frontend-design
+description: 前端设计实现（用于视觉型 landing page / 网站 / 应用界面 / demo / prototype；强调构图、层级、图像、动效与克制，不做通用卡片墙）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在 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 个动效想法；说明它们如何改善层级/氛围/可感知性
+
+设计默认值：
+- 从构图开始，不从组件库开始
+- 第一屏优先做成海报感（poster），不是文档感（document）
+- 默认先找一个强视觉锚点：大图、主视觉平面、关键产品画面、主数据工作区
+- 默认不做卡片墙；优先 section、column、divider、media block、list、plain layout
+- 默认最多两套字体、一种强调色；若已有品牌系统，优先跟随现有 token
+- 优先靠留白、尺度、裁切、对比、对齐建立层级，再考虑装饰
+
+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`
+  - 差例子：首页口号、情绪化隐喻、执行摘要横幅
+
+图像与媒体：
+- 图像必须承担叙事任务，不能只是补背景
+- 品牌页/空间页/生活方式产品优先真实感强的图，而不是抽象 3D / 假 dashboard
+- 选图时优先有稳定明暗区，便于文字落位
+- 避免图里自带抢戏的 logo、signage、碎字、边框 UI
+- 若需要多个场景，优先多张图，不要拼贴大杂烩
+
+文案：
+- 用产品语言，不用设计评论语言
+- headline 负责主要意义；supporting copy 通常一句话够了
+- 每个 section 只负责一件事：explain / prove / deepen / convert
+- 如果删掉 30% 文案后更清楚，就继续删
+
+动效：
+- 视觉型页面至少给 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 是否真有必要
+- 动效是否真的提升层级/氛围
+- 去掉装饰阴影后，页面是否仍然成立
+
+输出要求：
+- `Mode:` `landing | app-ui | polish-only`
+- `Visual thesis:` 一句话
+- `Changed:` 改动文件清单
+- `Verify:` 实际运行命令 + 预期结果
+- `Evidence:` 相关 `plan/...`、`changes/<change-id>/...` 或截图/审计路径

package/templates/workspace/.agents/skills/ws-handoff/SKILL.md

@@ -7,25 +7,46 @@ description: 交接（归档后生成/查看 changes/archive/.../handoff.md）
 
 目标：
 - 让 change 的交接信息可回放：`handoff.md`（包含：本次完成/改动文件/关键决策/下一步建议/绑定）
+- 若存在协同工件：在 handoff 中一并概述 `analysis/`、`patches/`、`review/`、`evidence/`
 - 指引在归档与依赖场景下如何使用 handoff
 
 说明：
-- `handoff.md` 由 `aiws change archive` 自动生成：`changes/archive/<date>-<change-id>/handoff.md`
+- `handoff.md` 默认由 `aiws change finish --push` 自动归档时生成：`changes/archive/<date>-<change-id>/handoff.md`
 - `Depends_On` 依赖若已归档，`aiws change start` 会尝试读取依赖的 `handoff.md` 并输出摘要
 
+阶段定位：
+- handoff / archive 阶段；负责查看或补充已归档 change 的交接说明。
+
+必需输入：
+- 已归档的 `change/<change-id>`
+- 对应 archive 目录
+
+必需输出：
+- `Change_ID:` 当前交接对象
+- `Handoff:` `changes/archive/.../handoff.md`
+- `Next:` 推荐后续 change / `Depends_On` 关系
+
+阻断条件：
+- 无法定位目标 change
+- `handoff.md` 无法生成或读取
+
+完成判定：
+- 下一位协作者可以只依赖 `handoff.md` 和绑定信息继续工作，而不需要回溯整段会话。
+
 执行建议：
 1) 先运行 `$ws-preflight`。
-2) 若本 change 已完成并准备归档：运行 `aiws change archive <change-id>`（会先做严格校验，并移动目录到 `changes/archive/`，同时生成 `handoff.md`）。
+2) 先确认本 change 已通过 `aiws change finish <change-id> --push` 完成自动归档。
 3) 查看 handoff：
 ```bash
 change_id="<change-id>"
 ls -1 changes/archive/*-"${change_id}"/handoff.md
 sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
 ```
-4) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
+4) 若是历史/异常场景，尚未归档且需要手工恢复，再运行 `aiws change archive <change-id>`。
+5) 若要让后续 change 可接力：在 `proposal.md` 里声明 `Blocks`（下一步建议会据此生成）。
+6) 若本 change 使用了外部 / 子 agent 协作：确认关键结论已经进入 `review/` 或 `evidence/`，避免 handoff 只留下原始 patch/分析文件而没有最终结论。
 
 输出要求：
 - `Change_ID:` <change-id>
 - `Handoff:` `changes/archive/.../handoff.md`
 - `Next:` 若还有后续工作，建议创建新 change 并在其 `Depends_On` 引用本 change
-

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

@@ -18,6 +18,30 @@ description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
 - 未运行不声称已运行；验证命令要写清“预期结果”
 - 若存在 `changes/<change-id>/proposal.md`，计划与 proposal 的绑定字段必须保持一致（不一致时先修正再继续）
 
+阶段定位：
+- planning 阶段；负责把用户目标收敛为 change 绑定、计划文件和验证入口。
+
+必需输入：
+- 当前任务描述
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 若已存在：`changes/<change-id>/proposal.md`
+- 若已有计划：当前 `plan/...` 文件
+
+必需输出：
+- `Plan file:` 实际写入的 `plan/...`
+- `Change context:` 当前生效的 `change/<change-id>` 分支或 worktree
+- `Bindings:` `Change_ID` / `Req_ID|Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
+- `Verify:` 可复现验证命令与预期
+- `Next:` 先 `$ws-plan-verify`，通过后再 `$ws-dev`
+
+阻断条件：
+- 任务目标或归因绑定不清晰
+- 当前工作区 dirty 且尚未进入可复用的 change 上下文
+- 无法把计划实际写盘
+
+完成判定：
+- 计划已落盘、绑定已同步、验证入口明确，后续实现可以直接按计划推进。
+
 执行步骤（建议）：
 1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
 2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
@@ -66,7 +90,7 @@ fi
    - `Bindings`：`Change_ID` / `Req_ID` / `Problem_ID` / `Contract_Row` / `Plan_File` / `Evidence_Path`
    - `Goal`：要达成什么
    - `Non-goals`：明确不做什么（避免 scope creep）
-   - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
+   - `Scope`：默认写成 `## Scope` 或 `## 影响范围（Scope）`，并包含 `### In Scope` / `### Out of Scope`；`In Scope` 下列出允许修改的文件/目录清单（支持 glob，不确定就写 `TBD` 并说明如何确定）
    - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
    - `Submodules`（当存在 `.gitmodules` 且声明了 submodule 条目时，强制）：声明“本次 change 的 submodule 目标分支真值”（用于同一 superproject 分支内的多渠道交付；也避免仅靠 `.gitmodules` 默认分支导致交付推送到错误分支）
    - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）

package/templates/workspace/.agents/skills/ws-plan-verify/SKILL.md

@@ -14,6 +14,26 @@ description: 计划质检（执行前检查计划是否过长/跑偏，并给出
 - 已执行过 `$ws-plan`，且准备开始编码
 - 或用户反馈“计划太长/容易跑偏”，需要先压缩并对齐
 
+阶段定位：
+- planning gate；负责在编码前检查计划是否满足 change 严格契约。
+
+必需输入：
+- 当前 `plan/...`
+- `changes/<change-id>/proposal.md`
+- 当前 change 上下文
+
+必需输出：
+- `Quality gate:` pass/fail
+- `Fix list:` 最小修正项
+- `Next:` 通过则 `$ws-dev`，未通过则继续修正并复跑
+
+阻断条件：
+- 无法定位当前 change 或计划文件
+- `aiws change validate <change-id> --strict` 未通过
+
+完成判定：
+- 计划满足严格门禁，且后续实现可以在不补需求/补绑定的情况下直接开始。
+
 执行步骤（建议）：
 1) 先运行 `$ws-preflight`。
 2) 识别 change 上下文：

package/templates/workspace/.agents/skills/ws-preflight/SKILL.md

@@ -7,6 +7,29 @@ description: 预检（提交前快速检查与建议）
 
 目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
 
+阶段定位：
+- workflow 入口阶段；负责判断当前仓库是否具备继续执行其它 `ws-*` 阶段的前置条件。
+
+必需输入：
+- 当前项目根目录候选路径
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+
+必需输出：
+- `Root:` 当前项目根
+- `Found:` 实际读取到的真值文件
+- `Missing:` 缺失项
+- `Key rules:` 3-8 条约束摘要
+- `Next:` 若真值齐全，建议进入 `$ws-plan` 或 `$ws-dev`；若缺失，建议先 `aiws init .`
+
+阻断条件：
+- 无法确定项目根目录
+- 缺失任一真值文件
+
+完成判定：
+- 使用者已经知道当前仓库能否继续进入后续阶段，以及必须遵守的约束与下一步入口。
+
 执行步骤（强制）：
 1) 定位项目根目录：
    - 优先：`git rev-parse --show-toplevel`

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

@@ -0,0 +1,56 @@
+---
+name: ws-quality-review
+description: 质量审查（行为回归 / 测试覆盖 / 实现质量）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动的行为正确性、边界条件、测试覆盖和实现质量
+- 把“代码/行为层 findings”优先落盘到 `changes/<change-id>/review/quality-review.md`
+
+阶段定位：
+- review 子 gate；负责实现质量、行为回归与验证覆盖审查。
+
+必需输入：
+- 当前 `git diff`
+- 已执行的验证结果
+- 相关代码 / 配置 / 测试文件
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 review 文件
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/quality-review.md` 或回退 `.agentdocs/tmp/review/quality-review.md`
+- `主要发现（Findings）:` 高到低排序的问题 / 风险 / 缺失测试
+- `下一步（Next）:` 最小修复项与回归命令
+
+阻断条件：
+- 没有可审改动
+- 没有任何验证上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 quality review 证据，且 findings / 测试缺口 / next 明确。
+
+步骤（建议）：
+1) 先读取 `git diff`、验证结果与相关代码。
+2) 检查：
+   - 行为是否可能回归
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑改动
+   - 是否存在明显复杂度、耦合、可维护性或性能问题
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是质量 / 回归 review，不替代 requirements / gate review。
+- 若发现流程、归因、evidence 缺口，转交给 `$ws-spec-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

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

@@ -7,15 +7,39 @@ description: 评审（提交前审计与证据落盘）
 
 目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据优先落盘到 `changes/<change-id>/review/`（若无法确定 `change-id` 再回退 `.agentdocs/tmp/review/`）。
 
+阶段定位：
+- review 阶段；负责对当前改动做规范、风险和验证完整性的审计。
+
+必需输入：
+- 当前 `git status` / `git diff`
+- 已执行的验证结果
+- 真值文件：`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`
+- 当前 `change/<change-id>` 上下文（若能识别）
+- 若存在：`changes/<change-id>/analysis/`、`patches/`、已有 `review/` 文件
+
+必需输出：
+- 审计文件：`changes/<change-id>/review/codex-review.md` 或回退 `.agentdocs/tmp/review/codex-review.md`
+- `主要风险（Top risks）:` 3-8 条
+- `下一步（Next）:` 最小修复清单 + 最小验证命令
+
+阻断条件：
+- 没有可审计的改动或验证上下文
+- 审计证据无法写盘
+
+完成判定：
+- 审计证据已落盘，主要风险和下一步已明确，可作为 commit/deliver 前置输入。
+
 步骤（建议）：
 1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
 2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
    - 是否存在越界目录改动/危险操作
    - 是否有可复现验证命令与证据
    - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+   - 若存在 `analysis/` / `patches/`：审查这些委托工件是否已被主 agent 理解、是否需要采用/拒绝，并把结论写入 review 文件
 3) 将审计落盘到（目录不存在则创建）：
    - 默认：`changes/<change-id>/review/codex-review.md`
    - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
+   - 若已有其它 reviewer 文件：不要覆盖它们；当前 reviewer 应写自己的文件或更新自己的汇总文件
 4) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）

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

@@ -0,0 +1,57 @@
+---
+name: ws-spec-review
+description: 规范审查（requirements / plan / evidence / gate 完整性）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 审查当前改动是否满足真值文件、change 绑定、证据路径和 gate 完整性要求
+- 把“流程/规范层 blocker”与“代码层问题”区分开，优先落盘到 `changes/<change-id>/review/spec-review.md`
+
+阶段定位：
+- review 子 gate；负责 requirements / plan / evidence / workflow gate 完整性审查。
+
+必需输入：
+- `AI_PROJECT.md`
+- `REQUIREMENTS.md`
+- `AI_WORKSPACE.md`
+- 当前 `git diff`
+- 若存在：`plan/...`、`changes/<change-id>/proposal.md`、`tasks.md`、`review/`、`evidence/`
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/review/spec-review.md` 或回退 `.agentdocs/tmp/review/spec-review.md`
+- `阻断项（Blockers）:` requirements 归因 / gate / evidence 缺口
+- `下一步（Next）:` 修复项与最小验证命令
+
+阻断条件：
+- 无法定位项目根或真值文件
+- 无法判断当前 change / 归因上下文
+- 无法写 review 证据
+
+完成判定：
+- 已落盘 spec review 证据，且明确指出 blocker / warning / next。
+
+步骤（建议）：
+1) 先运行 `$ws-preflight`。
+2) 对照 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 检查：
+   - 当前改动能否归因到 `Req_ID` / `Problem_ID`
+   - `plan/...`、`proposal.md`、`tasks.md`、`evidence/` 是否与改动保持一致
+   - 是否存在越界目录改动、危险操作、未声明的非目标扩张
+   - 是否已经准备好可复现验证入口
+3) 把结论落盘到：
+   - 默认：`changes/<change-id>/review/spec-review.md`
+   - 回退：`.agentdocs/tmp/review/spec-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `阻断项（Blockers）:`
+   - `警告（Warnings）:`
+   - `下一步（Next）:`
+
+重点：
+- 这是 spec / gate review，不是代码质量 review。
+- 若发现实现质量或回归问题，转交给 `$ws-quality-review`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

package/templates/workspace/.agents/skills/ws-verify-before-complete/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ws-verify-before-complete
+description: 完成前验证（finish / handoff 前检查双审查与 validate/evidence 是否齐全）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 在进入 `$ws-finish` / `$ws-handoff` 前，检查 review、validate stamp 和证据是否齐全
+- 输出明确的 pass/fail 结论，避免“看起来完成了但 gate 没过”的伪完成
+
+阶段定位：
+- finish 前 gate；负责 completion readiness 检查，不直接做 merge / push / handoff。
+
+必需输入：
+- `changes/<change-id>/review/spec-review.md`
+- `changes/<change-id>/review/quality-review.md`
+- `.agentdocs/tmp/aiws-validate/*.json`
+- 若存在：`changes/<change-id>/evidence/...`、`git status`
+
+必需输出：
+- `证据（Evidence）:` `changes/<change-id>/evidence/verify-before-complete.md` 或回退 `.agentdocs/tmp/review/verify-before-complete.md`
+- `结论（Result）:` pass / fail
+- `缺失项（Missing）:` 未满足的 gate
+- `下一步（Next）:` 进入 `$ws-finish` / `$ws-handoff`，或回退前置 gate
+
+阻断条件：
+- 缺少 spec review
+- 缺少 quality review
+- 缺少 validate stamp
+- review 中仍有未关闭 blocker
+- 无法写 verification 证据
+
+完成判定：
+- 已落盘 verify-before-complete 证据，并明确能否进入 `$ws-finish` / `$ws-handoff`。
+
+步骤（建议）：
+1) 识别当前 `change/<change-id>`。
+2) 检查以下最小 gate：
+   - `changes/<change-id>/review/spec-review.md`
+   - `changes/<change-id>/review/quality-review.md`
+   - `.agentdocs/tmp/aiws-validate/*.json`
+3) 若存在 `changes/<change-id>/evidence/`，检查是否已经收敛 review / validate / collaboration summary。
+4) 将结果落盘到：
+   - 默认：`changes/<change-id>/evidence/verify-before-complete.md`
+   - 回退：`.agentdocs/tmp/review/verify-before-complete.md`
+5) 输出：
+   - `证据（Evidence）:`
+   - `结论（Result）: pass|fail`
+   - `缺失项（Missing）:`
+   - `下一步（Next）:`
+
+重点：
+- 这个 gate 不替代 `$ws-finish`；它只判断“是否具备进入 finish / handoff 的前置条件”。
+- 若 fail，必须明确回退到哪个 gate：`$ws-spec-review`、`$ws-quality-review`、`aiws validate . --stamp` 或 `aiws change evidence <change-id>`。
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

package/templates/workspace/.aiws/manifest.json

@@ -5,7 +5,7 @@
   "aiws_version": "0.0.0",
   "installed_at": "1970-01-01T00:00:00Z",
   "updated_at": "1970-01-01T00:00:00Z",
-  "tools": ["claude", "opencode", "codex", "iflow"],
+  "tools": ["claude", "opencode", "codex"],
   "managed": [
     { "path": ".githooks/pre-commit", "mode": "replace_file", "sha256": "<sha256>" },
     { "path": ".githooks/pre-push", "mode": "replace_file", "sha256": "<sha256>" },
@@ -27,10 +27,6 @@
     { "path": ".codex/prompts/aiws-init.md", "mode": "managed_blocks", "blocks": { "codex:aiws-init": "<sha256>" } },
     { "path": ".codex/prompts/aiws-update.md", "mode": "managed_blocks", "blocks": { "codex:aiws-update": "<sha256>" } },
     { "path": ".codex/prompts/aiws-validate.md", "mode": "managed_blocks", "blocks": { "codex:aiws-validate": "<sha256>" } },
-    { "path": ".codex/prompts/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "codex:aiws-rollback": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-init.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-init": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-update.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-update": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-validate.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-validate": "<sha256>" } },
-    { "path": ".iflow/commands/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "iflow:aiws-rollback": "<sha256>" } }
+    { "path": ".codex/prompts/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "codex:aiws-rollback": "<sha256>" } }
   ]
 }

package/templates/workspace/.claude/commands/using-aiws.md

@@ -0,0 +1,25 @@
+<!-- AIWS_MANAGED_BEGIN:claude:using-aiws -->
+# using aiws
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 把当前任务先路由到正确的 AIWS workflow，而不是直接跳进实现。
+
+执行建议：
+1) 先读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`。
+2) 若缺失任一真值文件：先 `/ws-preflight`，必要时运行 `aiws init .`，不要继续实现。
+3) 若任务意图、归因或验证入口不明确：先提 1-3 个关键澄清问题并停止。
+4) 路由规则：
+   - 需求/验收/合同变更：`/ws-req-review`
+   - 中大型实现或需要 change/worktree：`/ws-plan`
+   - 小步明确实现：`/ws-dev`（若是 simple/local 单点修复，可显式进入 `/ws-dev-lite`）
+   - 评审/审计：`/ws-review`
+   - finish / merge / push / cleanup：`/ws-finish`
+   - handoff / archive summary：`/ws-handoff`
+5) 输出 `Task intent:` / `Binding:` / `Route:` / `Why:` / `Next:`。
+6) 若 `Route: ws-dev` 且任务属于 simple/local 单点修复：`Next` 可显式建议 `/ws-dev-lite`。
+7) 除非用户只要路由判断，否则给出 route 后继续遵循对应入口的契约。
+<!-- AIWS_MANAGED_END:claude:using-aiws -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-dev-lite.md

@@ -0,0 +1,31 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-dev-lite -->
+# ws dev lite
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：处理 simple/local 单点修复，走最小改动 + 最小验证，不默认拉起完整重流程。
+
+使用条件：
+- 目标明确、归因明确、验证入口明确
+- 一般只影响单文件或紧密相关的小范围文件
+- 不需要先改 `REQUIREMENTS.md`
+
+强制流程：
+1) 先运行 `/ws-preflight`。
+2) 先说明：
+   - `Goal:`
+   - `Why lite:`
+   - 若说不清，立刻回到 `/ws-dev` 或 `/ws-plan`
+3) 实施最小改动；不要为形式完整额外扩 scope。
+4) 运行最小可复现验证；允许比全量更窄，但必须说明为什么足够。
+5) 输出 `Changed / Verify / Evidence / Next`。
+6) 若准备提交或交付：后续仍进入 `/ws-review`、`/ws-commit`、`/ws-finish`。
+
+边界：
+- 默认不创建 `plan/...`
+- 默认不跑 `ws-plan-verify`
+- 默认不要求先做双 review
+- 一旦复杂度升高，停止 lite，切回主流程
+<!-- AIWS_MANAGED_END:claude:ws-dev-lite -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-finish.md

@@ -58,7 +58,7 @@ fi
 6) 任一 submodule 不满足 fast-forward 条件时立即停止（不要继续 push 主仓库）。
 7) submodules 全部成功后，再回到主仓库执行：
    - `aiws change finish <change-id> --push`
-8) （可选）交付完成后归档变更工件：`aiws change archive <change-id>`。
+8) `aiws change finish --push` 成功后会自动归档并生成 handoff；只有历史/异常场景才需要手工运行 `aiws change archive <change-id>`。
 
 安全：
 - push 前先输出状态并说明远端/分支。

package/templates/workspace/.claude/commands/ws-handoff.md

@@ -5,10 +5,10 @@
 
 目标：
 - 交接与回放：通过 `handoff.md` 让已归档的 change 可被下一位/下一次会话快速接力。
-- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（由 `aiws change archive` 自动生成）。
+- handoff 文件位置：`changes/archive/<date>-<change-id>/handoff.md`（默认由 `aiws change finish --push` 自动归档时生成）。
 
 执行建议：
-1) 若 change 已完成并准备归档：运行 `/p-aiws-change-archive`（会先严格校验，再归档并生成 `handoff.md`）。
+1) 先确认 change 已通过 `/ws-finish` 或 `aiws change finish --push` 完成自动归档。
 2) 查看 handoff：
 ```bash
 change_id="<change-id>"
@@ -17,6 +17,7 @@ sed -n '1,160p' changes/archive/*-"${change_id}"/handoff.md
 ```
 3) 依赖提示：
 - 若你在某个 change 的 `proposal.md` 声明了 `Depends_On`，`aiws change start` 会尝试读取依赖 change 的 `handoff.md` 并输出摘要（前提：依赖已归档且 handoff 存在）。
+- 若是历史/异常场景尚未归档，再手工运行 `/p-aiws-change-archive`。
 <!-- AIWS_MANAGED_END:claude:ws-handoff -->
 
 可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-quality-review.md

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-quality-review -->
+# ws quality review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：审查行为回归、边界条件、测试覆盖与实现质量。
+
+步骤（建议）：
+1) 读取 `git diff`、已执行的验证结果和相关代码。
+2) 检查：
+   - 是否存在行为回归或明显 bug 风险
+   - 边界条件 / 失败路径是否覆盖
+   - 测试是否足以支撑当前改动
+3) 将结论落盘到：
+   - 默认：`changes/<change-id>/review/quality-review.md`
+   - 回退：`.agentdocs/tmp/review/quality-review.md`
+4) 输出：
+   - `证据（Evidence）:`
+   - `主要发现（Findings）:`
+   - `测试缺口（Gaps）:`
+   - `下一步（Next）:`
+<!-- AIWS_MANAGED_END:claude:ws-quality-review -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-review.md

@@ -12,8 +12,8 @@
    - 是否有可复现验证命令与证据
    - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
 3) 将审计落盘到（目录不存在则创建）：
-   - 默认：`changes/<change-id>/review/claude-review.md`
-   - 回退：`.agentdocs/tmp/review/claude-review.md`（仅在无法确定 `change-id` 时使用）
+   - 默认：`changes/<change-id>/review/codex-review.md`
+   - 回退：`.agentdocs/tmp/review/codex-review.md`（仅在无法确定 `change-id` 时使用）
 4) 回复中输出：
    - `证据（Evidence）:` 证据文件路径
    - `主要风险（Top risks）:` 3–8 条（高→低）