@aipper/aiws-spec 0.0.1

package/templates/workspace/.iflow/commands/ws-feature-plan.toml

@@ -0,0 +1,47 @@
+# Command: ws:feature-plan
+# Description: 规划跨子项目的交付（需求 -> 代码 -> 测试 -> Review -> 提交）
+# Category: workspace
+# Version: 1
+
+description = "规划跨子项目的交付（需求 -> 代码 -> 测试 -> Review -> 提交）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在“目录A工作区”（可能包含 server/web/app 等多个 submodule 目录）为本次需求变更产出一个可执行计划，并把计划落到可追踪的执行合同里。
+
+输入（按优先级读取）：
+- REQUIREMENTS.md：需求与验收标准（唯一真值来源）
+- AI_WORKSPACE.md：工作区结构、目录发现、policy（environment/base_url_allowlist 等）、启动/测试覆盖方式
+- docs/openapi.json（若涉及服务端 API）
+
+进行中项目（必须先做，不允许“从零假设”）：
+1) 代码现状盘点：扫描当前工作区（server/web/app）已有实现与现有接口（OpenAPI/路由/关键模块）。
+2) 需求对比：将 REQUIREMENTS.md 的目标逐项映射到“已有/缺失/部分完成”，并给证据（文件路径/接口路径）。
+3) 只为“缺失/部分完成”的项创建 issues；已有项要么标 DONE（需有证据），要么标 SKIP（说明理由）。
+
+输出必须包含：
+1) GOALS / NON-GOALS（必须与 REQUIREMENTS.md 一致）
+2) 影响范围（按 subproject 列出：server/web/app；给出候选目录与识别依据）
+3) 执行合同（写入/维护这些文件）：
+   - issues/feature-issues.csv：任务分解（TODO/DOING/DONE/BLOCKED/SKIP）
+   - （如涉及 API）issues/server-api-issues.csv：接口验收合同（由 runner 维护）
+4) 测试策略（按 subproject）：
+   - server：优先 runner（uv），并遵守 AI_WORKSPACE.md policy（base_url_allowlist/allow_mutations）
+   - web/app：优先使用 AI_WORKSPACE.md 指定的 *_test_cmd；若缺失则基于常见标记提出建议但不臆测结果
+   - 工具链准备：如果 AI_WORKSPACE.md 定义了 toolchain_bootstrap_cmd / node_use_cmd / java_use_cmd，必须在 build/test 前执行
+5) 风险/边界：
+    - 不改需求语义；需求不清先补 REQUIREMENTS.md（只补可验收字段）
+    - 需求变更必须通过 `/ws-req-change` 处理，并写入 `requirements/CHANGELOG.md`，再同步 issues 执行合同
+    - 不触发破坏性数据操作（除非 environment=test 且 allow_mutations=true 且 REQUIREMENTS 明确允许）
+6) 回滚方案（按 submodule/根仓库分别写）
+7) 完成条件：满足 REQUIREMENTS.md 的验收 + 所有相关测试通过 + 无未解释错误日志
+
+执行合同 CSV（必须创建或更新）：
+- 文件：issues/feature-issues.csv
+- 列（固定）：Issue_ID, Subproject, Title, Files, Tests, Status, Notes
+- Status：TODO | DOING | DONE | BLOCKED | SKIP
+
+最后给出下一步命令（建议）：
+- 运行交付闭环：`/ws-feature-deliver`
+"""

package/templates/workspace/.iflow/commands/ws-init.toml

@@ -0,0 +1,53 @@
+# Command: ws:init
+# Description: 初始化当前目录为 workspace-A（AI_WORKSPACE/REQUIREMENTS/tools/secrets 示例）
+# Category: workspace
+# Version: 1
+
+description = "初始化当前目录为 workspace-A（AI_WORKSPACE/REQUIREMENTS/tools/secrets 示例）"
+
+prompt = """
+用中文输出；命令与路径保持原样不翻译。
+
+目标：把“当前目录”初始化为 aiws `workspace` 模板（真值文件 + 门禁 + tool-native commands）。
+
+约束：
+- 不创建/不打印真实 secrets；只生成 `secrets/test-accounts.example.json` 示例文件。
+- 默认不做破坏性操作。
+
+执行：
+!{bash -lc '
+set -euo pipefail
+
+root="$(pwd)"
+
+run_aiws() {
+  local subcmd="$1"
+  shift
+
+  if [[ -x "$root/node_modules/.bin/aiws" ]]; then
+    "$root/node_modules/.bin/aiws" "$subcmd" "$@"
+    return 0
+  fi
+  if command -v aiws >/dev/null 2>&1; then
+    aiws "$subcmd" "$@"
+    return 0
+  fi
+  if command -v npx >/dev/null 2>&1; then
+    npx -y @aipper/aiws "$subcmd" "$@"
+    return 0
+  fi
+
+  echo "error: aiws not found (install @aipper/aiws or ensure npx is available)" >&2
+  exit 2
+}
+
+run_aiws init .
+run_aiws validate .
+
+echo "下一步:"
+echo "  - 启用本机 hooks：git config core.hooksPath .githooks"
+echo "  - 如启用了 iFlow pre_tool_guard：执行 /ws-contract-check（写入 stamp）"
+echo "  - 创建 secrets：cp -n secrets/test-accounts.example.json secrets/test-accounts.json"
+echo "  - 重新运行门禁：aiws validate ."
+'}
+"""

package/templates/workspace/.iflow/commands/ws-memory-bank-init.toml

@@ -0,0 +1,100 @@
+# Command: ws:memory-bank-init
+# Description: 初始化 memory-bank/（用于固定上下文，避免会话跑偏）
+# Category: workspace
+# Version: 1
+
+description = "初始化 memory-bank/（用于固定上下文，避免会话跑偏）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在当前 git workspace 根目录创建/更新 `memory-bank/` 的模板文件（非需求真值），用于固定工程上下文。
+
+执行：
+!{bash -lc '
+set -euo pipefail
+
+ws_root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$ws_root"
+
+mkdir -p memory-bank
+
+write_if_missing() {
+  local p="$1"
+  shift
+  if [[ -f "$p" ]]; then
+    echo "OK: exists: $p"
+    return 0
+  fi
+  mkdir -p "$(dirname "$p")"
+  cat >"$p" <<EOF
+$*
+EOF
+  echo "OK: created: $p"
+}
+
+write_if_missing "memory-bank/README.md" "# Memory Bank（工作区上下文）
+
+目的：给 iFlow/Codex/Claude 一个“固定且可持续更新”的上下文集合，避免每次会话重新讲一遍导致跑偏。
+
+在你的工作区中：
+- \`REQUIREMENTS.md\` 仍是**需求真值**（不要复制到这里）。
+- \`AI_PROJECT.md\` / \`AI_WORKSPACE.md\` 是**边界与运行真值**。
+- 本目录补齐的是“实现过程中的稳定上下文”（更偏工程视角）。
+
+建议规则：
+- 改代码前：先看 \`REQUIREMENTS.md\` + \`AI_PROJECT.md\` + \`AI_WORKSPACE.md\`，再结合本目录的 \`architecture.md\`/\`progress.md\`。
+- 每次完成一个可验证的小步：更新 \`progress.md\`（写清：做了什么、证据路径、下一步）。
+- 发生重大结构变化：更新 \`architecture.md\`（只写高层关系，不要堆细节）。
+"
+
+write_if_missing "memory-bank/tech-stack.md" "# Tech Stack
+
+填写原则：只写“确实在用且影响决策”的信息，避免长篇大论。
+
+建议包含：
+- 语言/运行时版本（例如 Java/Node/Python）
+- 构建工具链（Gradle/Maven、pnpm、uv 等）
+- 关键框架与约束（Spring Boot、Ktor、Vue、React 等）
+- 数据层（DB/Redis/MQ）与迁移方式
+- 本地/测试环境切换方式（引用 \`AI_WORKSPACE.md\` 的命令即可）
+"
+
+write_if_missing "memory-bank/architecture.md" "# Architecture
+
+目标：记录“模块关系与关键边界”，让新的会话可以快速对齐代码布局。
+
+建议包含：
+- 目录/模块分层（例如 server/web/app）
+- 核心数据流（请求入口 → service → repo → DB）
+- 关键约束（鉴权、request-id、幂等、事务）
+"
+
+write_if_missing "memory-bank/implementation-plan.md" "# Implementation Plan
+
+目标：把需求拆成可验证的小步（每步都有验证命令与期望结果）。
+
+模板（示例字段）：
+- Step 1: …
+  - Scope:
+  - Files:
+  - Verify: \`...\`
+  - Expected:
+"
+
+write_if_missing "memory-bank/progress.md" "# Progress
+
+每次完成一个可验证小步就追加一条：
+
+- YYYY-MM-DD HH:MM: 做了什么（关联 Issue_ID/验收项）
+  - Changed: \`path/to/file\`
+  - Verify: \`command\`
+  - Evidence: \`path/to/log_or_report\`
+  - Next:
+"
+'}
+
+说明：
+- `REQUIREMENTS.md` 仍是需求真值；不要把需求复制进 memory-bank。
+- 建议完成后立刻执行：`/ws-contract-check`（让 pre_tool_guard 放行写入类工具）。
+"""

package/templates/workspace/.iflow/commands/ws-migrate.toml

@@ -0,0 +1,59 @@
+# Command: ws:migrate
+# Description: 将当前目录迁移到最新的 workspace-A 约定（安全，默认不覆盖）
+# Category: workspace
+# Version: 1
+
+description = "迁移当前目录为 workspace-A 约定（补齐 AI_PROJECT.md 与 .gitignore managed block，默认不覆盖）"
+
+prompt = """
+用中文输出；命令与路径保持原样不翻译。
+
+目标：将“当前目录”迁移/补齐为最新的 aiws `workspace` 约定（以 `.aiws/manifest.json` 与模板托管面为准）。
+
+安全规则：
+- 不要打印 secrets；不要创建真实 secrets。
+- 只通过 `aiws init/update/validate` 更新托管面（replace_file + managed blocks）。
+
+迁移完成后建议运行 `/ws-doctor` 并手工检查 `AI_PROJECT.md` 的“项目特有规则”段是否符合本项目约束。
+
+Execute:
+!{bash -lc '
+set -euo pipefail
+
+root="$(pwd)"
+
+run_aiws() {
+  local subcmd="$1"
+  shift
+
+  if [[ -x "$root/node_modules/.bin/aiws" ]]; then
+    "$root/node_modules/.bin/aiws" "$subcmd" "$@"
+    return 0
+  fi
+  if command -v aiws >/dev/null 2>&1; then
+    aiws "$subcmd" "$@"
+    return 0
+  fi
+  if command -v npx >/dev/null 2>&1; then
+    npx -y @aipper/aiws "$subcmd" "$@"
+    return 0
+  fi
+
+  echo "error: aiws not found (install @aipper/aiws or ensure npx is available)" >&2
+  exit 2
+}
+
+if [[ -f ".aiws/manifest.json" ]]; then
+  run_aiws update .
+else
+  run_aiws init .
+fi
+run_aiws validate .
+
+echo
+echo "下一步:"
+echo "  - 运行: /ws-doctor"
+echo "  - 手工检查: AI_PROJECT.md（把本项目的特殊约束补齐进去）"
+echo "  - 如启用了 iFlow pre_tool_guard：执行 /ws-contract-check（写入 stamp）"
+'}
+"""

package/templates/workspace/.iflow/commands/ws-preflight.toml

@@ -0,0 +1,30 @@
+# Command: ws:preflight
+# Description: AI Workspace 预检：读 AI_PROJECT/REQUIREMENTS/AI_WORKSPACE 并输出约束摘要
+# Category: workspace
+# Version: 1
+
+description = "AI Workspace 预检：读 AI_PROJECT/REQUIREMENTS/AI_WORKSPACE 并输出约束摘要"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在开始“写代码/改配置/给补丁”之前，先把工作区真值文件读全并对齐，避免规则漂移。
+
+执行步骤（强制）：
+1) 定位项目根目录：
+   - 优先：`git rev-parse --show-toplevel`
+   - 若失败：说明无法判断项目根；请用户确认当前目录是否为项目根（不要猜测）。
+2) 在项目根目录读取以下文件（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+3) 输出：
+   - `Root:` <项目根路径>
+   - `Found:` 列出实际读取到的文件列表
+   - `Missing:` 列出缺失文件（若缺失 `AI_PROJECT.md`，建议用户先运行 `/ws-migrate` 或 `/aiws-init` 补齐）
+   - `Key rules:` 用 3–8 条 bullet 摘要关键约束（范围/禁止项/必须产物/必须验证命令）
+
+安全规则：
+- 不打印 secrets；遇到疑似敏感值仅提示并建议迁移到本地私密文件（不要复述原文）。
+- 不执行破坏性命令。
+"""

package/templates/workspace/.iflow/commands/ws-req-change.toml

@@ -0,0 +1,52 @@
+# Command: ws:req-change
+# Description: 记录需求变更到 requirements/CHANGELOG.md 并更新 REQUIREMENTS.md
+# Category: requirements
+# Version: 1
+
+description = "记录需求变更到 requirements/CHANGELOG.md 并更新 REQUIREMENTS.md"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：处理“进行中的需求变更”，并把变更记录到独立的变更文件中，避免 REQUIREMENTS.md 的历史被覆盖。
+
+约定：
+- `REQUIREMENTS.md`：当前有效需求（唯一真值）
+- `requirements/CHANGELOG.md`：需求变更历史（追加记录，不改旧记录）
+- `requirements/requirements-issues.csv`：需求拆解执行合同（机器可读；用于审核/回放/状态机）
+
+步骤（必须按顺序）：
+1) 读取 `REQUIREMENTS.md` 与 `requirements/CHANGELOG.md`（若不存在则创建 changelog 文件与目录）
+2) 明确本次变更的类型：
+   - Clarify：补充不清晰的验收字段（不改变语义）
+   - Change：修改/新增/删除需求（改变语义）
+3) 产出“变更摘要”（1-5 条）并在执行前确认边界：
+   - 是否影响 API（OpenAPI/状态码/鉴权/字段）
+   - 是否影响自动化测试边界（allow_mutations/dangerous_disabled/base_url_allowlist）
+4) 更新 `REQUIREMENTS.md`（只留下当前有效版本；不要在文件中堆历史表格）
+5) 追加一条 changelog 记录到 `requirements/CHANGELOG.md`（必须包含：日期、变更内容、原因、影响范围、关联 issues/PR、记录人）
+6) 需求拆解到 CSV 执行合同（强制）：
+   - 确保存在 `requirements/requirements-issues.csv`（若无则初始化）：
+     - `python3 tools/requirements_contract.py init`
+   - 为本次变更新增/更新 1..N 条 Req 行，并拆到“可实现、可测试”的粒度：
+     - 每条至少写清：CRUD、Scenario、Inputs、Outputs、Business_Logic、Tests
+     - 状态机：
+       - `Spec_Status`: DRAFT(未完善)/READY(已完善可开工)
+       - `Impl_Status`: TODO/DOING/DONE/BLOCKED/SKIP
+   - 完成后必须跑一次校验（READY/DONE 的必填字段会被检查）：
+     - `python3 tools/requirements_contract.py validate`
+7) 同步执行合同（至少做到其中之一）：
+   - 更新 `issues/feature-issues.csv`（新增/调整对应任务，并关联 Req_ID）
+   - 若涉及 API：运行/更新 runner 产物并修正 `issues/server-api-issues.csv` 的验收字段
+8) 生成简短逻辑图与场景执行合同（强烈建议，每次变更后都做）：
+   - 运行 `/ws-req-flow-sync` 生成/更新 `docs/api-flow.mmd` 与 `issues/server-scenario-issues.csv`
+
+输出必须包含：
+- 本次更新的文件清单（路径）
+- 回滚方案（如何撤销本次需求变更）
+- 下一步建议命令（至少包含：`/ws-req-flow-sync`；以及 `/server-fix` 或 runner 命令）
+
+安全规则：
+- 不打印 secrets/test-accounts.json
+- 不引入任何 token/密钥到仓库
+"""

package/templates/workspace/.iflow/commands/ws-req-contract-sync.toml

@@ -0,0 +1,25 @@
+# Command: ws:req-contract-sync
+# Description: 从 REQUIREMENTS.md 的 FlowSpec 补齐 requirements/requirements-issues.csv（半自动）
+# Category: requirements
+# Version: 1
+
+description = "从 REQUIREMENTS.md 的 FlowSpec 补齐 requirements/requirements-issues.csv（半自动）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+用途：当项目已经做了一部分，但 `requirements/requirements-issues.csv` 还没建立/没补齐时，用本命令从 `REQUIREMENTS.md` 的 FlowSpec（机器可读）生成/补齐需求条目骨架。
+
+说明：
+- 本命令只做“补齐骨架”：把每条 Flow 变成一条 Req（默认 `Spec_Status=DRAFT`、`Impl_Status=TODO`），不会猜测你已完成哪些。
+- 生成后请手工补齐 CRUD/Inputs/Outputs/Business_Logic/Tests，并把可开工的条目标为 `Spec_Status=READY`。
+
+执行：
+!{bash -lc '
+set -euo pipefail
+python3 tools/requirements_contract_sync.py --workspace .
+'}
+
+下一步：
+- 运行：`/ws-req-contract-validate`
+"""

package/templates/workspace/.iflow/commands/ws-req-contract-validate.toml

@@ -0,0 +1,16 @@
+# Command: ws:req-contract-validate
+# Description: 校验 requirements/requirements-issues.csv（READY/DONE 必填字段）
+# Category: requirements
+# Version: 1
+
+description = "校验 requirements/requirements-issues.csv（READY/DONE 必填字段）"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+执行（失败则修正 CSV 再重试）：
+!{bash -lc '
+set -euo pipefail
+python3 tools/requirements_contract.py validate
+'}
+"""

package/templates/workspace/.iflow/commands/ws-req-flow-sync.toml

@@ -0,0 +1,36 @@
+# Command: ws:req-flow-sync
+# Description: 从 REQUIREMENTS.md FlowSpec 生成流程图与场景 CSV
+# Category: requirements
+# Version: 1
+
+description = "从 REQUIREMENTS.md FlowSpec 生成流程图与场景 CSV"
+
+prompt = """
+用中文输出；命令与路径保持原样不翻译。
+
+目标：在工作区根目录基于 `REQUIREMENTS.md` 内的 FlowSpec（FLOW_SPEC_BEGIN/END 标记）生成：
+- `docs/api-flow.mmd`（简短逻辑图，Mermaid）
+- `issues/server-scenario-issues.csv`（场景执行合同：TODO/DONE/BLOCKED）
+
+要求：
+- 不读取/不打印 secrets
+- 输出要短：只打印生成的文件路径与下一步命令
+
+Execute:
+!{bash -lc '
+set -euo pipefail
+
+[[ -f REQUIREMENTS.md ]] || { echo "缺少 REQUIREMENTS.md（请先 /aiws-init 或补齐需求文件）" >&2; exit 2; }
+
+if [[ -f tools/requirements_flow_gen.py ]]; then
+  python3 tools/requirements_flow_gen.py --workspace .
+  echo ""
+  echo "下一步:"
+  echo "  - 查看逻辑图: cat docs/api-flow.mmd"
+  echo "  - 查看场景合同: cat issues/server-scenario-issues.csv"
+else
+  echo "缺少工具: tools/requirements_flow_gen.py（建议运行 /aiws-init 或从模板复制）" >&2
+  exit 2
+fi
+'}
+"""

package/templates/workspace/.iflow/commands/ws-req-review.toml

@@ -0,0 +1,56 @@
+# Command: ws:req-review
+# Description: 需求整体评估（不落盘）：对 REQUIREMENTS.md 做 QA，输出缺口/冲突/风险，减少漂移
+# Category: requirements
+# Version: 1
+
+description = "需求整体评估（不落盘）：对 REQUIREMENTS.md 做 QA，输出缺口/冲突/风险，减少漂移"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在不修改任何文件的前提下，对“当前整体需求”做一次质量评估（Requirements QA），提前发现不清晰/不可验收/与项目约束冲突的点，减少后续实现漂移。
+
+执行步骤（必须按顺序）：
+1) 定位项目根目录（优先 `git rev-parse --show-toplevel`；失败则停止并让用户确认根目录）。
+2) 在项目根目录读取（存在则必须读取；缺失则明确报告缺失项，不要臆测内容）：
+   - `AI_PROJECT.md`
+   - `REQUIREMENTS.md`
+   - `AI_WORKSPACE.md`
+   - `requirements/CHANGELOG.md`（若存在）
+   - `requirements/requirements-issues.csv`（若存在）
+3) 输出一个固定结构的评估报告（Markdown）：
+
+## Requirements QA
+
+### 1) 结论（1–3 行）
+- 当前需求是否“可进入实现阶段”？（是/否/有条件）
+
+### 2) 漂移风险（必须列出）
+- 哪些点最容易导致实现与需求不一致？为什么？
+
+### 3) 可验收性（必须列出）
+- 列出“缺少明确验收标准”的条目（输入/输出/错误码/边界条件/示例）。
+
+### 4) 完整性（必须列出）
+- 是否缺少：Non-goals、兼容性/迁移、鉴权/权限、失败重试、并发/幂等、观测性（日志/trace/request-id）、性能预算。
+
+### 5) 一致性（必须列出）
+- 与 `AI_PROJECT.md`（禁止项/产物要求/验证要求/边界）是否冲突？逐条列冲突与建议。
+
+### 6) 可测试性与证据（必须列出）
+- 给出最小验证路径（命令 + 期望结果 + 证据落盘路径建议，例如 `.agentdocs/tmp/...`）。
+
+### 7) 风险清单（3–8 条）
+- 风险 → 影响面 → 缓解建议（尽量可操作）。
+
+### 8) 需要澄清的问题（优先级排序）
+- 用 5–12 个问题把不确定点一次问清（每题说明“为什么要问/影响什么验收”）。
+
+4) **强制停下来询问用户确认**：
+   - 问用户：**“是否基于上述评估进入需求落盘/变更流程 `/ws-req-change`？(Y/N)”**
+   - 若 N：停止，等待用户补充信息或调整需求文本。
+
+边界：
+- 不打印任何 secrets（尤其是 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+"""

package/templates/workspace/.iflow/commands/ws-review.toml

@@ -0,0 +1,32 @@
+# Command: ws:review
+# Description: AI Workspace 交叉审计交付（Claude + Codex + Gemini），证据落盘到 .agentdocs/tmp/review/
+# Category: workspace
+# Version: 1
+
+description = "AI Workspace 交叉审计交付（Claude + Codex + Gemini），证据落盘到 .agentdocs/tmp/review/"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：在实现/提交前，对当前工作区改动进行交叉审计，并把审计结论落盘到 `.agentdocs/tmp/review/`，便于回放与追责。
+
+强制步骤：
+1) 读取真值文件：`AI_PROJECT.md`、`REQUIREMENTS.md`、`AI_WORKSPACE.md`。
+2) 若 iFlow 拦截写入：先执行 `/ws-contract-check`，再继续。
+3) 审计输入（按优先级）：
+   - `git diff`（或变更工件 `changes/<change-id>/`）
+   - `issues/*.csv`（状态机是否存在 TODO/DOING/BLOCKED）
+   - 最近一次门禁输出（如 `aiws validate .`）
+4) 输出（必须）：
+   - Findings：问题清单（按严重性排序，引用具体文件路径）
+   - Risks：3–8 条
+   - Next：最小修复清单 + 最小验证命令
+5) 证据落盘（必须）：
+   - 在 `.agentdocs/tmp/review/` 写入一份 `review.<timestamp>.md`
+6) 如果目标是提交前门禁：
+   - 建议运行：`aiws validate .`（或 `npx @aipper/aiws validate .`）
+
+边界：
+- 不打印任何 secrets（尤其是 `secrets/test-accounts.json`）。
+- 不执行破坏性命令。
+"""

package/templates/workspace/.iflow/commands/ws-rule.toml

@@ -0,0 +1,43 @@
+# Command: ws:rule
+# Description: 整理项目规则写入 AI_PROJECT.md 的 managed block
+# Category: workspace
+# Version: 1
+
+description = "整理项目规则写入 AI_PROJECT.md 的 managed block"
+
+prompt = """
+用中文输出（命令/路径/代码标识符保持原样不翻译）。
+
+目标：当用户提出“项目规则/约束/边界”时，将其整理为结构化条款，并写入工作区根目录的 `AI_PROJECT.md`。
+
+约定真值：
+- `AI_PROJECT.md`：项目约束真值（本命令只维护其中的 managed block）
+- `REQUIREMENTS.md`：需求真值（本命令不改需求）
+- `AI_WORKSPACE.md`：运行/测试真值（本命令不改运行方式）
+
+安全规则（强制）：
+- 不打印 secrets；不把 token/密钥/内网地址写入 `AI_PROJECT.md`。
+- 不进行破坏性命令。
+- 写入前必须创建备份：`.aiws/backups/manual/AI_PROJECT.md.bak.<timestamp>`
+
+写入位置（强制）：
+- 仅修改 `AI_PROJECT.md` 中 `<!-- AI_PROJECT_RULES_BEGIN -->` 与 `<!-- AI_PROJECT_RULES_END -->` 之间的内容。
+- 若文件/标记不存在：先运行 `/aiws-init`（或 `aiws init .`）补齐模板，再继续。
+
+工作流：
+1) 读取（或创建）`AI_PROJECT.md`，并定位 managed block。
+2) 如果用户还没给出明确的规则文本：最多问 3 个澄清问题（例如：允许改动目录白名单/必须跑哪些测试/是否允许有副作用接口/是否允许自动提交）。
+3) 将用户输入整理为短而硬的条款（建议按以下结构）：
+   - 范围/目录白名单
+   - 必须执行的验证命令（含期望结果）
+   - 禁止项（危险操作/敏感文件/越界访问）
+   - 交付产物（必须更新哪些文件：issues/证据/文档）
+4) 更新 managed block：合并去重（同义合并）、保持条款可执行；避免重写文件其它部分。
+4.1) 写入前必须复述“将写入的规则清单”，并要求用户回复 `CONFIRM` 后再落盘（避免误写/误删）。
+5) 输出必须包含：
+   - 更新了哪些文件（路径）
+   - 回滚方式（恢复备份文件）
+   - 下一步建议（例如运行 `/ws-doctor`）
+
+提示：用户的“规则”可能零散，优先把它们变成可检查的条款（能落到命令/文件/目录）。
+"""

package/templates/workspace/.opencode/command/aiws-init.md

@@ -0,0 +1,19 @@
+<!-- AIWS_MANAGED_BEGIN:opencode: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:opencode:aiws-init -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/.opencode/command/aiws-rollback.md

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

package/templates/workspace/.opencode/command/aiws-update.md

@@ -0,0 +1,18 @@
+<!-- AIWS_MANAGED_BEGIN:opencode: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:opencode:aiws-update -->
+
+可在下方追加本项目对 OpenCode 的额外说明（托管块外内容会被保留）。
+

package/templates/workspace/.opencode/command/aiws-validate.md

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

package/templates/workspace/.opencode/command/ws-analyze.md

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