@bompus/house-rules 0.0.0-stage → 0.11.0

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+Issues and pull requests are welcome: a rule an agent misreads, a modifier
+or skill that would help other setups, a bug in `compose.mjs`.
+Everyone taking part follows the [code of conduct](CODE_OF_CONDUCT.md).
+
+## What fits
+
+House-rules is a practical starting point for ordinary development with AI
+coding agents. Include guidance for common work or a recurring failure with a
+clear benefit over existing rules, tools and skills.
+
+For a new rule, modifier or skill, show:
+
+1. The concrete problem and representative developer task.
+2. The existing alternative and why it is insufficient.
+3. Evidence for the behavior, including when it should stay inactive.
+4. Its cost in setup choices, loaded context, dependencies and maintenance.
+5. Why it belongs here rather than in personal or project guidance.
+
+Portability and explicit invocation alone do not establish a reason to include
+a workflow. Prefer improving existing guidance or tools. Keep speculative
+procedures and personal operating habits in their own layers.
+
+Always-on rules must be broadly useful and preserve project choices. Default
+skills must support routine work with little setup. Specialist additions need
+a concrete shared use case and stay out of fresh defaults. Introduce them when
+the relevant task arises; setup should not require choosing from the catalog.
+
+Everything here must work for anyone's projects. Leave out names of private
+projects or repositories, local paths, home directories and credentials. A
+preference only some users want belongs in an opt-in modifier, not in
+`rules/core.md`.
+
+When you change rule wording, say in the pull request which agent behavior
+it changes and how you saw it. The end-of-reply eval in `evals/end-of-reply/`
+is one way to show it.
+
+## Before you open a pull request
+
+1. Run the checks in the README's Development section. CI runs them too.
+2. Add a `CHANGELOG.md` entry under `Unreleased` for any change users will
+   notice. The maintainer batches approved changes into versioned releases;
+   each pull request does not need its own version or tag.
+
+## How changes land
+
+The maintainer lands pull requests by rebasing them onto `main` and
+fast-forwarding, so your commits keep you as their author. Contributions are
+licensed under the MIT licence in `LICENSE`. When you adapt someone else's
+work, record its source and applicable licence notices in `THIRD_PARTY_NOTICES.md`.
+A skill copied on its own must carry those notices inside its bundle, such as
+`NOTICE.md` or `LICENSE`. Keep source references in instructions when they help
+the task; pure credit belongs in the notices.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Queen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,348 @@
-# Temporary Holding Version
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.png">
+    <img src="docs/assets/banner-light.png" alt="house-rules" width="100%">
+  </picture>
+</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://github.com/bompus/house-rules/actions/workflows/check.yml"><img src="https://github.com/bompus/house-rules/actions/workflows/check.yml/badge.svg" alt="CI status"></a>
+  <a href="https://github.com/bompus/house-rules/releases/latest"><img src="https://img.shields.io/github/v/release/bompus/house-rules" alt="Latest release"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/bompus/house-rules" alt="MIT license"></a>
+</p>
+
+A practical starting point for ordinary development with AI coding agents.
+Fresh installs select eight skills for setup, review, diagnosis, explanation,
+planning, tests, writing and remaining work. Modifiers start off. Add guidance
+when a task needs it, and let each repository supply its own safeguards.
+
+<p align="center"><img src="docs/assets/overview.png" alt="The four layers composed into one rules file: core, opt-in modifiers, your layer and each repository's AGENTS.md. The eval figures in this illustration come from an early internal run and are not a current result." width="100%"></p>
+
+If you are an AI agent reading this for your user, the prompt under
+[Evaluate it with your agent](#evaluate-it-with-your-agent) is the evaluation
+they would ask for. Summarize how it fits their setup and let them choose;
+don't install or copy anything on your own.
+
+## How the layers fit
+
+1. **Core** (`rules/core.md`): the base every setup gets. Its first section is
+   the end-of-reply check, so an agent that reads only the top of the file
+   still knows when to keep working and when to stop and ask.
+2. **Modifiers** (`rules/modifiers/`): opt-in preferences, such as coded
+   option lists or squash-only landing. Each one replaces a core section or
+   adds a section after one.
+3. **Your layer** (by default `~/.config/house-rules/`): `house-rules.json`
+   names the modifiers you enable, `rules/` holds your own sections, and
+   `skills/` holds your own skills. A skill there replaces the house-rules
+   skill of the same name. The config's other keys are optional: `layers`
+   lists layer directories relative to the config (default `["."]`, its own
+   directory). `skills.include` selects shipped skills; omitting it keeps the
+   full shipped set for existing configs. Personal skills remain included.
+   `skills.exclude` leaves names out of every layer. `skills.independent` records
+   generic personal names you intend to keep beside renamed house-rules skills.
+4. **The repository** (`AGENTS.md`, `CLAUDE.md` or your host's equivalent):
+   its commands, branch names, safeguards, required checks and landing path.
+   It adds to your rules and does not replace them. See
+   `examples/project/AGENTS.md` for the pattern: point at the house rules
+   instead of restating them, and add only what the project needs.
+
+`compose.mjs` merges layers 1 to 3 into one rules file. A replaced section
+leaves no trace of the old text, because an agent given two versions of a rule
+tends to follow either one. Composition fails on a duplicate heading, an
+unknown target or any attempt to replace the end-of-reply check.
+
+## Quick start
+
+Requires `git` and either [Bun](https://bun.sh) 1.4 or newer or Node.js 22 or
+newer. On Linux, macOS or WSL, one line installs or updates the selected guidance:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/bompus/house-rules/main/install.sh | sh
+```
+
+On Windows 10 or 11, run this in PowerShell instead:
+
+```powershell
+irm https://raw.githubusercontent.com/bompus/house-rules/main/install.ps1 | iex
+```
+
+To read the script before it runs:
+
+```bash
+curl -fsSLO https://raw.githubusercontent.com/bompus/house-rules/main/install.sh
+less install.sh
+sh install.sh
+```
+
+```powershell
+irm https://raw.githubusercontent.com/bompus/house-rules/main/install.ps1 -OutFile install.ps1
+notepad install.ps1
+powershell -ExecutionPolicy Bypass -File install.ps1
+```
+
+The script picks the newest Bun 1.4 or newer it finds on `PATH` or in a
+version manager's directory, otherwise the newest Node.js 22 or newer. It
+clones this repository to `~/.local/share/house-rules` (or pulls it when it is
+already there), copies `examples/person/house-rules.json` to
+`~/.config/house-rules/` when you have no config yet, and composes
+`~/.config/house-rules/rules.md` and `~/.config/house-rules/composed-skills`.
+Those are the default paths: a set `XDG_DATA_HOME` replaces `~/.local/share`,
+and a set `XDG_CONFIG_HOME` replaces `~/.config`. On Windows the checkout goes
+to `%LOCALAPPDATA%\house-rules` and the config to
+`%USERPROFILE%\.config\house-rules`.
+The fresh config selects the eight skills named above and no modifiers.
+Updates preserve your existing config. An explicit `skills.include` list keeps
+later shipped additions off until selected. Browse the full catalog only when
+you want more choices.
+
+On a later run it keeps the previous skills directory under a dated name
+instead of deleting it. It never edits an agent host's files. The comment at
+the top of `install.sh` lists the environment variables that change its paths
+or runtime; `install.ps1` takes the same variables. Some skill scripts need Bun
+even when Node.js composes the rules.
+
+Then connect the composed file to your agent. Claude Code reads
+`@~/.config/house-rules/rules.md` on its own line in `~/.claude/CLAUDE.md`;
+other hosts take a copy in their user-level rules file, with the
+`house-rules-references/` directory placed beside it. Written rules link to the
+procedures in that directory; stdout and configuration previews keep them
+inline. See [reference output](docs/configuration.md#reference-output). To change modifiers or
+skills, change to the checkout directory and run `node compose.mjs setup`,
+or `bun compose.mjs setup` when Node.js is unavailable. Review the numbered
+choices and use `save` to change only the configuration. Then run the
+installer again.
+The [configuration CLI guide](docs/configuration.md) covers status, previews,
+question preferences and safe writes. The
+`hr-house-rules-setup` skill preserves selections, offers relevant additions and connects
+hosts, and asks before it touches a host file.
+
+### npm distribution
+
+`@bompus/house-rules` is published to npm. The package provides the
+`house-rules` composition and configuration commands. Installation has no
+lifecycle hooks and does not connect an agent host or change its settings.
+
+```bash
+npm install --global @bompus/house-rules
+house-rules --list
+house-rules config help
+house-rules --config ./house-rules.json --out ./rules.md --skills-out ./composed-skills
+```
+
+Create your configuration before composing. The
+[configuration guide](docs/configuration.md) describes the available choices.
+The package bundles rules, skills, their resources and documentation. With the
+npm package, run `house-rules setup` to change modifiers or skills. Git-based
+installers follow the default branch; npm follows published versions.
+
+### Manual steps
+
+To keep the checkout somewhere else, run the same steps by hand. The commands use `node`; `bun` runs them the same way.
+
+```bash
+git clone https://github.com/bompus/house-rules.git
+cd house-rules
+node compose.mjs --list
+mkdir -p ~/.config/house-rules
+cp examples/person/house-rules.json ~/.config/house-rules/
+node compose.mjs --config ~/.config/house-rules/house-rules.json \
+  --out ~/.config/house-rules/rules.md --skills-out ~/.config/house-rules/composed-skills
+```
+
+To recompose later, move or remove the old `composed-skills` directory first,
+because `--skills-out` must be empty or absent. `compose.mjs` writes the rules
+file, a `house-rules-references/` directory beside it (or at `--references-out`)
+when the rules include reference procedures, and `--skills-out` when given. It never deletes anything.
+
+When distributing a rules-only output, carry this checkout's `LICENSE` and
+`THIRD_PARTY_NOTICES.md` alongside it. Copy them into an explicit destination
+and reconcile existing notice files before replacing them. A full
+`--skills-out` export already includes both at its root. When copying one
+skill, keep its entire directory, including any `NOTICE.md` and `LICENSE`.
+Personal layers must also carry notices required by their own sources.
+
+The `hr-navigation-retro` skill finds navigation failures in selected tool-call
+transcripts, then proposes fixes verified against current source. Any agent with
+file and shell access can run it. Supported inputs include Claude Code, Codex,
+OpenCode exports, Cursor CLI streams and ACP v1 recordings from other agents.
+See its [input limits](skills/hr-navigation-retro/references/inputs.md).
+It is explicit-only, requires Python 3.11+ and keeps reports local.
+
+## Upgrading skill names
+
+All shipped skill names use `hr-`. Before updating an older installation,
+follow [the skill name upgrade guide](docs/skill-names.md) to preserve exclusions
+and personal overrides. Composition stops on ambiguous old names before
+writing output. Host links and copies need a separate update.
+
+## Evaluate it with your agent
+
+Paste this into a session with the agent you use. It compares house-rules with
+the rules you already have and changes nothing until you choose.
+
+```text
+I'm considering house-rules (https://github.com/bompus/house-rules), working
+rules and skills for AI coding agents. Read its README, rules/core.md,
+rules/modifiers/ and the skills list, then compare them with the rules and
+skills I already use (my user-level rules file for this host and this
+repository's AGENTS.md or equivalent). Tell me:
+1. Which rules, modifiers or skills would change how you work with me, with
+   an example from how you work now.
+2. Which ones duplicate or conflict with what I already have.
+3. Whether to adopt it whole (compose.mjs plus my own layer) or copy single
+   sections into my existing rules. Taking individual ideas is fine.
+If I run several agent sessions on one machine at once, also look at
+Swarmail (https://github.com/bompus/swarmail); house-rules has an opt-in
+modifier for it.
+Read only: don't install, compose or edit anything until I choose. When I
+adopt a section or idea, record its source in distributed notices, such as
+"Adapted from house-rules (https://github.com/bompus/house-rules)". Keep required
+licence notices with copied text and standalone skill bundles.
+```
+
+Taking individual ideas is welcome. If you adopt any, we'd appreciate a
+source credit in your distributed notices. Copying substantial text also needs
+the MIT notice kept (see `LICENSE`).
+
+## Writing your own sections
+
+A rules file in your layer starts with frontmatter that names one operation
+and a core heading, followed by its own `## ` heading:
+
+```markdown
+---
+after: Implementation economy
+---
+
+## My tooling
+
+Use pnpm for JavaScript projects unless the repository uses another manager.
+```
+
+The operations are `replaces:`, `after:`, `before:` and `removes:`; a
+`removes:` file has no body. A file without frontmatter is added at the end.
+Frontmatter may also hold `description:` and `requires:` (a comma-separated
+list of skills the section relies on); any other key is an error. Files apply
+in name order, after the modifiers.
+
+## Modifiers
+
+| &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Modifier&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; | What it does                                                                                                                                                                                                                   |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `coded-offers`                                                                                                                                           | Offers use numbered questions and coded options (`1A`, `1B`) so one short reply answers every decision.                                                                                                                        |
+| `effort-estimates`                                                                                                                                       | Options that differ in cost, or work that waits on CI, a build or a deploy, carry a wall-clock estimate based on comparable finished work. Estimates from workers, docs or other models are converted the same way or dropped. |
+| `land-when-done`                                                                                                                                         | Authorized repository work is not finished until it is in the remote default branch.                                                                                                                                           |
+| `low-quota-handoff`                                                                                                                                      | When the current model's usage allowance runs low, write a handoff before work stops.                                                                                                                                          |
+| `multi-agent`                                                                                                                                            | Work is split across delegated workers and several agent hosts; worker reports, review standards and cleanup checks account for all of them.                                                                                   |
+| `no-attribution`                                                                                                                                         | Commits, pull requests and comments carry no agent or tool credit lines.                                                                                                                                                       |
+| `plan-files`                                                                                                                                             | Multi-step work keeps a visible task list mirrored to a plan file with a ledger of every item's outcome.                                                                                                                       |
+| `question-cards`                                                                                                                                         | Opt in to question cards beside complete text offers when the host supports them; availability and presentation can vary by host, provider and model.                                                                          |
+| `release-batching`                                                                                                                                       | Batch approved, compatible changes for releases and audit factual claims before releases or public announcements.                                                                                                              |
+| `scratch-on-disk`                                                                                                                                        | Task scratch lives on disk under the user data directory, never in RAM-backed `/tmp`.                                                                                                                                          |
+| `shared-host-load`                                                                                                                                       | Coordinate shared local work within host-defined resource budgets; isolate measurements and release reservations during remote waits.                                                                                          |
+| `solo-operator`                                                                                                                                          | For repositories with one maintainer, the user's direction is the review; no review-gated steps.                                                                                                                               |
+| `squash-landing`                                                                                                                                         | Pull requests land by squash merge after review-bot findings are handled, and the session's checkout moves off the landed branch.                                                                                              |
+| `swarmail`                                                                                                                                               | Locate Swarmail-owned instructions and tool contracts for local session coordination.                                                                                                                                          |
+
+Questions use text by default, with plain options or `coded-offers`. Text-only
+setups do not call question-card tools merely because a host exposes them.
+Enable `question-cards` only when you want cards too. Cards can be unavailable,
+skipped or shown unexpectedly across hosts, providers and models; the text
+offer remains usable on its own. `hr-house-rules-setup` asks which format you
+want and explains these limits before changing the configuration.
+
+## Skills
+
+| Skill                       | Use it to                                                                                                 |
+| --------------------------- | --------------------------------------------------------------------------------------------------------- |
+| `hr-agent-guidance-audit`   | Audit a repository's agent guidance for stale, duplicated or conflicting rules.                           |
+| `hr-agent-guidance-refresh` | Re-read guidance that changed since the session started.                                                  |
+| `hr-api-exposure-check`     | Keep API responses to the fields a consumer reads and the caller may see.                                 |
+| `hr-audit-choices`          | List and check the decisions made while implementing a task.                                              |
+| `hr-benchmarking`           | Design, run and assess timing, CPU and memory comparisons; choose tools by the question they answer.      |
+| `hr-better-accessibility`   | Build and review keyboard access, semantics, forms, focus, motion and reflow in web UI.                   |
+| `hr-better-colors`          | Choose and check palettes, semantic tokens, themes, gamut and rendered contrast.                          |
+| `hr-better-layout`          | Build and review grouping, alignment, spacing, responsive layout and clipping.                            |
+| `hr-better-typography`      | Style and review type scales, wrapping, spacing, truncation and font loading.                             |
+| `hr-better-writing`         | Write and review interface labels, errors, empty states and product terminology.                          |
+| `hr-change-impact`          | Check what a change can break beyond its diff before merging.                                             |
+| `hr-code-review`            | Review a diff against the repository's standards and the originating request.                             |
+| `hr-design-exploration`     | Compare four visual directions and refine the selected two toward one final design.                       |
+| `hr-diagnosing-bugs`        | Work a hard bug or regression to a confirmed cause.                                                       |
+| `hr-explain-code`           | Trace how existing code works, read-only, before changing it.                                             |
+| `hr-extract-shared-steps`   | Move operations repeated across workflows into shared functions.                                          |
+| `hr-handoff`                | Write a handoff a fresh session can resume from.                                                          |
+| `hr-house-rules-setup`      | Choose modifiers, create your layer and connect your hosts.                                               |
+| `hr-issue-tracker-setup`    | Configure project tracker, domain-term and ADR conventions; explicit-only.                                |
+| `hr-lean-plan`              | Write or tighten an implementation plan with the fewest moving parts.                                     |
+| `hr-maintainability-review` | Review a diff or entire codebase strictly for structure and maintainability.                              |
+| `hr-manual-qa`              | Give reproducible human checks after reporting agent verification results.                                |
+| `hr-navigation-retro`       | Audit navigation failures in selected transcripts and propose verified findability fixes; explicit-only.  |
+| `hr-ordering-tests`         | Enumerate event orderings through the real code to find race bugs.                                        |
+| `hr-plain-prose`            | Make text people read plain and specific.                                                                 |
+| `hr-progress-report`        | Report current task activity, milestone completion and remaining wall-clock time.                         |
+| `hr-pr-followup`            | Address conflicts, feedback and failing checks for a requested PR; honor existing landing authority.      |
+| `hr-read-reddit`            | Read Reddit feed output while supported; RSS support ends November 13, 2026. Partial web-search fallback. |
+| `hr-read-x-links`           | Read the full content of X posts.                                                                         |
+| `hr-split-to-prs`           | Divide work into coherent PRs while preserving recovery points and verifying each slice.                  |
+| `hr-stock-ui-audit`         | Find and triage template-default styling in frontend code.                                                |
+| `hr-tdd`                    | Implement requested test-first work through one red-green slice at a time; simplify during review.        |
+| `hr-test-audit`             | Decide which new tests are worth keeping and which old ones to prune.                                     |
+| `hr-what-next`              | Reconcile remaining session work and recommend priorities when asked what comes next.                     |
+| `hr-writing-for-agents`     | Write skills, rules and other documents agents read.                                                      |
+| `hr-writing-pr`             | Write a pull request title and body from the final diff.                                                  |
+
+## Checking the rules against your models
+
+`evals/end-of-reply/` runs short scenarios through any model CLI and grades
+whether the agent keeps working or ends with an offer at the right time,
+including when it reads only the first 80 lines. In a 2026-10-04 run of the
+three original scenarios against v0.5.7 on seven models, the rules passed 62 of
+63 replies, against 26 for a one-sentence instruction and 21 with no rules; its
+README has the breakdown and limits.
+
+## Development
+
+```bash
+node --test test/*.test.mjs   # composer and eval grader (or: bun test test/)
+bun test skills/    # skill scripts
+npx oxlint . && npx oxfmt --check .
+```
+
+Oxfmt checks authored Markdown, HTML, JSON, JSONC, YAML, TOML and CSS as well
+as JavaScript and TypeScript. Test fixtures stay excluded because scanner
+tests depend on their exact text and line numbers. Package fields and
+dependency maps are sorted; script order is preserved.
+
+Tests remove their own fixture directories after each test, including failures.
+Set `HOUSE_RULES_TEST_TMP` to an existing directory to choose their scratch root;
+otherwise they use the operating system temporary directory. Choose a disk-backed
+location when the system temporary directory is RAM-backed.
+
+CI runs the same checks on every push and pull request. See
+[CONTRIBUTING.md](CONTRIBUTING.md) before opening one.
+
+The local-reference gate runs in `test/guidance-links.test.mjs`. Audit another
+checkout with `node guidance-links.mjs --root <checkout> --repository
+owner/repo=<local-checkout>`; repeat `--repository` for other available sources.
+Its JSON report identifies GitHub file pointers to replace. When a remote
+link deliberately cites current provenance, downloads a file or refreshes
+upstream guidance, use one of these comments on that line. Each needs a reason:
+
+- `<!-- local-reference: source <reason> -->`
+- `<!-- local-reference: download <reason> -->`
+- `<!-- local-reference: remote-refresh <reason> -->`
+
+Pinned history and images are exempt.
+
+## Sponsoring
+
+house-rules is built and maintained by one person. If it saves you time, you can
+sponsor it monthly or once through
+[GitHub Sponsors](https://github.com/sponsors/bompus), or leave a tip on
+[Ko-fi](https://ko-fi.com/bompus).
+
+## Licence
+
+MIT. Some skills adapt MIT-licensed work, and `CODE_OF_CONDUCT.md` is the
+Contributor Covenant under CC BY 4.0; see `THIRD_PARTY_NOTICES.md`.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,188 @@
+# Third-party notices
+
+Some files in this repository copy or adapt work published under the MIT
+License. Each source's copyright notice and the licence text follow.
+`CODE_OF_CONDUCT.md` is the Contributor Covenant, under CC BY 4.0, noted at
+the end.
+
+## Cursor workflow ideas
+
+Source: https://cursor.com/docs/skills
+
+- `skills/hr-split-to-prs/`: independently written workflow informed by the
+  purpose of Cursor's built-in `split-to-prs` skill.
+- `skills/hr-pr-followup/`: independently written workflow informed by the
+  purpose of Cursor's built-in `autopilot` skill.
+
+These bundles distribute no Cursor instruction text. Their MIT licence applies
+to newly written house-rules material, not to the Cursor skills.
+
+## mattpocock/skills
+
+Source: https://github.com/mattpocock/skills (compared at revision `d81f3a1`)
+
+- `skills/hr-writing-for-agents/`: adapted from `skills/productivity/writing-for-agents/`.
+- `skills/hr-code-review/`: adapted from `skills/engineering/code-review/`.
+- `skills/hr-handoff/`: adapted from `skills/productivity/handoff/`.
+- `skills/hr-diagnosing-bugs/`: written for this repository after
+  `skills/engineering/diagnosing-bugs/`, which it shares a purpose with.
+
+- `skills/hr-tdd/`: adapted from `skills/engineering/tdd/` at revision
+  `f3fc5632f401156837ee3872f14fe33ccf1024ea`. The bundle carries its MIT notice.
+
+Copyright (c) 2026 Matt Pocock
+
+## obra/superpowers
+
+Source: https://github.com/obra/superpowers (compared at revision `8ca22db`)
+
+- `skills/hr-writing-for-agents/SKILL.md`: the instruction-form table is adapted
+  from `writing-skills`. Its wording tests found that a recipe beat a prohibition
+  for shape failures.
+- `skills/hr-test-audit/SKILL.md`: cites `writing-good-tests.md`.
+
+Copyright (c) 2025 Jesse Vincent
+
+## addyosmani/agent-skills
+
+Source: https://github.com/addyosmani/agent-skills (compared at revision `9d0c60d`)
+
+- `skills/hr-test-audit/scripts/floor-guard.ts`: adapted from
+  constraint-driven-development.
+
+Copyright (c) 2025 Addy Osmani
+
+## openclaw/openclaw
+
+Source: https://github.com/openclaw/openclaw (linked at revision `65f1e4d`, compared at `1fda703`)
+
+- `skills/hr-test-audit/SKILL.md`: the authoring gate, junk patterns, retention
+  bar and evidence fields are adapted from `.agents/skills/test-audit/`.
+
+Copyright (c) 2026 OpenClaw Foundation
+
+## no-human-ai/no_human
+
+Source: https://github.com/no-human-ai/no_human (compared at revision `9b50bf6`)
+
+- `skills/hr-test-audit/SKILL.md`: the rule that weakening a test counts as
+  removing it is adapted from its tamper guard.
+- `skills/hr-code-review/references/evidence.md`: test-weakening assessment and
+  refuting completion claims are informed by its verification approach.
+
+Copyright (c) 2026 Eyal Golan
+
+## omkamal/pypict-claude-skill
+
+Source: https://github.com/omkamal/pypict-claude-skill (compared at revision `fbda212`)
+
+- `skills/hr-test-audit/SKILL.md`: the pairwise-coverage guidance is adapted from
+  this skill.
+
+Copyright (c) 2025 pypict-claude-skill contributors
+
+## sickn33/antigravity-awesome-skills
+
+Source: https://github.com/sickn33/antigravity-awesome-skills (compared at revision `7bb0ab4`)
+
+- `skills/hr-writing-pr/SKILL.md`: selected ideas from
+  `skills/git-pr-workflows-pr-enhance/`. Selected ideas also come from
+  [Luke Parker's writing-pr post](https://x.com/LukeParkerDev/status/2096769160021979571).
+
+Copyright (c) 2026 Antigravity User
+
+## cursor/plugins (pstack)
+
+Source: https://github.com/cursor/plugins (compared at revision `e43c7ee`)
+
+- `rules/core.md`: the § Implementation economy bullet on scripting changes
+  that span more than three places is adapted from
+  `pstack/skills/principle-build-the-lever/`.
+- `skills/hr-diagnosing-bugs/SKILL.md`: § Question the premise is adapted from
+  `pstack/skills/principle-attack-the-premise/`.
+- `skills/hr-benchmarking/SKILL.md`: the validity checks are adapted from
+  `pstack/skills/benchmark-checklist/`.
+
+Copyright (c) 2026 Lauren Tan
+
+## jakubkrehel/skills
+
+Source: https://github.com/jakubkrehel/skills (compared at revision `267330e1adfc66a718fb65fa6918c1f06d0a689e`)
+
+- `skills/hr-better-accessibility/`, `skills/hr-better-colors/`, `skills/hr-better-layout/`,
+  `skills/hr-better-typography/` and `skills/hr-better-writing/`: adapted skill bundles,
+  including their supporting references and discovery metadata.
+
+Copyright (c) 2026 Jakub Krehel
+
+## emilkowalski/skills
+
+Source: https://github.com/emilkowalski/skills (compared at revision `e8a175de22ae1e49370fc144c1f3bb9aeedf988d`)
+
+- `skills/hr-better-accessibility/` and `skills/hr-better-layout/`: mobile behavior and
+  viewport guidance adapted from `skills/mobile-native/SKILL.md`.
+- `skills/hr-better-layout/`, `skills/hr-better-typography/` and `skills/hr-better-writing/`:
+  clipping, truncation and plural-form guidance adapted from `skills/break-ui/SKILL.md`.
+
+Copyright (c) 2026 Emil Kowalski
+
+## humanlayer/skills
+
+Source: https://github.com/humanlayer/skills (compared at revision `bba9d13ab34f0a87f1cc33df4dd196372393ddfc`)
+
+- `skills/hr-explain-code/SKILL.md` and `skills/hr-writing-pr/SKILL.md`: compact
+  visual explanation and focused structural-diff guidance adapted from
+  `plugins/show-me/skills/show-me/SKILL.md`.
+
+Copyright (c) 2026 HumanLayer
+
+## Jeanno/jeanno-skills (ideas)
+
+Source: https://github.com/Jeanno/jeanno-skills (compared at revision `db4e8fd66197ece38d622ca8b527dbe821843df2`)
+
+- `skills/hr-manual-qa/SKILL.md`: independently written instructions informed by
+  the reproducible-checklist idea in `skills/qa-checklist/SKILL.md`.
+- `rules/core.md`: independently written correction handling informed by the
+  dependent-work sweep in `skills/realign/SKILL.md`.
+
+No source text from this repository is copied here.
+
+## ayghri/i-have-adhd (ideas)
+
+Source: https://github.com/ayghri/i-have-adhd (compared at revision `723af7d9afaf43eb871dbcce6129e2bf80de90d5`)
+
+- `rules/core.md`: independently written guidance informed by the small visible
+  list idea in `skills/i-have-adhd/SKILL.md`.
+- `skills/hr-plain-prose/SKILL.md`: independently written reply check informed
+  by the first-and-last-line check in that skill.
+
+No source text from this repository is copied here.
+
+## MIT License text
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Contributor Covenant
+
+Source: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+
+- `CODE_OF_CONDUCT.md`: version 2.1, with this repository's reporting method
+  filled in. Licensed under
+  [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); its own
+  Attribution section credits the source.