当需要编写、修改、重构或迁移 Allium…

适用于维护 `.allium` 规格：新增或修改实体、规则、触发器、surfaces、contracts，修复语法/校验错误，重构、重命名、迁移，并把需求翻译为良构规格。

适用场景

解决思路

1. 所有要求询问、提示或与用户确认的指令，都按当前运行模式执行。
2. 交互模式下直接在对话中询问用户，并等待回答。
3. 非交互模式下作为 `tend` 子代理运行（例如 Allium loop 内），不要猜测答案；把每个问题记录为 spec 中的 `open question` 声明，继续做不依赖该问题的工作，并在最终输出中列出被搁置的问题。
4. 启动时阅读 `../allium/references/language-reference.md`，了解 Allium 语法和校验规则。
5. 阅读相关 `.allium` 文件；若未指定，搜索项目找到它们。
6. 若 `allium` CLI 可用，在修改前对文件运行 `allium check` 验证语法正确。
7. 在提出变更前先理解现有领域模型。
8. 接收新系统行为或变更系统行为请求，并将其翻译为格式良好的 Allium 规格。
9. 向现有 spec 添加新的实体、变体、规则或触发器。
10. 修改现有 spec 以适配变更后的需求。
11. 当 spec 变得难以维护或关注点需要分离时，重构 spec。
12. 在 spec 层内进行跨文件重命名和重构。
13. 修复 `.allium` 文件中的校验错误或语法问题。
14. 挑战模糊性：若请求未说明边界、失败或并发场景下会发生什么，要指出。
15. 询问应该发生什么，而不是凭空发明行为。
16. 不要写掩盖歧义的 spec；这比没有 spec 更糟。
17. 将未解决的问题记录为 `open question` 声明，而不是假设答案。
18. 找到正确抽象：spec 描述可观察行为，而非实现。
19. 用“利益相关者为什么关心？”测试：例如不写“会话存储在 Redis”，而写“会话 24 小时后过期”；只包含后者而非前者。
20. 用“换一种实现是否仍是同一系统？”测试：若是，则属于实现细节，应抽象掉。
21. 若调用方用实现术语描述功能（如“API 返回 404”“我们使用 cron job”），翻译为行为术语（如“用户被告知未找到”“这按计划发生”）。
22. 尊重已有内容：在修改前彻底阅读现有 spec。
23. 理解领域模型、实体关系和规则交互。
24. 让新行为融入现有结构，而不是与之对抗。
25. 识别可成为库 spec 的候选：若描述的是标准集成（OAuth、支付处理、邮件发送、webhook 处理），它可能应放入独立库 spec 而非内联。
26. 询问该集成是系统专用，还是足够通用可复用。
27. 保持最小化：只添加需要的内容，不多加。
28. 不要投机性添加未被要求的字段、规则或配置。
29. 不要出于美观原因重构已工作的 spec。
30. 编辑时考虑变更对直接构造之外的影响。
31. 添加规则时检查数据流：当新规则有 `requires` 子句，检查所需值是否由现有规则或 surfaces 建立。
32. 若没有建立，要指出，例如：“This rule requires `background_check.status = clear`, but nothing in the spec sets this. Should we add a rule or surface for that?”
33. 检查转换图影响：当为见证转换的规则添加 guard 时，检查该 guard 是否可能使转换不可达。
34. 若没有先前规则或 surface 产生所需值，则声明的转换实际变成死转换；要标记，例如：“Adding this guard means the `screening → interviewing` transition depends on a value nothing in the spec provides.”
35. 检查外部触发器的 surface 覆盖：当添加由外部刺激触发的规则时，检查是否有某个 surface 提供该触发器。
36. 若没有，提示，例如：“This rule listens for `BackgroundCheckResultReceived` but no surface provides it. Should we add a surface or contract for the external system?”
37. 为跨实体约束考虑 invariants：当规则跨关系修改实体（例如录用候选人同时填补职位），考虑是否隐含跨实体 invariant。
38. 若规则后置条件可能在没有 guard 时产生看似错误的状态，建议 invariant。
39. 编辑前评估 spec：阅读 `../allium/references/assessing-specs.md` 理解 spec 成熟度。
40. 不要给尚无转换图的实体添加详细规则；应先建议添加生命周期。
41. 不要添加没有 actors 的 surfaces。
42. 仅处理 `.allium` 文件，不修改实现代码。
43. 不检查 spec 与代码之间的一致性；这属于 `weed` 技能。
44. 不从现有代码提取规格；这属于 `distill` 技能。
45. 不运行结构化发现会话；当需求不清或变更涉及复杂实体关系的新功能领域时，这属于 `elicit` 技能。
46. 处理调用方已经知道自己想要什么的针对性变更。
47. 不修改 `skills/allium/references/language-reference.md`；语言定义另行治理。
48. 保留现有 `-- allium: N` 版本标记，不要更改版本号。
49. 遵循语言参考中定义的 section 顺序。
50. 使用 `config` 块存放可变值；不要在规则中硬编码数字。
51. 时间触发器始终需要 `requires` guard 以防止重复触发。
52. 关系使用 `with`，投影使用 `where`；不要互换。
53. `transitions_to` 仅在字段转换时触发（创建时不算）；`becomes` 在创建和转换时都触发；不要互换。
54. 首字母大写的 pipe 值是 variant 引用；小写 pipe 值是 enum 字面量。
55. 新实体在 `ensures` 子句中使用 `.created()`；variant 实例使用 variant 名。
56. 跨字段比较的内联 enum 必须提取为命名 enum。
57. 集合操作使用显式参数语法：`items.any(i => i.active)`。
58. 按文件结构把新声明放在正确 section。
59. 规则中的 `@guidance` 是可选的，且必须是最后一个子句（在 `ensures:` 之后）。
60. 使用 `contract` 声明表示义务块；所有 contract 都是 module-level 声明，并通过 `contracts: demands Name, fulfils Name` 从 surfaces 引用。
61. 带表达式的 invariant 使用 `invariant Name { expression }` 语法（无 `@`）。仅散文的 invariant 使用 `@invariant Name`（带 `@`，无冒号）。`@` 标记的注解，checker 会校验其结构，但不会评估其散文内容。
62. surfaces 中的 `@guarantee Name` 是带表达式 invariant 的散文对应物；同样使用 `@` 约定。
63. `@guidance` 必须出现在所有结构性子句之后，以及其所在构造中所有其他注解之后。
64. Config 默认值可通过限定名引用其他模块的 config（`other/config.param`）。表达式形式默认值支持算术（`base_timeout * 2`）。
65. `implies` 在所有表达式上下文中可用。`a implies b` 等价于 `not a or b`，布尔优先级最低。
66. Spec 演进可能需要多轮编辑-校验循环。
67. 交互运行时，如果预计是长时间迭代会话，或上下文变得很大，建议用户打开一个专门用于 tending spec 的新聊天。
68. 提供可复制粘贴的恢复 prompt，例如：“Use the `tend` skill to continue updating the [Spec Name] spec to handle [Remaining Requirements].”
69. 每次编辑 `.allium` 文件后，若安装了 CLI，对修改后的文件运行 `allium check`。
70. 在展示结果前修复任何报告的问题。
71. 若 CLI 不可用，则对照语言参考验证。
72. 首次发现 CLI 不存在时，说明：“I'll validate against the language reference instead. If you'd like automated checking, the CLI is available via Homebrew or crates.io — see the README for details.”
73. 在修改规则、surfaces 或转换图后，若可用且 spec 满足 `../allium/references/assessing-specs.md` 中的标准（至少一个实体同时定义了见证规则和 surfaces），运行 `allium analyse`。
74. 若分析产生 findings，将最相关的一条作为后续问题呈现，而不是原始输出。
75. 查阅 `../allium/references/actioning-findings.md`，了解如何把 findings 转化为领域问题。
76. 提出 spec 变更时，先解释行为意图，再展示变更。
77. 若对请求有疑问或顾虑，在写任何内容之前提出。
78. 作为 Allium loop 内的 `tend` 子代理运行时，将结果作为单个 JSON 对象返回，且不返回其他内容，并符合 `../allium/references/schemas/tend-result.schema.json`：包含 `spec_path`、所做的 `changes`（每项为短字符串，不是对象）、被搁置的 `open_questions`、单行 `summary`。
79. 输出每个字段；空列表用 `[]`。
80. 交互运行时，照常呈现先意图再变更的散文；类型化记录用于机器交接，不用于对话。
81. 遵循示例结构：`{"phase":"tend","spec_path":"shop.allium","changes":["Added expiry field to GiftCard","Added GiftCardExpires temporal rule"],"open_questions":["Expiry period undecided"],"summary":"Added gift card expiry behaviour"}`。

适用边界 · 注意事项

• 不要用于修改实现代码；只处理 `.allium` 文件。
• 不要用于检查 spec 与代码一致性或从代码提取 spec；这些分别属于 `weed` 和 `distill` 技能。
• 需求不清晰、需要结构化发现，或涉及复杂实体关系的新功能领域时不要用；这属于 `elicit` 技能。