let-it-go 使用指南

let-it-go 是一套研发工作流技能集：27 个技能，把「想法 → 交付」拆成标准步骤——需求、设计、拆解、实现、审查、交付——每一步由一个技能负责。

它让 AI Agent 能够像一个有经验的工程师一样——从理解需求、拆解任务、编写代码、审查质量，到最终提交合入——全流程自主完成。你只需描述功能想法，剩下的交给工作流。

两条安装路径，二选一即可。

方式一（推荐）：作为 skill 目录安装

# 安装全部 skills 到 ~/.agents/skills
npx skills add 9Ashwin/let-it-go

# 之后按来源更新
npx skills update -g

• skills 落到 ~/.agents/skills，这条装法不必动任何 profile 依赖。
• npx skills 递归扫描，安装时把 skills/<桶>/<技能> 拍平成 ~/.agents/skills/<技能>——技能根只扫一层，所以必须拍平。
• 选择技能时，picker 按根目录 .claude-plugin/marketplace.json 分成 Let It Go Flow / Bonus / Vendor 三组（共 27 项）；安装后仍是拍平的 ~/.agents/skills/<技能>，桶这一层只存在于仓库里。
• 这是最省事的一条路：不必动 profile 的依赖，对所有 profile 都生效。

手动拷贝时要自己完成拍平这一步——不要连桶一起拷：

# 拍平到 ~/.agents/skills/<技能>
cp -R <let-it-go>/skills/flow/graph ~/.agents/skills/graph

方式二（可选）：作为 bundle 安装

# 安装到 web profile
dsh plugin --profile web add -w github:9Ashwin/let-it-go

# 生产环境建议锁定到某个 commit
dsh plugin --profile web add -w github:9Ashwin/let-it-go#<sha>

# 验证安装
dsh --profile web --dump-config | grep -A3 let-it-go

• -w 不能省略：DSH 把 profile 当作 pnpm workspace 根，pnpm 9 缺少该标志时会报 ERR_PNPM_ADDING_TO_ROOT。
• 包里的 dsh.bundle 声明会让 dsh 把它追加进 profile 的 bundles 层，技能由包内自带的 provider 提供，不依赖 ~/.agents/skills 是否在技能根里。provider 的 patch 把 skills/flow、skills/bonus、skills/vendor 各列为一个技能根——技能根只扫一层，漏掉一个桶那一桶就会整体消失。
• 本包是 config-only bundle（纯配置包，没有构建脚本），因此不需要 allowBuilds 授权。
• 生产环境建议锁定 commit：github:9Ashwin/let-it-go#<sha>。
• 验证：dsh --profile web --dump-config | grep -A3 let-it-go，应看到 # == let-it-go-skills 层。
• 本地 checkout 联调：dsh plugin --profile demo add -w /path/to/let-it-go。

前置要求

从需求到交付的闭环工作流：

/prd → [跨两个及以上服务 / 改数据模型或迁移 / 两条以上对外契约 → /to-design] → /to-issues ─┬─→ /implement  （单单元：内联实现 → 门禁自证 → /review-it → /ship-it）
                                             ├─→ /loop-it    （串行：一次一个 Issue，带检查点恢复）
                                             └─→ /graph      （并行：按波次 fan-out，每节点独立 git worktree，波次间 fan-in 屏障）
                                                     节点：内联实现 → 门禁自证 → commit；波末：集成 → /review-it → /walkthrough → /ship-it

/prd 将一个模糊的功能想法转化为结构化的产品需求文档（PRD）：先把歧义问清楚，再把需求写成可验证的验收条件。它只产出 PRD，不拆 Issue——拆解交给 /to-issues。

触发方式

# 直接输入
/prd 给我们的任务管理系统加一个优先级功能

# 或使用触发词
写PRD：用户注册功能，支持邮箱和手机号
需求分析：为 API 增加限流能力

工作流程

• Agent 提出澄清问题（带字母选项，可快速回复 "1A, 2C, 3B"），数量随复杂度伸缩，不凑数
• 根据回答生成结构化 PRD（用户故事、功能需求、非目标、验收标准）
• 展示 PRD 供审阅，确认或调整
• 保存 PRD 到 tasks/prd-[feature-name].md
• 建议下一步：/to-issues 拆解为 Issue

输出示例

# 保存 PRD 后给出的下一步
✅ PRD saved to tasks/prd-priority-system.md

/to-issues    （把 PRD 拆成有阻塞关系的 Issue）

/to-issues 把 PRD（或任何一段需求描述）拆解为垂直切片的可独立实施 Issue，并创建到你选择的平台。可独立使用，不需要先运行 /prd。

触发方式

# 直接输入
/to-issues

# 或使用触发词
创建issue：基于 prd-user-auth.md 创建 Issue
拆解issue：把这段需求拆成可实施的卡片
生成卡片：把 PRD 拆成带阻塞关系的 Issue

输入来源

创建平台

工作流程

• 定位输入（自动检测 PRD、手动指定，或直接粘贴需求描述）
• 先识别 prefactoring（"让改动变简单"的铺垫工作），排在最前
• 拆解为垂直切片 Issue，把契约字段（目标 / 非目标 / 验收条件 / 必须收集的证据 / 外部边界 / 完成定义 / 未决问题）写进正文，标注 demo path 与显式 Blocked by 依赖边，按依赖顺序编号
• quiz 用户复核：粒度、依赖边、demo path 是否为行为而非某一层
• 选择创建平台（GitHub / Local）
• 阻塞者优先创建，逐条落地并输出汇总报告（含可立即开始的 frontier）

边界：/triage 只管从外面进来的条目

/to-issues 拆的是你自己的需求，产出已经是 agent-ready 的卡片；从外面进来的 bug 报告、用户反馈、别人提的需求归 /triage——先复现 / 理解，再定角色（ready / needs-info / bug-confirmed / duplicate / wontfix），并把 ready 的补成 agent 可执行的卡片。不要 triage /to-issues 产出的卡片。详见 18. /triage。

实现步骤由正在运行的 agent 内联完成：它读取 Issue 的标题、正文与验收标准（含其中引用的 PRD/SPEC），自己写代码、跑测试与 lint，直到验收条件全部满足。技能提供三条实现路线：只有一个单元时内联走 /implement，串行走 /loop-it，并行走 /graph。

/implement — 单单元内联闭环

一条 issue、一张卡片、spec 里的一项——只有一个单元时走这条路，闭环是：内联实现 → 项目门禁自证 → /review-it → /ship-it。它明确不建 worktree、不派子代理、不建波分支——那些是 /loop-it 与 /graph 的编排，单点上图或开循环只是多付编排成本。

• 先读清这个单元：把验收条件逐条列出来，读它引用的 PRD / SPEC / 设计文档，再读相邻代码与现有测试，让命名、错误处理与日志风格和仓库一致
• 就跑项目自己的门禁自证（mise run check、go build ./... && go test ./...、pnpm --dir web lint …）：边写边跑相关单测，最后跑一次全量；没被测过的验收条件不算满足
• 不扩张范围：不 force-push，不替用户拍含糊的验收条件（先问清楚），不把范围外的顺手改动塞进这份 diff（要改就另开一条）

参考：/test-first — 红 → 绿

需要先把行为定下来再写实现时用它：一个测试 → 一段实现 → 再一个测试，一次一个接缝。它同样是 /implement 内部会用到的参考，可以单独调用。

• 接缝要预先与用户约定：写任何测试之前，先把「要测哪些接缝」写下来并与用户确认——测不了所有东西，先约定接缝，精力才会落在关键路径与复杂逻辑上
• 三个反模式：与实现耦合（mock 内部协作者、测私有方法、从侧信道验证）、同义反复（期望值用与实现相同的方式重算，于是按构造就通过）、横向切片（先把所有测试写完，测的是想象出来的形状而非面向用户的行为）
• 循环规则：红先于绿（先写失败测试，再写刚好让它通过的最少代码）、一次一片（一轮 = 一个接缝 + 一个测试 + 一个最小实现）、重构不属于这个循环（它属于 /review-it）

节点作用域：实现 → 自证 → 只 commit

• 每个节点独享一个 git worktree 与自己的分支 feat/node-{N}-{slug}，所有编辑都发生在该 worktree 内
• 实现完成后，在自己的 worktree 内跑目标项目的门禁自证（如 go build ./...、go test ./...、mise run check），没有测到的验收条件不算满足
• 只 commit 到自己的分支：不 push、不开 PR、不合并，也不自审——节点的报告是证据而不是结论

/loop-it — 串行实现

• 获取仓库中所有打开的 GitHub Issue
• 解析 Issue 正文里的依赖关系，做依赖感知的拓扑排序，得到可安全开始的顺序
• 一次一个 Issue 内联实现（读需求 → 写代码 → 跑门禁自证），随后过一次 supervisor 检查——判据是证据（命令与真实输出），不是 diff 观感——再在该 Issue 自己的分支上 commit；不 push、不开 PR
• 批末把各 Issue 分支汇总成一条批次分支（不并入 failed 的分支），只做一次 /review-it、一次 /walkthrough 与一次 /ship-it
• 每次状态变更立即写入 .loop-state.json 检查点，崩溃或中断后可从断点恢复

适合节点之间大量共享文件、必须串行保证安全的场景；一次只处理一个 Issue。批末 PR 关闭多个 Issue，需按逐项证据表列出每项的 commit、关闭编号、验收证据与人工验收状态。

/graph — 并行实现

• 把一个任务（或 PRD / SPEC / Issue 集合）转化为有向无环图（DAG），按依赖关系分层为若干波次（wave）
• 每个波次里相互独立的节点由一个子代理 并发实现，每个节点独占一个 git worktree，并行编辑互不污染工作树
• 节点只 commit 到自己的分支；波次之间设强制 fan-in 屏障（BSP 语义）——等齐本波所有节点的完成通知后才收尾
• 屏障到达后统一收尾：泄漏检查 → 对每个节点过 evidence check（判据是节点报上来的证据：命令与真实输出，不是 diff 观感）→ 集成（只合并 shipped 的节点，failed 的绝不合并）→ 在集成后的树上跑门禁 → 评审一次（逐节点分节）→ ship 一次（一个 PR，关闭该波满足的 Issue）
• 每波写入 .graph_state.json 检查点，并据此重新渲染 graph.html 实时看板

适合 DAG 中存在真正并行度（相互独立的子系统）的场景。单节点波没有可集成的对象，跳过 wave 分支与 merge 仪式，直接对该节点分支 review + ship。详见 13. /loop-it 与 15. /graph。

失败节点：原地重试 → 重跑 → 剔除

• 先用继续消息复用该节点的上下文原地重试；仍失败再考虑作为新节点重跑，最后才剔除
• 其依赖节点标记为 blocked；其余兄弟节点照常 ship——波不是全有全无，但 failed 的分支永不合并，也不为推进波次而谎报 shipped

/review-it 是提交前的审查收尾：先跑门禁自证，再评审 diff，发现真实问题并迭代修复，直到没有可操作的发现。在当前契约里它按波 / 批调用一次，审的是集成后的 diff，而不是每个节点各自审自己刚写完的代码。

双轴：Spec 与 Standards，分开报告

每次评审回答两个不同的问题，分成两节报告，绝不合并成一张排序表——一旦合并，「命名与风格」的意见就会把「漏掉一条验收条件」淹没掉：

• Spec 轴 — 这份 diff 有没有做「要求的事」？先找到规格再读 diff：commit message 里的 issue 编号（gh issue view <n>）、用户给的路径、或对应的 tasks/prd-*.md / tasks/spec-*.md / docs/*.md；都不存在就说明「没有规格」，对着用户明确说过的要求审，不要发明需求。三种查法：要求了但缺的 / 没人要求却多做的 / 形状对但做错的。每条发现都要引用它对应的验收条件，才可证伪而不是偏好。
• Standards 轴 — 这份代码在本仓库里算不算好？即下面 8 个维度，按严重程度排序。

评审路径

没有外部 review CLI——/review-it 加载后，由正在运行的 agent 亲自按下面的审查原则审当前 diff，不会 shell out 任何 review 命令。

# 未提交变更（默认）：直接审工作树，含未跟踪文件
git status --short
git diff
git diff --cached

# 分支 / PR：先生成相对 base 的 diff，再逐段审
# base 取 PR 的 base，否则取仓库默认分支——不写死 main
base=$(gh pr view --json baseRefName --jq .baseRefName 2>/dev/null || git symbolic-ref -q --short refs/remotes/origin/HEAD | sed 's|^origin/||')
diff_file=$(mktemp)  # 固定 /tmp 名可被预创建，别用
git diff "origin/$base"...HEAD > "$diff_file"

diff 较大、或更看重独立性时，可把 diff 文件交给一个全新的子代理审——它看不到本会话的上下文，因此提示词必须自包含。

审查原则

审查模式

波级评审：一次、逐节点分节

• 评审对象是集成后的树：/graph 一波审 git diff main...wave-{K}-{slug}（单节点波直接审该节点分支）；/loop-it 一批审批末汇总出的批次分支
• 按计划顺序逐节点 / 逐 issue 分节读，重点看节点之间的结合部——共享接口、装配文件、配置与状态；这是逐节点自审结构上看不到的一类缺陷
• 这是这一波唯一的评审：绝不跳过，也绝不让某一个特性的小节吃掉整个 pass
• 采纳的发现先修复，再在集成后的树上重跑门禁，直到没有可操作的发现

/ship-it 是实现完成后的标准收尾流程：提交代码、创建 PR、合入、关闭 Issue，并一次写出实现总结评论（设计决策 / 偏离 / 权衡 / 待确认）。它是 PR body 的唯一产出者——/walkthrough 只提供证据，由它一次写进 body。在 /graph 一波或 /loop-it 一批的收尾里，它只调用一次：一个分支、一个 PR、一次 CI、一次 merge，关闭该波 / 该批满足的多个 Issue。

触发方式

# 直接调用
/ship-it

# 或使用触发词
提交代码
创建PR并合入

完整流程

# Step 1: 提交代码（关联 Issue）
git add <related files>
git commit -m "Add priority field to database (#42)"

# Step 2: 推送分支
git push -u origin feat/issue-42-priority-field

# Step 3: 创建 PR（body 包含 Closes #42）
gh pr create --title "Add priority field" \
  --body "Closes #42 ..."

# Step 4: 合入
gh pr merge --squash --delete-branch

# Step 5: 关闭 Issue（如未自动关闭）
gh issue close 42 --reason completed

多个 issue 共用一个 PR（波 / 批末模式）

/graph 一波与 /loop-it 一批默认把多个 Issue 收进同一个 PR（squash 后只剩一个 commit）。此时 PR body 必须逐项列出证据，不能只写一行 Closes #1 #2 #3——否则单项特性既没法审计，也没法单独回滚。

• commit 列必填：squash 之后这些提交在 main 上已经看不到，只有写进 PR body 才能按项追溯与回滚
• 验收证据要具体：写测试名或命令，不写「测试通过」
• 人工验收逐项标注：该项主路径没人走过就写「尚未人工验收」；只有用户明确确认后才能改，并注明确认依据（时间 / 环境）
• 逐项关闭 issue：每项各自写 Closes #N（或合入后手工关闭），不要合成一行
• 本 PR 由 N 项合并而成；squash 后如需撤销单项，按上表里的 commit 手工 revert

单项 PR（一个 Issue 一个 PR）不需要这张表，按上面的「完整流程」即可。

错误处理

/svg-diagram 是一套手写 SVG 图的「房屋风格」：把技术感的外观与对 CJK 友好的排版固定下来，并用机械检查证明图确实守了规矩。流程图、架构图、时序图这类「画出来给人看」的图都走它。

触发方式

# 直接输入
/svg-diagram

# 或使用触发词
画架构图：为技能加载流程画一张 SVG 架构图
画流程图：把这个模块的调用流程画成 SVG

规范覆盖

机械校验：tools/svg-lint

技能自带零依赖的 tools/svg-lint，对 SVG 跑 12 项检查：重叠、块间距、框高、连接线几何、箭头 marker、文字溢出、viewBox 裁切、字体栈、调色板一致性、浅底回退、基线偏移、XML 转义。

工作流程

• 图落到文档旁边的 assets/ 目录（如 docs/foo.md → docs/assets/foo-arch.svg）
• 在 Markdown 里用相对路径引用（![title](assets/xxx.svg)），不要把 SVG XML 内联进正文
• 生成后自己先走一遍校验清单，修掉间距、内边距、对齐与裁切问题再交给用户
• 文档里的数据变了，对应的 SVG 也要一起改——图和正文互相矛盾比没有图更糟

/refactor 基于 Martin Fowler《重构》第 2 版的完整目录，提供专家级代码重构能力。通过识别代码坏味道并应用经过验证的重构手法，在不改变外部行为的前提下改善代码的可维护性、可读性和结构。

两种模式

请求里同时含「找问题」和「改掉」时：先 audit，与用户确认发现，再在确认过的清单上切到 fix。

触发方式

# 直接输入
/refactor

# 或使用触发词
重构：重构 UserManager 类，它太大了
code smell：这个函数有 Feature Envy，修复它
extract method：把这个长方法拆分成更小的函数

代码坏味道目录

共识别 22 种代码坏味道，按五大类别组织：

重构手法目录

40+ 种重构手法，分 6 大类，每种附带机械步骤和对比示例：

安全协议

• 准备阶段：编写特征测试 → 提交当前状态 → 创建重构分支
• 每一步：一次仅做一处变更 → 编译通过 → 所有测试通过 → 提交
• 验证阶段：全部测试通过 → 手动冒烟测试 → 自审 diff → 最终提交
• 铁律：不改变外部行为，不混杂功能变更，每一步都有测试保障

语言专属指南

/modern-go 自动将 Go 代码升级为现代写法和 API，类似 go fix。扫描 go.mod 检测 Go 版本，对 Go 源文件批量应用版本适配的转换规则，覆盖从 Go 1.0 到 1.27+ 的 35+ 条规则。

触发方式

# 直接输入
/modern-go

# 或使用触发词
modernize：现代化改造这个项目的 Go 代码
升级Go代码：更新到 Go 1.22 的写法
gofix：扫描 pkg/ 目录并应用转换

工作流程

• 读取 go.mod 获取 Go 版本
• 在目标范围内（指定文件/目录/整个项目）查找 .go 文件
• 逐个文件扫描 "Before" 模式，应用所有版本 ≤ 项目版本的转换
• 每条转换附带简洁对照表和代码示例（before/after）
• 编辑完成后运行 goimports -w 清理 import
• 输出改造报告：文件数、应用转换数、已跳过的规则

转换规则目录（按 Go 版本）

安全规则

• omitzero 仅建议不自动应用（可能改变 JSON 序列化行为）
• SplitSeq 仅在循环体不需要索引或完整切片时应用
• strings.Builder 仅当拼接发生在循环内时应用
• 每次转换若需要新 import，自动添加并运行 goimports 清理

/walkthrough 在实现、验证和 /review-it 都完成之后、/ship-it 之前，产出一份可以直接交给 reviewer 的走查文档：说清改了什么、真的跑过什么、打印了什么，并用视觉证据证明 demo 路径确实走通。它的重点是证据而不是断言——diff 说明代码长什么样，走查说明你实际运行了什么、看到了什么。

触发方式

# 直接输入
/walkthrough

# 或使用触发词
走查：为 user-auth 生成交付前走查
交付前走查：整理这次改动的验证证据

走查文档的四个部分

输出

• 格式：Markdown，单个文件
• 保存到 tasks/walkthrough-<feature>.md（tasks/ 是这套技能集默认的工作产物目录）
• 文件名用 kebab-case；功能名优先取用户给的名字，其次从分支名或 tasks/prd-*.md / spec-*.md 推导，都没有就问用户
• 图片默认用相对路径（![caption](tasks/shot.png)）并随文件一起提交：文件小、diff 可读
• 只有文档必须独立存在时（贴进聊天、issue 评论等图片不会跟着走的地方）才用 base64 data URI，并说明用了哪种模式

定位

/walkthrough 只负责证据：命令与真实输出、可视化、风险点、人工验收状态。PR body 与合并清单不在这里产出——那是 /ship-it 的产物，由它写一次即可；走查再写一份就是同一份内容维护两处。它记录门禁输出，但不替代项目自己的门禁；没有验证过的步骤要如实写成未验证或阻塞，绝不写成已通过。

/loop-it 获取所有打开的 GitHub Issue，解析依赖顺序，一次一个 Issue 内联实现（读需求 → 写代码 → 跑门禁自证 → 记 evidence → supervisor 检查，判据是证据不是 diff 观感），只在该 Issue 自己的分支上 commit（不 push、不开 PR）。批末把各分支汇总成一条批次分支（failed 的分支不并入），只做一次 /review-it、一次 /walkthrough 与一次 /ship-it。进度持久化到 .loop-state.json，崩溃或中断后可从断点恢复。每条验收条件对应的观测以结构化 evidence 写进同一检查点，执行中发现的新任务以 followup 进队列——批次可以在跑的过程中长出新 issue，而不是被冻结在拆解那一刻的清单里。

如何调用

# 直接输入
/loop-it

# 或使用触发短语
批量实现: 实现所有issue
循环实现: 批量实现
恢复循环: resume loop

核心特性

• 前置检查 — 验证 gh 认证、git 状态、远程可达性、工作树清洁度
• 依赖拓扑排序 — 解析 Issue 正文中的依赖关系，按拓扑顺序处理
• 逐 issue supervisor 检查 — 每个 issue 实现后交给一个全新上下文的评审者看证据（命令与真实输出），判据是证据不是 diff 观感；/ship-it 仍只在批末一次
• 结构化证据 — 每条验收条件对应一次实际观测（test / runtime / database / external / human），带产生它的命令、结果与产物路径；deferred 与 pass 分得开，没跑的不会被写成通过
• follow-up 台账 — supervisor 判 follow-up 时把新任务写进检查点并随需求资料版本化；批末逐条收口，promote 成新 issue 再跑一轮，或写清理由 drop
• 检查点恢复 — 每次状态变更写入 .loop-state.json，崩溃后可断点续传
• 结构化错误恢复 — 10 类错误（构建、测试、lint、合并冲突、CI、认证、限流等），每类有独立恢复策略和重试上限
• 分支卫生 — 每个 Issue 独立分支 feat/issue-N-desc，只在自己的分支 commit（不 push）；批末汇总成批次分支，failed 的分支不并入且保留
• 依赖阻塞 — 依赖的 Issue 未 shipped 时自动跳过并标记 blocked
• 进度可观测 — 每个 Issue 后输出结构化进度（已交付/跳过/阻塞/失败/剩余）

流水线集成

# 从 PRD 到代码交付的完整流水线
/prd → /to-issues → /loop-it
                              │
                              └→ 每个 Issue：内联实现 → 门禁自证 → 记 evidence → supervisor 检查 → commit（× N）
                                 批末 ×1：follow-up 收口 → 汇总批次分支 → /review-it → /walkthrough → /ship-it

/to-design 把一份 PRD（或一个粗略想法）转化为 设计文档（design doc），文风借鉴 Go 官方提案：朴素的语言、具体的示例，以及最重要的——诚实地交代为什么选这个方案而不是别的。Markdown 提案是主产物；渲染成单文件 HTML 只是可选的呈现层，默认不渲染。

如何调用

# 直接输入
/to-design tasks/prd-priority-system.md

# 或使用触发词
生成设计文档：为优先级系统写一份 design doc
prd转设计文档：基于 prd-user-auth.md

什么时候用

• 已有 PRD，但在动手前需要先决定怎么建
• 方案有真实取舍，希望把它们记录下来供讨论
• 改动有风险、破坏性强或难以回退（设计文档会提前逼出兼容性讨论）
• 多人需要在工作分散开之前就方向达成一致
• 想留下一份"为什么选 X、否决 Y"的持久记录——即使方案最终被否决

设计文档结构（源自 5 篇 Go 官方提案）

工作流程

• 定位输入（PRD 文件 / Issue 链接 / 直接粘贴 / 仅描述想法）
• （可选）扫描代码库：现有模式、约束、可引用的真实痛点代码
• 找出真正的"决策分叉点"，提 3-5 个澄清问题
• 按 Go 提案风格生成设计文档
• 展示供审阅，重点看 Rationale 与 Compatibility
• 保存到 tasks/design-[feature-name].md

/graph 把一个任务（或 PRD / SPEC / Issue 集合）转化为有向无环图（DAG），按依赖关系分层为若干超步（wave），然后对每一层中相互独立的节点并发实现：每个节点由一个 subagent 在独立的 git worktree 中内联实现并 commit 到自己的分支；层与层之间用栅栏（fan-in barrier）汇聚——泄漏检查、逐节点过 evidence check、只合并 shipped 的节点、在集成后的树上跑门禁，然后评审一次、走查一次、ship 一次，并动态重规划下一层。PR body 与合并清单由 /ship-it 唯一产出，/walkthrough 只提供证据。

设计思想借鉴了当下热议的 graph engineering、LangGraph 的 StateGraph / Pregel-BSP 超步模型，以及动态工作流（dynamic workflow）的编排理念。

如何调用

# 直接输入
/graph tasks/prd-url-shortener.md

# 或使用触发词
并发实现：把这些 issue 变成任务图并行实现
任务图：build a graph 并发跑

核心概念（借自 LangGraph / graph engineering）

工作流程

• 拆解为节点 — 复用 /to-issues 规则，每个节点含标题、依赖、验收条件、类型、scope_hint（预计触碰的文件）
• 构建 DAG 并校验 — 检测环（按 id 打破）、悬空依赖、scope 冲突
• 拓扑分层 — Kahn 算法分层为若干 wave；同波内改动同一逻辑的节点串行到下一波
• 渲染图并确认 — 输出分层计划 + Mermaid 图，等用户确认后才 fan-out
• 逐波执行 — fan-out（一个响应内派发多个 subagent = 并发）→ fan-in 栅栏 → 汇聚、更新状态、动态重规划

核心特性

• Worktree 隔离（强制） — 每个节点独占一个 git worktree，并行编辑互不污染工作树
• Fan-in 栅栏（强制） — 上一波全部节点完成、且波级集成结束后，下一波才启动（BSP 语义）
• scope 冲突串行化 — 无依赖但改同一逻辑的节点自动分到不同波次；共享的"接线文件"（router/main）例外，不因此串行全图
• 动态重规划 — subagent 通过 NEW_WORK: 行上报新工作，栅栏处修订图并重新分层
• 失败阻塞下游 — 某节点失败则其所有依赖节点标记 blocked 并跳过
• 断点恢复 — 每波写入 .graph_state.json，崩溃后按波边界恢复；同时重新渲染 graph.html（浏览器打开后每 5s 自动刷新，实时跟踪波次、节点状态与进度）
• 并发上限 — 默认 3–4 个并发 subagent，避免限流与合并冲突

并发执行图

# 每波：fan-out → fan-in 栅栏
Wave 0 (并发×3):  #1 建表   #2 缓存层   #3 日志工具
Wave 1 (并发×2):  #4 API (依赖 #1)   #5 CLI (依赖 #2)
Wave 2 (并发×1):  #6 集成 (依赖 #4,#5)

# 每个节点在自己的 worktree 内：
内联实现 → 门禁自证 → commit 到自己的分支

# 每波末（只做一次）：
泄漏检查 → 逐节点 evidence check → 只合并 shipped 节点 → 集成后跑门禁 → /review-it → /walkthrough → /ship-it

流水线集成

/prd → /to-issues ┬→ /loop-it  # 串行：一次一个节点
                                        └→ /graph    # 并行：整波一起跑

/understand 把你刚生成的改动（通常是 AI 写的）变成一个单文件、可交互的审阅网页，帮你在审查或交付前真正吃透这次改了什么。它扫描仓库里未提交 / 分支变更，生成一个浅色主题的两栏页面：左侧是按真实项目布局排列的变更文件树，右侧是所选文件的语法高亮 diff，并在右侧边栏逐段给出相关单位需求与代码解释。

如何调用

# 直接输入
/understand

# 或使用触发短语
review 这次改动：解释一下这批新生成的代码
解释代码：带我过一遍刚生成的变更

页面构成

工作流程

• 扫描变更：已提交(base..HEAD) + 已暂存 + 未暂存 + 未跟踪新文件，基线为与主分支的 merge-base
• Agent 通读每处改动，再逐段撰写需求 + 解释注释
• 渲染出单文件 .understand/report.html 并在浏览器打开

定位

/understand 是 /review-it 的理解型搭档：/review-it 负责发现并修复问题，/understand 则帮你在决定采纳前，看清新生成代码背后的意图与理由。

/ask-flow 是整套技能集的入口：你想不起来这么多技能各自管什么，所以问。说清你现在的处境（一个还没成形的想法、一堆进来的 issue、一段调不通的代码、一次漫长的实现），它挑出该走的那一步，然后直接开始——读那个技能的正文并按它做，而不是只报一个名字让你再敲一遍。

触发方式

# 直接调用
/ask-flow

# 或直接问
该用哪个技能
这套流程怎么走

路由覆盖

• 主线：/prd → /to-design（有条件：只在跨两个及以上服务、改数据模型或迁移、涉及两条以上对外契约时写，不命中就跳过）→ /to-issues → 岔口（真并行 /graph / 串行 /loop-it / 单单元 /implement）→ 内联实现 → 门禁自证 → /review-it → /ship-it；交付前走查补 /walkthrough
• 旁路：有 bug 走 /diagnose，外面进来的原始条目走 /triage，先把行为定下来走 /test-first，正在解 merge / rebase 走 /conflict
• 直接开始那一步：路由之后读该技能的正文并按它做，不会只报一个名字让你再敲一遍；只有两条路真接近、或下一步越过人的判断边界（开 PR、合入、产品验收）时才停下来问
• 自报缺口：维护规则要求任何技能新增 / 改名 / 删除后都回来重读并更新这份路由，以及两份 README 与这两份 HTML 指南——说谎的路由比没有路由更糟

/triage 处理从外面进来的原始条目：bug 报告、用户反馈、别人提的需求。它先复现 / 理解，再给每条定一个角色，并把 ready 的补成 agent 可执行的卡片。/to-issues 产出的卡片不要 triage——那些已经 agent-ready。

角色（每条最后必须落到一个）

处理一条

• 先复现 / 先理解：按报告里的步骤重现；重现不了就明确说「我按 X 复现不了」，不要假装
• 判断影响面：影响谁、会不会坏数据、有没有绕过办法、是不是老版本才有
• 补成 agent-ready 的卡片：正文要写到「一个不共享本次对话上下文的子代理也能独立开工」——复现步骤、期望行为、验收条件、涉及文件 / 模块、明确的非目标；这条标准与 /to-issues 一致
• 留痕：每条处理完在那个 issue 上留一条评论（角色 + 理由 + 下一步），不要只改标签；整批处理完把新增的 ready / needs-info / wontfix 数量报给用户

难 bug、偶发 flake 与性能回归的纪律：在有一条已经在「这个」bug 上变红的命令之前，不许开始推理——直接跳到「我觉得是这里」正是这个技能要防的失败。它不做 /review-it / /ship-it，定位清楚后按单点改动回主线。

触发方式

# 直接调用
/diagnose

# 或直接说
排查一下这个偶发失败
这个性能回归怎么回事

循环

• 建立反馈环路：先拿到一条紧的 pass/fail 信号（在这个 bug 上会红）——失败测试、curl / HTTP 脚本、CLI + fixture、无头浏览器、重放捕获的轨迹、一次性 harness、属性 / 模糊测试、二分 harness、差分环路。判据：能变红、确定、秒级、可无人运行
• 复现 + 最小化：确认红出来的就是用户说的那个失败，再砍到「去掉任何一个剩余元素都会变绿」
• 3–5 条可证伪假设：每条写出「如果 X 是原因，那么改 Y 会让 bug 消失 / 改 Z 会更严重」；写不出预测的是感觉。排序后的清单先给用户看（他们常有领域知识能瞬间重排）
• 一次只改一个变量地埋点：探针都要对应某条预测；优先级是调试器 / REPL > 有目标的日志 > 绝不「全打日志再 grep」。每条调试日志带唯一前缀（如 [DEBUG-a4f2]），收尾一次 grep 全清。性能回归先建基线测量再二分
• 在正确的接缝上补回归测试，再修：测试要能在调用点复现真实的 bug 模式；没有正确接缝本身就是结论（记下来，当成一条新 issue 走主线）
• 收尾清单：原始复现不再出现、回归测试通过（或「无正确接缝」已记录）、所有 [DEBUG-...] 埋点已清除、一次性原型已删除、最终成立的那条假设写进 commit / PR 说明

/conflict 解进行中的 git merge / rebase 冲突：先查清两边意图，再逐 hunk 解，跑项目门禁，把这次操作做完。永远解，不 --abort。

步骤

• 看清现状：git status、git log --oneline --graph -10、列出冲突文件；确认这是 merge 还是 rebase、从哪分出来的、这次合并要达成什么
• 找出每处冲突的原始意图：读两边的 commit message、看对应的 PR 与 issue、必要时 grep 调用方——不要只看哪边新、哪边大就选哪边
• 逐个 hunk 解：能同时保留两边意图就都保留；真的不兼容时，选与本次合并目标一致的那一边，并把这个权衡写进 commit message，绝不发明新行为
• 跑项目门禁：至少构建 + 测试；判据是合并后的树自己通过门禁，而不是「两边合起来看起来对」
• 收尾：git add 全部冲突文件，把这次操作做完（rebase 时 git rebase --continue 直到所有提交重放完），再把「哪边让了什么」写进 commit / PR 说明

skills/vendor/ 放的是第三方技能的逐字副本：它们不是这套技能集写的，只是被收进来一起安装。谁、从哪个 commit 收的，由 skills/vendor/vendor.json 这份 manifest 记录，每个技能目录里还有一份 NOTICE.md（来源 / commit / 许可 / 同步日期）。

维护命令

make vendor        # 按 vendor.json 里钉住的 commit 同步
make vendor-check  # 报告上游是否已前进
make vendor-update # 重新钉到上游默认分支 HEAD、同步、再校验
make vendor-list   # 列出已 vendor 的技能与 commit
make vendor-add URL=<git url> SKILL="名字 [名字...]"
make check          # 布局、frontmatter、交叉引用、bundle patch
make test           # 先 check，再跑各脚本自测

Q: 必须按顺序使用所有步骤吗？

不必。每个 Skill 都是独立的，可以单独使用。比如你已经有 Issue 了，可以直接从实现开始——单个单元走 /implement，串行走 /loop-it，并行走 /graph；代码已经写好，可以直接用 /review-it 审查。但完整走一遍流程能获得最好的效果。

Q: /goal 是什么？为什么不在 skills 目录中？

在 DSH 中，/goal 是命令而不是 skill，因此不在 ~/.agents/skills 中。它由人类在命令行输入，创建一个带自动续跑轮次的持久目标；这条能力的模型侧是 create_goal / update_goal，但 create_goal 只在顶层直接的人类回合执行——子代理、或正在编排的技能，都无法给自己铸造一个长期目标。而「实现 Issue」这一动作与它无关，由 agent 内联完成（见 Step 2: /implement · /loop-it · /graph）。

Q: 可以在非 GitHub 项目中使用吗？

可以。/to-issues 支持把 Issue 保存为本地 Markdown 文件。/review-it 只需要本地 git 仓库。/ship-it 目前依赖 GitHub（gh CLI）。

Q: /review-it 和手动 code review 的区别？

/review-it 是自动化的自查（self-review），在提交前发现明显问题。它分两轴报告：Spec 轴查这份 diff 有没有做「要求的事」（缺的 / 多做的 / 做错的，每条引用对应的验收条件），Standards 轴按 8 个维度查代码质量。两轴分开报告、不合并排序。它不替代团队 code review，而是在 PR 创建前提升代码质量，减少 reviewer 需要指出的低级问题。

Q: Issue 粒度应该多大？

每个 Issue 应该是一个 Agent 在单次会话中可以完成的工作量——通常是 1-3 个文件的变更，有明确的验收标准。这个粒度由 /to-issues 把关，拆完你可以调整。

Q: skills/vendor/ 里的技能可以直接改吗？

不要。skills/vendor/ 下都是上游技能的逐字副本，就地编辑会在下次 make vendor 时被覆盖。要改就先改 skills/vendor/vendor.json 里的 manifest，再重新同步；如果你要做的是这套技能集自己的改动，那就写成一个 flow / bonus 技能。详见 21. Vendor 技能与一键同步。

Q: /svg-diagram 的机械校验包含哪些检查？

它自带零依赖的 tools/svg-lint，共 12 项检查：重叠、块间距、框高、连接线几何、箭头 marker、文字溢出、viewBox 裁切、字体栈、调色板一致性、浅底回退、基线偏移、XML 转义。规范本身还覆盖布局、连接线与箭头的画法，以及 CJK 字体栈。