@damiangilgonzalez/harness 1.3.7

package/skills/hiring/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: hiring
+description: "Use when a role is open and you must write the job post, screen inbound candidates, structure the interview loop, or score them to a defensible Hire / On-Hold / No-Hire — including whether an AI résumé filter is legal. NOT after the offer is accepted — onboarding, payroll, performance (that is `people-ops`), NOT offer terms (that is `contracts`)."
+tags: [hiring, recruiting, job-description, interview-scorecard, candidate-screening, structured-interview]
+recommends: [people-ops, brand-voice, contracts, compliance, cold-outreach, calendar-scheduling]
+profiles: []
+origin: risco
+---
+
+# Hiring
+
+You run the **selection funnel up to the hire decision**: write the post, screen
+the pile, structure the loop, and score candidates so the call is evidence-based
+and defensible. The product of this skill is a job post, a set of screen
+decisions, an interview structure, and a scorecard that says Hire / On-Hold /
+No-Hire with the reason written down.
+
+Hard boundary: the moment the offer is accepted, you are done. Onboarding,
+payroll, equipment, performance reviews, PTO — that is `../people-ops/SKILL.md`.
+Do not draft offer-letter terms here either; that is `../contracts/SKILL.md`.
+
+## The funnel (the spine)
+
+Every engagement walks this line, in order. Do not skip to scoring before the
+rubric exists.
+
+```text
+define role → write post → screen pile → structured loop → independent scores → calibrated debrief → decision
+```
+
+One rule per stage, with the why:
+
+- **Define the role first.** You cannot screen against criteria you have not
+  named. Write the 3–6 competencies before the post, because they drive the
+  post, the questions, and the scorecard.
+- **Write the post from the competencies.** A post is the competencies turned
+  outward, not a wish list.
+- **Screen against one rubric.** Same criteria, same order, every candidate, or
+  the comparison is meaningless.
+- **Run a structured loop.** Same questions, same rubric, every candidate —
+  structured interviews are the single highest-validity selection method
+  (~.51 predictive validity vs ~.38 unstructured; the 2022 Sackett et al.
+  re-analysis ranks them above cognitive-ability tests). Unstructured = lottery.
+- **Score independently, then calibrate.** Each interviewer submits before the
+  group talks. Debrief is calibration, not a re-vote.
+
+## Write the job post
+
+The job post is the top of the funnel and it leaks candidates if you write it
+wrong. Apply the company voice from `../brand-voice/SKILL.md` if one exists — but
+do not author the voice guide here, just apply it.
+
+**Split must-haves from nice-to-haves, and keep must-haves short.** Women tend to
+apply only when they meet ~100% of listed requirements vs ~60% for men, so every
+extra "requirement" silently filters out qualified candidates. Cap must-haves at
+~6. Everything that is genuinely learnable on the job goes under nice-to-have.
+
+**Ban gender-coded language.** Removing gender-coded terms yields roughly 29%
+more applications. Masculine-coded words skew the applicant pool male. Strip and
+replace:
+
+- Drop: *rockstar, ninja, dominant, aggressive, fearless, ambitious, competitive,
+  driven, strong, crush it.*
+- Prefer: *collaborate, support, partner, build, responsible, dependable, share.*
+
+Full do/don't word list and a fill-in post skeleton: `references/templates.md`.
+
+**State pay.** Pay transparency is law in a growing number of jurisdictions and a
+range widens the pool. Put a band in the post.
+
+Bad → Good, same role:
+
+```text
+BAD
+We need a rockstar engineer — a fearless, aggressive self-starter who can crush
+ambiguous problems. Requirements: 8+ years, CS degree from a top school, expert
+in 11 named technologies, startup experience, must thrive under pressure.
+
+GOOD
+Senior Backend Engineer · €70–90k · Barcelona / remote-EU
+You'll own our payments service end to end and partner with product on the
+roadmap.
+Must-haves (≤6): 5+ yrs building production backend services; fluent in one of
+Go/Python/Java; designed and run a service in production; comfortable with SQL.
+Nice-to-haves: payments domain, Kafka, prior on-call.
+How to apply: send a short note + anything you've shipped.
+```
+
+## Screen the pile
+
+Score every applicant against the **same job-related rubric** you derived from
+the competencies (template: `references/templates.md`). No bespoke criteria per
+candidate.
+
+- **Blind to non-job factors.** School prestige, name, age, employment gaps,
+  photo — none of it is in the rubric, so it does not enter the decision.
+- **Work samples beat résumés.** Skills-based signals (a structured task, a code
+  sample, a portfolio teardown) predict performance better than résumé history;
+  >73% of companies now report a skills-based approach. When a must-have is
+  unclear, resolve it with a small work-sample, not a guess.
+- **Defer criminal history.** Fair-chance / "ban-the-box" laws in 37+ states and
+  150+ US cities require deferring criminal-history questions until after a
+  conditional offer, plus an individualized assessment. Do not put a
+  criminal-history box on the application form. (Candidate-data retention and
+  consent: `../gdpr-privacy/SKILL.md`.)
+
+For each candidate, the call:
+
+| Signal | Decision |
+|---|---|
+| Meets the must-haves on job-related evidence | Advance to loop |
+| Strong on most, one must-have unclear | Send a short work-sample / structured task to resolve it |
+| Misses a hard must-have (verified skill, legal eligibility) | Reject, with the job-related reason logged |
+| Borderline, more reqs open soon | Parking lot — note why, revisit, do not silently ghost |
+| Non-job factor (school name, age, gap, "vibe", name) | Ignore it — it is not in the rubric |
+
+## Structure the interview loop
+
+Turn the 3–6 competencies into a loop where each interviewer owns distinct
+ground.
+
+1. **Map competencies to stages.** Each competency gets a clear owner. If four
+   people will all ask "tell me about a hard project", you have a duplicate-
+   coverage bug — split the competencies so each stage probes something the
+   others do not.
+2. **Build a structured question bank.** Behavioral / STAR + work-sample, tied to
+   each competency, asked in the same order for every candidate. Sample inline;
+   full bank in `references/templates.md`.
+3. **Calibrate before kickoff.** Run a 15-minute session on what a "5" vs a "3"
+   means on the scale *before* anyone interviews, so scores are comparable.
+
+Sample structured question (problem-solving, behavioral/STAR):
+
+```text
+"Walk me through the hardest technical tradeoff you owned in the last year."
+Follow-ups (STAR): What was the situation? What were YOUR options and the one
+you picked? What did you actually do? What was the measured result, and what
+would you change?
+```
+
+## The scorecard
+
+This is where gut-feel hiring dies. A structured scorecard with behavioral
+anchors lifts interview validity from ~.20 to ~.51 (most rigorous scoring ~.57)
+and a 2022 SHRM-cited figure puts bias reduction above 50% versus unstructured
+scoring. Shape it exactly:
+
+- **3–6 competencies.** Fewer misses dimensions; more than 6 dilutes focus and
+  loads the interviewer.
+- **5-point anchored scale.** Write the anchor text for at least the low / mid /
+  high points so a "4" means the same thing to everyone.
+- **A required evidence field.** Forces a quote or concrete example, not a vibe.
+- **One overall: Hire / On-Hold / No-Hire.**
+- **Score independently, submit before the debrief.** Fill it right after the
+  session (recency) and submit before the group talks, so no one anchors on the
+  loudest voice in the room.
+
+Skeleton:
+
+```text
+Candidate: ___   Role: ___   Interviewer: ___   Stage: ___
+
+Competency: Problem-solving
+  Score (1–5): __
+  Anchors — 1: gave a vague answer, no real tradeoff
+            3: described a decision but thin on alternatives/result
+            5: clear tradeoff, owned the call, measured the outcome
+  Evidence (required, quote/example): "____________________"
+
+[ repeat for each of the 3–6 competencies ]
+
+Overall recommendation:  [ ] Hire   [ ] On-Hold   [ ] No-Hire
+Rationale (one paragraph, tied to the evidence above): ______
+```
+
+Bad → Good entry:
+
+```text
+BAD:  Problem-solving: 7/10. Good vibes, seems smart, would grab a beer with him.
+GOOD: Problem-solving: 4/5. Evidence: "chose eventual consistency to cut p99 from
+      900ms to 120ms, named the staleness tradeoff and how they bounded it."
+```
+
+Full anchored template (one competency written out at all five levels) and the
+question bank: `references/templates.md`.
+
+## Debrief & decision
+
+Turn independent scores into one calibrated call.
+
+1. Collect all submitted scorecards — confirm they came in before the debrief.
+2. Surface disagreements: where scores diverge, go to the **evidence**, not the
+   loudest opinion. A "5" with a weak quote loses to a "3" with a strong one.
+3. Reach Hire / On-Hold / No-Hire and **write the rationale**, tied to the
+   evidence on the cards.
+4. **Retain the records.** EEOC requires keeping interview notes and scoring
+   tools at least 1 year after the decision (2 years for federal contractors).
+   The anchored scorecards with documented evidence *are* the defense if the
+   decision is ever challenged. Do not delete them.
+
+A loop that "still can't decide after four interviews" almost always lacks
+independent submitted scores and anchors — fix the structure, do not add a fifth
+interview.
+
+## AI & legal guardrails
+
+Before you let any model rank, score, or reject candidates, know these triggers.
+This skill *follows* the rules; it does not run the legal program — that is
+`../compliance/SKILL.md`.
+
+- **NYC Local Law 144** (enforced since 2023-07-05): any Automated Employment
+  Decision Tool needs an annual independent bias audit, public posting of the
+  results, and advance notice to candidates. No audit, no notice → do not deploy.
+- **EU AI Act:** recruitment / CV-screening / candidate-ranking AI is classed
+  *high-risk* (Annex III, Cat. 4). Obligations apply from **2 Dec 2027**
+  (deferred from 2 Aug 2026 by the Nov-2025 AI-omnibus). Deployer fines reach
+  €15M or 3% of global turnover. Colorado's AI Act effective date moved to 2027.
+- **Never auto-reject without human review.** A model can sort or flag; a person
+  makes the reject call. Keep the human in the loop and the evidence trail intact.
+
+## Anti-patterns
+
+| Anti-pattern | Why it fails | Do instead |
+|---|---|---|
+| "7/10, good vibes" rating | Unscoreable, bias-prone, indefensible | 5-point anchored scale + evidence quote |
+| Different questions per candidate | No comparison is valid | Same structured bank, same order |
+| Four interviewers, one question | Wastes the loop, no coverage | Map each competency to one owner |
+| 15-item must-have list | Self-filters qualified candidates (100% vs 60%) | ≤6 must-haves; rest are nice-to-haves |
+| Gender-coded words in the post | ~29% fewer applications, skews male | Strip and replace; check the word list |
+| Criminal-history box on the form | Violates fair-chance / ban-the-box law | Defer to post-conditional-offer |
+| Debrief before scores submitted | Groupthink anchors on the loudest voice | Independent scores in first, then talk |
+| Model auto-rejects résumés | LL144 / EU AI Act exposure, no human in loop | Model flags, human decides, audit + notice |
+| "Culture fit" as a competency | Coded bias, not job-related | Score job-related competencies only |
+| Screening on school / name / gap | Non-job factor, not in the rubric | Blind to it; rubric only |
+| Deleting interview notes | Breaks EEOC retention; no defense | Retain ≥1 yr (2 yr for fed contractors) |
+| Drifting into onboarding/payroll | Out of scope, wrong skill | Stop at the decision → `../people-ops/SKILL.md` |

package/skills/hiring/evals/README.md

@@ -0,0 +1,13 @@
+# Hiring evals
+
+`cases.yaml` holds the trigger / near-miss / capability cases for the `hiring`
+skill. There is no automated runner here — score by judgment. For each
+`should_trigger` prompt, confirm a router would reach for `hiring`; for each
+`should_not_trigger`, confirm it routes to the named sibling instead (the test is
+that the boundary holds, not just that hiring is skipped). For the `capability`
+case, give the scenario to an agent loaded with `SKILL.md` and check the output
+against every `must_include` line — a pass means it produced a split must/nice
+post with inclusive language and a 3–6-competency anchored scorecard with an
+evidence field and an overall recommendation, stated the independent-scoring
+rule, and stayed out of onboarding/payroll. This is a process skill, so the
+capability rubric is the rigor; there is no `verify.sh`.

package/skills/hiring/evals/cases.yaml

@@ -0,0 +1,41 @@
+skill: hiring
+
+should_trigger:
+  - prompt: "Write a job description for a senior backend engineer."
+    why: Core post-writing — must-haves vs nice-to-haves, inclusive language, pay band.
+  - prompt: "I've got 80 CVs for this role, help me screen them down."
+    why: Screening the pile against a consistent job-related rubric.
+  - prompt: "Build an interview scorecard for a product manager loop."
+    why: Anchored scorecard — 3–6 competencies, 5-point scale, evidence field.
+  - prompt: "Four of us interviewed the candidate and we still can't agree — help."
+    why: Non-obvious — the answer is independent scores + calibration, not a fifth interview.
+  - prompt: "Is it legal to use an AI tool to auto-reject résumés?"
+    why: Non-obvious — triggers the NYC LL144 / EU AI Act guardrail inside the hiring flow.
+  - prompt: "Necesito una scorecard para entrevistas y redacta la oferta de empleo."
+    why: Spanish — scorecard + job post, both core hiring outputs.
+
+should_not_trigger:
+  - prompt: "Onboard our new hire — set up payroll and their first-week plan."
+    route_to: people-ops
+    why: After the offer is accepted; hiring stops at the decision.
+  - prompt: "Source 50 passive candidates with a LinkedIn outreach sequence."
+    route_to: cold-outreach
+    why: Outbound sourcing; hiring screens inbound, it does not run the outreach sequence.
+  - prompt: "Draft the offer letter and employment contract terms."
+    route_to: contracts
+    why: Hiring produces the decision; contracts drafts the binding agreement.
+  - prompt: "Run our annual algorithmic bias audit and AI-Act compliance program."
+    route_to: compliance
+    why: The legal program itself, not the hiring-flow guardrail hiring follows.
+
+capability:
+  - scenario: "We're hiring a first marketing hire. Give me the job post and the interview scorecard."
+    must_include:
+      - Splits must-haves from nice-to-haves and keeps must-haves short (≤6).
+      - Flags or avoids gender-coded language in the post.
+      - States a pay band / pay transparency in the post.
+      - Scorecard has 3–6 competencies, a 5-point anchored scale, and a required evidence field.
+      - Scorecard has one overall Hire / On-Hold / No-Hire recommendation.
+      - States score-independently-and-submit-before-debrief.
+      - Evaluates job-related criteria only; does not use "culture fit" as a competency.
+      - Does NOT drift into onboarding / payroll (that is people-ops).

package/skills/hiring/references/templates.md

@@ -0,0 +1,118 @@
+# Hiring templates
+
+Copy-paste material for the `hiring` skill: a full anchored scorecard, a
+structured question bank, a job-post skeleton with the gender-coded word list,
+and a screening rubric. Adapt the wording to the role; keep the *shape*.
+
+## Anchored scorecard (one competency at all five levels)
+
+Write anchors like this for each of your 3–6 competencies. The example below is
+"Problem-solving"; mirror the structure for the others.
+
+```text
+Competency: Problem-solving
+  1 — Vague answer. No real problem, no tradeoff, no result. Hand-wavy.
+  2 — Names a problem but cannot explain the approach or alternatives.
+  3 — Describes a decision and what they did, but thin on alternatives or
+      on the measured outcome.
+  4 — Clear problem, considered alternatives, owned the call, knows the result.
+  5 — All of 4, plus named the tradeoff explicitly and how they bounded the
+      risk; reflects on what they would change.
+  Score (1–5): __
+  Evidence (required — quote or concrete example): "____________________"
+```
+
+Overall block, filled once per interviewer per candidate:
+
+```text
+Overall recommendation:  [ ] Hire   [ ] On-Hold   [ ] No-Hire
+Rationale (one paragraph, tied to the evidence above):
+  ____________________________________________________________
+Submitted before debrief?  [ ] yes
+```
+
+## Structured question bank (by competency)
+
+Ask the same questions in the same order for every candidate. Each line is a
+behavioral / STAR or work-sample prompt; the follow-ups dig for Situation, Task,
+Action, Result.
+
+```text
+Ownership
+  "Tell me about something you owned end to end that no one asked you to fix."
+  Follow-ups: What made it yours? What did YOU do vs the team? What changed?
+
+Problem-solving
+  "Walk me through the hardest tradeoff you owned in the last year."
+  Follow-ups: Options? The one you picked and why? Measured result? Redo?
+
+Collaboration
+  "Describe a disagreement with a peer on an approach. How did it resolve?"
+  Follow-ups: Their view vs yours? What did you do? Outcome for the work?
+
+Communication
+  "Explain a complex thing you had to make a non-expert understand."
+  Follow-ups: Who was the audience? How did you check they got it?
+
+Role-craft (work-sample, swap per role)
+  Engineer: review this 40-line diff aloud — what would you change and why?
+  PM: here's a vague feature request — write the one-paragraph problem statement.
+  Marketer: here's our product — draft a 3-line value prop and who it's for.
+```
+
+## Job-post skeleton
+
+```text
+[Title] · [pay band] · [location / remote policy]
+
+[2-line hook: the mission and why this role matters — apply brand-voice.]
+
+What you'll do
+  - [3–5 concrete outcomes, not a duty list]
+
+Must-haves (cap at ~6)
+  - [job-related, verifiable; nothing learnable-on-the-job]
+
+Nice-to-haves
+  - [everything else that helps but isn't required]
+
+Comp & location
+  - [pay range, location/remote, anything material]
+
+How to apply
+  - [low-friction; ask for work, not a cover-letter ritual]
+```
+
+### Gender-coded word do/don't
+
+| Don't (masculine-coded / exclusionary) | Do (neutral / inclusive) |
+|---|---|
+| rockstar, ninja, guru, wizard | engineer, specialist, owner of |
+| aggressive, dominant, fearless | proactive, decisive, confident |
+| ambitious, driven, competitive | motivated, goal-oriented |
+| strong, crush it, kill it | capable, deliver, ship |
+| "8+ years required" as a must-have | "experience building X" (skill, not tenure) |
+| "must thrive under pressure" | "comfortable with shifting priorities" |
+| 11 named technologies, all required | one or two core, rest as nice-to-have |
+
+## Screening rubric template
+
+Score every applicant on the same rows. Blind the non-job fields before review.
+
+```text
+Candidate: ___   Role: ___   Screener: ___
+
+Job-related criteria        | pass | partial | fail
+  [must-have 1]             |      |         |
+  [must-have 2]             |      |         |
+  [must-have 3]             |      |         |
+  [work-sample signal]      |      |         |
+
+Blind these — do NOT score on them:
+  school name · candidate name · age · employment gaps · photo · address
+
+Criminal history: NOT asked at this stage (defer to post-conditional-offer).
+
+Decision: [ ] advance  [ ] work-sample to resolve  [ ] reject  [ ] parking lot
+Job-related reason (required if reject): ______________________
+```

package/skills/htmx/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: htmx
+description: "Use when adding interactivity to a server-rendered app (FastAPI/Jinja, Django, Rails, Laravel, Go templates, Express) without adopting a JS framework — hx-get/post/put/delete with hx-target, hx-swap and hx-trigger, returning HTML fragments instead of JSON, out-of-band swaps, active search, infinite scroll, inline edit and polling. NOT a client-state SPA with routing and a store (that is `react` or `nextjs`)."
+tags: [htmx, hypermedia, frontend, server-rendered, html]
+recommends: [fastapi, django, secure-coding, accessibility]
+origin: risco
+---
+
+# htmx: hypermedia-driven UIs
+
+The server owns all application state and renders HTML. The client is dumb: it swaps
+server-rendered fragments into the DOM. There is no JSON API for the UI, no client store,
+no virtual DOM, no client router. If you find yourself returning JSON and rendering it with
+JavaScript, you have stopped doing htmx and started building an SPA — use a different tool.
+
+**The unit of work is one request, described by four attributes on one element:**
+
+1. a verb — `hx-get` / `hx-post` / `hx-put` / `hx-patch` / `hx-delete` (the URL)
+2. `hx-target` — which DOM node receives the response (CSS selector or `this`)
+3. `hx-swap` — how the response is placed (default `innerHTML`)
+4. `hx-trigger` — on what event (default: natural — `click` for buttons, `submit` for forms,
+   `change` for inputs)
+
+**Versions (verify before pinning).** htmx 2.0.x is current stable (2.0.10 latest 2.x line);
+v1 (1.9.x) is legacy, kept only for IE/old-browser support. htmx v4 is in beta targeting
+Summer 2026 and changes some defaults (default swap behavior, config) — do **not** write to v4
+yet. Pin to 2.x:
+
+```html
+<script src="https://unpkg.com/htmx.org@2.0.10" crossorigin="anonymous"></script>
+```
+
+## When to use
+
+- Adding interactivity to a server-rendered app without a JS framework.
+- Wiring a verb + `hx-target` + `hx-swap` + `hx-trigger` to update a page region.
+- Returning **partials/fragments** — full page on direct navigation, fragment on htmx request
+  (branch on the `HX-Request` header).
+- Out-of-band updates (`hx-swap-oob`) when one response must refresh several regions.
+- Trigger-driven UX: active search, infinite scroll, inline edit, click-to-load, polling,
+  `revealed`, `intersect`, debounced input.
+- Server-driven control flow via response headers (`HX-Trigger`, `HX-Redirect`, …).
+
+## When NOT to use — route elsewhere
+
+- A client-state-heavy SPA (offline, optimistic UI everywhere, complex client routing) →
+  `react`, `vue-nuxt`, `svelte`, `solid-js`, `angular`, or ../nextjs/SKILL.md. htmx is the
+  anti-SPA; do not fight it.
+- How to structure the server framework itself (routers, ORM, controllers) → ../fastapi/SKILL.md,
+  `django`, `rails`, `laravel`. This skill owns the *htmx contract* (which fragment, which
+  header, which swap), not framework internals. Cross-link, do not duplicate.
+- Generic XSS/CSP/auth theory → ../secure-coding/SKILL.md. Keep only the htmx-specific notes here.
+- Focus management and ARIA live regions after a swap → `accessibility`.
+- Browser E2E of swaps → `testing-web` / `e2e-testing`.
+- Purely-client state (Alpine, vanilla sprinkles) → out of scope; htmx is for server round-trips.
+
+## Decision rules
+
+1. **Return HTML, never JSON, for the UI.** The response *is* the new DOM. JSON forces a client
+   renderer, which is the SPA you are trying to avoid.
+2. **Branch on `HX-Request`: fragment for htmx, full page otherwise.** A bookmarked URL or hard
+   refresh must still render a whole page; the htmx call gets just the partial.
+3. **The full page is the layout wrapping the *same* partial.** One template for the fragment,
+   reused inside the page layout — never two copies that drift.
+4. **Set `hx-target` and `hx-swap` explicitly when the default is wrong.** Default target is the
+   element itself; default swap is `innerHTML`. Be explicit the moment you need otherwise.
+5. **Use out-of-band swaps for multi-region updates, not multiple requests.** One action that
+   changes a list *and* a counter is one response with one OOB element.
+6. **Drive UX with `hx-trigger`, not JavaScript.** Debounce, polling, reveal, intersect are all
+   trigger modifiers — reaching for `addEventListener` usually means you missed a modifier.
+7. **Steer the client from the server with response headers.** Redirect, retarget, reswap, and
+   fire events via `HX-*` response headers instead of branching logic in the browser.
+8. **Escape everything; add CSRF yourself.** Your template engine auto-escapes — keep it on.
+   htmx does not add CSRF tokens; you propagate them via `hx-headers` or a hidden field.
+
+## Request anatomy: Bad to Good
+
+```html
+<!-- Bad: JSON endpoint + hand-written DOM patching = a tiny SPA -->
+<button id="like">Like</button>
+<script>
+  document.getElementById('like').addEventListener('click', async () => {
+    const r = await fetch('/posts/42/like', { method: 'POST' });
+    const data = await r.json();                       // JSON contract
+    document.getElementById('count').textContent = data.count;  // manual render
+  });
+</script>
+```
+
+```html
+<!-- Good: the server returns the new HTML; the element declares the swap -->
+<button hx-post="/posts/42/like"
+        hx-target="#likes"
+        hx-swap="outerHTML">Like</button>
+<span id="likes">42 likes</span>
+<!-- POST /posts/42/like responds with: <span id="likes">43 likes</span> -->
+```
+
+The Good version has no JS, no JSON, no client state. The server computed the count and rendered
+the truth; the client placed it.
+
+## Fragment rendering: branch on HX-Request
+
+Framework-agnostic rule: **if `HX-Request: true`, render the partial; otherwise render the page
+that embeds that same partial.** Concrete FastAPI + Jinja2:
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.templating import Jinja2Templates
+
+app = FastAPI()
+templates = Jinja2Templates(directory="templates")
+
+@app.get("/contacts")
+def contacts(request: Request, q: str = ""):
+    rows = search_contacts(q)
+    # htmx asked for just the table body; a browser nav gets the whole page.
+    template = "contacts/_rows.html" if request.headers.get("HX-Request") else "contacts/index.html"
+    return templates.TemplateResponse(template, {"request": request, "rows": rows, "q": q})
+```
+
+```jinja
+{# templates/contacts/index.html — the page wraps the SAME partial #}
+{% extends "base.html" %}
+{% block content %}
+  <input type="search" name="q" value="{{ q }}"
+         hx-get="/contacts" hx-target="#rows" hx-swap="innerHTML"
+         hx-trigger="keyup changed delay:500ms">
+  <table><tbody id="rows">{% include "contacts/_rows.html" %}</tbody></table>
+{% endblock %}
+```
+
+```jinja
+{# templates/contacts/_rows.html — auto-escaped; reused by page AND fragment #}
+{% for c in rows %}<tr><td>{{ c.name }}</td><td>{{ c.email }}</td></tr>{% endfor %}
+```
+
+Full per-framework wiring (Django `django-htmx` middleware, Express, CSRF per stack) is in
+[references/server-contract.md](references/server-contract.md).
+
+## Swap and target reference
+
+| `hx-swap` | Where the response goes |
+|---|---|
+| `innerHTML` | inside the target, replacing contents (default) |
+| `outerHTML` | replaces the target element itself |
+| `beforebegin` / `afterbegin` | before the target / as its first child |
+| `beforeend` / `afterend` | as its last child / after the target |
+| `delete` | deletes the target (response ignored) |
+| `none` | does not swap (use with OOB or `HX-Trigger`) |
+
+Swap modifiers: `transition:true`, `swap:<time>` (delay before swap), `settle:<time>`,
+`scroll:top|bottom`, `show:top|bottom`, `focus-scroll:false`.
+
+`hx-target` accepts a CSS selector, `this`, or an extended selector: `closest <sel>`,
+`find <sel>`, `next <sel>`, `previous <sel>`. Prefer a **stable `id`** over a fragile structural
+selector — a deep `div > div:nth-child(3)` breaks the first time markup shifts.
+
+## Out-of-band swaps
+
+When one action must refresh more than the target, mark extra elements in the response with
+`hx-swap-oob`. They are swapped into the matching live element **by `id`**, bypassing the target.
+
+```html
+<!-- Response to POST /cart/add: swap the row in normally... -->
+<tr id="row-42">2 × Widget</tr>
+<!-- ...and update the cart badge out of band (default OOB swap is outerHTML) -->
+<span id="cart-count" hx-swap-oob="true">3 items</span>
+```
+
+`hx-swap-oob="true"` defaults to `outerHTML`; you can specify a strategy
+(`hx-swap-oob="beforeend:#log"`). Use OOB instead of firing two requests for two regions.
+
+## Server-driven control flow (response headers)
+
+The server can steer htmx without any client code:
+
+| Response header | Effect |
+|---|---|
+| `HX-Trigger` | fire client event(s); JSON value `{"event": detail}` passes detail |
+| `HX-Retarget` | override `hx-target` with a CSS selector |
+| `HX-Reswap` | override `hx-swap` for this response |
+| `HX-Redirect` | full-page client redirect to the given URL |
+| `HX-Location` | client-side navigation *with* an htmx request (no full reload) |
+| `HX-Push-Url` | push a URL into history |
+| `HX-Refresh` | `true` forces a full page reload |
+
+Request headers htmx sends (read these server-side): `HX-Request`, `HX-Target`, `HX-Trigger`,
+`HX-Current-URL`, `HX-Boosted`. Full tables in
+[references/server-contract.md](references/server-contract.md).
+
+`hx-boost` is the cheapest "SPA feel": it upgrades normal `<a>`/`<form>` to AJAX that swaps
+`<body>` with `pushState` history — no SPA, no JSON.
+
+## Security (htmx-specific only)
+
+htmx makes HTML more expressive, so **injected HTML is an XSS surface**. The htmx-specific rules
+(generic theory lives in ../secure-coding/SKILL.md):
+
+- **Keep your template engine's auto-escaping on.** Never `| safe` / `|safe` user-controlled
+  content. Manually rendering raw user HTML re-introduces XSS that escaping had closed.
+- **When you must inject third-party HTML, scrub it with a whitelist** — strip `hx-*`/`data-hx-*`
+  attributes and inline scripts. An injected `hx-get` would issue requests you never intended.
+- **`hx-disable` halts htmx processing for a subtree** as defense-in-depth — but it is bypassable
+  by closing the tag, so it is *not* a primary control. Sanitize at the source.
+- **`htmx.config.selfRequestsOnly` defaults to `true` in 2.x** — keep it. It blocks htmx requests
+  to other origins.
+- **CSRF is your job.** htmx sends same-origin requests but adds no CSRF token. Propagate it:
+  `<body hx-headers='{"X-CSRF-Token": "…"}'>` or a hidden form field.
+- **Guard `HX-Redirect` / `HX-Location`** — never build them from attacker-controlled values;
+  a `javascript:` URL there is an injection.
+
+## UX recipes
+
+Worked, copy-ready recipes — server fragment + client markup for each — live in
+[references/patterns.md](references/patterns.md):
+
+- **Active search** — debounced `keyup changed delay:500ms` filtering a results table.
+- **Infinite scroll / click-to-load** — `hx-trigger="revealed"` or a "load more" button.
+- **Inline edit (click-to-edit)** — swap a row to a form and back.
+- **Delete row + OOB count** — remove a row and update a counter in one response.
+- **Modal dialog** — load a dialog fragment on demand.
+- **Progress bar** — `every 600ms` polling closed by an `HX-Trigger` event.
+- **Tabs / accordion** — swap the active panel.
+
+## Common triggers
+
+| `hx-trigger` value | Use |
+|---|---|
+| `keyup changed delay:500ms` | active search (debounced, only on real change) |
+| `every 2s` | polling a progress/status region |
+| `revealed` | infinite scroll — load when the sentinel scrolls into view |
+| `intersect once` | lazy-load a region once it enters the viewport |
+| `load delay:1s` | deferred load after the page paints |
+| `click[ctrlKey]` | event filter — only ctrl-click |
+| `submit` / `change` | natural defaults for forms / inputs |
+| `customEvent from:body` | react to an `HX-Trigger`-fired event from elsewhere |
+
+Modifiers worth knowing: `throttle:<time>`, `queue:first|last|all|none`, `from:<sel>`, `once`,
+`changed`, `delay:<time>`.
+
+## Anti-patterns
+
+| Anti-pattern | Why it is wrong | Do instead |
+|---|---|---|
+| Endpoint returns JSON, JS renders it | that is an SPA; you lose htmx's whole point | return the HTML fragment; the server renders |
+| No `HX-Request` branch | the fragment leaks the full layout (nested `<html>`) on htmx calls, or a bookmark renders a bare partial | branch: partial vs page wrapping the same partial |
+| Two copies of the fragment (page + ajax) | they drift; bug fixed in one, not the other | one partial template, `{% include %}`d by the page |
+| Polling `every 1s` for a one-off event | wasteful traffic; hammers the server | poll only while pending, end it with `HX-Trigger`/`hx-swap-oob`; or use SSE |
+| `hx-target="div > div:nth-child(3)"` | structural selectors shatter when markup shifts | target a stable `id` |
+| `{{ user_html | safe }}` | unescaped user content → XSS | keep auto-escaping; whitelist-scrub if injecting 3rd-party HTML |
+| Rebuilding client state in `hx-on`/JS | re-creates the SPA state you came here to avoid | let the server hold state; re-render from it |
+| Multiple requests to update related regions | extra round-trips, races | one response + `hx-swap-oob` |
+
+## See also
+
+- ../fastapi/SKILL.md — FastAPI routes/templates that serve these fragments.
+- ../secure-coding/SKILL.md — the general XSS/CSP/auth theory this skill defers to.
+- ../nextjs/SKILL.md — when the requirement really is a React/SPA app, not hypermedia.
+- `django`, `rails`, `laravel` — other server frameworks (the htmx contract is identical).
+- `accessibility` — focus and ARIA after a DOM swap.

package/skills/htmx/evals/README.md

@@ -0,0 +1,3 @@
+# htmx evals
+
+Trigger and capability checks for htmx hypermedia UI work.