Core Concepts

At a Glance

Sessions

A session is a single conversation between you and your AI agent. It begins when the agent loads its context window and ends when the conversation closes or the window compacts. Without TRW, everything the agent discovers during a session evaporates when it ends.

TRW changes this by bookending every session with two tools. trw_session_start() loads learnings from prior sessions so the agent already knows the codebase's patterns and gotchas. trw_deliver() persists everything discovered during the session so the next one starts smarter.

The result: session 50 in a project is fundamentally better than session 1 — not because the agent remembers more, but because the framework does.

Runs

A run is a tracked unit of work with a name, a directory, and a progression through phases. When the agent calls trw_init("auth-refactor"), TRW creates a run directory under .trw/runs/ that holds checkpoints, analytics, and state.

Runs survive context compaction. If the agent's context window shrinks mid-task, it can resume from the last checkpoint instead of starting over. Runs also span sessions — an interrupted run is automatically detected and resumed on the next trw_session_start().

trw_init("auth-refactor")
# → Run created: .trw/runs/auth-refactor/
# → Phase: PLAN

trw_checkpoint("middleware complete, tests next")
# → Checkpoint saved to .trw/runs/auth-refactor/

# ... context compacts ...

trw_session_start()
# → Recovered active run: auth-refactor
# → Resuming from checkpoint: "middleware complete, tests next"

Learnings

A learning is a discovery recorded by the agent during a session. When the agent hits a gotcha, finds a pattern that works, or discovers an architectural decision worth preserving, it calls trw_learn() with a summary and detail.

Each learning receives an impact score based on specificity, actionability, and relevance. High-impact learnings get promoted into CLAUDE.md so they load automatically every session. Low-impact learnings decay over time and are eventually pruned — keeping the knowledge base fresh and relevant.

trw_learn(
  "SQLite WAL mode required for concurrent readers",
  "Without WAL, concurrent read queries block on writes..."
)
# → Learning recorded (impact: 0.8)
# → Will surface on future trw_recall("sqlite") queries

Knowledge Compounding

Knowledge compounding is the core insight behind TRW. Each session's discoveries feed into the next session's starting context, creating a flywheel that accelerates over time.

Learn → Persist → Recall → Apply → Improve → Learn
  ↑                                              |
  └──────────────────────────────────────────────┘

Phases

TRW organizes every task into six phases. Each phase has a purpose, key tools, and exit criteria that must be satisfied before advancing. This prevents the most common failure mode in AI development — rushing to code before understanding the problem.

Phases are not strictly linear. When a later phase reveals a problem, the agent reverts to an earlier phase rather than pushing through. See the Lifecycle page for full detail on each phase, reversion rules, and exit criteria.

Ceremony

Not every task needs all six phases. TRW scores task complexity and assigns a ceremony tier that matches process rigor to the risk of the change. A one-line config fix skips straight to implementation. A multi-file architecture change uses every gate.

The tier is determined automatically based on file count, PRD presence, and whether existing tests are affected. You can also set ceremony mode explicitly in configuration.

Phase Gates

A phase gate is a quality check at each phase boundary. The agent cannot advance to the next phase until the current phase's exit criteria are satisfied. Gates enforce discipline structurally — catching issues when they are cheap to fix instead of after they have cascaded downstream.

Putting It Together

Here is a complete workflow showing how these concepts interact during a typical full-ceremony session.

# SESSION START — load prior knowledge
trw_session_start()
# → Loaded 47 learnings (12 high-impact)
# → No active run found

# RESEARCH — gather context
trw_recall("authentication middleware")
# → 3 relevant learnings found

# PLAN — create a tracked run
trw_init("auth-refactor")
# → Run created, phase: PLAN → IMPLEMENT

# IMPLEMENT — write code, save progress
# ... write code ...
trw_checkpoint("JWT validation extracted to shared module")
# → Checkpoint saved

# VALIDATE — verify the work
trw_build_check()
# → 312 passed, 0 failed, coverage 93%
# → Phase: VALIDATE → REVIEW

# REVIEW — quality audit, record discoveries
trw_review()
# → 2 findings, 0 blockers
trw_learn("JWT validation must check 'aud' claim", "...")
# → Learning recorded (impact: 0.85)

# DELIVER — persist everything, close the run
trw_deliver()
# → 2 learnings persisted, 1 promoted to CLAUDE.md
# → Run closed: auth-refactor

Next Steps