Problem 4: Architecture is tribal knowledge
Architecture is tribal knowledge. Anyone who has inherited a codebase knows it, and now I inherit my own every day: I start a fresh agent session for each milestone to keep context clean, and every session re-derives the structure from directory names and gets some of it wrong. I built the same app twice, once on s0ma and once without, so I can run both.
Solution. s0ma declares layers, kinds, and dependency rules where the components live, and makes them queryable. It prescribes placement, not architecture: your design, stated once, readable by every newcomer, human or agent.
Demo. A fresh agent meets w4velength, an application of mine, with no source files and one tool, which reads the application's self-model. I ask where Linux system-audio capture belongs, how it connects, and what it must preserve. It surveys the modules, reads the capture component and its backends, and plans a new infrastructure module that implements the shared interface, registers where the others do, keeps audio in memory, and never opens the microphone. I grade the plan against a key I wrote from the source before any run. The take I kept meets all six criteria; two other takes fell short on one each. The diagram and checklist on screen are mine.
Transcript
I ask a fresh agent, with only w4velength's self-model, to plan Linux
system-audio capture
Recorded 2026-10-28 at 04:14 UTC.
Backend: claude. Model: claude-haiku-5-5, effort medium.
Client: Claude Code 2.1.286; tools mcp__s0ma__inspect_module; MCP server
s0ma (connected).
Run stream: media/short/runs/s4-20261028T041419Z.jsonl.
Every line under "Screen" comes from the run's stream, except lines
marked as editorial labels.
Screen
▌ fresh session, w4velength self-model only
> I want to add Linux system-audio capture
to w4velength. Where should it live, how
should it connect to the existing capture
flow, and which constraints must it
preserve? Inspect the project and give me
a short implementation plan. Do not change
files.
inspect_module …/w4velength
capture_coreaudio, capture_wasapi
layer INFRASTRUCTURE, INFRASTRUCTURE
inspect_module capture
layer APPLICATION
capture::register_backend
intent Additively register a platform
capture backend factory under a name …
capture::CaptureBackend
interface start, stop, read_window,
health, device_info
guarantees A conforming backend keeps raw
audio in memory only (NFR-P1), reads
system output via loopback and never opens
the microphone (NFR-P2), and produces
windows whose length matches the
config/sample-rate sizing (CAP-2).
inspect_module capture_coreaudio
inspect_module capture_wasapi
inspect_module contract
Add a new infrastructure module,
capture_linux (a proposed name), that
implements the CaptureBackend interface and
self-registers through register_backend, as
capture_wasapi and capture_coreaudio do.
Callers select it by name through
open_session, so the application-layer
capture module stays OS-agnostic. Reuse
capture_wasapi's downmix, silence, and
watchdog helpers. Constraints: capture only
the output monitor, never the microphone
(NFR-P2); keep audio in memory (NFR-P1);
size windows from config (CAP-2); re-attach
within 5s (CAP-3); defer platform imports.
Unknown: config wiring and registration call
sites, not inspected; no files changed.
▌ INFRASTRUCTURE APPLICATION
▌ new Linux module ─────▶ capture
▌ factory ─implements──▶ CaptureBackend
▌ register ─calls──────▶ register_backend
▌ placement: a new INFRASTRUCTURE module?
▌ register: via capture::register_backend?
▌ interface: implements CaptureBackend?
▌ memory: raw audio stays in memory?
▌ microphone: loopback, never the mic?
▌ windows: sized from config?
» check key
placement "…a new infrastructure module"
register "…through register_backend"
interface "…CaptureBackend interface…"
memory "keep audio in memory"
microphone "never the microphone"
windows "size windows from config"
exit 0, 34 ms
» check untouched
no output, exit 0, 10 ms
Edits
The recording ran 36.20 s as made; this video runs 27.88 s. One stretch
where the screen stood still was shortened by removing frames from the
middle, 8.32 s in all; nothing was sped up.
At 7.52 s: 8.32 s of waiting removed (7.04 to 16.36 s of the recording
stood still; 1.00 s of it stays).Benchmark. Two agents with no prior context, a fixed exploration budget, and the same questions about intent, dependencies, and placement. One has code and docs; the other has the registry. We measure accuracy against tokens spent, and the budget each needs to reach a passing score.
Status: planned.