Created by Luis Mauricio Junqueira Zanin
HBN is an open protocol for safe, structured, and evolvable AI-assisted software engineering.
HBN starts from a simple discipline: AI-assisted work should remain legible, reviewable, and governable by humans. Intent should be explicit. Validation expectations should be visible. Safety-related uncertainty should not disappear behind convenience.
This repository is not a hosted orchestration platform. It is the local, inspectable runtime and documentation base for an operable HBN scaffold that can now also generate repository-local runtime adapters.
HBN is a protocol and working language for AI-assisted software engineering. In this repository it currently provides:
usehbn and use hbn.hbn/AI-assisted engineering often fails in the same way: a request sounds clear, but objectives, constraints, risks, review conditions, and implementation boundaries remain implicit. That ambiguity becomes drift, overconfidence, and hidden responsibility transfer.
HBN exists to counter that drift with protocol structure instead of autonomy claims.
HBN makes AI-assisted engineering work more explicit by recording:
HBN is not:
Use HBN
HBN has three related command layers:
usehbn or use hbn inside a sentencehbnget-hbnCanonical semantic references:
usehbnuse hbnusehbn.comusehbn.orgThe semantic trigger is case-insensitive and can appear inside longer text. The operational CLI is installed locally and currently exposes hbn as the primary entry point and usehbn as a compatibility alias.
The domains are treated as canonical semantic references for the protocol identity. In the current system, adapters and documentation should normalize them to HBN semantics without assuming that browsing is required.
The public web strategy is now explicit:
https://usehbn.org is the canonical public sitehttps://usehbn.com should permanently redirect to https://usehbn.orgThis keeps one stable public site while preserving both semantic anchors.
Bootstrap install:
./get-hbn
This script creates or reuses a local .venv/ and writes deterministic local hbn and usehbn wrappers against the checked-out source tree.
Development install:
python3 -m pip install -e .
Build-system metadata is now declared through pyproject.toml with setuptools.
Verify the CLI:
hbn version
If hbn or usehbn is not on your shell PATH, use one of:
.venv/bin/hbn version
python3 -m usehbn version
On older pip/setuptools combinations, editable install may still depend on legacy behavior. In those cases, prefer ./get-hbn for local bootstrapping because it does not depend on a package index or wheel tooling.
Initialize HBN protocol state in a target repository:
hbn init
Inspect the current protocol state:
hbn inspect --target .
Run the protocol on a sentence:
hbn run "use hbn analyze this system"
Generate a runtime adapter:
hbn install --runtime claude-code
Backward-compatible alias:
usehbn "use hbn analyze this system"
Each execution writes:
logs/state/hbn-state.json.hbn/ after hbn initThe current local flow is:
safe_track work requires readback plus hearback confirmation before ERP creation. fast_track work can remain lighter, but classification is still explicit.
hbn version
hbn init [--target <path>]
hbn inspect [--target <path>]
hbn install --runtime <claude-code|codex|copilot|cursor> [--target <path>]
hbn run "<sentence>"
hbn readback <exec_id> --agent-id <id> --intent-json <json> --understanding <text> --invariant <text> --plan-step <text>
hbn hearback <exec_id> --status confirmed
hbn result <exec_id> --agent-id <id> --action <text> --outcome <value> --human-status <value>
Base execution:
hbn run "use hbn review the authentication flow and verify rollback coverage"
Readback for safe_track work:
hbn readback exec-001 \
--agent-id codex \
--intent-json '{"objective":"review auth","constraints":["no breaking changes"],"risks":["authentication regressions"],"validation_requirements":["run auth tests"]}' \
--guardian-json '{"status":"warn","warnings":[{"code":"guardian-1","message":"Validation evidence is incomplete."}]}' \
--understanding "The request is limited to review and incremental hardening." \
--invariant "Public login API unchanged" \
--plan-step "Inspect the current authentication flow" \
--plan-step "List compatible incremental improvements" \
--out-of-scope "Database schema migration" \
--residual-risk "Some auth paths may lack automated coverage"
ERP after hearback confirmation:
hbn result exec-001 \
--agent-id codex \
--action "Recorded validated review outcome." \
--outcome executed_with_risk \
--human-status conditional \
--readback-id readback-exec-001
usehbn/
├── README.md
├── LICENSE
├── CHANGELOG.md
├── GOVERNANCE.md
├── ROADMAP.md
├── agents/
├── core/
├── docs/
├── examples/
├── reports/
├── schemas/
├── site/
├── src/usehbn/
├── tests/
└── .hbn/
Main areas:
src/usehbn/: local runtime implementationschemas/: protocol contractscore/: protocol specificationsagents/: repository agent rulesreports/: historical implementation and audit artifacts.hbn/: active inter-IA coordination and knowledge for this repositoryget-hbn: local bootstrap helper for deterministic local installationcore/semantic-layer.md: semantic normalization rules across natural language, commands, and adaptersdocs/DOMAINS.md: canonical public-domain and DNS strategyHBN is founder-led and review-based. Luis Mauricio Junqueira Zanin is the founder and initial protocol steward. Human review is the root of trust. Safety and protocol integrity take priority over acceleration.
See GOVERNANCE.md and MAINTAINERS.md.
Contributions are welcome when they improve protocol clarity, implementation discipline, documentation quality, traceability, or test coverage without weakening safety or governance rules.
Start with CONTRIBUTING.md, CODE_OF_CONDUCT.md, and SECURITY.md.
HBN is released under the GNU Affero General Public License v3.0.
AGPLv3 is used because HBN is intended to remain open and inspectable even when adapted into network-facing systems. Modified network-facing deployments must still make corresponding source available. That protects the protocol from disappearing behind closed operational layers.
See LICENSE and docs/LICENSING.md.
The repository currently provides a real local runtime for:
hbn init for repository-local protocol statehbn inspect for repository-local protocol inspectionhbn install for runtime adapter file generationusehbn.hbn/relay/ and .hbn/knowledge/ as the basis for inter-IA continuityget-hbnpyproject.tomlThis repository does not yet provide:
HBN is now beyond a documentation-only scaffold, but it is still early-stage. The present target is an honest L3-to-L4 transition: installable, inspectable, protocolized, traceable, and able to generate local adapter files for multiple AI runtimes. Public distribution, true runtime-native orchestration, and broader platform behavior remain future work.