graph-engineer

A Claude Code skill for a common problem: by default, you want a second model (Codex) to apply the code while Claude preserves context for orchestration and judgment, and you don't want Codex grading its own homework without arbitration. graph-engineer makes Claude the orchestrator and arbiter, and Codex the one who writes, adversarially reviews, and fixes the code, running as a self-correcting loop instead of a single implement-and-hope pass. The split isn't only about token cost: it also separates roles and puts a different model in the arbitration path.

Status: adversarially reviewed and dogfooded end-to-end in this repository. The 8-node cycle and the QUALITY GATE resolver have now been exercised against two real features in this skill's own repository, through repeated REFACTOR rounds and real failure-recovery paths. Real-world validation is still limited to this one repository; see Limitations / Risks before running --write against anything you care about.

What is "graph engineering"?

Not an official term — no Anthropic or OpenAI product is called that. It's useful as a mental model anyway: think of the workflow as a small graph.

• Nodes are units of work: Claude writing a spec, Codex implementing, Codex critiquing, Claude triaging.
• Edges are handoffs between them: spec → implementation → mechanical quality gate → critique → triage → fix.

What makes it a graph instead of a list is its return edges: a failed QUALITY GATE returns to the last writer, and VERIFY loops back to CRITIQUE. The latter lets the same critique step run again, and again, over code that's already been through one round of fixes — until a stop condition is actually met. Take those edges out and you just have a pipeline: write once, review once, done, bugs and all.

This skill is a concrete implementation of two patterns Anthropic does document officially — Orchestrator-Workers and Evaluator-Optimizer, from Building Effective Agents — nested together. See skills/graph-engineer/references/sources.md for exactly what's official versus what "graph engineering" gets credited with online but isn't.

The cycle (8 nodes)

The cycle doesn't stop after one implement→review→fix pass — a fix can introduce its own problems, and a first pass rarely catches everything. The outer loop keeps going until a condition you define is verifiably true: usually "no valid findings left, and functional tests pass."

At a glance — the state machine this skill actually runs (detailed trace below):

flowchart TD
    PF["0 PRE-FLIGHT<br/>Claude: branch + gate resolution"] --> SPEC["1 SPEC<br/>Claude: contract → PROJECT_CONTEXT.md"]
    SPEC --> IMPL["2 IMPL<br/>Codex --write"]
    IMPL --> QG{"3 QUALITY GATE<br/>mechanical checks"}
    QG -- "fail (max 3/activation)" --> IMPL
    QG -- pass --> CRIT["4 CRITIQUE<br/>Codex, read-only"]
    CRIT --> DEBATE{"5 DEBATE<br/>Claude triages"}
    DEBATE -- valid --> REFACTOR["6 REFACTOR<br/>Codex --resume-last --write"]
    DEBATE -- "debatable: internal Codex round-trip" --> DEBATE
    REFACTOR --> QG
    DEBATE -- "no findings" --> VERIFY{"7 VERIFY<br/>functional tests"}
    VERIFY -- fail --> CRIT
    VERIFY -- pass --> DONE(["DONE"])

Loading

On the default codex path, every node is Claude or Codex, never a third agent. Each completed writer iteration's outcome is durably recorded in PROJECT_CONTEXT.md, so the cycle can resume from that checkpoint after a session restart even though within-round continuity relies on --resume-last session memory — together, those explicit transitions and durable records make this a graph/state-machine rather than a single long conversation. The local-Explore Claude backends' continuity additionally relies on the orchestrator's conversation memory; see backend-selection.md. Which tool call implements each node (subagent, flags) is in the How it works table below.

QUALITY GATE is numbered so the invariant is visible, but it is not a new actor or an unconditional pipeline stage: it is a capped retry edge attached to whichever writer, IMPL or REFACTOR, just ran. CRITIQUE may run only on a tree that has passed QUALITY GATE since the last write, or for which a currently-valid persisted user-confirmed opt-out exists. The gate is mechanical only (lint, formatting, type checking, and build), while VERIFY owns functional tests and acceptance criteria. A VERIFY failure returns to CRITIQUE for classification as an implementation defect, test defect, contract mismatch, or environmental failure; it never takes the fast mechanical-fixer route. If VERIFY cannot execute assertions at all because of an environmental block, the cycle escalates directly to the user.

Before IMPL, PRE-FLIGHT resolves the project's real local quality command. For an existing feature section it stores the resolution—not a previous result—there before SPEC; for a brand-new full-cycle feature, SPEC persists the PRE-FLIGHT resolution in its initial section-creation write with the contract. The cycle revalidates that cached resolution after each write. Ambiguous or unsafe candidates require one user decision; no usable candidate stops the cycle before IMPL unless the user explicitly opts out. See skills/graph-engineer/references/quality-gate-detection.md for the resolver order, safety checks, cache schema, bundled-command split, retry cap, and escalation rules.

Active feature entries keep bounded truth under #### Current state and an append-only audit history under #### Round log. Each node is dispatched under its default disclosure policy—fresh elevated lenses and the exit challenger are instructed not to read the log—and, when checkpoint commits are authorized, a successfully completed write cycle atomically moves the full section to PROJECT_CONTEXT.archive/<feature-slug>.md (otherwise it escalates without a partial move). See the complete context-lifecycle.md protocol for the section shape, node-specific reads, terminal pointer, and interruption checks.

Node 5 isn't a flat pass/fail filter — "debatable" findings open their own small sub-loop, invisible in the 8-node diagram above:

[5 DEBATE]  finding classified as "debatable"
      ↓
      On the default codex path, Claude reinjects it to
      codex:codex-rescue with a counterargument
      ("Codex flagged X, but Y because Z — do you stand by it or reconsider?"),
      always with --resume-last so the thread stays continuous
      ↓
      Codex replies (still read-only — no --write in this call either)
      ↓
      Claude decides: valid → refactor, or false positive → discarded
      (with written justification either way)

This sub-loop happens entirely inside node 5, before anything reaches node 6 — it's an extra round-trip to Codex per debatable finding, not just a triage checkbox. Non-Codex backends use the manual or cross-session continuity mechanism in backend-selection.md instead.

/goal (see Usage) is Claude Code's built-in stop-gate: it holds the turn open until your success condition is verifiably true. On top of that, the outer critique loop has two brakes for when it isn't converging, and both are conditional on your /goal text actually including them — neither is enforced by the skill unconditionally:

• An anti-loop cutoff — if, across two rounds in a row, Claude judges a CRITIQUE finding to be the same underlying complaint restated with no real change to the code, the cycle is meant to stop and escalate to you instead of spinning. But /goal binds Claude to its literal condition: this cutoff can only actually end the turn early if your /goal text itself includes an explicit escalation/stop clause (the templates in skills/graph-engineer/references/goal-templates.md include one — make sure yours does too). Without that clause, Claude remains bound by "keep working until true" and will surface the repeated finding rather than unilaterally stopping. Don't rely on this as an unconditional guarantee.
• A recommended total CRITIQUE cap (3 passes in the linked goal-templates.md) — unlike the anti-loop cutoff, this isn't a distinct finding-comparison rule; it's a plain iteration ceiling you write into /goal so a string of different findings can't keep the cycle going indefinitely. Same caveat: only as real as the clause your /goal text includes.

QUALITY GATE has its own separate absolute brake: no more than 3 failed runs per writer activation. That cap never expands based on apparent progress.

Everything above is strictly sequential with return edges. The one real fan-out/join in the whole cycle appears only when elevated assurance is on, and it happens inside node 4 — the node count stays 8, this is not a 9th node.

A hypothetical worked example

This is an illustrative flow, not a transcript of an executed end-to-end run (see the Status note above). Loosely modeled on the single-message template — shortened here for readability; don't copy this exact text, use the full template in goal-templates.md, also linked from Usage, which includes the CRITIQUE cap, anti-loop, QUALITY GATE, and environmental stop clauses this shortened version omits:

/goal Implement a POST /api/webhooks/verify endpoint in src/routes/webhooks.ts,
code written and fixed by Codex via graph-engineer. Stop condition: the
endpoint verifies webhook signatures and returns the documented status codes,
AND no valid findings remain from the adversarial-review. [...full template's
CRITIQUE cap, anti-loop, QUALITY GATE, and environmental clauses apply too.]

0. PRE-FLIGHT — Claude confirms the branch and worktree are safe, then resolves and persists the feature's mechanical quality gate.
1. SPEC — Claude writes the endpoint's contract (inputs, signature verification rule, response codes) to PROJECT_CONTEXT.md.
2. IMPL — Codex writes webhooks.ts following that contract.
3. QUALITY GATE — The resolved local lint/typecheck/build command passes over the newly written tree.
4. CRITIQUE — Codex reviews its own code adversarially and reports, say, two findings: "the signature comparison uses === instead of a constant-time compare — timing attack surface" and "the handler doesn't log request IDs".
5. DEBATE — Claude reads the full security-related file before ruling, then triages: the timing-attack finding is valid, so it goes to refactor. The logging one is judged a false positive for this repo (it has no logging convention anywhere else) — discarded, with that reason written down, not silently dropped.
6. REFACTOR — Codex swaps in a constant-time comparison.
   • Mini-loop: Return to node 3 QUALITY GATE, then node 4 CRITIQUE — both pass this time.
7. VERIFY — Functional tests run green. The terminal archival transition succeeds, the /goal condition is met, and the loop ends.

Checkpointing

Long cycles — especially with elevated assurance, which can chain many REFACTOR rounds — benefit from a restore point after every round. Claude creates a local git commit (never pushed) after each round's mechanical checks pass and before the next review starts, tagged Cycle-State: CHECKPOINT rather than COMPLETE — a checkpoint only proves the tree passed lint/type/build, not that the adversarial review or tests approved it. If a later round goes wrong, you can revert to any prior round's checkpoint. See skills/graph-engineer/SKILL.md's QUALITY GATE node for the exact commit format and the narrow exception this carves out of "Claude never edits implementation files" (it covers local git metadata, never file content).

Requirements

The default codex backend needs the official OpenAI Codex plugin for Claude Code: openai/codex-plugin-cc.

/plugin marketplace add openai/codex-plugin-cc
/plugin install codex@openai-codex
/codex:setup

/codex:setup should report Status: ready. The opt-in backend: claude, backend: claude:<account-alias>, and backend: claude-writer:<account-alias> routes do not call Codex and therefore do not require this plugin, though all backend-resolution and cycle invariants still apply. The skill also needs Claude Code itself — this skill relies on the built-in /goal command; confirm it's available in your installed build, since this repository doesn't currently pin a verified Claude Code version.

Exercised end-to-end against openai-codex plugin v1.0.6. This repository's real dogfooding run exercised the routing, flag, and sandbox assumptions (single codex:codex-rescue entry point, --write / --resume-last flag behavior, and sandbox enforcement of read-only CRITIQUE and exit-challenger calls), including recovery after a resumed --write attempt was rejected by the read-only sandbox. This verification is specific to v1.0.6. Installing via the commands above pulls whatever version is current, which may not be v1.0.6; check your installed version and treat anything other than v1.0.6 as compatibility-unverified.

Installation

npx skills add Ranteck/graph-engineer

This uses the skills CLI (vercel-labs/skills) — an independent installer, not a Claude Code builtin. Requires Node/npm.

Or manually, after cloning this repository and from its root:

mkdir -p ~/.claude/skills
cp -R skills/graph-engineer ~/.claude/skills/

Before authorizing any --write cycle, exercise the review-only template (see Usage below) against a disposable repository that starts with a clean git status, and confirm the final git status still reports clean afterward (a clean starting point is what makes that comparison meaningful).

Choosing a mode

There are three entry paths. On the default codex backend, the cheapest costs a single Codex call and is a complete answer for most review work, so pick deliberately rather than defaulting to the full cycle.

Both columns are derived, not measured. Floor is a run where CRITIQUE finds nothing. One-fix round is a run where one finding is accepted, fixed, and re-reviewed once — the smallest run that actually does something. Real runs with several findings cost more.

Mode	Path	Standard Codex calls (floor / one-fix round)	Use when
Review-only	PRE-FLIGHT → CRITIQUE → DEBATE/report → DONE	1 / 1	You want an adversarial read of existing code. Authorizes no writes; only the default Codex path enforces that with a sandbox.
Refactor-only	PRE-FLIGHT → CRITIQUE → DEBATE → REFACTOR → QUALITY GATE → CRITIQUE → … → DONE	1 / 3	Existing code needs fixing, with no new feature contract involved.
Full 8-node write cycle	PRE-FLIGHT → SPEC → IMPL → … → VERIFY	2 / 4	New functionality that needs a contract written before the code exists.

Review-only is 1 in both columns because it never refactors — it reports and stops. The other two reach their one-fix number by adding REFACTOR plus the re-review CRITIQUE after it.

On the default codex backend, only IMPL, CRITIQUE, and REFACTOR are Codex calls; the other nodes are Claude. QUALITY GATE reaches Codex only when a mechanical check fails, and DEBATE only when a "debatable" finding is reinjected (see the sub-loop above). Elevated assurance expands node 4 and adds exit-challenger passes — it doesn't multiply IMPL or REFACTOR — and has its own, much higher floors.

Both write-authorized paths start at PRE-FLIGHT for a reason: that's where the clean-tree and non-main branch checks happen. Refactor-only does not begin by calling Codex.

When not to authorize a write cycle. The question is blast radius, not whether a change is "structural" or "cosmetic". A change that alters no behavior, crosses no module boundary, and touches no text another file cites as a contract hasn't earned a write cycle — read it yourself, or use review-only. Naming isn't automatically exempt: a local variable's name has no blast radius, but a term other files reference as a contract does, and getting that wrong propagates silently.

Backend selection (optional)

IMPL, CRITIQUE, and REFACTOR can select one backend per cycle with backend: codex, backend: claude, backend: claude:<account-alias>, or backend: claude-writer:<account-alias>; omission keeps codex as the default. claude-writer:<account-alias> is available only for the full 8-node write cycle and refactor-only, not review-only. Any Claude backend gives up the cross-model diversity that the default path adds between reviewer and orchestrator; claude:<account-alias> also has the weakest writer/reviewer isolation because the same retained session remembers authoring the code it reviews. claude-writer:<account-alias> instead keeps the same fresh local Explore reviewer as backend: claude, improving on the retained session's self-review but only moving the writer's token cost to the named second account — it does not add independent review.

See the complete backend-selection.md protocol for confirmation, persistence, dispatch, continuity, elevated-assurance compatibility, mutation detection, authority, confidentiality, workspace-identity limitations, and out-of-scope behavior.

Usage

The default-codex, write-authorized template linked below lets Codex edit files. For a review-only audit that authorizes no edits, use the dedicated review-only template in skills/graph-engineer/references/goal-templates.md instead of substituting "review" into a write-authorized prompt; the two modes have different, incompatible permissions. Review-only also isn't the 8-node cycle running read-only — it's a separate terminal path (PRE-FLIGHT → CRITIQUE → DEBATE/report → DONE) that skips SPEC, IMPL, QUALITY GATE, REFACTOR, and VERIFY. It reviews the scope you name directly and doesn't require a PROJECT_CONTEXT.md contract to exist. Review-only rejects claude-writer:<account-alias> at PRE-FLIGHT because that mode has no writer role. For the accepted non-Codex backends, “authorizes no edits” is not an absolute sandbox guarantee; follow the mutation-detection and prompt-only/tool-list caveats in backend-selection.md.

The authoritative ready-to-paste default prompt is the goal-templates.md single-message mode. Use it verbatim rather than copying a shortened duplicate from this README. It includes the terminal-archival requirement, mandatory Current-state sentinel/count/order and forbidden-heading stop, QUALITY GATE and elevated-assurance escalation clauses, anti-loop cutoff, and environmental preconditions. Keeping the copyable prompt in one reference prevents these safety clauses from drifting independently.

Prefer to review the contract before Codex is authorized to write anything? Use the two-message mode instead — send a prepare-only request, review the SPEC node's contract, then lock in the /goal. Full text for both messages is in goal-templates.md, "Two-message mode".

More templates (with tests, without tests, refactor-only, review-only, elevated-assurance variants) are all in skills/graph-engineer/references/goal-templates.md.

Elevated assurance (optional)

Standard single-thread CRITIQUE (used everywhere above) is the default for every mode. Elevated assurance is an opt-in variant of node 4: instead of the default codex path's one Codex critique thread, 3 independent fresh-thread lenses (correctness/contracts, integration/state/reproducibility, security/abuse/data-loss) review the implementation in parallel, Claude fans in and normalizes their findings, and a fresh "exit challenger" pass reviews the final artifact cold before VERIFY. It never activates by default or silently — only on explicit request or after you confirm a matched risk trigger (auth/crypto/payments/migrations, irreversible operations, concurrency, public contract changes, a large diff, or a skipped QUALITY GATE).

The diagram and Codex-call counts below describe the default codex path. With a confirmed backend: claude or backend: claude-writer:<account-alias>, elevated assurance instead follows backend-selection.md: 3 parallel fresh Explore lenses and Claude's own canonicalization, with no separate canonicalization call, canonical thread, --resume-last, or Codex budget consumed. claude-writer:<account-alias> applies here only to the full 8-node write cycle and refactor-only, not review-only. The claude:<account-alias> backend cannot run elevated assurance.

flowchart TD
    QGpass["3 QUALITY GATE pass"] --> L1["Lens: correctness-contracts"]
    QGpass --> L2["Lens: integration-state-repro"]
    QGpass --> L3["Lens: security-abuse-data-loss"]
    L1 --> FANIN["Claude: fan-in / normalize<br/>(corroboration = metadata only)"]
    L2 --> FANIN
    L3 --> FANIN
    FANIN --> CANON["4 CRITIQUE: fresh canonicalization"]
    CANON --> DEBATE2{"5 DEBATE"}
    DEBATE2 -- valid --> REFACTOR2["6 REFACTOR"] --> QG2["3 QUALITY GATE"] --> RESUME["4 CRITIQUE --resume-last"]
    RESUME --> DEBATE2
    DEBATE2 -- "no findings" --> EXIT["4 CRITIQUE: fresh exit challenger"]
    EXIT --> DEBATE3{"5 DEBATE"}
    DEBATE3 -- valid --> REFACTOR3["6 REFACTOR"] --> QG3["3 QUALITY GATE"] --> EXIT
    DEBATE3 -- "no findings" --> VERIFY2["7 VERIFY"]

Loading

The 3 lenses run independently, in parallel, never seeing each other's output — Claude is the only place they converge. The exit challenger re-runs fresh — back to the top of that loop — every time its own findings go through REFACTOR, until one pass finds nothing against the artifact as it stands at that point. Only the last pass's "no valid findings" clears the gate into VERIFY (or DONE in refactor-only, which has no VERIFY node).

It costs more than standard CRITIQUE: a clean run of the full 8-node write cycle has 5 Codex review calls (3 lenses + canonicalization + exit challenger) — 6 Codex calls total, counting IMPL. Clean refactor-only has 5 total; clean review-only has 4 total (3 lenses + canonicalization) because it has neither IMPL nor an exit challenger. It also consumes Claude context during fan-in. For the risks that come with it — it is not independent verification, and the fan-in barrier has to be ordered correctly — see Limitations / Risks.

Full protocol (including why the fan-in barrier is not optional ceremony) and the ready-to-paste /goal templates:

• skills/graph-engineer/references/elevated-assurance.md
• skills/graph-engineer/references/goal-templates.md

Why

The role and cost claims below describe the default codex path. Opting into a Claude backend replaces those actors and carries the trade-offs disclosed in backend-selection.md.

1. Intended token and context savings. This split is designed to keep Claude's context focused on the contract, orchestration, and judgment while Codex carries the implementation-heavy work — not independently benchmarked yet. "Cheap" is relative, not free: repeated loops still accumulate findings and triage context. Nor does the design mean "Codex always implements only because it costs fewer Claude tokens": Codex is also routed to implementation because applying code is a role it performs well, independent of cost.
2. Less correlated self-review failure (intended). Reflection improves results, but a writer evaluating its own output can repeat the same blind spots; see Andrew Ng's Agentic Design Patterns — Reflection (that source backs the general reflection pattern, not a specific claim about same-model self-preference bias). Claude's DEBATE arbitration adds a different model to the decision path instead of letting Codex apply every self-critique automatically. This is meant to mitigate, not eliminate, the risk of correlated blind spots: IMPL and CRITIQUE still use the same underlying Codex model.
3. Specialization by role. Codex writes and mechanically repairs code; Codex's adversarial pass challenges it; Claude owns the contract, checks evidence, and arbitrates disputed findings. Each role gets a narrower, explicit responsibility instead of one model silently switching between author, reviewer, and judge.

Elevated assurance deliberately trades away part of point 1 for a specific gap in point 2: the single CRITIQUE thread's --resume-last continuity is good for triage memory but can anchor it to its own earlier framing of a REFACTOR'd fix. Closing that gap with extra fresh lenses and a cold exit challenger is worth it only when the risk of a missed finding outweighs the added cost, which is why it's risk-triggered rather than default.

How it works

This table describes the default codex path; the Claude substitutions are defined in backend-selection.md.

Graph role	Piece	Invocation
Orchestrator	User + Claude Code session	—
Loop driver	/goal <condition>	built-in; /goal clear to reset
Worker (implements)	subagent codex:codex-rescue	Agent tool, --write
Mechanical gate	project-local resolved command	local shell, cached per feature
Evaluator (critiques)	same subagent, read-only	Agent tool, no --write, adversarial prompt
Fixer	same subagent, resumed	Agent tool, --resume-last --write
Elevated lens sweep (opt-in)	3× same subagent, fresh, read-only	Agent tool ×3, no --write, --fresh --wait, in foreground
Elevated canonical critic (opt-in)	same subagent, fresh then resumed	Agent tool, --fresh --wait once, then --resume-last
Elevated exit challenger (opt-in)	same subagent, fresh, read-only, rerun until clean	Agent tool, no --write, --fresh --wait, gates VERIFY/DONE — reruns fresh after any REFACTOR it triggers

Every Codex interaction goes through the single codex:codex-rescue subagent — it's the only command in the plugin invocable directly by the model (/codex:review, /codex:adversarial-review, /codex:status, /codex:result, and /codex:cancel are typed-by-human-only). If you prefer to run a review by hand instead of through the cycle, you can still type /codex:adversarial-review yourself — it's just not what this skill automates.

Limitations / Risks

Caveats on the claims made above: several sections above call something "intended," "designed to," or "hypothetical" rather than stating it as proven — that's precision, not filler. Specifically: the worked example above is illustrative, not an executed transcript; the token/context savings in Why are unverified estimates, not a benchmark; and elevated assurance's 3 lenses give angle diversity, not independent verification (see below). The rest of this section is where the concrete risks and unverified claims live.

• Writer edits are destructive. The selected writer edits files directly; on the default codex path, Codex receives that authority through --write. Always run on a branch with a clean working tree, never on main with uncommitted changes.
• Codex's cost is separate from Claude's. This skill is designed to reduce Claude's context/token usage (not independently benchmarked, see Why); Codex calls are billed through your own OpenAI account.
• The overhead isn't in "calling a CLI binary." Source-inspected in the pinned openai-codex v1.0.6 plugin: the underlying process is spawn("codex", ["app-server"]) (scripts/lib/app-server.mjs) — a long-lived JSON-RPC server, not a fresh CLI exec per review. "review" is an internal job-class label used against that server, not a CLI argument. The real cost is one full Codex turn per Codex node (context, model reasoning) — IMPL, CRITIQUE, and REFACTOR, not all 8 nodes, since the other five run on Claude (see Choosing a mode) — multiplied across however many times the loop revisits them and, if elevated assurance is on, the extra lens/canonicalization/exit-challenger calls on top. That's where the expense actually is, not in process startup.
• A read-only Codex session may stay read-only when resumed. A session created without write access has been observed rejecting a later --resume-last --write attempt at the sandbox boundary. Recovery is to compare a before/after snapshot (untracked-file status, tracked diff, and content hashes — git diff --check alone doesn't prove nothing changed) and, only if they match, start a fresh, non-resumed Codex session with --write from the beginning instead of retrying the resume.
• Same-model review is not independent verification. On the default codex path, IMPL and CRITIQUE both use Codex, so they can share blind spots and self-preference bias. Claude's evidence-based DEBATE is a mitigation, not a proof of correctness. Claude backends have their own same-model limitation documented in backend-selection.md.
• Multi-model fan-out was considered and deliberately rejected. Having Claude, Codex, and other models each review independently and reconcile by majority vote sounds like it would buy more coverage. It was evaluated and rejected as the default mechanism: majority vote would discard a real security finding that only one reviewer happened to catch. Elevated assurance instead adopts angle diversity (3 lenses with different responsibilities) and explicitly rejects vote aggregation — cross-lens corroboration is recorded as metadata, never a fourth verdict. If you want true cross-model review, you can still drive it by hand outside this skill; it's just not what the automated cycle does.
• Idea considered and deferred: parallel independent multi-feature cycles. Today each graph-engineer cycle is scoped to exactly one feature: PROJECT_CONTEXT.md namespaces every feature under its own section, and SPEC requires a cycle to read and write only that section so contracts cannot contaminate one another. Useful parallelism already exists within that feature — elevated assurance runs 3 independent lenses concurrently and reconciles them through fan-in — but not across features. If a /goal names multiple genuinely independent features, the skill still runs one complete cycle at a time; it does not launch N concurrent sub-cycles, each internally ordered writer → reviewer → arbiter, and merge them into one final report. That design was evaluated and deliberately deferred rather than implemented speculatively: it needs a sound protocol for isolating concurrently active PROJECT_CONTEXT.md sections, a shared Codex call budget across sub-cycles, and final-report fan-in. Those choices should be driven by a real multi-feature use case. This is recorded as a deliberately deferred design idea, not a scheduled roadmap item.
• /goal is a per-turn stop-gate, not a scheduler. It keeps one turn alive until the condition is met; it doesn't survive closing the session. Some Claude Code environments offer /loop for unattended runs across turns (see the note in skills/graph-engineer/references/goal-templates.md; sources.md only confirms turn-level persistence, not that it survives closing the session) — this is the highest-risk way to run this skill, since it authorizes unattended --write cycles with no human reviewing the contract or the findings as they happen. This project has not independently benchmarked or stress-tested /loop specifically for this use case.
• The skill creates or updates PROJECT_CONTEXT.md in the target repository. It's a real, persistent file in your repo, namespaced per feature. It remains active context during the cycle; after a successful checkpoint-authorized write cycle, terminal archival atomically moves the full feature section to PROJECT_CONTEXT.archive/ and leaves its verified pointer in PROJECT_CONTEXT.md. If that transition cannot complete safely, the cycle escalates instead of claiming success. Review both the pointer and archive before wrapping up the work.
• A checkpoint commit is not an approval. See Checkpointing above. Claude tags every one Cycle-State: CHECKPOINT, never COMPLETE, precisely because passing QUALITY GATE only proves lint/type/build passed, not that CRITIQUE or VERIFY signed off — a real run once tagged an intermediate round COMPLETE and needed five more REFACTOR rounds after it.
• Elevated assurance is not independent verification. On the default codex path, its 3 lenses share the same underlying Codex model as standard CRITIQUE, so what they add is angle diversity plus reduced single-thread anchoring — not a second opinion from a different model. A clean elevated run of the full 8-node write cycle costs 5 review calls (3 lenses + canonicalization + exit challenger) — 6 total counting IMPL; clean elevated refactor-only costs 5 total, and clean elevated review-only costs 4 total. Those are elevated figures only; the standard floors are in Choosing a mode. That extra cost (detailed under Elevated assurance) would undercut the token-savings motivation in Why if it were ever treated as a default instead of a risk-triggered exception, which is why it isn't one. On that path, getting the fan-in barrier ordering wrong can misdirect --resume-last to a stray lens thread instead of the intended canonical one — see elevated-assurance.md for why that barrier exists and is not optional. backend: claude and backend: claude-writer:<account-alias> have neither those Codex-call floors nor that --resume-last risk; their distinct limitations are documented in backend-selection.md. Elevated assurance must never activate without your explicit authorization on any compatible backend.
• Running the reviewer headless can look hung instead of failed. User-reported, not verified by this project: if the target isn't a git repo, or the review process is run with stdin attached to a terminal, the Codex call may sit waiting on input instead of failing fast — reported fixes are closing stdin (< /dev/null) and passing --skip-git-repo-check when the target genuinely isn't a repo. Worth trying if a cycle appears stuck rather than erroring out.

Feedback / bug reports

Open an issue at github.com/Ranteck/graph-engineer/issues. Please include: your Claude Code version, the openai-codex plugin version, the ecosystem/language of the target repo, the QUALITY GATE command that got resolved (from PROJECT_CONTEXT.md), and sanitized output — this skill has not been dogfooded across ecosystems yet, so real-world reports are the fastest way to close that gap.

License

MIT — see LICENSE.