Portable Agent Operating-Model

A lightweight introduction to reliable-agent principles — ingestible by any agent, at any stage, with no workspace install

Use arrow keys or the buttons below to navigate

What it is

A 12-file handoff package — pure markdown, no install
Distills the patterns we use for reliable AI agents
Reads as a primer, not a runtime — pure conceptual transfer
Public, free, fork-friendly — one entry doc; references go deep

An agent reads it and rebuilds the model in its own runtime.

How to use it

Two ways in — pick the one that fits where you are.

Read it yourself — get the conceptual model in 30 minutes; understand why each pattern exists and the failure mode it defends against.

Hand it to your agent — point at the public repo, say “emulate this setup as best you can within your environment.”

Runtime-neutral — works on Claude Code, Codex, Cursor, Aider, MCP-only, or any in-house harness; a translation table maps the primitives.

Six core principles

Ordered by impact — how much each shapes outcomes when applied vs. skipped. Everything else in the package operationalizes one of these.

DOE architecture — push deterministic work into code, not the LLM

File-first output — files are the canonical state, not conversation

Layered memory — memory has lifetimes; don’t flatten them

Quantized iteration — small units, durable state, fresh context each loop

Progressive disclosure — surface area is on-demand, not always-on

Self-annealing — treat errors as instruction-set updates

DOE

Directive · Orchestration · Execution

Directive

SOPs in markdown — the what and why

Orchestration

The agent — routes tools, handles errors

Execution

Python scripts — reproducible, testable

A 100-line Python function is 100% reproducible. A 100-line LLM prompt is not. Push compute into code; let the LLM route.

File-first output

Files are the canonical state, not conversation

Every decision, plan, intermediate result, and deliverable lives in a known location
Conversation context is volatile; the filesystem is durable — survives compaction, vendor switches, team handoffs
Structured directories with conventions: runtime/.tmp/, runtime/deliverables/, directives/, executions/
It’s the substrate that makes layered memory and progressive disclosure work

If it’s worth doing, it’s worth writing down. Conversation forgets; files don’t.

Layered memory

Lifetimes, not a flat blob

Long-term — identity, brand, conventions; version-controlled in repo

Mid-term — topic memories that survive across sessions and vendors

Near-term — current-state file: what’s in flight, decisions, blockers

Session — volatile working context; dies on compaction (and that’s fine)

Quantized iteration

Small units · durable state · fresh context each loop

Bound

Define one small, discrete unit of work

Execute + persist

Do it; write status to a durable file

Clear + resume

Fresh context; read the file; next unit

The MAKER finding plus Anthropic’s harness papers (and Huntley’s Ralph loop before them): “claimed done, actually broken” comes from compounding error in long contexts. Bound the unit, persist the state, reset the context — then iterate.

Progressive disclosure

Load only what you need

Every agent-consumable file carries standardized YAML frontmatter — summary, version, last_updated, and more
The agent maintains registry index files that aggregate those summaries
When the agent needs something, it scans the registry first, then loads only the file that matters
No “just-in-case” loading — context windows are finite

Pre-summarized agent-curated indexes beat search-every-time.

Self-annealing

Errors are instruction updates

When something breaks, fix it — then update the directive or skill so the next agent doesn’t repeat the failure
Every directive carries a version + last_updated; every fix bumps it
Errors are the system’s primary learning channel
A pristine directive that has never been corrected is a directive that has never been used

Single-instance failures become structural defenses.

What’s in the package

One entry doc, one rubric, ten reference files — plus copy-pasteable starter templates inside.

AGENT-OPERATING-MODEL.md — entry point; the why and the topic index
REVIEWER-RUBRIC.md — 10-dimension anchored 1-5 rubric for convergence reviews
references/00-primitive-translation.md — maps primitives across Claude Code, Codex, Cursor, Aider, MCP-only, in-house
references/01-09 — one deep-dive per principle plus skills, anti-rot, recipes, behavioral rules
12 starter templates — AGENTS.md, MEMORY.md, SKILL.md, feature_list.json, council rubric, loop-harness pseudocode, and more

Take it and run

Public, free, fork-friendly. Read AGENT-OPERATING-MODEL.md first — that’s the entry point.

View on GitHub

Pvragon/ai-workspace-reference → portable-agent-package/