Work Session Guide

This is the routine to use when you sit down to build Forge.

Before coding

1. Open docs/status/CURRENT.md.
2. Open the current course lesson.
3. Read only the lesson's required current architecture pages.
4. Run the existing test suite once so you know the starting state.
5. Decide the smallest coherent slice you can finish in this session.

While coding

Keep one question in mind: which boundary owns this behavior?

• Domain: rules/invariants.
• Application: use-case coordination and durable intent.
• Operations: external-effect lifecycle/recovery.
• Storage: SQLite representation.
• Git/Execution/Agent infrastructure: external mechanics.
• RPC: transport translation.
• React: presentation/interactions.
• Electron: desktop/OS/core lifecycle.

When an AI agent is helping, give it the current lesson + relevant architecture doc + AGENTS.md. Ask it to keep changes inside the current lesson unless a blocker proves the plan wrong.

Before committing

• run lesson completion tests;
• inspect the diff yourself;
• remove accidental abstractions/dead code;
• update current docs if behavior changed;
• update docs/status/CURRENT.md if current lesson/next action changed;
• add a Learning Log entry only for evidence worth remembering.

When stuck

Do not solve uncertainty by adding architecture. First reduce the question to a small experiment in a disposable repo/test. Record the result. Then change the architecture if evidence demands it.