@aipper/aiws-spec 0.0.1

package/README.md

@@ -0,0 +1,12 @@
+# @aipper/aiws-spec
+
+本包存放 aiws 的规范与模板（单一真值来源）。
+
+当前已从 dotfiles 复制一份 AI Workspace 模板到：
+- `templates/workspace/`
+
+后续 `@aipper/aiws` CLI 将以此为输入生成/更新目标仓库内的真值文件与 tool-native 配置文件。
+
+另见（本包内文档）：
+- `docs/spec-contract.md`：模板契约（required/optional、managed markers、tool matrix、`.aiws/manifest.json` 约定）
+- `docs/cli-interface.md`：CLI 行为语义（仅定义，不实现）

package/docs/cli-interface.md

@@ -0,0 +1,288 @@
+# CLI Interface（@aipper/aiws）
+
+本文件只定义 `@aipper/aiws` CLI 的行为语义（不包含实现）。
+
+## 目标与非目标
+
+目标：
+- 在任意仓库内执行 `init/update/validate/rollback`，落盘“真值文件 + 变更工件流程 + 门禁校验”，并可回滚。
+
+非目标：
+- 不承诺所有工具启动即自动加载规则（以 tool-native 文件能力为准）。
+- 不写入任何 secrets。
+
+## 通用约定
+
+- 默认模板：`--template workspace`
+- 默认生成：required + optional（模板 manifest 里标注）
+- 更新策略：
+  - `replace_file`：整文件由 aiws 托管
+  - `managed_blocks`：只更新 `AIWS_MANAGED_BEGIN/END` 托管块
+- 备份目录：`.aiws/backups/<timestamp>/`
+- manifest：`.aiws/manifest.json` 必须入 git，记录模板/版本与托管面 hash（详见 `docs/spec-contract.md`）
+  - 模板内置的 `.aiws/manifest.json` 允许是占位（含 `<sha256>` / epoch 时间戳），但 `aiws init` 必须重写为真实值；`aiws validate` 必须把占位 manifest 视为未初始化并失败。
+  - `managed` 字段不包含 `.aiws/manifest.json` 自身（避免 self-hash），但 `validate` 仍必须校验 manifest 可解析且字段完整。
+
+退出码（建议）：
+- `0`：成功
+- `2`：校验失败/门禁失败/用户输入不合法
+- `1`：CLI 自身错误（异常/IO 等）
+
+## `aiws init`
+
+语义：
+- 在目标仓库根目录写入/补齐模板（默认 `workspace`）。
+- 默认生成 required + optional 文件/目录。
+- 写入/更新 tool-native 文件（默认覆盖 Claude/OpenCode/Codex/iFlow；Codex 为 repo skills：`.agents/skills/`）。
+- 写入/更新 `.gitignore` 的 aiws 托管块（其余内容保留）。
+- 生成并写入 `.aiws/manifest.json`：
+  - 记录 `template_id/spec_version/aiws_version`
+  - 记录托管面 hash（用于后续 `validate`）
+
+接口（仅定义）：
+- `aiws init [path]`
+- `aiws init [path] --template <template_id>`
+
+幂等性：
+- 重复执行不应破坏用户在“托管块外”的自定义内容。
+
+## `aiws update`
+
+语义：
+- 从当前 `spec_version`（或用户指定版本）刷新模板与 tool-native 文件。
+- 更新前必须备份将改动的文件到 `.aiws/backups/<timestamp>/`。
+- 只允许更新：
+  - `replace_file` 文件：整文件覆盖
+  - `managed_blocks` 文件：仅更新托管块
+  - required 但不在上述两类中的文件：不改动内容（最多补齐缺失文件）
+- 若某个 `managed_blocks` 文件缺失指定 block、marker 不成对、或 marker 被破坏：必须失败（退出码 `2`），不做自动修复（提示用户重新 `aiws init` 或手工修复）。
+- 更新完成后刷新 `.aiws/manifest.json`（版本与 hash）。
+
+接口（仅定义）：
+- `aiws update [path]`
+
+## `aiws rollback`
+
+语义：
+- 从 `.aiws/backups/` 恢复到某一次备份的快照。
+
+接口（仅定义）：
+- `aiws rollback [path] <timestamp|latest>`
+
+## `aiws validate`
+
+语义（强门禁）：
+- 缺 `python3` 或缺 required 脚本直接失败（退出码非 0）。
+- `.aiws/manifest.json` 若仍为占位（含 `<sha256>` / epoch 时间戳等）必须失败（退出码 `2`），提示先运行 `aiws init`。
+- 可选：开启 stamping（证据落盘）：
+  - 方式 A：`aiws validate [path] --stamp`
+  - 方式 B：设置环境变量 `AIWS_VALIDATE_STAMP=1` 后执行 `aiws validate [path]`
+  - 产物：写入 `.agentdocs/tmp/aiws-validate/<timestamp>.json`（`.agentdocs/` 由 `.gitignore` 忽略；stamp 不应包含 secrets）
+- 校验范围至少包含：
+  1) 文件结构：required 文件/目录存在（以模板 manifest 为准）
+  2) `.gitignore`：存在且包含 aiws 托管块
+  3) `.aiws/manifest.json`：存在且可解析；托管面 hash 与当前一致（漂移检测）
+  4) 执行门禁脚本（示例）：
+     - `python3 tools/ws_change_check.py --strict`
+     - `python3 tools/requirements_contract.py validate`
+
+接口（仅定义）：
+- `aiws validate [path] [--stamp]`
+
+## `aiws codex install-skills`
+
+背景：
+- Codex 推荐使用 repo skills（`.agents/skills/`）；但对于“未初始化的任意仓库”，用户可能仍希望能直接调用一组通用 skills（如 `$ws-dev`、`$ws-preflight`）来引导回 AIWS 工作流。
+- 因此提供**全局 skills 安装**：把模板内的 repo skills 安装到 Codex 的全局 skills 目录中，使其在任意仓库都可显式调用（是否自动发现/是否需要重启由 Codex 实现决定；aiws 不做保证）。
+
+语义：
+- 将模板内的 skills（`templates/<template_id>/.agents/skills/*/SKILL.md`）安装到 Codex 的全局 skills 目录：
+  - 默认：`~/.codex/skills/`
+  - 若设置了 `CODEX_HOME`：`$CODEX_HOME/skills/`
+- 幂等：重复执行应只更新 AIWS 托管块，不破坏用户在文件托管块外追加的说明。
+- 若目标文件已存在但不含 AIWS 托管块：默认失败（退出码 `2`）；需用户显式 `--force` 才允许覆盖（覆盖前应备份）。
+- 支持预演：`--dry-run` 仅输出将创建/更新/覆盖的 skills 清单，不写入任何文件。
+
+接口（仅定义）：
+- `aiws codex install-skills [--template <template_id>] [--dir <path>] [--force] [--dry-run]`
+
+> `--dir` 可覆盖默认全局 skills 目录（用于 CI/沙箱验证，避免写入真实 home）。
+
+## `aiws codex status-skills`
+
+语义：
+- 检查 Codex 全局 skills 目录中，模板期望的 skills 是否就绪，并输出每个 skill 的状态：
+  - `ok`：存在且 AIWS 托管块与模板一致
+  - `missing`：不存在
+  - `unmanaged`：存在但不含 AIWS 托管块（aiws 不会自动覆盖）
+  - `outdated`：存在且含 AIWS 托管块，但块内内容与模板不一致（建议重新 `install-skills`）
+- 默认只做信息输出（不修改任何文件；退出码 `0` 表示命令执行成功，不代表全部为 `ok`）。
+
+接口（仅定义）：
+- `aiws codex status-skills [--template <template_id>] [--dir <path>]`
+
+## `aiws codex uninstall-skills`
+
+语义：
+- 从 Codex 全局 skills 目录卸载 AIWS 托管的 skills：
+  - 仅处理“含 AIWS 托管块”的文件（避免误删用户自建 skills）
+  - 移除前必须备份到：`<skillsDir>/.aiws/backups/codex-skills/<timestamp>/`
+
+接口（仅定义）：
+- `aiws codex uninstall-skills [--template <template_id>] [--dir <path>]`
+
+---
+
+## `aiws codex install-prompts`
+
+背景（legacy）：
+- prompts 为遗留机制（deprecated）；优先使用 repo skills（`.agents/skills/`）或全局 skills（`aiws codex install-skills`）。
+- Codex 的自定义 prompts 主要从全局目录发现（通常为 `~/.codex/prompts/`）。
+- 因此项目内的 `.codex/prompts/*.md` 不能保证会被 Codex 自动加载；需要显式安装到全局目录。
+
+语义：
+- 将模板内的 Codex prompt 文件（`templates/<template_id>/.codex/prompts/*.md`）安装到 Codex 的全局 prompts 目录：
+  - 默认：`~/.codex/prompts/`
+  - 若设置了 `CODEX_HOME`：`$CODEX_HOME/prompts/`
+- 幂等：重复执行应只更新 AIWS 托管块，不破坏用户在文件托管块外追加的说明。
+- 若目标文件已存在但不含 AIWS 托管块：默认失败（退出码 `2`）；需用户显式 `--force` 才允许覆盖（覆盖前应备份）。
+- 支持预演：`--dry-run` 仅输出将创建/更新/覆盖的文件清单，不写入任何文件。
+
+接口（仅定义）：
+- `aiws codex install-prompts [--template <template_id>] [--dir <path>] [--force] [--dry-run]`
+
+## `aiws codex status`
+
+语义：
+- 检查 Codex 全局 prompts 目录中，模板期望的 prompts 文件是否就绪，并输出每个文件的状态：
+  - `ok`：存在且 AIWS 托管块与模板一致
+  - `missing`：不存在
+  - `unmanaged`：存在但不含 AIWS 托管块（aiws 不会自动覆盖）
+  - `outdated`：存在且含 AIWS 托管块，但块内内容与模板不一致（建议重新 `install-prompts`）
+- 默认只做信息输出（不修改文件；退出码 `0` 表示命令执行成功，不代表全部为 `ok`）。
+
+接口（仅定义）：
+- `aiws codex status [--template <template_id>] [--dir <path>]`
+
+## `aiws codex uninstall-prompts`
+
+语义：
+- 从 Codex 全局 prompts 目录卸载 AIWS 托管的 prompts：
+  - 仅处理“含 AIWS 托管块”的文件（避免误删用户自建 prompts）
+  - 移除前必须备份到：`<promptsDir>/.aiws/backups/codex-prompts/<timestamp>/`
+
+接口（仅定义）：
+- `aiws codex uninstall-prompts [--template <template_id>] [--dir <path>]`
+
+## `aiws hooks install`
+
+语义：
+- 为当前 git 仓库启用 aiws 门禁 hooks：
+  1) 自动补齐 `.githooks/pre-commit` 与 `.githooks/pre-push`（从模板复制；若已存在则不覆盖）
+  2) 设置 `git config core.hooksPath .githooks`（使 `git commit`/`git push` 触发 `aiws validate .`）
+- 若需要临时绕过 hooks：设置环境变量 `WS_CHANGE_HOOK_BYPASS=1`。
+
+接口（仅定义）：
+- `aiws hooks install [path]`
+
+## `aiws hooks status`
+
+语义：
+- 输出当前仓库 hooks 状态（不修改任何文件）：
+  - git 仓库根目录
+  - `core.hooksPath` 当前值（是否指向 `.githooks`）
+  - `.githooks/pre-commit` / `.githooks/pre-push` 是否存在且可执行
+- 失败时应给出下一步建议命令（如 `aiws hooks install .` 或 `aiws init .`）。
+
+接口（仅定义）：
+- `aiws hooks status [path]`
+
+## `aiws change`
+
+背景：
+- `changes/` 用于保存每次变更的可审计工件：`proposal.md` / `tasks.md` / `design.md`（可选）/ `.ws-change.json`（基线元信息）。
+- 门禁脚本：`tools/ws_change_check.py`（通常由 git hooks/CI 触发；也可手工执行）。
+
+约束：
+- 不依赖 dotfiles；由 `@aipper/aiws` 提供 `aiws change ...` 子命令。
+- 必须在 git 仓库内执行，且仓库根目录存在真值文件：`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`。
+
+### `aiws change new`
+
+语义：
+- 生成 `changes/<change-id>/` 目录与工件：
+  - `proposal.md`
+  - `tasks.md`
+  - `design.md`（可选；`--no-design` 可跳过）
+  - `.ws-change.json`（记录 `created_at` 与 `base_truth_files` 作为基线）
+- 模板来源优先级：
+  1) `changes/templates/`
+  2) `workflow/changes/templates/`（兼容旧布局）
+  3) `@aipper/aiws-spec` 内置模板：`templates/<template_id>/changes/templates/`
+
+接口（仅定义）：
+- `aiws change new <change-id> [--title <title>] [--no-design]`
+
+### `aiws change start`
+
+语义：
+- 切分支：`change/<change-id>`（存在则切换；不存在则创建）。
+- 若 `changes/<change-id>/` 不存在：等价执行 `aiws change new ...`。
+- 可选：`--hooks` 等价于 `aiws hooks install .`。
+
+接口（仅定义）：
+- `aiws change start <change-id> [--title <title>] [--no-design] [--hooks]`
+
+### `aiws change sync`
+
+语义：
+- 刷新 `.ws-change.json` 的 truth baseline：
+  - 写入 `synced_at` / `synced_truth_files`
+  - 追加 `sync_events`（保留最近 20 条）
+- 写入 stamp（不含 secrets）：`.agentdocs/tmp/change-sync/<timestamp>-<change-id>.json`
+
+接口（仅定义）：
+- `aiws change sync [<change-id>]`
+
+### `aiws change validate`
+
+语义：
+- 调用 `python3 tools/ws_change_check.py` 校验单个 change 工件目录。
+- `--strict`：强门禁（例如 WS:TODO、占位符、缺归因、truth drift 等都失败）。
+- `--allow-truth-drift`：仅用于紧急场景跳过 truth drift gating（仍会输出 warnings；不建议常用）。
+
+接口（仅定义）：
+- `aiws change validate [<change-id>] [--strict] [--allow-truth-drift]`
+
+### `aiws change archive`
+
+语义：
+- 严格校验后归档：将 `changes/<id>/` 移动到 `changes/archive/<YYYY-MM-DD>-<id>/`。
+- 默认要求 `tasks.md` 无未勾选任务；`--force` 可跳过（不建议）。
+- 更新 `.ws-change.json`：
+  - `archived_at`
+  - `archived_to`
+  - `archived_truth_files`
+- 写入 stamp（不含 secrets）：`.agentdocs/tmp/change-archive/<timestamp>-<change-id>.json`
+
+接口（仅定义）：
+- `aiws change archive [<change-id>] [--date YYYY-MM-DD] [--force]`
+
+### `aiws change list/status/next`
+
+语义：
+- 信息性命令：列出当前 changes 进度与下一步建议（不修改任何文件）。
+
+接口（仅定义）：
+- `aiws change list`
+- `aiws change status [<change-id>]`
+- `aiws change next [<change-id>]`
+
+### `aiws change templates which/init`
+
+语义：
+- 查看/初始化 change 工件模板。
+
+接口（仅定义）：
+- `aiws change templates which`
+- `aiws change templates init`

package/docs/spec-contract.md

@@ -0,0 +1,183 @@
+# Spec Contract（@aipper/aiws-spec）
+
+本文件定义 `@aipper/aiws-spec` 的模板契约与“可更新/可校验/可回滚”的边界。实现与发布以本文件与 `packages/spec/templates/*/manifest.json` 为准。
+
+## 目标与非目标
+
+目标：
+- 约束 `aiws init/update/validate/rollback` 的**文件结构**与**更新策略**，避免规则漂移。
+- 明确单一真值（SSOT）：`@aipper/aiws-spec`（`packages/spec/`）。
+
+非目标：
+- 不保证所有 AI 工具都“启动即自动加载规则”；对不支持者提供可触发的入口文件。
+- 不在 spec/模板中写入任何 secrets（token、账号、内网端点等）。
+
+## 核心概念
+
+- `template_id`：模板标识，等于 `templates/<template_id>/` 的目录名；默认 `workspace`。
+- managed surface（可托管面）：
+  - `replace_file`：该文件由 aiws 全量托管（更新可整文件覆盖）。
+  - `managed_blocks`：只更新文件内 `AIWS_MANAGED_BEGIN/END` 标记的托管块；块外内容保留给用户自定义。
+- unmanaged required（必需但不托管）：
+  - 模板 `manifest.json` 里的 `required` 仅表示“init/validate 必须存在”。
+  - 若某个 required 文件不在 `update.replace_file` 且不在 `update.managed_blocks` 中：视为用户自主管理内容；`aiws update` 不应修改其内容（最多只补齐缺失文件）。
+- SSOT：
+  - 机器可读契约：`templates/<template_id>/manifest.json`
+  - 人类可读说明：本文件
+
+## 模板结构契约（SSOT）
+
+模板目录结构：
+- `packages/spec/templates/<template_id>/`：一份可落盘到目标仓库根目录的模板快照
+- `packages/spec/templates/<template_id>/manifest.json`：该模板的 required/optional 文件列表与每个文件的更新策略
+
+默认模板：
+- `workspace`
+
+## Managed markers 约定
+
+统一格式：
+- `AIWS_MANAGED_BEGIN:<id>`
+- `AIWS_MANAGED_END:<id>`
+
+注释语法（按文件类型）：
+- Markdown：`<!-- AIWS_MANAGED_BEGIN:<id> -->`
+- `.gitignore` / `*.sh` / `*.yaml` / `*.yml` / `*.toml`：`# AIWS_MANAGED_BEGIN:<id>`
+
+规则：
+- `<id>` 必须稳定且可读（推荐：`area:purpose`，如 `agents`、`gitignore`、`claude:aiws-init`）。
+- 托管块应当是**连续整块文本**；aiws 只允许更新托管块内容，不触碰块外内容（除非该文件策略为 `replace_file`）。
+- 对于模板 manifest 声明为 `managed_blocks` 的文件：若目标仓库缺失指定 block、marker 不成对、或 marker 被破坏，`aiws update` 必须失败（不做自动修复）。
+
+## `.gitignore` 托管块（默认约定）
+
+目标仓库的 `.gitignore` 必须包含以下托管块（块外可自由扩展）：
+
+```gitignore
+# AIWS_MANAGED_BEGIN:gitignore
+.agentdocs/
+.aiws/backups/
+secrets/test-accounts.json
+.env
+.env.*
+!.env.example
+!.env.*.example
+# AIWS_MANAGED_END:gitignore
+```
+
+说明：
+- aiws 只负责维护托管块内容；不会帮你维护 `node_modules/`、`dist/`、`target/` 等项目特定忽略项。
+- 你可以把项目自己的 ignore 规则追加在托管块之外；`aiws update` 会保留块外内容不变。
+
+## `.aiws/manifest.json` 契约（漂移检测锚点）
+
+位置与版本控制：
+- `.aiws/manifest.json`：必须入 git（可审计、可复现）
+- `.aiws/backups/`：必须被 `.gitignore` 忽略
+
+用途：
+- 记录当前仓库“来自哪个模板 + 版本锚点 + 托管面 hash”，用于 `aiws validate` 的漂移检测。
+- `managed` 清单应覆盖模板 `manifest.json` 中声明的所有可托管面（`update.replace_file` + `update.managed_blocks`），用于精确定位漂移点。
+  - 例外：**不包含** `.aiws/manifest.json` 本身（避免“manifest 自己哈自己”的悖论）；但 `validate` 仍必须校验 manifest 可解析且字段完整。
+
+推荐字段（schema 级别约定；实际以 `cli-interface.md` 为准）：
+- `manifest_version`：整数，便于未来升级
+- `template_id`
+- `spec_version`：`@aipper/aiws-spec` 版本
+- `aiws_version`：`@aipper/aiws` 版本
+- `installed_at` / `updated_at`：ISO 8601 UTC 时间
+- `tools`：`["claude","opencode","codex","iflow"]` 的子集
+- `managed`：托管面清单（文件级或托管块级 hash）
+
+hash 规则（用于跨平台稳定性）：
+- 算法：SHA-256
+- 文本归一化：计算前将 `\r\n` 统一转为 `\n`（不做其它 trim）
+- `replace_file`：对整个文件内容计算 hash
+- `managed_blocks`：对每个托管块的“块内内容”计算 hash（不包含 begin/end 行）
+
+示例（仅示意；hash 由 `aiws init/update` 填充）：
+
+```json
+{
+  "manifest_version": 1,
+  "template_id": "workspace",
+  "spec_version": "0.0.0",
+  "aiws_version": "0.0.0",
+  "installed_at": "2026-01-25T00:00:00Z",
+  "updated_at": "2026-01-25T00:00:00Z",
+  "tools": ["claude", "opencode", "codex", "iflow"],
+  "managed": [
+    { "path": ".githooks/pre-commit", "mode": "replace_file", "sha256": "<sha256>" },
+    { "path": ".gitignore", "mode": "managed_blocks", "blocks": { "gitignore": "<sha256>" } }
+  ]
+}
+```
+
+模板内置占位（重要）：
+- 模板目录中的 `templates/<template_id>/.aiws/manifest.json` 允许出现 `<sha256>` 与占位时间戳（例如 `1970-01-01T00:00:00Z`），仅用于让 `init` 能直接落盘一个“结构正确的 manifest”。
+- 一旦仓库通过 `aiws init` 初始化成功：该文件必须被重写为真实值（版本号/时间戳/hash）。
+- `aiws validate` 必须把“占位 manifest”（仍含 `<sha256>` / epoch 时间戳等）视为 **未初始化/不可校验** 并失败（提示用户运行 `aiws init` 或 `aiws update`）。
+
+## Tool-native 文件矩阵（第一期覆盖）
+
+说明：
+- tool-native 文件是 derived 产物；aiws 按模板 `manifest.json` 的 `update` 策略维护（`managed_blocks` 或 `replace_file`）。
+- 默认覆盖：Claude Code / OpenCode / Codex / iFlow。
+
+约定路径（示例；最终以模板 manifest 为准）：
+- Claude Code：`.claude/commands/aiws-*.md`（commands）
+- OpenCode：`.opencode/command/aiws-*.md`（command）
+- Codex：`.agents/skills/*/SKILL.md`（skills）
+- iFlow：`.iflow/commands/aiws-*.toml`（commands）
+
+补充（workflow 入口，同样由模板提供；最终以模板 manifest 为准）：
+- Claude Code：`.claude/commands/ws-*.md`
+- OpenCode：`.opencode/command/ws-*.md`
+- Codex：`.agents/skills/ws-*/SKILL.md`
+- iFlow：`.iflow/commands/ws-*.toml`
+
+注意（Codex）：
+- Codex 的 repo skills 目录为 `.agents/skills/`（可随仓库共享；prompts 已 deprecated）。
+- 如需在任意仓库也能显式使用 AIWS skills：可用 `aiws codex install-skills` 从模板 `.agents/skills/*/SKILL.md` 安装到 `~/.codex/skills/` 或 `$CODEX_HOME/skills`。
+- 如仍需使用全局 prompts（遗留机制）：可用 `aiws codex install-prompts` 从模板 `.codex/prompts/*.md` 安装到 `~/.codex/prompts/` 或 `$CODEX_HOME/prompts`。
+
+能力边界（必须在文档中不夸大）：
+- aiws **不保证** 工具会自动加载/自动注册这些文件（是否自动发现、是否需要重启/重新打开会话，由工具实现决定）。
+- aiws 的最低承诺是：这些文件提供一致的“工作流入口”（例如引导执行 `npx @aipper/aiws init|update|validate|rollback`），从而把用户带回同一套真值文件与门禁。
+
+每个文件的托管方式（推荐）：
+- 对于 commands 类文件（如 `.claude/commands/*.md`、`.opencode/command/*.md`）：每个文件包含**一个且仅一个**托管块（block id 形如 `claude:aiws-init`），aiws update 只更新托管块，块外内容保留给用户追加说明。
+- 对于 Codex skills（`.agents/skills/*/SKILL.md`）：由于文件顶部 YAML front matter 需要保持一致性，默认采用 `replace_file` 全量托管；如需自定义请新增独立 skill 目录。
+
+最小矩阵（建议写清以下字段，便于未来实现与验收）：
+- `path_pattern`：文件路径模式
+- `purpose`：它是“可执行入口/提示入口/命令入口”还是“自动注入规则”
+- `autodiscovery`：是否依赖工具自动发现（未知/不保证/已知支持）
+- `reload_needed`：更新后是否通常需要重启/重新加载（未知/不保证/通常需要）
+- `fallback`：若不生效，用户如何手动触发（直接运行 `npx @aipper/aiws ...`）
+
+建议的默认取值（与 `workspace` 模板一致）：
+- Claude Code
+  - `path_pattern`：`.claude/commands/aiws-*.md`
+  - `purpose`：提供“在 Claude 内可见的命令入口/说明”，引导用户运行 `npx @aipper/aiws ...`
+  - `autodiscovery`：不作为契约要求（由工具决定；aiws 不做保证）
+  - `reload_needed`：不作为契约要求
+  - `fallback`：在 shell 直接运行 `npx @aipper/aiws init|update|validate|rollback`
+- OpenCode
+  - `path_pattern`：`.opencode/command/aiws-*.md`
+  - `purpose`：提供命令入口/说明（同上）
+  - `autodiscovery`：不作为契约要求
+  - `reload_needed`：不作为契约要求
+  - `fallback`：同上
+- Codex
+  - `path_pattern`：`.agents/skills/*/SKILL.md`
+  - `purpose`：提供 skills（显式 `$<skill>` 或隐式套用工作流），引导用户运行 `npx @aipper/aiws ...`
+  - `autodiscovery`：不作为契约要求（由工具决定；aiws 不做保证）
+  - `reload_needed`：不作为契约要求
+  - `fallback`：显式使用 `$ws-preflight` / `$ws-plan` / `$ws-dev` / `$ws-review` / `$ws-commit`（或在 shell 直接运行 `npx @aipper/aiws init|update|validate|rollback`）
+- iFlow
+  - `path_pattern`：`.iflow/commands/aiws-*.toml`
+  - `purpose`：提供 commands/命令入口/说明（同上）
+  - `autodiscovery`：不作为契约要求
+  - `reload_needed`：不作为契约要求
+  - `fallback`：同上

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@aipper/aiws-spec",
+  "version": "0.0.1",
+  "description": "AIWS spec and templates (single source of truth).",
+  "type": "module",
+  "files": [
+    "templates",
+    "docs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}

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

@@ -0,0 +1,23 @@
+---
+name: aiws-change-archive
+description: 归档变更工件（会先做严格校验）
+---
+
+目标：
+- 将 `changes/<change-id>/` 归档到 `changes/archive/<YYYY-MM-DD>/...`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change archive "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change archive "$change_id"
+else
+  npx @aipper/aiws change archive "$change_id"
+fi
+```
+
+说明：
+- `archive` 默认会先跑严格校验并要求 tasks 全部勾选
+- `--force` 会绕过部分门禁（不推荐）

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

@@ -0,0 +1,18 @@
+---
+name: aiws-change-list
+description: 列出 changes 工件（只读）
+---
+
+目标：
+- 列出当前仓库的变更工件与状态
+
+执行（在仓库根目录）：
+```bash
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change list
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change list
+else
+  npx @aipper/aiws change list
+fi
+```

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

@@ -0,0 +1,26 @@
+---
+name: aiws-change-new
+description: 创建 changes/<change-id> 工件
+---
+
+目标：
+- 创建 `changes/<change-id>/` 工件目录与基础文件（proposal/tasks/可选 design）
+
+要求：
+- `change-id` 必须是 kebab-case：`^[a-z0-9]+(-[a-z0-9]+)*$`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change new "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change new "$change_id"
+else
+  npx @aipper/aiws change new "$change_id"
+fi
+```
+
+可选参数：
+- `--title <title>`：写入标题
+- `--no-design`：不生成 design.md

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

@@ -0,0 +1,19 @@
+---
+name: aiws-change-next
+description: 给出下一步建议（只读）
+---
+
+目标：
+- 基于当前仓库与 changes 工件状态，输出最小下一步建议
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change next "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change next "$change_id"
+else
+  npx @aipper/aiws change next "$change_id"
+fi
+```

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

@@ -0,0 +1,27 @@
+---
+name: aiws-change-start
+description: 切分支并初始化变更工件（可选安装 hooks）
+---
+
+目标：
+- 切到分支 `change/<change-id>` 并初始化 `changes/<change-id>/` 工件
+
+要求：
+- 需要 git 仓库；若不是 git 仓库先 `git init`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change start "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change start "$change_id"
+else
+  npx @aipper/aiws change start "$change_id"
+fi
+```
+
+可选参数：
+- `--hooks`：同时执行 `aiws hooks install .`
+- `--title <title>`：写入标题
+- `--no-design`：不生成 design.md

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

@@ -0,0 +1,19 @@
+---
+name: aiws-change-status
+description: 查看单个变更工件状态（只读）
+---
+
+目标：
+- 查看指定 `change-id` 的工件状态与下一步建议
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change status "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change status "$change_id"
+else
+  npx @aipper/aiws change status "$change_id"
+fi
+```

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

@@ -0,0 +1,19 @@
+---
+name: aiws-change-sync
+description: 同步真值基线到 changes/<change-id>（写入 .ws-change.json）
+---
+
+目标：
+- 将当前真值文件（`AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md`）的 hash 快照同步到 `changes/<change-id>/.ws-change.json`
+
+执行（在仓库根目录）：
+```bash
+change_id="<change-id>"
+if [[ -x "./node_modules/.bin/aiws" ]]; then
+  ./node_modules/.bin/aiws change sync "$change_id"
+elif command -v aiws >/dev/null 2>&1; then
+  aiws change sync "$change_id"
+else
+  npx @aipper/aiws change sync "$change_id"
+fi
+```