Skip to content
Skills Library
AI & agents · Planning

graph-engineering

/graph-engineering

Use when a workflow has explicit data dependencies, independently executable branches, typed joins, or node-local recovery needs that justify a bounded static dependency graph.

Licence
MIT
Last repository change
21.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
5
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 21.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/validate_graph_contract.py

What it does and when to use it

Use when a workflow has explicit data dependencies, independently executable branches, typed joins, or node-local recovery needs that justify a bounded static dependency graph.

Original author description

Use when a workflow has explicit data dependencies, independently executable branches, typed joins, or node-local recovery needs that justify a bounded static dependency graph.

How it works

  1. Usage Template
  2. Workflow
  3. Failure Protocol
  4. Output Contract
  5. Edge Cases
  6. Success Metrics
  7. Quality Gates
Original SKILL.md headings · 151 lines, 886 words
SKILL.md preview
---
name: graph-engineering
description: Use when a workflow has explicit data dependencies, independently executable branches, typed joins, or node-local recovery needs that justify a bounded static dependency graph.
metadata:
  version: "8.1.0"
  updated: "2026-08-18"
  profile: "high-risk"
  assumes: "Nodes, payloads, writers, verifiers, budgets, and permission boundaries can be declared before execution."
  conflicts_with: "Dynamic or cyclic expansion, overlapping writers, whole-graph retries, hidden joins, or external effects without approval and compensation."
---

# Graph Engineering

<skill_contract>
  <input>A dependency-heavy objective with candidate nodes, data schemas, owners, effects, verifiers, joins, budgets, and durable state paths.</input>
  <output>A validated static DAG contract with typed edges, explicit joins, node-local recovery, and graph-level receipts.</output>
  <done>Static invariants and terminal acceptance checks pass with fresh node, join, budget, permission, and state evidence.</done>
  <non_goals>Temporal loop design, worker-team command, runtime-kernel implementation, dynamic graphs, or universal parallelism.</non_goals>

Use Graph Engineering for dependency width. Use `loop-engineering` for repeated
execution through time, `agent-teams-command` for process ownership and IPC,
and `harness-engineering` for scheduler, permission, lease, and observability
infrastructure. A graph node may contain a bounded Loop or Agent Team.

## Usage Template

Provide: objective/non-goals, candidate nodes, real data dependencies, payload
schemas, owners and write territories, join semantics, node/terminal verifiers,
effects and permissions, artifact/state paths, budgets, stop conditions, and
recovery. Load `references/graph-contract.md` for the full schema and boundary;
start from `references/diamond-graph-example.json`.

## Workflow

<intake>

Run the admission gate before drawing a graph:

1. Identify which steps actually consume another step's output.
2. Estimate independent width, critical path, scheduler overhead, and review
   load. Require measurable payback or stronger independent evaluation.
3. Keep one-shot or Loop execution when work is mainly sequential, small, or
   cheaper to review serially.
4. Limit V8.1 to a static DAG: sequence, pipeline, diamond, maker-checker, or
   bounded subgraph. Put repetition inside a `loop` node; reject graph cycles
   and dynamic expansion.

</intake>

<unknowns_gate>

Return `NEEDS_INPUT` when objective, graph owner, dependency direction, payload
schema, writer, verifier, permission boundary, budget, join, or recovery is
missing and cannot be discovered safely. Probe candidate independence with a
small dry run. Do not invent an edge merely because two steps are adjacent.

</unknowns_gate>

<execute>

1. Write the JSON contract and run
   `scripts/validate_graph_contract.py <contract.json> --strict`.
2. Give every node one owner, typed inputs/outputs, explicit reads/writes,
   verifier, timeout, attempt/tool caps, effect class, idempotency, and
   compensation.
3. Add only data, control, verification, failure, or compensation edges.
   Schema-bearing edges must match both endpoint contracts.
4. Enforce one writer per target. Agent workers use isolated artifacts or
   worktrees; the integration owner controls shared schemas and final writes.
5. Declare a join for every multi-input node. Choose `all`, `reduce`,
   `first-success`, `quorum`, `barrier-verifier`, or `human-gate`; name the
   exact input set and verifier.
6. Schedule only `READY` nodes whose dependencies are verified. Persist every
   transition and edge payload reference before releasing successors.
7. Retry the failed node or smallest invalid subgraph after a changed
   diagnosis. Preserve verified branches; never replay the whole graph merely
   for convenience.
8. Require human approval, a compensation route, and verified rollback before
   any external, shared, destructive, published, credentialed, or financial
   effect. In strict contracts, name the external node ID in
   `approval_required`, feed it a typed approval receipt directly from a
   `human-gate`, and list each exact write target as allowed and not denied.
9. At terminal nodes, verify the end-to-end objective and graph guardrails;
   node success alone cannot certify graph success.

</execute>

<evaluate>

Check static integrity: known endpoints, compatible schemas, reachability,
acyclicity, single writers, complete joins, finite budgets, and compensated
effects. Check runtime integrity: deterministic readiness, duplicate-delivery
idempotency, checkpoint replay, permission denial without mutation,
smallest-unit recovery, terminal evidence, and cleanup. Use an independent
reviewer for consequential graph behavior.

</evaluate>

<retry_policy>

`max_attempts` comes from each node and never exceeds the graph cap. Retry only
after changing diagnosis, input, owner, tool, or strategy. Stop on a repeated
signature, incompatible edge, permission denial, invalid checkpoint, exhausted
review budget, or `NO_PROGRESS`. Whole-graph retry is forbidden in strict V8.1.

</retry_policy>

<state_contract>

Persist `{run_id, graph_id, status, attempt, budget, evidence, unknowns,
last_error, next_action}` plus contract/implementation hashes, node states,
edge payload locators, join decisions, writer leases, approvals, checkpoints,
compensations, terminal receipts, and cleanup. Use append-only events and an
atomic current checkpoint; chat history is not graph state.

</state_contract>

## Failure Protocol

- `NEEDS_INPUT`: a mandatory graph contract or authority field is unresolved.
- `BLOCKED_DEPENDENCY`: keep affected nodes `WAITING`; run only independent
  ready nodes.
- `BLOCKED_PERMISSION`: deny the effect, preserve state, and request approval.
- `VERIFY_FAILED`: reject the node/join artifact and recover the smallest unit.
- `NO_PROGRESS`: the same failure repeats after a changed attempt.
  `max_attempts: 2` by default and always finite.
- `BUDGET_STOP`: stop scheduling, checkpoint, compensate active effects, and
  return a partial graph receipt.

## Output Contract

Return `status`, `result` (terminal decision and accepted artifacts), `evidence`
(validator, node, join, terminal, budget, approval, and cleanup receipts),
`unknowns`, and `next_action` (stop, retry node, compensate, approval, or
handoff).

## Edge Cases

- Two workers both write `report.md`: strict validation fails the single-writer
  invariant; isolate worker artifacts and let one reduce node own the report.
- A branch passes but its sibling times out: preserve the verified branch,
  retry only the failed node within cap, and do not release the join until its
  declared mode and verifier pass.

## Success Metrics

- The strict graph validator passes before execution.
- Graph admission shows bounded value beyond orchestration and review cost.
- Every node, edge, join, effect, and terminal claim has fresh evidence.
- Recovery replays the smallest failed unit from durable state.

## Quality Gates

- [ ] Static DAG scope and Loop/Teams/Harness boundaries are explicit.
- [ ] Owners, payload schemas, writers, joins, verifiers, and budgets are exact.
- [ ] State replay and duplicate delivery preserve graph invariants.
- [ ] External effects have independent review, approval, compensation, and rollback.
- [ ] Terminal verification supports the end-to-end claim.

</skill_contract>
Files in this package (5)
  • SKILL.md 7 KB
  • agents/openai.yaml 1 KB
  • references/diamond-graph-example.json 5 KB
  • references/graph-contract.md 4 KB
  • scripts/validate_graph_contract.py 23 KB

Versions

RepositoryScoreLicence
This page · Mark393295827/third-brain-v7-skills100MIT
codicovibes/devstack100MIT
citypaul/.dotfiles90MIT

Database snapshot: 13.11.2026 · package version 1d5a27fb6d37 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100engineering-workflow
    Use for harness engineering, verification loop design, task dependency graph planning, and multi-step work that needs explicit checks, bounded retries, independent review, or a handoff. Skip for simple questions and isolated edits unless explicitly invoked.
  • 100graph
    Graph engineering for parallel task execution: convert a task, PRD, SPEC, or issue set into a dependency graph (DAG), layer it into supersteps, then implement each independent node concurrently with subagents — each node runs /goal → /review-it → /ship-it in an isolated git…
  • 100agent-graph-designer
    Use this skill when the user asks to design an agent graph, graph a multi-agent workflow, connect agents or loops, parallelize specialist agents, define agent handoffs or joins, map conditional branches and approval gates, or decide whether a workflow needs a loop or graph. It…
  • 100design-workflow-graphs
    Design, transform, review, and evolve graph-based workflows with explicit state, nodes, edges, routing, concurrency, joins, loops, approvals, recovery, termination, side effects, and observability. Use when Codex needs to decide whether graph orchestration fits a process; turn…
  • 90routing-skill-graph
    Use when routing skill graph is required during kernel work, especially when the result must be traceable, independently reviewable, and safe to hand to another agent.
  • 90graph-running
    Use when the user has approved a work graph designed with the graph-engineering skill and wants it carried out, or when a command says to run an approved graph. Covers saving the graph as a file trail, running lanes at the execution level the graph recommends (by hand, one job…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.