1. Introduction

This article is the fifth 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 terminology. The only command you type in Hora Kit is /hora. Depending on the situation, /hora calls /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 the 18 checkpoints), and /hora-accept (performs acceptance) in order. Only /hora-hotfix is not called by /hora; a person runs it directly. The docs call /hora-spec "the deciding side" and the rest "the building side", and this article uses those names as well.

In Hora Kit, a skill called /hora-spec writes the spec. In other words, an AI writes it. And yet it never ends up in a state where "the AI decided the requirements".

These two probably sound contradictory. In this article we write about how that contradiction is resolved, following the flow by which a spec comes together.

2. Why not have a human write it

First, why have an AI write it in the first place.

Part 2 of the docs opens with the sentence: "If specs/ is kept as a humans-only territory, the first step of every project becomes 'a step no one takes twice'." Being handed an empty spec and a description of the format is, in effect, an essay assignment. What is more, Hora Kit's format is strict: it requires use cases and acceptance criteria for each feature, the kind of each operation, two kinds of "out of scope", and an id that never changes. The person handed this writes only the parts that are easy to write, and /hora-plan ends up asking about the rest one question at a time, forever.

With a product that is already running, things get even worse. Have a person describe a 20-feature product from memory in this format, and they will talk only about what they remember. And the silence over the parts left unspoken reads exactly the same as "there is nothing there".

That is why /hora-spec writes it. In exchange, every mechanism on this side is there to keep it from becoming "the AI decided the requirements".

3. Where you put things declares your intent

You do not need to write a spec before starting. You put what you have into three directories.

What you put in request/ and annex/ never becomes the wording of the spec by itself. It comes back to you as a proposal or a question, and only what you approve gets written. sources/ alone is treated differently: a document placed here and declared in the spec's Sources section is read as equivalent to the spec itself, and /hora-plan creates tasks from its contents.

When in doubt, put it in annex/. Nothing is lost by doing so. If the content is truly needed, it enters the spec through the dialogue.

4. Stage 0, and then 7 stages

Stage 0 is where what you handed over gets read. It reads request/ first, then sources/ and annex/, and then the rest of specs/1.0.0/. For a new project it passes in a single sentence; for an existing project it reads the repositories and documents and records each discrepancy between spec and code as one line per item.

From there, 7 stages run in order.

The order is a rule. Use cases first, screens later. If you start from the screens, requirements that have no screen disappear.

Each stage has the same 3 states as a checkpoint: passed, not passed, and n/a with a reason, nothing else. Only stage 5 can be n/a, and that is for versions that declare no frontend, for example an API-only version for a mobile app. Even a version with no authentication at all must state that fact and the reason in stage 6.

5. "Reading" is not "guessing"

This is the most important line on this side.

Read the code, draft what it shows, present it, and have someone say yes   Allowed
Read the code and write the requirements it implies                         Not allowed

What the invariant protecting specs/ forbids is guessing requirements. It has never forbidden reading. So stage 4 reads the existing migrations, models, and API schemas in depth, and stage 6 reads the authorization filters and role checks to establish "who can call this operation today". Since that is a fact, it comes out as a confirmation.

On the other hand, "who should be able to call it" is a decision no one has made. That comes out as a question.

6. There are three ways to ask, and they must not be mixed

When a skill puts something to a person, it takes one of three forms.

Confirmation   "This is how I read it. Is that right?"
Proposal       "I recommend doing it this way. You decide."
Question       "This is decided nowhere. What is it?"

The docs name the direction in which this distinction collapses. The danger is presenting a proposal in the form of a confirmation. The person answers "yes, that's right" to something the skill invented, and it enters specs/ as an existing fact.

For example, the sentence "this screen has an error state" is a confirmation if it is in the code, and a proposal if it is not. Since the same sentence must not mean both, when it is a proposal it is always written as "I propose adding an error state to this screen".

7. Approval is per section

Each section is presented in full, and only once you approve it is it written to spec.md.

Incidentally, proposals are not merely permitted; they are required. A person asking for a product describes the product in their own head, so its gaps are invisible from the inside. Breaking down the request, presenting a better shape for a flow, and naming cases no one had thought of are the value of this side. What is forbidden is a proposal that slips in silently, not proposals themselves.

8. Questions come back "batched"

Placing 20 documents does not mean being asked 20 times. The confirmations of stage 0 are one round trip for all of sources/, one for annex/, and one for request/. After that, there is only one more round trip about anything you want to move to a different place.

We believe the burden of the dialogue is determined not by "the number of questions" but by "the number of times you are asked the same thing", and batched confirmations eliminate the latter.

9. About real examples

Sample specs actually written by /hora-spec are currently being prepared. We plan to publish sample code and specs for an application on the scale of several hundred thousand lines, and will replace this section once they are published.

10. From the second version on, it becomes a diff

From the second version, spec.md writes only the diff against the previous version. Most of what the 7 stages decide has been settled in the previous version, so a stage whose sections this version does not touch presents the immediately preceding version's answers, obtains confirmation, and passes with a carry-over note.

<!-- carried: 1.0.0's numbers, confirmed unchanged -->

This is a confirmation, not a guess. A carry-over is the only kind of pass that is indistinguishable from a stage that never ran, so without a record of the confirmation the two cannot be told apart. Stages 6 and 7 alone never carry over for what that version adds. Who may call a new operation is always stated in the version that introduces it.

11. Summary

"Let the AI write the spec" turns into "the AI decides the requirements" unless it is done well. Hora Kit places four lines in between: reading is free but guessing is forbidden; confirmation, proposal, and question are never mixed; approval is per section, showing the full text; and the order is a rule, with use cases first.

We hope this is useful to anyone who has tried to have an AI write a spec and is stuck with a result they cannot trust.

The original sources are here. https://github.com/openreachtech/hora-core/blob/main/docs/quick-start.ja.mdhttps://github.com/openreachtech/hora-core/blob/main/docs/architecture.ja.md