Systems Architecture

A map of everything. Working.

A cognitive twin is designed to scan the environment, index every tool, map every project, and set up the work so it can run with less babysitting. It is built to be the meta-layer that the other stacks are designed to sit on top of.

01 — The System Scan

What was found.

The environment is a working surface. Not a storage dump — a living pipeline. The twin starts by making an honest inventory of what's actually there, in plain text, so the rest of the layers have something concrete to reason over.

Domain Tools & Environment Projects / Memory
Music Production DAW · Notation · Sample library · Sampler · Synth · FX chain · Generative audio music-corpus — analysis index
audio-pipeline — source separation → transcription → notation
practice-tracker · repertoire-db · arrangement-tools
AI Audio STT · audio analysis · audio editing · LLM APIs · browser audio · voice synthesis transcription-dashboard — research tracker
handwriting-ocr — image → font engine
audio-summarizer
AI Agents Code assistant · Coder · Generalist · Reviewer · Verifier memory/user.md · memory/agent.md — durable agent context
Visual / Web WebGL · build tool · UI framework · image gen · video gen · NLE · video upscale shader-sketches · gen-art · long-horizon · web-lab
Knowledge Note system · Reference corpus · Notation · Code assistant notes-source.md · notes-status.log
memory/user.md · memory/agent.md · session history
GitHub gh CLI · Git · deploy targets · static hosting Dozens of repositories across the audio, web, and tooling layers — including a series site, a prompt library, and a jazz lexicon.
The environment is not a backup. It's a pipeline. The twin doesn't catalog it for its own sake — it catalogs it so the right tool gets routed to the right job without manual retrieval. "I want to transcribe this recording" should route to the transcription pipeline, not require re-discovering which tools are installed.
02 — Architecture

Four layers. Each one does one thing.

The twin is not a single agent. It's a layered system — scan, model, reason, orchestrate — where each layer feeds the next and none of them require a human in the loop once the work is defined.

1
Scanner
Index the environment
Runs on demand or on a cron. Traverses the filesystem at startup — reads package.json, requirements.txt, agent skills, installed tools (brew, pip, npm), GitHub repos, Obsidian vault index. Outputs a structured snapshot of every tool, project, and capability available right now. If a new package appears, the scanner finds it on the next run.
2
Model
Persist the inventory as memory
The scan output writes to a durable layer — memory/user.md for cross-project preferences, memory/agent.md for agent behavior, and a project-level twin index for domain-specific context. This is what allows the twin to know "I already have a transcription pipeline" without re-running discovery. The model is the memory of the environment.
3
Reasoner
Match work to tools
Given a job — "transcribe this recording", "build a landing page for X", "run the weekly report" — the reasoner reads the model and selects the right tools in the right order. It's not an LLM doing freeform reasoning from scratch; it's a routing decision constrained by the actual inventory. If Whisper and pYIN are installed, route audio transcription there. If not, route to the API. The reasoner picks from what's actually available.
4
Orchestrator
Set up and run the work process
Once the reasoner picks the path, the orchestrator sets up the process — writes a subagent prompt, schedules a cron, triggers a webhook, or hands off to the next agent in the chain. The orchestrator also handles failure modes: if a step fails, it retries, rolls back, or escalates to the human digest with a diff. The orchestrator is the part that does the work. The other three layers exist so it always knows what it's working with.
03 — Designed Processes

What the twin is built to run.

The twin doesn't just describe the environment — it acts on it. These are the process templates it runs, the way an operating system runs its daemons: each one is a defined loop with a defined output.

Research swarm — scheduled subagent that polls a paper feed (arXiv, conference proceedings) and a code feed (GitHub trending, releases) on a fixed cadence. Writes a summary into a tracked docs folder; the published site rebuilds on push.
↓
Deploy gate — fires on every web deploy. Visits the live URL, asserts HTTP 200, checks the rendered DOM for expected strings, fails on console errors, retries the deploy if the check fails. The twin verifies its own output.
↓
Memory maintenance — at the end of a working session, the twin appends durable learnings to memory/user.md (cross-project rules), memory/agent.md (agent behavior), or a project-level AGENTS.md (repo-specific context). The next agent that spins up reads the model and starts with working context.
↓
E2E regression gate — after any sprint (multi-step code change), the twin runs the project's end-to-end test before reporting done. Typecheck + build passing don't count. The test must pass. If it fails, the sprint isn't done.
The twin is not a dashboard. A dashboard shows you what's happening. The twin acts on what it finds. If a scheduled job fails three times in a row, the twin doesn't just tell you — it flags it, rolls back the broken deploy, and puts the diagnostic in your next digest. You read the report, not the process.
04 — Twin Instances

Domain-specific twins built from the scan.

The general scanner produces domain-specific instantiations. Each twin knows its domain cold and runs the work without asking — one set of tools per domain, switched on by what the scan finds.

Music Twin

Index: DAW projects, recording sessions, scores, sample libraries, patches, presets. Knows the full instrument and FX chain. Routes requests to the right environment — generative audio for demos, DAW for production, corpus tools for analysis.

Transcription Twin

Index: live recordings, transcription output, charts, practice logs. Scans the transcription stack directories. Keeps the pitch-detection + notation pipeline warm. Routes new recordings to the ingest → transcribe → chart flow automatically.

Web Twin

Index: all deployed pages, deploy targets, hosting providers. Keeps every spoke linked to the hub. Monitors every deploy with the page-check gate. Notifies (or auto-reverts) on failure.

Research Twin

Index: paper feeds, code trending, jazz reference corpus, audio corpora, knowledge base. Runs the research swarm. Keeps a domain-specific dashboard current. Alerts when a new relevant paper or tool appears.

Toolchain

What the twin is built from.

Filesystem traversal (stdlib) GitHub CLI Code assistant + specialized subagents Memory layers (user · agent · AGENTS.md) Scheduled self-reminders Subagent swarms Headless deploy gate E2E regression runner Python package introspection npm manifest parsing Scheduled job runner JSON durable memory

Nine stacks. One philosophy. Zero babysitting.