Delegating Work to Background Sub-Agents

Joseph's standing expectation for medium-to-heavy tasks: write a task brief, then delegate

to background sub-agents so the session does not stall on serial reconnaissance + inline

work. A task that takes many minutes of tool round-trips is a task that should run in a

sub-agent while the orchestrator stays free.

When to delegate

Reach for this pattern when a task has any of:

Fresh ground truth needed (research a real directory tree, a live system, current

config) that would otherwise take several serial find/ls/head calls.

A large draft / document / digest to produce from a known brief.
Independent parallel workstreams (batch mode, up to 3 concurrent).
Context flooding — the intermediate data (many files, logs, pages) would swamp the

orchestrator; a sub-agent reduces it to a summary.

Do NOT delegate: a single tool call, a task needing live user interaction, or mechanical

steps better done with execute_code.

The pattern (Joseph's preferred workflow)

1. Write a task.md first. A self-contained brief that captures: the task, the goal,

the required output, the constraints, key references (file paths, skill names), a

delegation plan, and any ground-truth facts already gathered. Place it with the work

or in produce/hermes/plans/. This lets any future run (or a fresh session) resume

without re-deriving context. Also: Joseph reviews plans before execution.

2. Do the research ONCE, batched. Pull all ground truth in one parallel call set

(parallel search_files/find), not one directory at a time. Real facts beat

remembered ones — a blog rewrite needs the actual directory tree, not a guess.

3. Dispatch to a background sub-agent. A sub-agent knows NOTHING of this conversation.

Bundle everything it needs into the context: the required output verbatim, the full

rule set / constraints, and the exact ground-truth map. Keep it background, then keep

working — do not poll or wait inline.

4. Verify on return — do not trust the self-report. A sub-agent's summary is a

self-report, not verified facts. Check the output against the brief and the governing

skill, run the checks (e.g. Flesch for writing, exists() for file writes), and patch

before declaring success. Never save the sub-agent's output unverified.

Writing a good brief (context)

State the output format explicitly ("return the complete markdown; do not write files").
Enumerate the constraints, not just the goal. If a skill governs the output, embed its

rules or point to its file path.

Provide exact nouns: real directory names, real numbers, the verbatim opening line.
Tell it what NOT to do (no "you", no em-dashes, no invented facts).

Parallel chapter writing

When writing multiple chapters for a book, delegate each chapter to its own sub-agent in parallel. Each sub-agent gets:

Source material (file paths to read)
Voice guidelines (embedded in context, not as a loaded skill)
Structure requirements (section order, word count targets)
Output path (the markdown file to write)

Example batch of 6 chapters:

delegate_task(tasks=[
  {goal: "Write Ch 1: WINS Framework", context: "...", role: "leaf"},
  {goal: "Write Ch 2: Why Hermes", context: "...", role: "leaf"},
  ...
])

Assembly after all complete: cat 00-intro.md 01-chapter.md ... > full-book.md

Pitfall: delegation pool capacity limits concurrency. If max_concurrent_children is hit, sub-agents run synchronously. This is fine — the result is the same, just slower.

File Write Fallback in execute_code

hermes_tools.write_file in execute_code may silently succeed without writing to disk. After calling it, verify with read_file or terminal cat. If the write didn't land, fall back to terminal with Python pathlib:

terminal("python3 -c \"import pathlib; p=pathlib.Path('/path/to/file'); p.write_text('content')\"")

This is more reliable than hermes_tools.write_file for execute_code scripts.

Pitfalls

1. Delegating a task that needs a loaded skill. Sub-agents don't share your context or

your loaded skills. Embed the skill's rules into the brief or let it read the skill file.

2. Treating the summary as fact. Verify anything with external side effects (file

writes, uploads) by checking the artifact yourself.

3. Polling. delegate_task returns to the conversation when done; don't burn turns

polling unless you need a live partial result.

4. Re-delegating just to re-run research the orchestrator already did. If you already

gathered ground truth, pass it in — don't make the sub-agent re-discover it.

5. Forgetting to verify file existence after delegation. Sub-agents may report success

but the file might not exist. Always ls the output paths after a batch completes.

6. Vague file paths in context. Writing "read the file at the path provided" without

actually providing the path wastes the sub-agent's turns searching. Always include

exact absolute paths (e.g., /opt/data/wiki/consume/agentic-chats/extracted/deep-threads/raw-01-foo.txt)

in the goal/context. If you extracted files to disk, list them explicitly.

Support files

templates/task.md — starter brief for documenting and delegating a task.

subagent-delegation