Documentation
From README.md · b46c48d · Built 2026-11-17
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.
Step plan exit codes: 0 valid, 2 error, 3 no matching card recipe (a schema is printed
so Claude can write the steps). Validation checks the required fields, known
kinds, unique IDs, known dependencies, cycles, absolute write paths, and
write-path overlap, including parent/child paths, symlink aliases, and existing
paths that refer to the same file. Each part of a resolved path is normalized
to Unicode NFC and case-folded, so paths differing only by Unicode normalization
or letter case are conservatively rejected even when they do not yet exist or
the filesystem treats them as distinct.
Overlapping writes are rejected even between dependent steps. Combine those
writes into one step. Empty paths declares no writes.
Recipes save to $DECOMPOSE_RECIPES or ~/.claude/decompose/recipes.json,
creating directories as needed. User recipes override bundled recipes by name;
tools_by_kind and scopes merge by kind. Saved names must be new. Saved
steps retain their literal inputs and paths. The helper never writes recipes
inside the plugin directory, including case variants and directory aliases.
Concurrent saves hold an exclusive lock beside the recipe store across reading,
checking names, merging, and atomic replacement. On systems without fcntl, an
exclusive lock file retries for up to 10 seconds, then reports an error. A stale
lock file left by an interrupted save on those systems must be removed before
saving again.
Step kinds
| Kind | Purpose |
|---|---|
frame | Plan changes by file. |
code | Make scoped changes. |
test-run | Run the specified checks. |
audit-needed | Decide whether an audit is needed. |
ship | Prepare an authorized release operation. |
reproduce | Reproduce an issue. |
search | Find evidence. |
fetch | Retrieve sources. |
extract | Extract information. |
synthesize | Combine evidence. |
read | Read supplied material. |
audit | Review supplied material. |
Only code and ship are write kinds. Their paths must be absolute and
disjoint across steps. Tool names describe required capabilities, not installed
integrations. Bundled search and fetch steps request web.