Wing CLI 使用规范

Wing 管理项目的 Agent 协作元数据：根/局部 AGENTS.md、领域文档、ADR、文档
frontmatter、OpenSpec 变更结构。配置文件为 wing.config.yaml（旧项目可能仍是
agent-meta.config.yaml，wing upgrade 会自动迁移）。命令用 wing；旧别名 meta 等价。

核心原则：修改文档与元数据时用 wing 的命令，不要手搓文件——命令保证编号、
frontmatter、目录结构与索引一致。

安装与初始化（仓库还没被 Wing 管理时）

仓库里没有 wing.config.yaml 时，先安装并初始化：

pnpm add -D @bossmissing/wing   # npm/yarn 同理；需 Node >= 20
pnpm exec wing init --yes       # 非交互初始化；交互式直接 wing init

常用 init 选项：--type（项目形态）、--language、--with-mcp <pack>[,<pack>]
（可选 MCP 工具包：playwright、dev-env）、--with-deploy <target>（部署 skill：
cloudflare / ansible / github-actions）、--dry-run 先预览。

init 后跑 wing doctor 自检环境（Node / 包管理器 / 配置 / Git Hook / OpenSpec）。

收尾前必须做

• 提交前跑 wing check（CI 与 pre-commit 用 wing check --strict，warning 也会阻塞）。
  有 error 先修再提交，不要绕过。
• 报告结论前，若改动涉及对外可观察行为，更新对应的 OpenSpec spec / 文档。

脚手架：用命令，别手搓

• 新领域文档：wing new-domain <name>（自动建 docs/domain/<name>/ 的 README、rules，
  按需 state-machine/glossary 与局部 AGENTS.md）。不要手工新建领域目录。
• 新架构决策：wing new-adr <slug>（自动分配下一个编号、写好 frontmatter）。
  绝不手工编号 ADR——编号冲突会被 wing check 拦下。
• 新功能变更：wing new-change <name>（建 OpenSpec 兼容的变更目录；命中高风险领域时
  自动附 risk-review.md）。

索引与同步

• docs/domain/README.md、docs/adr/README.md 是自动生成的索引，不要手工编辑。
  增删领域或 ADR 后跑 wing sync 重建索引（并调用 openspec update，若装了 OpenSpec）。

以下文档是唯一事实来源（改行为前先读）

• docs/engineering/constraints.md — 项目级硬限制（不可违反）。
• docs/engineering/tech-stack.md — 技术栈选型；换选型先写 ADR。
• docs/domain/<domain>/rules.md 的「硬限制（不可违反）」章节 — 领域级硬限制。
• 高风险领域（命中 wing.config.yaml 的 risk_keywords）必须在 rules.md 声明非空硬限制，
  否则 wing check 报 HIGH_RISK_DOMAIN_MISSING_HARD_CONSTRAINTS。

文档 frontmatter

docs/** 下需要 frontmatter 的文档必须含 title / status / owner / last_reviewed
（具体范围见 wing.config.yaml 的 validation）。缺字段或 last_reviewed 过期会被
wing check 标记。

事后维护

• 加部署 / MCP 工具包：wing add deploy <target> / wing add mcp <pack>
  （增量安装并把规则幂等追加进 AGENTS.md）。
• 升级到当前 CLI 版本：wing upgrade（补齐新增文件、刷新已装 skills、迁移旧配置文件名、
  对生成文档做漂移报告）。
• 治理分析：wing audit（只报告不改文件）；定期 review：wing review；
  上线前 checklist：wing preflight（--confirm 逐项人工确认）。
• 配置：wing config list / set；生成 pre-commit 钩子：wing config hooks lefthook。

命令速查

退出码：0 通过；1 校验 error；2 参数错误；3 配置无法解析；4 IO 错误；5 模板缺失。

硬性规则

• 不手工编辑自动生成的索引；改动后用 wing sync。
• 不手工编号 ADR；用 wing new-adr。
• 不在 wing check 未通过时收尾提交。
• 领域规则只写在 docs/domain/<domain>/，不要复制进根 AGENTS.md。