Tenon 文档

Tenon 是面向 Codex、Claude Code 等 Agent 宿主的本地优先交付工作流插件。它把正常对话里的开发请求路由到合适的执行模式，并用状态机、OpenSpec、Skill 证据、文档摘要和 review receipt 约束“做了什么、为什么能推进、后续读了哪一版”。

从这里开始

• 第一次使用：先读安装与宿主配置，再完成第一个受治理任务。
• 不确定该走哪种流程：读选择执行模式。
• 任务一直显示等待：读Dashboard 与本地 API和故障排查。
• 需要团队定制：读自定义 Workflow 与 Track。
• 需要理解证据门：读文档、Skill 与证据链。
• 需要自己的执行者或评审者：读智能体。
• 想让 Pull Request 自己证明测试证据：读CI 校验。

四种常用结果

入口	适用目标	是否创建 Change	文档行为
discussion	问答、解释、只读分析	否	不创建治理文档
default 的 lite 轨道	修缺陷、小改动、错字级改动（建任务前先评估改动范围）	是	无 OpenSpec，只有一道评审门
default 的 pm / frontend / backend 轨道	跨模块、需要规格与验证的开发	是	完整七阶段与 OpenSpec 证据链
自定义工作流	团队自定义 DAG	是	只生成声明的文档

默认生命周期

open → explore → spec ⇄ build ⇄ verify → ship → archive

explore、spec、verify 的前进出口需要精确 review receipt。Build 发现需求变化时走 requirements-changed 回到 Spec；Verify 不通过时走 verify-fail 回到 Build——验证轮次还没用完时这条回退边不需要 review receipt，直接 tenon transition，用完后被拒。Pipeline 不允许通过手改状态文件跳过这些边界。

你会在仓库中看到什么

• .pipeline/workflows/：项目自定义 Workflow 的版本化定义；
• openspec/changes/<name>/：活跃 Change 的 proposal、design、tasks、delta spec 与状态投影；
• openspec/changes/archive/<日期>-<name>/：已结束的 Change（完结、已升级、已终止都在这里）；
• openspec/specs/：已经应用、持续维护的主规格；
• docs/adr/ 与 docs/superpowers/：架构决策、技术设计、计划和验证报告；
• .pipeline-document-locale.json：新 Change 固定的文档呈现语言；
• .pipeline-step-outputs.json：每次步骤访问的产出、来源技能和读取回执；
• .pipeline-documents.json：升级前创建的任务的文档 producer、digest 和读取收据账本。

状态机决定“能否推进”，OpenSpec 描述“系统必须做什么”，计划描述“如何实现”，验证报告描述“实际验了什么”。任何一份文件都不能单独冒充流程完成。

文档如何保证可信

新任务不预先规定每一步的文档：Tenon 在离开步骤时记录该步新增、修改、删除的文件与来源技能，下一步只拿到直接上游的文档并必须读完（读取回执绑定 SHA-256），工作流只用 required-output 要求某一步必须写出哪些文件。升级前创建的任务仍按文档账本，记录 kind、路径、producer、SHA-256 和后续 phase 的读取收据。中文是新 Change 的默认呈现语言，但 phase id、命令、文件名、账本字段和 OpenSpec 操作词保持稳定英文 token。

运行边界

Dashboard 和 API 默认只绑定 loopback。公共文档站是纯静态产物，不包含本地 Change、token、SSE、写 API 或工作区路径。

安装后的本地控制面默认使用 18765；文档站使用 GitHub Pages 项目路径，两者不共享用户数据或运行时状态。

按角色阅读

• 第一次安装插件：从安装与宿主配置开始；
• 开发者执行需求：阅读第一个受治理任务；
• 技术负责人定制团队流程：阅读自定义 Workflow 与 Track；
• 运维人员处理更新或故障：阅读更新、恢复与卸载和故障排查；
• 贡献者修改插件：阅读贡献者开发指南。

三条不可绕过的原则

1. 新目标不会仅因存在旧的 active-change 指针就恢复旧 Change；
2. review receipt 必须绑定准确 phase 和 event，删除 marker 不等于确认；
3. 未运行的测试、未打开的页面和未成功的部署不得写成通过。

下一步

完成第一个受治理任务，或直接查阅CLI 参考。