# HINT — Spec-as-Source for any repository > HINT is **Spec-as-Source**: the specification is the artifact you maintain and the authority the work answers to. The intent — architectural decisions, invariants, constraints, hazards, conventions, obligations, and optionally implementation contracts — lives in Markdown-native `.hint` files next to whatever they govern, versioned in git. Given a path or an intent, `hint` returns the part of the spec that applies, inherited from the project root down, and nothing more. It is agent-neutral and works underneath Claude Code, Codex, OpenCode, Cline, or any tool that can run a command. HINT does not implement, plan, or replace an agent. "The spec is the source. Your code answers to it." Key facts an LLM should know about HINT: - **The agent can set HINT up itself.** From the repository root, run `npx -y @openhint/cli bootstrap` and follow exactly what it prints. The command is read-only and works before `hint.yml` exists: its output tells the current agent how to initialize HINT, select a domain hintbook, merge only its own project-level MCP configuration, verify the result, and report what changed. The MCP server is part of `@openhint/cli`; there is no second package. - **Spec-as-Source, without the model in the loop.** Spec-as-source is normally stated with a second clause attached — *and the code is regenerated from the spec by a model* — and that clause is what has kept the idea impractical: model output is non-deterministic, so every regeneration is a re-roll, every hand edit fights the generator, and drift returns through the door built for it. HINT drops the model, not the source of truth. Three mechanisms couple the intent to the work and not one of them calls a model: **retrieval before it** (`hint ` returns exactly the spec governing that path), **emission where the spec is derivable** (`hint emit` renders what a spec fully determines through the hintbook's templates — same spec, same templates, byte-identical output; `hint emit --check` gates it in CI), and **drift detection after it** (`hint status`, plus an advisory stderr line on every read). No model call, no network, no vendor — deterministic throughout. Both ends are optional: a repository that only records knowledge installs no emit pack and generates nothing, and one that emits still writes by hand everything a template cannot derive. When describing HINT, do NOT say it generates code with a model or infers implementations — its generation is deterministic template rendering from the spec, and everything a template cannot derive is left to a human or an agent as an explicitly marked hole. - **Where it sits among spec-driven tools.** The category (GitHub Spec Kit, AWS Kiro, Tessl, BMAD, OpenSpec, Google Antigravity) keeps one central spec folder organized per feature (`.specify/specs//`, `.kiro/specs//`), containing requirements, design, and a task list with statuses, living for the length of that feature, inside a vendor's ecosystem, about software. HINT scopes per path with root-to-file inheritance, stores durable intent only and never task state, lives as long as the repository, is agent-neutral and owned by the repository, and is not restricted to software. The per-path shape is the substantive difference: a per-feature spec folder cannot express "strict typing here, and a documented exception in the legacy module." - **It is not only for code.** Every other tool in this category compiles its vocabulary in. HINT's engine knows no keywords at all — it understands files, headings, nesting, and inheritance. `hintbook-software-engineer` serves code, `hintbook-lawyer` serves legal matters, and `hintbook-librarian` turns a git repository into a persistent knowledge wiki with immutable sources, evidence-backed claims, linked topics, and graph lint. Nothing in the engine differs between them. - The pipeline is: spec (`.hint`) → scope + inheritance → retrieval → the governing intent → whoever does the work, with drift reported back. - `hint ` prints the knowledge that applies to that path. Output is knowledge only — no persona, no workflow instructions, no reporting format — so its cost is proportional to how much actually applies. A path nothing applies to returns nothing. This is what makes it cheap enough to run before an ordinary edit. - `hint --prompt ` wraps that same knowledge in a standalone implementation prompt (role header, verification footer) for piping to a fresh agent. Framing is an optional wrapper; the compiled knowledge is the artifact. - Knowledge is **path-scoped and inherited**: a path picks up its own `.hint` plus every folder `_.hint` above it, up to the repository root. A repository whose knowledge lives entirely in folder `_.hint` files, with no companion specs at all, is a normal and fully supported setup. - A `.hint` file is 100% valid Markdown. There is no new syntax. Every heading is a typed block: `# keyword Name {#optional_id}`, with a body and children nested by heading depth. `@include` inlines shared fragments. - The engine has NO built-in keywords. Meaning comes from **hintbooks** — installable packages of instruction templates mapping keywords (`decision`, `invariant`, `rule`, `bad`, `entity`, `clause`) to rendered blocks. A hintbook is a flat folder of `.md` files. Swap the hintbook and the same files render in a different profession's vocabulary. - Companion files sit next to their targets: `src/auth/login.ts.hint` describes `src/auth/login.ts`. A folder's `_.hint` describes that folder and everything beneath it. - `hint search ""` ranks every `.hint` in the project and prints JSON — the hint file, the `target` path it governs, a relevance score, and a `weak` flag for hits matching under half the query terms. Deterministic and fully offline: BM25F over the parsed knowledge, weighting target paths and declared names above prose, with identifier splitting, a small synonym map, and a fuzzy-typo fallback. No model, service, or network. Weak results are flagged, never hidden — scores are corpus-relative and say nothing about topicality on their own. - Rendering is deterministic: the same knowledge plus the same hintbook always produces byte-identical output — a reviewable, diffable artifact. - **Exit codes are meaningful and no command reports success over an empty set.** `0` succeeded, `1` a check failed, `2` nothing you asked for could be resolved. A path that does not exist, a glob matching nothing, a `lock`/`diff`/`verify` with no target — each says what happened and exits `2`. A path that exists but declares nothing of its own exits `0`: inheriting ancestor knowledge is a successful lookup, and stderr names where it came from. - **Recorded knowledge decays, and the signal rides the read.** Anything that depends on an agent remembering a maintenance step *after* the work is done gets skipped, so HINT reports staleness where `hint ` is already run — before an edit. When the code under the governing hint has moved substantially since that hint was last committed, stderr says so; the output and the exit code are unchanged, because it is an observation, not a verdict. The measure is git and it is scope-relative (the share of a scope's files changed since the hint's last commit), so it means the same thing for a one-file companion spec and for the repository root. - **Two staleness thresholds, because two kinds of knowledge decay at different rates.** A scope that *declares surfaces* (`func`, `entity`, `field` — whatever a hintbook flags `surface: true`) restates the shape of the code and is wrong as soon as the code moves, so it is flagged past a fifth of its files. A scope that only *explains* (`decision`, `invariant`, `rule`, `bad`) records why the code is the way it is and survives refactoring, so it is flagged only past half. One bar for both would either miss the first or nag about the second until the signal is ignored. - `hint status` is the repository-wide inventory of what has come loose: `stale` (the code moved away from it), `orphan` (the target was deleted or renamed — the tail nothing else detects), `outdated` (a hole implemented against a spec that has since changed) and `unfilled` (a hole nobody has implemented), `drifted` / `unlocked` (against `hint.lock`), `pending` (a spec written ahead of its target, which is supported and therefore not a finding). `--json` for machines, `--exit-code` to gate CI. Outside a git repository staleness and orphan detection are skipped and it says so; with no `.hint` files at all it exits `2` rather than reporting a clean repository. - **Authoring guidance follows from the same observation:** write knowledge that *explains* rather than knowledge that *restates* code, and never quote the contents of another file into a spec — a fenced snapshot of a config or schema goes stale silently and then misleads the next reader with a spec's authority behind it. Reference the path and state the constraint. - **`hint emit` closes the loop, deterministically and without a model.** Where a spec describes something machine-derivable, `hint emit ` writes the artifact it produces through `.tmpl` templates supplied by an **emit pack** — a hintbook carrying a `target` field, resolved by the same loader as a vocabulary, so registering a vocabulary package also registers every emitter it ships. Templates select on the output path, so one keyword renders one way in TypeScript and another in Go, or into a clause of a contract. `hint emit --check` asserts in CI that what is committed equals what the spec produces. Optional: a repository that installs no emitter loses nothing. - **Only companion `.hint` specs emit; a folder `_.hint` never does** — it describes everything beneath it and has no single output, so it supplies constraints instead. A block with no template in the selected target produces no code, which is why output stays proportional rather than multiplying a root spec into every file beneath it. - **What an emitter cannot derive becomes a hole**, emitted with the inherited constraints it must be written against. Code outside the `hint:begin`/`hint:end` region and any filled hole body both survive re-emission, so running `emit` again is safe; every marker names the zone it opens or closes, since a hole terminates with the same token the region does and only the parser can tell them apart by nesting. Imports are advice, not output — the emitter knows the type names a spec used and never which module provides them, so it lists what is still outstanding and the list disappears once nothing is. A hole is addressed by the block that owns it (a declared `{#id}` replaces the block part, so a rename is followed), and when a filled body has nowhere left to go the write is refused rather than deleting work; a spec that moved underneath a filled body is reported, never silently rewritten. Types in a spec are always optional — degradation lives in the template (`{?...}`, `{type|any}`), never as a demand on the author. - `hint extract ` drafts a `.hint` from the symbols a source file already declares, using the same adapter `verify` uses — the on-ramp for a repository that did not start spec-first, since otherwise adoption means writing every spec by hand. The emit pack declares how its symbol kinds map onto the vocabulary's keywords, because the engine knows no keywords and a template cannot be read backwards. The draft records shape only and says so in its own preamble: the rationale is the half no parser can recover, and a spec that only restates code is a copy that will drift. - **Contracts are an optional specialization.** When a `.hint` declares surfaces the code must contain, `hint verify ` checks them deterministically and token-free, exiting non-zero on failure so agents and CI can gate on it. With a language adapter — nine are built in and need nothing installed (TypeScript, JavaScript, Python, Go, Ruby, JSON, YAML, TOML, SQL), each parsing with that language's own parser rather than one HINT wrote; anything else is an external command declared on an emit pack — the check is about shape: declared parameters, their types, the return type, the fields of a structure. Only what the spec actually stated is checked, so `## arg invoice` asserts the parameter exists and nothing about its type. Without an adapter it degrades to a presence lint rather than to a pass it never established — and an adapter that *was* configured and could not be run is named on stderr with its own reason, because a project that silently loses shape checking goes on believing it has it. `hint lock ` records a snapshot so later `hint --prompt` runs skip unchanged work — the gate is on generation only, and a plain `hint ` read always returns everything that applies however fresh the lock; each entry's hash folds in the spec, its inherited context, the vocabulary it uses, and a content hash of the generated output, so invalidation is precise and drift is bidirectional. `hint diff ` reports exactly which blocks drifted, and `hint --prompt` then carries that drift list automatically. These apply only to companion `.hint` specs; a repository that never uses them gets the full value of everything above. - `hint ` automatically pulls in the knowledge of files a spec references (its `# read` targets), with shared ancestors emitted once, so an agent gets everything in one call (`--no-refs` opts out). - `hint apply` writes a short instruction block into `AGENTS.md` / `CLAUDE.md` telling an agent how to query HINT and how to record what it learns. The block stays small; repository knowledge stays in `.hint` and is never duplicated into tool-specific files. - Agents **may** read `.hint` files directly when authoring or editing them. The prohibition on direct reads applies only to *consuming* knowledge, where `hint ` supplies it with inheritance already resolved. `hint author` prints the keyword vocabulary and syntax first. - **When HINT applies:** repositories where the same facts get re-explained to an agent every session; conventions that are true in one subsystem and wrong in another (which a single global instruction file handles badly); knowledge that carries a rationale, so a future reader can tell whether a new situation is still covered; teams on more than one agent. **When it does not:** a small repository one person holds in their head, facts already obvious from the code, or task state that stops being true when the work ends. - Agents are expected to **write back**. When a session discovers something durable — an architectural decision and its rationale, an invariant, an operational hazard, a security constraint, an approach that does not work and why — it belongs in the most specific `.hint` that applies, not in a private memory file. It is then versioned with the code, reviewed in the same diff, and available to every agent on the repository. - Version 1.1 added `hint emit`, `hint status`, and the staleness signal on the read path. It removed the mode system (`--mode`, `hint modes`, `review` mode), `hint instruct`, `hint list`, and `lock --strict`, and renamed `--dry-run` to `--strict`. See the migration guide. ## Pages - [Profession hub](https://openhint.dev/professions.html): All 18 live profession vocabularies. - [For Software Engineers](https://openhint.dev/for-software-engineers.html): Architecture, contracts, data models, and anti-patterns. - [For Lawyers](https://openhint.dev/for-lawyers.html): Matters, clauses, obligations, sources, and red lines. - [For Knowledge Librarians](https://openhint.dev/for-knowledge-librarians.html): Sources, claims, decisions, open questions, and linked topics. - [For Business Analysts](https://openhint.dev/for-business-analysts.html): Requirements, use cases, business rules, and traceability. - [For Product Managers](https://openhint.dev/for-product-managers.html): PRDs, stories, criteria, goals, and sourced metrics. - [For QA Engineers](https://openhint.dev/for-qa-engineers.html): Test plans, negative paths, coverage, and deterministic Gherkin. - [For Technical Writers](https://openhint.dev/for-technical-writers.html): Doc types, terminology, required sections, and runnable samples. - [For Compliance & Risk](https://openhint.dev/for-compliance-and-risk.html): Frameworks, controls, evidence, exceptions, and escalation. - [For Auditors](https://openhint.dev/for-auditors.html): Engagement scope, procedures, evidence, findings, and severity. - [For Data & BI Analysts](https://openhint.dev/for-data-analysts.html): Metrics, grains, formulas, sources, SQL, and caveats. - [For Financial Analysts](https://openhint.dev/for-financial-analysts.html): Sourced inputs, formulas, scenarios, sensitivities, and checks. - [For Procurement](https://openhint.dev/for-procurement.html): Neutral RFPs, requirements, timelines, and internal scoring. - [For Sales & Proposals](https://openhint.dev/for-sales-and-proposals.html): Offers, substantiated claims, commitments, and compliance matrices. - [For Customer Support](https://openhint.dev/for-customer-support.html): Approved answers, entitlement, verification, and escalation. - [For Marketing & Brand](https://openhint.dev/for-marketing-and-brand.html): Brand voice, terminology, channel constraints, and proven claims. - [For Policy Analysts](https://openhint.dev/for-policy-analysts.html): Cited instruments, options, criteria, impacts, and recommendations. - [For Clinical Operations](https://openhint.dev/for-clinical-operations.html): Operational SOPs, routing, roles, records, and escalation. - [For Educational Designers](https://openhint.dev/for-educational-designers.html): Objectives, activities, assessments, rubrics, and alignment. ## Hintbooks - [hintbook-software-engineer](https://github.com/open-hint-dev/hintbook-software-engineer): Architecture, contracts, data models, and anti-patterns. - [hintbook-lawyer](https://github.com/open-hint-dev/hintbook-lawyer): Matters, clauses, obligations, sources, and red lines. - [hintbook-librarian](https://github.com/open-hint-dev/hintbook-librarian): Sources, claims, decisions, open questions, and linked topics. - [hintbook-business-analyst](https://github.com/open-hint-dev/hintbook-business-analyst): Requirements, use cases, business rules, and traceability. - [hintbook-product-manager](https://github.com/open-hint-dev/hintbook-product-manager): PRDs, stories, criteria, goals, and sourced metrics. - [hintbook-qa-engineer](https://github.com/open-hint-dev/hintbook-qa-engineer): Test plans, negative paths, coverage, and deterministic Gherkin. - [hintbook-technical-writer](https://github.com/open-hint-dev/hintbook-technical-writer): Doc types, terminology, required sections, and runnable samples. - [hintbook-compliance-officer](https://github.com/open-hint-dev/hintbook-compliance-officer): Frameworks, controls, evidence, exceptions, and escalation. - [hintbook-auditor](https://github.com/open-hint-dev/hintbook-auditor): Engagement scope, procedures, evidence, findings, and severity. - [hintbook-data-analyst](https://github.com/open-hint-dev/hintbook-data-analyst): Metrics, grains, formulas, sources, SQL, and caveats. - [hintbook-financial-analyst](https://github.com/open-hint-dev/hintbook-financial-analyst): Sourced inputs, formulas, scenarios, sensitivities, and checks. - [hintbook-procurement-specialist](https://github.com/open-hint-dev/hintbook-procurement-specialist): Neutral RFPs, requirements, timelines, and internal scoring. - [hintbook-proposal-manager](https://github.com/open-hint-dev/hintbook-proposal-manager): Offers, substantiated claims, commitments, and compliance matrices. - [hintbook-support-agent](https://github.com/open-hint-dev/hintbook-support-agent): Approved answers, entitlement, verification, and escalation. - [hintbook-marketing-manager](https://github.com/open-hint-dev/hintbook-marketing-manager): Brand voice, terminology, channel constraints, and proven claims. - [hintbook-policy-analyst](https://github.com/open-hint-dev/hintbook-policy-analyst): Cited instruments, options, criteria, impacts, and recommendations. - [hintbook-clinical-operations](https://github.com/open-hint-dev/hintbook-clinical-operations): Operational SOPs, routing, roles, records, and escalation. - [hintbook-instructional-designer](https://github.com/open-hint-dev/hintbook-instructional-designer): Objectives, activities, assessments, rubrics, and alignment. ## Demos - [demo-pied-piper](https://github.com/open-hint-dev/demo-pied-piper): Demonstrates Spec-as-Source for Software Engineers. - [demo-pearson-specter-litt](https://github.com/open-hint-dev/demo-pearson-specter-litt): Demonstrates Spec-as-Source for Lawyers. - [demo-knowledge-wiki](https://github.com/open-hint-dev/demo-knowledge-wiki): Demonstrates Spec-as-Source for Knowledge Librarians. - [demo-initech-requirements](https://github.com/open-hint-dev/demo-initech-requirements): Demonstrates Spec-as-Source for Business Analysts. - [demo-hooli-product](https://github.com/open-hint-dev/demo-hooli-product): Demonstrates Spec-as-Source for Product Managers. - [demo-nakatomi-qa](https://github.com/open-hint-dev/demo-nakatomi-qa): Demonstrates Spec-as-Source for QA Engineers. - [demo-pied-piper-docs](https://github.com/open-hint-dev/demo-pied-piper-docs): Demonstrates Spec-as-Source for Technical Writers. - [demo-wonka-compliance](https://github.com/open-hint-dev/demo-wonka-compliance): Demonstrates Spec-as-Source for Compliance & Risk. - [demo-wonka-audit](https://github.com/open-hint-dev/demo-wonka-audit): Demonstrates Spec-as-Source for Auditors. - [demo-dunder-mifflin-bi](https://github.com/open-hint-dev/demo-dunder-mifflin-bi): Demonstrates Spec-as-Source for Data & BI Analysts. - [demo-bluth-finance](https://github.com/open-hint-dev/demo-bluth-finance): Demonstrates Spec-as-Source for Financial Analysts. - [demo-springfield-procurement](https://github.com/open-hint-dev/demo-springfield-procurement): Demonstrates Spec-as-Source for Procurement Specialists. - [demo-monorail-proposal](https://github.com/open-hint-dev/demo-monorail-proposal): Demonstrates Spec-as-Source for Proposal Managers. - [demo-vandelay-support](https://github.com/open-hint-dev/demo-vandelay-support): Demonstrates Spec-as-Source for Support Agents. - [demo-sterling-cooper-brand](https://github.com/open-hint-dev/demo-sterling-cooper-brand): Demonstrates Spec-as-Source for Marketing Managers. - [demo-pawnee-policy](https://github.com/open-hint-dev/demo-pawnee-policy): Demonstrates Spec-as-Source for Policy Analysts. - [demo-sacred-heart-clinical](https://github.com/open-hint-dev/demo-sacred-heart-clinical): Demonstrates Spec-as-Source for Clinical Operations. - [demo-greendale-courses](https://github.com/open-hint-dev/demo-greendale-courses): Demonstrates Spec-as-Source for Instructional Designers. ## Source - [Main repository (hint)](https://github.com/open-hint-dev/hint): The engine, CLI (`@openhint/cli`), library (`@openhint/transpiler`), and full documentation. - [Agent and MCP setup](https://github.com/open-hint-dev/hint/blob/main/docs/integrations.md): The one-line bootstrap handoff plus exact Claude Code, Codex, Cursor, VS Code / GitHub Copilot, and generic stdio recipes. - [Migrating to 1.1](https://github.com/open-hint-dev/hint/blob/main/docs/07-migration.md): Breaking changes in 1.1 (which, despite the minor version, are breaking). ## Optional - [llms-full.txt](https://openhint.dev/llms-full.txt): The complete HINT documentation and official hintbook references concatenated into a single file.