cao-workflow

Write a .py file to ~/.aws/cli-agent-orchestrator/workflows/ that imports from the cao_workflow package. Use step() or run_step() to invoke agents, declare an INPUTS dict for parameters, and call emit_output() for the run result. Then validate with cao workflow validate before running.

Use a ThreadPoolExecutor and give every concurrent run_step call an explicit, stable step_id derived from sorted inputs. The default sequential call-N counter is not deterministic under concurrent scheduling, so resume would replay the wrong results without stable IDs.

A recovery policy declares what re-running a step would mean: idempotent, reconcile, or manual. It is an author claim, not a protection — declaring idempotent on a step with side effects means resume will re-execute it. Omitting a policy via run_step halts for a human decision instead.

Resume re-executes the script top-to-bottom and replays journaled step results. Nondeterministic top-level values from random, time, datetime, or uuid differ on replay and raise ReplayDivergenceError, so the validator flags them. Derive IDs from inputs instead.

Run cao workflow resume <run-id>. A halted step surfaces as a ShimHTTPError with status 409; resolve it with --decide <step_id>=rerun or --decide <step_id>=skip, then resume again. Each decision authorizes exactly one attempt and does not carry forward.

Prefer claude_code as the step provider because it runs headless. The kiro_cli provider currently launches an interactive TUI that hangs run_step, though this is interim guidance pending a tracked fix.