Architecture Overview

Welcome to the map. Before diving into building piece by piece, it helps to see the whole picture from above. This document shows you what the full system contains, why the chapters are ordered this way, and what you will actually learn.

The Big Picture

The mainline of this repo is reasonable because it grows the system in four dependency-driven stages:

1. build a real single-agent loop
2. harden that loop with safety, memory, and recovery
3. turn temporary session work into durable runtime work
4. grow the single executor into a multi-agent platform with isolated lanes and external capability routing

This order follows mechanism dependencies, not file order and not product glamour.

If the learner does not already understand:

user input -> model -> tools -> write-back -> next turn

then permissions, hooks, memory, tasks, teams, worktrees, and MCP all become disconnected vocabulary.

What This Repo Is Trying To Reconstruct

This repository is not trying to mirror a production codebase line by line.

It is trying to reconstruct the parts that determine whether an agent system actually works:

• what the main modules are
• how those modules cooperate
• what each module is responsible for
• where the important state lives
• how one request flows through the system

That means the goal is:

high fidelity to the design backbone, not 1:1 fidelity to every outer implementation detail.

Three Tips Before You Start

Tip 1: Learn the smallest correct version first

For example, a subagent does not need every advanced capability on day one.

The smallest correct version already teaches the core lesson:

• the parent defines the subtask
• the child gets a separate messages[]
• the child returns a summary

Only after that is stable should you add:

• inherited context
• separate permissions
• background runtime
• worktree isolation

Tip 2: New terms should be explained before they are used

This repo uses terms such as:

• state machine
• dispatch map
• dependency graph
• worktree
• protocol envelope
• MCP

If a term is unfamiliar, pause and check the reference docs rather than pushing forward blindly.

Recommended companions:

• glossary.md
• entity-map.md
• data-structures.md
• teaching-scope.md

Tip 3: Do not let peripheral complexity pretend to be core mechanism

Good teaching does not try to include everything.

It explains the important parts completely and keeps low-value complexity out of your way:

• packaging and release flow
• enterprise integration glue
• telemetry
• product-specific compatibility branches
• file-name / line-number reverse-engineering trivia

Bridge Docs That Matter

Treat these as cross-chapter maps:

The Four Learning Stages

Stage 1: Core Single-Agent (s01-s06)

Goal: build a single agent that can actually do work.

Stage 2: Hardening (s07-s11)

Goal: make the loop safer, more stable, and easier to extend.

Stage 3: Runtime Work (s12-s14)

Goal: upgrade session work into durable, background, and scheduled runtime work.

Stage 4: Platform (s15-s19)

Goal: grow from one executor into a larger platform.

Quick Reference: What Each Chapter Adds

Key Takeaway

A good chapter order is not a list of features. It is a path where each mechanism grows naturally out of the last one.