Clarify Claude workflow primitive compatibility gaps

[xz1220]

Context

A review of ODW's workflow primitives against Claude Code dynamic workflows found that the core surface is aligned, but several currently documented or typed primitives are compatibility placeholders rather than full Claude-equivalent behavior.

This matters because Claude Code workflows are shareable via .claude/workflows/*.js, and ODW positions itself as able to run Claude-format workflow scripts. Scripts that only use the core primitives should migrate well; scripts that rely on newer/runtime-specific features may fail or silently lose semantics.

Official Claude docs used for comparison:

• Dynamic workflows: https://code.claude.com/docs/en/workflows
• .claude/workflows/*.js sharing: https://code.claude.com/docs/en/claude-directory
• Structured outputs: https://code.claude.com/docs/en/agent-sdk/structured-outputs
• Parallel agents overview: https://code.claude.com/docs/en/agents

What matches today

These are implemented and align with the core Claude workflow model:

• export const meta loader shape
• agent(prompt, opts?) as the only primitive that performs work
• parallel(thunks) barrier semantics with ordered results and recoverable failures becoming null
• pipeline(items, ...stages) per-item staged execution with failed items becoming null
• phase(title) and log(message) progress events
• injected args
• schema as a plain JSON Schema object passed to agent(..., { schema })
• concurrency cap and total-agent backstop

Current validation is strong for the happy path: npm test passes, including mock end-to-end runs for deep-research.js, fan-out-reduce.js, adversarial-verify.js, and loop-until-dry.js.

Compatibility gaps / migration risks

1. workflow() is typed/documented but not implemented

Current behavior: workflow() throws notImplemented("nested workflow() — deferred to v2").

Impact: any Claude workflow using nested workflow calls will fail at runtime in ODW.

Suggested action: mark workflow() clearly as unsupported in v1 in README/types/skill docs, or implement one-level nesting.

2. agentType semantics differ

Current behavior: ODW treats opts.agentType as an adapter name when opts.adapter is not set.

Claude behavior: agentType refers to a subagent role/type in Claude's runtime.

Impact: Claude scripts using agentType: "Explore", "Plan", or project subagent names may fail with an unknown adapter, or route to a different backend than intended.

Suggested action: either document this as an ODW-specific mapping, or add an explicit compatibility layer that maps known Claude agent types to adapters/roles.

3. model is accepted but ignored

Current behavior: opts.model is accepted for compatibility but not routed to adapters.

Impact: scripts that intentionally route cheap/expensive stages to different models will still run, but cost/performance semantics are lost.

Suggested action: document as no-op in v1, then add adapter-level model placeholder support.

4. isolation: "worktree" is accepted but ignored

Current behavior: isolation is controlled globally by workspaceMode: "copy" | "inplace"; per-agent isolation does not select git worktrees.

Claude behavior: workflows/subagents can request worktree isolation.

Impact: scripts should still run, but file-editing workflows do not get Claude-equivalent per-agent git worktree semantics.

Suggested action: document the current copy-mode substitute, and decide whether per-agent worktree isolation is a v1.5 or v2 target.

5. budget is only a stub

Current behavior: budget.total is injected, but spent() always returns 0, and remaining() does not decrement.

Impact: scripts that only use budget.total to choose initial fan-out depth are fine. Scripts that use remaining() as a loop guard can overrun until maxAgents stops them.

Suggested action: document this clearly and avoid recommending remaining() for v1 workflows.

6. JSON Schema support is a subset

Current behavior: ODW validates a small dependency-free subset: type, properties, required, additionalProperties, items, minItems, and enum.

Claude structured outputs support a broader JSON Schema surface, including features such as const and $ref definitions via the SDK docs.

Impact: complex Claude schemas may be under-validated or rejected/handled differently in ODW.

Suggested action: either document the supported subset prominently, or use a JSON Schema validator package if full compatibility is a goal.

7. Loader is not a Claude-equivalent sandbox

Current behavior: ODW uses AsyncFunction and does not prohibit direct JS globals such as Date.now(), Math.random(), or dynamic runtime escape hatches.

Claude docs state workflow scripts coordinate agents and do not get direct filesystem/shell access; previous research also noted deterministic restrictions for resumability.

Impact:

• Claude scripts generally run in ODW.
• ODW-authored scripts may accidentally use APIs that will not run in Claude Code.
• Lack of sandboxing matters if running untrusted shared workflows.

Suggested action: add a compatibility/safety mode that rejects non-portable APIs, or document that ODW v1 is not a sandbox and is only intended for trusted scripts.

8. Resume/journaling is not implemented

Claude workflows track completed agent results and can resume within the same session. ODW persists run directories and supports pause/stop/result, but does not cache and replay completed agent calls.

Impact: interrupted ODW runs do not have Claude-equivalent resume semantics.

Suggested action: keep documented as out of scope for v1, but avoid implying parity with Claude resume.

Proposed doc wording

Instead of saying ODW runs Claude's "exact" workflow dialect without qualification, consider:

ODW supports the core Claude Code workflow primitive subset: meta, agent, parallel, pipeline, phase, log, args, and JSON-schema structured handoff. Some Claude runtime features are accepted for source compatibility but are no-ops or deferred in v1: nested workflow(), per-agent model, Claude agentType, git-worktree isolation, real token accounting, deterministic sandboxing, and resumable journaling.

Acceptance criteria

• README and skill/references/primitives.md distinguish "core-compatible" from "full Claude runtime parity".
• types/workflow.d.ts marks no-op/deferred fields as such.
• Migration guide/checklist documents which Claude workflows run unchanged and which require edits.
• Tests cover expected failures/no-ops for workflow(), model, agentType, isolation, and unsupported schema keywords.