@openhint/hintbook-software-engineer

The official general-purpose hintbook for HINT — the keyword vocabulary that turns .hint specifications into binding implementation prompts for AI coding agents.

A hintbook supplies what the HINT transpiler deliberately leaves open: the meaning of every keyword. This book covers the day-to-day vocabulary of software engineering — data structures, function contracts, logic flows, UI surfaces, dependency policies, prohibitions, and test criteria — and ships three compilation modes: implement, fix, and review.

Installation

hint install @openhint/hintbook-software-engineer

This registers the book in your project's hint.yml:

books:
    - npm://@openhint/hintbook-software-engineer

Then let hint config | claude -p add the book's system glossary to your AGENTS.md / CLAUDE.md, so agents know how to read the compiled tags.

Vocabulary at a glance

Write any of these as a markdown heading — # keyword Name {#optional_id} — at any nesting level:

| Area | Keywords | | --------------- | -------------------------------------------------------------------------- | | Intent & scope | goal, done, scope | | Project context | app, lang, build, dep, module, lib, namespace, res, read | | Data | data, entity, field, table, column, row | | Behavior | func, arg, result, flow, action, error | | Constraints | rule, good, bad, test, example | | User interface | ui, form, block, image | | Spec-internal | notes (excluded from compiled output) |

Common long forms work as synonyms: application → app, function → func, dependencies → dep, language → lang, library → lib, argument → arg, return → result, intent → goal, acceptance → done, outofscope → scope, constant → data, and more.

See the full reference with rendered tags and usage guidance in docs/keywords.md.

Modes

| Mode | Invocation | The agent's role | | ------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | compile (default) | hint <paths> | Senior engineer implementing the specification exactly — no invented features, no placeholders, completion checklist at the end. | | fix | hint --mode fix <paths> | Senior engineer repairing code that violates the spec: root cause first, smallest conforming change, regression test required. | | review | hint --mode review <paths> | Senior engineer auditing an implementation against the spec: findings with severity and file references, no code changes. |

Details in docs/modes.md.

Example

# entity PaymentData {#payment_data}

this entity describes the payment data contract

## field timestamp

unix epoch milliseconds

compiles (inside the file/folder context chain, header, and footer) into:

<data_structure name="PaymentData" id="payment_data">

this entity describes the payment data contract

<field name="timestamp" id="">

unix epoch milliseconds

</field>

</data_structure>

The __system__ glossary defines data_structure, field, and every other tag as a binding directive — that pairing of rendered tags and glossary is what makes the output enforceable rather than decorative.

License

MIT