HoEN library intro¶
When to use: A newcomer (human or agent) asks what this library contains, how to use it, which skill fits a task, or invokes
/hoen-intro.
Instructions¶
Orient first — ask before you explain¶
Do not dump the whole catalog. This library wears three hats in one tree, so a
useful intro depends on where the person stands. Ask up to two short
orientation questions, then route. Prefer the AskUserQuestion tool so the
choices are clickable; fall back to plain prose if it is unavailable.
Question 1 — Scope: "Do you want a general tour of the library, or are you oriented to a specific project, workspace, or task right now?"
Question 2 — Role: "Which best describes what you're doing here?"
| If they say… | They're in role | Jump to |
|---|---|---|
| "Just exploring / general tour" | — | Asset catalog + README.md |
| "Using a skill to get work done" | Using / Self-use | Use-case routing |
| "Adding or editing a skill / asset" | Authoring | create-hoen-skill + CONVENTIONS.md |
| "Wiring this library into another repo" | Transplant | Transplant |
| "Helping with a specific project / workspace" | depends | Ask what the task is, then use Use-case routing |
If the user already named a task ("I need to review Databricks naming", "catch me up on recent commits"), skip the questions and route straight to the matching skill below.
BLUF¶
The HoEN Engineering Library is a proprietary, reusable toolbox of agent skills, exemplars, personas, and taxonomy that standardises how we and our agents do AI-augmented engineering work. It is intentionally aligned to the Hierarchy of Engineering Needs: assets are tagged by phase (diagnose / plan / implement / cross-cutting), HoEN need, and maturity, so an agent can pick the right help for the constraint in front of it. The library is still maturing — high operator attention is expected.
Three roles (why this repo can feel recursive)¶
This one tree is a library, a project that uses its own contents, and something downstream repos pull in. See README.md.
| Role | What you're doing | Where it happens |
|---|---|---|
| Authoring | Adding or editing canonical assets | library/ — skills/, exemplars/, personas/, taxonomy/ |
| Self-use | An agent in this repo reads skills in place | .agents/skills/, .claude/skills/, .cursor/skills/ (symlinks into library/skills/) |
| Transplant | A downstream repo includes this library so its agents use the same skills | Submodule + tool-specific wiring in the consumer |
If you're editing files under library/skills/, that's Authoring. Running an
agent here that reads them, that's Self-use. In a customer repo that pulled
this library in, that's Transplant.
Asset catalog¶
| Category | Location | What it is |
|---|---|---|
| Skills | library/skills/<name>/SKILL.md |
Reusable agent behaviours — the primary asset. Wired for invocation via IDE symlinks |
| Exemplars | library/exemplars/<phase>/ |
Redacted, persona-based example outputs (diagnose / plan) |
| Personas | library/personas/ |
Deterministic anonymisation data for redaction |
| Taxonomy | library/taxonomy/ |
Phase, HoEN-need, maturity, effort, and plan-status vocabularies |
Prompts, templates, and scripts are not a separate top-level category — they
live inside the skill that uses them (library/skills/<name>/references/,
assets/, scripts/).
Use-case routing¶
| I want to… | Start here |
|---|---|
| Understand what's in the library | This skill + README.md |
| Start any coding session cleanly | git-hygiene — branch off main first |
| Author or edit a skill | create-hoen-skill |
Catch up on recent main history |
project-catchup |
| Run a Databricks naming compliance audit | databricks-naming-compliance-review |
| Write commit messages to convention | commit-message-conventions |
| Plan work or estimate effort | plan-work · plan-effort-estimate |
| Build a remediation / gap-analysis plan | remediation-plan · gap-analysis |
| Keep docs in sync with code | docs-implementation-tagging |
| Tidy a churny docs folder | docs-lifecycle-convention |
| Diagnose an unfamiliar legacy codebase | diagnose-legacy-codebase |
| Redact real artifacts into shareable exemplars | redact-with-personas |
The folder listing under library/skills/ is the authoritative set — scan it if
the table above looks stale.
Transplant — wire into a consumer repo¶
Downstream repos include this library (commonly as a git submodule) and point
their agent tools at library/skills/. Prefer symlinks or copies from the
canonical paths over maintaining a second copy of skill content. Full wiring
(global symlink, per-skill links, project submodule, Windows / Git Bash):
ide-specific-skill-wiring.md.
Getting started (humans)¶
git clone --recurse-submodules <clone-url>npm installnode library-maintenance/scripts/validate.mjs— confirm assets validate- Read CONTRIBUTING.md and CONVENTIONS.md
References¶
- README.md — repo intent, three-role model, and layout
- CONVENTIONS.md — frontmatter and scanability rules
- CONTRIBUTING.md — how to work on the repo
- HoEN alignment guide — the five-dimension model
- ide-specific-skill-wiring.md — Transplant / Self-use wiring
Troubleshooting¶
| Symptom | Likely cause | Fix |
|---|---|---|
| Where are the skills? | Looking under .claude//.cursor/ |
Canonical sources live in library/skills/; the IDE folders are symlinks |
| Why does the repo feel recursive? | It is library, self-user, and transplant target at once | See the Three roles table |
What's /hoen-intro? |
— | This skill — the library onboarding entry point |
| A skill I expected isn't listed | Routing table drifted | Scan the library/skills/ folder; it's authoritative |
| How do I add a skill? | — | Use create-hoen-skill and validate before merge |