Forge Course — Learn by Building

This course builds the real Forge application from an empty scaffold. It assumes you have written application code before but does not assume experience building process supervisors, agent harnesses, worktree managers, realtime synchronization, or crash-recoverable desktop systems.

Teaching style

Each lesson has the same structure:

• Outcome — the real Forge capability you will have at the end.
• Why now — why this concept appears at this exact point.
• Understand — plain-language mental model.
• Build — the actual project changes; no disconnected toy exercise.
• Tests / completion gate — what proves the lesson is done.
• Pitfalls — mistakes comparable tools have already paid for.
• References — official docs, source repos, issues, and deeper reading.
• Checkpoint — what to update in project status before continuing.

You are allowed to use AI coding agents. They should accelerate the Build section while the lesson keeps you in control of the concepts.

Course map

Part I — Foundations

• 00 — Orientation and repository contract
• 01 — Toolchain and process boundaries
• 02 — Typed RPC and desktop/core separation

Part II — Domain and persistence

• 03 — Model engineering work, not screens
• 04 — Small state machines and invariants
• 05 — SQLite, migrations, and repositories

Part III — Reliable side effects

• 06 — Why database transactions cannot control the outside world
• 07 — Operation workers, idempotency, and recovery
• 08 — One safe process-launch boundary
• 09 — Git as code truth
• 10 — Worktrees and Execution Environments

Part IV — Agent architecture

• 11 — Driver, Instance, Strategy, Capability
• 12 — Task vs Run vs Turn vs process
• 13 — Build the programmable fake agent
• 14 — Raw before parse
• 15 — Normalize events without lying

Part V — First product slice

• 16 — Electron shell and secure renderer
• 17 — React data ownership and the first Task workspace
• 18 — Probe a real provider safely
• 19 — First real adapter

Part VI — Quality loop

• 20 — Revisions and diffs
• 21 — Verification that becomes stale correctly
• 22 — Human review and change requests

Part VII — Planning and judgement

• 23 — Immutable Plans and review rounds
• 24 — Decomposition and simple dependencies
• 25 — Decisions and Needs You
• 26 — Injected escalation and capability preflight
• 27 — Involvement modes and host gating

Part VIII — Parallel work and understandable activity

• 28 — Dependency readiness
• 29 — Bounded scheduler and parallel agents
• 30 — Facts, claims, and meaningful activity
• 31 — Assumptions ledger
• 32 — Realtime sync, coalescing, and bounded replay

Part IX — Daily-driver hardening

• 33 — Crash recovery and reconciliation
• 34 — Performance, diagnostics, migrations, packaging
• 35 — Add a second adapter/environment without breaking the architecture

Reading discipline

Do not read every reference before starting. Read the short lesson first. Follow a reference when:

• the lesson marks it Required;
• you are implementing that exact mechanism;
• something behaves differently from your mental model;
• you want to understand why we chose the architecture.

The reference library is in ../research/REFERENCES.md.

Progress tracking

docs/status/CURRENT.md is the official current position. When a lesson is complete, update its lesson number and next action. The course does not use a separate “course progress database”; Git + docs/status/CURRENT.md is enough at this stage.