STARTER GUIDE · 10 MIN

What is hornero and why do we use it?

Hornero turns what gets asked for in meetings into versioned specifications, agent-built code, and an end-to-end audit trail — all inside the git repo, with a person approving every step.

Think of it as a product assistant living in your repo: it reads the notes you drop, proposes what changed in the requirements, waits for your OK in the terminal, and writes everything down where you already work — no Jira, no external wiki, no extra system to keep in sync.

THE PROBLEM — why it exists

Requirements are born in conversations and die in documents. Three sprints later nobody knows whether something was built, who approved it, or why the code ended up this way.

WITHOUT HORNERO

  • Requests live in scattered notes; the trail is lost.
  • Specs (if any) drift from the code within weeks.
  • A coding agent gets vague instructions and hallucinates context.
  • “Why does this code look like this?” — nobody remembers.

WITH HORNERO

  • Every note is compared against the specs and proposes deltas with textual evidence.
  • The spec IS the tracker: its state lives in the file, versioned in git.
  • Agents receive a verifiable contract, not a “just do this”.
  • You can navigate: signal → delta → spec → task → PR → merge.

HOW IT'S USED — the loop, step by step

This is a normal day with hornero. Move forward with Next or click each stage — the terminal on the left shows what you'd actually see.

THE VALUE — what each side gains

FOR YOU (DEV)

  • Instant context: enter any repo and the wiki + specs orient you in minutes.
  • No re-discovering dead ends: DRs record what was tried and why it was rejected.
  • Less “ask whoever was there” — the repo remembers.

FOR THE TEAM

  • Full traceability: every line of code explains itself back to the meeting that originated it.
  • Agent prompts and rules sync across repos like dependencies, lockfile included.
  • Nothing approves itself: a human always decides, and it's on record.

FOR THE BUSINESS

  • Auto-generated HTML reports: what the product does today, without asking anyone.
  • Real audit of what AI agents built and under whose authorization.
  • Zero infrastructure: no server to operate, no SaaS to pay for.

MINIMAL GLOSSARY — 8 terms and you can follow any conversation

signal
Any text that comes in: meeting notes, a doc, an idea. It goes into .hornero/inbox/.
delta
A proposed requirement change: something NEW, CHANGED, OBSOLETE or a DUPLICATE relative to the specs.
verbatim evidence
Every delta must quote its source character for character. If the quote doesn't match, the delta is discarded — that's how hallucination gets stopped.
HITL (human-in-the-loop)
The human review in the terminal: approve / reject / edit / skip. Without an interactive terminal, nothing gets written.
spec
A requirement as a markdown file in sdd/specs/. Its frontmatter carries the state: proposed → approved → building → review → done.
dispatch
Sending an approved spec to a coding agent to build it. The result comes back as a PR to the same repo.
trace / DR
The trace records every agent action; the Decision Record summarizes it with verified citations into those events. Never narrative without evidence.
drift / diverged
State of toolkit files vs. their upstream. diverged = changed on both sides → a human resolves it, never a heuristic.

YOUR FIRST 15 MINUTES

git clone github.com/jelitox/hornero && uv pip install -e .

Python ≥ 3.11. A single runtime dependency.

cd a-test-repo/ && hornero init

Creates .hornero/ and the sdd/ layout. Idempotent: running it twice breaks nothing.

echo "users keep asking to export the report as CSV" > .hornero/inbox/note.md

Your first signal. Any text works.

hornero reconcile --dry-run

See what deltas it would propose. Guaranteed: nothing is written (check with git status).

hornero reconcile → approve the delta → hornero build && hornero report

Open sdd/reports/traceability.html and follow the full chain from your note to the simulated PR.

GOLDEN RULES — remember only this and you're set

1

Evidence is verbatim or the delta dies. Never “fix” a quote that doesn't match — discard it.

2

No human, no writes. If reconcile didn't ask you, it applied nothing. That's a feature, not a bug.

3

The spec wins. When code and spec disagree, the spec wins — and the discrepancy gets recorded.

4

diverged = stop and ask. Never force-merge toolkit files; use --theirs or --ours deliberately.

5

Nothing billed by surprise. The api backend only runs if someone explicitly wrote it first in the config.

github.com/jelitox/hornero · MIT · questions → team channel the ovenbird builds its house layer by layer 🪶