@aipper/aiws-spec 0.0.1

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

@@ -0,0 +1,36 @@
+{
+  "manifest_version": 1,
+  "template_id": "workspace",
+  "spec_version": "0.0.0",
+  "aiws_version": "0.0.0",
+  "installed_at": "1970-01-01T00:00:00Z",
+  "updated_at": "1970-01-01T00:00:00Z",
+  "tools": ["claude", "opencode", "codex", "iflow"],
+  "managed": [
+    { "path": ".githooks/pre-commit", "mode": "replace_file", "sha256": "<sha256>" },
+    { "path": ".githooks/pre-push", "mode": "replace_file", "sha256": "<sha256>" },
+    { "path": "tools/ws_change_check.py", "mode": "replace_file", "sha256": "<sha256>" },
+    { "path": "tools/requirements_contract.py", "mode": "replace_file", "sha256": "<sha256>" },
+    { "path": "AGENTS.md", "mode": "managed_blocks", "blocks": { "agents": "<sha256>" } },
+    { "path": "AI_PROJECT.md", "mode": "managed_blocks", "blocks": { "ai-project:core": "<sha256>" } },
+    { "path": "AI_WORKSPACE.md", "mode": "managed_blocks", "blocks": { "ai-workspace:core": "<sha256>" } },
+    { "path": "REQUIREMENTS.md", "mode": "managed_blocks", "blocks": { "requirements:contract": "<sha256>" } },
+    { "path": ".gitignore", "mode": "managed_blocks", "blocks": { "gitignore": "<sha256>" } },
+    { "path": ".claude/commands/aiws-init.md", "mode": "managed_blocks", "blocks": { "claude:aiws-init": "<sha256>" } },
+    { "path": ".claude/commands/aiws-update.md", "mode": "managed_blocks", "blocks": { "claude:aiws-update": "<sha256>" } },
+    { "path": ".claude/commands/aiws-validate.md", "mode": "managed_blocks", "blocks": { "claude:aiws-validate": "<sha256>" } },
+    { "path": ".claude/commands/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "claude:aiws-rollback": "<sha256>" } },
+    { "path": ".opencode/command/aiws-init.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-init": "<sha256>" } },
+    { "path": ".opencode/command/aiws-update.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-update": "<sha256>" } },
+    { "path": ".opencode/command/aiws-validate.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-validate": "<sha256>" } },
+    { "path": ".opencode/command/aiws-rollback.md", "mode": "managed_blocks", "blocks": { "opencode:aiws-rollback": "<sha256>" } },
+    { "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>" } }
+  ]
+}

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

@@ -0,0 +1,19 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-init -->
+# aiws init
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+建议执行：
+1) `npx @aipper/aiws init`
+2) `npx @aipper/aiws validate`
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件
+<!-- AIWS_MANAGED_END:claude:aiws-init -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
+

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

@@ -0,0 +1,12 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-rollback -->
+# aiws rollback
+
+目标：
+- 从 `.aiws/backups/` 恢复到某次备份快照
+
+建议执行：
+- `npx @aipper/aiws rollback latest`
+<!-- AIWS_MANAGED_END:claude:aiws-rollback -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
+

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

@@ -0,0 +1,18 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-update -->
+# aiws update
+
+目标：
+- 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+建议执行：
+1) `npx @aipper/aiws update`
+2) `npx @aipper/aiws validate`
+
+约束：
+- 不写入任何 secrets
+- 只更新托管块或 spec 指定的 `replace_file` 文件
+<!-- AIWS_MANAGED_END:claude:aiws-update -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
+

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

@@ -0,0 +1,13 @@
+<!-- AIWS_MANAGED_BEGIN:claude:aiws-validate -->
+# aiws validate
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+建议执行：
+- `npx @aipper/aiws validate`
+<!-- AIWS_MANAGED_END:claude:aiws-validate -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。
+

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

@@ -0,0 +1,27 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-analyze -->
+# ws analyze
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+
+输入：
+- 主题/需求：`$ARGUMENTS`（若为空，先问用户一句“本次分析主题是什么？”）
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 基于真值文件与当前代码现状，输出：
+   - 目标 / 非目标
+   - 现状证据（文件路径/接口路径）
+   - 推荐方案（1 个）+ 备选（可选）
+   - 风险与回滚（3–8 条）
+   - 最小验证命令（可复现）
+3) 将分析落盘到：`.agentdocs/tmp/analyze/claude-analysis.md`（目录不存在则创建）。
+4) 回复中必须包含：`Evidence:` 证据文件路径。
+
+安全：
+- 不打印 secrets（尤其 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:claude:ws-analyze -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-dev -->
+# ws dev
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+建议流程：
+1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+2) 建立变更归因（推荐）：
+   - 切分支：`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) 提交前强制：`aiws validate .`（commit/push hooks 也会阻断）。
+
+输出要求：
+- `Changed:` 文件清单
+- `Verify:` 实际运行的命令 + 期望结果
+- `Evidence:` 证据路径（例如 `.agentdocs/tmp/...` 或 `changes/<change-id>/...`）
+<!-- AIWS_MANAGED_END:claude:ws-dev -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,22 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-migrate -->
+# ws migrate
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+
+执行（在项目根目录）：
+1) 若已存在 `.aiws/manifest.json`：`npx @aipper/aiws update .`
+2) 否则：`npx @aipper/aiws init .`
+3) 门禁校验：`npx @aipper/aiws validate .`
+4) 启用本机 git hooks（推荐，本地生效）：`git config core.hooksPath .githooks`
+
+回滚：
+- 恢复最近一次快照：`npx @aipper/aiws rollback . latest`
+
+约束：
+- 不写入任何 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:claude:ws-migrate -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,27 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-preflight -->
+# ws preflight
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始任何“写代码/改配置/落盘文件”之前，对齐工作区真值文件，避免规则漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：停止并让用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 输出：
+   - `Root:` <项目根路径>
+   - `Found:` <实际读取到的文件列表>
+   - `Missing:` <缺失文件列表>
+   - `Key rules:` 3–8 条 bullet（范围/禁止项/必须产物/必须验证命令）
+
+安全：
+- 不打印 secrets；遇到疑似敏感值只提示“存在风险”但不要复述原文。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:claude:ws-preflight -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-req-change.md

@@ -0,0 +1,34 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-req-change -->
+# ws req change
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `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/密钥到仓库
+<!-- AIWS_MANAGED_END:claude:ws-req-change -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-req-contract-sync.md

@@ -0,0 +1,18 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-req-contract-sync -->
+# ws req 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`
+<!-- AIWS_MANAGED_END:claude:ws-req-contract-sync -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-req-contract-validate.md

@@ -0,0 +1,13 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-req-contract-validate -->
+# ws req contract validate
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 后重试）：
+- `python3 tools/requirements_contract.py validate`
+
+输出要求：
+- 若失败：列出前 20 条缺失字段（Req_ID + field），并给出最小补齐建议
+<!-- AIWS_MANAGED_END:claude:ws-req-contract-validate -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.claude/commands/ws-req-flow-sync.md

@@ -0,0 +1,20 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-req-flow-sync -->
+# ws req flow sync
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：基于 `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`：提示用户先运行 `npx @aipper/aiws init .`（默认会安装 optional tools）。
+
+输出要求：只打印生成的文件路径与下一步命令：
+- 查看逻辑图：`cat docs/api-flow.mmd`
+- 查看场景合同：`cat issues/server-scenario-issues.csv`
+<!-- AIWS_MANAGED_END:claude:ws-req-flow-sync -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,33 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-req-review -->
+# ws req review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对 `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`。
+<!-- AIWS_MANAGED_END:claude:ws-req-review -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,25 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-review -->
+# ws review
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在提交/交付前审计当前改动，对照真值文件检查是否越界，并把审计证据落盘到 `.agentdocs/tmp/review/`。
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 基于 `git status` / `git diff`（以及你实际运行过的测试结果），对照 `AI_PROJECT.md` 与 `REQUIREMENTS.md` 检查：
+   - 是否存在越界目录改动/危险操作
+   - 是否有可复现验证命令与证据
+   - 是否维护了 `changes/<change-id>/` 或相关 `issues/*.csv`
+3) 将审计落盘到：`.agentdocs/tmp/review/claude-review.md`（目录不存在则创建）。
+4) 回复中输出：
+   - `Evidence:` 证据文件路径
+   - `Top risks:` 3–8 条（高→低）
+   - `Next:` 最小修复清单 + 最小验证命令
+
+安全：
+- 不打印 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:claude:ws-review -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

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

@@ -0,0 +1,24 @@
+<!-- AIWS_MANAGED_BEGIN:claude:ws-rule -->
+# ws rule
+
+     用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+     目标：把用户口述的“项目特有规则”整理成可执行条款，并写入 `AI_PROJECT.md` 的 `AI_PROJECT_RULES_BEGIN/END` 段（托管块外内容会被保留）。
+
+     安全规则（强制）：
+     - 不打印/不写入 secrets（token、密钥、内网地址、账号密码）。
+     - 不执行破坏性命令。
+
+     工作流：
+     1) 先运行 `/ws-preflight`；若缺失 `AI_PROJECT.md`：提示用户先 `/ws-migrate` 或运行 `npx @aipper/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 .`
+<!-- AIWS_MANAGED_END:claude:ws-rule -->
+
+可在下方追加本项目对 Claude Code 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/aiws-init.md

@@ -0,0 +1,23 @@
+---
+description: 初始化工作区（生成真值文件与门禁）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:aiws-init -->
+# aiws init
+
+目标：
+- 生成/补齐真值文件与门禁文件（以 `AI_PROJECT.md` / `REQUIREMENTS.md` / `AI_WORKSPACE.md` 为准）
+- 写入/更新 `.gitignore` 的 aiws 托管块
+- 生成/更新 `.aiws/manifest.json`（用于漂移检测）
+
+建议执行：
+1) `npx @aipper/aiws init`
+2) `npx @aipper/aiws validate`
+
+约束：
+- 不写入任何 secrets
+- 只允许更新托管块（`AIWS_MANAGED_BEGIN/END`）或 spec 指定的 `replace_file` 文件
+<!-- AIWS_MANAGED_END:codex:aiws-init -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/aiws-rollback.md

@@ -0,0 +1,16 @@
+---
+description: 回滚工作区（从备份恢复）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:aiws-rollback -->
+# aiws rollback
+
+目标：
+- 从 `.aiws/backups/` 恢复到某次备份快照
+
+建议执行：
+- `npx @aipper/aiws rollback latest`
+<!-- AIWS_MANAGED_END:codex:aiws-rollback -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/aiws-update.md

@@ -0,0 +1,22 @@
+---
+description: 更新工作区（刷新模板与托管块）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:aiws-update -->
+# aiws update
+
+目标：
+- 基于当前 `@aipper/aiws-spec` 刷新模板与 tool-native 文件
+- 更新前备份到 `.aiws/backups/<timestamp>/`
+
+建议执行：
+1) `npx @aipper/aiws update`
+2) `npx @aipper/aiws validate`
+
+约束：
+- 不写入任何 secrets
+- 只更新托管块或 spec 指定的 `replace_file` 文件
+<!-- AIWS_MANAGED_END:codex:aiws-update -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/aiws-validate.md

@@ -0,0 +1,17 @@
+---
+description: 校验工作区（漂移检测 + 门禁）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:aiws-validate -->
+# aiws validate
+
+目标：
+- 作为 CI/本地门禁：校验 required 文件结构、托管块、`.aiws/manifest.json` 漂移
+- 强门禁：缺 `python3`/缺 required 脚本也应失败
+
+建议执行：
+- `npx @aipper/aiws validate`
+<!-- AIWS_MANAGED_END:codex:aiws-validate -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-analyze.md

@@ -0,0 +1,32 @@
+---
+description: 分析（定位问题与收集上下文）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:ws-analyze -->
+# ws analyze
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始实现/修复前做一次技术分析，产出可执行的最小行动清单，并把证据落盘到 `.agentdocs/tmp/analyze/`。
+
+输入：
+- 主题/需求：`$ARGUMENTS`（若为空，先问用户一句“本次分析主题是什么？”）
+
+步骤（建议）：
+1) 先运行 `/ws-preflight`。
+2) 基于真值文件与当前代码现状，输出：
+   - 目标 / 非目标
+   - 现状证据（文件路径/接口路径）
+   - 推荐方案（1 个）+ 备选（可选）
+   - 风险与回滚（3–8 条）
+   - 最小验证命令（可复现）
+3) 将分析落盘到：`.agentdocs/tmp/analyze/codex-analysis.md`（目录不存在则创建）。
+4) 回复中必须包含：`Evidence:` 证据文件路径。
+
+安全：
+- 不打印 secrets（尤其 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:codex:ws-analyze -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-dev.md

@@ -0,0 +1,29 @@
+---
+description: 开发（按需求实现并验证）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:ws-dev -->
+# ws dev
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在 AIWS 约束下完成一个可回放、可验证的小步交付。
+
+建议流程：
+1) 先运行 `/ws-preflight`（读真值文件并输出约束摘要）。
+2) 建立变更归因（推荐）：
+   - 切分支：`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) 提交前强制：`aiws validate .`（commit/push hooks 也会阻断）。
+
+输出要求：
+- `Changed:` 文件清单
+- `Verify:` 实际运行的命令 + 期望结果
+- `Evidence:` 证据路径（例如 `.agentdocs/tmp/...` 或 `changes/<change-id>/...`）
+<!-- AIWS_MANAGED_END:codex:ws-dev -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-migrate.md

@@ -0,0 +1,27 @@
+---
+description: 迁移（补齐/升级 AIWS 工作区文件）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:ws-migrate -->
+# ws migrate
+
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把当前仓库补齐为 aiws workspace 模板，并启用可验证门禁。
+
+执行（在项目根目录）：
+1) 若已存在 `.aiws/manifest.json`：`npx @aipper/aiws update .`
+2) 否则：`npx @aipper/aiws init .`
+3) 门禁校验：`npx @aipper/aiws validate .`
+4) 启用本机 git hooks（推荐，本地生效）：`git config core.hooksPath .githooks`
+
+回滚：
+- 恢复最近一次快照：`npx @aipper/aiws rollback . latest`
+
+约束：
+- 不写入任何 secrets。
+- 不执行破坏性命令。
+<!-- AIWS_MANAGED_END:codex:ws-migrate -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。

package/templates/workspace/.codex/prompts/ws-preflight.md

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

package/templates/workspace/.codex/prompts/ws-req-change.md

@@ -0,0 +1,39 @@
+---
+description: 需求变更（更新 REQUIREMENTS 并同步执行合同）
+argument-hint: ""
+---
+
+<!-- AIWS_MANAGED_BEGIN:codex:ws-req-change -->
+# ws req change
+
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：记录需求变更（更新 `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/密钥到仓库
+<!-- AIWS_MANAGED_END:codex:ws-req-change -->
+
+可在下方追加本项目对 Codex 的额外说明（托管块外内容会被保留）。