Moving Between Different Tools: Hitting the Capability Wall

The wall shows up more than you'd think

No AI tool does everything well, so at some point you always hit a wall: the tool you're in can't finish what it started, and the work has to move somewhere else. Claude Design can iterate on a look in seconds but can't touch a real repo. A subagent working a feature in an isolated git worktree can make all the changes it wants, but the main session that has to merge them wasn't there for any of it. A research thread can go deep on a problem, but the coding session that acts on it starts from zero.

The instinct is to just re-explain things on the other side — paste the conversation, summarize what happened, hope the next tool or session picks up the thread. That mostly works for small stuff and quietly fails for anything real, because a conversation and a set of decisions are not the same shape. One is everything that was said. The other is what actually needs to survive.

What crosses the wall is a document, not a transcript

I felt this concretely working on this site's terminal-window theme. Claude Design and I landed on a full design system — tokens, spacing, a Sanity field mapping, the works — entirely inside a tool that cannot run code. Getting it into Claude Code didn't mean re-describing the design in a fresh conversation. It meant a file existed first:

# Handoff: Terminal-Window Theme for prompttoproduction.ai

## About the Design Files
The files in this bundle are design references authored in HTML —
self-contained .dc.html files that open in any browser. They are
prototypes showing the intended look and behavior — not production
code to copy verbatim. The task is to recreate these designs in the
site's existing environment with its established component and
styling patterns, wiring the real Sanity data in place of the
hardcoded copy.

## Fidelity
High-fidelity. Final colors, typography, spacing, and interactions.

None of the "try 4," "nope, way off" back-and-forth that produced this design made it into that file. Nor did any code — Claude Design can't write code that runs, so it didn't pretend to. What it wrote instead was exact oklch values, a type scale, a screen-by-screen breakdown, and a Sanity field mapping telling Claude Code precisely which schema field fills which slot. Everything the next tool needed to finish the job. Nothing it needed to relitigate.

I've seen the same shape from the other direction, unglamorously, in my own build log: a subagent working a feature in a git worktree, writing up what it changed and why, and the main session absorbing that write-up and discarding the file the moment it was no longer needed. Different tools, same problem, same fix.

The anatomy of a handoff that actually works

A few things separate a handoff that works from a summary that doesn't:

It captures decisions, not discussion. The path to a decision is often messy — dead ends, reversals, "nope, try again." None of that belongs in the handoff. Only the outcome does. The receiving side doesn't need to know you tried four layouts; it needs to know which one won and why.

It's scoped to what the other side is missing, not everything you know. The Claude Design handoff didn't re-explain what a design token is, or narrate the whole collaboration — it assumed Claude Code already knew how to build a Next.js component and gave it exactly the site-specific facts it couldn't otherwise have: these colors, this field mapping, this fidelity level.

It says what it isn't, not just what it is. "Not production code to copy verbatim" is one sentence, and it prevents an entire category of mistake — the receiving tool copying prototype markup instead of rebuilding it properly. A good handoff is explicit about the boundary of its own authority.

It's disposable. The worktree HANDOFF.md got deleted once it was read and acted on. It didn't need to become documentation — it needed to exist exactly as long as the gap it was crossing, and then get out of the way.

The takeaway

Working across multiple AI tools isn't really a coordination problem you solve by picking better tools or writing longer prompts. It's a documentation problem, and a narrow one: at the exact moment work has to leave one context for another, something has to capture the decisions — not the process — in a form the next side can act on without you in the room. Get that one file right, and moving between tools stops feeling like a restart and starts feeling like a continuation.

❯ handoff() → continue() ✓