system-layer-extraction

System Layer Extraction

Investigate an entire codebase file-by-file to extract every system, map their boundaries, dependencies, state, lifecycle, and isolation potential. Produce a comprehensive layered architecture document and interactive visualization.

This is slow, thorough work. The value comes from reading actual source code — not READMEs, not architecture docs, not summaries. Every file gets read. Every import gets traced. The output is a document that makes the invisible structure visible.

---

Why This Matters

Codebases accumulate structure over time that nobody fully sees. Systems intertwine. Dependencies form that aren't in any diagram. State gets shared in ways the original authors didn't intend. This skill makes all of that explicit — so you can refactor with confidence, onboard new contributors faster, and identify where isolation is strong vs where it's fragile.

---

The Process

Step 1: Set Up

Create a working branch so the output files don't pollute the main branch:

git checkout -b system-layer-extraction

Step 2: Map the Territory

Before reading any code, get the full picture of what exists:

# All non-test source files, sorted
find src -name "*.ts" ! -name "*.test.ts" ! -name "*.spec.ts" | sort

# All source directories
find src -type d | sort

# Line counts per directory (rough sizing)
find src -name "*.ts" ! -name "*.test.ts" | xargs wc -l | sort -n

This gives you the raw material: how many files, how they're organized, where the mass is.

Step 3: Group Files Into Investigation Areas

Divide all source files into 5-8 logical groups based on directory structure and apparent concern. Each group becomes one subagent's assignment. Typical groupings:

• Entry points + CLI + Bootstrap — how the system starts, wires, and presents to users
• Communication infrastructure — event bus, observer/logging, streaming
• Core domain services — task engine, safety, authorization, memory, workspace
• Intelligence/orchestration — the brain, phase pipeline, prompts, LLM interaction
• Plugin ecosystem — adapters, registry, hooks, concrete plugin implementations
• Data layer — database, config, schemas, migrations
• UI/Dashboard — if present, the monitoring/visualization layer
• Cross-cutting — utilities, shared types, interfaces