Graph engineering

Graph Engineering

Design project-local graph contracts that a Codex Supervisor can follow. Do not build a graph runtime and do not execute the target business workflow.

Select the mode

• Use create to establish the first graph or add a new graph to an existing registry.
• Use audit for an existing .codex/graphs contract.
• Use evolve when the user supplies execution history, failures, or corrections and wants a governed improvement.

Read the discovery protocol before create or evolve work. Read the graph contract before writing graph files. Read the Codex mapping when choosing dynamic versus stable agents. Read governance for evolve work or any external side effect. Read multi-repo guidance whenever more than one repository is in scope.

Create workflow

1. Explore the target project read-only first: applicable AGENTS.md, README, architecture and product documents, entry points, tests, Git state, existing .codex files, and relevant history. Derive facts instead of asking for them.
2. Maintain a Graph Intent Brief in the conversation. Resolve project goal, intended users, success criteria, graph inventory, triggers, non-goals, artifacts, state, actors, tools, permissions, context boundaries, evaluation, failure routes, termination, human gates, repository boundaries, actual model availability, cost/latency preferences, minimum capability, and Max/Ultra policy.
3. Ask only one to three decision-changing questions per turn. Do not write project files until all required facts are confirmed, explicitly defaulted, or marked as a blocker.
4. Present the complete Intent Brief and exact proposed paths. Obtain explicit user approval before creating or changing graph files.
5. Copy and tailor the templates in assets/templates/. For a multi-repository graph, create TOPOLOGY.md only at the named governance root and place GRAPH-ENGINEERING-BOUNDARY.md in each authorized member repository; do not copy the graph registry or contracts to members. For an existing graph registry, merge rather than replace: preserve every approved graph document, registry row, proposal, Agent TOML, and non-marked AGENTS.md content; add only the new graph, its one registry row, and any required project-local agent. On a graph ID/path, registry row, proposal path, or Agent-name collision, stop and ask the user whether to evolve the existing artifact or choose a new identifier—never overwrite it. After approval, use scripts/integrate_supervisor_guidance.py --project <target-project> to add or refresh the marked AGENTS.md supervisor block without overwriting existing guidance.
6. Run scripts/validate_project_graph.py --project <target-project> and fix structural failures. For a multi-repository graph, supply every declared member as --member-root <repository-id>=<path>; validation is incomplete without them. Report validation gaps honestly.

Graph rules

• A project can have multiple graphs. Register them in .codex/graphs/INDEX.md.
• Treat a node as a bounded execution unit, not automatically as one sub-agent. Use node types agent, composite loop, tool, human gate, or subgraph.
• Model an independent review loop as a composite node: the Supervisor delegates implementation and review separately, routes only the necessary feedback back to the implementer, and enforces a finite retry or escalation policy.
• Define every edge with a guard, minimal context payload, destination, and a budget or escalation rule. Cycles and local repair routes are valid only when they can terminate.
• Keep agents project-local. Generate .codex/agents/*.toml only for roles that need pinned model/reasoning, permissions, tools, or persistent instructions; otherwise let the Supervisor spawn a bounded dynamic agent.
• Require a human gate before high-risk external side effects. A passing model score alone is never sufficient.
• For every delegated role, define adaptive execution routing: minimum/default capability tier, reasoning floor, difficulty signals, authority, and fallback. Discover the active spawn surface's available models before delegating; never infer Luna, Terra, or Sol availability from another surface.
• Generate stable project Agent TOML for instructions or configuration that must persist. Omit model and reasoning pins when the role needs adaptive routing; add both only with explicit user approval and active-surface confirmation.

Audit workflow

1. Inspect graph documents and related project guidance without changing them.
2. Run the validator.
3. Check that each graph still matches the project, has bounded cycles, minimizes context, distinguishes durable agents from dynamic roles, and has effective evaluation and human gates.
4. Return evidence-backed findings and a minimal repair proposal. Do not edit unless the user asks.

Evolve workflow

1. Classify the evidence as a memory, skill, agent, or graph change. Prefer the least invasive layer that fixes the measured problem.
2. Create a proposal from assets/templates/evolution-proposal.md; include evidence, expected benefit, risk, validation, rollback, and a concrete diff plan.
3. Do not alter graph, agent, or skill files before the user explicitly approves the proposal.
4. After approval, make the smallest coherent change, validate it, and leave Git history reviewable. Do not commit or push without explicit authorization.

Resources

• references/discovery.md — interview and confirmation gate.
• references/graph-contract.md — canonical graph-engineering/v1 document format.
• references/codex-runtime.md — Supervisor, dynamic sub-agent, and custom-agent mapping.
• references/multi-repo.md — control-plane and repository boundary rules.
• references/evolution-governance.md — evidence and approval requirements.
• assets/templates/ — copyable project artifacts.
• scripts/validate_project_graph.py — deterministic structural validation.
• scripts/integrate_supervisor_guidance.py — idempotent AGENTS.md Supervisor integration after approval.