安装当前机器
npx opennori setup 安装匹配版本的全局 CLI，并通过官方宿主入口安装 OpenNori Plugin。setup 不会初始化当前项目。
安装一次，
然后直接和 agent 说目标。
安装 OpenNori 后，你继续用自然语言描述目标。Agent 会先确认结果，再实现和验证；Codex 默认由新的检查 agent 复核，Claude Code 顺序验证。仍有结果或 Git 交付缺口时，不会告诉你“已经完成”。
First Run
第一次使用只需要三步
setup 只准备当前机器，init 只初始化当前项目。第三步必须开启新的 agent 对话，让更新后的能力生效。
初始化项目
opennori init --user <name> 在项目根目录创建可版本控制的任务状态和稳定知识。init 不会安装全局 CLI。
打开新的 agent 会话
为账号删除增加可恢复的确认流程。 直接描述真实目标。Agent 会先询问是否创建 task；你同意后才进入 Plan。
Codex + Claude Code
一个项目可以同时使用两个宿主
已经使用 Codex 的项目不需要重新初始化。先安装 Claude Code Plugin，再预览并确认项目入口；原有 Codex 入口、项目设置和任务状态都会保留。
npx opennori setup --platform claude
opennori platform add claude --dry-run
opennori platform add claude --confirm
opennori doctor完成后分别开启新的 Codex 或 Claude Code 对话，直接描述目标。两个 Plugin 都会通过 Hook 自动识别当前宿主，并使用同一套项目任务、验证事实和 Git 交付状态。
What To Say
把这些话发给 agent
下面这些是真实用户会用到的入口。你不需要知道它们背后触发了哪个内部能力。
开始一个目标
“为账号删除增加可恢复的确认流程。”
Agent 先询问是否创建 OpenNori task。你同意后，它理解项目和目标，只追问会改变最终结果的问题，并在实现前提供可点击的 contract.md。
确认前审阅结果
“开始实现前，把可打开的 contract.md 给我审阅。”
点击文件审阅完整 Contract；正文不会默认塞进对话。复杂任务的 design.md 和 plan.md 由 Agent 按需维护，不会增加审批步骤。
结果边界发生变化
“账号删除还需要恢复窗口，先修订结果，不要直接扩大实现。”
Agent 会返回规划阶段重新确认结果；旧范围不会继续被当成完成标准。
检查是否真正完成
“现在是否可以完成？告诉我已经验证的结果、Git 交付和仍然存在的缺口。”
Agent 会直接说明完成依据、当前缺口和下一步；证据或交付不完整时不会宣称完成。
Review Before Approval
确认前，点击审阅 contract.md
Agent 会提供可打开的文件名，不把整篇 Contract 塞进对话。点击检查目标、每个必需结果、验证方式和假设；只有你明确批准后才能开始实现。
账号删除需要二次确认和 30 天恢复窗口，请修订。 结果不准确时直接指出缺失内容。
contract.md 的目标、结果、验证方式和假设都正确，可以开始实现。 确认前保持实现关闭，确认后再进入下一阶段。
结果范围没变，只调整这次 Git 交付方式。 交付决策单独处理，不捆绑成新的 Contract 审批。
How To Read Status
看结果和缺口，不看执行流水账
你不需要阅读执行流水账。只要确认现在做到哪里、还差什么，以及是否需要你作出决定。
现在做到哪里
告诉你当前处于规划、实现、验证还是收尾。
还差什么
直接指出哪个结果或 Git 交付仍未满足。
是否需要你
需要确认、修订或接受例外时明确停下来。
Current Gap Gate
任何单一信号都不能代表完整交付
结果得到批准不代表实现完成，跑过测试也不代表用户目标已经满足。OpenNori 会同时检查最终结果、真实验证和 Git 交付。
结果仍未证明
Agent 会说明哪个用户结果还没有验证，并继续检查对应行为。
实现尚未交付
经过验证的结果必须对应实际 commit 或 pull request，避免测试与交付脱节。
最终状态仍未提交
完成报告和稳定项目知识也要进入干净的最终 Git 提交。
正确使用时你会看到
- Agent 在实现前提供可点击的 contract.md，而不是粘贴全文或只给摘要。
- 需要你批准、修订或确认时会明确停下来。
- 复杂任务按需维护 design.md 和 plan.md，小任务没有文档税。
- Codex 会由新的检查 agent 复核，验证结论会说明真实用户行为和实际 Git 交付。
- 仍有缺口时会告诉你下一步，而不是宣称完成。
这些情况要让 agent 重写
- 你还没有确认结果，Agent 就开始改代码。
- 目标变化后，Agent 没有重新让你审阅。
- 只说“测试通过”，却没有验证真实用户行为。
- 没有对应 Git 交付或仍有缺口时宣称完成。
Troubleshooting
常见问题
Agent 没有使用 OpenNori
先重新运行对应宿主的 setup 和项目初始化；Codex 还需要信任 OpenNori Hooks。然后开启新的编码 agent 会话。
项目里没有 .opennori/
进入项目根目录执行 opennori init --user <name>。
加入 Claude Code 时出现冲突
先审阅 opennori platform add claude --dry-run 报告的路径。OpenNori 不会覆盖已有文件，也不会移除 Codex。
状态看起来坏了
运行 opennori doctor。它会告诉你缺少什么，以及下一步恢复动作。
完成被验证阻止
让 agent 说明哪个结果还没有证明，并重新运行对应的用户可见检查。
完成被 Git 阻止
让 agent 检查实现是否已经提交，以及记录的 commit 或 pull request 是否就是当前结果。
升级出现冲突
先审阅 opennori update --dry-run 或 Doctor 给出的冲突路径，不要直接覆盖用户修改。