@weotro/dx 0.1.15 → 0.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/project-agent-standards/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: project-agent-standards
+description: 审核并补齐项目面向 agent 的 GitHub 模板、开发评审规范、DX 工作流与回访 Issue 规则，将 AGENTS.md 整理为按需读取的渐进披露结构。
+---
+
+# 项目 Agent 规范整备
+
+对用户指定仓库执行审核并补齐缺项；未指定时使用当前仓库。只读审核请求只报告差异。默认执行本地可回退的模板和文档修改，不包含提交、推送、发布 Issue / PR、安装工具或改造构建系统。现有全局技能保持不变。
+
+## 1. 建立项目依据
+
+检查工作区状态，读取目标及祖先的 `AGENTS.md`。按需检查已有规范、贡献指南、GitHub 模板、技术栈清单、任务配置和 CI。优先搜索标题与职责，不能仅凭文件名判定规范缺失。
+
+记录以下六项的现状、路径和缺口：Issue / PR 模板、agent 引用、开发评审规范、DX / Nx 工作流、回访规则、AGENTS.md 渐进披露结构。检查根及模块 agent 入口的内容分工、读取条件和引用链；祖先指令用于确定约束，不修改目标仓库之外的文件。区分已配置的命令、实际运行结果与未来建议；不读取或输出秘密值。
+
+完成条件：每项均有存在证据或明确的缺失结论，能够识别目标模块与实际工具链。
+
+## 2. 补齐 GitHub 模板
+
+使用随技能携带的完整模板，无需访问原始项目：
+
+| 资源 | 目标标准位置 |
+| --- | --- |
+| [Issue 模板](assets/github/ISSUE_TEMPLATE/issue.md) | `.github/ISSUE_TEMPLATE/issue.md` |
+| [PR 模板](assets/github/pull_request_template.md) | `.github/pull_request_template.md` |
+
+目标缺失时创建目录并直接复制。目标已有等效内容时保留；空文件或缺少模板必需结构时，以资源覆盖该目标文件。覆盖前保留目标的未提交或未跟踪原文到仓库外的临时备份，并记录路径；已提交的原文可通过 Git 恢复。用户明确要求统一为附带模板时直接覆盖。
+
+检查根目录、`docs/` 与 `.github/` 是否有竞争的默认 PR 模板；将仍适用的独有约束合入标准模板，再清理被取代的默认副本并更新引用。保留用途不同的 Issue Forms、多模板及配置，不因其存在就删除。已有标准文件中的项目专属验收要求同样需要保留。
+
+完成条件：两个标准位置均有可用模板，默认 PR 模板选择无冲突，独有约束和用户原文可追踪。
+
+## 3. 补齐面向 agent 的参考文档
+
+按缺口读取对应资源，依照源码、配置和已有决策改写。现有等效文档优先就地补齐并继续使用其路径；只有缺失时才使用表中的默认路径。
+
+| 缺项 | 适配资源 | 默认路径 |
+| --- | --- | --- |
+| 开发与评审规范 | [开发规范骨架](assets/development-standards.md) | `docs/guides/development-standards.md` |
+| DX / Nx 工作流 | [工作流骨架](assets/dx-development-workflow.md) | `docs/guides/dx-development-workflow.md` |
+| 回访规则 | [回访规则](assets/follow-up-issues.md) | `docs/agents/follow-up-issues.md` |
+
+文档写给执行任务的 agent：说明触发条件、具体决策、命令前置条件、失败处理与完成证据。删除骨架中的编写提示及不适用分支，替换所有 `{{...}}`。保留目标项目语言约定，无约定时使用简体中文。
+
+开发规范应覆盖实际模块与风险；不会因使用此技能就迁移成三层架构或引入新的测试框架。将已有约束、此次建立的规则和未来建议分清；尚未接入的检查不能写成已经运行的门禁。
+
+DX 文档必须检查实际 DX 配置、Nx 目标与 CLI 能力。已接入则记录真实命令；只接入其一则分别说明职责；均未接入也生成说明，明确“未接入”并给出现有命令，不编造 `dx` 入口。工具链接入是另一个任务。
+
+回访规则合入现有 Issue 规范的对应章节；没有载体时才创建独立文档。沿用目标项目的本地或远程追踪方式，不引入原始项目的 `.scratch/` 默认存储决定。
+
+完成条件：三类说明可被 agent 直接使用，命令有配置依据，待确认事实明确列出，无未替换占位符。
+
+## 4. 检查并改造 AGENTS.md 的渐进披露结构
+
+渐进披露按任务需要加载说明：根入口保留项目识别、全局必需约束与条件明确的文档入口；模块入口保留该目录适用的规则；详细流程、命令说明、模板字段和专题规范放在被引用文档中。判断依据是内容职责与加载方式，不以行数或是否已有链接判定。只有简短必需规则的入口无需为了拆分而创建文件。
+
+存在下列情况时，在本次整备中直接改造：入口堆放仅特定任务需要的详细流程；所有专题文档被要求无条件全文加载；只有链接而没有读取条件；相同规范在多个入口重复维护。只读审核请求则报告问题和迁移建议。
+
+1. 按原有规则的适用范围梳理内容，保留全局必需约束及模块覆盖关系；将条件性细节归入现有等效文档，缺少载体时再按专题创建文档，沿用项目目录约定。
+2. 在原入口用“执行什么任务时，必须读取哪个文档”的短指令替换已迁移细节。适用时才读取的专题不使用无条件全文导入；避免入口互相引用或仅为转发再增加一层目录页。
+3. 更新迁移内容中的相对链接和其他引用，确保目标存在且能从入口到达。保留原规则的强制程度、例外、权限边界和历史决策，不因移动位置而削弱要求。修改未提交或未跟踪原文前保存仓库外备份并记录路径。
+4. 建立原章节到新位置的对应记录，逐项核对无遗漏后再删除重复正文。已有合适结构则就地补齐缺失的读取条件和链接，重复执行不重复拆分。
+
+在根 `AGENTS.md` 放 GitHub 模板和回访规则的触发入口；模块独有的开发规范放在模块 `AGENTS.md`。若仓库采用其他 agent 入口，复用其引用链；缺少入口则创建根 `AGENTS.md`。参考以下文字并替换为真实的相对链接：
+
+> 创建或更新 GitHub Issue / PR 正文时，必须读取并使用 [Issue 模板](.github/ISSUE_TEMPLATE/issue.md) / [PR 模板](.github/pull_request_template.md)。网页、CLI、API 和技能操作均适用。正文结构和填写要求以模板为准；发布前检查必填章节与占位内容。
+
+> 开发、修复或评审代码时，按任务范围读取 [开发与评审规范](docs/guides/development-standards.md) 的相关章节。
+
+> 初始化环境、选择启动 / 验证 / 构建命令或排查环境注入时，读取 [开发工作流](docs/guides/dx-development-workflow.md) 的相关章节。
+
+> 创建、更新或转为回访用途的 Issue 时，读取 [回访规则](docs/agents/follow-up-issues.md)。
+
+入口保留必要约束和读取条件。模板字段留在模板，命令细节留在工作流，回访标识留在 Issue 规范。将仓库其他位置同义重复的说明改成引用或删除；保留模块专属约束与历史决策。重复运行时复用既有入口，不追加相同规则。
+
+完成条件：入口、模块规则与专题细节分工清楚，每个按需文档都有明确触发条件，原有有效约束完整保留，没有失效链接、循环引用或无条件加载所有专题的要求。
+
+## 5. 验证与交付
+
+检查差异、Markdown 链接、模板 frontmatter、占位符和竞争模板。逐项复核第 1 步的六项清单与所有新引用，确认再执行一次不会增加文件或重复条目。对照迁移记录检查规则完整性，并分别用代码修改、Issue / PR 编写和回访任务走查入口，确认能够找到对应规范，且不会要求加载无关专题。
+
+纯文档修改按项目规则做差异与格式验证；验证命令存在可以检查配置或安全的帮助输出，不为文档审核运行发布、迁移或全仓测试。报告每项的保留 / 新建 / 更新状态、文件链接、实际验证和未确认事项，以及渐进披露检查结论与章节迁移去向；未接入 DX / Nx 要明确说明。不要将文档中列出的命令写成已经执行通过。

package/skills/project-agent-standards/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "项目 Agent 规范整备"
+  short_description: "审核并补齐 GitHub 模板、开发评审规范、DX 工作流和回访规则"
+  default_prompt: "使用 $project-agent-standards 审核当前仓库并补齐面向 agent 的项目规范。"
+policy:
+  allow_implicit_invocation: false

package/skills/project-agent-standards/assets/development-standards.md

@@ -0,0 +1,49 @@
+<!-- 编写提示：这是适配骨架，不是可直接复制的项目决策。用实际目录、框架和验证目标替换变量，删除不适用章节与本提示。 -->
+# {{项目或模块}} 开发与评审规范
+
+适用范围：{{目录与业务入口}}。
+依据：{{已有架构决策、领域术语、工具配置的相对链接}}。
+
+## 规范与执行
+
+开发、修复和评审时按改动范围读取对应章节。“必须”是验收要求，“应”允许有依据的偏离，“可”是可选方案。新增规则的目标状态与现有实现分开记录；文档本身不证明实现合规。
+
+开始实现前明确输入输出、权限、业务不变量、失败行为和验证方式。架构例外按项目既有决策机制处理，并在 PR 模板对应章节记录影响及验证。
+
+## 模块边界与依赖
+
+{{记录实际模块、各层职责、允许的依赖方向、入口与组装位置，以及一组目标仓库真实路径。单体、库、前端或脚本项目按自身结构填写。}}
+
+公共接口暴露调用者需要的能力；基础设施与第三方细节留在适配边界。修改共享接口时检查实际消费方，并说明兼容方式。
+
+## 契约、状态与错误
+
+{{记录协议或组件接口的真源、生成文件边界、输入校验、错误码或异常约定。}}
+
+边界明确空值、非法输入、超时、取消与重复操作的行为。状态变化通过可观察结果验收。诊断遵循项目语言及脱敏规则，避免暴露凭据和用户敏感内容。
+
+## 数据与外部副作用
+
+{{仅在存在持久化或远程调用时保留：事务边界、并发约束、幂等、重试、迁移兼容性、失败恢复及资源生命周期。引用实际实现约定，不默认引入事务框架或 Outbox。}}
+
+## 界面与交互
+
+{{仅在存在界面时保留：状态归属、加载/空/错误状态、可访问性、响应式、已有设计系统、前后端契约和关键交互验收。}}
+
+## 安全、配置与运行
+
+{{说明实际身份与权限边界、配置来源及优先级、秘密存储、启停与日志约定。依项目风险补充资源限制和可观测性。}}
+
+## 验证与评审
+
+按变更风险选择能观察行为的检查：业务逻辑、接口、持久化、交互及跨模块链路分别映射到现有测试入口。缺少自动化覆盖时记录具体缺口，不把计划中的检查当成已接入门禁。
+
+| 变更范围 | 验收证据 | 命令依据 |
+| --- | --- | --- |
+| {{真实模块或变更类型}} | {{需验证的行为、失败路径}} | {{链接到工作流对应章节}} |
+
+纯文档核对差异、格式和引用；代码改动执行覆盖本次风险的检查。相关检查已通过且输入未变化时不重复运行。按证据区分本次回归、既有失败和环境问题；验证结果统一填写 PR 模板。
+
+## 规范维护
+
+{{列出本项目特有的评审要点及已知未落实要求。只引用真实存在的文档；需要外部依据时核对所用框架版本，未核实的判断标为待确认。}}

package/skills/project-agent-standards/assets/dx-development-workflow.md

@@ -0,0 +1,46 @@
+<!-- 编写提示：先检查项目实际配置。未接入 DX / Nx 时保留标题但明确状态，将命令表改为现有工具入口；删除无关章节、变量和本提示。 -->
+# DX 与 Nx 开发工作流
+
+供 agent 在初始化环境、选择命令或排查执行问题时按需读取。
+
+## 工具职责与真源
+
+接入状态：{{DX 与 Nx 分别为已接入 / 未接入；缺少 CLI 与缺少仓库配置分别说明}}。
+
+{{列出公开任务入口、内部编排工具、实际配置路径及版本依据。只有已验证使用全局 DX 时才写全局安装策略；不套用其他仓库包名、版本或目录。}}
+
+## 环境准备
+
+{{记录实际运行时版本来源、依赖安装命令、所需服务及其由谁管理。没有初始化入口就列现有必要步骤，不虚构 dx setup。}}
+
+## 配置与注入
+
+{{记录环境选择参数、配置文件加载顺序、秘密的本地存放位置、必须变量名及校验时机。说明绕过公开入口是否会丢失环境注入；不填写真实秘密。}}
+
+## 命令选择
+
+下表命令来自项目配置；“已配置”不表示本次已经运行通过。
+
+| 任务 | 实际命令 | 前置条件 | 行为与副作用 |
+| --- | --- | --- | --- |
+| {{初始化 / 启动 / 检查 / 测试 / 构建中实际存在的任务}} | {{精确命令}} | {{所需依赖与环境}} | {{执行范围、产物、是否启动服务或修改数据}} |
+
+{{DX 已接入时核对 CLI 支持的参数与目标映射；Nx 已接入时说明依赖顺序、缓存和 configuration。只记录存在的目标，明确附加路径或参数是否真的透传。}}
+
+## 验证范围与失败处理
+
+{{按模块列出行为验收入口，区分单元 / 集成 / E2E、Mock / 真实依赖。说明完整套件是否已包含子套件，避免重复执行。}}
+
+环境或依赖缺失单列为未运行或环境失败；测试进程失败不能记为通过。失败证据包括实际命令、退出状态和关键原因。运行结果填写仓库 PR 模板。
+
+## 生成产物与服务生命周期
+
+{{有生成代码时：真源、生成目标、消费方依赖和是否入库。有服务时：启动/结束责任、端口来源、临时数据隔离与清理，以及是否自动迁移。无相应行为则删除本节。}}
+
+## 发布边界
+
+{{只列现有发布入口、目标环境和执行权限；没有入口就明确尚未配置。文档审核不执行发布或迁移。}}
+
+## 尚未接入或待确认
+
+{{只列具体缺项及其对 agent 的影响。未接入 DX / Nx 时给出现有替代入口，明确本次只补文档，未安装或接入工具链；无缺项时删除本节。}}

package/skills/project-agent-standards/assets/follow-up-issues.md

@@ -0,0 +1,9 @@
+# 回访 Issue 规则
+
+创建用于后续复查、跟进验证的 Issue，或将既有 Issue 转为该用途时：
+
+- 标题使用 `[回访] 原标题`，并添加名称完全一致的 `回访` 标签；前缀与标签只保留一份，保留其他标签和流程状态。
+- GitHub Issue 正文沿用仓库 Issue 模板，在现有章节内写清回访对象、触发条件或时间、可观察的验收标准；模板的正文结构不在此重复定义。
+- 获得创建或更新 GitHub Issue 的授权后，若仓库缺少 `回访` label，随该次操作创建并应用；权限不足时报告标签未完成，不把 Issue 标记为全部处理完成。
+- 项目已有本地 Issue 追踪时，一级标题保留此前缀，在 `Labels:` 行或既有标签字段记录 `回访`，沿用原状态机制。同步到 GitHub 时保留标识；本规则不改变项目的本地 / 远程追踪策略。
+- 验证完成后按项目流程记录证据并关闭或更新状态；“回访”本身不表示验收通过。

package/skills/project-agent-standards/assets/github/ISSUE_TEMPLATE/issue.md

@@ -0,0 +1,27 @@
+---
+name: Issue
+about: 提交功能、缺陷、重构或其他可执行事项
+title: ""
+labels: ""
+assignees: ""
+---
+
+## 背景
+
+<!-- 说明当前情况、问题或提出该事项的原因。 -->
+
+## 目标
+
+<!-- 说明完成后可观察的状态；明确不做的事单独列出。 -->
+
+## 验收标准
+
+<!-- 使用客观、可验证的条目；每条标准应能通过测试、命令或明确观察进行确认。 -->
+
+- [ ]
+
+## 关联
+
+<!-- 可选。相关 Issue/PR 用 Refs: #<id> 列出；没有则删除本段。 -->
+
+Refs: #

package/skills/project-agent-standards/assets/github/pull_request_template.md

@@ -0,0 +1,27 @@
+## 变更目的
+
+<!-- 用 1-3 句话说明问题、预期结果和必要背景；不要复述 Issue 全文。 -->
+
+## 主要改动
+
+<!-- 用精简条目说明最终行为、契约或运维变化；不记录探索过程、agent 分工、复杂度门禁或完整日志。 -->
+
+-
+
+## 验证结果
+
+<!-- 只记录当前 HEAD 的最低充分验证。每项写“命令或检查 — 状态 — 关键结果”；状态使用“通过 / 失败 / 未运行”。失败必须说明是否为已登记并在基线复现的既有问题。 -->
+
+-
+
+## 风险与后续
+
+<!-- 统一列出未覆盖范围、已知风险、follow-up 和合并/发布后动作；每项标注“阻塞 / 非阻塞 / 发布后”。存在“阻塞”项时不得合并；没有则填写“无”。 -->
+
+无
+
+## 关联
+
+<!-- 主 Issue 使用 Closes: #<issue-id>；其他关联使用 Refs: #<issue-id>。 -->
+
+Closes: #

package/skills/ship-issue-pr/SKILL.md

@@ -6,94 +6,137 @@ disable-model-invocation: true
 
 # Ship Issue PR
 
-统一 Codex 与 Claude Code 的交付入口。按当前任务的终点处理本地改动、PR 或合并。
+统一 Codex 与 Claude Code 的 Issue → 实现 → PR → 审查修复 → 验证 → 合并交付流程。
 
-本文件包含完整交付流程与两种宿主的工具说明。按当前步骤执行：状态与范围 → 实现与验证 → 提交/PR → 已授权的合并与回访；已经完成的部分直接承接。
+本文件包含完整流程与两种宿主的工具说明。依次完成下列步骤；已有成果按验收标准承接，缺失的 Issue、方案审核、审查评论或验证报告必须补齐。
 
 ## 执行边界与优先级
 
 在宿主系统与开发者指令约束内，当前任务的具体要求和已有授权 > 项目适用的 AGENTS.md > 本技能及其他通用技能。项目规定的验证、分支与合并要求继续适用。
 
-只读检索、本地草稿、可回滚编辑和常规测试自主推进。从相关文件和直接依赖开始，只有证据不足或影响跨模块时扩大范围。已给出的授权跨轮有效；不可逆或难以回滚的修改缺少具体授权时，先准备可审阅的 diff、正文和验证结果，再说明对象及影响并等待确认。对外发送消息须有明确授权。
+用户调用本技能执行交付时，默认流程包括：创建或复用本次 Issue、提交与推送代码、创建或更新 PR、发布审查/修复/验证评论、通过门禁后合并、关闭已完成的 Issue，以及按下文规则创建和派发 follow-up Issue。沿用会话中已有授权，不逐步重复确认；用户明确限定仅本地、仅审查或不合并时遵守该终点。编辑或讨论本技能本身不触发交付操作。
 
-本技能默认把本次范围内的工作交付到 PR；用户明确要求仅本地修改、仅审查或继续到合并时，按该终点执行。单独调用技能不授权部署、数据操作、无关 Issue 或无限扩展任务。缺少目标事实时先从上下文与配置查证；能独立进行的工作继续，确实无法确定目标时才询问。
+从相关文件和直接依赖开始，按证据扩大范围。交付授权不包含生产部署、破坏性数据操作或与任务无关的对外消息；需要额外授权的动作先准备可审阅结果，说明对象与影响。缺少目标事实时先查上下文与项目配置，能独立进行的工作继续，确实无法确定目标时才询问。
 
-## 状态与范围
+## 1. 检查状态并确定交付目标
 
-检查当前分支、工作区状态、相关 diff 和已有交付记录；需要远端操作时再核对 remote、Issue、PR 和认证。基线、命令、模板和 CI 从项目实际配置确定，不假定 main、特定 monorepo 路径或没有 PR 检查。
+检查当前分支、工作区状态（已暂存、未暂存及未跟踪文件）、分支相对基线的 diff 和已有提交，同时读取当前对话中的问题、需求、Issue/PR 链接。核对 remote、相关 Issue、已有 PR 和认证；基线、命令、模板和 CI 从项目实际配置确定。
 
-工作区有改动不代表需求已完成：按验收标准识别已完成和剩余工作，复用成果。无关改动保持原样；不明归属的文件先避开，必要时在隔离 worktree 继续。只在必须修改且无法安全保留时澄清归属。工具或认证缺失只阻塞依赖它的操作，本地准备继续。
+- 已有修改：判断是否就是本次待交付内容，对照上下文识别已实现、待修复和待验证部分；有 diff 不等于已完成需求。
+- 没有修改：根据上下文和关联 Issue 明确要解决的问题，再进入实现；已有提交或 PR 时从剩余步骤继续。
+- 既没有可交付修改，也没有可确定的问题或 Issue：先询问具体目标，获得目标后创建 Issue，避免编造需求。
+
+无关改动保持原样；不明归属的文件先避开，必要时在隔离 worktree 继续。只在必须修改且无法安全保留时澄清归属。工具或认证缺失只阻塞依赖它的操作，本地准备继续。
 
 按本次需求或 diff 检查直接相关的重复实现；没有证据时不扩大为全仓历史审计。
 
-## Issue、分支与正文
+## 2. 补齐 Issue 与工作分支
+
+本次交付必须关联 Issue。优先核实并复用上下文、分支或 PR 指向的 Issue，搜索相关 Issue 避免重复；没有匹配项就创建，适用于已有代码修改和只有待解决问题两种入口。
 
-优先复用任务、分支或已有 PR 指向的 Issue。项目要求 Issue 时，在提交或 PR 前补齐；本地准备无需等 Issue 创建。任务包含创建 Issue 时，先准备背景、目标、可验证的验收标准及依赖说明，再创建并读回。没有仓库模板时使用这些字段即可，缺模板不构成阻塞。
+创建前读取项目 Issue 模板、贡献规范及与本次需求相关的规划/路线图，按模板填写背景、目标、范围、验收标准、依赖和规划归属。没有模板时使用这些字段；缺少规划信息时如实注明，不编造里程碑或扩大范围。创建后读回编号、正文与 URL，确认覆盖实际任务。远端创建失败时保留正文草稿并继续独立准备，但 Issue 未补齐不能完成交付。
 
 采用项目分支规则和指定基线；无规则时为本次交付创建独立分支，遵守宿主的默认命名前缀。已有合规分支可继续。创建 worktree 时保留任务所需的未提交上下文，按项目实际 setup 准备依赖，不默认执行全量构建或同步私有环境文件。
 
-Issue/PR 多行正文写入本次任务独立的临时文件，用 `--body-file` 传递；提交说明可用 `git commit -F`。正文写明实际变更、验证命令和结果、遗留风险以及已有 Issue 关联。修正影响理解的占位内容，合法代码示例或引用中的 TODO 不当作未完成工作。
+Issue/PR 正文及评论优先使用结构化工具参数；使用 CLI 时将多行内容写入本次任务独立的临时文件，用 `--body-file` 传递，提交说明可用 `git commit -F`。每次发布后读回内容与链接；重试前检查是否已成功，避免重复记录。修正影响理解的占位内容，合法代码示例或引用中的 TODO 不当作未完成工作。
+
+## 3. 判定复杂度并确定方案
+
+满足任一条件即按复杂任务处理：
+
+- 本次修改的文件超过 5 个，且新增与删除的总行数超过 100 行；两个数量条件必须同时成立。
+- 涉及并发逻辑、数据库变更或多端协同，例如事务/锁/并行写入、数据模型/迁移、前后端或多个客户端的契约与行为联动。
+
+统计范围是本次交付相对目标基线的完整改动，包含已提交、已暂存、未暂存及相关未跟踪文件，同一文件只计一次，排除无关工作。未开始实现时依据预计范围和语义影响判断，实施中范围扩大或最终 diff 达到条件时升级为复杂任务。记录统计、影响点和判定理由到 Issue 或 PR。
+
+简单任务由主线程拟定必要步骤并直接实现。复杂任务必须依次完成：
 
-## 实现与协作
+1. 主线程先提出方案，包含现状、目标、拟改文件/模块、接口与数据影响、风险、验收和测试计划。
+2. 调用下文第三方独立通道审核方案，提供需求、规划约束及相关源码；仅咨询，不授予写权限。
+3. 主线程核验返回意见，修订方案，记录采纳项、未采纳理由及最终方案。关键分歧未解决时再次审核，方案确定后才交给第三方实施。
 
-主进程直接处理能可靠完成的改动。公共契约、数据迁移、权限、并发、计费或跨模块协调等风险可以促使增加定向检查或独立意见；文件数和行数本身不强制切换模型、发问或扫描全仓。
+如果接手时复杂改动已存在，先根据现有 diff 整理方案并补做第三方审核，再交由第三方核查实现与完成必要修正，无需删除成果重做。
 
-用户要求专家协作，或复杂问题确实需要独立证据且环境允许时，使用下文对应宿主的运行时工具。交接包含目标、工作目录、责任文件、项目约束、已完成成果和验收命令。默认由主进程负责 Git/GitHub 交付，执行者仅修改分配文件；明确另行分配的授权按任务处理。
+## 4. 实施与主线程复核
 
-咨询只提供建议，实现才授予必要写权限。不同执行者避免同时修改同一范围，可在不重叠文件上继续工作；无法隔离时使用独立 worktree。外部通道不可用时自行接手剩余工作并说明限制，用户明确要求的独立审查仍需如实标记未完成。
+复杂任务由第三方实施，主线程负责方案定稿、协调与验收；简单任务主线程直接实施。交接包含最终方案、Issue、工作目录、责任文件、项目约束、已完成成果、验收标准及实际验证命令。主线程负责本次 Git/GitHub 交付，实施者只修改分配文件。
 
-## 委派活性与接管
+咨询与审查只读，实施才授予必要写权限。不同执行者避免同时修改同一范围，可在不重叠文件上继续工作；需要隔离时使用独立 worktree。任务书必须带上相关流程和项目规则，不能假定执行通道能加载技能。
+
+第三方完成后，主线程核对完整 diff、责任范围和验收标准，检查遗漏、回归、越界改动与测试证据，处理发现的问题。第三方返回成功不等于主线程已验收，也不替代后续 PR Code Review。
+
+复杂任务的第三方方案审核、实施与 Code Review 都是必需步骤。通道不可用时记录具体阻塞，继续可独立完成的准备或诊断；只有用户明确调整流程后才能以主线程实现或自审替代。依赖工具降级为当前模型 sub-agent 时如实记录，不能算已满足第三方要求。
+
+### 委派活性与接管
 
 保存本次任务 ID、工作目录、输出来源和责任文件基线，持续观察同一任务。有效日志、工具进展或责任文件变化可以证明活动；只读任务不要求文件修改。
 
 单次等待超时或静默告警只触发诊断，检查原会话、子命令、权限等待与错误；重复空心跳不代表进展。确认失败或无法推进后优先恢复；接管前确认原执行者及其写进程已停止，再核对现有成果，仅完成剩余工作。遵守用户取消要求，不盲目重放任务或绕过权限拒绝。
 
-## 验证与证据复用
+## 5. 提交代码并创建或更新 PR
 
-按项目 AGENTS.md 和实际测试配置完成必需检查，选择与改动相关的最小充分范围。纯文档或局部样式不因通用表格自动触发跨端 lint、全仓构建或数据库操作。
+完成实现与主线程复核后，按项目要求执行提交前检查。按项目提交规范和 PR 模板准备交付；无 PR 模板时写明问题、最终变更、Issue 关联、复杂度判定、方案审核、验证现状与遗留风险。
 
-记录被验证的代码与输入、覆盖范围、命令、实际执行者和可读结果。未提交改动也属于输入；不能只用 HEAD 代表含本地修改的验证现场。证据详细程度以能够判断是否仍适用为准。
+暂存明确的本次文件，核对暂存 diff，避免带入无关修改或凭据，随后提交并推送；提交钩子改变内容时补验受影响部分。复用已有 PR，确认 base/head 正确。创建或更新后读回标题、正文和 URL；部分失败先核对远端实际状态，只补剩余操作。
 
-- 内容、基线与相关输入未变：复用已有验收、审查和测试证据，包括可核实的其他执行者结果。
-- 仅 commit SHA 改变、内容相同：核对后关联新提交，不重跑相同检查。
-- 代码、验收标准、依赖或环境变化：检查增量及受影响调用方，仅补跑受影响项。
-- 来源或覆盖不足：补齐缺失检查；影响无法界定时再扩大到当前交付的完整 diff 和必要测试。
+尚未完成审查或验证时准确标记待完成项，可使用草稿 PR；不能把创建 PR 当作交付结束。
 
-测试通过不能替代代码审查。失败按复现、日志或基线证据归因；已知失败清单只是线索，未收录不代表本次引入。保留失败事实，修复任务范围内的问题，其他问题写明影响。
+## 6. Code Review、评论与修复循环
 
-测试若会清理共享数据库或改动共用资源，使用隔离环境，或沿用项目的互斥机制。不要把生产迁移当常规测试，也不要通过固定全局锁路径假定所有项目共享一套数据库。
+按最新复杂度选择审查方式：简单任务由主线程直接 Code Review；复杂任务必须调用第三方独立审查通道。独立审查使用未参与实现或修复的会话，主线程仍须核验关键证据。
+
+首次审查覆盖本次完整 PR diff 及必要上下文。每轮完成后都向 PR 发布 Code Review 结果评论，包括审查方式、实际审查者、被审查 head SHA、覆盖范围、发现及结论；无发现也要留下记录。每条发现给出严重程度、文件位置、触发条件、影响与修复建议。
 
-## 审查与修复
+存在有效问题时完成修复并推送，在 PR 发布修复报告评论：逐项关联发现、说明修复内容、提交与验证结果；不采纳的意见写明证据和理由。阻塞验收或影响正确性、安全的未解决问题不能转成 follow-up 后视为通过。
 
-首次审查覆盖本次完整 diff 及必要上下文；有效审查已有覆盖时只查增量和受影响部分。发现提供文件位置、触发条件、影响与修复建议，优先处理正确性、安全和验收缺口。
+修复后判断是否需要再次 Code Review：修改行为、接口、数据/并发逻辑，修复重大问题，或引入新风险时必须复审；复杂任务仍走第三方独立通道。复审覆盖修复增量与受影响调用方，范围扩大时重新覆盖完整 diff，并发布新一轮审查评论。纯文字或不改变行为的修正可核对后不再调用审查，但在修复报告中写明理由。循环直至阻塞性发现解决，不按固定轮数提前结束。
 
-独立审查使用未参与实现的上下文；自审按自审报告，不冒充外部审查。审查次数由新变化和未解决问题决定，不设“每 PR 最多一次”或“固定三轮”的通用额度，也不为凑轮次重复检查。
+## 7. 最终运行、编译与测试验证
 
-修复后验证受影响行为，复用其余证据。提交按逻辑变更组织，不要求每条 finding 单独一个 commit。确认有效的重大问题未解决时不声称可合并；无法在范围内解决时保留具体原因与后续建议，不靠创建 Issue 把失败改成通过。
+审查与最后一次修复完成后，对最终待合并代码完成一轮验证：按项目配置运行受影响目标的编译/构建、启动或运行冒烟检查，以及与改动相关的单元测试、集成测试和端到端（E2E）测试。多端改动覆盖受影响各端与关键联动路径，同时完成项目 AGENTS.md 和 CI 要求的检查。
 
-## 提交与 PR
+按实际影响选择相关测试，不强制执行与任务无关的全仓或跨端检查。某类检查不适用或项目没有对应命令时，在报告中明确说明理由；关键行为缺少自动化覆盖时补充适当测试或可复现验证。环境、认证或外部资源缺失导致必需检查无法运行时，标记阻塞，不声称验证通过。
+
+记录被验证的代码与输入、覆盖范围、命令、实际执行者和可读结果。未提交改动也属于输入；不能只用 HEAD 代表含本地修改的验证现场。证据详细程度以能够判断是否仍适用为准。
+
+- 最终修复后已执行且内容、基线与相关输入未变：复用这一轮可核实的验证结果，包括其他执行者结果，无需重复运行同一命令。早于最后修复的结果只作过程证据，不能替代最终一轮。
+- 仅 commit SHA 改变、内容相同：核对后关联新提交，不重跑相同检查。
+- 最终验证后代码再次修复：重新完成最终一轮；仅验收标准、依赖或环境变化时核对覆盖并补齐失效项。
+- 来源或覆盖不足：补齐缺失检查；影响无法界定时再扩大到当前交付的完整 diff 和必要测试。
 
-执行任务已授权的提交和 PR 交付。暂存明确的本次文件，并核对暂存 diff，避免带入无关修改或凭据；提交钩子改变内容时补验受影响部分。
+测试通过不能替代代码审查。失败按复现、日志或基线证据归因；已知失败清单只是线索，未收录不代表本次引入。保留失败事实，修复任务范围内的问题，其他问题写明影响。
 
-复用已有 PR。创建或更新后读回标题、正文、base、head 和 URL，确认发布的是已验证内容；部分失败先查远端实际状态，只补剩余操作。检查当前项目实际要求的 CI，不沿用“本仓库没有 PR CI”的历史假设。
+将最终验证报告发布为 PR 评论，包含 head SHA、环境、执行者、命令、覆盖范围、通过/失败结果、不适用项及阻塞。检查当前 head 对应的实际必需 CI；CI 未结束则等待，失败或必需验证缺失则继续处理。评论发布后读回确认；报告仍在本地或发布失败时，记录步骤尚未完成。
 
-依赖 PR 未合并时，继续可独立完成的实现、审查和草稿准备；只延后依赖它的集成或合并。需要判断冲突时优先使用只读比较或隔离 worktree，不为探测冲突修改用户当前工作树。
+测试若会清理共享数据库或改动共用资源，使用隔离环境，或沿用项目的互斥机制。不要把生产迁移当常规测试，也不要通过固定全局锁路径假定所有项目共享一套数据库。
 
-## 合并与回访
+## 8. 合并与关闭
 
-仅当当前任务授权包含合并时执行。合并前确认验收范围已满足、必需测试和 CI 通过、重大 findings 已解决；核对最新远端 head、base 与验证对象。变化使证据失效时补查增量。
+默认在门禁全部满足后合并；用户限制终点时按其要求停止。合并前确认 Issue 验收完成、复杂任务必需的第三方步骤完成、Code Review 报告及发生修复时的修复报告已评论、适用的最终运行/编译/相关测试及必需 CI 通过、验证报告已评论、阻塞性 findings 已解决。核对最新远端 head、base 与验证对象；变化使证据失效时重新进入相关审查和最终验证步骤。
 
 使用项目允许的合并方式，绑定已核验的 head（例如 gh 的 `--match-head-commit`）；保留分支保护，不能用管理员开关绕过。自动合并已设置不代表已合并，读回 `mergedAt` 与状态后再报告；异步检查仍在运行时准确说明等待原因。
 
 合并后按任务要求回访关联 Issue，确认实际验收与关闭状态。只有本次确实完成整个 Issue 时才使用关闭关联；对误关或剩余工作按已有授权修正并报告。
 
-## 后续工作与交付
+## 9. Follow-up Issue 与派发
+
+全过程发现新的范围外问题时，搜索去重后直接创建或补充 follow-up Issue，按项目模板与规划记录复现/证据、影响、目标、验收标准、来源 Issue/PR 和依赖。当前验收必须解决的问题留在本次修复循环，不能通过拆 Issue 绕过合并门禁。
+
+回访性质的 follow-up（例如发布后效果检查、观察期结束后的验证或问题修复后的跟踪确认）必须添加回访标签。优先使用项目已有的回访标签；没有对应标签时创建 `回访` 并添加。复用已有 Issue 时也要补齐标签，保留其他标签，并读回确认。正文写明回访时间或触发条件、检查对象和完成标准；尚未到回访时机的任务按等待项处理。
+
+| Follow-up 状态 | 处理 |
+| --- | --- |
+| 无阻塞，代码与所需资源均可用 | 直接创建独立 worktree，派发 sub-agent，要求调用 `ship-issue-pr` 完成同一套流程 |
+| 依赖当前 PR、其他任务或尚未满足的条件 | 在 Issue 按项目支持的状态/标签标记等待，写明阻塞对象与解除条件；条件满足后再派发 |
+| 需要额外外部资源、人工决策、账号或权限 | 只创建 Issue 并列出需要谁提供什么，不派发执行者 |
+
+主线程维护后续队列，记录 Issue、状态、依赖、worktree、agent ID 与交付进度，避免重复派发。运行中的依赖完成、当前 PR 合并或收到条件变更时重查等待项；如需跨会话等待，使用宿主可用的持久任务/提醒机制，记录唤醒条件与检查方式。宿主不支持持久等待时，将等待项与恢复条件明确交付，不能声称会自动唤醒。
 
-范围外问题先记录本地发现、影响和建议。任务已明确授权创建 follow-up Issue 或委派后续交付时才执行；每项沿用原授权边界，不递归扩大外部写操作或派发深度。
+子任务采用各自责任范围与正确基线，交接 Issue、验收、项目规则和完整交付终点。依赖父 PR 时等合并后从最新基线派发。子任务发现新问题仍创建 follow-up Issue，交回主线程统一去重与调度，避免重复或递归派发。外部资源后来齐备时，重新判断阻塞并进入可派发队列。
 
-已授权的独立后续任务使用各自责任范围与合适基线；依赖当前未合并改动时先准备，集成条件满足后继续。回收 worktree 前确认成果已保留、没有待整合改动，授权覆盖删除；squash 合并后不能仅凭分支名称判断可强删。
+主线程持续跟踪已派发任务直到完成或明确阻塞；follow-up 的等待不阻止满足门禁的当前 PR 合并。回收 worktree 前确认成果已保留、没有待整合改动且允许删除；squash 合并后不能仅凭分支名称判断可强删。
 
-最终报告实际终点、本次改动、验证、Issue/PR 链接及未完成项。已创建 PR、已设置自动合并、已合并和已回访分别陈述；仅本地任务以本地产物完成，不强制走到远端合并。
+最终报告实际终点、本次改动、复杂度、第三方执行情况、审查/修复/验证评论链接、Issue/PR 状态，以及 follow-up 的已派发、等待和外部资源清单。已设置自动合并与已合并分别陈述；有阻塞时明确停在哪一步、缺什么以及恢复条件。
 
 ## 按宿主选择工具
 
@@ -103,9 +146,9 @@ Issue/PR 多行正文写入本次任务独立的临时文件，用 `--body-file`
 | --- | --- |
 | Codex | 下文 Codex 运行时：通过 ask_cc / delegate-cc 咨询、审查或执行 |
 | Claude Code | 下文 Claude Code 运行时：通过可用的 Codex 插件协作 |
-| 其他或外部工具不可用 | 当前执行者直接完成可做的实现与自审，说明独立能力的限制 |
+| 其他或外部工具不可用 | 简单任务由当前执行者完成；复杂任务记录第三方通道阻塞，按第 4 步处理 |
 
-轻改动直接推进，无需为了加载技能探测另一套运行时。仅执行当前宿主适用的工具流程。外部执行者接手的是分配范围，完整交付与事实核验默认仍由主进程负责。
+简单任务直接推进。复杂任务必须使用当前宿主对应的第三方通道：Codex 调用 Claude Code，Claude Code 调用 Codex。普通同宿主 sub-agent 可承接 follow-up，但不替代复杂任务的第三方步骤。外部执行者接手的是分配范围，完整交付与事实核验仍由主线程负责。
 
 ## Codex 运行时
 
@@ -128,11 +171,11 @@ Issue/PR 多行正文写入本次任务独立的临时文件，用 `--body-file`
 
 ### 等待、验收与后续任务
 
-保存会话 ID，读取同一任务的流式结果；静默或宿主单次等待超时先排查，接管前确保旧写进程停止。依赖缺失或确实无法运行时主进程接手可完成的剩余工作，报告实际执行者与未完成验证。
+保存会话 ID，读取同一任务的流式结果；静默或宿主单次等待超时先排查，接管前确保原写进程停止。依赖缺失或确实无法运行时按第 4 步记录阻塞与已完成成果，不能把降级接手计为第三方完成。
 
 可核实的验证结果按共享流程复用，不因来自其他执行者而全部重跑。
 
-仅在已授权的后续交付需要独立执行者时，使用 `spawn_agent` 的可用角色，prompt 指定独立 worktree、目标、授权终点和责任文件，并要求调用 `ship-issue-pr`。子任务发现范围外问题先记录，不自动继续派发。
+对第 9 步已满足派发条件的 follow-up，使用 `spawn_agent` 的可用角色，prompt 指定独立 worktree、Issue、目标、交付终点和责任文件，并要求调用 `ship-issue-pr`。子任务发现新问题创建或复用 Issue，交回主线程统一调度。
 
 ## Claude Code 运行时
 
@@ -146,7 +189,7 @@ Issue/PR 多行正文写入本次任务独立的临时文件，用 `--body-file`
 - 普通审查：Codex companion 的 `review`。
 - 需要挑战方案假设时：companion 的 `adversarial-review`。
 
-通道不可用时主进程继续实现或自审并如实报告。
+通道不可用时按第 4 步记录复杂任务的阻塞，并继续可独立完成的准备。
 
 ### companion 与结果
 
@@ -165,6 +208,6 @@ node "<plugin-root>/scripts/codex-companion.mjs" review --wait --base "<actual-b
 
 根据实际权限判断补跑项，不预设沙箱不能联网、绑定端口或运行数据库测试。核对版本、命令、环境和可读输出后复用验证，只补缺失或失效项。
 
-等待期间主进程可继续不重叠工作。静默告警触发诊断，接管前确保旧写进程停止；无法使用外部通道时自行继续，不把自审冒充独立审查。
+等待期间主进程可继续不重叠工作。静默告警触发诊断，接管前确保原写进程停止；无法使用外部通道时记录阻塞，不把自审冒充独立审查。
 
-仅在已授权的后续交付需要独立执行者时，使用 `Agent(subagent_type: "general-purpose", run_in_background: true)`，指定 worktree、责任范围及授权终点，要求调用 `ship-issue-pr`。子任务发现范围外问题先记录，不自动继续派发。
+对第 9 步已满足派发条件的 follow-up，使用 `Agent(subagent_type: "general-purpose", run_in_background: true)`，指定独立 worktree、Issue、责任范围及交付终点，要求调用 `ship-issue-pr`。子任务发现新问题创建或复用 Issue，交回主线程统一调度。