graph-engineer

Files (17)

• SKILL.md
• evals.json · evals/
• BAR.md · evals/gauntlet/
• CRITIC.md · evals/gauntlet/
• ROUNDS.md · evals/gauntlet/
• AGENT.md · fixtures/linear-chain/
• README.md · fixtures/linear-chain/
• README.md · fixtures/smelly-workflow/
• workflow.js · fixtures/smelly-workflow/
• anti-patterns.md · references/
• contracts.md · references/
• cost-model.md · references/
• cycles.md · references/
• report-template.md · references/
• topologies.md · references/
• verification.md · references/
• graph-lint.mjs · scripts/

SKILL.md (first lines)

# Graph Engineer

A linear agent is a graph already — the worst one: a single chain where
every step waits for the last, one context holds everything, and one stall
kills the run. Graph-engineering is redrawing it: cut the arrows that carry
no data, fan out what is independent, merge only where the whole set is
needed, put a verifier on the edge a wrong answer would cross, and let the
orchestration be code so it runs the same way every time.

This skill produces **one artifact** — a graph review: diagram first, the
node and edge tables, every barrier justified, the cost estimate, and the
script — and, when asked, the script itself in the place the user names. It
designs and reviews; it never launches a workflow on its own.

```mermaid
flowchart LR
  A["inventory<br/>every 'and then' · what crosses"] --> B["contracts<br/>node shape · edge shape"]
  B --> C["topology<br/>chain · fan-out · pipeline · diamond · route · cycle"]
  C --> D["confidence<br/>verifiers · isolation · convergence"]
  D --> E["tier + cost<br/>model per node · agents · critical path"]
  E --> F["script + lint<br/>graph-lint.mjs → rows"]
  F --> G["review<br/>diagram · tables · script · do-next"]
  G -. only when the user opts in .-> H["run<br/>Workflow tool"]
```

## The guard-rail

- **Write nothing into the target repo unasked.** The review and the script
  go to the scratchpad. If the user wants the script kept (`.claude/workflows/`
  is the usual home), they name the path and you write exactly that file.
- **Never launch the graph yourself.** The Workflow tool runs only on the
  user's explicit opt-in ("run it", "use a workflow", `ultracode`). Hand back
  the script and say how to run it; running is their call.
- **No subagents to design a graph.** One context, one pass. Designing a
  fan-out by fanning out is the joke the economist already told.
- **Read bounded.** The linear agent's prompt/script fully; anything it reads
  (a backlog, a log) by header and size only.
- **Every number is derived or labelled an estimate.** Agent counts come from
  the script; latency and tokens are estimates from the topology, stated as
  such, with the formula.
- **Leave a receipt** in the footer: what was read, lint rows found and
  closed, nothing written into the repo.

## Load only what the job needs

The references are ~9.5k tokens together; no job needs all of them. Read the
ones in the job's row, plus any a lint row points to — not the rest.

| job | read | skip |
|---|---|---|
| **quick question** — "parallel() or pipeline()?", "where does the verifier go?" | the one reference that answers it | the review; answer in chat in a few lines |
| **design from a chain** | `topologies`, `contracts`, `cost-model`, `report-template`; `verification` if a step checks work | `cycles`, `anti-patterns` |
| **review a script** | `anti-patterns`, `report-template` | the others until a row needs one: G6 → `topologies`, G7 → `contracts`, G8/G9 → `cycles` |
| **cycle of unknown size** | `cycles`, `verification`, `cost-model`, `report-template` | `contracts`, `anti-patterns` |

A quick question gets an answer, not a review: no artifact, no script, no
receipt — offer the full review in one line if the question hides a design
problem.

## Workflow

### 1. Inventory the chain

Take the thing as it is — a prompt with "then" in it, a script, a skill, a
Workflow script — and list every step in order. For each arrow between two
steps answer one question: **which variable crosses it?** Name the value that
leaves one step's output and enters the next step's input. If none does,
write `none`.

An arrow with `none` is not an edge; it is the order someone typed. Cut it.
What is left is usually two or three independent nodes feeding one that
needs all of them — the diamond, hiding inside the chain.

For an existing Workflow script, run the lint first:

```bash
node <skill-dir>/scripts/graph-lint.mjs <script.js> > <scratchpad>/graph-lint.json
```

It returns the shape (agent, parallel, pipeline, loop and phase counts, the
static fan-out widths) and one row per mechanical finding — `G` ids from
`references/anti-patterns.md`. Rows are evidence; the review adds the
judgement the lint cannot make.

### 2. Give every node and edge a contract

`references/contracts.md`. A node is one agent, one bounded job, explicit
input in, validated output out — a JSON schema on the `agent()` call, so the
next node consumes a shape rather than parses prose. An edge is the shape
that crosses it, named by its data, not its order.

Then the rule that saves the most tokens in any graph: **agents for
judgement, code for plumbing.** Flatten, dedupe, filter, group, count —
these are the edge, and the edge is plain JavaScript at zero tokens. An
`agent()` whose prompt begins "combine these" is paying rent on wiring.

### 3. Choose the topology

`references/topologies.md` — the six shapes, when each is right, what each
costs. Default to `pipeline()`: every item flows through every stage on its
own, no barrier. A barrier (`parallel()`, or awaiting a whole set before the
next stage) is earned only when a stage needs **every** prior result at once
— a cross-set dedupe, an early exit on the total, a prompt that compares one
finding against the others. "The stages feel separate" and "it's cleaner"
are not reasons; separate is not synchronised.

Routing is a schema-validated classification followed by an `if` in code.
The judgement is the agent's; the branch taken is the script's, and it takes
the same branch for the same classification every time.

### 4. Buy confidence where a wrong answer costs

`references/verification.md`. A verifier is a node whose only job is to kill
the finding before it crosses the edge: N skeptics prompted to refute
(adversarial), one lens each — correctness, security, does it reproduce
(perspective-diverse), or N attempts scored by judges (judge panel). Pick by
how a finding can be wrong. A verifier that produced the finding is not one.

`references/cycles.md` for discovery of unknown size: loop until K

From Busy-Office/ai-skills, MIT.

More from Busy-Office/ai-skills