Escapement

Escapement is a workflow plugin for Claude Code.

If you let a watch’s mainspring unwind all at once, the hands would spin wildly for a few seconds before the energy spent itself. Instead of a sudden burst, a good watch runs for days. That endurance is made possible by the escapement: a mechanism that releases the spring’s energy one precise tick at a time.

The spring wants to unwind all at once. That's its power, its whole reason for being. The escapement simply refuses to let it.

AI coding agents are like a wound mainspring. They possess enormous potential energy, ready to spew thousands of lines of code the moment you give them an opening. Without something to regulate that energy, that’s exactly what you get: one uncontrolled burst, followed by a mess you’re left to sort through.

A workflow is the escapement—a constraint on capability that governs how the energy gets released.

Beyond the Chat Window

When people discuss AI coding workflows, the conversation often centers on the chat window: prompt engineering, context management, and phrasing things "just right" to prevent hallucinations while letting the model off the chain. Those tactics matter. But an escapement isn’t a prompting trick, and it doesn’t live entirely inside the conversation. It’s an apparatus that sprawls across the landscape of the development process: the issue tracker, the branching strategy, the review loop, and archival practices. None of this is new. Disciplines like Gitflow, agile sprints, atomic commits, and PR-based review existed long before LLMs. They emerged because complex systems don't tolerate unconstrained, monolithic change.

While the AI is a new capability, the material of software engineering remains the same. The escapement simply regulates this new force using the old, proven logic.

A Caveat

What follows is a description of a single-threaded workflow.

I tackle one issue at a time, maintain one scratchpad, and use one branch, keeping my attention on the chosen unit of work as it happens. I’m not orchestrating a fleet of agents while I sip coffee, nor letting autonomous processes run unchecked for hours while I sleep.

Maybe I'm doing it wrong. Much of the current discourse revolves around spawning parallel agents, letting them race across git worktrees, and auto-merging their output. That may well be the future. However, for now, I don’t trust the structure unless I’m watching the decisions as they’re made. Working one tick at a time may sound slow, but arguably, under AI augmentation, velocity matters less than validity. As has been widely noted, unverified speed is often just rework that hasn't been discovered yet.

The Mechanism

Here is how my workflow breaks down.

• Epic
  
  Large goals are decomposed. This starts as a conversation about what we are building or fixing, and what shape the solution is likely to take. From there, the Agent and I derive a sequence of coarse steps, each becoming its own issue. Together, they form an epic—a coherent arc with a clear endpoint. This is the only moment where the AI sees the full picture; from here on, its focus is strictly narrowed.
  
  
• Backlog
  
  Ideas surface constantly—during work, in conversation, in the shower. They go straight into the backlog, alongside planned issues, at whatever level of detail exists in that moment. Sometimes it's just a title; sometimes it's fully specified.
  
  The backlog is a holding pen. Capture the thought, park it, move on.
  
  You could later formalize this into sprint planning. I don't run strict sprints, but the structure supports them.
  
  
• Scratchpad
  
  When an issue is pulled, it gets a fresh conversation. The codebase may have shifted since the issue was written, so we first sanity-check the approach. For ad-hoc work, we flesh out understanding and strategy, occasionally spawning more issues along the way.
  
  The AI then drafts a scratchpad: a concrete execution plan for this specific unit of work.
  
  It is an iterative process. The AI drafts and asks clarifying questions; I respond, and it redrafts. Assumptions surface and the spec tightens.
  
  Once the scratchpad is solid, I often clear the context. The exploratory conversation did its job and I don't want the execution to be polluted by the noise of the brainstorming session. The scratchpad carries the distillation of intent forward.
  
  
• Execute
  
  Open a feature or fix branch off develop, gitflow-style. The AI then works against the scratchpad while I watch—sometimes closely, correcting drift early; sometimes loosely, letting it run to a checkpoint before I evaluate.
  
  Either way, human attention stays in the loop. The scratchpad evolves as work progresses, and the agent commits in small increments as TODOs get crossed off.
  
  
• Integrate
  
  Push the branch and open a PR back to develop. Then, review the code against the original issue to see if it meets the acceptance criteria.
  
  Sometimes fixes happen directly in the CLI. Other times, it is a more formal review with inline comments for the AI to address. Less often do I have an AI perform the PR review itself.
  
  Finally, I squash-merge and delete the branch.
  
  
• Archive
  
  I have a hook on compact that dumps the session log to disk with incremental numbering. By the end of an issue, there may be several of these. I archive the scratchpad and logs under a timestamp and issue number.
  
  The result is a history of the work—not just the code, but the thinking.

Each of these steps serves as a tooth in the escapement. Issue discipline bounds scope, the scratchpad crystallizes intent, clearing context resets focus, while branch strategy isolates change, incremental commits protect momentum, PR routine gates integration, and the archive preserves history — tick. Without a mechanism like this, you get a burst; with it, you get measured, verified forward motion.

The Rhythm

Beyond just metering energy, an escapement serves another vital purpose: it keeps time.

A clock doesn't speed up for important moments or slow down for trivial ones. The mechanism enforces a steady cadence regardless of the circumstances.

The workflow performs that same role here. Not all work is equal. Some issues are tiny. Others are deep, risky, mission-critical. Some touch only the surface code; others cut into and through load-bearing structure. Even within "incremental" work, there's real variation in complexity and consequence.

This machinery absorbs that variance. Because every task must pass through the same gates of issue, scratchpad, branch, review, and archive, high-risk changes don't arrive as adrenaline spikes, and low-impact tweaks don't get waved through on vibes. Everything advances one tick at a time. The system doesn’t eliminate difficulty, but it does meter it, creating an intentionally boring, trustworthy pace.

Unsolved

The archive is becoming a problem.

Every issue adds to the pile of historical scratchpads and conversation logs, saved under docs/. The idea was insurance: a record I could consult if I ever needed to understand the context of why something was done or otherwise replay the narrative of decision making.

In practice, I rarely consult the logs. Instead, I find myself fighting search results that are polluted with log files when I’m trying to find actual code. As the project grows, so does this noise.

I don't have a solution yet. Maybe the archive belongs outside the repo. Maybe in a separate branch, or managed by some third party service. Maybe it doesn't belong at all—perhaps git history and the issue tracker are enough.

For now, I'm noting the problem and living with it.

The core mechanism works.

The Repo

I’ve codified this philosophy into a tool called escapement, a dedicated plugin for Claude Code. Install once, use it across projects.

The mainspring is wound tight. This will help keep it from unwinding all at once.