openreachtech/hora-core/hora

hora

The orchestrator. Decide where this project stands, run the skill that comes next, and own every git operation on the way.

/hora does no implementation of its own. Five skills do the work:

An emergency fix is not one of the five. /hora-hotfix takes one defect to main on its own, gives up the acceptance review, and records what it gave up as a debt. /hora reports that debt; /hora-plan turns it back into work (../hora-hotfix/SKILL.md).

Replacing a running system starts before the five, and `/hora` never starts it. /hora-replace describes the old system from its code in several passes and proposes a scope, and a person places what it wrote in annex/ and request/ before /hora-spec runs (../hora-replace/SKILL.md).

Read references/structure.md before anything else — the repository layout, where a per-repository command runs, and the three invariants all come from there. references/commits.md holds every git rule.

The shape of a run

/hora-spec ─> /hora-setup ─> /hora-plan ──┬─> /hora-build #A ─> /hora-accept ─┐
                                          ├─> /hora-build #B ─> /hora-accept ─┤
                                          └─> /hora-build #C ─> /hora-accept ─┴─> sweep ─> merge

One feature goes all the way to acceptance before the next one starts. Backend, then frontend, then acceptance — per feature, not per layer. Building every backend task, then every frontend task, then testing, means the first time anyone finds out whether a feature works is after all of them are written.

Re-entrancy is the center. A single session does not run to the end. Each run decides where it is and continues from there. Nothing is ever redone because a session ended — every checkpoint's checkbox is written the moment it passes.

Serial down to the checkpoint. No feature ever runs alongside another, and no checkpoint alongside another checkpoint.

`/hora-fast` is the other scheduler. It builds several features at once, each in its own git worktree, on the same feature files this one writes. A person chooses it by invoking it instead of /hora (../hora-fast/SKILL.md).

Inside a checkpoint, its units do run together. Five of the eighteen divide into units whose files are exclusive — a table, a module, an operation, a component, a screen — and each gets an implementer of its own. The checkpoint stays one gate with one exit condition (../hora-build/SKILL.md, "Step 5 — splitting a checkpoint into units").

Whether hora can start at all

The procedures `/hora` orders are not in this repository, and /hora never puts them in place itself. They arrive as skills of their own, alongside these, and this is the one thing to confirm before deciding anything else.

Is there at least one skill under .claude/skills/ whose name carries an
hoc- / hor- / hof- / hos- prefix?
                             if not → stop. Report that the implementation
                                      skills are not equipped, and ask for
                                      them to be equipped before rerunning
 
Is /hora-setup under .claude/skills/ too?
                             if not → stop. Report that code setup is not
                                      equipped, and ask for it before
                                      rerunning

`/hora-setup` is asked for here because it is not in this package either. What it does is one stack from beginning to end — which repositories exist, what fills them, what to read once they arrived — so it is written by the boilerplate that knows that stack, and equipped from there. /hora orders it like the rest, and a project whose boilerplate has not put it in place cannot get past step 2.

Nothing here checks the hora skills themselves. /hora is one of them, so a session that reached this line has already proved they are equipped. What cannot be known from the inside is the other package's state, and that is the whole of what this section asks.

A partial set is not a failure. Which of them a repository equips is its own decision, and a checkpoint that finds nothing covering its work says so and carries on (references/structure.md, "How the match is made"). Only the empty case stops, because there nothing is covered at all.

How they are equipped is not this file's business. Say what is missing, not what command to run — the route differs by repository, and naming one of them here would be wrong wherever the other is used.

Deciding where you are

With that settled, do this every time — a fresh start and a restart alike.

0. git fetch origin --prune, for the hora repository and every declared row
   that already exists. Then check for a hotfix that landed on main
   (references/commits.md, "Keeping release/<version> current"), and read
   .hora/hotfix/ for any record whose debt: still reads open.
   Then git -C <row> worktree list, for every declared row: a worktree under
   .worktrees/ is a feature /hora-fast has in flight. Stop, and say to drain
   it through /hora-fast (../hora-fast/SKILL.md, "Switching between the two
   schedulers")
 
1. Does the target version have a spec at all — a specs/<version>/spec.md with
   content in it?                             if not → /hora-spec.
                                              A version with no spec declares no
                                              layout, so /hora-setup has nothing
                                              to read and /hora-plan nothing to
                                              verify
 
2. Are all declared repositories present, per the current spec's layout?
                                              if any is missing  → /hora-setup
 
3. Always run /hora-plan. It fixes the version, and reconciles the feature
   list against specs/ on every re-entry
 
4. Does .hora/questions/<version>/open.md still hold an unresolved
   blocking: yes?                             if so → stop, unless the run
                                              may go on past it (step 4,
                                              after this list). Report what
                                              to fix
 
5. Does .hora/tasks/<version>/_plan.md still hold an unfinished feature — an
   entry with a [ ] box that the ## Acceptance sweep entry does not already
   close?                                     if so → /hora-build, on the
                                                      first one that is ready
 
6. No [ ] entry remains that the ## Acceptance sweep entry does not close, and
   _sweep.md's newest block does not read reach: full with a passing verdict,
   a version-criteria: line accounting for every criterion the version
   declared, and a tips: line every declared row's release/<version> still
   points at                                  → /hora-accept, whole-version
 
6a. It does, and entries that sweep closes still stand [ ]
                                              → /hora-plan again, to set them
                                                and their checkpoint 18 off
                                                that block (../hora-plan/
                                                SKILL.md, "collapses to one
                                                sweep")
 
7. _sweep.md's newest block reads reach: full with a passing verdict, a
   version-criteria: line accounting for every criterion the version
   declared, and a tips: line every declared row's release/<version> still
   points at, and every entry in _plan.md is [x]
                                              → merge (references/commits.md,
                                                "Merge order into main";
                                                references/done-criteria.md,
                                                "When a version is done",
                                                conditions 1 and 3)

Step 0 is also what catches `release/<version>` up with a `hotfix/*`. /hora has no scheduler: this fetch and the one right after every merge into release/<version> are the only two occasions it gets to notice one landed on main.

An open hotfix debt is reported here, never acted on here. Step 3's /hora-plan is what turns it back into work (../hora-hotfix/SKILL.md, "Paying the debt back").

Step 4 stops only where `Whether the run may go on past an open blocking question` (`../hora-plan/SKILL.md`) says no. The decision lives in /hora-plan, beside the question file it reads, so /hora and /hora-plan never answer it differently.

`/hora` does not ask before running this check, or before acting on an ordinary result. It stops and asks once the check turns up something it cannot resolve on its own.

Step 1 is not "write the spec for them". /hora-spec writes nothing without somebody reading it first, and a run that reaches step 1 with nobody there to answer stops there.

Step 3 runs even when the feature list already exists. A spec keeps moving while implementation is under way. Only once /hora-plan's reconciliation shows no difference does a version move on.

Step 5 reads only the entries that carry a checkbox, so a listed feature is never a candidate. A feature listed under Baseline: inventoried sits under _plan.md's ## Not accepted with no box at all, so it is neither done nor unfinished. A version whose every remaining feature is listed passes step 5 and is swept at step 6 (references/spec-format.md, "baseline"). Paying the debt is a later version's ordinary work, scheduled by a person.

Step 5 also passes over an entry whose checkpoint 18 the `## Acceptance` sweep entry covers. Its [ ] means the sweep will close this, not hand this to `/hora-build` (../hora-plan/SKILL.md, "collapses to one sweep"; ../hora-build/SKILL.md, "Where to start").

Steps 6 and 7 read the newest block's own `reach:`, never whether `_sweep.md` exists. That sweep may be invoked before every feature is done, and every run appends a block, so the file's presence says only that it ran at least once. A sweep invoked at the eighth of twenty gates writes a truthful reach: scoped.

They read `version-criteria:` beside `reach:`, for the same reason one level up. reach: full says the run reached every feature acceptance could reach; the version's own criteria reach no feature's gate at all (references/spec-format.md, "15. Version acceptance criteria").

They read `tips:` because a pass describes the code it drove. Step 0's hotfix catch-up, a retake or an update/ merge after the sweep moves a tip, and the pass no longer covers what would merge (../hora-accept/SKILL.md, "Recording the result").

Keyed that way the two steps leave no gap. Whatever fails step 7's test — no record, reach: scoped, a failed verdict, a short version-criteria: line, a stale or missing tips: line — satisfies step 6's predicate, so the run goes back to /hora-accept.