Quest Plan

Onboarding Tour · 4 levels · populated

Level 1 · Map the architecture

Build the map before touching anything. Find the entry points — main/index, CLI commands, server bootstrap, the first line that runs. Identify the major modules or directories and what each one is responsible for. Work out how they’re wired together: what calls what, what owns state, what’s a leaf and what’s a hub. Produce a short written map — a paragraph or a small diagram is enough — that names the pieces and the direction data flows between them. When you could point a newcomer at any file and say which part of the map it belongs to, run quest_level complete.

Level 2 · Trace one flow end to end

Pick one real thing the system does and follow it all the way through. Choose a concrete flow — a login, an API request, a build step, a message being processed — and trace it from the entry point to wherever it terminates, through every layer it touches. Note every side effect along the way: what gets written, what network calls fire, what state changes, what gets logged. Don’t paraphrase from memory — actually read the code at each hop. When you can narrate the flow accurately from entry to exit, including its side effects, run quest_level complete.

Level 3 · Find the fragile edges

Identify the part of this codebase people are quietly afraid of. Look for the file with the worst edit history, the critical path with no tests, the implicit assumption baked in three layers deep that nobody documented, the thing that would break loudly — or worse, silently — if someone violated an assumption they didn’t know existed. Say specifically why it’s fragile, not just that it looks scary: what would have to go wrong, and what would happen next. When you’ve named the riskiest spot and can explain the failure mode, run quest_level complete.

Level 4 · Write it up

Leave a findings doc that lets someone start here cold. Combine the architecture map, the traced flow, and the fragile-edge finding into one document a new engineer — or the next agent — could read before making their first change. End with the three things you’d want explained before touching this codebase, in priority order. When the doc exists and says something a stranger could actually use, run quest_level complete.