Graph Skill

Run a deterministic orchestration graph from a declarative JSON descriptor.

The runtime consumes the sealed-descriptor and pure-scheduler contracts in

src/graph/* and executes through an independent OS process (omc graph run),

so crash recovery (kill mid-run, rerun, resume from journal) works for real.

Usage

/oh-my-claudecode:graph <descriptor.json>
/oh-my-claudecode:graph "build then test then ask me before deploy"   (author the descriptor first)

The execution surface is always the CLI subcommand:

omc graph run <descriptor.json> [--runs-root <dir>]

Run it via the Bash tool for non-interactive graphs. Progress lines stream as

[run], [node], [ok], [fail], [join], [done].

When To Use

• Repeatable multi-step pipelines with explicit dependencies (DAG)
• Work that must survive interruption: kill/restart resumes from journal
• Auditable runs: OCC journal + projection snapshots under .omc/graph-runs/<run_id>/

When NOT to use: exploratory one-off work (use conversation or /team);

anything needing adaptive re-planning mid-run (graphs are deterministic).

Workflow

1. Descriptor given -> go to step 3.
2. Pipeline described -> author the descriptor JSON (schema below), write

it next to the project (suggest .omc/graphs/<name>.json) and show it to

the user before running. run_id must be unique per logical pipeline;

rerunning with the same run_id RESUMES, not restarts.

1. Approval nodes: if the descriptor contains any "kind": "human-approval"

node, do NOT run it through the Bash tool (stdin is not interactive there;

EOF fails closed to denied). Tell the user to run interactively instead:

! omc graph run <file>

The ! prefix runs it inside this session with live stdin so y/n works.

1. Run and relay progress. Exit codes (normative):

0 succeeded | 1 terminal failed | 19 another writer owns this run (busy)

20 corrupt/tampered journal (fail-closed) | 21 descriptor drift on resume

| 70 runtime crash (unmapped error)

1. Resume: rerunning the same command after a crash replays committed

transitions and continues. Completed nodes never re-execute.

Descriptor Schema (minimal)

{

"descriptor_version": 1,

"run_id": "unique-pipeline-id",

"revision_id": "rev-1",

"goal": "one line",

"nodes": [

{ "id": "n1", "kind": "command", "title": "...", "timeout_ms": 60000,

"max_attempts": 2, "effect_policy": { "policy": "side_effect_free" },

"command": "npm test" },

{ "id": "a1", "kind": "agent", "title": "...", "timeout_ms": 300000,

"max_attempts": 1, "effect_policy": { "policy": "side_effect_free" },

"instructions": "..." },

{ "id": "gate", "kind": "human-approval", "title": "...",

"prompt": "Proceed?" }

],

"edges": [ { "id": "e1", "kind": "fixed", "from": "n1", "to": "a1" } ],

"entry_node_ids": ["n1"],

"concurrency_limit": 2,

"terminal_verification_node_id": "a1"

}

Edge kinds: fixed | conditional | fan_out/join pairs

| back_edge (bounded retries via max_traversals). See src/graph/schema.ts for

the authoritative Zod schema — and read the Capability Boundary section above

for what built-in executors actually execute today.

Capability Boundary & Semantics (read before authoring)

• Edge support: built-in command/agent executors cover fixed edges and

fan_out/join pairs. conditional and back_edge routes are fully

supported by the runtime and scheduler contracts but require a custom

NodeExecutor that emits route on its results — built-in executors never

produce routes, so graphs relying on them fail fast with

route_required rather than guessing.

• Crash-recovery guarantee is at-least-once for command nodes: a crash

between an external side effect and its journal append re-executes that node

on resume. For idempotent commands, the resolved key is available to the

command as GRAPH_IDEMPOTENCY_KEY before it starts and is also recorded for

downstream dedupe. Built-in executors reject reconcile; reconciliation

requires a custom executor with an actual external reconciliation authority.

Exactly-once for external side effects is out of scope for v1.

• Command trust boundary: command nodes are arbitrary shell lines with

process authority in the current working directory. Only run descriptors

you wrote or trust. Command children receive an allowlisted environment

(PATH, HOME/USERPROFILE, TEMP/TMP, locale/timezone, USER identity,

GRAPH_*, and the optional idempotency key), not the host's full secrets.

Commands are not filesystem/process sandboxed.

• Agent authority boundary: built-in agent nodes are explicitly read-only.

They run in the current working directory with no additional directories,

only Read, Glob, and Grep, permissionMode: dontAsk, session

persistence disabled, and a provider-specific environment allowlist. Agent

timeouts abort and interrupt the SDK query. Use a custom executor for any

agent that needs mutation or external effects. Treat

.omc/graph-runs/<run_id>/descriptor.json as executable content.