hornero 🪶

Repo-native product loop: requirement signals → living memory → SDD specs → dispatched builds → HTML reports. Everything lives in your git repo; nothing needs a server, a database service, or a SaaS.

El hornero (ovenbird) builds its own house, layer by layer — so does this tool: hornero is developed with the same spec-driven workflow it implements (fully self-hosting).

What's new in 0.4.0.post13001

Added

• Publish reproducible workflow documentation, an executable offline quickstart, Spanish and English zero-to-production videos, and a graph-derived command cheatsheet for building updated Hornero infographics.

Full changelog · Compare changes

What it does

 meeting notes, docs, ideas          you                     coding agents
        │                             │                            │
        ▼                             ▼                            ▼
 .hornero/inbox/  ──reconcile──▶  HITL review  ──apply──▶  sdd/specs/*.md
        │            (LLM drafts      approve/reject           │
        │             deltas with     /edit/skip               ▼
        │             VERBATIM        in your TTY         hornero build
        │             evidence)                          (spec → brief →
        │                                                 mock/cli backend)
        ▼                                                      │
 .hornero/knowledge/  ◀──reindex──  write-back: code + spec + reports
                                    land in the SAME branch/PR
        ▼
 sdd/reports/*.html   (capabilities, workflows, traceability — offline, deterministic)

• Signals in: drop meeting notes / docs into .hornero/inbox/.
• Project factory: create a Git repository and runnable stack from a composable, versioned blueprint; lock hashes expose local drift.
• Reconcile: an LLM drafts RequirementDeltas (NEW / CHANGED / OBSOLETE / DUPLICATE) — every delta carries evidence that is a mechanically verified substring of the source signal. No evidence, no delta.
• Human gate: nothing mutates a spec without an interactive approval (approve / reject / edit / skip). No TTY → no writes, by design.
• Specs are the tracker: markdown files with YAML frontmatter under sdd/specs/; status transitions and comments are written into the files themselves. ADRs in sdd/decisions/, low-confidence ideas become brainstorm proposals in sdd/proposals/.
• Build: approved specs are rendered into build briefs and dispatched to a coding-agent backend (mock by default; cli/api are explicit opt-ins).
• Reports: capabilities.html, workflows.html, traceability.html — the full audit chain signal → delta → spec → SDD tasks → PR → merge, with honest gaps.
• SDD toolkit sync: hornero sdd install|status|diff|sync manages your .claude/ + sdd/ toolkit files against an upstream repo with a committed lockfile and a three-way drift model — like a package manager for prompts, where diverged files are never auto-merged.
• Agent-facing wiki: wiki/ is a second projection of the knowledge layer, written FOR the next agent run — watermark-scoped surgical updates, anti-stub and link-check gates, and a no-op discipline that makes scheduled refreshes churn-free (quiet days produce no PR).
• Code as signal: opt-in GitSource turns commits into requirement signals so specs and code never silently drift apart.
• Flight recorder & scribe: every dispatch leaves a redacted action-stream trace; the scribe distills it into a Decision Record whose every claim cites a verified event range — and past rejections resurface in the HITL preview before you approve a repeat.
• Semantic project graph: sources, requirements, criteria, controls, tasks, code, tests, decisions and findings are connected with source hashes and evidence locators. validate repairs derived state and fails closed on corrupt traceability.
• Continuous improvement: deterministic architecture, security, compliance, dependency, performance, quality, test, documentation and graph packs produce stable findings. Approved low-risk work runs in an isolated Git worktree; gates must pass before a review branch is retained.
• Temporal intelligence: immutable entity versions, supersession, contradiction/duplicate candidates, impact paths, coverage scores, explainable queries and token-budgeted context packs.
• Production factory: signed blueprint registries, three-way upgrades, capability resolution, production components, generated contracts and federated multi-repository plans.
• Assurance: expiring finding baselines, declarative policy packs, offline SBOM/vulnerability input, STRIDE threat models and evidence mappings for SOC 2, ISO 27001, GDPR and PCI.
• Autonomous runtime: signed webhook/schedule events, resource sandbox, budgets, retries, risk approvals, provider-neutral PR creation, metrics and bounded feedback learning. It never merges a branch.
• Independent perspectives: ground one neutral brief in specs, decisions and diffs, fan it out concurrently through Multicoders, preserve every provider opinion and require explicit finding dispositions.
• Grounded mockups: edit a real product screenshot through Codex image generation, validate and hash each named PNG view, retain refinement lineage and promote only an explicitly reviewed artifact.

Install

Requires Python ≥ 3.11. Single runtime dependency (pyyaml).

git clone <this-repo> && cd hornero
python -m venv .venv && source .venv/bin/activate
uv pip install -e .            # or: pip install -e .

For ai-parrot's LLM-wiki knowledge plane and native coding-agent integration:

pip install 'hornero[knowledge]'
hornero wiki codex install
hornero wiki claude install        # Claude Code
hornero wiki gemini install        # Gemini CLI
hornero wiki parrot build

Quickstart

hornero new billing-api --blueprint python-service --commit
cd billing-api
hornero ingest product-requirements.docx
hornero reindex
hornero validate
hornero improve scan
hornero improve plan --limit 20

For an existing repository:

cd your-project/
hornero init                   # scaffolds .hornero/ + the sdd/ layout
echo "Users keep asking for CSV export of the usage table" \
  > .hornero/inbox/note-2026-07-08.md
hornero reconcile --dry-run    # see the proposed deltas, writes nothing
hornero reconcile              # review interactively, apply approved deltas
hornero build                  # dispatch approved specs (mock backend)
hornero reindex                # rebuild local knowledge graph + HTML graph report
hornero report                 # regenerate sdd/reports/*.html
hornero status                 # spec counts, inbox, index health

Add the shared SDD toolkit (agents, commands, rules, templates):

hornero sdd install --from <toolkit-repo-or-path>
hornero sdd status             # drift table: current/behind/modified/diverged/...
hornero sdd sync               # fast-forward what's safe; diverged blocks

CLI at a glance

Hard invariants

1. Evidence is verbatim or the delta dies — excerpts are mechanically verified substrings of the signal; mismatches are dropped and ledger-logged.
2. HITL is fail-closed — no approval channel ⇒ no spec mutation, no dispatch. --dry-run always leaves git status clean.
3. No billed backend by surprise — api never runs unless it is the explicit first entry of dispatch.backend_order.
4. Diverged toolkit files are never auto-merged — no timestamp heuristics; a human resolves with --theirs / --ours or by hand.
5. Deterministic tests only — the suite needs no network, keys, or services.

Documentation

• Workflow cookbook — reproducible examples from project creation through operations
• Video script — narrated end-to-end demonstration plan
• Infographic cheatsheet source — graph-derived command map, examples and visual brief
• Independent advisory and grounded mockups — provider bridge, safety boundaries and commands
• Usage guide — the full loop, configuration, SDD toolkit sync
• Development guide — setup, architecture, the self-hosted SDD workflow
• Deployment guide — adopting hornero in your repos, CI, multi-repo fanout
• PyPI release runbook — trusted automatic publishing from master
• Changelog guide — fragments, PR policy and PyPI projection
• ai-parrot LLM-wiki guide — knowledge bridge for Codex, Claude Code and Gemini CLI
• Changelog
• Visual artefacts — architecture diagram, infographic, cheatsheet, interactive onboarding (English + Spanish)

Specs are the source of truth: see sdd/specs/.

License

MIT