Graph Engineering
Model the work itself as a graph. Keep the domain knowledge graph, database graph, or dependency data separate from this orchestration graph.
Read references/graph-contract.md before defining or changing a graph specification. It contains both the stable unconditional v1 contract and the evidence-gated v2 conditional-routing contract. Read references/adapters.md when migrating an existing workflow or introducing a domain adapter.
Evolve the graph without bypassing it
Read references/evolution.md before importing a method from another skill, promoting an incident fix into the generic layer, or changing the graph contract. Treat external systems as evidence sources for graph evolution, not as authorities that can bypass the current validator, domain adapter, or root gate.
- Pin the evidence source and state its permitted and excluded access.
- Contrast matched contexts and express every candidate as condition, action, recovery, and verification.
- Admit the candidate as
General,Scoped, orExclude; place onlyGeneralrules in the core and routeScopedrules to an adapter or example. - Validate the change set with
scripts/validate_graph_change.py <change-set.json>before compilation. - Re-run graph validation, domain audits, compatibility tests, and rollback checks after compilation.
Use examples/skillalchemy-change-set.json as the bridge-format example. The example records the upstream version; it is not permission to execute or install upstream code.
Discover before redesigning
Identify the current entry point, commands, authoritative inputs, generated outputs, mutation boundaries, completion markers, audit reports, retry behavior, and recovery checkpoints. Preserve existing domain invariants until an explicit change is justified.
Draw the current execution graph before proposing a target graph. A node is a unit of work with one accountable role and declared read/write sets. An edge is a typed dependency and a deliberately limited handoff packet, not a vague statement that two steps are related.
Define the graph contract
Give every node a stable ID, kind, role, command or virtual-gate marker, read set, and write set. Give every edge a source, target, packet type, allowed fields, and any independence requirement. Designate exactly one virtual root gate owned by root_controller.
Use a directed acyclic graph for one execution pass. Represent iteration as an explicit feedback edge with a condition and finite max_iterations; never hide an unbounded retry inside a node. Make terminal outcomes typed and auditable, including bounded negative results when the domain permits them.
Use graph-engineering/v1 for fixed dependency graphs. Use graph-engineering/v2 only when an ordinary branch genuinely depends on a declared packet value; express the predicate structurally, declare accepted source statuses, and set an explicit join policy wherever multiple edges enter one node. Validate v2 selected-path evidence with scripts/validate_workflow_graph.py <spec.json> --run <run.json>.
Run scripts/validate_workflow_graph.py <spec.json> after editing any graph. Treat overlapping writes in one potential parallel wave, unreachable nodes, cycles, missing contracts, or fake independence as design errors. Conditional exclusivity does not by itself prove that overlapping writes are safe.
Separate orchestration from domain judgment
The generic layer owns topology, dependency scheduling, typed packets, write-conflict checks, checkpoint identity, failure propagation, and root-gate arbitration. A domain adapter owns commands, evidence standards, semantic validation, terminal states, and external-action permissions.
Do not replace a repository's authoritative importer, validator, or evidence rules with generic graph machinery. Wrap the existing implementation at stable seams and migrate one phase at a time.
Preserve real role boundaries
A role label is not evidence of independence. Use separate agents, processes, reviewers, or independently produced artifacts when the workflow actually requires independent judgment and the task authorizes that execution model. Otherwise run the graph with isolated packets and report that actor-level independence was not established.
Only pass fields declared on the incoming edge. Validators should consume persisted artifacts or bounded packets, not the builder's hidden reasoning. The root controller receives results, resolves conflicts, and decides whether the completion marker may be published; it does not silently rewrite specialist evidence.
Execute and close the loop
Schedule topological waves. Parallelize only nodes in the same wave whose declared writes do not overlap and whose runtime behavior is safe. Stop the graph on a failed hard gate and preserve its last successful checkpoint.
For every run, record the graph ID and version, node outcomes, artifact identities or hashes, failed checks, feedback decisions, and the terminal outcome. Completion means the root gate has verified the domain adapter's acceptance contract, not merely that all commands exited.
When refactoring an existing workflow, prove equivalence with focused tests and before/after hashes for protected products. Keep a rollback path until the new graph runner has passed the same domain audits as the former sequence.
