Set up TRW for Claude Code

Prerequisites

The installer handles package acquisition, but you need three things on the machine before you run it.

• Claude Code CLI installed and signed in
• Python 3.10 or newer on PATH
• A git repository where you want TRW active (TRW writes files into it)

You do not need Node.js, a background daemon, or cloud credentials. TRW runs locally and keeps its state inside the repo under .trw/.

Install

Run the bootstrap from the project root. It downloads trw-mcp from PyPI, writes a repo-local config, and asks which client surfaces you want configured. Pick Claude Code.

curl -fsSL https://trwframework.com/install.sh | bash

On first install, the Python installer opens a guided client picker so you can wire this repo for more than one surface in the same pass. Claude Code is always available; other surfaces are additive.

What the installer writes

Everything TRW adds to your repo is plain files you can read, commit, and delete. There is no binary state, no process running in the background, and no remote service call on install.

Commit these files. The installer also creates .trw/ runtime state that you should keep gitignored — the default .gitignore entries are written for you on first run.

Verify the install

Four quick checks confirm the repo is wired correctly before you start a session. If any of these fail, re-run the installer rather than hand-editing the files — the installer is idempotent and will repair drift.

which trw-mcp                      # resolves to ~/.local/bin/trw-mcp or similar
ls .claude/ .mcp.json CLAUDE.md    # all three present
grep target_platforms .trw/config.yaml
                                   # includes claude-code
claude --version                   # Claude Code CLI reachable

Run your first session

Launch Claude Code from the repo root. The CLAUDE.md surface loads automatically, and the session-start hook fires before your first prompt.

claude

Your first message should trigger trw_session_start(). CLAUDE.md prompts the agent to call it as the mandatory first action, and the tool returns prior learnings plus any run you can resume. A typical session-start response looks like this.

trw_session_start() ->
  framework: v24.6_TRW
  learnings_loaded: 492
  sessions_indexed: 249
  active_run: null
  ceremony_level: FULL
  next_action: declare intent, then call trw_checkpoint() after milestones

From there the loop is: do the work, checkpoint on milestones, record discoveries, verify with a build check, and close with trw_deliver(). The checkpoint is what makes your session resumable — if the context compacts between turns, the next session picks up from the last checkpoint instead of restarting.

trw_checkpoint("rate limiter merged, tests next")
trw_learn(summary="Cursor CLI needs .cursor/cli.json permissions baseline",
          detail="...full explanation...")
trw_build_check(scope="full")
trw_deliver()

Enable agent teams

Agent teams are opt-in. Without the env var, the TeamCreate, SendMessage, and TaskCreate tools silently no-op. Add the flag to your project or user settings to unlock the orchestration surface.

// .claude/settings.json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Once enabled, call /trw-team-playbook to generate a teammate roster with file-ownership YAML, and /trw-sprint-init to bootstrap a sprint run. Focused subagents produce fewer defects because they each get deeper context per task than a single generalist would.

Slash skills

TRW ships 24 slash-skills. Each is a folder with a SKILL.md that defines the trigger, tools, and workflow. Claude Code exposes them as /skill-name commands. The ones you will use most on day one.

• /trw-prd-ready — one-command PRD lifecycle: create, groom, review, refine, and produce a micro-task execution plan.
• /trw-sprint-init — initialize a sprint, list draft PRDs, and bootstrap the run directory.
• /trw-audit — adversarial spec-vs-code audit against a PRD with the mandatory NFR checklist.
• /trw-self-review — pre-audit checklist that catches 60%+ of typical audit findings before they are recorded.
• /trw-framework-check — ceremony adherence, phase gate status, and active run health in one report.
• /trw-memory-audit — tag distribution, impact spread, staleness, and duplicate candidates across your learnings.
• /trw-ceremony-guide — full tool lifecycle reference when you need to remember which tool to call and when.
• /trw-commit — stage, write a conventional-commit message, and commit without touching unrelated changes.

The full catalogue is in the Skills reference.

Bundled agents

TRW installs 12 subagents into .claude/agents/. Claude Code picks the right one for a task automatically based on the frontmatter triggers, or you can call one by name. Use agents to delegate specialist work so the primary context stays clean.

• trw-lead — team orchestrator for Agent Teams, owns the 6-phase lifecycle and delegates to focused teammates.
• trw-researcher — read-only codebase access with web research, produces structured findings before a decision is made.
• trw-implementer — writes production code and tests together under TDD, targets 90%+ coverage, honors file-ownership boundaries.
• trw-reviewer — rubric-scored review across 7 dimensions including OWASP Top 10 and DRY/KISS/SOLID. Read-only.
• trw-auditor — 7-phase spec-vs-code audit with bidirectional traceability between PRD requirements and implementation.
• trw-prd-groomer — full PRD lifecycle from initial draft to sprint-ready at completeness ≥ 0.85.

The other six agents (adversarial auditor, tester, requirement writer, requirement reviewer, traceability checker, code simplifier) are listed in the Agent roles reference.

Lifecycle hooks

Hooks are the enforcement layer — they run outside the agent so the agent cannot talk its way past them. Claude Code executes them at well-defined lifecycle events, and TRW registers 13 of them during install. All hooks are shell scripts under .claude/hooks/, fail-open on any error, and log to .trw/logs/hooks.log so you can audit what fired.

session-start

Fires on startup, resume, compact, and clear. Dispatches on the source payload from Claude Code and prompts the agent to load prior learnings via trw_session_start(). Fail-open: any error silently exits 0 so a broken hook never blocks a session.

pre-compact

Fires when Claude Code is about to compact the context window. Calls trw_pre_compact_checkpoint() so the active run's progress is saved before tokens are dropped — the next turn resumes instead of restarting.

subagent-start

Fires when a subagent is spawned. Propagates the parent session ID and active run pin so learnings and checkpoints the subagent records land in the right run, not an orphan one.

stop-ceremony

Fires on Claude Code stop events. Enforces the ceremony contract — if the session recorded work but skipped trw_deliver(), the hook nudges before the context is lost. The nudge is load-bearing; do not remove it without replacing the enforcement path.

The full list and payload schemas live in the Hooks reference.

Common problems

Two more worth knowing. If a linter rewrites a TRW-managed file, run the installer again — do not hand-edit the generated surfaces, since installer drift produces silent tool misconfiguration. And if you see stale behavior after decomposing a large module, clear __pycache__ in your Python packages — stale bytecode beats the reloader. Deeper debugging paths and client-specific startup issues are in the troubleshooting guide.