Rules with long half-lives
Identity, security, tool policy, canonical grammar, and irreversible product laws belong in byte-stable or versioned owners.
Open-kimono architecture report · July 2026
The agent is temporary. The kernel travels.
Across years of MCP servers, companion agents, content systems, dashboards, prompt optimizers, autonomous loops, and Snappy itself, the reusable mechanism is not a particular model. It is a portable control architecture made of inspectable prompts, typed capabilities, explicit state, bounded delegation, and independent proof.
Capability should survive the harness that discovered it.
Prompt ≠ blobIt is compiled control architecture.
Skill ≠ proseIt becomes real through typed callable files.
Activity ≠ progressOnly retained proof advances state.
Actor ≠ auditorIndependent verification is structural.
01 / CONTROL PLANE
Prompts are compiled runtime architecture.
The hard-won move was to stop treating one giant system prompt as the product. Different facts have different owners, half-lives, trust levels, cache behavior, and ideal positions.
Reality that can expire
Current time, active object, source readiness, goal, approval state, and authoritative IDs are rebuilt near the decision.
Domain depth on demand
A small index makes chapters visible; relevant canonical bodies load only when the task needs them.
Results with provenance
Recent tool outputs, receipts, access records, and prior attempts are bounded, typed, and treated as untrusted input.
Reusable head
+Cacheable identity, laws, grammar, stable tool semantics.
Variable tail
→Live reality, goal, authoritative state, relevant loaders.
Decision frame
Enough truth for the next action; no catalog tax.
Decision-local salience
The correct rule must appear where the model chooses. The HTML-first instruction initially failed because it sat behind 19.6k characters of familiar component signatures. The fix was to shrink the phone book and move the law into ComposeUI’s high-salience description—not to write a more emotional paragraph.
- Context firstThe companion-agent lineage established identity, memory, relationship, and current scene before behavioral instructions. [P1]
- Action lastLength caps and immediate action constraints sit nearest generation so they are not washed out by earlier prose.
- TraceabilityPrompt versions, owner breakdowns, skill digests, and exact prompts used turn “the model was weird” into an inspectable hypothesis.
- Cache placementStable law can be cached; live state and history must remain outside. Cache correctness is an architecture property.
- OptimizationA/B prompt work is meaningful only when examples, judges, and metrics remain comparable across runs.
02 / CAPABILITY
The filesystem is both declaration and reflection.
A skill grows by adding inspectable files, not by editing an omniscient router. The directory itself says how mature, portable, schedulable, and measurable the capability is.
Mentionable
SKILL.md + AGENTS.md + api.tsCallableAt least three typed exported functions.
Drillable
entities.json declares providers and verbs.ScriptableAn operations recipe binds the typed API.
CronableA loops entry schedules the recipe.
Measurable
metrics.json declares quality gauges and smoke tests.Canonical knowledge
Full workflows, decision trees, source contracts, edge cases, and safety law. This is the domain source—not the global bootstrap.
Operational loader
A compressed execution map plus passive index. It makes relevant files visible before the agent must remember retrieval exists.
Typed primitive
The one programmatic interface. It must work from raw shell and different model harnesses, not just from a magic tool name.
npx tsx ~/.claude/skills/snappy-<name>/api.ts <command> [...args]
// the same primitive can also be imported
import { operation } from "../snappy-<name>/api.ts";
// promotion happens through files
entities.json → recipe.ts → loops.json → metrics.json
Electricity test
A useful capability should be consumable without the harness that taught the model about it. Hooks may improve discovery, but the primitive must still execute through plain TypeScript and direct APIs. The hook serves the agent; the API serves the world.
Canonical specification: Snappy Skill System — Ground Truth. The current spec is ambitious but candid: trend-sensitive PID escalation is described as an implementation path, not falsely claimed as complete.
03 / DISCOVERY
Make the right capability hard to forget.
Good knowledge that never enters attention is operationally nonexistent. Discovery moved from “the agent should remember” to passive indexes, automatic activation, progressive disclosure, and model-selectable fallback brains.
MentionUser, main agent, or delegated task names a skill.
IndexPassive file map reveals relevant chapters.
InjectHook or runtime loader supplies operational context.
InvokeTyped API performs the real operation.
VerifyIndependent proof checks the effect.
ImproveDetected gaps queue regeneration or spec fixes.
Activation becomes environmental.
Prompt-submit and pre-tool hooks match skill names, load compact instructions, append the self-correcting footer, and log injection. Post-tool and stop hooks queue and check drift. [S1]
Cheap labor is a separate economic lane.
Mechanical, bounded, verifiable work can go to a cheaper model. Architecture, publication-quality judgment, and ambiguous decisions stay with the orchestrator.
The brain is replaceable.
A full kernel prompt can boot a different provider when the primary harness is unavailable. The recipe should not care which brand produced the tokens.
What changed
Earlier MCP generations put every tool in resident context. Later systems filtered by mode or slug. The current pattern keeps a small semantic core, exposes a passive map, retrieves exact schemas, and preserves one typed primitive underneath. Discovery and execution are different layers.
04 / DELEGATION
Agents need bounded ownership, not swarm theater.
Parallelism is useful only when work can proceed independently and merge through evidence. Shared-state collisions, ambiguous ownership, and duplicated judgment can erase the latency gain.
Concrete finish line
An agent gets a named artifact or question, explicit scope, exclusions, and a return contract.
One canonical writer
Overlapping edits and two agents “owning” final synthesis create invisible conflict even when git merges.
Worktrees for mutable state
Parallel code changes benefit from isolated worktrees. Shared directories are acceptable only when ownership is non-overlapping and explicit.
Findings, not autobiography
The child returns files, claims, commands, failures, and proof. The lead owns synthesis and contradictory evidence.
| Delegate when | Keep central when | Failure to watch |
|---|---|---|
| Repository inventory, grep, source extraction, independent audits | Architecture, prioritization, claim wording, final teaching narrative | Many summaries repeating the same shallow scan |
| Independent components with separate files or worktrees | Changes that share a fragile state machine or one canonical writer | Last writer wins over another agent’s valid work |
| Actor/auditor split across different brains or providers | One brain both performs and certifies its own effect | Confidence reported as evidence |
| Mechanical tasks with deterministic verification | Ambiguous human intent or irreversible external action | Delegation silently broadens authority |
Shared-state law
A team of agents is a distributed system. Define ownership, isolation, state transfer, idempotency, and evidence exactly as you would for services. “They are all smart” does not solve coordination.
05 / AUTONOMY
Autonomy should preserve best-known state.
The Ralph lineage replaces endless self-reported activity with a keep-or-revert loop: one story, one attempt, real acceptance, evidence, and a branch tip that never advances on an unproven regression.
SelectChoose one failing or highest-value story.
AttemptCreate a bounded candidate change.
BuildRun structural and production gates.
DriveExercise the real cold user path.
JudgeInspect proof artifacts and regressions.
Keep / revertAdvance only when the evidence improves.
Bound the search.
A loop that changes five unrelated systems cannot explain which change produced the outcome.
Drive what users drive.
Warm unit paths miss authentication, initialization, hydration, runtime owner, packaging, and browser paint failures.
State survives context loss.
Attempts, gates, screenshots, failures, and retained deltas accumulate outside model memory.
best_known = branch_tip
for story in prioritized_failures:
candidate = attempt_one(story)
proof = build_and_drive_cold_path(candidate)
if proof.improves_without_regression:
keep(candidate); best_known = candidate
else:
revert(candidate)
record(proof) // including failed attempts
Historical implementation: backend-dashboard/scripts/ralph/prompt.md. The transferable lesson is the invariant, not the name “Ralph.”
06 / EVALUATION
Effects need certificates; quality needs comparable evals.
These are different proof problems. A certificate answers “did the action really happen?” An eval answers “how good was the result under a stable rubric?”
Actor cannot audit itself.
A different brain or provider verifies the external effect against an independent surface. Same-session success text is not proof.
Real, sample, target, stub
Suggestion-engine work separated live mechanisms, sample data, built-but-unrouted migration targets, and honest stubs so demos could not silently upgrade reality. [E1]
Minimum, not average
Visual QC scores logic, composition, style, text, artifacts, and two-second concept relevance—then uses the minimum so one fatal weakness cannot hide behind five pretty dimensions. [E2]
| DSPy / prompt lesson | Observed failure | Operating law |
|---|---|---|
| Count unique examples | 527 EmailResponder traces collapsed to roughly 12 distinct inputs. | Choose optimizer by post-dedup information diversity, not event volume. |
| Match optimizer to data | MIPROv2 overfits tiny datasets. | Use a bounded few-shot optimizer below the unique-example threshold. |
| Give judges rich context | Sparse strings produced flat, uninformative scores. | Judge the full relevant output and task context. |
| Compare compatible metrics | Old heuristic scores and later LLM-judge scores looked like one timeline. | Only compare runs evaluated with equivalent metrics and fields. |
| Preserve human voice | A rewrite loop could “improve” already-authentic source material. | Support score-without-rewrite preservation mode and human redlines. |
Saved runs are data
Every versioned prompt, exact input, output, judge context, score, user rating, redline, and activation decision should become a reusable eval corpus. Optimization is an evidence pipeline, not a prompt séance.
DSPy operating notes: dspy-worker/.claude/CLAUDE.md. Voice preservation and prompt versioning: content-engine/stage_voice.js.
07 / MEMORY
Memory is not a bigger prompt. It is mutable attention state.
The Charlotte/Cyborg lineage treated retrieval as a policy shaped by current goal, inhibition, salience, access history, and decay—not as a heap of facts dumped into every turn.
Current objective
The active goal defines what counts as relevant now, not forever.
Deliberate inhibition
Some knowledge becomes more salient; other recurring distractions are intentionally damped.
Use changes state
Retrieval history and recency update future relevance rather than disappearing after one answer.
Attention has a half-life
Nightly or periodic decay prevents yesterday’s urgency from becoming permanent identity.
Narrative layering beats fact dumping.
Recent exchanges, short-term memories, a longer arc, and relationship state are rendered at different resolutions. The model can ask for depth instead of receiving the whole archive.
Identity should emerge from context.
The companion prompt aimed to make memory read like someone remembering a person, not a database reciting rows. The current scene and relationship modulate tone without replacing model judgment.
Transferable secret
When retrieval feels noisy, do not immediately add a larger embedding model. First model what the system is trying to do, what it should ignore, what has recently mattered, and how attention should decay.
Historical evidence: cyborg-mcp/CLAUDE.md and the context-first prompt construction in companion-agent-mcp/src/index.ts.
08 / EFFECTS
Let the model choose meaning. Let the runtime own identity.
Semantic judgment and authoritative context are complementary. The model can decide what action fits; the boundary must supply the real user, object, source, scope, and approval state.
Model judgment
+Select action, synthesize meaning, choose fitting content and sequence.
Runtime authority
→Overwrite hallucinated IDs, enforce user/session/source scope, decide approval policy.
Governed effect
Stage, approve, execute idempotently, receipt, verify, resume.
Defaults are non-effecting.
Plans, previews, drafts, and capability declarations do not mutate external systems unless explicit apply authority is present.
Context defeats hallucination.
The companion runtime replaced model-provided companion, user, post, comment, group, scene, and lineage IDs with trusted session context.
Effects are resumable.
Durable task handles, approval identity, idempotency keys, and outcome-unknown states support reconciliation without blind repetition.
Human authority law
A helpful agent may discover, prepare, stage, and explain an effect. It may not reinterpret helpfulness as permission. Approval is a state transition owned by the human plane, not a sentence in the model’s inner monologue.
09 / OPEN LEDGER
The reversals are part of the invention.
This is not a clean-room architecture that emerged fully formed. It is a trail of overload, inert knowledge, false proof, overfitted prompts, duplicate owners, blind retries, and abstractions deleted after contact with reality.
Prompt ownership and live context
Separate long-lived law from per-turn reality; place critical guidance at the decision point.
Filesystem capability contracts
Typed APIs and measurable files let tools outlive their discovery harness.
All tools resident
Coverage without attention became context bloat. Progressive discovery replaced the phone book.
Skills that depend on memory to load
Useful instructions stayed inert. Hooks and passive indexes made activation environmental.
Trace count was fake diversity
Hundreds of events reduced to a dozen unique inputs, changing optimizer choice.
Average scores hid fatal quality
Weakest-link visual evaluation exposed one bad dimension instead of laundering it through a mean.
Some laws remain linguistic
Not every prompt contract has been compiled into a schema, gate, or state machine.
PID trend detection is target state
The skill spec defines escalation from repeated gap patterns, but explicitly describes the trend detector as an implementation path.
Independent proof is uneven
Certificates are a strong contract; historical projects do not all meet the current actor/auditor standard.
| Lineage | What it contributed | What not to overclaim |
|---|---|---|
| MCP generations | Tool education, compact results, poka-yoke, disclosure economics, runtime errors that teach recovery. | Earlier large catalogs and mode filters are historical steps, not the current ideal. |
| Companion / Cyborg | Context-first prompting, authoritative IDs, narrative memory, goals, inhibition, salience, decay. | These are lineage mechanisms; not every one is present unchanged in Snappy OS. |
| Suggestion engine / DSPy | Reality matrices, A/B levers, comparable evals, unique-example counts, optimizer selection. | Built-but-unrouted targets and sample dimensions remain explicitly labeled. |
| Content Engine | Prompt versions, bounded retries, preservation mode, weakest-link visual QC. | Model judging is a quality signal, not independent proof of external effect. |
| Ralph / agent studio work | Best-known state, cold-path acceptance, evidence ledgers, keep/revert autonomy. | Autonomy quality depends on the acceptance surface and can still optimize the wrong proxy. |
| Snappy kernel / Mini | Portable verbs, filesystem rungs, typed APIs, brain swaps, actor/auditor certificates, self-hosting. | Some kernel enforcement and cross-runtime parity are newer target contracts with uneven historical coverage. |
10 / MANIFESTO
Orchestration is scaffolding. Capability and proof are the building.
A mature agent system should remain useful when the model, provider, IDE, connector protocol, or scheduler changes.
The secret is not making the agent remember everything. It is making the system remember what the agent must not be trusted to remember.
Separate stable law, live reality, retrieved depth, tool evidence, and decision-local constraints.
Give every useful skill one callable interface that works outside its favorite harness.
Name owner, scope, output, isolation, and proof before adding another brain.
Attempt one change, drive reality, keep on proof, revert on failure.
Effects require independent certificates; quality requires stable comparable evals.
Goals, boost, suppression, access, salience, and decay beat indiscriminate memory dumps.
Let the model choose semantic action; let the boundary own real IDs, scope, and approval.
Implemented, measured, historical, inferred, desired, and unresolved are different truth classes.
11 / PROVENANCE
Attribution is part of the architecture.
First-party mechanisms, forks, references, experiments, generated output, and target state were separated before synthesis.
First-partyHistoricalReferenceRuntimeUncertain
