graph-engineer

name	graph-engineer
description	Author, inspect, validate, and repair portable Graph Engineering projects and their command, script, or Codex/OpenAI agent workflows. Use for `.graph/` source; do not use to hand-edit runtime state.

Graph Engineer

Work from the nearest project containing .graph/graph.json, or pass an explicit --root. Read references/cli.md when choosing commands and references/graph-document-v1.md before changing control flow.

Authoring loop

1. Run graph list --json, graph resources --json, and graph schemas --json to discover existing IDs and contracts.
2. Inspect the target with graph inspect <graph-id> --json. Read only the relevant resource/session reference below.
3. Edit authorable files under .graph/graphs/, .graph/resources/, .graph/prompts/, .graph/schemas/, or .graph/scripts/.
4. Run graph validate <graph-id> --json after every coherent edit. Repair every error using its location.file and JSON Pointer; do not discard independent diagnostics while fixing the first one.
5. Re-run validation until it succeeds. Run the graph only when the user asked for execution and the declared resources/permissions match that authorization.

Non-negotiable boundary

Never author or repair a graph by editing .graph/runtime/, SQLite databases, snapshots, journals, leases, artifacts, provider session IDs, or invocation history. Runtime data is evidence, not source. Use graph status, graph inspect, graph send, graph resume, or graph cancel to interact with runs.

Keep machine definitions JSON-only and portable: reference named bindings from invoke.src; keep prompts, executable commands, scripts, secrets, absolute paths, and provider lineage out of the machine. Every resource-backed invocation needs an explicit stable invoke.id.

References

• Read references/resources-and-bindings.md for command, script, agent, mapping, and recovery declarations.
• Read references/sessions-and-policies.md when choosing fresh versus continued sessions, Codex versus direct API, permissions, or recovery behavior.
• Read references/diagnostics.md when validation fails.
• Read references/cli.md for command syntax and structured-output behavior.
• Read references/effect-runtime.md when changing the TypeScript runtime, providers, persistence, tests, or executable composition.

Use the projects under examples/valid-project/ as copyable patterns. Files under examples/invalid-project/ are diagnostic fixtures, not templates.