@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-writing-for-agents/SKILL-MECHANICS.md

@@ -0,0 +1,83 @@
+# Skill mechanics
+
+The skill-specific branch of [`hr-writing-for-agents`](SKILL.md): frontmatter, invocation choice, testing a description or output, and router skills. The main skill owns writing guidance.
+
+## Invocation
+
+Choose whether the host may select the skill implicitly or whether the user must request it. Keep a concise description that states its scope.
+
+Configure invocation through the host's supported mechanism. [Codex documents](https://learn.chatgpt.com/docs/build-skills#optional-metadata) `policy.allow_implicit_invocation` in `agents/openai.yaml`; setting it to `false` prevents implicit invocation while explicit invocation remains available. Use `disable-model-invocation` only for a host whose documentation supports it.
+
+When a user invokes a skill with arguments, Claude Code substitutes `$0`, `$1`, … and `$ARGUMENTS` anywhere in the skill text, so a price written as `$0.01` renders as the first argument followed by `.01`. Write amounts as `0.01 USD` in skill files.
+
+Make each runnable block in a skill self-contained. Hosts differ on whether a variable, `cd` or sourced function survives from one tool call to the next, so a later block that needs a value says where to get it rather than relying on an earlier block's shell. Branches between blocks read better as numbered steps than as shell conditionals.
+
+Do not assume an invocation setting hides metadata, prevents reading a referenced file, or has the same effect across hosts. Invocation policy alone does not establish context-token savings.
+
+## Testing a description
+
+A description is a context pointer, so judge a rewrite by whether it fires on
+the right requests, not by how it reads. Compare the current and the new
+wording on the same prompts: requests that should trigger the skill, taken
+from real use where possible, plus near-misses that belong to a neighbouring
+skill. Run each prompt at least three times per wording; one run is noise.
+Keep the rewrite only when it fires more without firing on the near-misses,
+then add the missed prompts as a trigger eval.
+
+Test in an isolated copy of the skill catalog, never by editing installed
+skill files, which every live session on the host reads. With Claude Code,
+copy the skills into a scratch plugin, edit the copy, and read the first
+`Skill` call from each run:
+
+```bash
+claude -p "<prompt>" --setting-sources project --plugin-dir <catalog-copy> \
+  --max-turns 2 --output-format stream-json --verbose
+```
+
+`--setting-sources project` hides the user-level skills, so only the copy
+loads. Run the repository's skill tests on the new frontmatter before
+trusting a result: Claude Code accepts an unquoted description containing
+`: `, but a strict YAML parser rejects it, so quote such descriptions.
+Prompts lifted from old sessions often fire nothing without their
+conversation; count that as a limit of the test set, not of the wording.
+
+## Testing output
+
+A trigger eval shows that the skill fires; an output case shows that it does
+its job. Give each case a prompt that carries the whole input (a diff, a
+scenario), so a run needs no repository.
+
+- The runner sees only the prompt, in a fresh session. A separate judge grades
+  the reply against a bar: the outcome a good reply reaches and the smells that
+  fail it. Name a specific item only when missing it is the failure; a full
+  answer key tests conformance, not the skill's judgment.
+- Run each case with and without the skill, at least three times per arm, and
+  read the delta, not the with-skill score. When the no-skill arm passes too,
+  the case cannot measure the skill: read both arms' replies, then raise the
+  bar to what the skill promises beyond a plain answer.
+- Before editing the skill over a miss, decide whether the skill failed or the
+  bar asked for something the skill should not do. Fix the bar in the second
+  case.
+- After an edit, re-run every case for that skill, since a fix can regress a
+  passing one.
+- To compare wordings of one instruction, run five or more fresh samples per
+  wording plus a no-guidance control. If the control does not show the
+  failure, there is nothing to fix. Read the spread as well as the average: a
+  wording that gives the same result every run beats a noisier one with a
+  similar mean.
+
+When your host has a skill-eval runner (Claude Code's `claude plugin eval`,
+for example), run the cases under it: it supplies the fresh runner, a grader
+and the no-skill arm. Check its help for how it selects several cases at once:
+Claude Code's `--case` takes one glob and a repeated flag keeps only the last,
+so select several cases by a shared name prefix (`--case 'audit-*'`), and the
+replies land in the run's `aggregate-result.json`. Its results cover that
+host's skill selection only; other hosts need their own runs.
+
+## Splitting by invocation
+
+Split off a skill when it handles a distinct task the user or another workflow needs to select independently. Define its trigger and invocation policy for the supported hosts. Keep shared reference in a plain file when several workflows need it.
+
+## Router skills
+
+A router names related skills and when to use them. State whether it suggests a skill to the user or invokes it under the active host's policy. Referencing a file and implicitly selecting a skill are separate operations; follow the host's rules for each.

package/skills/hr-writing-for-agents/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: hr-writing-for-agents
+description: "How to write any document an agent reads: skills, AGENTS.md, CLAUDE.md, rules and the docs they point to (wording, structure, triggers, pruning). Use when drafting or revising that text in any repository."
+---
+
+Reference for writing any document an agent consumes: a skill, an `AGENTS.md` / `CLAUDE.md`, a doc reached by a pointer. The packaging differs; the writing does not: the same levers make each one predictable, since the agent takes the same _process_ every run rather than producing the same output.
+
+When the document you're writing is a skill, read [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md) for frontmatter, invocation choice, testing a description or a skill's output, and router skills.
+
+## Source ownership and adaptations
+
+Choose the owning source within the selected scope. Keep portable shared guidance
+with its shared owner, host settings and personal selections with their host,
+and product commands, contracts and safeguards with their product. For mixed
+content, split only the portions the user authorized. An ownership lookup does
+not authorize edits, installation or publication.
+
+Reusable third-party guidance may be contributed upstream or published as a
+clearly identified adaptation within the selected scope. Check its licence before
+copying or adapting it. Preserve required notices and source provenance, including
+the revision when known. A vendor label identifies its source; assess permitted
+adaptations rather than excluding them by that label alone. For house-rules
+contributions, locate its checkout and follow `CONTRIBUTING.md` for notice placement.
+Put pure credit in distributed notices; retain instruction references that help
+the task. Standalone bundles must carry their required notices.
+
+## Context pointers
+
+Use local files for operational pointers to available guidance. In a skill,
+bundle the target or name its path from a located checkout; source-relative
+paths outside the installed skill can break. The local-reference check is
+`guidance-links.mjs` in the located house-rules checkout. Its README describes
+the gate, repository mappings and justified remote-reference annotations.
+
+A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `AGENTS.md` naming a doc is the same object. The pointer's _wording_, not its target, decides when the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.
+
+A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
+
+- **Front-load the leading word**: the pointer is where it does its triggering work.
+- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice; collapse them and keep only distinct branches.
+- **Cut identity the body already carries.**
+
+## The two loads
+
+Every document and pointer you add spends one of two budgets:
+
+- **Context load** is the cost of always-loaded material on the agent's window: an `AGENTS.md` line, a skill description, anything sitting in context every turn, spending tokens and attention whether or not it fires.
+- **Cognitive load** is the cost on the human: which documents exist and when to reach for each. The human is the index. Not a cost to minimise: it is the price of human agency; spend it where human judgement matters, remove it where it does not.
+
+Material reached only through a pointer escapes context load at the price of the pointer's own line; material with no pointer at all rides entirely on cognitive load.
+
+## Information hierarchy
+
+A document is built from two content types: **steps** (the ordered actions the agent performs) and **reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps (a recipe), all reference (a review's rules, this skill), or both. The core decision is where each piece sits on the **information hierarchy**, a ladder ranked by how immediately the agent needs the material:
+
+1. **In-file step** is the primary tier: what the agent does, in order.
+2. **In-file reference** is consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung), which is a fine arrangement, not a smell.
+3. **Disclosed reference** is pushed out into a separate file, reached by a context pointer, loaded only when the pointer fires. Spans a sibling file in the same folder through fully external reference that lives anywhere and any document can point at.
+
+Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.
+
+**Progressive disclosure** is the move down the ladder (out of the main file and behind a pointer) so the top stays legible. Not primarily a token optimisation: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches reach. When a document has steps, in-file reference that should be disclosed buries them and turns attending to them into a coin-flip: a variance lever, not just a legibility one.
+
+**Co-location** is the within-file companion: where the ladder decides _how far down_ a piece sits, co-location decides _what sits beside it_ once there. Keep a concept's definition, rules, and caveats under one heading rather than scattered, so reading one part brings its neighbours with it. The test: the document should read like documentation written for the agent. Grouped material reads that way; scattered material does not. (Distinct from duplication: that repeats one meaning in two places; scattering fragments one meaning across many.)
+
+**Sprawl** is the failure mode here: a document simply too long, even when every line is live and unique. Attention thins across the excess, and every extra line is one more to keep relevant. The cure is the ladder: disclose reference behind pointers, and split by branch or sequence so each path carries only what it needs.
+
+## Steps and completion criteria
+
+Every step ends on a **completion criterion**, the condition that tells the agent the work is done. Two properties make it a lever:
+
+- **Clarity**: can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: ending the step before it is genuinely done, attention slipping to _being done_. The visible steps still ahead (the **post-completion steps**) supply the pull; the criterion's clarity is the resistance. Defend in order: **sharpen the bound first** (local and cheap); only if it is irreducibly fuzzy _and_ you observe the rush, hide the later steps by splitting the sequence. Hiding only works across a real context boundary (a hand-off or a subagent dispatch; an inline call leaves the later steps in context and clears nothing).
+- **Demand**: how much it requires. "Every modified model accounted for" forces thorough work where "produce a change list" does not. Demand drives **legwork** (the digging the agent does within the work, latent in the wording rather than written as its own step), and it is not step-bound: "every rule applied" binds a body of flat reference just as "every step done" binds a sequence, which is how an all-reference document still carries an exhaustiveness bar.
+
+The strongest criteria are both checkable and exhaustive.
+
+## When to split
+
+Splitting one document into two spends one of the two loads, so split only when the cut earns it:
+
+- **By sequence**: split a run of steps where the post-completion steps tempt the agent to rush the one in front of it. Keeping them out of view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's later steps to what follows, inviting premature completion.
+- **By invocation**, skill-specific: see [`SKILL-MECHANICS.md`](SKILL-MECHANICS.md).
+
+## Leading words
+
+Reuse established domain terms when their meaning is clear to the intended reader. Keep explicit criteria where a shorter label would hide a constraint. Do not invent shorthand merely to reduce token count. Judge wording by whether it produces the intended behavior, not by its intensity.
+
+State the desired behavior clearly. Retain explicit prohibitions when they define a real boundary, and pair them with the permitted behavior when that helps the reader act.
+
+Choose the instruction's form from the failure it fixes:
+
+| Observed failure                             | Form that fixes it                                | Form that backfires                                      |
+| -------------------------------------------- | ------------------------------------------------- | -------------------------------------------------------- |
+| Knows the rule, skips it under pressure      | An explicit prohibition that names the workaround | Soft guidance ("prefer", "consider")                     |
+| Complies, but the output has the wrong shape | A recipe: the output's parts, in order            | A list of "don't" items, which the agent negotiates with |
+| Leaves out a required element                | A required slot in the template it fills in       | A prose reminder near the template                       |
+| Behavior depends on a condition              | A conditional on something the agent can observe  | An unconditional rule with exemption clauses             |
+
+Exemption and nuance clauses leak: "don't X unless it matters" reopens the decision, and "this limit doesn't apply to code blocks" still suppresses code blocks. Express a real exception as its own conditional, or restructure so the rule cannot reach the exempt part.
+
+## Pruning
+
+- Keep each meaning in a **single source of truth**: one authoritative place, so changing the behaviour is a one-place edit. **Duplication** (the same meaning in more than one place) costs maintenance and tokens, and inflates a meaning's prominence on the ladder past its real rank.
+- The **environment** is a source of truth too (`package.json` scripts, config files, the directory layout, `--help` output), and a document that restates it is a **cache**: a copy of a lookup, earning its load only when the lookup is expensive. Cache what the agent cannot find by looking: the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the one-file, one-command lookups to the environment, where they cannot go stale.
+- A rule a **check** can enforce (a type, a lint rule, a test, a CI gate) lives in that check. An agent under pressure skips a prose rule but cannot pass a failing check. The document keeps only what the check cannot say: why the rule exists, where it deliberately does not apply, and the check's name, so an agent that trips it knows what to do instead. When you write a mechanical rule (a pattern a search could find, such as raw colour values outside the token file) and no check exists, add one in the same change, or state that the rule is unchecked.
+- Document a **component beside the component**: its build, flags, layout, measurements and troubleshooting go in its directory's README or its header comment, with at most a one-line pointer from shared guidance. A shared file is read for many tasks; component detail there taxes every reader for a lookup only one task needs, and it drifts because nobody editing the component sees it.
+- Check every line for **relevance**: does it still bear on what the document does? A line loses relevance by never bearing on the task (mere exposition, or a branch that should be disclosed) or by going stale as the behaviour or world it describes changes. Shorter documents are easier to keep relevant. Without a pruning discipline the default fate is **sediment**: stale layers that settle because adding feels safe and removing feels risky, until you must core down through them to find what is still live. Rewrite durable guidance in place; keep incident history in the repository's tracker or archive rather than appending it to operational rules. An example goes stale the same way when it records the fix you applied: have it teach the failure and the tell that exposed it, and let the agent derive the fix from the current code.
+- If an instruction adds no useful behavior, remove it. If behavior is missing, state the observable requirement or completion condition rather than adding stronger emphasis. Treat claims about wording effects as hypotheses unless supported by task evidence.

package/skills/hr-writing-for-agents/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "HR: Writing for Agents"
+  short_description: "Write documents agents consume"

package/skills/hr-writing-pr/NOTICE.md

@@ -0,0 +1,48 @@
+# Source notices
+
+This notice accompanies the hr-writing-pr bundle when copied on its own.
+
+## 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/`.
+
+Copyright (c) 2026 Antigravity User
+
+## 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
+
+Selected ideas also come from [Luke Parker's writing-pr post](https://x.com/LukeParkerDev/status/2096769160021979571).
+
+## house-rules and MIT permission notice
+
+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/skills/hr-writing-pr/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: hr-writing-pr
+description: Write or revise pull request titles and bodies from the final diff, with concrete behavior and relevant proof. Use when preparing a PR or improving its description.
+---
+
+# Writing pull requests
+
+Give a reviewer who has not seen the conversation enough context to understand the change and assess its evidence. Follow the target repository's PR template and contribution rules. This skill governs writing; existing rules govern commits, publication, and review gates.
+
+## Fix scope
+
+For fixes intended for pull requests in any repository, try the simplest
+adequate change first. Keep the diff focused and easy to review, with the fewest
+changed lines and files that solve the problem while preserving correctness,
+readability and required tests. Leave unrelated refactors and speculative
+abstractions out. When performance requires a larger change, show measurements
+explaining why the simpler approach is insufficient and what the added
+complexity achieves.
+
+## Material changes to an existing PR
+
+When an existing PR needs major or material changes, replace it with a new
+PR in any repository. Compare the proposed revision with the published PR.
+A revision is major or material if it changes the scope, fix approach or
+promised behavior.
+Corrections within that scope and approach that preserve the promised behavior
+are routine. Carry forward relevant evidence and unresolved review findings,
+and link the old and new PRs both ways. Publish and verify the replacement
+before closing the old PR as superseded. Recheck its final diff and required
+checks; prior PR review approvals and CI results do not cover the new submission.
+Routine corrections that leave the PR materially unchanged stay in place.
+
+## Read before writing
+
+Before creating a PR, apply the submission search in your loaded agent guidance's "Repository work" section.
+If that section is unavailable, locate the local house-rules checkout and read
+`rules/core.md` there. Report an unavailable local source before submitting.
+
+Inspect the actual diff against the intended target branch, the linked issue or request, and available validation results. For an existing PR, confirm its current base and head. Commit messages can provide context; the final diff determines what the PR claims.
+
+Resolve mismatches between the description and the implementation before calling the description complete. If evidence is unavailable, state the specific gap rather than inventing a result.
+
+## Title and body
+
+Write a title naming the resulting behavior or fixed failure. Use the repository's title convention when it has one. Check the title's type and scope against the diff's dominant change. A `docs:` title on a diff that adds an executable installer misfiles the squash commit. When no PR template exists, the title convention is the only template; default to Conventional Commits `type(scope):` unless the repository's recent history uses another style. Flag a mixed diff as a possible split into separate PRs (the `hr-split-to-prs` skill, where installed) instead of stretching the title to cover it.
+
+Lead the body with the concrete problem and resulting behavior. A small change may need only a paragraph and a validation sentence. Expand only where the reviewer needs more context:
+
+- **Bug fix:** trigger, previous behavior, corrected behavior, and regression proof.
+- **Feature:** observable capability, a small usage example, and supported limits.
+- **Refactor:** motivation, the structural change, and evidence that required behavior is preserved.
+
+Explain implementation details only when they clarify a decision or help assess correctness. Include compatibility, dependency, migration, or documentation implications when the diff creates them. When the change has a hard-to-reverse surface (host-level effects such as `sudo install-deps`, migrations, destructive actions), say so in one sentence; never a fixed risk section, and nothing on purely additive changes. Identify a useful review starting point for a complex change, using `path:line` anchors for load-bearing claims.
+
+Describe the final combined change. Leave out intermediate attempts, commit reshuffling, conversational history, and file inventories already visible in the diff. Write for the reviewer in plain language: no unexplained jargon, and no narrative about how the change was produced. Review panels, models consulted, harnesses, and agent process never appear in titles, bodies, or PR comments; that detail lives in plan files and session records. For routine clarifications, update the title and body. Material scope changes follow the replacement rule above.
+
+## Evidence that earns its space
+
+Report relevant checks and their actual outcomes, including material failures and unverified behavior. Name the tests or commands run and their scope; a suite-wide pass count alone is not evidence for the changed behavior. When generated files dominate the diff, give the authored line count alongside the headline number so the size does not mislead review. Distinguish newly introduced failures from established baseline failures only when a comparison supports that claim. Keep detailed logs in a linked artifact when the short result is sufficient.
+
+Use a small code example when it makes behavior concrete. For visual changes, use comparable before/after images when available. When the change replaces an existing procedure, state the prior and new procedure in one line each. For measured performance claims, follow the installed `hr-benchmarking` skill's
+"Report and decide" guidance for benefit columns, variability and claim limits.
+When that skill is unavailable, identify the baseline and candidate, workload,
+repetitions and variability, and show before/after metrics with percent or times
+benefit. Keep material limitations beside the results.
+
+For reproduction examples, apply the direct-command and material-condition
+guidance in the installed `hr-diagnosing-bugs` skill's `references/reporting.md`.
+When that skill is unavailable, show commands that reproduce the symptom and
+omit incidental scheduling, resource-control and observer wrappers. Keep exact
+executed commands and material conditions in the measurement record. Disclose
+material conditions beside performance results. Retain any control required to
+reproduce the defect and explain its purpose.
+
+When the existing shape is familiar, use a focused diff of calls, components
+or files to show the change. Use a diagram when it explains relationships more
+clearly than prose. Show the whole relevant block when omitted context would
+hide ownership, order or a guard. Keep verification and uncertainty beside
+the view; brevity does not remove required evidence.
+
+Put the measured result table after the change summary and before lengthy
+verification details, within the repository's required template. Explain the
+result without repeating the table's numbers. Keep the relevant checks and
+outcomes visible; collapse long commands or supporting detail when useful.
+Required scope or approval sections stay, with only the justification and links
+the reviewer needs.
+
+For qualified measured performance changes outside the declared no-clear-change
+band, prefer a compact chart alongside the exact result table when it makes
+comparisons easier to scan. Skip charts
+that add no information, such as a single small change. Preview a proposed
+visual with the user before publishing a new visual style. Use labeled units,
+zero-based bar axes, readable contrast and meaningful precision. Show the
+workload and material limits beside it; a synthetic benchmark is not a
+production or UI speedup. Keep the table or equivalent text accessible, and
+attach PR-only graphics without committing them to the product repository.
+
+Scale structure to the change. Omit empty optional sections, placeholder text, guessed risk scores or review times, and coverage percentages that were not measured. Complete a required checklist with this PR's specifics rather than omitting it, and mark non-applicable items N/A with a reason. Preserve required template sections and mark unavailable evidence honestly.
+
+## Completion check
+
+Every factual claim must be supported by inspected code, the originating request, or observed results. The opening explains what changes and why; the remaining text helps review it. Deliver the title and body in the form requested. Apply them to a remote PR only within the user's authorized scope. When the user's rules turn attribution off, include no `Made with` or other host attribution. After `gh pr create` or `gh pr edit`, reread the published body and strip any footer a harness appended.
+
+Relevant validation stays in the description; extensive templates and review automation are outside this skill.

package/skills/hr-writing-pr/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "HR: Writing PR"