The last post was about where the engineer runs. I’d built eng, a CLI that dispatches engineering work to an always-on Mac Studio instead of my laptop, with a choice of two engines and each run isolated in its own git worktree. This one is about how the architect and the engineer actually talk to each other.

Design happens in the architect thread, between me and the agent: back and forth, half-formed ideas, me changing my mind. None of that goes to the engineer. The architect and the engineer never share a context window, and they’re not even the same tool: an architect thread in Cursor handing off to eng, which runs Claude Code or Pi. The handoff between them happens through two places only: Linear issues and ADRs.

What a handoff looks like

The handoff between the architect and the engineer is a comment on the relevant Linear issue. The first one, the implementation handoff, is a self-contained context package: a summary, affected files, implementation steps, test strategy, open questions.

The reply from the engineer is a pull request (PR). The engineer commits its work to a branch and opens a PR from it, with CI and Bugbot running against the diff and gating the merge. The architect reviews the PR on GitHub, via the gh CLI.

Review findings go back to the engineer the same way, as a CLI argument: eng review <run> --feedback "...", full technical detail, file paths, the exact fix. None of that goes to Linear.

Once the issue lands, the architect composes a summary compressed to what a future reader would actually want to know happened, not a copy of what went to the engineer as feedback. A finding about the shipped code’s correctness earns a line in that summary. A finding that was really about getting the PR into a landable state, a bad rebase, flaky CI, nothing to do with the issue’s own scope, gets fixed and forgotten.

ADRs capture the durable, widely applicable decisions

In addition to the handoff comment posted on the issue, some issues also come with an ADR.

An ADR, short for architecture decision record, is a short markdown file living in the repo under docs/decisions/, one per decision: what constraint forced a choice, what was decided, which alternatives got rejected and why, what consequences matter later. Nothing fancy, no special tooling beyond a skill that tells the architect when and how to write one, just a folder of dated files that git tracks like everything else.

Most of what’s in a handoff comment is issue-specific: useful context if a similar bug or feature comes up later, findable by searching Linear, but scoped to that one piece of work. A decision that shapes the architecture is different. It’s usually relevant well beyond the issue that prompted it, and it doesn’t belong buried in a comment thread that’s really about one narrow change. That’s what goes in an ADR instead, cross-linked from the issue. The issue says what to build and how, for this piece of work; the ADR says why, for the product as a whole.

What makes them worth the ceremony is that they accumulate. A repo that’s been running on this method for a while ends up with a stack of ADRs that amounts to a running record of why the architecture looks the way it does. New sessions, human or agent, can read that stack before proposing something that contradicts a decision already made. In practice I see the architect reach back into an old ADR unprompted more often than I’d have guessed, citing a decision from months ago to explain why a new proposal needs to work around it rather than through it.

How the status field is used

The Linear issue’s status acts as a turn marker.

  • Backlog: captured, not designed yet.
  • Todo: the handoff is posted. Ready for an engineer.
  • In Progress: the engineer is implementing, or fixing something sent back in review.
  • In Review: PR open, CI green, Bugbot passed. Waiting on the architect.
  • Done: merged, verified, over.

Moving the issue is part of the handoff. eng has its own run status too (queued, running, awaiting review, done), but that only exists once a run has been dispatched. Linear status is the record that exists before and after that: it’s still the turn marker even when no run exists yet.

An ADR has its own status too, and the two are meant to move together: an ADR stays Proposed and the issue stays in Backlog until I give an explicit greenlight. The explicit “yes, build it” from me flips the ADR to Accepted and the issue to Todo.

How it fits together

Put together, a piece of work moves through all three at once. Design settles in the architect thread. If it’s architecturally significant, it becomes an ADR, cross-linked to the issue. I greenlight it, the ADR and the issue move in step, and the handoff comment goes up. The engineer implements, replies with a PR, the issue tracks whose move it is throughout, and any review findings go back as directives, the same as the handoff, just through eng review --feedback instead of a Linear comment. Once it lands, the ADR stays in the repo for the next decision that needs it; the issue stays in Linear for the next similar bug.