Summary

Adds a "When to Use Nested Workflows" section to the swamp-workflow skill covering the three cases where a child workflow is the right shape — most importantly, the one that's invisible until you hit it:

forEach over an async list. forEach.in is evaluated synchronously at expansion time (src/domain/workflows/execution_service.ts:1543), so CEL expressions that return a Promise — data.latest(), data.findByTag(), data.findBySpec() — never resolve in that position, and the step fails with a misleading forEach.in must evaluate to an array or object, got: object (the "object" is the unresolved Promise).

Task inputs: ARE awaited for both model_method and workflow tasks (execution_service.ts:329 and :1964, both using evalService.evaluateData which calls celEvaluator.evaluateAsync). So the canonical fix is to resolve the async call in the parent's task.inputs and let the child iterate over a plain inputs.<name>:

# parent — task.inputs awaits data.latest()
- name: download
  task:
    type: workflow
    workflowIdOrName: download-episodes
    inputs:
      episodes: ${{ data.latest("dedup", "current").attributes.episodes }}

# child — forEach over pre-resolved inputs array
- name: download-${{ self.ep.show }}
  forEach:
    item: ep
    in: ${{ inputs.episodes }}
  task: { ... }

Changes

• references/nested-workflows.md — new top section covering three "when to nest" cases (async list → forEach, reusable sub-process, independent cadence) and an explicit "when NOT to nest" list (use dependsOn for ordering, direct CEL for shared values, 10-level nesting cap).
• references/expressions-and-foreach.md — new "forEach.in Cannot Await Promises" subsection right after the forEach variables table, with a pointer to nested-workflows.md#when-to-use-nested-workflows so readers landing on the forEach doc find the escape hatch.
• SKILL.md — reference index pointer updated to surface "when to split a workflow into parent + child (including the async-list-into-forEach pattern)".

Follow-up issue filed for the misleading got: object error message itself (the docs fix the user-facing workaround; the error message fix is orthogonal).

Test Plan

• deno fmt --check passes
• deno lint passes
• CI verifies deno run test
• Skill content renders correctly in future sessions (verified by re-loading the swamp-workflow skill)

🤖 Generated with Claude Code