# Workflow Ledger > Save and recall runs of the capital-W `Workflow` orchestration tool (and notable `Agent` fan-outs) across sessions and projects. NOT for colloquial "workflows", CI pipelines, or git flow. Invoke AFTER a substantial Workflow/fan-out to record what worked — structure, agentType, model, concurrency, gotchas — so future sessions reuse proven recipes instead of re-deriving them. Invoke BEFORE designing a new Workflow to check the ledger for a proven one. Triggers on "save this workflow", "check the workflow ledger", "reuse a proven workflow", "fan out N agents", "multi-agent orchestration", "have we run a workflow like this". - Skill: `oimiragieo/workflow-ledger` (Agent Skill) - Install (CLI): `npx skillmds@latest add oimiragieo/workflow-ledger` - Raw SKILL.md: https://api.skillmd.com/api/skills/oimiragieo/workflow-ledger/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: oimiragieo (https://skillmd.com/u/oimiragieo) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/oimiragieo/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 ``` ### · · - **Purpose:** - **Structure:** parallel | pipeline | chunked(N) · <#agents> · <#sequential groups | concurrency> - **Config:** agentType= · model= · output= - **Skills/agents/tools used:** <...> - **Outcome:** (figures are as-of the date above; they drift) - **Gotchas + fixes:** - **Failed configs (don't repeat):** - **Reusable script:** ``` ## 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//.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).