Everything changed very quickly.
In a matter of days, my work at DataCamp went from coding and debugging mostly by hand to doing a lot of it throu...
For further actions, you may consider blocking this person and/or reporting abuse
This is the real shift with coding agents. Specs stop being ceremony and become runtime context. The better the decision trail, constraints, and acceptance criteria are, the less the agent has to infer from vibes.
"Runtime context", I am stealing that. That is exactly it. The spec used to be something you wrote to feel responsible and then never opened again. Now it is the thing the agent actually reads at the moment of doing the work, so a vague line in the spec turns straight into a vague line in the code
Please steal it. The interesting part is that specs become executable context. They are no longer just a planning artifact; they are one of the inputs that shapes the actual edit, test, and review path.
Runtime context is the reframe. The spec stops being ceremony you write once and becomes what the agent actually reads as it acts, so a vague line in it turns straight into vague code.
Exactly. Runtime context is a useful way to say it because it makes the spec part of execution, not documentation. The agent is not just reading requirements; it is using them as operating memory while it edits.
Yip I feel that. The one time at my job that I actually got a thorough 4 page document on what the module was meant to be. We discussed it, I made the changes. Then fed it to an agent to see just how well it'll do... It finished the entire 1500 LOC module in 30 min. No actually done, not 'find the bug'
That is exactly the thing that flipped for me. The agent was never the bottleneck, the ambiguity was. Give it a real spec and it just goes. The hard part is that most of the time nobody writes the 4 pages, so we blame the agent for guessing
Exactly. 2 fatal errors: Context starvation and Context bloat. both lead to hallucinations and drift. If you want something specific, be specific. Agents arent meant to guess, they're meant to translate from natural language into code.
The line that lands hardest here is that if the next session starts with old context, the agent works on a reality that no longer exists. That is the whole game with fragmented sessions, and you built the right reflex for it with /handoff and /update-docs. Specs make the work testable, but the half that rots fastest is not the spec, it is the decisions and the why: what you chose, what you ruled out, what is still open. A stale spec is annoying, a stale decision is the one that makes the agent confidently rebuild something you already killed.
What helped me was treating that operating state as its own file layer the agent reads at the start and writes back at the end of a task, not a doc I have to remember to update. Decisions with a status, open questions, what changed since last session, sitting next to the specs in .harness-style folders. Your /handoff is basically that as a command, mine is the same instinct as a closing habit. I open-sourced the shape for Claude Cowork and Code if you want to compare notes, MIT, just folders plus a write-back step: cowork-os.
One thing I keep wrestling with on the handoff: does yours summarize the session freely, or do you pin certain things verbatim (constraints, killed options) so the compression cannot quietly drop them? That boundary is where mine leaks the most.
Good question, and you put your finger on the exact thing I was scared of. The split is by layer, not one or the other.
The handoff doc itself summarizes freely. It is disposable, it just gets the next session moving, and it points to the real files instead of re-pasting them.
The stuff I cannot let drift never lives in that summary. Constraints sit in the feature specs, and decisions plus killed options sit in ADRs. An ADR has an "Options considered" section, so the approach I rejected stays written down right next to why it lost. That is the part that keeps the agent from happily rebuilding something I already killed.
The handoff only grabs decisions from the conversation that have not made it into an ADR yet, and it drops the "I picked X because it was faster today" kind of reasoning on purpose.
So, summarize the session, pin the decisions, different files. A killed option does not survive because I quoted it in a summary, it survives because it gets its own little tombstone in the ADRs.
By the way, I've skimmed your cowork-os and it looks promising. I'll take a closer look when I have some time 😉
The tombstone framing is the keeper here. A killed option survives because it gets its own marker next to why it lost, not because someone remembered to quote it in a summary. That is the one thing a disposable doc should never be trusted to hold. And thanks for looking at cowork-os, no rush at all.
The place I still get bitten is the door between the two layers. Your handoff grabs decisions that have not made it into an ADR yet, so there is a window where a real constraint lives only in the disposable summary. If the next handoff re-summarizes it instead of graduating it, it can age out before it ever gets its tombstone. The durable side is solid, the promotion step is where mine leaks.
Mine leans on a closing habit to move things into decisions with a status, which is exactly where I fumble when a session ends mid-thought. So what actually triggers promotion for you: is it /handoff judgment each run, or does referencing a killed option force the ADR to exist on the spot?
Honest answer: neither.
/handoffis the disposable layer, it never makes the tombstone. It just carries ungraduated decisions forward and flags them as "not in an ADR yet," so that window you spotted is real, the handoff makes it loud instead of closing it.The real trigger is at decision time: /dev-plan writes ADRs up front, /task has to stop and escalate the second it hits one not already covered. Closest thing to a forcing function, but yeah, nothing forces the ADR the instant a killed option gets referenced.
So mine leaks where yours does, just a step earlier. The fix is the thing you are hinting at: make referencing a killed option spawn the ADR on the spot. Have not built it, but it is the first idea here that kills the judgment call instead of just moving it 😉
Right, and I think the cost hides one step before the spawn. To force the ADR the instant a killed option gets referenced, something first has to recognize that what /task is about to do re-enters a path you already killed. That recognition is the expensive part, and it only works if the killed option left an external handle behind: the thing you chose instead, a flag, a file path, something /task can match against. If the kill lives only as prose in an ADR body, the trigger fires on recall, which is the exact reflex you were trying to stop leaning on. So the on-the-spot ADR quietly depends on killed options being addressable, not just written down. When you sketch it, does a killed option get a stable handle /task checks against, or does catching the reference still come down to the model reading the right ADR at the right moment?
The choice that stood out to me is splitting the work by feature instead of by layer. A "frontend agent" and a "backend agent" both have to guess the contract where they meet, and that seam is exactly where agents drift. Giving one agent the whole slice means the spec it reads is the whole story, with nothing important hiding in another agent's head. The detail about measuring work in naps made me smile too, but that vertical slice is the part I'd steal.
the thing that gets me is a vague spec was always a problem - agents just made it immediate. before, a dev would fill gaps with judgment. now those gaps become literal bugs.
I really enjoyed reading your post. What particularly impressed me was not only the AI workflow but also the way you reinterpreted specifications not merely as documentation, but as engineering tools to reduce ambiguity. It felt like you were focusing on optimizing the quality of decision-making as well as coding speed.