Documentation
From README.md · b46c48d · Built 2026-11-17
- Split the ask into numbered clauses and tag every unit with the clauses it serves. A clause with no unit is flagged.
- Break the job into the smallest units, each with its own inputs, outputs and verifier. N similar items become N units.
- Give each unit one of 14 types (coding, reasoning, research, writing, four creative types, design, vision, review, data, agentic, cyber) and one of 3 speeds (fast, standard, frontier).
- Draw only real data edges: a unit depends on another only when it reads that unit's output. False and missing edges are rejected. Checks that can kill the plan run first.
- Build parallel waves, count how many units read each output, and raise importance with that count.
- Choose a dispatch shape per group: one call per unit, an agent's own subagents, a bulk prompt fan-out, an agent fan-out, or split worktrees for disjoint writes. The thresholds are tunable defaults.
- Send big or serial maps to an advisor review before any picks, and apply its patch (split, cut edges, re-tier, change the shape or the needs) all or nothing.
- Pick a model and a machine per unit with a written method: type first, then speed, family spread within a wave, context as a scored key, effort set apart from tier, and the smallest machine that fits.
- Print one plan table with the waves, the critical path and clause coverage.
Unit map example
From the root of this repository:
python3 skills/decompose/scripts/decompose.py --plan skills/decompose/examples/plan.json
The bundled map compares three CSV libraries on speed and license, then recommends one. Actual output, exit 0 (table trimmed to four rows):
PLAN valid
Advisor review: REQUIRED before picks (S1 read by 3 units)
| unit | parent | clause | type x speed | wave | group | shape | model | machine | runner-up |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| S1 (invalidator) | - | C1 | data x fast | 0 | W0 | single | - | - | - |
| S3.1 | S3 | C2 | research x fast | 0 | W0 | single | - | - | - |
| S2.1 | S2 | C1 | coding x standard | 1 | W1 | single | - | - | - |
| S4 | - | C3 | writing x standard | 2 | - | single | - | - | - |
Waves:
W0: S1, S3.1, S3.2, S3.3
W1: S2.1, S2.2, S2.3
W2: S4
Critical path (minutes): S1 -> S2.3 -> S4, length 11
Serial estimate: 29 minutes. Both figures come from the units' own needs.minutes.
Clause coverage:
C1 (compare on speed): S1, S2.1, S2.2, S2.3
C2 (compare on license): S3.1, S3.2, S3.3
C3 (recommend one): S4
The advisor gate fired because S1 is read by three units. The bundled patch.json is a sample review: it splits S4 into a draft and a citation check. Apply it with --apply-patch skills/decompose/examples/patch.json. Add --json for machine-readable output. The model, machine and runner-up columns stay empty until you pick them by the method in references/picking.md.
Unit map exit codes: 0 valid, 2 every error listed, including unknown types or speeds, clause gaps, false or missing edges, cycles, substeps more than one level deep, and overlapping writes between units that could run at the same time. Dispatch and gate thresholds live under plan_defaults in the bundled recipes.json; override any of them in your own recipe store.
The full method
The skill file holds every step the agent follows, with the dispatch table and the plan schema.
Read the full method in SKILL.md
Model and machine picks
The helper never picks or calls a model or a machine. Picking is a written method for the agent.
Current recipe defaults
{
"advisor_max_steps": 5,
"advisor_min_units": 12,
"advisor_serial_min_steps": 4,
"advisor_serial_ratio": 0.75,
"advisor_min_readers": 3,
"high_importance_readers": 3,
"agent_fanout_min": 10,
"bulk_prompt_min": 2,
"subagents_min": 4
}