🇨🇳 中文 · 🇯🇵 日本語 · 🇬🇧 English · 🇪🇸 Español

Graph Engineering Architect

Design systems that improve without learning to fool themselves.

graph-engineering-architect is a Codex Skill and an open engineering kit for designing grounded graphs of interacting improvement loops.

It helps you decide whether a task needs a direct workflow, one bounded loop, or a governed graph—and then makes the graph's evidence, authority, anchors, conflicts, and human boundaries explicit.

Open the four-language visual guide · Install · Architecture · Example contract

The 30-second explanation

A loop says:

measure -> act -> check -> repeat

That works until the metric becomes a target, the target becomes wrong, two loops fight each other, or the measurement quietly stops representing reality.

Graph Engineering connects several loops with explicit control relationships:

execute -> verify -> constrain or veto
    |          |
    v          v
counter-signal  reality anchor
    |          |
    +-> arbitrate -> human approval -> stop or continue

The point is not to add more agents. The point is to make it clear who acts, who checks, who can veto, what evidence is independent, and where machine authority ends.

Why one loop can fail

Structural failure	What it looks like	Graph response
Metric gaming	The score rises while the real outcome worsens	Pair the metric with counter-signals and a reality anchor
Upward blindness	The loop faithfully optimizes the wrong target	Put target revision in a slower, human-governed loop
Loop conflict	Speed, quality, safety, and cost optimize against each other	Add explicit arbitration and priority rules
Measurement decay	Dashboards stay green while data or definitions drift	Add an audit loop with independent provenance

The minimum grounded graph

A serious graph usually needs these responsibilities:

1. Root outcome — the real result, owned by a human.
2. Execution loop — acts within declared bounds.
3. Verification loop — independently tests progress claims.
4. Counter-metric or audit loop — detects cheap wins, side effects, and measurement drift.
5. Arbitration — resolves conflicts before they become incidents.
6. Reality anchor — evidence the optimizer cannot create, edit, or hide.
7. Human gate — approves changes to goals, anchors, permissions, and frozen rules.
8. Stop and handoff — records success, failure, blockage, rollback, or budget exhaustion truthfully.

These are responsibilities, not necessarily separate agents.

The durable principle

The durable axis is not loop versus graph. It is ungrounded versus grounded.

A sophisticated graph can still fail if every node reads the same corrupted dashboard. A second agent is not an independent verifier when both agents share the same data and scoring logic. Grounding requires evidence that touches the world independently—and frozen rules the optimizer cannot weaken.

Install

Skills CLI

npx skills add 2023Anita/graph-engineering-architect

Manual installation

git clone https://github.com/2023Anita/graph-engineering-architect.git
cp -R graph-engineering-architect/skills/graph-engineering-architect ~/.codex/skills/

Reload Codex, then invoke:

Use $graph-engineering-architect to assess and design the minimum grounded architecture for this workflow.

Initialize a graph contract

python3 skills/graph-engineering-architect/scripts/init_graph.py \
  "Improve real customer issue resolution without increasing churn" \
  --root "/path/to/project" \
  --slug "customer-support"

This creates:

.graph/customer-support/
├── graph-spec.md
├── graph.json
├── validation-report.md
└── handoff.md

The scaffold is intentionally incomplete. Replace its placeholders, then validate:

python3 skills/graph-engineering-architect/scripts/validate_graph.py \
  "/path/to/project/.graph/customer-support"

Structural validation catches missing nodes, dangling edges, unfrozen anchors, absent human gates, and incomplete stop rules. It cannot decide whether your root goal is morally or strategically correct; that remains human judgment.

Repository map

graph-engineering-architect/
├── skills/graph-engineering-architect/  # Installable Codex Skill
├── examples/customer-support/           # Complete grounded contract
├── docs/                                # Four-language visual website
├── assets/project-illustrations/        # Original generated illustrations
├── scripts/check_project.py             # Repository integrity checks
├── tests/                               # Validator regression tests
└── .github/workflows/validate.yml       # Dependency-free CI

Use it with Loop Engineering

The two Skills have different jobs:

• Graph Engineering Architect owns topology, edge authority, grounding, cadence separation, cross-loop conflicts, and human governance.
• Loop Engineering Co-Builder owns the state, permissions, budget, evidence, stop logic, recovery, and handoff inside one bounded loop.

Design the graph first. Instantiate only the nodes that genuinely need a persistent loop.

Verify the project

No third-party runtime dependency is required:

make verify

This checks the Skill package, example graph, four-language key parity, illustration assets, internal links, and validator regression tests.

Design boundaries

• Do not create one agent per node by default.
• Do not call shared-data self-review “independent verification.”
• Do not let fast loops rewrite slow goals or protected tests.
• Do not let improvement loops change Skills, permissions, memory, production configuration, or root goals without explicit human approval.
• Do not declare completion because every agent agrees; require fresh anchored evidence and a usable handoff.

Provenance and license

The conceptual model was synthesized from a user-provided essay on the shift from Loop Engineering to Graph Engineering and reconciled with a working Loop Engineering control model. Trend claims are treated as design heuristics, not scientific consensus.

Illustration provenance and rights notes are documented in assets/illustration-provenance.md.

Code and original documentation are released under the MIT License.