Hora Kit is two machines sharing one document
The first article in the series "The design of Hora Kit." It extracts only the skeleton of the 40KB design docs, so that you can first get the big picture, "two machines sharing one document," into your head as a map. It explains /hora-spec on the deciding side and /hora on the building side, the human-approved spec placed between them, and the four layers that support the building side.
1. Introduction
This is the first article in a series explaining the design of Hora Kit, the AI development framework that we (Open Reach Tech) released as open source. The main article is here.
We open-sourced Hora Kit, an AI development framework for truly automated development
A note on terms. There is only one command to type in Hora Kit:
/hora. Depending on the situation,/horacalls/hora-spec(writes the spec),/hora-setup(creates the implementation repositories),/hora-plan(fixes the version and writes the feature list and contracts),/hora-build(takes one feature through 18 checkpoints), and/hora-accept(acceptance), in order. Only/hora-hotfixis not called by/hora; a person types it directly. The docs call/hora-spec"the deciding side" and the rest "the building side," and this article uses the same terms.
Among the Hora Kit docs there is a document called architecture.ja.md, and it is 40KB. We would like you to read all of it, but 40KB out of nowhere is heavy, so the purpose of this article is to extract only its skeleton and get the big picture into your head first. The details are left to the docs, or to the other articles in this series.
To give the conclusion up front: Hora Kit is "two machines sharing one document." Once that sentence clicks, every later article can be read as a zoomed-in view of some part of this picture.
2. Two machines and one document
The first machine is /hora-spec. In dialogue with the person who wants the product, it decides what to build and writes it into the spec. The second machine is the building side: /hora calls /hora-setup, /hora-plan, /hora-build, and /hora-accept in order, and actually builds what the spec says. The docs refer to this second machine simply as /hora, after the name of the orchestrator.
The only thing the two machines share is one file, specs/<version>/spec.md. That is why each can be explained on its own, and why either one can be swapped out by itself.
/hora-spec | /hora | |
|---|---|---|
| What it produces | specs/<version>/spec.md | The implementation repositories and .hora/ |
| Unit of work | One section of the spec. Gets approval before writing | One feature. Passes 18 checkpoints |
| What it does when there is a gap | Asks, proposes, and writes only what is approved | Stops, and says what in specs/ needs fixing |
| What it never does | Design nobody approved. Touching git or the implementation repositories | Inventing requirements |
A word on why these two are separated. If a single agent is entrusted with everything from organizing requirements to implementation, then when something not written in the spec comes up, the agent decides it for the convenience of the implementation. The decision itself sinks deep into the conversation log, so tracing "why is it like this" afterward becomes hard.
Separating the machine that decides "what to build" from the machine that executes "how to build it," and placing only a human-approved document between them, is Hora Kit's answer to this problem.
3. Spec by dialogue, implementation by automatic execution
The two machines differ in how much human attention they need.
/hora-spec is worth having a person sit with at every stage. It is a dialogue from beginning to end, and if you cut corners here, the spec ends up as "a list of feature names." /hora, on the other hand, can be left running. When it needs an answer, it stops and asks rather than filling the gap by guessing, so letting it proceed automatically is not dangerous.
The docs call this division "spec by dialogue, implementation by automatic execution." The reason automatic execution is safe on one side and not on the other is only this difference: whether it stops.
4. The four layers
Breaking the /hora side down a little further gives four layers.
| Layer | What it decides | What it never does | Shipped by |
|---|---|---|---|
/hora | Which stage comes next. Every branch, commit, and merge | Anything about the content of the work | @openreachtech/hora |
The 5 skills (/hora-spec /hora-setup /hora-plan /hora-build /hora-accept) | The order of work, and the exit condition of each checkpoint | How it is written | @openreachtech/hora (only /hora-setup comes from the boilerplate) |
| Stage skills and the 3 agents | One section of the spec, or one checkpoint's worth of code or judgment | Its place in the order. Anything about git | @openreachtech/hora |
| The 4 skill packages | Every procedure, and every pass/fail criterion | When it gets called | @openreachtech/hora-skills-ort-* |
From top to bottom, responsibility shifts in the order "when" → "what" → "how." An upper layer does not know the contents of the layer below, and a lower layer does not know when it will be called. The row that surprises people most in this table is the fourth: Hora Kit itself holds neither how a resolver is written nor the shape of a table. The reason is in the second article of the series.
The roles of the three agents are as follows.
hora-implementerwrites the code and tests for one checkpoint, or one unit. It does not touch git or.hora/hora-verifierchecks whether a checkpoint's exit condition is truly satisfied. It is read-only and does not fix anythinghora-digestersummarizes one equipped skill down to a size the implementing agent can keep resident
And none of these four layers lives inside the project's repository. All of it arrives as npm packages; the repository holds only the spec and the records.
5. One skill that belongs to no layer
Only /hora-hotfix fits into none of the four layers above. It is the one skill /hora never launches, and it decides neither the order of work nor the exit condition of any checkpoint.
The reason is that what counts as an emergency is for a person to decide. A person calls it directly, it runs on main rather than on release/<version>, and /hora then rebases the open release line on top of its result. This route is covered in the tenth article of the series.
6. The two boundaries that hold everything up
The structure so far rests on two lines.
The first is the split of ownership. specs/ belongs to humans; .hora/ is written by the Kit. When there is a problem in specs/, what the Kit does is ask, not fix. A typo and a broken layout are treated the same. The docs say "allow 'it's trivial, let's just fix it' even once, and this rule disappears," and we think that is right. Only /hora-spec and /hora-plan can write to specs/, and both write only wording a person has just read and approved.
The second is the line that says classification may be inferred, but content may not.
| Examples | Treatment | |
|---|---|---|
| Classification | target, depends | May be inferred. It only attaches a label and adds no information |
| Content | Requirements, use cases, acceptance criteria, the kind of API operation | Inference forbidden. It would be inventing something the spec does not say |
| Permanent identifiers | id | Invention forbidden. Once decided, never changes |
What these two lines protect is, in the end, one thing: the invariant that a requirement never enters specs/ without a person having read its wording.
7. The two approaches this shape rejects
The docs explain this structure by contrast with "the other way."
The first is keeping specs/ as a humans-only area. Someone handed an empty spec and a format guide writes the parts that are easy to write, and /hora-plan ends up asking about the rest one question at a time, forever. The docs call this "a step nobody takes twice." So /hora-spec takes over the writing, and in exchange, all the mechanisms that keep it from becoming "the AI decided the requirements" are concentrated there.
The second is building layer by layer. With the order "the whole backend, the whole frontend, then tests at the end," design flaws surface only at the end, by which point everything is stacked on top of them.
The current shape, split into two machines and passing checkpoints per feature, is the inverse of these two.
8. Summary, and what to read next
Drawn as a single picture, Hora Kit is a human-approved document in the middle, with the deciding machine and the building machine reading it from either side. A person sits with the deciding side; the building side can be left alone. This asymmetry runs through the whole design.
The other articles in this series each zoom in on one part of the picture above.
- The division between the 4 skill packages and the Kit: Why Hora Kit holds not a single procedure
- Repository layout: A repository with no implementation code directs the whole project
- The
/horaside: The 18 checkpoints and 4 gates one feature passes through - The
/hora-specside: Let the AI write the spec, but never let it decide the requirements - State and records: A re-entrant orchestrator with no state file
The original is here. With the map in hand, even 40KB is surprisingly readable. https://github.com/openreachtech/hora-core/blob/main/docs/architecture.ja.md
