orchestrate-code-task

🎼 orchestrate-code-task

A Claude Code skill that runs code-changing tasks like a disciplined engineering team — reviewed plans, controlled multi-agent edits, and evidence-backed verification.

一个 Claude Code 技能：像一支训练有素的工程团队那样处理"改代码"的任务 —— 计划经独立审查、多代理受控实现、交付有证据支撑。

English · 中文

---

English

Why this exists

LLM coding agents are great at writing code and bad at knowing when they're done. Left unchecked they:

• declare success without ever running the code,
• "review" their own work in a way that only rubber-stamps it (review theater),
• quietly reformat or clean up files you never asked them to touch,
• thrash on the same bug with two cosmetic re-edits and call it progress,
• and treat your uncommitted changes as part of their own diff.

On low-risk edits that's annoying. On auth, migrations, billing, concurrency, or compatibility changes, that's how silent breakage ships.

orchestrate-code-task wraps every code-changing task in a process that is hard to fake:

• plans are reviewed by an agent that is never told the expected answer,
• writes are handed out as scoped, revocable grants — not permanent ownership,
• and nothing is called done without verification output you can actually read.

Features

• 🎯 Intent-gated — Engages only when a task actually changes code. Pure Q&A, diagnosis-only, status checks, and bare commit/push/deploy stay out of scope.
• 🪜 Proportional rigor — A trivial one-file edit takes a fast track; a risky migration gets parallel review and full verification. Process strength scales to risk, never the reverse.
• 🔍 Independent review, not review theater — Reviewers never receive the main agent's expected conclusion. Review independence may degrade under constraints, but review and tests themselves are never skipped.
• 🤝 Safe multi-agent edits — Two-phase write authorization, explicit ownership records, and stop-the-line the moment two agents' scopes collide on a file, symbol, or shared interface.
• 🧪 Evidence-backed delivery — No "success" without real command output. High-risk work must clear a per-risk external-signal matrix (A = machine-verifiable: tests, build, type-check, lint, dry-run; B = external artifacts: docs, schema/API, call-site search).
• 🛡️ Protects your uncommitted work — A concrete forbidden-command list (git reset --hard, git clean, git checkout --, force overwrites…) plus a read-only start snapshot that isolates the task's diff from your in-progress changes — tracked and untracked.
• 🔁 Anti-patch-loop — After two genuinely different fixes fail on the same issue, it stops thrashing, re-diagnoses the root cause, and reports instead of faking progress.
• 📋 Structured final report — Every task ends with a fixed skeleton: what shipped, agent split & review method, verification evidence, and remaining risks.

How it works

flowchart TD
    A[User request] --> B{Needs code changes?}
    B -->|No| Z[Out of scope: analyze / diagnose only]
    B -->|Yes| C[Classify task level<br/>light · standard · complex · high-risk]
    C --> D[Recon + start snapshot<br/>dynamic TODO + ownership]
    D --> E[Independent plan review<br/>reviewer never sees the expected answer]
    E --> F[Controlled implementation<br/>two-phase, revocable write grants]
    F --> G[Main-agent base verification<br/>diff · lint · types/build · targeted tests]
    G --> H[Independent result verification<br/>+ external signals for high-risk]
    H --> I{Pass?}
    I -->|No| F
    I -->|Yes| J[Delivery checklist → final report]

Task levels at a glance

Level	Investigation	Plan review	Result verification	Writes
Light (fast track)	Main agent	Main-agent isolated self-review	Self-review + targeted checks	Direct
Standard	Main agent (+1 helper if needed)	1 independent subagent	Base + 1 new independent subagent	Direct or single-writer
Complex	Parallel read-only subagents	2 parallel reviewers, different angles	Base + parallel verifiers	Parallel writers, full two-phase grants
High-risk	Parallel subagents + official docs / real call-sites	2 reviewers, ≥1 on security/compat	Base + new subagent + per-risk external-signal matrix	Serial single-owner, no parallel writes

The initial level is provisional and continuously recalibrated — any new risk signal escalates it, and you can't downgrade to dodge a check you already owe.

Install

Agent Skills load from your Claude Code skills directory. Pick one scope:

# Personal — available in every project
git clone https://github.com/MillenClaassen/orchestrate-code-task \
  ~/.claude/skills/orchestrate-code-task

# Or per-project — checked in with your repo
git clone https://github.com/MillenClaassen/orchestrate-code-task \
  .claude/skills/orchestrate-code-task

That's it — Claude Code discovers SKILL.md automatically.

Use

You don't call it manually. When your request implies a code change, Claude Code recognizes the trigger and runs the flow. You can also nudge it explicitly:

Add rate limiting to the /login endpoint and cover it with tests.

Use orchestrate-code-task to refactor the payment retry logic.

It works the same regardless of the language you prompt in.

What it will not do

• Start editing code you haven't authorized — it will analyze or diagnose only.
• Commit, push, deploy, or publish without explicit approval.
• Discard, overwrite, or stash your uncommitted changes.
• Silently expand the agreed scope, non-goals, or acceptance criteria.
• Claim success without verification evidence, or hide a failing test.

Design principles

• You can degrade the reviewer's independence — never the review. Self-review is allowed in exactly two labeled cases (a truly trivial fast-track task, or no subagent is available); both must be disclosed.
• The execution contract is sacred. Result, scope, non-goals, and acceptance criteria are treated as a contract; changing them requires asking you.
• Ask only after clearing three gates — not self-answerable from the repo, materially changes the implementation, and no safe reversible default. Otherwise decide, record the assumption, and disclose it.
• Complements your repo instructions. CLAUDE.md defines what good output looks like; this skill defines when and how that standard is enforced.

Repo layout

orchestrate-code-task/
├── SKILL.md                      # Entry: trigger boundary, mandatory flow, core rules, report skeleton
└── reference/
    ├── task-levels.md            # Classification, level-control matrix, lightweight fast track
    ├── recon-and-todo.md         # Workspace recon, start snapshot, dynamic TODO & ownership
    ├── subagents-and-writes.md   # Subagent dispatch, two-phase write auth, write-isolation tiers
    ├── review-and-verify.md      # Plan review, A/B external-signal verification, fix loop
    └── delivery.md               # Delivery checklist & report requirements

Reference files are loaded on demand, step by step — not all at once — so the skill stays cheap to run.

Contributing

Issues and PRs are welcome — sharpen the checklists, add task patterns, or improve the docs. If this saved you from a rubber-stamped merge, give it a ⭐ — it genuinely helps others find it.

License

MIT.

---

中文

为什么需要它

LLM 编码代理很擅长写代码，却很不擅长判断自己什么时候真正做完了。放任不管时，它会：

• 代码一行没跑就宣布成功；
• 用一种只会给自己盖章的方式"审查"自己的工作（审核表演）；
• 悄悄格式化、顺手清理你根本没让它碰的文件；
• 对同一个 bug 做两次换汤不换药的修改，就当作在推进；
• 把你自己尚未提交的改动算进它的成果 diff 里。

在低风险改动上，这只是烦人。但在权限、认证、数据迁移、计费、并发、兼容性这类改动上，这正是"静默故障"上线的方式。

orchestrate-code-task 给每一个"改代码"的任务套上一层难以糊弄的流程：

• 计划由一个从不被告知预期答案的代理来审核；
• 写入权限以限定范围、可随时撤销的方式发放 —— 而不是永久所有权；
• 在拿出你能亲自读到的验证输出之前，绝不宣称"完成"。

核心特性

• 🎯 意图门控 —— 只有任务真正要改代码时才介入。纯问答、只诊断、状态查询、单纯的提交/推送/部署都在范围之外。
• 🪜 强度与风险相称 —— 琐碎的单文件改动走快速通道；高风险迁移则并行审核 + 完整验证。流程强度随风险伸缩，绝不反过来。
• 🔍 独立审核，而非审核表演 —— 审核者从不接收主代理的预期结论。审核的独立性可能因环境受限而降级，但审核和测试本身永不跳过。
• 🤝 安全的多代理协作 —— 两阶段写入授权、显式所有权记录，一旦两个代理在同一文件/符号/共享接口上发生范围重叠，立即停线。
• 🧪 交付有证据支撑 —— 没有真实命令输出就不算"成功"。高风险任务必须通过按风险类型定制的外部信号组合（A = 机器可验证：测试、构建、类型检查、lint、dry-run；B = 外部权威工件：官方文档、schema/API、调用点搜索）。
• 🛡️ 保护你未提交的工作 —— 一份明确的禁止命令清单（git reset --hard、git clean、git checkout --、强制覆盖……），外加一次只读起点快照，把本任务的 diff 与你在途的改动干净剥离 —— 已跟踪与未跟踪文件都覆盖。
• 🔁 反打补丁循环 —— 同一问题在两次实质不同的修复后仍失败，就停止空转，重新诊断根因并如实上报，而不是假装还在推进。
• 📋 结构化最终报告 —— 每个任务都以固定骨架收尾：交付了什么、代理分工与审核方式、验证证据、剩余风险。

工作流程

flowchart TD
    A[用户请求] --> B{需要改代码吗?}
    B -->|否| Z[范围之外: 只分析 / 诊断]
    B -->|是| C[判定任务等级<br/>轻量 · 标准 · 复杂 · 高风险]
    C --> D[工作区检查 + 起点快照<br/>动态 TODO + 所有权]
    D --> E[独立方案审核<br/>审核者不知道预期答案]
    E --> F[受控实现<br/>两阶段、可撤销的写入授权]
    F --> G[主代理基础验证<br/>diff · lint · 类型/构建 · 定向测试]
    G --> H[独立结果验证<br/>高风险追加外部信号]
    H --> I{通过?}
    I -->|否| F
    I -->|是| J[交付清单 → 最终报告]

任务等级一览

等级	调查	方案审核	结果验证	写入方式
轻量（快速通道）	主代理	主代理隔离式自审	自审 + 定向检查	主代理直接
标准	主代理（必要时 +1 辅助）	1 个独立子代理	基础 + 1 个新独立子代理	直接或单写入者
复杂	并行只读子代理	2 个并行审核，不同角度	基础 + 并行验证代理	并行写入，走完整两阶段授权
高风险	并行子代理 + 官方文档/真实调用点	2 个审核，≥1 个从安全/兼容角度	基础 + 新子代理 + 按风险类型的外部信号组合	串行单所有者，不并行写入

初始等级只是暂定，会被持续校准 —— 任何新的风险信号都会触发升级，而且不允许通过降级来规避你已经欠下的检查。

安装

Agent Skills 会从 Claude Code 的技能目录加载。选一种作用域：

# 个人级 —— 在所有项目中可用
git clone https://github.com/MillenClaassen/orchestrate-code-task \
  ~/.claude/skills/orchestrate-code-task

# 或项目级 —— 随仓库一起提交
git clone https://github.com/MillenClaassen/orchestrate-code-task \
  .claude/skills/orchestrate-code-task

就这样 —— Claude Code 会自动发现 SKILL.md。

使用

你不需要手动调用它。当你的请求意味着要改代码时，Claude Code 会识别触发条件并运行整套流程。你也可以显式点名：

给 /login 接口加上限流，并补上测试。

用 orchestrate-code-task 重构支付重试逻辑。

无论你用哪种语言提问，效果都一样。

它不会做的事

• 在你没有授权时就开始改代码 —— 它只会做分析或诊断。
• 未经明确同意就提交、推送、部署或发布。
• 丢弃、覆盖或 stash 你未提交的改动。
• 悄悄扩大已约定的范围、非目标或验收标准。
• 没有验证证据就宣称成功，或隐藏失败的测试。

设计原则

• 可以降级的只有审核者的独立性，永远不是审核本身。 自审只在两种被明确标注的情形下允许（真正琐碎的快速通道任务，或确实没有子代理可用），且都必须披露。
• 执行契约不可侵犯。 结果、范围、非目标、验收标准被视为契约；需要改动时必须先问你。
• 提问要连过三关 —— 仓库里查不到答案、不同答案会实质改变实现、没有安全可逆的默认值。否则自行决定、记为假设、并在报告中披露。
• 与仓库指令分工互补。 CLAUDE.md 定义好的产出长什么样；本 skill 定义在何时、以何种清单去强制执行这个标准。

目录结构

orchestrate-code-task/
├── SKILL.md                      # 入口: 触发边界、强制主流程、核心规则、报告骨架
└── reference/
    ├── task-levels.md            # 任务分级、等级控制矩阵、轻量快速通道
    ├── recon-and-todo.md         # 工作区检查、起点快照、动态 TODO 与所有权
    ├── subagents-and-writes.md   # 子代理调度、两阶段写入授权、写入隔离分级
    ├── review-and-verify.md      # 方案审核、A/B 外部信号验证、修复闭环
    └── delivery.md               # 交付清单与报告要求

细则文件按步骤按需加载，不会一次性全部读入，因此运行开销很低。

参与贡献

欢迎提 Issue 和 PR —— 打磨清单、补充任务模式，或改进文档。如果它帮你挡下了一次被盖章放行的合并，给个 ⭐ 吧 —— 这能实实在在帮到更多人。

许可证

MIT。