Show and Tell: ORCH — a runtime that implements several 12-factor agent principles in practice

[oxgeneral]

Hey 12-factor-agents community 👋

This project has been really useful framing for my work. I've been building ORCH — a TypeScript CLI runtime for coordinating multi-agent teams — and found myself naturally converging on several of the same principles.

How ORCH maps to the 12 factors:

Factor: Own your control flow — ORCH's state machine (todo → in_progress → review → done) makes control flow explicit and inspectable. Every state transition is logged; no task is "done" without a review gate. The orchestrator code is deterministic TypeScript, not prompt-driven.

Factor: Pause and get confirmation — the review state is literally a structured pause point. Before any task transitions to done, a reviewer agent (or human) must explicitly approve it. This is enforced by the state machine, not by convention.

Factor: Compact errors — when an agent fails, ORCH captures the last 30 lines of the event stream (tail read, not full load) and transitions to retrying. The error context is preserved and visible in the TUI without loading the full 100K+ event log.

Factor: Stateless (where possible) — all state lives in .orchestry/ YAML/JSON files. The orchestrator is a process that reads and writes this state; agents themselves are stateless processes.

The piece I'm still figuring out: where should agent-level memory fit in a 12-factor architecture? Right now I use a shared context store (orch context set), but it's more like environment config than true episodic memory.

Question: Which factors from this list have you found hardest to implement in production systems? Pause/confirm patterns and compact error handling seem underappreciated to me.

GitHub: https://github.com/oxgeneral/ORCH — would genuinely value feedback on alignment with the 12 factors.