| name | coding-agent-workflow |
| description | 代码任务委派三层决策——自己做 / 本 session sub-agent（Task tool）/ 外部 Codex session（spec 文件）。Use when 任何代码/调研/重构任务开工前判断谁来做，或用户说「派个 agent」「让 codex 搞」「并行跑」。 |
Coding Agent 委派三层决策
三层分工
| 层 | 工具 | 适用 | 边界 |
|---|
| L0 自己做 | 直接 Read/Edit/Grep | 改 <3 文件、上下文已在手、单一逻辑 | context 预算够、不涉及 ~/Orb/src/ |
| L1 Sub-agent（本 session） | Task tool（Explore / general-purpose / feature-dev:* / pr-review-toolkit:*） | 护 context（大量 grep/read）、并行独立调研、专项审查 | 不能改 ~/Orb/src/；不做 synthesis |
| L2 外部 session（Codex / CC） | specs/xxx.md + external-session-spawn.sh 派遣 | 改 Orb 源码铁律、跨 session 隔离、大重构 (≥10 文件)、长程 audit / 治理（worker timeout 风险） | 必须先写 spec；走 launcher 自动回报，不裸跑 codex/claude |
Trigger 判别
→ L0 自己做
- 改动 <3 文件 且 不碰
~/Orb/src/
- 只读分析 + 短回答
→ L1 sub-agent（Task tool）
- 需要跑 ≥3 次 grep/glob 才能定位 →
Explore（"quick/medium/very thorough"）
- 多个独立域并行调研（同时查 Linear API + Slack manifest）→ 多个
Task 并发
- 写完代码让人审 →
pr-review-toolkit:code-reviewer
- 架构设计 →
feature-dev:code-architect
→ L2 外部 session
- 动
~/Orb/src/*.js、package.json、start.sh、config.json（自改会崩 + CLAUDE.md 铁律）
- 改动预估 ≥10 文件或 ≥架构级
- 需要跨 session 隔离（本 session context 已满 / 实验性改动）
- 长程 audit / 大型治理任务（预估 worker turn 跨度 >30min 或多次 turn）— 见下节专门规则
长程 audit / 大型治理：默认 codex 化（体制铁律）
症状识别：任何「全面审计 / 整体治理 / 跨多个子系统的 cleanup / 重大 refactor」类任务，默认走 L2 codex 化，主 thread 只做 dispatch + 回报。
为什么不能挂在主 worker 跑：
- Worker timeout =
ORB_WORKER_TIMEOUT_MS 默认 30min，长程任务必然超时。worker 死 → task card 卡半截 + 用户什么都看不到（即使 task-card-interrupt-recovery 已 ship 中断红条 + sticky snapshot，那只是降级显示，进度本身丢了）。
- Slack stream 是 per-turn-per-message 设计（lessons/slack-stream-chunk-semantics.md）：跨 turn
inject 必新建 stream，原 task card 不延续。Karry 看到的进度被切碎到多个独立卡。
- Context 中段衰减 30%+（agent harness 文献）：长 prompt 中段信息容易被忽略，长程任务在主 worker 反而比 codex 单跑次数多 + 错。
正确姿势：
长程任务到来
↓
主 thread 写 spec → external-session-spawn.sh --engine codex --spec <path>
↓
立即拿到 pid / log，主 thread 回 Karry 一句「已派，跑完自动回报」
↓
codex 后台独立跑（不受主 worker timeout 影响）
↓
跑完自动 chat.postMessage ✅ 推回原 thread
↓
主 session 验真 + commit + 归档
实证（2026-05-08）：Orb 全面审计治理 thread。原始一锅塞主 worker 跑：第一轮 30min timeout 中途挂，task card 显示半截进度，必须发「继续」重启。改成 spec + 串行 codex 派遣后（fork-A orb-fork-a-cleanup-2026-05-08.md / fork-A 余项 orb-fork-a-safe-2026-05-08.md / task-card-interrupt-recovery-2026-05-08.md 等），每个 codex 独立跑完自动回报，主 worker 可任意 idle/重启，进度永不丢。
反例：
| 误用场景 | 后果 |
|---|
| Karry 说「全面审计 X 系统」直接在主 thread 自己干 | 30min 后 timeout，task card 半截 |
| 「重构 5 个模块」全塞 TodoWrite + 自己执行 | turn 跨度太长，stream 切碎多卡 |
| 「调研 10 个第三方库 + 写报告」自己读 | context 衰减 + 调研结果稀释主结论 |
正解：上述场景第一动作是写 spec → 派 codex；主 thread 只做选型 + 回报判断。
例外（仍可主 worker 跑）：
- 任务本身 <30min 可见完结
- 用户显式「你直接干，不要派 codex」
- 紧急修复必须立即出结果（codex 派遣 + 等回报 ≥ 2min 启动开销）
L1 触发=必须清单（硬阈值，事件驱动）
偷自 runesleo/claude-code-workflow v2（2026-04 CHANGELOG）。背景：他 30 天实测 agent 分派率仅 0.18%（44/24722 API calls），结论是「软建议无约束力，触发=必须才有」。Orb 同样有 skill 但偏软，本节把 L1 判别从描述升级成铁律。
命中以下任一条件必须派 L1 sub-agent，不得自己硬扛：
| 触发 | 必须分派到 | 原因 |
|---|
| Read ≥3 文件才能回答单个问题 | Explore (medium) | 护主 session context |
| 跨目录 Grep ≥3 轮才能定位 | Explore (very thorough) | 同上 |
| URL 研究 / GitHub repo 调研 / 第三方文档抓取 | Explore 或 general-purpose | 整 repo / 整文档塞主 session = 浪费 |
| ≥3 个独立域并行调研（互不依赖） | 多个 Task 并发 | 串行浪费时间 |
| 写完非 trivial 代码 ≥50 行 | pr-review-toolkit:code-reviewer | 自审有盲点 |
强制留痕：每次 L1 分派必须输出一句 🔀 分派 → <agent_type>：<一句话目标>。便于事后 grep transcript 审计漏派。
反向铁律：命中清单条件未派 = 流程作弊。事后发现写 lesson 复盘到 ~/Orb/profiles/<your-profile>/data/lessons/agent-dispatch-miss-*.md，标记触发场景 + 漏派代价。
例外：
- 任务本身就是「读 1 个特定文件回答 1 个具体问题」→ L0 自己做（即使 ≥3 行 grep 也走 L0，因为目标文件已知）
- Karry 显式说「你直接干」→ 服从
L2 内部选型：Codex vs CC（铁律：默认 Codex，切 CC 必须声明）
L2 派遣默认 --engine codex，无需理由，直接用。
切换到 CC 必须命中以下条件之一，且分派前输出一句 🔀 CC 理由：<原因>：
| 切 CC 的条件 | 原因 |
|---|
| 任务需要多轮探查 + 反复试错，spec 无法预写完整 | Codex 一次性 exit，探查型任务需要 agentic loop |
| 必须复用 Orb 的 skills/CLAUDE.md 体系 | CC 起在 workspace/ 能直接吃 skill + memory，Codex 是裸的 |
| 任务边界模糊，需要在歧义点停下确认 | Codex 不反问，边界模糊时会猜错方向 |
未声明理由直接选 CC = 流程违规，事后发现写 lesson 复盘。
决策流（举证责任在 CC 一侧，不在 Codex 一侧）：
有 CC 条件？
├─ 是 → 输出「🔀 CC 理由：xxx」→ --engine claude
└─ 否 → --engine codex（无需声明）
对照参考（参考，不是规则；规则是上面的 CC 条件表）：
改 Orb src/ 单文件 + spec 清晰 → Codex
改 Orb src/ 跨模块 + 需要探查 → CC（命中条件①）
独立子项目（不依赖 Orb skill 体系） → Codex
视觉/文档/agentic loop 类 → CC（命中条件①②）
长程 audit / 多模块治理 → Codex
为什么这样加固：默认 Sonnet 环境下，无硬约束的「软建议」会导致 CC 的选用频率远超预期。铁律 = 举证责任在 CC 一侧，不在 Codex 一侧。
L1 Sub-agent prompt 模板
[目标]：一句话目标
[背景]：为什么做（非 synthesis，只给事实）
[范围]：可以看/改的文件或目录
[约束]：不能改什么、不能重构什么
[输出]：期望返回格式（发现清单 / 诊断 / diff 路径），字数上限
反例："根据你的调查来修 bug" ← synthesis 外包了
正例："定位 src/scheduler.js 里负责 stream lifecycle 的函数，返回函数名 + 行号 + 30 字职责"
L2 派遣：external-session-spawn.sh（默认入口）
执行铁律：决定走 L2 后，第一个 Bash 命令必须是 external-session-spawn.sh。
禁止先尝试 codex exec / claude -p 再转 launcher——这是最常见的错误路径，会浪费 2 步且被 hook 拦下。
禁止传 --model / -m 给 codex——不指定模型，让 codex 自己判断。
直接跳到 launcher 命令；hook 会在裸跑时 block 并提示，但那是防守线不是工作流程。
默认必走 launcher，不裸跑 codex exec / claude -p。launcher 解决两个问题：
- 标准姿势固化（codex
--cd ~/Orb + bypass + </dev/null + stderr 噪音过滤；claude -p + skip-permissions）
- 自动完成回报——后台跑完用
chat.postMessage 推回原 thread，不需要 Karry 催「好了吗？」
~/Orb/scripts/workflow/external-session-spawn.sh \
--engine codex \
--channel <slack-channel-id> \
--thread <slack-thread-ts> \
--label "<人类可读标签>" \
--log /tmp/<engine>-<topic>-$(date +%s).log \
--prompt "严格按 specs/<topic>.md 执行。只改 spec 列出的文件,不 git add/commit。完成后输出 diff 摘要。"
--engine claude 用法相同，prompt 直接是任务描述（不必引用 spec，Claude Code 会读 skills/CLAUDE.md）。
调用方做的事：
- 立即拿到 launcher stdout 输出的
pid + log + label
- 在 thread 回 Karry 一句「已派 X，跑完自动回报」
- 不再用 ScheduleWakeup 猜时间——launcher 完成后 Bot 自发的 ✅ 消息会出现在 thread
Bot 自发消息默认不触发新 worker（adapter 忽略 self），不会循环；Karry 看到 ✅ 后若要详细 diff/commit，主动问就好。
五个铁律（launcher 内部已实现，调用方了解原因即可）
--cd 必须是 ~/Orb，不能给子目录。原因：codex sandbox 把 --cd 当可写根，给 workspace/ 会让 ~/Orb/profiles/<your-profile>/scripts/ 被踢出可写域，4/30 daily-notes-monitor regex 修复就栽在这。</dev/null 强制关 stdin — codex 检测到 stdin open 会等输入，heredoc/pipe 喂 prompt 都会触发挂起- prompt 走位置参数，不走 heredoc / pipe /
<<EOF
--sandbox workspace-write + -c approval_policy='"never"' + -c sandbox_workspace_write.network_access=true + spec 里禁止 codex 动 git — 替代旧 --dangerously-bypass-approvals-and-sandbox（5/2 切换）。新姿势：~/Orb 顶层 + /tmp + $TMPDIR + ~/.codex/memories 在 sandbox 内可写，网络启用，approval 不阻塞；写域外（如 Karry 别处文件）会被拒，比 bypass 多一层护栏。git diff 仍由主 session commit。- stderr 过滤
failed to record rollout items: thread — codex_core 内部 rollout 持久化噪音，每次 exec 都出现且不影响执行
调用反例速查
| 写法 | 踩的坑 |
|---|
裸跑 codex exec ... 不走 launcher | ⚠️ 没自动回报，要 Karry 催「好了吗」 |
codex exec --cd ~/Orb/profiles/<your-profile>/workspace ... | ① sandbox 把 workspace 当可写根，profiles//scripts 被踢出 |
echo "干活" | codex exec ... | ② stdin 管道，挂 |
codex exec <<EOF ... EOF | ② heredoc，同样挂 |
codex exec --sandbox workspace-write "...动 .git..." | ③ sandbox 拦 .git/index.lock |
不加 --cd，cwd 飘 | 改错文件 |
| spec 里写「commit 一下」 | codex 边写边 commit，主 session diff 回收混乱 |
| 不过滤 stderr | rollout ERROR 每次出现，混淆真错误 |
强制：~/Orb/profiles/<your-profile>/workspace/.claude/hooks/codex-exec-guard.sh 已升级为 block 模式（PreToolUse Bash hook，exit 2 阻断）。命中铁律 1-4 任一坑会被直接拦下。launcher 内部已经合规，所以裸调用 launcher 不被 block；如果绕过 launcher 自己写 codex exec 命令，hook 还在守底线。
何时仍可裸跑（罕见例外）
只在以下场景手动调用 codex exec / claude -p（不走 launcher）：
- 一次性命令行测试 / 调试 launcher 自身
- 不需要 Slack 回报的本地探查（短任务 < 30s）
- 没有 thread 上下文（cron 等已经有自己的失败回报机制）
例外场景仍然受 hook 管制，必须用标准模板。
L2 spec 模式：自动测试 + commit + 归档 + 串联
加 --spec <path> 参数即触发后置流水线（2026-05-07 引入）。codex 与 claude engine 都生效，行为一致。
~/Orb/scripts/workflow/external-session-spawn.sh \
--engine codex \
--channel <id> --thread <ts> --label "..." --log /tmp/... \
--prompt "严格按 specs/<topic>.md 执行..." \
--spec ~/Orb/profiles/<your-profile>/workspace/specs/<topic>.md
行为分工
| 谁干 | 干什么 |
|---|
| session 内部（codex / claude 都一样） | 跑 spec ## 验收 段所有测试命令；删自己在 /tmp 创建的中间产物；删自己产生的 untracked 调试文件；不动 git |
| launcher（rc=0 后内联 bash） | git mv spec → specs/.archive/<basename>-<YYYY-MM-DD>.md → git add -A && git commit -m "codex: <spec title>" → 解析 next_spec 串下一份 |
launcher 的 prompt 注入前缀（自动 prepend，不需要写进 spec，两 engine 都注入）：
完成主任务后、退出前必须依次：①跑 ## 验收 测试，全绿才继续；②删 /tmp 中间产物；③删 untracked 调试文件；④不动 git。
engine 差异：claude 已有 CLAUDE.md + verification-before-completion 等 skill 体系覆盖类似纪律，prompt prefix 与之冗余而不冲突；codex 是裸的，prefix 是其唯一约束源。两边的 launcher 后置（commit + 归档 + 串联）完全一致。
Frontmatter（spec 顶层 YAML）
只有一个可选字段：
---
next_spec: specs/step2.md
---
...
无 frontmatter / 无 next_spec = 单步任务，跑完归档 commit 即结束。
多步串联
next_spec 在 launcher commit 完成后被 fork 起一个新的 launcher 进程（同 channel/thread），label 自动加 → next:<basename>，递归同行为。串联自动跟随上游 engine——上游 codex 串 codex，上游 claude 串 claude，无需手动指定。
任一步测试挂 → session exit ≠ 0 → 走原 ❌ 分支，spec 保留原位不归档不 commit不串联，链终止，failure 推 Slack 兜底。
适用场景
- ✅ 单步独立任务（最常见）—— 跑完自动归档 commit
- ✅ 多步串联（A 完成 + 测试通过 → B 自动起）—— 在 spec A frontmatter 写
next_spec: specs/B.md
- ✅ 长程 audit / 大型治理（多 fork 拆分各自 spec，串联或独派）
- ❌ 需要主 session 介入的多步（中间要 Karry 决策 / 看 diff）—— 不要串，分次手动派
Spec ## 验收 段写法（决定 session 跑什么测）
## 验收 段下的命令行/检查项是 session 自检的依据。写得越具体，session 自跑越准：
## 验收
- [ ] 单测：`cd ~/Orb && npm test -- scheduler`
- [ ] lint：`cd ~/Orb && npm run lint`
- [ ] 手动验证（session 跳过此项，由主 session 后置）：发 /xxx 到 #test
- [ ] git diff 行数 < 300
session 会跑能跑的命令（前两个），跳过纯人工项，全绿才退出 0。
L2 外部 Codex spec 模板
放 ~/Orb/specs/<topic>.md：
---
next_spec: specs/<next-topic>.md # 可选；多步任务才填
---
# <Topic>
## 目标
<一句话>
## 背景 / 根因
<为什么改，指向具体 bug/需求>
## 相关上下文位置
<外部 codex 不知道 Orb 有这些索引，显式告诉它去哪找；没有则写「无」>
- 对话记忆：holographic DB（`profiles/<your-profile>/data/memory.db`），trust>0.6 相关 facts
- 文件知识：docstore FTS（`profiles/<your-profile>/data/doc-index.db`，slug: <project-slug>）
- spec 前置 / 历史 spec：`specs/<related>.md`
- 运行时日志：`logs/orb.log`
## 变更范围
- 可改：src/scheduler.js (L120-180), src/worker.js (IPC handler)
- 禁改：adapters/*, lib/holographic/*, config.json
## 禁写区（默认值，每个 spec 必带）
codex 验收 / 自测期间禁止写以下生产数据，要造数据用临时 fixture：
- `profiles/<your-profile>/data/memory.db`（holographic 记忆，曾被 codex 验收时塞测试 fact）
- `profiles/<your-profile>/data/cron-jobs.json`（活 cron，写错会乱 schedule）
- `profiles/<your-profile>/data/sessions.json`（thread↔session 映射）
- `profiles/<your-profile>/data/doc-index.db`（DocStore FTS）
- `profiles/<your-profile>/data/daily-notes/*.md`（实时日记）
- 任何 `profiles/*/data/` 下的真实落盘文件
例外（spec 显式声明才能写）：
- 测试数据 fixture：写 `/tmp/` 或 spec 指定的 `tests/fixtures/`
- 本 spec 改动需要新增的产物：spec 显式写明路径
## 执行边界（硬约束，codex 必须遵守）
- 只改本文件「变更范围」列出的路径
- 不写「禁写区」列出的路径
- 不执行 `git add` / `git commit` / `git push`
- 完成后输出 diff 摘要，由主 session 回收并 commit
## 设计要点
1. ...
2. ...
## 收口协议
**每个 spec 执行 session 的降落规则（适用于 CC engine；Codex 单次 exit 不适用）：**
| 触发信号 | 动作 |
|---|---|
| 每完成一个主要阶段（研究/设计/实施/验收任一阶段边界） | 调 `scratchpad-append.py --kind decision` 写阶段快照：已完成/卡点/下一步 |
| 同一工具连续调用 ≥3 次且无明显进展 | 视为卡住：立即写 scratchpad checkpoint → 向 Karry 报告中断点 → 停止执行 |
| 感知到即将跑满 turns（context 压缩已发生 / 同一文件反复读 / 同一工具出现 3+ 次） | 主动降落：写 checkpoint + 报告 + 停止；不硬撑到 maxTurns 被动 stop |
**scratchpad 快照格式**：
```bash
python3 ~/Orb/profiles/<your-profile>/scripts/scratchpad-append.py \
--thread-ts <thread_ts> \
--kind decision \
--title "已完成：X；卡点：Y；下一步：Z" \
--body-file /tmp/checkpoint.md
为什么：maxTurns 跑满后 CLI 直接 stop，没有收口窗口。主动降落让 Karry 知道断点在哪，下次可以接续而不是重来。Orb 未来会在 context.js 注入 remaining turns 信号（spec: orb-remaining-turns-inject-2026-05-13.md），届时可机械感知阈值，目前靠 session 自律。
验收
执行
调研 turn ≤ X，实施 turn ≤ Y。
## 验证回收协议
收到 launcher 自动 ✅ 后：
1. **读 diff / 读 log**，不信任 launcher 摘要（"agent 说做了 X 不等于做了 X"）
2. **验禁写区**：`git status` + `ls -la profiles/<your-profile>/data/*.db profiles/<your-profile>/data/*.json` 看 mtime，禁写文件被改 = FAIL，回滚 + 改 spec 重派
3. 判级：
- **PASS** — 符合预期，commit
- **PARTIAL** — 列缺口，决定本地补 or 再派一轮
- **FAIL** — 分析原因（spec 不清 / context 不够 / 方向错），改 spec 重派，不手工救火
4. **架构级改动**（L2）commit 后追加 daily-note 一行
收到 launcher ❌ 时：直接看 log tail（消息附带前 800 字符），多数情况 spec 不清或 sandbox 误判，看清根因后改 spec 重派，不手工救火。
**spec 模式特别注意**：launcher 已自动 commit + 归档，回收协议第 1-2 步仍要做（验真）；如果 commit 内容超出 spec 范围或有禁写区污染，用 `git revert <hash>` 回滚而非 reset（commit 已落盘）。
## 禁区
- ❌ **禁止派 sub-agent（L1）改 `~/Orb/src/`** — sub-agent 没 Orb 铁律感知，会直接改；L2 codex 才能改
- ❌ **禁止 L1 + L2 嵌套**（sub-agent 再派 codex）— 失控
- ❌ **禁止裸跑 codex exec / claude -p**（除少数例外）— 没自动回报，会重蹈「好了吗？」覆辙
- ❌ **禁止把"理解"外包** — Orb 自己必须看 diff、读回报、做判断，不写 "agent 说 OK 就 OK"
- ❌ **禁止 spec 用 "根据你的判断" / "看情况办"** — 外部 codex 没 context，要具体到文件行号
- ❌ **禁止长程 audit / 多模块治理在主 worker 跑** — 必走 L2 codex 化（见上节），主 worker 30min timeout 必死
- ❌ **禁止未声明理由选 CC** — L2 默认 Codex；切 CC 必须输出 `🔀 CC 理由：xxx`，无理由 = 流程违规
## 与 `subagent-driven-development` 的关系
全局 skill `subagent-driven-development` 是通用 plan→dispatch→review 流水线（superpowers 版）。本 skill 补 Orb 特化层：**何时用 L1 vs L2 + Orb 禁改自身源码的铁律 + launcher 自动回报姿势**。执行大 plan 时两个 skill 叠用——本 skill 先定位「这步该 L1 还是 L2」，大 plan 迭代时套 `subagent-driven-development` 的 batch + review 模式。
