“Which rule applied?”
The instruction file says everything. The agent followed some of it. Nobody can say which rule shaped this change.
graph engineering: Graphs your agents run.
Graph engineering is how you design work in ConvOps: a graph of small workflows behind one door, which your agent walks one step at a time. The knowledge grows. The prompt does not.
one router · detours · fix loops · fragments · child tasks
workspace routerexample workspace
new work1/4
One door
Add SSO to the admin appinitiative · needs a plan
next item
Feature deliverya larger initiativefeature
idle
Developmentcode change + MRdevelopment
idle
Simple tasksmall, known patternquick
idle
Ops taskinfrastructureops
idle
invokefeature-deliveryreturns to the router
Plan
Approve planapproval
Child tasks
Review
Done
AGENTS.md
8 lines · stays 8
knowledge · grows
in short
What is graph engineering in ConvOps?
Designing the process as a graph of small workflows behind one router, which your agent walks one step at a time, instead of one giant prompt.
ConvOps is the operations layer for AI agents: an MCP server that holds your team's process as workflows, with approval gates, a shared memory and an audit trail. It runs no AI models.
key facts · october 2026
- Others use "graph engineering" for multi-agent topologies. In ConvOps it means designing the process as small workflows a single agent walks one step at a time.
- Every new task enters through one router workflow, which sends it to the workflow that owns that kind of work.
- Decisions detour into sub-workflows and come back; there is no goto. Loops go back to an earlier step, for example fix and re-test.
- Fragments are shared blocks written once and embedded in every workflow that needs them, so one edit reaches all of them.
- Parallel work is a set of child tasks that share an order; the parent waits until every child is done.
best for
- Teams whose CLAUDE.md or AGENTS.md keeps growing and gets skimmed.
- Processes with exceptions, reviews and fix loops that one linear checklist cannot hold.
- Engineering leads who want to change one rule in one place and have every run pick it up.
not for
- Wiring several agents into a conversation topology in code. That is what agent frameworks such as LangGraph do.
- Drawing graphs on a canvas. You change the graph in conversation.
updated
the problem
The rulebook grows. The agent skims.
Every lesson becomes another paragraph in CLAUDE.md or AGENTS.md. The file grows, the agent reads less of it, and the process lives in prose.
“Why does it keep growing?”
Every incident adds a paragraph. The file gets longer, the agent skims more, and the next incident adds another.
“Where is the process?”
In prose. Steps, checks and exceptions mixed into one page that nobody can run, test or review.
the difference
A rulebook vs eight lines.
The instruction file keeps who the agent is and one rule: follow the workflow. The process moves into workflows. The rules move into standards, read at the step that needs them.
lines 1 to 386 above+1 rule
- 393## Git
- 394- Always run the tests before pushing.
- 395- Never push to main. Except hotfixes, see below.
- 396- Squash commits unless the reviewer asks.
- 397## Billing
- 398- Never touch billing without a second review.
file398 lines
readskimmed
one door
Every new task enters one door.
Mark one workflow as the workspace router. New work starts on it. The agent triages, picks one of the exits and records why.
new work1/6
- initiativeAdd SSO to the admin app
- bugRefund rounds the wrong way
- ideaDark mode for reports?
- taskFix a typo on pricing
- bugCheckout fails on retry
- taskRotate staging certificate
one door1/4
Workspace router
Add SSO to the admin apprule matched: type is initiative
next item
Feature deliverya larger initiativefeature
idle
Developmentcode change + MRdevelopment
idle
Simple tasksmall, known patternquick
idle
Ops taskinfrastructureops
idle
router workflow · example
- Triageconfirm the kind of work
- Routefour exits
- Sub-workflowruns, then returns
- Capture learningsworkspace-wide
- Completeworkspace-wide
recorded waiting for the route decision
- One router per workspaceOwners and admins mark one workflow as the door.
- Every new task starts thereTasks, bugs, initiatives and plans. Phases, goals, ideas and scheduled work keep their own rules.
- An explicit choice winsName a workflow when you create the work and it skips the door.
- No router? Rules matchWithout one, rules match on type, area, tags and project.
decisions
Decisions detour, then come back.
An exit can invoke a sub-workflow on the same task. The parent waits, then carries on. An exit without one just records the choice.
example · parent and sub-workflow, same taskexit invokes a sub-workflow
parent · routerwaiting
sub-workflowdevelopment-mrsame task · level 2
TriageTriageRouteRouteCapture learningsCaptureCompleteDoneBuildBuildVerifyVerifyReviewReviewMergeMerge- An exit can invoke a sub-workflow.It runs on the same task. The parent waits, then carries on from the next step.
- An exit without one records the choice.The run carries on. The record says which exit and why.
- Detours nest up to five levels.
- No jump to an arbitrary step.By design. Every detour returns, so the graph stays readable.
fix loops
Fail, fix, go round again.
A failed review invokes a fix and returns to Verify. A person who rejects at an approval sends the run back to the step the workflow names.
example · development-mrround 1
BuildVerifyReviewApprovea personCompleteFixsub-workflowresume_at: verifyon_rejected: build
run record
- round 1 · build
The loop ends when the work passes. Every turn is saved, so any session picks the run up where it stopped.
fragments
Write it once. Embed it everywhere.
Shared blocks like finding the standards, build and verify, and review live in fragments. Edit one, and every workflow that embeds it changes.
one fragment, edited once
build-and-verify
Developmentworkflow
Simple taskworkflow
Ops taskworkflow
find-standards
- List files in scope
- Find the standards
- Hand them on
embedded infeature-deliverydevelopment-mrops-task
build-and-verifyedited once
- Build
- Lint+ new
- Verify
embedded indevelopment-mrsimple-taskops-task
review
- Review
- Fix or pass
embedded infeature-deliverydevelopment-mr
workspace-wide
- Capture learnings
- Complete
Added to every workflow automatically. Nobody copies them in.
child tasks
Workflows start workflows.
A parent splits into child tasks, each with its own workflow. Children that share an order start together. The next order starts on its own. The parent waits for all.
parent · initiative · feature-deliveryworking
Add SSO to the admin app
- Plan
- Run the child taskssequential_children
- Review
- Done
order 1waits its turn
SSO data modelqueued
development-mrnot started
Login screen designqueued
design-reviewnot started
order 2waits its turn
Wire the login flowqueued
development-mrnot started
order 3waits its turn
Admin docsqueued
simple-tasknot started
Release notesqueued
simple-tasknot started
at the step
The right agent, the right rules.
Each step names the agent your orchestrator should use, and can name where it runs. It finds the standards for the files in scope. The agent gets one step.
parts
- design-revieweragent
- isolated-sonnetexecutor
- app/components/*files in scope
- frontend/components.mdstandard
- accessibility.mdstandard
- this step onlyinstructions
one step, assembledReview the UI change
draft- agentdesign-reviewer
- executorisolated-sonnet
- files in scopeapp/components/*
- standardfrontend/components.md
- standardaccessibility.md
- instructionsthis step only
- standards found for the files in scope
- agent named for your orchestrator
- executor resolved
- one step handed over
- The step names the agent.A standards scout, a design reviewer. Your orchestrator starts the one the step names.
- The rules arrive at the step.The step finds the standards for the files in scope and passes them on. Nothing else.
- Never the whole graph.The agent sees one step. The engine holds the rest and saves every step, so any session resumes.
built by talking
Change the graph in conversation.
Ask your AI client for the change. It edits the one step that needs it. No canvas, no code. Runs already in flight keep going.
Ask for the change you want.
- 1Find standardsfragment
- 2Buildfragment
- 3Verifyfragment
- 4Mergeapproval
runs in flight
Refund rounds the wrong wayat Merge · keeps going
Retry banner copyat Build · keeps going
the primitives
Eight pieces build every graph.
Router
One door per workspace. New work starts there and leaves by one exit.
is_router
Decision
Picks an exit and records why. A rule can match a task field instead.
decision · conditions
Sub-workflow
A detour on the same task. The parent waits, then carries on. Up to five levels deep.
invoke
Loop
Failed work returns to an earlier step and comes round again until it passes.
resume_at · on_rejected
Fragment
Shared steps written once and embedded everywhere. Edit once, every workflow changes.
embed
Gate
The engine checks it. The run does not move until the condition is met or a person approves.
requires_approval
Child tasks
A parent splits into tasks with their own workflows. Same order starts together.
sequential_children
Standards at the step
Rules live in files, found for the files in scope, read when the step needs them.
standards/
for engineers
The graph, as the engine stores it.
Every picture above is a few fields on a step. Here they are as the engine reads them.
The router decision
Four conditions, each invoking a sub-workflow. The first matches a task field on its own; the others are picked by the agent, who records why.
payload
// router · step "route" (example)
{
"id": "route",
"name": "Route decision",
"decision": true,
"instructions": "Pick the exit that fits. Say why.",
"conditions": [
{ "id": "feature", "name": "Larger initiative",
"when": { "task_field": "type", "equals": "initiative" },
"invoke": "feature-delivery" },
{ "id": "development", "name": "A code change",
"invoke": "development-mr" },
{ "id": "quick", "name": "Small, known pattern",
"invoke": "simple-task" },
{ "id": "ops", "name": "Infrastructure",
"invoke": "ops-task" }
]
}A fix loop and a rejection
resume_at sends the return trip from the fix back to verify. on_rejected names where a person's rejection sends the run.
payload
// development-mr · review loop (example)
{
"id": "review",
"name": "Review",
"decision": true,
"conditions": [
{ "id": "needs-fixes", "name": "Needs fixes",
"invoke": "fix" },
{ "id": "passed", "name": "Passed" }
],
"resume_at": "verify"
},
{
"id": "merge",
"name": "Approve the merge",
"gate": { "requires_approval": true },
"on_rejected": "build"
}Fragments
An embed directive pulls a fragment's steps into the workflow. Edit the fragment and every workflow that embeds it changes.
payload
// development-mr · steps (example)
[
{ "embed": "fragment", "id": "find-standards" },
{ "embed": "fragment", "id": "build-and-verify" },
{ "id": "review", "decision": true, ... },
{ "id": "merge", "gate": { "requires_approval": true } }
]
// capture-learnings and complete are added
// to every workflow by the workspace globalsChild tasks
A sequential_children gate routes the parent into its children by order. Children that share an order start together. The parent advances when all are done.
payload
// feature-delivery · step "children" (example)
{
"id": "children",
"name": "Run the child tasks",
"gate": { "sequential_children": true }
}
// children, by order
// order 1 SSO data model development-mr
// order 1 Login screen design design-review
// order 2 Wire the login flow development-mr
// order 3 Docs simple-taskMark the router
One call marks a workflow as the workspace router. It needs a workspace owner or admin and is checked before anything is saved.
payload
workflow_template_meta_update({
"template_id": "router",
"changes": { "is_router": true }
})
// owners and admins only
// every new task, bug, initiative and plan
// in this workspace now starts on "router"questions
What engineering leads ask.
What is graph engineering?
Designing how work gets done as a graph of small workflows instead of one giant prompt. One router takes every new task, decisions detour into sub-workflows and come back, loops send failed work round again, and shared fragments keep common steps in one place. Your agent walks the graph one step at a time.
How is this different from LangGraph or n8n?
Those are graphs that call APIs: you write code or wire nodes, and the framework calls models and services. Here ConvOps holds the graph and your AI session walks it. Claude Code, Codex, Cursor or any MCP client asks for the current step, does it and advances. Graphs your agents run, with no code to write.
Can a step jump to any other step?
No, by design. A decision either records a choice or detours into a sub-workflow that returns. A loop goes back to an earlier step the workflow names. Every path comes back to the line, so anyone can read the graph and know where a run can go.
What happens when a person rejects at an approval?
The run goes back to the step the workflow names for a rejection, often the build or the fix step, and comes round again. The run does not move past the approval until a person approves it.
Do I need a router?
No. Without one, rules match new work to a workflow by type, area, tags and project. A router gives every new task, bug, initiative and plan one door, where the agent triages it and records why it went where it went.
Can the AI change the workflow?
Yes, in conversation. Ask for a review loop after the build and the AI edits that one step. Runs already in flight keep going. Marking a workflow as the workspace router is reserved for owners and admins.
Is there a visual editor?
No canvas. You describe the change from the AI client you already use, and every run follows the stored workflow. The graph is the steps, decisions and links the engine evaluates.