@aipper/aiws-spec 0.0.1

package/templates/workspace/.agents/skills/aiws-change-templates-init/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: aiws-change-templates-init
+description: 在仓库内初始化 change templates（写入 changes/templates）
+---
+
+目标：
+- 初始化 `changes/templates/`（用于在仓库内自定义 proposal/tasks/design 模板）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates init
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates init
+else
+  npx @aipper/aiws change templates init
+fi
+```

package/templates/workspace/.agents/skills/aiws-change-templates-which/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: aiws-change-templates-which
+description: 查看当前 change templates 来源（只读）
+---
+
+目标：
+- 输出当前仓库 change templates 的解析来源与路径（用于排查模板来自哪里）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change templates which
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change templates which
+else
+  npx @aipper/aiws change templates which
+fi
+```

package/templates/workspace/.agents/skills/aiws-change-validate/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: aiws-change-validate
+description: 校验 changes 工件（可 strict）
+---
+
+目标：
+- 校验 `changes/<change-id>/` 工件完整性、归因与 WS:TODO（用于 hooks/CI）
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change validate "$change_id" --strict
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change validate "$change_id" --strict
+else
+  npx @aipper/aiws change validate "$change_id" --strict
+fi
+```
+
+说明：
+- `--strict` 会把 `WS:TODO`/缺少归因等视为错误（预期在工件未完善前会失败）
+- 紧急情况下可用 `--allow-truth-drift`（不推荐）

package/templates/workspace/.agents/skills/aiws-hooks-install/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: aiws-hooks-install
+description: 启用 git hooks 门禁（core.hooksPath=.githooks）
+---
+
+目标：
+- 为当前 git 仓库启用 aiws 门禁 hooks（`git commit`/`git push` 自动跑 `aiws validate .`）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks install .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks install .
+else
+  npx @aipper/aiws hooks install .
+fi
+```
+
+验证（可选）：
+```bash
+git config core.hooksPath
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.agents/skills/aiws-hooks-status/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: aiws-hooks-status
+description: 查看当前仓库 hooks 状态（只读）
+---
+
+目标：
+- 输出当前仓库 hooks 状态（不修改文件）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws hooks status .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws hooks status .
+else
+  npx @aipper/aiws hooks status .
+fi
+```

package/templates/workspace/.agents/skills/aiws-init/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: aiws-init
+description: 初始化工作区（生成真值文件与门禁）
+---
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws init .
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws init .
+  aiws validate .
+else
+  npx @aipper/aiws init .
+  npx @aipper/aiws validate .
+fi
+```
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件

package/templates/workspace/.agents/skills/aiws-rollback/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: aiws-rollback
+description: 回滚工作区（从备份恢复）
+---
+
+目标：
+- 从 `.aiws/backups/` 恢复到某次备份快照
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws rollback . latest
+elif command -v aiws >/dev/null 2>&1; then
+  aiws rollback . latest
+else
+  npx @aipper/aiws rollback . latest
+fi
+```

package/templates/workspace/.agents/skills/aiws-update/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: aiws-update
+description: 更新工作区（刷新模板与托管块）
+---
+
+目标：
+- 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws update .
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws update .
+  aiws validate .
+else
+  npx @aipper/aiws update .
+  npx @aipper/aiws validate .
+fi
+```
+
+约束：
+- 不写入任何 secrets
+- 只更新托管块或 spec 指定的 `replace_file` 文件

package/templates/workspace/.agents/skills/aiws-validate/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: aiws-validate
+description: 校验工作区（漂移检测 + 门禁）
+---
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  AIWS_VALIDATE_STAMP=1 ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  AIWS_VALIDATE_STAMP=1 aiws validate .
+else
+  AIWS_VALIDATE_STAMP=1 npx @aipper/aiws validate .
+fi
+```
+
+证据（可选）：
+- stamp：`.agentdocs/tmp/aiws-validate/*.json`（由 `.gitignore` 忽略）

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

@@ -0,0 +1,26 @@
+---
+name: ws-analyze
+description: 分析（定位问题与收集上下文）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+
+输入：
+- 主题/需求：用户在本次消息中提供的主题（若不明确，先问一句“本次分析主题是什么？”）
+
+步骤（建议）：
+1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+2) 基于真值文件与当前代码现状，输出：
+   - 目标 / 非目标
+   - 现状证据（文件路径/接口路径）
+   - 推荐方案（1 个）+ 备选（可选）
+   - 风险与回滚（3–8 条）
+   - 最小验证命令（可复现）
+3) 将分析落盘到：`.agentdocs/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
+4) 回复中必须包含：`Evidence:` 证据文件路径。
+
+安全：
+- 不打印 secrets（尤其 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。

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

@@ -0,0 +1,50 @@
+---
+name: ws-commit
+description: 提交（先审计/门禁并落盘证据，再 git commit）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 提交前审计与证据落盘（`$ws-review`）
+- 提交前门禁校验与证据落盘（`aiws validate . --stamp`）
+- 最后执行 `git commit`（commit 前必须让用户确认 message；不使用 `--no-verify` 绕过 hooks）
+
+安全约束（强制）：
+- 不自动 `git add -A`（避免误提交）；只在用户明确指示时才执行 staging 命令
+- 不自动 push
+- 不写入任何 secrets
+
+执行步骤（建议）：
+1) 运行 `$ws-preflight`（确保真值文件就绪）。
+2) 运行 `$ws-review`（生成审计证据：`.agentdocs/tmp/review/codex-review.md`）。
+3) 运行门禁校验并写 stamp：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws validate . --stamp
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate . --stamp
+else
+  npx @aipper/aiws validate . --stamp
+fi
+```
+4) 检查当前 staging 状态（必须输出给用户确认）：
+```bash
+git status --porcelain
+git diff --staged
+```
+5) 若没有 staged changes：停止并提示用户先明确要提交哪些文件（例如 `git add -p` 或 `git add <path>`）。
+6) 让用户提供 commit message（必须确认后再执行）。
+7) 执行提交（不带 `--no-verify`）：
+```bash
+git commit -m "<message>"
+```
+8) 输出提交结果（可选）：
+```bash
+git show --stat --oneline -1
+```
+
+输出要求：
+- `Evidence:` `.agentdocs/tmp/review/codex-review.md` + `.agentdocs/tmp/aiws-validate/*.json`
+- `Commit:` 最终使用的 commit message（仅当用户确认后）
+

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

@@ -0,0 +1,34 @@
+---
+name: ws-dev
+description: 开发（按需求实现并验证；适用于任何需要修改代码/配置的任务）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+建议流程：
+1) 先做 preflight：定位项目根目录，读取 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`，输出约束摘要。
+   - 若是中大型任务：建议先用 `$ws-plan` 生成 `plan/` 工件，再进入实现（便于可回放与对齐验证入口）。
+2) 建立变更归因（推荐）：
+   - 推荐一键：`aiws change start <change-id> --hooks`（切分支 + 初始化变更工件 + 启用 hooks）
+   - 或手工：`git switch -c change/<change-id>`，并创建 `changes/<change-id>/proposal.md` 与 `changes/<change-id>/tasks.md`（参考 `changes/README.md`）
+3) 如涉及需求调整：先做需求评审（可用 `$ws-req-review`）→ 用户确认后再做需求落盘（可用 `$ws-req-change`）（避免需求漂移）。
+4) 实施最小改动：任何改动都要能归因到 `REQUIREMENTS.md`（验收）或 `issues/problem-issues.csv`（问题）。
+5) 运行 `AI_WORKSPACE.md` 里声明的验证命令；未运行不声称已运行。
+6) 多步任务（≥2 步）：使用 `update_plan` 工具跟踪 `pending → in_progress → completed`，每完成一步立即更新（不要事后批量更新）。
+7) 提交前强制门禁（commit/push hooks 也会阻断）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate .
+else
+  npx @aipper/aiws validate .
+fi
+```
+
+输出要求：
+- `Changed:` 文件清单
+- `Verify:` 实际运行的命令 + 期望结果
+- `Evidence:` 证据路径（例如 `plan/...`、`.agentdocs/tmp/aiws-validate/...` 或 `changes/<change-id>/...`）

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

@@ -0,0 +1,54 @@
+---
+name: ws-migrate
+description: 迁移（补齐/升级 AIWS 工作区文件）
+---
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+
+执行（在项目根目录）：
+```bash
+if [[ -f ".aiws/manifest.json" ]]; then
+  if [[ -x "./node_modules/.bin/aiws" ]]; then
+    ./node_modules/.bin/aiws update .
+  elif command -v aiws >/dev/null 2>&1; then
+    aiws update .
+  else
+    npx @aipper/aiws update .
+  fi
+else
+  if [[ -x "./node_modules/.bin/aiws" ]]; then
+    ./node_modules/.bin/aiws init .
+  elif command -v aiws >/dev/null 2>&1; then
+    aiws init .
+  else
+    npx @aipper/aiws init .
+  fi
+fi
+
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws validate .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws validate .
+else
+  npx @aipper/aiws validate .
+fi
+
+git config core.hooksPath .githooks
+```
+
+回滚（恢复最近一次快照）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws rollback . latest
+elif command -v aiws >/dev/null 2>&1; then
+  aiws rollback . latest
+else
+  npx @aipper/aiws rollback . latest
+fi
+```
+
+约束：
+- 不写入任何 secrets。
+- 不执行破坏性命令。

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

@@ -0,0 +1,39 @@
+---
+name: ws-plan
+description: 规划（生成可落盘 plan/ 工件；供 ws-dev 执行）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：
+- 对齐真值文件（`AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md`）
+- 为当前任务生成一份可追踪的执行计划文件：`plan/<timestamp>-<slug>.md`
+- 计划必须包含可复现验证命令（优先引用 `AI_WORKSPACE.md`）
+
+约束：
+- 不写入任何 secrets（token、账号、内网端点等不得进入 git）
+- 本 skill 只负责“想清楚怎么做 + 落盘计划”，不要直接大规模改动代码
+- 未运行不声称已运行；验证命令要写清“预期结果”
+
+执行步骤（建议）：
+1) 先运行 `$ws-preflight`（读取真值文件并输出约束摘要）。
+2) 若用户任务描述不清：先问 1-3 个关键澄清问题（不要猜）。
+3) 判断复杂度：`simple / medium / complex`（给出一句理由），并估算步骤数。
+4) 生成计划文件：
+   - 文件名：`plan/YYYY-MM-DD_HH-MM-SS-<slug>.md`（`<slug>` 用 kebab-case；同一任务调整计划时尽量复用同一文件）
+   - 若 `plan/` 不存在先创建
+   - 必须实际写入到磁盘（不要只在对话里输出）；如因权限/策略无法写盘，必须明确说明原因并输出可复制的完整内容
+5) 计划内容至少包含（不要留空）：
+   - `Goal`：要达成什么
+   - `Non-goals`：明确不做什么（避免 scope creep）
+   - `Scope`：将改动的文件/目录清单（不确定就写 `TBD` 并说明如何确定）
+   - `Plan`：分步执行（每步尽量落到具体文件/命令；必要时拆 Phase）
+   - `Verify`：可复现命令 + 期望结果（优先引用 `AI_WORKSPACE.md` 的入口；必要时补充 e2e）
+   - `Risks & Rollback`：风险点 + 回滚方案（例如 git 回滚、`aiws rollback`、恢复备份等）
+   - `Evidence`：计划文件路径；若创建了变更工件则附 `changes/<change-id>/...`
+6) 若计划涉及“需求/验收”变更：先用 `$ws-req-review` 评审 → 用户确认后再 `$ws-req-change` 落盘（避免需求漂移）。
+7) 多步任务（≥2 步）：后续进入实现时，使用 `update_plan` 工具跟踪 `pending → in_progress → completed`。
+
+输出要求：
+- `Plan file:` <实际写入的路径>
+- `Next:` 推荐下一步（通常是 `$ws-dev` 或 `aiws change start <change-id> --hooks`）

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

@@ -0,0 +1,29 @@
+---
+name: ws-preflight
+description: 预检（提交前快速检查与建议）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 若缺失任意真值文件：不要继续“写代码/改配置/落盘文件”。先输出缺失项，并给出下一步建议：
+   - `npx @aipper/aiws init .`（或 `aiws init .`）初始化真值文件
+   - 然后重新执行 `$ws-preflight`
+4) 输出：
+   - `Root:` <项目根路径>
+   - `Found:` <实际读取到的文件列表>
+   - `Missing:` <缺失文件列表>
+   - `Key rules:` 3–8 条 bullet（范围/禁止项/必须产物/必须验证命令）
+
+安全：
+- 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。
+- 不执行破坏性命令。

package/templates/workspace/.agents/skills/ws-req-change/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: ws-req-change
+description: 需求变更（更新 REQUIREMENTS 并同步执行合同）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `REQUIREMENTS.md` + 追加 `requirements/CHANGELOG.md`），并同步/校验执行合同 `requirements/requirements-issues.csv`。
+
+步骤（必须按顺序）：
+1) 读取：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`、`requirements/CHANGELOG.md`（缺失则创建目录与文件）。
+2) 先产出“拟变更方案”（不要立刻写文件）：
+   - 变更摘要（1–5 条）
+   - 影响范围（API/鉴权/字段/状态码/测试边界）
+   - 回滚思路（1–2 条）
+3) 强制停下来让用户确认：是否继续落盘？(Y/N)
+4) 用户确认 Y 后再写入：
+   - 更新 `REQUIREMENTS.md`（只保留当前有效版本，不在此堆历史）
+   - 追加 `requirements/CHANGELOG.md`
+5) 同步/补齐执行合同（至少做其中之一，按仓库现状选择最安全路径）：
+   - 若你维护了 FlowSpec：`python3 tools/requirements_contract_sync.py --workspace .`
+   - 否则：`python3 tools/requirements_contract.py init` 后手工补齐/新增对应 Req 行
+6) 校验（强制）：`python3 tools/requirements_contract.py validate`
+7) 建议（如维护 FlowSpec）：运行 `$ws-req-flow-sync`
+
+输出必须包含：
+- 本次更新的文件清单（路径）
+- 回滚方案（如何撤销本次需求变更）
+- 下一步建议命令
+
+安全：
+- 不打印 `secrets/test-accounts.json`
+- 不引入任何 token/密钥到仓库

package/templates/workspace/.agents/skills/ws-req-contract-sync/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ws-req-contract-sync
+description: 合同同步（requirements contract sync）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+用途：从 `REQUIREMENTS.md` 的 FlowSpec 补齐 `requirements/requirements-issues.csv`（只生成骨架，不猜测完成状态）。
+
+执行（在 workspace 根目录）：
+- `python3 tools/requirements_contract_sync.py --workspace .`
+
+输出要求：
+- 说明新增/更新了多少条
+- 明确下一步：手工补齐 CRUD/Inputs/Outputs/Business_Logic/Tests，并将可开工条目标为 `Spec_Status=READY`
+
+下一步建议：`$ws-req-contract-validate`

package/templates/workspace/.agents/skills/ws-req-contract-validate/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: ws-req-contract-validate
+description: 合同校验（requirements contract validate）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议

package/templates/workspace/.agents/skills/ws-req-flow-sync/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: ws-req-flow-sync
+description: Flow 同步（生成 api-flow 与场景执行合同）
+---
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `REQUIREMENTS.md` 的 FlowSpec 生成：
+- `docs/api-flow.mmd`（简短逻辑图，Mermaid）
+- `issues/server-scenario-issues.csv`（场景执行合同：TODO/DONE/BLOCKED）
+
+执行（在 workspace 根目录）：
+`python3 tools/requirements_flow_gen.py --workspace .`
+
+若缺少工具 `tools/requirements_flow_gen.py`：提示用户先运行 `$aiws-init`（默认会安装 optional tools），或执行：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws init .
+elif command -v aiws >/dev/null 2>&1; then
+  aiws init .
+else
+  npx @aipper/aiws init .
+fi
+```
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`

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

@@ -0,0 +1,32 @@
+---
+name: ws-req-review
+description: 需求评审（对齐真值与验收）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `REQUIREMENTS.md` 做一次整体 QA，输出缺口/冲突/风险，减少实现漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：`git rev-parse --show-toplevel`（失败则停止并让用户确认根目录）。
+2) 读取（存在则必须读取；缺失则明确列出，不要臆测）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+   - `requirements/CHANGELOG.md`（若存在）
+   - `requirements/requirements-issues.csv`（若存在）
+3) 输出固定结构的报告：
+
+## Requirements QA
+- 结论：是否可进入实现（是/否/有条件）
+- 漂移风险：最容易导致不一致的点
+- 可验收性缺口：缺少输入/输出/错误码/边界/示例的条目
+- 完整性：Non-goals/兼容性/鉴权/重试/并发/观测性/性能
+- 一致性：与 `AI_PROJECT.md` 约束冲突点
+- 可测试性与证据：最小验证命令 + 期望结果 + 证据路径
+- 风险清单：3–8 条
+- 需要澄清的问题：5–12 个（按优先级）
+
+4) 最后询问用户：是否进入需求落盘流程 `$ws-req-change`？(Y/N)
+
+安全：不打印 `secrets/test-accounts.json`。

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

@@ -0,0 +1,24 @@
+---
+name: ws-review
+description: 评审（提交前审计与证据落盘）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据落盘到 `.agentdocs/tmp/review/`。
+
+步骤（建议）：
+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`
+3) 将审计落盘到：`.agentdocs/tmp/review/codex-review.md`（目录不存在则创建）。
+4) 回复中输出：
+   - `Evidence:` 证据文件路径
+   - `Top risks:` 3–8 条（高→低）
+   - `Next:` 最小修复清单 + 最小验证命令
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。

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

@@ -0,0 +1,23 @@
+---
+name: ws-rule
+description: 规则（解释项目规则与边界）
+---
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+安全规则（强制）：
+- 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+- 不执行破坏性命令。
+
+工作流：
+1) 先做 preflight；若缺失 `AI_PROJECT.md`：提示用户先 `$ws-migrate`（或 `$aiws-init`）。
+2) 写入前创建备份（必须）：
+`ts="$(date +%Y%m%d-%H%M%S)"; mkdir -p .aiws/backups/manual; cp -a AI_PROJECT.md .aiws/backups/manual/AI_PROJECT.md.bak.${ts}`
+3) 先输出“将写入的规则清单”（3–12 条），并要求用户回复 `CONFIRM` 后再落盘。
+4) 用户确认后，**仅更新** BEGIN/END 段内内容（合并去重；写成可检查条款：目录白名单/必须验证命令/禁止项/产物要求）。
+5) 输出必须包含：
+   - 更新了哪些文件（路径）
+   - 回滚方式（恢复备份文件）
+   - 下一步建议：`$aiws-validate`