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/
│   └── contracts/<graph-id>/task-admission-pack.yaml  # authority-critical only
└── 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 one-time bounded reversible task may not need a durable Graph at all. When one is justified, the Skill chooses the lowest sufficient tier:

governed-implementation/v1 remains supported as a legacy alias for the authority-critical profile.

Profile selection is now action-derived. A user-authorized one-time, bounded, reversible local task with no authority effect is NO_GRAPH; it proceeds under repository rules without a Graph-creation question. Durable profiled Graphs declare workflow lifetime, reversibility, actual authority effect, material batch, family/lineage, one canonical status artifact, and a real business-gate delta. Validator/receipt/Graph/seal progress is not a business delta.

Graph-contract selectability is draft, active, terminal, or retired, while one declared canonical artifact owns run and business status. There is at most one active Graph per family and lineage. Successor ordinal three is a hard lifetime ceiling; ordinal four fails, root evolution does not reset the counter, and a managed run never creates its own successor.

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.

After a create or evolve task has produced its requested artifacts and reported validation, the Skill asks once whether to enter event-driven managed execution with stated positive limits for parallel subagents, dispatched work items, and wall-clock minutes. With explicit consent to those exact limits it renders a portable Root Supervisor prompt:

python3 skills/graph-engineering/scripts/generate_managed_supervisor_prompt.py \
  --project /path/to/target-project --graph delivery --run delivery-2026-07-30 \
  --max-parallel-subagents 2 --max-dispatched-work-items 8 --max-wall-clock-minutes 60

Only a Codex surface that verifies both separate-task creation and completion/attention hooks may launch that separate task and attach the hooks. Otherwise the Skill shows the prompt and explicitly says no hook is attached; it never silently runs the business Graph from the design task.

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. Workflow-lite stays small. Reviewed-batch freezes one complete candidate and starts one independent read-only reviewer. Authority-critical adds the closed catalog and reconciliation machinery only when its blast radius justifies it.

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

Parallelism is bounded by the graph and actual runtime capacity. Authority-critical work additionally uses one writer per canonical domain, conflict-free ready selection, exclusive high-risk work, and serial integration.

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, action-derived profiles, lifecycle/family limits, canonical status, business deltas, index registration, node and edge contracts, reachability, bounded cycles, AGENTS.md integration, and basic project-scoped custom-agent fields. Reviewed-batch adds a small independent-review contract. Authority-critical adds the closed admission-pack schema, contract-validation dominance, complete-batch review barrier, typed repair routing, pre-invocation lifecycle witness, parallelism bounds, serial integration, and terminal seal. 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.