@weotro/dx 0.1.12 → 0.1.14

package/README.md

@@ -302,7 +302,7 @@ dx cache clear -Y
 关于 `dx initial`：
 
 - `dx initial` 会把 npm 包内置的 `skills/` 覆盖同步到 `~/.agents/skills`。
-- 包内共享 agent reference 会覆盖同步到 `~/.agents/references`，供多个 skill 共用同一真源。
+- 技能的流程、运行时引用和脚本都放在各自目录内，随整个技能一同同步。
 - `~/.claude/skills` 中包内管理的同名非软链接 skill 会先删除，再创建指向 `~/.agents/skills` 的软链接。
 - `~/.codex/skills` 中包内管理的同名非软链接 skill 会被清理；已有软链接不会按旧副本删除。
 - 从包内移除的历史 skill 会在 `~/.agents/skills`、`~/.claude/skills`、`~/.codex/skills` 中一并清理。
@@ -312,6 +312,12 @@ dx cache clear -Y
 
 安装或升级 dx 后，运行 `dx initial` 即可同步。默认脚本位置为 `~/.agents/skills/delegate-cc/scripts/delegate_cc.py`；旧咨询入口为 `~/.agents/skills/ask_cc/scripts/ask_cc.py`。
 
+Issue/PR 交付统一使用 `ship-issue-pr`：在 Codex 中调用 `$ship-issue-pr`，在 Claude Code 中调用 `/ship-issue-pr`。技能按当前宿主选择工具，轻改动由当前执行者直接完成，需要外部协作时才读取对应运行时。
+
+升级 dx 后再次运行 `dx initial`，会整体更新 `~/.agents/skills/ship-issue-pr/`，并清理已移除的技能和独立引用文件。现有调用统一改为 `ship-issue-pr`。Claude 的软链接直接读取同一份更新；入口同时声明 Codex 和 Claude 的显式调用策略。外部 Claude CLI 或 Codex 插件仍需自行安装并完成认证，目录兼容不代表外部通道已可用。
+
+默认安装根目录固定为当前用户的 `~/.agents` 和 `~/.claude`；`dx initial` 当前不读取 `AGENTS_HOME` 或 `CLAUDE_CONFIG_DIR`。引用文件使用技能目录内的相对路径。需要从本仓库验证当前修改时，使用 `node ./bin/dx.js --config-dir ./example/dx/config initial`；日常 `dx initial` 同步的是当前安装的 npm 包内容。
+
 关于 `help`：
 
 - `dx --help`

package/lib/codex-initial.js

@@ -5,7 +5,7 @@ import os from 'node:os'
 import { logger } from './logger.js'
 
 const TEMP_DIR_PATTERN = /^\..+\.(tmp|backup)-\d+-\d+$/
-const MANAGED_AGENT_REFERENCES = ['ship-issue-pr-core.md']
+const REMOVED_AGENT_REFERENCES = ['ship-issue-pr-core.md']
 
 // 历史上曾在 skills/ 目录托管、但后续已删除的 skill 名称。
 // 来源：git log --all --diff-filter=A --name-only -- 'skills/*' | sed -n 's#^skills/\([^/]*\)/.*#\1#p' | sort -u
@@ -13,6 +13,8 @@ const MANAGED_AGENT_REFERENCES = ['ship-issue-pr-core.md']
 // 这些名字需要在 ~/.agents、~/.claude、~/.codex 三处彻底清理（软链或真实目录都清）。
 // 将来从 skills/ 删除新的 skill 时，把它追加到这里即可。
 const DELETED_SKILLS = [
+  'oo-ship-issue-pr',
+  'cc-ship-issue-pr',
   'autospec',
   'backend-audit-fixer',
   'backend-layering-audit-fixer',
@@ -29,7 +31,6 @@ const DELETED_SKILLS = [
   'pr-ship',
   'pr-train-ship',
   'create-issue',
-  'ship-issue-pr',
   'third-party-review',
 ]
 
@@ -151,43 +152,6 @@ async function copyDirMerge({ srcDir, dstDir }) {
   return { fileCount }
 }
 
-async function copyManagedFiles({ srcDir, dstDir, fileNames }) {
-  let fileCount = 0
-
-  for (const fileName of fileNames) {
-    const source = join(srcDir, fileName)
-    const target = join(dstDir, fileName)
-    const token = `${process.pid}-${Date.now()}`
-    const temporary = join(dstDir, `.${fileName}.tmp-${token}`)
-    const backup = join(dstDir, `.${fileName}.backup-${token}`)
-    let hasBackup = false
-
-    try {
-      const sourceStat = await fs.stat(source)
-      if (!sourceStat.isFile()) throw new Error(`agent reference 不是文件: ${source}`)
-
-      await fs.copyFile(source, temporary)
-      if (await lstatIfExists(target)) {
-        await fs.rename(target, backup)
-        hasBackup = true
-      }
-      await fs.rename(temporary, target)
-      if (hasBackup) await fs.rm(backup, { recursive: true, force: true })
-      fileCount++
-    } catch (error) {
-      await fs.rm(temporary, { recursive: true, force: true })
-      if (hasBackup && !(await lstatIfExists(target))) {
-        await fs.rename(backup, target)
-        hasBackup = false
-      }
-      if (hasBackup) await fs.rm(backup, { recursive: true, force: true })
-      throw error
-    }
-  }
-
-  return { fileCount }
-}
-
 async function removeManagedNonSymlinkSkills(skillsDir, skillNames) {
   for (const skillName of skillNames) {
     const target = join(skillsDir, skillName)
@@ -277,14 +241,12 @@ export async function runCodexInitial(options = {}) {
 
   const homeDir = options.homeDir || os.homedir()
   const srcSkillsDir = join(packageRoot, 'skills')
-  const srcAgentReferencesDir = join(packageRoot, 'agent-references')
   const agentsSkillsDir = join(homeDir, '.agents', 'skills')
   const agentsReferencesDir = join(homeDir, '.agents', 'references')
   const claudeSkillsDir = join(homeDir, '.claude', 'skills')
   const codexSkillsDir = join(homeDir, '.codex', 'skills')
 
   await assertDirExists(srcSkillsDir, '模板目录 skills')
-  await assertDirExists(srcAgentReferencesDir, '模板目录 agent-references')
   const skillNames = await collectSkillNames(srcSkillsDir)
 
   // 护栏：已删除名单不得与现存 skill 重叠，否则会把刚同步的 skill 又清掉（自相矛盾）。
@@ -296,7 +258,6 @@ export async function runCodexInitial(options = {}) {
   await ensureDir(codexSkillsDir)
   await ensureDir(claudeSkillsDir)
   await ensureDir(agentsSkillsDir)
-  await ensureDir(agentsReferencesDir)
 
   await removeManagedNonSymlinkSkills(codexSkillsDir, skillNames)
   await removeManagedNonSymlinkSkills(claudeSkillsDir, skillNames)
@@ -310,19 +271,17 @@ export async function runCodexInitial(options = {}) {
 
   await removeStaleTempDirs(agentsSkillsDir)
   const copyStats = await copyDirMerge({ srcDir: srcSkillsDir, dstDir: agentsSkillsDir })
-  await removeStaleManagedFileArtifacts(agentsReferencesDir, MANAGED_AGENT_REFERENCES)
-  const referenceStats = await copyManagedFiles({
-    srcDir: srcAgentReferencesDir,
-    dstDir: agentsReferencesDir,
-    fileNames: MANAGED_AGENT_REFERENCES,
-  })
-  await removeStaleManagedFileArtifacts(agentsReferencesDir, MANAGED_AGENT_REFERENCES)
   await removeStaleTempDirs(agentsSkillsDir)
   await linkSkillsToClaude({ skillNames, agentsSkillsDir, claudeSkillsDir })
+  if (await pathExists(agentsReferencesDir)) {
+    await removeStaleManagedFileArtifacts(agentsReferencesDir, REMOVED_AGENT_REFERENCES)
+    for (const fileName of REMOVED_AGENT_REFERENCES) {
+      await fs.rm(join(agentsReferencesDir, fileName), { force: true })
+    }
+  }
 
   logger.success('已初始化 skills 模板')
   logger.info(`agents skills: 覆盖复制 ${copyStats.fileCount} 个文件 -> ${agentsSkillsDir}`)
-  logger.info(`agents references: 覆盖复制 ${referenceStats.fileCount} 个文件 -> ${agentsReferencesDir}`)
   logger.info(`claude skills: 已创建 ${skillNames.length} 个软链接 -> ${claudeSkillsDir}`)
   logger.info(`codex skills: 已清理 ${skillNames.length} 个包内托管 skill 的旧副本 -> ${codexSkillsDir}`)
   logger.info(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -19,7 +19,6 @@
     "bin/",
     "lib/",
     "skills/",
-    "agent-references/",
     "LICENSE",
     "README.md",
     "package.json"

package/skills/ask_cc/SKILL.md

@@ -1,13 +1,21 @@
 ---
 name: ask_cc
-description: 仅在用户显式调用 $ask_cc 或明确要求使用 ask_cc 技能，或用户已显式调用的 oo-ship-issue-pr 流程要求咨询时使用；不要通过关键词、任务类型或上下文自动触发。
+description: 仅在显式调用 ask_cc 时使用：咨询 Claude Code 获取第二意见。
 ---
 
 # ask_cc
 
+## 执行边界与优先级
+
+在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
+只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
+仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
+
 使用 [delegate-cc](../delegate-cc/SKILL.md) 的咨询流程获取答案或第二意见，默认不授予工具权限。
 
-调用前完整读取该技能，按其中的活性监控、诊断和接续规则执行。咨询没有文件修改是正常现象，以本次会话的流式输出和进程状态辅助判断；静默只触发排查，不能仅因尚无答案就停止或换模型。
+已显式调用的 `ship-issue-pr` 需要咨询时可进入本技能，沿用原任务范围与授权。
+
+调用前读取该技能的咨询调用与结果处理部分，按需查看诊断和接续规则。咨询没有文件修改是正常现象，以本次会话的流式输出和进程状态辅助判断；静默只触发排查，不能仅因尚无答案就停止或换模型。
 
 若用户明确要求修改代码或执行开发任务，转入该技能的 `task` 模式，按任务范围完成实现和验收。
 

package/skills/delegate-cc/SKILL.md

@@ -1,18 +1,26 @@
 ---
 name: delegate-cc
-description: 仅在用户显式调用 $delegate-cc 或明确要求使用 delegate-cc 技能，或已获用户调用授权的 ask_cc、oo-ship-issue-pr 流程要求委派时使用；不要通过关键词、任务类型或上下文自动触发。
+description: 仅在显式调用 delegate-cc 时使用：委派 Claude Code 执行开发任务或咨询。
 ---
 
 # delegate-cc
 
+## 执行边界与优先级
+
+在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
+只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
+仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
+
 把 Claude Code 当作协作者。模型顺序固定为 Fable 5.1（`claude-fable-5-1`）→ Opus 5（`claude-opus-5`）→ 当前 sub-agent。保留本机现有认证。
 
+已显式调用的 `ask_cc` 或 `ship-issue-pr` 需要委派时可进入本技能，沿用原任务范围与授权。
+
 ## 1. 准备交接
 
 - **咨询 `consult`**：用户需要答案、决策建议或评审意见。提供问题、相关代码或事实、约束；CLI 无工具权限，只返回建议。
 - **执行 `task`**：用户要求实现、修复或把开发任务交给 CC。任务书必须包含工作目录、目标、可修改文件或模块、适用的项目指令、验收标准和仓库实际验证命令。明确告知 CC 还有其他协作者，保留他人的改动，只负责分配范围。
 
-执行前检查 `git status --short` 和已有 diff，记录涉及文件的初始状态及未跟踪文件。分配互不重叠的文件；需要并发改同一文件时，先拆分责任或使用独立 worktree，指定由谁整合。worktree 不会自动携带未提交改动，必须提供任务所需的当前版本。CC 执行期间，主 agent 不同时修改其负责的文件。
+执行前检查 `git status --short` 和任务涉及文件的 diff，记录这些文件的初始状态及相关未跟踪文件。分配互不重叠的文件；需要并发改同一文件时，先拆分责任或使用独立 worktree，指定由谁整合。worktree 不会自动携带未提交改动，必须提供任务所需的当前版本。CC 执行期间，主 agent 不同时修改其负责的文件。
 
 将任务书写入临时 UTF-8 文件，只传必要上下文，排除凭据。完成条件：CC 无需当前对话即可理解目标、权限范围与完成标准。
 
@@ -30,7 +38,7 @@ python3 "$HOME/.agents/skills/delegate-cc/scripts/delegate_cc.py" --prompt-file
 python3 "$HOME/.agents/skills/delegate-cc/scripts/delegate_cc.py" --mode task --cwd /绝对路径/工作区 --prompt-file /绝对路径/任务.txt
 ```
 
-需要 CC 自行运行验证命令时，按本次授权追加 `--allow-command '仓库实际验证命令'`，可重复传入。使用具体命令而非开放全部 Bash；检查命令本身及其调用脚本的作用。现有 Claude Code 权限规则仍生效，`--allow-command` 只是增加允许规则，不是独立沙箱。文件责任范围通过任务书和验收控制，需要隔离时使用 worktree 或已有沙箱。
+需要 CC 自行运行验证命令时，按本次授权追加 `--allow-command '仓库实际验证命令'`，可重复传入。使用具体命令而非开放全部 Bash；根据命令和已知脚本判断副作用，仅对未知或可能破坏数据的脚本进一步检查。现有 Claude Code 权限规则仍生效，`--allow-command` 只是增加允许规则，不是独立沙箱。文件责任范围通过任务书和验收控制，需要隔离时使用 worktree 或已有沙箱。
 
 执行模式保留默认编码系统提示，开放 `Read,Glob,Grep,Edit,Write,Bash`，使用 `acceptEdits`，不能获批的工具请求自动拒绝。两种模式都关闭 hooks、MCP 和技能，避免额外任务链；主 agent 应把所需项目规则及技能要求写入任务书。本技能不使用 `bypassPermissions`，也不扩大任务至提交、推送、部署或对外发送消息。
 

package/skills/delivering-design-handoff/SKILL.md

@@ -1,290 +1,33 @@
 ---
 name: delivering-design-handoff
-description: 仅在用户显式调用 $delivering-design-handoff 或明确要求使用 delivering-design-handoff 技能时使用；不要通过关键词、任务类型或上下文自动触发。
+description: 仅在显式调用 delivering-design-handoff 时使用：整理设计、实施计划与工程交接资料。
 ---
 
 # Delivering Design Handoff
 
-## Overview
+## 执行边界与优先级
 
-Turn an approved design into a ready-to-assign engineering package with one closed loop: spec, spec review and fixes, implementation plan, plan review and fixes, handoff doc, issue, branch, commit, push, issue assignment comment, and copyable assignment text.
+在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
+只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
+仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
 
-**Core principle:** after the design is approved, the user should not have to restate the delivery choreography. Each review gate must be completed and fixed before the next artifact is written.
+把已有设计整理为可交给工程师实施的文档。沿用已讨论的方向；尚有局部空缺时写明假设并继续草稿，不重新启动整轮设计问答。
 
-## When To Use
+## 文档与检查
 
-Use this only after the solution direction is already approved. If the design is still being explored, first use `brainstorming`.
+按项目惯例选择路径；无既有约定时使用：
+- 设计：`docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`，说明目标、方案、接口、兼容性、风险与验收标准。
+- 计划：`docs/superpowers/plans/YYYY-MM-DD-<topic>.md`，列出涉及文件、实现顺序、关键接口与实际验证命令。
+- 交接：`docs/superpowers/handoffs/YYYY-MM-DD-<topic>-handoff.md`，提供文档链接、实施顺序、风险和完成标准。小任务可按用户或项目要求合并文档。
 
-Typical user asks:
+设计、计划和交接草稿可并行完善；交付前核对三者一致性，修正实际影响实施的缺口。根据复杂度选择自审或独立审查，已有有效审查可复用；审查工具不可用时自行检查并注明限制。仅在需要相应写作方法且技能可用时读取 `brainstorming` 或 `writing-plans` 的相关章节。
 
-- “把这个方案写成设计文档并提 issue”
-- “写计划和交接文档，提交到 issue 分支”
-- “后续不想重复输入，从设计文档到 issue/分支/提交都自动做”
-- “给我一段可以直接复制给工程师的任务分配文字”
+## 交付
 
-## Required Output Contract
+1. 检查相关项目指令、分支及本次涉及文件的状态，保护已有改动。
+2. 完成任务要求的文档，检查关键接口、验收标准和失效链接；真实未决项标明假设与影响。
+3. 需要 Issue、提交、推送或分配评论时，先准备正文与明确文件清单，再按任务授权执行。只要求本地交接时，本地文档即可完成。
+4. 需要分支时从项目规定的基线创建，保留现有工作；按明确路径暂存并检查 diff。多行正文用临时文件与 `--body-file` 或 `git commit -F` 传递。
+5. 已授权发布交接评论时，包含分支、提交、文档链接和可复制的任务分配文字，并读回核对。用户或项目要求 PR 时，纳入本次交付。
 
-By the end, produce all of these or clearly state the blocker:
-
-| Item | Required shape |
-| --- | --- |
-| Design spec | `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`, created using the design-doc discipline from `brainstorming` |
-| Spec adversarial review | Reviewer subagent completed before the plan exists; valid findings applied to the spec, or explicit rejected findings with reasons |
-| Implementation plan | `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`, created by using `writing-plans` |
-| Plan adversarial review | Reviewer subagent findings applied to the plan, or explicit rejected findings with reasons |
-| Handoff doc | `docs/superpowers/handoffs/YYYY-MM-DD-<topic>-handoff.md` |
-| GitHub issue | Structured issue with background, goals, plan, acceptance criteria, and doc paths |
-| Issue branch | `codex/docs/<issue-id>-<slug>` for docs-only handoff, or matching repo convention |
-| Commit | Conventional commit ending with `Refs: #<issue-id>` |
-| Push | Branch pushed with upstream |
-| Issue comment | Comment linking branch, commit, spec, plan, and handoff, plus the same project-manager-style assignment block from the final answer |
-| Final answer | Short status plus a copyable project-manager-style assignment block |
-
-## Workflow
-
-### 1. Confirm starting state
-
-- Read project instructions: `AGENTS.md`, referenced ruler docs, and git workflow docs.
-- Check branch and worktree:
-
-```bash
-rtk git status --short --branch
-rtk git remote -v
-rtk gh auth status
-```
-
-- If there are unrelated dirty changes, do not overwrite them. If the handoff docs are the only dirty files, continue.
-
-### 2. Write the design spec
-
-Use `brainstorming` for the design-document phase. If the conversation already contains an approved design, do not restart exploratory questioning; treat that approved discussion as the input and apply `brainstorming`'s write-design-doc and self-review standards.
-
-Create `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`.
-
-Spec sections:
-
-- Background
-- Goals
-- Non-goals
-- Chosen approach and rejected alternatives
-- Backend/frontend/data/API design as applicable
-- Error handling
-- Testing and verification
-- Compatibility and risks
-- Acceptance criteria
-
-Run a self-review:
-
-```bash
-rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path>
-```
-
-Fix every hit that is a placeholder. A literal example such as `new BasePaginationResponseDto(total, page, limit, items)` is allowed; vague ellipses are not.
-
-### 3. Dispatch adversarial review
-
-Spawn one reviewer subagent. The prompt must include:
-
-- spec path
-- repo root
-- current approved design context
-- review axes: correctness, missing edge cases, repo convention violations, testability, and handoff ambiguity
-- “read-only, do not modify files”
-
-Apply all valid findings to the spec. If rejecting a finding, record the reason in the handoff doc's review notes and mention it briefly in the final answer only if material.
-
-**Gate before planning:** do not create the implementation plan until the reviewer subagent has returned, every valid spec finding has been fixed, every rejected finding has a recorded reason, and the spec placeholder scan has passed again. If the reviewer subagent is still running, timed out, or failed, this gate is not complete. If the user asks to save time by writing the plan while review or fixes are pending, decline that shortcut and finish this gate first.
-
-### 4. Create the implementation plan
-
-Announce and use `writing-plans`:
-
-> I'm using the writing-plans skill to create the implementation plan.
-
-Start this step only after Step 3 is complete.
-
-Create `docs/superpowers/plans/YYYY-MM-DD-<topic>.md` using the `writing-plans` required structure:
-
-- header with goal, architecture, tech stack, and global constraints
-- file map before tasks
-- bite-sized tasks with exact files, interfaces, steps, commands, and expected results
-- self-review for spec coverage, placeholders, and type consistency
-
-Run placeholder scan:
-
-```bash
-rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <plan-path>
-```
-
-Fix every true placeholder. Do not proceed to handoff until the plan can guide an engineer without asking back.
-
-### 5. Dispatch plan adversarial review
-
-Spawn one reviewer subagent for the plan. The prompt must include:
-
-- spec path
-- plan path
-- repo root
-- review axes: spec coverage, task order, file ownership, testability, missing code/commands, placeholders, type/interface consistency, and repo convention violations
-- “read-only, do not modify files”
-
-Apply all valid findings to the plan. If a finding reveals a spec defect, fix the spec too and re-check plan consistency.
-
-### 6. Write the handoff document
-
-Create `docs/superpowers/handoffs/YYYY-MM-DD-<topic>-handoff.md`.
-
-This is separate from the implementation plan. It is the short assignment packet for a human engineer:
-
-- Issue title and eventual issue id placeholder until issue exists
-- branch name placeholder until branch exists
-- links/paths to spec and plan
-- why the work matters
-- implementation order summary
-- top risks and invariants
-- required verification commands
-- delivery boundary and acceptance checklist pointer
-
-Run placeholder scan over all docs. Placeholders that must be filled before commit, such as issue id after creation, must not remain.
-
-```bash
-rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path> <plan-path> <handoff-path>
-```
-
-### 7. Create the GitHub issue
-
-Use heredoc, never `-m` or literal `\n`.
-
-Issue body must include:
-
-- Background
-- Goals
-- Plan
-- Acceptance criteria with objective checkboxes
-- Links or paths to the spec, implementation plan, and handoff doc
-
-Labels should match repo conventions. Prefer labels for backend/frontend/admin/database/api/docs when they exist.
-
-After issue creation, fill the concrete issue id and URL into the handoff doc if it used placeholders.
-
-### 8. Create the issue branch
-
-Fetch the base and create a clean issue branch:
-
-```bash
-rtk git fetch origin main --prune
-rtk git switch -c codex/docs/<issue-id>-<slug> origin/main
-```
-
-If the spec was created before switching, remember that untracked files usually follow the checkout but tracked edits may not. Verify both docs are present after the switch. If content disappears, recover it intentionally with `git show`, `git stash`, or re-apply the patch; never use destructive checkout/reset.
-
-After branch creation, fill the concrete branch name into the handoff doc if needed. Run final placeholder scan:
-
-```bash
-rtk rg -n "TBD|TODO|待定|占位|\\.\\.\\." <spec-path> <plan-path> <handoff-path>
-```
-
-### 9. Commit and push
-
-Stage only the intended docs:
-
-```bash
-rtk git add <spec-path> <plan-path> <handoff-path>
-rtk git diff --cached --stat
-rtk git diff --cached --check
-```
-
-Commit:
-
-```bash
-rtk git commit -F - <<'MSG'
-docs: add <topic> handoff
-
-变更说明：
-- 新增设计文档，固化已确认方案、风险、测试和验收标准。
-- 新增实施计划和交接文档，拆分实现任务、文件范围和验证命令。
-
-Refs: #<issue-id>
-MSG
-```
-
-Push:
-
-```bash
-rtk git push -u origin <branch>
-```
-
-Comment on the issue with branch, commit, spec path, plan path, handoff path, and the copyable project-manager-style assignment block from the final answer. This issue comment is mandatory; do not finish with only a local final answer.
-
-### 10. Do not create a pull request
-
-This skill stops after the handoff docs are committed, pushed to the remote issue branch, and linked from the GitHub issue comment. Do not create or update a PR for the docs-only handoff branch as part of this workflow, even when the repository's normal implementation flow expects PRs.
-
-If the user explicitly asks for a PR, treat that as a separate follow-up workflow after this handoff is complete.
-
-### 11. Final verification
-
-Before claiming completion, run:
-
-```bash
-rtk git status --short --branch
-rtk git log -1 --oneline
-rtk git rev-parse --abbrev-ref --symbolic-full-name @{u}
-```
-
-Report actual state. If no tests/builds were run because this is docs-only, say that.
-
-Read back the issue comments and verify that the latest handoff comment contains the branch, commit, spec path, plan path, handoff path, and the same assignment block shown in the final answer. If `gh issue comment` failed, the comment is missing, or the readback does not match the final assignment block, fix that before claiming completion.
-
-## Final Answer Template
-
-Keep it short, then include this copyable block:
-
-```markdown
-已准备好交接资料：
-
-- Issue：#<issue-id> <issue-url>
-- 分支：`<branch>`
-- 提交：`<sha> <subject>`
-- 设计文档：`<spec-path>`
-- 实施计划：`<plan-path>`
-- 交接文档：`<handoff-path>`
-
-以下交接评论已同步写入 Issue，可直接派发给开发工程师：
-
-请基于 `<branch>` 接手实现 Issue #<issue-id>：<issue-title>。
-
-先阅读：
-1. `<spec-path>`
-2. `<plan-path>`
-3. `<handoff-path>`
-
-实现时请按实施计划的 Task 顺序推进，并重点守住以下约束：
-- <top-risk-or-constraint-1>
-- <top-risk-or-constraint-2>
-- <top-risk-or-constraint-3>
-
-完成后请至少运行：
-- `<verification-command-1>`
-- `<verification-command-2>`
-- `<verification-command-3>`
-
-验收标准以 Issue #<issue-id> 的 checklist 为准。实现过程中如遇到与设计文档冲突的细节，先在 Issue 中同步风险和建议处理方式。
-```
-
-In Codex app, after successful git actions, also emit the app directives for branch creation, staging, commit, and push.
-
-## Common Mistakes
-
-- Writing the issue before the spec is stable and then forgetting to update links.
-- Writing the implementation plan before spec adversarial review has completed and valid findings have been fixed.
-- Skipping adversarial review because the spec “looks obvious”.
-- Treating the handoff doc as the implementation plan. The implementation plan must be produced with `writing-plans`, reviewed, and fixed before the handoff doc.
-- Skipping adversarial review of the implementation plan.
-- Creating the branch from the current stale feature branch instead of `origin/main`.
-- Committing on an unrelated branch.
-- Writing a handoff that says “add tests” without exact files, behaviors, and commands.
-- Forgetting the issue comment, leaving the receiving engineer to hunt for branch and docs.
-- Posting an issue comment with links only, but omitting the project-manager-style assignment block.
-- Creating or updating a PR for the docs-only handoff branch instead of stopping after commit, push, and issue comment.
-- Final answer lists artifacts but omits the copyable project-manager-style assignment block.
+最终给出实际产物链接、验证结果及简短可复制的交接文字：从哪个分支接手、先读什么、实施重点、验收命令。只报告实际完成的提交、推送和评论。

package/skills/doctor/SKILL.md

@@ -1,10 +1,16 @@
 ---
 name: doctor
-description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技能时使用；不要通过关键词、任务类型或上下文自动触发。
+description: 仅在显式调用 doctor 时使用：检查或修复本机 agent 开发环境。
 ---
 
 # Doctor
 
+## 执行边界与优先级
+
+在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
+只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
+仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
+
 ## 概览
 
 本技能用于把当前机器调整到可稳定运行 agent 开发工作流的状态。
@@ -13,7 +19,7 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
 
 ## 目标状态
 
-最终环境应尽量满足：
+完整环境体检时参考以下目标；单项修复仅检查目标工具及直接依赖，已有健康证据可复用：
 
 - `python3` 可用。
 - `python` 可调用 Python 3，或有清晰说明当前系统无需/不应创建该别名。
@@ -28,7 +34,7 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
 
 ## 执行原则
 
-- 先诊断，再修复；不要未经确认就重复安装已经健康的工具。
+- 先诊断，再修复；健康工具直接复用，已明确需要的可回滚修复自主执行。
 - 优先使用系统已有的包管理器和用户态安装路径。
 - 遇到多个可行方案时，选择对系统影响最小、最容易回滚的方案。
 - 对需要管理员权限、网络下载或会修改 shell 配置的动作，执行前简短说明影响。
@@ -37,7 +43,7 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
 
 ## 建议工作流
 
-1. 收集上下文：
+1. 按任务范围收集必要上下文；完整体检可检查：
    - 操作系统与架构
    - 当前 shell 与 PATH
    - `python3`、`python`、`node`、`npm`、`pnpm`、`dx`、`agent-browser`、`rg`、`gh`、`rtk` 的存在性与版本
@@ -46,12 +52,12 @@ description: 仅在用户显式调用 $doctor 或明确要求使用 doctor 技
 2. 对照目标状态判断缺口。
 3. 制定最小修复动作并执行。
 4. 每次修复后重新验证相关项。
-5. 所有项目完成后运行一次最终复检。
+5. 汇总已验证的结果，只补查仍缺证据或被后续修改影响的项。
 6. 输出报告。
 
 ## 验证要求
 
-最终复检至少覆盖：
+按本次修复范围选择验证项；完整体检覆盖下列适用项：
 
 - 每个目标命令是否可被当前 shell 找到。
 - 每个目标命令的版本或基本健康输出。

package/skills/gh-dependabot-cleanup/SKILL.md

@@ -1,15 +1,21 @@
 ---
 name: gh-dependabot-cleanup
-description: 仅在用户显式调用 $gh-dependabot-cleanup 或明确要求使用 gh-dependabot-cleanup 技能时使用；不要通过关键词、任务类型或上下文自动触发。
+description: 仅在显式调用 gh-dependabot-cleanup 时使用：修复 Dependabot 安全告警。
 ---
 
 # GH Dependabot Cleanup
 
+## 执行边界与优先级
+
+在宿主系统与开发者指令约束内，冲突时依次采用：当前任务的具体要求与已有授权 > 目标项目适用的 AGENTS.md > 本技能及其引用的通用流程。
+只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
+仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
+
 ## Overview
 Use this skill to complete a Dependabot remediation loop with minimal manual input. Rely on `gh` directly, fix all patchable alerts in scope, and document unpatched alerts without auto-dismiss.
 
 ## Closed Loop Workflow
-1. Confirm target and scope in one sentence.
+1. Infer the repository and scope from the task and current remote, state the choice, and fetch evidence without waiting for reconfirmation.
 2. Fetch open alerts with `gh api`.
 3. Classify alerts into:
    - patchable: has `first_patched_version`
@@ -19,7 +25,7 @@ Use this skill to complete a Dependabot remediation loop with minimal manual inp
 5. Apply dependency changes (prefer overrides/resolutions for transitive alerts).
 6. Refresh lockfile.
 7. Run required project verification commands.
-8. Commit, push, and open exactly one PR.
+8. For an authorized PR delivery, commit, push, and open a focused PR; a local remediation request finishes with the verified local changes.
 9. Report residual risk (unpatched alerts) in PR and final reply.
 
 ## Default Commands
@@ -49,6 +55,3 @@ Include these sections:
 2. Remaining alerts: alert id, reason (for example, no upstream patch)
 3. Verification: exact commands run and outcomes
 4. Risk note: what is deferred and why
-
-## Fast Trigger
-修复安全警告