A worked reference, not a framework

An agent you can hand work to.

A reference implementation of agent-ready knowledge architecture: the roles, routines, hooks, memory, and task coordination that make working knowledge legible to AI agents, and turn a coding agent into a system you can trust to make progress while you're away.

One person's actual setup, redacted and published with the reasoning attached. The example runs in Claude Code, but the architecture ports to any agent runtime. This page is the five-minute tour; the docs hold the depth.

The shape

Five layers, top to bottom

From how you talk to it down to the agents that do the work. Select a layer to see what it holds and why it's there.

The pieces

The modules

Each is a cohesive cluster with one upgrade boundary. Tap one.

The thinking

Thirteen load-bearing patterns

If you read one thing, read these — each as problem, pattern, why it beats the obvious alternative, and what it costs. Expand any card.

01Pure roles, composed with project factsRun security review across five projects and you get five near-identical 500-line prompts that drift apart the moment one is edited.
Pattern
Keep the expert persona pure: method, constraints, and red flags, with zero entity facts. Project specifics live in a CONTEXT.md. A thin binding composes the two at invocation.
Why it beats the obvious
A fix to the auditor's method reaches every project at once, and a new project gets an expert reviewer by writing one CONTEXT.md instead of cloning a prompt that immediately starts to rot.
Cost
Indirection (two files, not one) plus a validator. Worth it past about three projects; overkill for one.
02Classify-then-act, not ask-then-waitAn autonomous background agent has two failure modes: it nags for input on everything, or it acts confidently on tasks it doesn't understand.
Pattern
Classify every task first — has-default, needs-intent, or out-of-scope. Build the has-default work in a sandbox, lodge it for review, act only on approval, and log every rejection.
Why it beats the obvious
A pure question-queue stalls on the user; a pure autonomous loop ships things you didn't want. Classification routes each task to safe handling, and the rejection log stops the same bad idea returning.
Cost
A sandbox, a review queue, and a rejection history to maintain. Some speculative work gets discarded.
03Make silent failure loudA scheduled task that stops firing fails silently. You find out weeks later, when the thing it produced is missing.
Pattern
Each task emits a success sentinel to its log. A watchdog scans for that sentinel inside a staleness window and raises a finding when it's missing or stale. Self-hosted, no external service.
Why it beats the obvious
“I'll notice if it breaks” is false — the whole point of a background task is that nobody is watching it. A sentinel converts absence-of-success into a visible, dated finding.
Cost
Per-task staleness configuration, plus a tolerance flag for tasks that run on demand rather than on a clock.
04Tier by mechanical impact, not by toneA system that auto-applies its own findings needs a line between apply-automatically and ask-first. Drawing it from how confident a finding sounds is a trap.
Pattern
Classify each change by mechanical reversibility. A typo fix and a deleted file sit in different tiers regardless of wording. Trivially reversible changes auto-apply; anything that deletes, publishes, or spends money gets a human gate.
Why it beats the obvious
Tone-based heuristics are gameable and drift over time. Mechanical impact is a property of the action itself, not the language describing it.
Cost
An explicit impact table, kept current as new action types appear.
05Memory points, it doesn't mirrorAgent memory that copies your source documents goes stale the moment a source changes, then quietly contradicts it.
Pattern
Memory holds an index plus typed notes that point at the source of truth instead of duplicating it. Every write is one of four operations — add, update, delete, no-op — never a blind append.
Why it beats the obvious
Dumping everything into memory feels safe and rots fast. A pointer cannot contradict its source; a copy eventually always does.
Cost
Discipline at write time, plus a periodic consolidation pass to merge duplicates and prune the index.
06Credentials live in one place, never in filesA secret written to a file leaks: into git history, into a backup, into an agent's context window, into a screenshot.
Pattern
A password manager is the single store. Files reference the item name, never the value. Running code resolves the secret at runtime and scrubs it. Allow one narrow, audited exception per genuine need, not a general waiver.
Why it beats the obvious
A .env file and “I'll just paste it for now” are how secrets end up in transcripts forever. One store with runtime resolution keeps the value off every durable surface.
Cost
A runtime lookup step, and the discipline to refuse the convenient shortcut.
07A cheap hook beats a careful agentAn agent that misread the task can overwrite a secrets file, delete a record, or force-push. “Be more careful” does not scale.
Pattern
A PreToolUse hook intercepts file writes and shell commands against a blocklist — sensitive paths, destructive verbs, pushes to protected branches — and blocks them before they run. It fails open, so a bug in the guard never wedges the session.
Why it beats the obvious
Trusting the model to never err is a hope, not a control. A ten-line deterministic check catches the large majority of accidental damage for almost nothing.
Cost
Occasional false positives, best resolved by naming around them rather than widening the gap.
08Audit the workspace like a fitness functionA workspace degrades while the ecosystem improves. Context bloats, configs drift, a hook stops firing, memory contradicts reality — and nobody's job is to notice either direction.
Pattern
A scheduled auditor with two jobs: find improvements (public-source research plus a module-by-module best-practice critique) and sweep configs, the security envelope, and drift, writing tiered findings. Canaries verify it still detects known-bad fixtures. Deliberately no single numeric score — a self-grading audit optimises for the grade.
Why it beats the obvious
“I'll clean it up when it bothers me” loses to a cadence with canaries, because drift is invisible right up until it isn't; “I'll look for upgrades when I have time” never fires at all.
Cost
The audit is itself a system to maintain, and it can cry wolf, so findings are tiered and tracked rather than dumped raw.
09Context is a budget, not a constantEverything auto-loaded into a session — instruction files, the memory index, skill descriptions, hook strings — costs tokens on every turn, forever. No single addition is large, so the total grows a few percent a week, and unattended agents spend with nobody watching.
Pattern
Meter it like money. A per-source baseline counter with history, a trend alarm against a rolling median (accretion is the common failure, not the blowout), hard spend ceilings on unattended runs, fan-outs bounded by construction, and a standing note on what must survive compaction.
Why it beats the obvious
A size warning on one instruction file watches one source and one absolute threshold. The real failure is distributed and relative, so per-source measurement with trend detection catches what a static ceiling misses.
Cost
A counter to maintain, estimates that drift from true tokenizer counts, and ceilings that need sizing judgment — a cap set as a governor instead of a belt aborts legitimately heavy runs.
10A skill is editable weights — never adopt a self-edit without a gateA CLAUDE.md or skill doc is plain text the agent can rewrite, and an agent watching its own transcripts can propose better wording every day. Let that loop close on itself and the system edits its own controlling instructions with nobody checking whether each edit helped.
Pattern
Treat instruction text as optimizable weights, and gate the path from proposal to live file. Here the gate is human: the heartbeat sandboxes a change and applies nothing until approval, memory consolidation runs add/update/delete/no-op instead of blind appends, and the file-protection hook blocks even an approved edit on an unwatched path. Stage, review, adopt.
Why it beats the obvious
Microsoft Research's SkillOpt (arXiv:2605.23904, MIT, v0.1.0 alpha) models a skill doc as a frozen model's trainable weights and accepts an edit only when a held-out split strictly improves. Their single-seed cautionary run: an ungated loop on a weak model with a degraded signal collapsed 0.554→0.026 (−52.8 pts) by learning to echo the document title verbatim, while the gated twin rejected every bad edit and stayed flat. Single-seed result, gains only where tasks recur with a checkable signal; the durable lesson is that a self-edit loop without an accept/reject check can optimize off a cliff. This workspace runs the human-gated cousin — no training gradient, no held-out gate, just the refusal to adopt an edit on its own say-so.
Cost
The gate is the slow part: instruction improvements land in days, not seconds, and a rejected edit's speculative work is discarded. That latency buys never waking to a controlling file an unsupervised loop quietly rewrote.
11A scaffold is a hypothesis — gate it behind a measurable signalThe tempting way to make an agent smarter is to keep adding to the layer around it: another skill, another always-loaded rule, another self-critique pass. Most of it feels like an upgrade and never gets checked. A second same-model pass over the same prompt does nothing and can degrade the answer, and every always-loaded line dilutes the signal of every other — so a workspace can get measurably dumber by growing.
Pattern
Treat the workspace as fixed weights and everything around it as the trainable part, then borrow the discipline that makes training honest: a held-out check. A change earns its place only when it adds a checkable external signal (a golden expectation, a deterministic lint, a test) or genuine divergence (a critic on a different rubric, attempts seeded from genuinely different strategies); more same-model compute is neither. Register every scaffold with a falsifiable hypothesis and a review date, measure with a golden-set reasoning-regression suite under a variance floor (a pass-rate plus-or-minus stddev, never a single number), and at the review date beat baseline or get cut.
Why it beats the obvious
The obvious move is to add the thing that sounds smart and trust it helped — exactly what a self-improving layer cannot afford, because the same plausibility that sells a good scaffold sells a useless one. A correctness signal scores the answer, not the story; a variance floor stops one lucky run posing as a gain; and removal is a first-class outcome, since an upgrade pass is wired to add and under-weights the cut that would help more.
Cost
A suite to build and maintain, with real cases whose answers are deterministically checkable, and a variance floor that multiplies every measurement by the re-run count. The register only works if it is actually consulted at the review date instead of becoming another stale list.
12Loop selection: not everything should be a loopHand someone a capable agent and the instinct is to automate everything — put a loop on every recurring task and remove yourself as the bottleneck. But most real work is judgment-heavy, irreversible, or unverifiable. Loop that work and you either delete the value (the judgment was the point) or ship damage unattended.
Pattern
A four-box test. A task earns an autonomous loop only when it is all of: recurring, mechanically verifiable (a script, exit code, or diff confirms it worked, not your taste), low-judgment-per-instance (the same decision every time), and headless-executable (it can actually run unattended — no interactive credential, no GUI, no human mid-step). An irreversibility override caps any outward or destructive act (email sent, comment posted, money moved, history pruned) at surface even when all four boxes pass. Three buckets fall out: LOOP (autonomous on a trigger, the verifier is the gate), SURFACE (recurring and verifiable but judgment-heavy or irreversible, so a read-only nudge or an approval-gated act, never silent autonomy), and KEEP MANUAL. The worked example here is a close-out routine that, when a task finishes, runs a read-only scan and surfaces what drifted — stale context docs, fired strategic triggers, stale backups, aging open questions — for the operator to action while still in context. It adds no autonomy; it widens the operator's view at the moment state changed.
Why it beats the obvious
The obvious move treats autonomy as a pure good and automates whatever can be automated. But a loop only pays where the work is verifiable and low-judgment; pointed at judgment work it removes the value or acts wrongly with nobody watching. This is the same route-by-consequence instinct as classify-then-act, tier-by-impact, the skill-as-weights gate, and the scaffold-as-hypothesis check: gate by consequence, not by how automatable a thing feels.
Cost
A selection pass before you build, and the restraint to leave high-value judgment work manual when looping it would feel productive. One sharp corollary: verify the target against the code before deciding it loops — does it exist on the right branch, does it do what its description claims, can it run headless — because a task can pass every quality box and still fail the headless one.
13Challenge half-formed ideas with a different lensEvery tool that critiques an agent's work assumes a finished artifact — a draft, a decision, a result. None help during the messy part, where you're exploring and nothing is built yet. The tempting fix, a second agent challenging every idea always-on, is the same model rationalizing its own frame, and unmeasurable once it runs on everything.
Pattern
A single divergent lens, not a debate: one challenge from a deliberately different frame — strongest objection, baked-in assumption, unconsidered option — grounded in a criterion or a retrieved fact, the human as arbiter. It widens options, never argues to a winner. Then hold a sample back: roll on each fork and skip the challenge ~1 in 3, logging both, and have the human tag each firing changed / considered / noise.
Why it beats the obvious
Same-model same-prompt debate loses to majority voting at equal compute, ungrounded self-critique often degrades, and assigned devil's advocacy is weaker than dissent that carries real information (decades of group-decision evidence). And an always-on aid is unmeasurable by construction: if it fires on everything, you never see the one without it. Holding out a sample is a control group for a behavioral aid.
Cost
A behavioral trigger that depends on the agent firing it (the log's fire count doubles as the adherence check), a held-out sample you deliberately skip to stay measurable, and a human tagging step — a model grading its own challenges is self-biased.

They're not independent

Three instincts, each applied in two places. Keep damage out of durable surfaces — the credential law and the file-protection hook. One source of truth, referenced not copied — the roles library and memory hygiene. Route by consequence, not by confidence — classify-then-act for tasks, tier-by-impact for findings. Adopt each when you feel the friction it removes, not before.

In motion

A task, end to end

What static files can't show: how one task moves through the system without you babysitting it. Step through it.

Go deeper

Read it, fork it, or hand it to your agent

The docs follow Diátaxis: why, what, how, and scaffolding to copy.

Spun out as a standalone tool: signal-sweep generalizes this workspace's thread-sweep module into a human-gated toolkit for finding the open GitHub threads your project's docs already answer.

Hand the repo to your own agent Tour this repo. Read PATTERNS.md, then META_ARCHITECTURE.md, then WORKFLOW.md, then scan samples/. Summarise the patterns most applicable to my workspace.

Standing this up inside an organisation?

I'm James Ross, an AI Knowledge Architect. The practice is Agent-Ready Knowledge Architecture: making an organisation's knowledge legible to AI agents. This workspace is the reference version of my own agent-ready memory layer. If you want these patterns adapted to your stack, the practice site is jamesross.ai.