Graph Engineering

中文说明 · Apache-2.0

graph-engineering is a Codex Agent Skill for designing governed, project-local agent graphs. It helps an agent understand a project, interview the user until intent is explicit, and then create or evolve Graph contracts that a Codex Supervisor can execute with native sub-agents.

It is deliberately not a graph runtime, a LangGraph wrapper, or a library of global agents. The Skill teaches an agent how to architect the Graph for the project in front of it.

What it produces

After a user confirms the Graph Intent Brief, the Skill creates a small, reviewable control plane in the target project:

AGENTS.md
.codex/
├── graphs/
│   ├── INDEX.md
│   ├── <graph-id>.md
│   └── proposals/
└── agents/
    └── <stable-role>.toml   # only when a role needs durable config

Each graph is a graph-engineering/v1 Markdown contract: intent, scope, state, nodes, execution routing, guarded edges, evaluation, execution, and governance. A project can own several graphs, graphs can contain subgraphs, and edges may form bounded repair loops.

Install

Install the Skill from GitHub in Codex:

Use $skill-installer to install https://github.com/luxiaolei/graph-engineering/tree/main/skills/graph-engineering

Or install it with a compatible Agent Skills installer:

npx skills add luxiaolei/graph-engineering --skill graph-engineering --agent codex

Start a new Codex conversation after installation if the Skill does not appear immediately.

Use

Use $graph-engineering to understand this repository and design the project graphs.

The Skill supports three modes:

• Create — read the project, interview the user, confirm an Intent Brief, then write Graph documents.
• Audit — assess an existing Graph for topology, context boundaries, evaluators, loop termination, and governance.
• Evolve — turn measured execution evidence into a human-approved proposal for a memory, Skill, agent, or Graph change.

The Skill explores before it asks. It asks only questions that change durable Graph decisions, in batches of at most three. It does not write target-project files until the user approves the completed Intent Brief and planned paths.

Core model

Project
  └── Graph registry
       ├── Graph A ── nodes, edges, state, evaluation, governance
       └── Graph B ── nodes, edges, state, evaluation, governance

Codex Supervisor
  └── dynamically spawns bounded sub-agents or uses project-scoped custom agents

A Graph node is a bounded execution unit, not necessarily one sub-agent. It may be an agent, deterministic tool, human gate, subgraph, or composite loop. For example, a composite implementation node can independently delegate an implementer and reviewer, then route reviewer feedback back to the implementer with a finite retry budget or human escalation.

Graph edges carry a guard, minimal context payload, destination, and a stop or escalation rule. Cycles are allowed; unbounded cycles are not.

Agent and composite-loop roles also declare a minimum and default capability tier, reasoning floor, tool authority, and fallback. The Supervisor discovers the active model catalog before delegating, then selects the smallest qualifying GPT-5.6 route: Luna for routine repeatable work, Terra for everyday implementation, and Sol for deep or critical work. A model preference never overrides the user's actual availability, cost/latency constraints, or a required human gate.

Governance and evolution

High-risk external actions require a human gate. Passing model scores alone never authorize them.

Evolution follows a governed loop:

execution evidence → reflection → proposal → human approval → minimal change → validation → Git review

The Skill always proposes an evolution before changing project Graph or Agent files. It never commits, pushes, deploys, or takes an external action without a separate explicit instruction.

Validate a generated project

The bundled validator has no third-party dependencies:

From a checkout of this repository:

python3 skills/graph-engineering/scripts/validate_project_graph.py --project /path/to/target-project

For a governed multi-repository project, run the validator from the declared governance root and map every member ID in .codex/graphs/TOPOLOGY.md to its actual Git repository root:

python3 skills/graph-engineering/scripts/validate_project_graph.py \
  --project /path/to/governance-root \
  --member-root catalog=/path/to/catalog \
  --member-root application=/path/to/application

The governance root owns the authoritative Graph contracts. Member repositories contain only their boundary declaration; the validator rejects copied Graphs, missing members, and worktree aliases.

After installing the Skill, use the location-independent request below. Codex will run the bundled validator from the installed Skill directory:

Use $graph-engineering to audit the graph contracts in /path/to/target-project.

It checks Graph IDs, index registration, node and edge contracts, reachability, bounded cycles, AGENTS.md integration, and basic project-scoped custom-agent fields. It validates structure; human review remains responsible for semantic correctness.

Development

python3 -m unittest discover -s tests -v
python3 scripts/validate_skill.py skills/graph-engineering

See CONTRIBUTING.md for contribution rules.