Developer tools · AI workflow safety

Engineering OS

A deterministic Python kernel for coordinating AI-assisted engineering through scoped authority, work-state transitions, evidence requirements, readiness planning and GitHub-native recovery.

PythonGitHub APIPolicy engineState machinesJSON contractsTests

The problem

AI workers are fast enough that coordination itself becomes a software problem.

As the number of repositories and parallel AI sessions grew, chat memory, branch names and “looks green to me” were not strong enough guarantees for consequential work.

Engineering OS moves the important questions into explicit contracts: who has authority, what state the work is in, which evidence is required, what dependencies are unresolved, and whether a transition or closeout is actually legal.

Kernel flow

Evidence enters. Deterministic decisions come out.

INPUTGitHub work + evidence
→
POLICYAuthority / risk
→
STATELifecycle / DoD
→
PLANNINGReadiness / dispatch
→
OUTPUTDecision + receipt

Capability is deliberately not treated as authority: possessing a tool or token does not grant permission to use it.

Implemented mechanisms

Policy that can be tested, not merely remembered.

01

Kernel

Authority & risk

A deterministic evaluator resolves scoped authority, computes risk floors and fails closed on stale, contradictory or insufficient evidence.

02

Kernel

Golden Path lifecycle

State transitions, evidence requirements, Definitions of Done and terminal closeout are executable rules rather than prose conventions.

03

Kernel

Readiness & dispatch

Dependencies, collisions, accepted base, capacity and capabilities are evaluated before work is considered dispatchable.

04

Kernel

GitHub-native controller

The controller recovers durable work state from GitHub, runs the kernel, detects drift and can plan bounded idempotent updates without a shadow source of truth.

Fail-closed examples

The system is designed to stop when evidence is not good enough.

stale authoritycontradictory authorityscope expansionmissing dependency evidencestale accepted headdestructive / irreversible worksecret or privilege expansionproduction green-light

Several controller repairs were driven by recovery/security edge cases in live GitHub work—useful evidence that the policy layer is being tested against real failure modes rather than only happy-path fixtures.

Professional signal

Developer tooling at the boundary between AI agents and real engineering state.

This project demonstrates Python, schema/contracts, state-machine design, policy evaluation, GitHub integration, adversarial testing and a practical approach to making AI-assisted development reproducible.

It should not be read as enterprise management experience or external organizational adoption. Its transferable value is the software mechanism: turning fuzzy workflow rules into deterministic, testable gates and receipts.

Selected work

See the products and systems this tooling helps keep recoverable.

Back to all work