Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Design & UI

hora-spec-backend

Stage 4 of /hora-spec. Declare the repositories and servers, then design the data model, the operation list and the background jobs that every stage-1 use case can be walked against. Invoked by /hora-spec, or directly.

openreachtech · Static checks on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

npx skills add openreachtech/hora-core --skill hora-spec-backend

About this skill


name: hora-spec-backend description: Stage 4 of /hora-spec. Declare the repositories and servers, then design the data model, the operation list and the background jobs that every stage-1 use case can be walked against. Invoked by /hora-spec, or directly.

hora-spec-backend

Stage 4 of /hora-spec. Design what holds the data, what operates on it, and what runs outside the request — and prove, use case by use case, that the result can serve them.

Read ../hora/references/structure.md and ../hora-spec/references/principles.md first. ../hora-spec/references/stages.md is the authority on this stage's exit condition, ../hora/references/spec-format.md on the format of every table written here, and ../hora/references/asking.md on how anything is put to a person.

This stage holds no design rule of its own. How a table is shaped, how an API schema is named, where a job belongs and how a queue is tuned all live in the @openreachtech/hora-skills-ort-* packages. Invoke the skills the delegates table names and read them — never restate one of their rules here.

What this stage reads

This is the stage that reads the backend properly: the migrations, the models, the API schemas, the REST routes, the job definitions and the entry points, at depth.

The whole existing data model and operation list goes out as checks, batched per area — one for the tables, one for the operations, one for what runs outside the request. A person confirming the fourteenth table in a row has stopped reading (../hora-spec/references/investigation.md).

A check on the data model says what the product remembers, not which columns hold it (../hora/references/asking.md, "What changes for the person").

A feature listed under Baseline: inventoried still owes its tables and its operations a row each here. The section itself carries a name and one line (../hora/references/spec-format.md, "baseline") — but its tables are in the database everything designed here has to fit around, and its operations sit on a server stage 6 has to state a caller for. It costs almost no exchanges, since those rows sit inside the batched checks above.

Read it, put it up as a checkAsk, or propose
which tables exist, and what columns they holdwhy the model came out that way, and what it rules out
which operations exist, and what each returnswho each operation is for
which work already runs outside the request pathwhether work that runs in the request still belongs there
what the existing tests assertwhether what they assert is what anybody wanted

A shortfall found while reading is a proposal, never a check. "There is no index on this foreign key" states a fact; "add one" is this stage's own thinking.


What this stage decides

which repositories exist, and which servers run inside the backend
one endpoint switched on role, or an endpoint per audience
what tables hold, in logical terms
which operations exist, of which kind, against which server
which processing does not run inside a request, and why not

What it must not decide

Whose it is
a new use case, or a use case's wordingstage 1
whether a feature is in this releasestage 2
a user count, a retention period, an availability targetstage 3
which screen calls an operationstage 5
who may call an operationstage 6. This stage writes the operation; stage 6 writes its caller
a class name, a table name, a column name that lint has to accept/hora-plan, against the lint rules
the migration, the model, the resolver, the job class/hora-build, at checkpoints 3 to 7

The order inside this stage

1. The repositories, and the servers inside the backend
2. Roles on one endpoint, or endpoints of their own
3. The data model
4. The operations, per server
5. What runs outside the request
6. Walk every stage-1 use case against 3, 4 and 5

Step 6 is the exit condition, not a review. A data model that is internally tidy and cannot represent one stated use case passes every other check in this document.


1. The repositories and the servers

Declared, never assumed — /hora-setup reads this table and stops without it.

| Repository | Origin | Role |
|---|---|---|
| `acme-backend` | `<a backend origin>` | the API and jobs (holds the DB) |
| `acme-frontend-employee` | `<a frontend origin>` | the employee-facing screens |
| `acme-frontend-admin` | `<a frontend origin>` | the admin screens |

### 2.1 Servers

| Server | protocol | consumer |
|---|---|---|
| `employee-api` | (the default style) | `frontend-employee` |
| `admin-api` | (the default style) | `frontend-admin` |
| `worker` | — | an API server in the same repository (no contract needed) |
  • Origin comes from the origin catalog, and so does each origin's row count (../hora/references/structure.md, "How to find the origin catalog"). A count outside an origin's stated bounds — a second backend, say — stops the run
  • Frontends are zero or more. An API-only release declares none, and stage 5 is then not applicable
  • Names read <myproject>-<role>-<purpose>, from stage 1's project name
  • The server table is the unit contracts are cut from, so it is always written. consumer decides whether a contract exists at all
  • A repository that already existed gets the optional Directory column, and /hora-setup then never clones it

Everything else about this table is in ../hora/references/spec-format.md.

2. Roles on one endpoint, or endpoints of their own

The most consequential choice this stage makes. ../hora-spec/references/principles.md holds the full decision table; the three cases in one line each:

The situationWhat to do
roles come and goone endpoint, switched on role
genuinely different entities — a different login, a different lifecycle**separate endp
Read the complete source ↗