A rewrite of this piece, edited for readability. Facts, case IDs, links, and citations are unchanged.
The chat is gone. Can someone else finish the work?
You're halfway through a feature when the agent stops. Maybe you hit the usage limit, maybe the provider is down. So you open a different agent, point it at the same repo, and type "keep going."
It has never seen the conversation. It has the files.
In my experience this is the most common handoff in agent-assisted development, and the most mundane: same person, same repo, a different tool with no memory. Anything the first agent and I agreed on in chat is gone unless it got written into the repo.
Railspike is a workflow for coding agents that writes it down. Each round of work (a cycle) leaves four files in the repository: an assessment of the options, the agreed requirements, a development plan, and an implementation summary. The bet is that a second agent can read those four files and pick up correctly.
This article tests that bet cheaply. I took three real sets of plan files and asked what a fresh agent would learn from them, where it would go wrong, and what the files can't tell it.
A note on method first. I only read files. Nobody handed them to a fresh agent and watched what it did. The cases come from the Railspike maintainer's own projects, picked by a fixed rule (the lowest ID in each category of an earlier 25-record review) so I couldn't swap weak cases for flattering ones. One comes from a different project that kept a single plan file instead of Railspike's four, and I don't know whether Railspike ran it. Every claim below traces to a source in the evidence appendix, with hashes and limits.
Case 1: half the feature is missing on purpose
The request was one sentence: two features had been built in another project, fold them into this one. The first groups each feature's plan files into their own folder. The second is a "debug mode" that writes diagnostic reports on how the workflow instructions performed.
The assessment weighed three paths: do both at once, split them, or import the old commits and repair the conflicts. It recommended splitting, to keep the Git history readable. The first cycle's requirements then excluded debug mode outright. The implementation summary closed out the folder work and said debug mode would get its own cycle with its own approvals. (Evidence appendix, case C002.)
A new agent that reads only the original request sees half the feature missing and builds it. One that reads the requirements and summary learns the half was deferred deliberately, and asks first. Same repo, opposite actions. A forgotten requirement is a bug you fix. A split feature needs its own go-ahead.
There's a smaller trap in the same files. The folder rule's own plan files were written before the rule existed, so they couldn't follow it. The development plan says this outright and calls it a bootstrap exception. Delete that line and it looks like the cycle that introduced the rule also broke it.
What the files don't say is who approved anything. The summary reports that approved content was preserved, but I didn't see an approval transcript. The commit shows the public-copy changes and the summary landing together. It doesn't show who signed off or whether the reported checks passed. A tidy folder of plans still needs evidence behind its status labels.
Case 2: the page that was finished and not released
The second case is a replacement homepage for skeptical technical readers. It has a plain explanation, the install path, a worked example drawn from real plans, and honest limits. The implementation summary reports that local checks passed: layout measurements, example excerpts checked against their source plans, and links.
The same summary lists three things still open: the maintainer's review of the copy and rendered page, the merge, and a check of the live URL after deployment. The commit is titled "record release verification" and touches only the summary file. It doesn't show the page was released. (Evidence appendix, case C005.)
The question a new agent faces here is "do I merge this?" The files answer it: not yet, three gates are open. Without that list there are two tempting mistakes, redoing finished work or publishing on authority nobody gave. (That's my reading of the files. I didn't see an agent make either mistake, and I didn't check whether the gates closed later.)
"These checks passed" sitting next to "this review is still open" isn't a contradiction, and it's the most useful thing in the file. It breaks when a single word like "complete" flattens the two together. It also breaks when an old pending item sits there with no sign of whether it's still pending.
This case also shows the repo's one real blind spot. The homepage's worked example came from an earlier cycle, and that cycle's summary notes the approval was typed in chat and never stored. The proposal survived, and so did the result. The "yes, go ahead" didn't, because it lived in the conversation.
Case 3: the field that changed meaning at the bottom of the file
The third case is from a separate application. Its activity page lists recently changed source files, each with the commit that last touched it. That commit is stored at indexing time so the page never runs Git on a request. One plan file holds the data contract, five implementation stages marked complete, the reported tests, the risks, and an approval gate.
At the bottom sits a production hotfix note. Full rebuilds now use the repo's current commit instead of looking up each file's last commit, because the per-file lookups held a global execution lock during rebuilds. Incremental writes still use the exact commit that wrote them. (Evidence appendix, case C024.)
That matters because the latest commit may not have touched a given file. After the hotfix, the column no longer means "the commit that last changed this file." It now means "a commit where this file existed." Linking to a file at a revision is a different promise from saying when it last changed. The field kept its name and changed its meaning.
A new agent sees the top of the file say one thing and the bottom say another, with nothing crossed out. Under the five completed stages, the last line still reads: pause here until this plan is approved. An agent that treats every sentence as a live instruction might restore the per-file lookups and bring the lock problem back. One that reads the file as a chronology gets it right. The file rewards that reading but doesn't force it.
The files can't say whether the hotfix was worth it or whether anyone signed off on the new meaning. The committed diff does remove the per-file Git lookup and cache a single repository-head value, so the change is real. But nothing measures the speedup that motivated it. The test-success note also predates the hotfix, so it says nothing about the new meaning. And the stale approval gate isn't evidence that anything ran without permission. It's a sentence nobody deleted.
Appending the correction instead of overwriting the plan kept the reason for the change. The cost is that the old contract and the new one look equally authoritative. A two-line current-state note at the top would fix that, naming which behavior governs and pointing down to the superseded decision. I haven't tested it, and the idea isn't new. Michael Nygard's architecture decision records have recommended marking reversed decisions "superseded," with a pointer to the replacement, since 2011.
Five things to find before you type "keep going"
These cases suggest a short checklist. It hasn't been validated, so treat it as a proposal. Before resuming from files alone, find:
1. The outcome currently wanted. This is the latest scoped requirement and how it differs from the original request. In case 1, it's the line deferring debug mode.
2. The decisions still in force. These are the chosen approach, the reason for it, and anything superseded. In case 3, it's the hotfix note.
3. The next action that's actually authorized. You need an approval tied to this scope at this revision. If the file only reports that approval happened, note that. A plan file, or a status an agent wrote about itself, can't grant permission.
4. What was actually checked. Look for the command or observation itself, separate from the summary of its result, with revision and environment if you have them. In case 2, local rendering tells you nothing about the deployed page.
5. What's still open. This covers pending checks, deferred work, missing evidence, and who has to decide. Leave the next reader a concrete question rather than a vague worry.
A short current-state section at the top of each plan could answer all five and link down to the history. The history is still worth keeping, because it explains how the current state got that way. Replaying the whole chat would make the new agent redo the selection work. Compressing too hard drops exactly the exception or correction that matters.
One practical test: take the next action you're tempted to do and trace its justification through the files. "May I merge this homepage?" should lead you to the release condition and the evidence behind it. If the trail ends at an approval that only ever existed in a chat window, leave that gap visible. "Not yet" is a fine answer.
The reader still has to judge how strong each piece of evidence is. An interview study by Dhanorkar, Passi, and Vorvoreanu describes developers overseeing agents through planning and review, and treating test results as assurance of correctness. I mention it as context for taking that judgment seriously. It didn't evaluate Railspike or this checklist.
How you'd actually test this
The claim everyone wants is that durable plans make handoffs better. Three files from one maintainer can't settle that. A fresh agent might find the answer in a minute, or ignore the files entirely. It might follow the superseded instruction, or spend longer reconciling documents than it would have spent reading the chat.
Here's a test that could settle it.
1. Stop several tasks at defined points.
2. Give fresh agents the same repo snapshot plus one of three context packages: the full conversation, a short handoff note, or the durable plan files.
3. Include an ordinary unfinished implementation, a reversed decision, and an open approval gate.
4. Write down the acceptable next actions before anyone sees a continuation.
5. Score each continuation on whether it reconstructed the current scope, made an authorized move, repeated finished investigation, or introduced a mistake.
Hold model, tools, time budget, and task difficulty constant. Have reviewers score without knowing which package produced each result. Run it enough times that one lucky continuation can't carry the result.
Two controls matter. First, if the plan package simply contains facts the handoff note left out, it'll win for that reason alone. So one comparison should hold information constant and vary only organization. Second, a fair comparison counts what the files cost to maintain. A plan that saves its reader ten minutes after costing its author twenty is a trade. (Those numbers are illustrative. Nothing in these cases was timed.)
Human handoffs would need their own study. Nothing measured on fresh agents should be passed off as evidence about how fast a developer gets up to speed. None of this has been run yet.
What the files offer for now is unfinished business you can inspect. Case 1 explains why half a request was set aside, case 2 names the release work it doesn't prove, and case 3 keeps a correction that changes how its own requirement should be read. Whether the next agent notices any of it is what's worth testing.
Draft written and source-checked by Codex from the maintainer's development records, with editorial revisions by Claude on October 30, 2026. Independent human review is pending.
Sources:
- Evidence appendix (inspected artifacts, reported results, and interpretation): https://github.com/rlspk/railspike-dev/blob/feat/durable-handoffs/docs/research/durable_handoffs/evidence.md
- Michael Nygard, Documenting Architecture Decisions: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- Dhanorkar, Passi, and Vorvoreanu, Human oversight of agentic systems in practice: https://arxiv.org/abs/2606.05391
#railspike #agents #writing