Start Here

Forge is both a real application and the course through which you will learn to build it. You do not need to read the whole repository before you begin.

Every build session

1. Read the current status.
2. Open the current lesson from the course.
3. Read only the architecture/design pages linked from that lesson.
4. Build the real Forge increment.
5. Run the lesson's completion gate.
6. Update status and, when useful, the learning log.
7. Commit a small coherent unit of work.

The project itself is the exercise.

Read these first

1. Vocabulary — the words used throughout Forge.
2. Product requirements — what we are building.
3. Architecture overview — the major boundaries.
4. Course overview — the lesson sequence.
5. Master build plan — the larger picture when you need it.
6. Reference library — primary docs, repos, and deeper reading.

The first product loop we are aiming for

create task
    ↓
start agent in isolated worktree
    ↓
see useful progress
    ↓
agent produces a candidate revision
    ↓
review
    ↓
request changes if needed
    ↓
agent revises
    ↓
human approves
    ↓
Done

Do not begin by implementing every provider, a plugin platform, full event sourcing, or a beautiful dashboard. Sophisticated machinery earns its place by making this loop safer, clearer, or more useful.

How documentation is maintained

Canonical product, architecture, and design docs must describe the current system. ADRs preserve the reason behind consequential decisions. We do not leave known-wrong paragraphs in canonical docs and ask future agents to mentally patch them with ADRs.

When a decision changes:

make decision
   ↓
update canonical doc
   ↓
write/amend ADR if the reason is important
   ↓
update plan/course if sequencing changed
   ↓
update current status

See the documentation site guide for the Bun/VitePress commands.

When an AI coding agent helps

Give it the current lesson, the relevant architecture page, and the repository-root AGENTS.md. Do not dump the entire documentation tree into its context by default. Use agents to accelerate implementation, not to bypass your understanding: if the agent introduces something you cannot explain in simple language afterward, the lesson is not complete yet.