Workflow Ledger

workflow-ledger

A persistent, cross-session, cross-project record of multi-agent orchestrations run via the Workflow tool (and notable Agent-fan-out patterns). The point: stop re-deriving workflow structure + config every session. Past runs — especially their failure modes — are captured so the next session reuses the proven recipe and skips the dead ends.

Scope boundary (read first). Workflow is for file-grounded fan-out — audit / fix / migration / research sweeps, and same-model judge panels over code/artifacts. For cross-MODEL perspective breadth (strategic forks, design review, ScholarEval — different providers' takes), use a cross-model peer-review council, not Workflow. Both can run "judge panels"; the difference is file-grounded-same-model (Workflow) vs perspective-diverse-cross-model (council).

The ledger

• File: ~/.claude/skills/workflow-ledger/LEDGER.md (global — all projects). Newest entry first (prepend), above the existing ### blocks and below the intro. "Append-only" here means never mutate or delete a past entry's lessons — only add new ones or bump a date.
• The Workflow tool already persists each run's script under the session dir and prints the path. The ledger links that script path so a proven workflow can be re-run via Workflow({scriptPath: "..."}) (+ resumeFromRunId to resume — same-session, stop the prior run first; verify constraints against current tool docs).

When to CONSULT (before designing a workflow)

Before authoring a new Workflow script, Grep LEDGER.md by task-class (audit / fix / migration / research / review) and read only the matching blocks + the distilled "Quick recipes" — don't ingest the whole file once it has many entries. If a match exists, copy its structure + config (agentType, model, concurrency, output mode) and pre-apply the gotchas it already solved. That reuse IS the optimization the ledger exists for.

CONSULT is model-self-triggered — nothing enforces it. If you're about to call Workflow, treat "Grep the ledger first" as step 0. (A PreToolUse hook on the Workflow tool could enforce it.)

When to SAVE (after running a workflow)

Save when a run produced something worth reusing: a new gotcha + fix, a materially new structure/config, or a reusable recipe (success or instructive failure — failures are the highest-value entries).

• Dedup first: Grep for an existing entry with the same project + pattern. If the run only re-confirms a proven recipe with no new lesson, bump that entry's date instead of appending a near-duplicate.
• Keep it tight; one block per run.

Entry format

### <YYYY-MM-DD> · <project> · <workflow-name>
- **Purpose:** <one line>
- **Structure:** parallel | pipeline | chunked(N) · <#agents> · <#sequential groups | concurrency>
- **Config:** agentType=<general-purpose|Explore|...> · model=<inherit|sonnet|opus> · output=<text|file|schema>
- **Skills/agents/tools used:** <...>
- **Outcome:** <success/findings · ~token cost · wall time>  (figures are as-of the date above; they drift)
- **Gotchas + fixes:** <THE most valuable field — failure modes hit + how solved>
- **Failed configs (don't repeat):** <optional — the exact config that returned 0 tokens / failed, so it's Grep-able>
- **Reusable script:** <path the Workflow tool printed, if worth re-running>

Hard-won workflow rules (read before any Workflow dispatch)

The empirical rules below were observed 2026-05-29 on a standard rate tier — re-verify limits against the current tool/account; the ~3 and ~6–12 numbers are mitigations, not tool constants.

1. agentType matters. OBSERVED: dispatching with no agentType on a file-reading task returned subagent_tokens: 0 and no output — the default workflow subagent appears to lack Read/Grep. For anything that reads/edits files, set agentType: 'general-purpose'. (Mechanism not confirmed in docs; if you see 0 tokens, also rule out the rate limit.)
2. Throttle — and know WHICH limit you're hitting. Two different ceilings: (a) the per-workflow concurrency cap min(16, cpu cores - 2) — excess agent() calls QUEUE and run as slots free, they do NOT fail; (b) the account-level Anthropic API rate limit — many heavy agents firing at once can return 0-token failures fast. We hit (b) on 2026-05-29 launching 12-at-once (which was UNDER cap (a), proving the failure was (b)). Mitigate (b) by spacing launches: chunk into sequential groups of 3 — for (i+=3) { await parallel(group) } — or use pipeline() so later items start as slots free. There is no sleep primitive; the sequential await IS the spacer. `3` mitigates (b), not (a), and is account-specific.
3. Check subagent_tokens in the result. 0 means the agents never actually ran — regardless of a "completed" status. Re-dispatch with the fix; don't trust the summaries. (Tool-agnostic — survives version changes.)
4. READ-only audits are safe + high-value. WRITE (fix) workflows are HIGH regression risk — parallel subagents reliably introduce type errors. ALWAYS run a full check-types/pytest + diff-review yourself after a fix workflow; the subagents' "tsc 0 errors / I fixed it" claims are NOT trustworthy (they often check only their own file). For parallel writes, either scope each subagent to ONE file (no shared files) and have them FLAG — not edit — shared/backend files, OR run under isolation: 'worktree' (each agent gets its own git worktree → no collisions + a clean per-agent diff). Commit/stash a checkpoint before a WRITE fan-out so a regression-heavy result is discardable instead of hand-repaired.
5. Browser/aura/figma can't fan out. They share one Chrome/MCP session and collide across parallel subagents. Keep live-browser audits + aura/figma cloning orchestrator-serial. (Also: give each subagent a slug/item-keyed output filename — never a shared next-available-number scheme; parallel agents race and overwrite each other's files when they all compute "next available number" independently.)
6. Output mode. For LARGE fan-outs, prefer text return or per-agent file-write (each agent writes docs/audits/<dir>/<item>.md + returns a one-line summary) — keeps the workflow result small and persists full reports. NOTE: the schema (StructuredOutput) path is NOT itself a 0-token cause — it has built-in retry; a 10-agent schema review ran clean at ~508K tokens (2026-05-29). The original v1 0-token failure was default-agent + rate limit, never isolated from the schema.
7. Stay in the loop between phases. Run several smaller workflows in sequence and read each result before the next — especially for write phases. (This is about human-in-the-loop phasing, NOT about avoiding the pipeline() primitive: pipeline() = no barrier between stages, the recommended default; parallel() = a barrier that waits for all results — use it only when you genuinely need every result at once.)

Native primitives worth knowing (detail → tool docs)

pipeline() (no-barrier, default) vs parallel() (barrier) · isolation: 'worktree' (parallel writes) · budget (token-target scaling) · log()/phase() (progress) · workflow() (one-level nesting) · resumeFromRunId (same-session resume; stop the prior run first) · lifetime cap = 1000 agent() calls.

Cross-references

• Authoritative source for the rules above = this skill. This skill generalizes the original project-scoped receipt; make edits HERE, not in any project-local note.
• The parallel-write filename-collision footgun behind rule 5 — a shared next-available-number scheme races across concurrent writers.
• The Workflow tool documentation — primitive semantics + quality patterns (adversarial verify, loop-until-dry, judge panels), isolation: 'worktree', resumeFromRunId.
• A cross-model peer-review council skill, if this project has one — for cross-MODEL perspective panels (see the scope boundary at the top).