task-graph-orchestration-skill

In the historical v1.3.0 benchmark, on a bulk import that silently loses rows, agents without the skill gave wrong counts in their final report in 15 of 20 runs; with it, in 0 of 20 (Haiku 5.5, DeepSeek V4.1 Flash). It does not make agents stronger at tasks they already do right, and it costs ×1.3–1.6. Benchmark ↓

One drop-in skill for Claude Code, Codex and OpenCode that changes how an agent runs anything bigger than a one-liner:

• Proof, not prose. A worker saying “tests pass” is a claim. Open the CI run, file or receipt; distinguish checked facts, reports with an artifact reference, and unsupported claims. Omit empty groups.
• Numbers from a command, not by eye. Every verified count in the final report is printed by a command that counts exactly that thing; quoted counts remain attributed until checked; counting lines of output by eye is how reports go wrong.
• Look at what people will see. Before “done”, open the result the way a person will — each language, role and state that changed — or check what it renders from. Otherwise the headline says “done except X”.
• Read the live system before touching it. Before an email, payment, deploy or deletion: read the record of what already happened, do only the remainder, re-read. Change a running system only through the path it actually runs on, and never leave test records in it.
• No blind retries. Two identical failures in a row trigger SSoT: stop, name the assumption every attempt shared, change the cause — or escalate.
• A second look at the moments that matter. SSoT also fires before committing to a root cause or approach, before the first command that changes something outside the working directory, and before the final answer.
• Delegate only when it pays. Subagents only for independent units with heavy reading or long runtimes; a minimal brief (paths, not contents) and a return of about 15 lines. Their answer is a claim too.
• Small stays small. A rename stays a rename: no plans, no ceremony.

Install

Paste into your agent (Claude Code, Codex, OpenCode):

Install the agent skill from https://github.com/Lexus2016/task-graph-orchestration-skill —
run its install.sh, show me the INSTALLED line, and tell me to restart you.

One line in a terminal:

curl -fsSL https://raw.githubusercontent.com/Lexus2016/task-graph-orchestration-skill/main/install.sh | bash

Claude Code plugin:

/plugin marketplace add Lexus2016/task-graph-orchestration-skill
/plugin install task-graph-orchestration@task-graph-orchestration

The installer copies skills/task-graph-orchestration/ into every agent skills folder it finds — ~/.claude/skills, ~/.agents/skills (Codex, Gemini CLI, Copilot CLI), ~/.config/opencode/skills — and nothing else. Restart the agent afterwards.

Benchmark

Measured on 2026-11-05/06 with Claude Code 2.1.318 (Haiku 5.5) and OpenCode 2.1.2 (DeepSeek V4.1 Flash). Every run starts in a fresh directory with clean settings: no user CLAUDE.md / AGENTS.md, no MCP servers, no other skills.

Method. Each task runs against a small local mock service (or plain files) that records what the agent really did. Outcomes are checked by code from that record; a blind judge (Sonnet 5.5, arm hidden, skill mentions redacted) only checks that the agent's final report matches the record, with the ground-truth numbers supplied. Arms: no skill · v1.2.0 · v1.3.0, with the skill installed and the prompt asking for it. v1.4.0 was checked against v1.3.0 separately (below).

What it costs, versus no skill, averaged over the three mock-service tasks: Haiku — tokens ×1.25, bill ×1.30, time ×1.23; DeepSeek — tokens ×1.83, bill ×1.61, time ×1.38.

What this says. The measurable gain is in the report. Agents without the skill got a count wrong in 15 of 20 import runs (mostly the comma-decimal prices: 6, 8, 9, 11, 13 or 14 where the truth was 7) because they counted printed lines by eye. v1.3.0 asks for every number to be printed by a command that counts exactly that, and it was right in all 20. Where agents already behave — the service ended in a correct state in every run of every arm — the skill adds cost and nothing else.

Correction. Earlier versions of this README claimed "+6 to +13 percentage points" on discipline tasks. That figure came from a grader that checked whether the answer contained an SSoT line, which only the skill can produce. Graded on outcomes alone, those tasks were solved equally with and without the skill. The claim is withdrawn.

Caveats: 5–10 runs per cell and two models (Haiku 5.5, DeepSeek V4.1 Flash); the judge shares a model family with one of them. The v1.3.0 counting rule was written after the import task exposed the problem, so that row is not independent evidence; the refund task was chosen independently and points the same way, but 5 runs are not significant on their own (p = 0.44 against no skill). Two failures of the plain agent seen in a 3-run pilot — a duplicated charge and a stray test record in a live service — did not recur in the 150+ runs that followed. The test cases, mock services and judge are not published in this repository.

v1.4.0 (historical). Four rules come from a real deploy session in which an agent reviewed a teammate's branch, called it clean and released it — after which every language except English showed message ids instead of text: open what a person will see; read how a running system is actually run before changing it; give a request that arrives mid-work its own criteria; pause (SSoT) before the first command that changes something outside the working directory. Small tasks did not reproduce that failure — without the skill, 20 of 20 runs translated every language — so these rules are checked for harm only, not for benefit:

v1.5.0 (current). Makes the SSoT pause explicit in working messages, includes failures reported by the user in loop detection, distinguishes checked facts from referenced and unsupported claims, and fixes stale references to removed modes. Small local edits skip the whole protocol, including the final pause; evidence groups need no empty headings. Existing user authorization is preserved.

On 2026-11-10, the pre-release candidate completed 60 Haiku 5.5 runs (six tasks × forced/automatic discovery × five repeats). Rechecking saved files and mock-service records found all 40 candidate runs in the four tasks with executable outcome checks correct, as were all 40 comparable v1.4.0 runs. This checks file/service state, not final-report accuracy. In the repeated-failure task, valid SSoT lines rose from 0/5 to 5/5 when forced and from 0/5 to 4/5 with automatic discovery. These are protocol-compliance counts, not evidence of better task results.

The candidate also emitted unnecessary SSoT in 4/5 forced simple-rename runs. The final text strengthens the small-task exit and removes mandatory report grouping. The automated judge returned no candidate scores after the account limit was reached; the final wording therefore has no completed comparative quality or speed evaluation. Historical benchmark results above belong to their named versions, not to v1.5.0.

What the skill makes the agent do

The benchmark measures the counting row directly, and the crash row is the refund task. The UI and live-system rows come from a real deploy session and are checked only for harm; the loop row is a rule the benchmark could not separate from what agents already do.

How it works

SKILL.md has six sections and an explicit exit for small local tasks, even when the skill was loaded on request. Detailed state and runtime guidance stays in the references.

SSoT in one minute

The agent writes 10 fresh letters and digits, picks one by a digit-sum rule, and the position sets the angle it must look from:

SSoT: Rb7xQ2mT4z (digit-sum 13, pos 3): x.   angle = 3 mod 5 = reviewer
Re-look: both attempts edited key names, assuming svc-017 uses the default loader.
It uses a custom loader. New unit `loader-shim`; no third retry of the same cause.

Angles: 0 user · 1 spec · 2 edge case · 3 reviewer · 4 next agent. If the angle repeats the previous one in the same task, the agent takes the next. For non-trivial work it fires on a loop, before a commitment the rest of the work depends on, before marking done a unit no check covers, before the first command of a batch that changes something outside the working directory, before the final answer, and when you write “SSoT”. Write the line in the working message immediately before the guarded action; keep it out of the final deliverable. Small local tasks skip it unless standing user instructions require it.

The characters only create the pause; the re-look does the work. Historical limit: in the v1.3.0/v1.4.0 comparison, an SSoT line appeared in only two of 80 runs that loaded the skill on request. v1.5.0 makes the working-message requirement explicit; the candidate results above measure compliance, not task quality.

Long, resumable or recurring work

When work must survive the session — overnight runs, multi-session batches, recurring jobs — the skill points to scripts/tgo.py, a small state machine on disk (plan, start, done with a check, failure ledger, final), and references/full-mode.md for checkpoints, resume and monitoring. An optional graph-trace viewer (scripts/trace_graph.py, assets/trace-viewer.html, references/trace.md) renders a recorded run as an animated graph; the core skill does not turn it on.

Auto-update

The agent never updates itself mid-task. Updates arrive from outside its work:

• install.sh schedules a daily background check — launchd on macOS, cron on Linux.
• The Claude Code plugin checks once per session (SessionStart hook).
• Manually: bash ~/.claude/skills/task-graph-orchestration/scripts/update.sh update.

The check compares VERSION with this repository, downloads the tagged release, validates its name and version, and swaps every local copy atomically. Offline it does nothing. Turn it off with bash <skill>/scripts/update.sh unschedule, or install with TGO_AUTO_UPDATE=0.

Works with

Repository layout

skills/task-graph-orchestration/   the skill: SKILL.md, references/, scripts/ (update.sh, tgo.py, trace_graph.py), assets/trace-viewer.html (optional), VERSION
tests/                             unit tests for the helper scripts
.claude-plugin/ · hooks/           Claude Code plugin + marketplace manifests · SessionStart update hook
install.sh · PROMPT.md             one-line install · paste-into-agent install

About the benchmark

The test cases, mock services and the blind judge are kept outside this repository; it ships only the skill and these READMEs. The Benchmark section above describes the method, the results, the cost and the limits.