Article 7 of 12 · ARTHA Craft
A codebase full of 80% complete features. One template ended that permanently.
Let me tell you how this methodology actually started.
Not with a framework. Not with a plan. With a wall.
I was building with AI agents the way most people do, describing what I wanted, letting the agent build, moving fast. Features were appearing. The demo was growing. The speed was genuinely exciting.
Then progress stalled.
The Origin Story: Three Phases
Phase 1: Pure Vibe Coding
Fast output. Features appearing in hours. Agent building confidently in every session. No structure. No design before build. No defined destination. Progress felt real.
Phase 2: The Wall
Codebase full of 80% complete features. Functionality working in isolation, broken in combination. Sessions starting new things without finishing old ones. Agent guessing at destinations that hadn't been defined. Progress stalled.
Phase 3: Two Things at Once
The Step Sequence gave visibility across everything. The Task File gave each step a complete design before coding started. Progress became measurable, predictable, and continuous. The guessing stopped.
Pivot 1: The What
The Step Sequence
A complete, ordered list of every feature the product needed. Not a rough backlog. Every item a discrete, buildable unit of work with a clear status. For the first time: visibility across the whole product. What was done. What was in progress. What hadn't been started. What was blocking something else.
Pivot 2: The How
The Task File
A structured document, one per step, that translates a feature from "here's what I want" into "here is everything the agent needs to build this exactly right, the first time." Not a prompt. A design document. Written before the coding session opens. Reviewed and locked by the architect.
The task file has twelve sections, a header, and two appendices. But the count is not the point, and getting fixated on it is how templates turn into bureaucracy.
That is the test for whether a section earns its place: name the failure it prevents. If you cannot, delete it. Here is what each one stops.
Why Prevents: a locally-sensible choice that is globally wrong
What problem this solves and how it fits the larger product. An agent that understands why makes better implementation decisions than one that only knows what. Every claim carries evidence: a file and line, a count, measured output. "The console is dead" is an assertion. The failing call and the missing error handler is evidence. Keep it short: this is the section most likely to become decoration.
Current State & Re-Verify at Claim Prevents: building on a tree that moved
What already exists that this step extends, and then an executable gate the coder runs before building, because upstream work lands between authoring and claiming. Assert the negative too. Any mismatch is a blocker that stops the work and raises it, never something to adapt around silently.
Decisions: Locked and Delegated Prevents: the agent inventing what the architect should have decided
Every significant decision already made, numbered so reports can cite them. For anything with a UI, the approved design is attached as an input. A pointer is not a design. Then the part most templates miss: what the coder may decide alone, within stated bounds. That is the legitimate third state between "architect decided" and "blocked". Without it, every micro-decision escalates. Bounded, never a dumping ground.
Gaps & Resolutions Prevents: open questions discovered during coding
Every open question found during planning and its answer. Blocking by default: resolved before go-ahead, not during. The real value is as an anti-complacency check: it forces the author to show they went looking. If nothing was found, say so explicitly. A silent gap and a closed one look identical on the page and mean opposite things.
Scope Boundary Most Critical
Prevents: the agent expanding into the neighbouring feature. Two axes, and both are needed. The capability axis names every adjacent thing the agent might logically extend into, and excludes it. The file axis is the explicit path list bounding blast radius. Two axes because file scope is mechanically checkable and capability scope is not.
Cross-Layer Contracts & Composition Prevents: silent breakage between sessions
Distinct from scope: scope is a permission boundary, this is an interface obligation. What the layer above expects, what the layer below provides, and for every seam its signature and what is bound where. Then the part almost everyone forgets: state how this step is reached from a running entrypoint. A component nothing can reach is not delivered, however green its tests.
Guardrails & Laws Prevents: quietly violating a product-wide invariant
The non-negotiable rules of the system, written out in full, in every task file. Deny-by-default is code, not policy. An unrun check is a gap, never an implied pass. A degraded state must never be indistinguishable from a healthy one. The reader is a cold-start agent: it has not read your other files.
Execution Mode & Stop Conditions Prevents: silent workarounds
How this runs, solo, parallel, backend-first, and the named conditions under which the agent must stop and raise rather than proceed: two locked instructions conflict, an upstream contract does not match the delivered code, a law cannot be honoured without weakening it. None of these is ever resolved by weakening a test, padding an allowlist, or relabelling a failure. When several agents work one branch, this section also carries the ownership map and commit discipline.
Waves, TODO Board & Checkpoints Prevents: big-bang delivery and invisible progress
Work split into independently committable, independently verifiable chunks. A live TODO board the agent maintains while work is in flight, not reconstructed at the end, so progress is visible rather than reported. And a checkpoint printed at the end of every wave: what was built, what proved it, the evidence, and any surprise. Naming "surprise" as a required field is what surfaces the second root cause instead of burying it.
Acceptance: Static Prevents: "done" being a claim rather than a state
What proves it without a running stack, as a ticked checklist written before the code. Named tests, the exact test function, so "did they write the load-bearing test?" is a lookup, not an opinion. Clean type-check, lint and build. Proof the diff stayed inside the declared file scope. Docs and registers updated in the same commit, not a follow-up.
Acceptance: Runtime Prevents: static proof standing in for runtime proof
What requires the artifact actually running: real journeys on a production build, live data through the real API. Never merged into the static section. Each item is observed, or explicitly marked deferred with its reason, never implied to have passed. This exists because screens passed their unit tests and then rendered an endless loading skeleton in a browser. "I proved the code" kept standing in for "I proved the running thing."
Report Contract Prevents: verification resting on trust
The exact evidence handed back, named in advance so the agent knows before it starts what it will be asked to show. Not "it works": the commit and its diff, the before/after impact, the re-verification output pasted in, what ran versus what was deferred, what was not changed and why, and every judgement call flagged rather than guessed. Lead with the observation that needs an owner decision. Never claim a green you did not observe.
And two appendices
A · Go-Ahead Prompt
The exact prompt pasted into the coding session: written during planning, reviewed, locked, self-contained. It is an appendix rather than a section because it is derived from the twelve, not a peer of them. When this drifted into something improvised at send time, it produced an instruction that made its own task impossible.
B · Amendments
Spec changes made before the work is claimed, recorded with a version bump and a date, so the spec can evolve without rewriting history. Once an agent is running, changes go to the ledger, never silently into the file underneath it.
Every task file is self-contained
Each one goes to a fresh agent with no shared context. Never replace content with a pointer to another document: referenced files get loaded partially, or not at all. Repeating the guardrails across every file is correct, not waste. DRY is a source-code principle, and it is wrong here.
One file per step
An earlier version split the brief from its pre-implementation research. They drifted, and newer files silently dropped whole sections. One file means one place to drift, and drift you can see.
Sections may be brief when a step is small. But an omission has to carry its reason, "none, searched, none found", because a silent gap and a closed one look identical in a file and mean opposite things.
Section 4: Why This Changes Everything
The section that stopped more breakages than any other.
Before the scope boundary, every coding session had a tendency to expand. The agent would complete the feature and then, being helpful, start the adjacent one. Or add an improvement that wasn't asked for. Or create a dependency on something that hadn't been designed yet.
None of this was malicious. All of it was expensive.
The scope boundary stops it. It tells the agent: this is where this step ends. Not because the adjacent work isn't valuable, but because the adjacent work has its own step, its own design, its own go-ahead moment.
Build this. Stop here. The next step will be built when it has been designed.
One section. Prevents an entire category of cascading breakage.
Nothing improvised. Nothing incomplete. Nothing that breaks the adjacent feature because it expanded past its scope boundary.