Master Build Plan

This plan is the product build order and the spine of the course. It deliberately builds vertical slices. A milestone is not complete because code exists; it is complete when its acceptance scenario works, tests pass, and current docs match reality.

How to use this plan

The detailed teaching lives in docs/course/lessons/. Do not implement a whole milestone from this summary alone when the course has a lesson for it.

Every milestone follows the same rhythm:

understand the boundary
    ↓
build the smallest useful version
    ↓
test it deterministically
    ↓
use/inspect it
    ↓
record what reality taught us
    ↓
continue

M0 — Repository, toolchain, and contracts

Goal: A clean Go/Electron/Bun repository where the core and desktop can run independently and a minimal generated RPC round trip is possible.

Build:

• root repository/tooling conventions;
• Go core executable skeleton;
• Bun-managed desktop workspace;
• Electron main + sandboxed renderer shell;
• Protobuf/Buf/Connect toolchain or an intentionally minimal temporary RPC bootstrap if generation blocks progress;
• centralized config/data-path helpers;
• logging baseline;
• CI/check commands.

Do not build Tasks, agents, or Kanban behavior yet.

Acceptance:

forge-core starts
Electron starts
renderer cannot directly access Node/process APIs
UI can call a typed core Health/GetVersion RPC
all starter checks pass

Lessons: 00–02.

M1 — Task domain and SQLite

Goal: Create Projects and Tasks with a correct small state machine and persist them safely.

Build:

• SQLite open/migration system;
• pragmas via connection/DSN configuration;
• Project;
• Task + Acceptance Criterion;
• BACKLOG → READY → WORKING → REVIEW → DONE transitions;
• NEEDS_YOU transition hooks reserved for later;
• command-oriented application layer;
• repositories/queries;
• initial RPC commands/queries;
• migration tests and domain tests.

Acceptance:

create Project
create Task
add criteria
make Ready
start logically (no agent yet)
move to Review in a controlled test/harness path
approve → Done
illegal transitions fail clearly
restart core → state survives

Lessons: 03–05.

M2 — Durable Operations

Goal: Introduce the pattern that keeps SQLite intent coherent with non-transactional external side effects.

Build:

• Operation domain/storage;
• idempotency keys;
• bounded worker;
• lifecycle PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED;
• retry/requeue primitives;
• deterministic Drain for tests;
• startup scan/recovery hook;
• fake operation handler used to prove crash/retry behavior.

Acceptance:

application command commits Operation
worker performs fake external effect
restart with PENDING operation → continues safely
repeat same idempotent operation → no duplicate effect
in-flight/queue drain tests are deterministic

Lessons: 06–07.

M3 — Git, worktrees, and first Execution Environment

Goal: Forge can safely prepare an isolated local worktree for a Task.

Build:

• centralized ProcessRunner;
• GitService using real git executable;
• real-temp-repo test harness;
• stable-ID worktree paths;
• Worktree lifecycle/storage;
• create pipeline: inspect → resolve base → add → verify;
• cleanup safety checks;
• LocalWorktreeEnvironment;
• Project Trust model before repository-defined setup scripts are introduced.

Acceptance:

real temp repo
Task requests local worktree
Operation creates and verifies it
path does not change when Task title changes
attempt to remove dirty worktree is refused
restart can rediscover/reconcile prepared worktree

Lessons: 08–10.

M4 — Agent model and deterministic fake adapter

Goal: Prove the agent architecture without relying on any model API or provider CLI.

Build:

• Agent Driver / Instance / Strategy model;
• Capability types;
• Agent Run and Agent Turn;
• adapter interface;
• adapter registry;
• programmable Fake Adapter;
• adapter contract suite;
• execution orchestration using a LocalWorktreeEnvironment;
• fake agent can edit files, emit events, finish, crash, and be cancelled.

Acceptance:

Task starts
worktree prepared
Fake Agent Run starts
one or more Turns execute
fake changes a file
Run completion is classified without using a fake PID as identity
Task obtains a candidate revision/result path
contract tests pass

Lessons: 11–13.

M5 — Raw logging and normalized event pipeline

Goal: Make provider history recoverable and create the foundations for useful activity.

Build:

• append-only framed JSONL RawLog;
• raw reference returned before parse/normalize;
• AgentEvent model;
• fact/claim discriminator;
• normalized message/tool/result events;
• unknown-event policy;
• partial-final-line recovery;
• compact queryable history separate from live deltas.

Acceptance:

fake raw event written first
normalized event always has RawRef
parser failure does not erase source input
restart can read valid history despite a simulated partial final line
facts and claims cannot be accidentally omitted

Lessons: 14–15.

M6 — First usable desktop vertical slice

Goal: Use Forge through a real desktop UI before the backend becomes huge.

Build:

• Project open/create flow;
• Task list;
• Task detail;
• create Task/criteria;
• make Ready / Start;
• current Run/Turn status;
• bounded live activity for Fake Adapter;
• command accepted versus Operation/provider progress states;
• basic error/degraded presentation.

Acceptance:

A human can open the desktop app, create a Task, start the fake agent, watch it work, see the resulting candidate state, and close/reopen without losing Task data.

Lessons: 16–17.

M7 — First real agent adapter

Goal: Control one real coding agent through a structured supported protocol.

Current working assumption: Claude Code, but close OD-002 before implementation.

Build:

• side-effect-minimal Probe;
• run isolation/config strategy;
• structured protocol decoder;
• raw-before-parse integration;
• external session ID handling;
• interruption/cancellation;
• provider completion semantics;
• capability declaration;
• fixtures from captured protocol data;
• live acceptance test in a disposable repository.

Acceptance:

Probe detects availability without starting real work
Forge starts real provider in Task worktree
structured progress appears
provider edits code
completion classified from protocol semantics
raw evidence retained
cancel works
unsupported capability is explicit

Lessons: 18–19.

M8 — Candidate revisions, verification, and human review loop

Goal: Reach the product's core quality loop.

Build:

• candidate revision identity;
• Verification Definition/Run;
• revision validity/staleness;
• Review + Review Comment;
• diff querying/rendering;
• acceptance criterion acknowledgement;
• request changes;
• review feedback injected into a new Turn/Run as appropriate;
• human approval to Done;
• optional AI reviewer as a reviewer kind, not Task status.

Acceptance:

agent finishes revision A
verification runs against A
human reviews A
requests changes
agent produces B
A verification/review shown stale for B
verification/review B
human approves B
Task becomes Done

Lessons: 20–22.

M9 — Planning and decomposition

Goal: Build the optional plan/review loop without bloating Task status.

Build:

• Plan identity and scope;
• immutable Plan Revision;
• Plan Review/annotations;
• reject → new revision;
• approve;
• Feature Plan decomposition proposal;
• editable confirm-before-commit;
• Task Execution Plan using same machinery;
• dependency edge validation including cycle rejection.

Acceptance:

create Feature Plan revision 1
review rejects with annotations
revision 2 approved
planner/fake produces proposed Tasks
human edits/confirms
Tasks/dependencies persisted idempotently

Lessons: 23–24.

M10 — Decisions, Needs You, escalation, and gating

Goal: Make human judgement a reliable structured path rather than inferred from text.

Build:

• Decision/Option/Resolution;
• Task NEEDS_YOU behavior;
• global Decision Inbox;
• Involvement Mode and policy snapshot;
• host gating independent from involvement;
• injected escalation tool for capable adapter;
• preflight verifies tool is actually invocable;
• resume/exit-and-resume behavior as supported;
• default/deadline semantics only where safe;
• destructive actions never auto-resolve.

Acceptance:

agent encounters ambiguity
raises Forge Decision
Task visibly Needs You
Decision survives desktop/core restart
human resolves
agent continues with answer
history records true human resolution
failed escalation preflight blocks mode rather than silently degrading

Lessons: 25–27.

M11 — Dependencies, scheduler, and safe parallelism

Goal: Run several eligible Tasks without turning Forge into a workflow engine.

Build:

• dependency readiness query;
• simple cycle guard already introduced in planning;
• bounded scheduler;
• max_concurrent_agent_runs;
• multiple worktrees;
• clear blocked/eligible states;
• no branch-off-unmerged-sibling optimization yet.

Acceptance:

With Tasks A and B independent and C depending on both, A/B can run concurrently up to the configured limit; C does not start until both are Done/integrated according to the selected policy.

Lessons: 28–29.

M12 — Meaningful activity and realtime hardening

Goal: Make supervision useful without raw transcript reading and keep long-running clients correct.

Build:

• deterministic Steps from observed facts;
• agent-authored Intent/Phase markers where supported;
• Assumptions Ledger;
• Fact/Claim UI;
• pageable activity;
• streaming coalescing;
• bounded replay + snapshot fallback;
• Connection Health + Sync Health;
• stale subscription recovery;
• large-history performance fixtures.

Acceptance:

A long Task remains responsive; reopen after a large history does not replay an unbounded firehose; disconnect/reconnect converges to authoritative state; useful activity remains understandable without opening raw logs.

Lessons: 30–32.

M13 — Recovery, diagnostics, packaging, and observability

Goal: Make Forge dependable as a daily Linux desktop application.

Build:

• startup reconciliation matrix;
• crash-boundary test suite;
• structured logs/diagnostic bundle;
• DB backup/repair strategy;
• migration fixtures;
• performance profiling;
• Electron packaging (AppImage first, then other Linux formats as needed);
• core lifecycle hardening;
• safe update story later, not self-updating core magic in the first pass.

Acceptance:

Kill Forge at several defined lifecycle boundaries; restart converges without losing work or falsely marking completion. Packaged app runs on the target Linux environment.

Lessons: 33–34.

M14 — Additional adapters/environments

Only after the central loop is strong:

• Codex strategy/instance;
• OpenCode service-shaped adapter;
• Pi/OMP shared transport where appropriate;
• Docker/SSH Execution Environments if real workflows require them;
• richer provider settings and account management.

Every new adapter must pass the contract suite and must not cause provider-name branches in the domain/UI.

Lesson: 35.

Milestone discipline

At the end of each milestone:

• run all tests;
• manually perform its acceptance scenario;
• update docs/status/CURRENT.md;
• add useful observations to LEARNING_LOG.md;
• close/open decisions based on evidence;
• update canonical docs if implementation revealed a better model;
• keep the next milestone smaller rather than carrying hidden unfinished work forward.