DEV Community: Halfcycle

Nine blockers on a feature that was two screens and a button

Halfcycle — Fri, 09 Oct 2026 19:45:24 +0000

Halfcycle is a module that runs a five-layer build method inside your own Claude Code (npx halfcycle).

Most process claims cannot be checked, because nobody writes down the bugs that never happened. Here is one that can.

A real feature on a live product: let somebody restore an older version of a document they had edited. Small by any measure. Two screens of work and a button. It was reviewed five times before anybody was allowed to start building.

Blockers found each round: six, then two, then one, then none, then none. Nine in all.

Here are eight of them. The first four would have reached real users.

Restore could overwrite a file that is meant to be locked. The rule was enforced in the normal save path, and nobody copied it into the new restore path. Every test of the new code passes. There is no failing assertion to find, because the thing that is wrong is a rule that is not there. Somebody has to notice an absence.

The undo feature could destroy the backup it exists to protect. Save a backup, update the search index, commit, all one step. If the index update failed, the backup was discarded and the new content had already been written. The window is small and the loss is total.

The button would never have appeared for anybody. It was keyed on a piece of data the system only attaches to exactly the records the feature refuses to act on. The code is correct in isolation. It ships to nobody, silently, and every test is green.

Restoring a document would have silently deleted its labels. A shared helper wipes all labels and puts back whatever it is handed, and the design handed it an incomplete list. Nothing fails. Nothing logs. The loss surfaces weeks later, somewhere else, and looks like a different bug entirely.

The plan described a bug that did not exist. It came from a search of the codebase that was accurate and drew the wrong conclusion from what it found. Everything downstream of it would have been solving a problem that was not there.

The design could not be built where it was going. The place the plan chose to hang the new screen is a sibling of the thing it needed to replace, and a sibling cannot replace anything. Correct design. Wrong address.

The final checklist pointed at addresses nobody had ever written down. It survived four rounds of review doing that. It needed no knowledge of the code to catch — it is a mechanical check that a path exists — and it consumed an expensive human reader anyway.

The summary everybody reads first still described a plan three rounds had thrown out. The document had been fixed. The abstract at the top of it had not, and the abstract is the part people actually read.

The thing they have in common

Not one of them is a coding mistake.

Every one sits in a join: between two pieces of code, between two people's work, or between the plan and what was already there. An agent writing the file in front of it cannot see any of them, because none of them is visible in the file in front of it. Neither can a reviewer reading the change on its own, for the same reason.

That is the shape of how AI-assisted work actually fails now. Not bad code. Confident, well-tested, well-structured work built on something nobody examined.

And notice which tools would have caught which. A linter: none. A type checker: none. A test suite: none, and worse than none, because four of these ship green and green is read as evidence.

The honest part

Five rounds on a feature that small is heavy, and we are not going to defend it.

The first round alone returned six blockers. Rounds two through four found five more defects, and nearly all of those five were introduced by the previous round's own fixes. That is its own finding, and it is uncomfortable: the fixes are the highest-risk region of the work. A reviewer who asks for a change is the least able to see what the change broke, which is exactly why the next round has to run in a session that has never seen the last one.

The method was amended in four places because of this feature. What a scoping document has to mark as unverified before it travels. What a design has to check rather than assume. A cheap mechanical pass that runs before any expensive reader is spent on things a mechanical pass can do — the checklist pointing at nonexistent addresses should never have reached a human at all. And when the summary everybody reads first is allowed to be written, which is: last.

That is the loop working, and it is also the argument. A finding on one project becomes a step on every project after it, and nobody has to install anything for that to be true.

What it would have cost

The four that would have reached users are not equivalent to four bug reports.

The label deletion is data loss with a delayed and misattributed symptom — the kind that gets investigated as a different problem for a week. The backup destruction is a support conversation you cannot win. The button that appears for nobody is a feature that ships, gets announced, and generates no usage, and somebody spends a sprint on analytics before anyone opens the code.

Against that: five rounds of review on two screens of work, which felt excessive at the time and still does.

We do not have a number for what that trade is worth and are not going to invent one. What we have is the list above, which is checkable, and the note that every finding on it is now a step earlier in the process.

Getting started

npx halfcycle

Run that in the folder you want to work in, then open it in Claude Code and say what you are building. Needs Node 20 or newer. There is nothing to learn first and no next step to remember — it tells you what is next when it is next.

halfcycle.ai

The first useful thing it does is disagree with you

Halfcycle — Fri, 09 Oct 2026 19:44:19 +0000

Halfcycle is a module that runs a five-layer build method inside your own Claude Code (npx halfcycle).

Node 20 or newer, and Claude Code. That is the whole prerequisite list. Everything below happens in one sitting.

mkdir tally && cd tally
npx halfcycle

That command signs you in through your browser and creates the project your work gets recorded against. It talks to one address, the same one for everybody, and it ships in the CLI, so there is nothing to configure and no value anyone has to give you first. If it cannot reach us it stops and writes nothing, which is deliberate: a folder set up with no cover behind it is worse than one that is not set up at all.

When it finishes it points you at your project's page on the web. You can also just sign in at app.halfcycle.ai whenever you want.

Click one and you are looking at its console. There is nothing to set up and no second account — it is the same sign-in as the install.

The part worth opening on day one is the crew.

That is the team, live. Twenty-one agents grouped into builders, reviewers, and the ones that are always on. Each shows what it is for and how deep it goes, and each is busy, idle or stood down right now — not a log of what ran an hour ago.

You will not have much on that page twenty minutes in, and that is the point of looking at it early: you can watch it fill up. The first time you run real work, the page stops being a roster and starts being the answer to a question that has no good answer in a terminal. If three agents are running, "what are they all doing" gets you three scrollbacks and a guess.

The other page to know about on day one is the overview, which is where the project's shape lives.

Where each gate stands, which phase is active, and what is happening right now. A phase is a slice of the product that ships and can be shown to someone, and the strip along the top is every gate between you and closing this one.

On a solo project all of this sounds pointless right up until the first time you come back after two weeks away and cannot remember where you were. The console is a faster way to reload a project than your own notes, because it is a record of what happened rather than a record of what you meant to do. On a team it is the only place the work exists for somebody who was not in the session.

Then open the folder in Claude Code.

That is the last instruction in this article, which is worth pausing on, because it is unusual. There is no command to learn, no next step to remember, and no order to get right. Say hello, or say what you want to build, and it takes it from there.

The next ten minutes are questions

This is the part people are not expecting, so it is worth saying plainly: nothing asks you to fill in a form. It reads the folder first, works out what it can, and then asks you only the things it genuinely cannot answer.

The questions come one at a time, in an order where nothing gets asked before the thing it depends on. Each one arrives with a recommended answer and the reasoning behind it, so the cheap path is to read the recommendation and say yes. And where the answer is a fact about your repo rather than a decision, it has already gone and looked, and it shows you what it found rather than asking you to confirm something it could have checked.

You also cannot get ahead of it. Ask for something three steps away and it either does it, because that is what came next anyway, or it tells you why not and what is missing. There is no path through this where you skip a step by accident, which means there is nothing to hold in your head and no checklist to keep open in another tab.

The one thing it will not do is let you record a decision without a reason. Not a spelling of a reason. An actual one. This is the first place the tool has an opinion, and it is worth understanding why it holds it: in three months, the only difference between a decision you can revisit and a decision you have to re-litigate from scratch is whether anyone wrote down why. Every agent session after this one reads what you decided here. A decision with no rationale attached is a decision the next session will quietly reinterpret.

Answer them honestly rather than quickly. You are the only person in this loop who knows what you are building.

Then it asks what you are making

Say it in your own words. Not a spec, not a structured brief. A paragraph.

I want a thing where I can log what I ate and it tells me roughly what I have had this week. Just for me. Web, phone browser mostly.

What comes back is a draft of what you just described, longer and more specific than what you said, and about seventy percent right. That draft is not the product. It is the strawman, and the strawman exists because pushing back on a specific wrong claim is enormously easier for a human than answering an open question against a blank page. Anyone who has been handed a template with an empty "Non-functional requirements" heading knows exactly what that difference feels like.

So it drafts, and then it turns on the draft. Same interrogation shape as the setup: one question at a time, ordered, each with a recommended answer.

The moment worth waiting for

Somewhere in there, it asks you something you had not decided.

On a food log, it is usually this one, or a version of it: what happens when you log the same thing twice in one day. That sounds trivial. It is not, and here is the honest shape of why. If two identical entries are one row with a count, your weekly total is a sum over counts and your history is lossy. If they are two rows, your total is a row count and you can show the day back to the user exactly as it happened. Both are fine. But one of them is a schema, and you are about to build on it, and nobody was going to ask.

That is the intervention. It is not a bug caught. It is a decision surfaced before it became a default, which is the only time a decision is cheap.

The tell that it landed is that you stop typing for a second.

What you have after twenty minutes

Files, in your own folder, in plain markdown. The context your agent sessions read on every future session, the decisions you made and the reasons you gave, and the beginning of a description of your product that is more specific than the one in your head.

Nothing of ours is left in there. The process itself — the steps, the templates, the questions — arrives in the session that asks for it, sized for the step you are on, and is not at rest in your repository. What stays is what you wrote.

You have not built anything yet. You do not need to know what happens next, either. It will say.

Getting started

npx halfcycle

halfcycle.ai