docs(workflow-creator): add headless/background stage documentation

[lavaman131]

Summary

Documents the new headless: true option on SessionRunOptions, which lets workflow stages run provider SDKs in-process without a tmux window. Updates the workflow-creator skill references and README to cover per-SDK behavior, graph topology semantics, the fan-out/merge pattern, and a new failure mode.

Key changes

workflow-creator skill (SKILL.md)

• Updated skill description to trigger on headless/background stages keywords
• Added "Background (headless) stages" section with code examples and when-to-use guidance
• Updated concept-to-code mapping table with headless entries
• Added structural rule updated AGENTS.md/CLAUDE.md #8: headless stages share the same callback interface

Reference docs

• references/agent-sessions.md — per-SDK headless mode sections for Claude (Agent SDK query() in-process), Copilot (no-tmux SDK subprocess), and OpenCode (createOpencode() in-process)
• references/control-flow.md — headless stages are transparent to graph topology: visible → [N headless] → visible renders as visible → visible; includes decision table (headless vs. visible)
• references/failure-modes.md — new F16 failure mode: headless stage errors produce no graph node; wrapping callbacks with descriptive error context is the recommended mitigation
• references/getting-started.md — new headless stages section; updated SessionRunOptions type signature (headless?: boolean); updated paneId docs; added headless-test to builtin reference implementations

README

• Added Background (headless) stages row to the Workflow SDK capabilities table
• New collapsible example: seed → [3 parallel headless] → merge pattern
• Updated SessionRunOptions reference table to include headless?: boolean
• Added key rule updated readme #7 on headless stage callback API parity
• General table-alignment cleanup throughout

No breaking changes

This is a documentation-only PR — no runtime behavior is changed.

[claude]

Code Review

Documentation-only PR adding headless/background stage docs to the workflow-creator skill and README. I verified all technical claims against the implementation in src/sdk/ — the per-SDK behavior, type signatures, paneId format, graph-transparency semantics, and error paths all match the code accurately. Nice work; F16 in particular is a valuable addition.

Issues found

1. Inconsistency: headless-test listed as a "builtin SDK workflow" — it isn't (getting-started.md:277-285)

## Builtin reference implementations

The SDK ships two builtin workflows that demonstrate production patterns…

- **`ralph`** (`src/sdk/workflows/builtin/ralph/`) — …
- **`deep-research-codebase`** (`src/sdk/workflows/builtin/deep-research-codebase/`) — …
- **`headless-test`** (`.atomic/workflows/headless-test/`) — …

Three problems:

• The heading says "two builtin workflows" but three are now listed
• headless-test lives in .atomic/workflows/ (this repo's local config), not src/sdk/workflows/builtin/. Users who bun add @bastani/atomic will not receive it
• The trailing sentence "Both include helpers/ directories…" no longer parses cleanly with three items, and headless-test/{claude,copilot,opencode}/index.ts has no helpers/ dir at all

Suggestion: either move it under a separate "In-repo example workflows" sub-heading, or describe it inline in the headless section instead of listing it next to shipped builtins (which sets the wrong expectation about what end users will get from the package).

2. Minor — headless-demo vs headless-test naming (README.md:528)

The README example uses name: \"headless-demo\" while the actual repo workflow is headless-test. Inline examples don't have to match a real workflow, but if a reader cross-references the two it's mildly confusing. Not blocking — just a heads-up.

3. Minor — README TOC auto-generation noise

The regenerated TOC adds - [Atomic](#atomic) as a top-level entry pointing back at the page title, plus per-section heading links for every #### (e.g., Builder API, Key Rules). This is a side effect of whatever TOC tool ran; the pre-PR version was hand-curated and shorter. Worth deciding whether to keep the deeper auto-generated TOC or restore the more curated one. Not a correctness issue.

Verified accurate

• ✅ SessionRunOptions.headless?: boolean (src/sdk/types.ts:249)
• ✅ HeadlessClaudeClientWrapper/HeadlessClaudeSessionWrapper — noop start/stop, direct query() call (src/sdk/providers/claude.ts:599-631)
• ✅ OpenCode uses createOpencode({ port: 0 }) with oc.server.close() cleanup (src/sdk/runtime/executor.ts:601-607)
• ✅ Copilot headless creates CopilotClient without cliUrl so SDK spawns its own subprocess (src/sdk/runtime/executor.ts:585-587)
• ✅ paneId format: headless-\${name}-\${sessionId} (src/sdk/runtime/executor.ts:767)
• ✅ Graph transparency: graphParents = isHeadless ? [] : graphTracker.onSpawn() and skipped onSettle for headless (executor.ts:732, 1011, 1036)
• ✅ Background task counter exists in statusline (src/sdk/components/statusline.tsx:40-50)
• ✅ Error paths: \${sessionDir}/error.txt (executor.ts:983) and orchestrator.log in session dir (executor.ts:336)

Style / quality

• F16's Right example reuses the stage's own name in the error prefix ([gather-a]). Since headless stages already have a deterministic name, you might note that the runtime's error logger already includes name and sessionId in error.txt — so the wrap is mostly for surfacing context in the orchestrator log / TUI error overlay. Worth being explicit so readers understand they're not duplicating logging that already happens.
• The "Both include helpers/ directories" sentence (mentioned above) is the only place where the prose drifted out of sync with the new bullet — easy to fix.
• Per-SDK examples in agent-sessions.md correctly use the right save pattern for each provider (Claude s.sessionId, Copilot await s.session.getMessages(), OpenCode result.data!). Consistent with the existing table in the README.

Tests / coverage

N/A — pure docs. The fact that a .atomic/workflows/headless-test/ workflow exists in the repo across all three SDKs is a reasonable smoke check for the documented APIs, though it's not part of the automated test suite.