@bompus/house-rules 0.0.0-stage → 0.11.0

package/rules/modifiers/low-quota-handoff.md

@@ -0,0 +1,19 @@
+---
+description: When the current model's usage allowance runs low, write a handoff before work stops.
+after: Finishing work
+requires: hr-handoff
+---
+
+## Low-quota handoff
+
+Check your remaining usage allowance at session start or resume, after a model
+switch and before substantial new work, using a reading the host shows or the
+user reports. When a fresh reading shows the current session's provider and
+model with less than 5% of its daily, weekly or monthly allowance left, use the
+`hr-handoff` skill to checkpoint the work. Another model being low, context size
+and token totals do not trigger it. When no reliable reading is available, say
+once that detection is unverified; never guess a low balance or poll for one.
+
+This handoff is a stop under § End of every reply: after saving it, end the
+reply with the handoff report and its recorded next action, which serve as the
+offer, and do no further work until the user resumes it.

package/rules/modifiers/multi-agent.md

@@ -0,0 +1,34 @@
+---
+description: Work is split across delegated workers and several agent hosts; worker reports, review standards and cleanup checks account for all of them.
+after: Coordination and isolation
+reference: ../references/multi-agent.md
+---
+
+## Working with other agents
+
+Keep delegation within the user's authorization and responsibility in the current
+conversation. Before delegating work, reviewing a worker, requesting a follow-up
+review, creating a task worktree, or cleaning up a branch, directory or worktree
+manually or on a schedule, read [the agent-work procedure](../references/multi-agent.md).
+
+An incomplete worker report is a checkpoint. A worker with a background command
+or subagent still running is not done. Verify reports against evidence and use
+host durations or timestamps for elapsed time. Keep workers from delegating
+further unless asked.
+
+Give implementers the task, file boundaries, public APIs and architectural
+constraints. Put mechanically enforceable standards in tooling; reserve style
+and judgment for review. The user's direction is the judgment backstop when
+no second reviewer runs. An advisor model is not a second review.
+
+After review, fix findings and run relevant checks. A logic change permits a
+follow-up review but does not require one. Request it only for a named risk
+local checks cannot resolve. Record its scope and round limit first; further
+fixes do not reset that limit. At the limit, get the user's direction before
+another model round. Required repository checks and review gates still apply.
+
+Before cleanup, verify no installed agent host's active, idle, paused,
+disconnected or resumable session uses the path or branch. Include equivalent
+paths and child directories, and recheck immediately before deleting. Skip
+scheduled cleanup when qualification is incomplete. Leave app-managed or other
+sessions' work to their owners; follow the procedure and § Cleanup.

package/rules/modifiers/no-attribution.md

@@ -0,0 +1,10 @@
+---
+description: Commits, pull requests and comments carry no agent or tool credit lines.
+after: Writing
+---
+
+## No attribution
+
+Commits, pull requests, issues and comments carry no agent or tool credit: no
+"Generated with" lines, no `Co-Authored-By` agent trailers, no "Made with"
+footers. Where a host has a setting that turns attribution off, set it.

package/rules/modifiers/plan-files.md

@@ -0,0 +1,50 @@
+---
+description: Multi-step work keeps a visible task list mirrored to a plan file with a ledger of every item's outcome.
+after: Durable notes
+---
+
+## Task tracking
+
+For work with two or more steps, create the task list up front, keep exactly
+one item in progress and mark each item done as it finishes. When no task tool
+is available, keep the list in short progress messages and say so once.
+
+Mirror the list to a plan file: the project's plans directory when it documents
+one, otherwise `plans/<topic>/plan.md` in your notes directory (§ Durable
+notes). At session start, read the relevant plans and every `blocked-on-user`
+plan whatever its owner, so unanswered decisions stay visible; that read is not
+the sweep below. Update the plan when you update the list, add findings as they
+turn up, and use the same item states in both. At each reconciliation event in
+§ Finishing work, update both records before choosing the next action. Point at
+the plan or handoff that owns an item instead of copying it; a handoff points
+at its plan.
+
+- Head the plan with `Owner:` (session name, or `none` for a shared backlog)
+  and `Status:` (`active`, `paused`, `blocked-on-user`, `completed`); update both
+  when they change.
+- For substantial plans, state the intended outcome and the evidence that will
+  show it is done; update both when findings change the task.
+- When new work arrives mid-task, add it as pending before switching; never
+  drop an in-progress item silently.
+- Keep the whole ledger in the plan: deferred items, follow-ups and incidental
+  findings with a one-line disposition (`user-flagged`, `deferred-by`,
+  `blocked-by`, `low priority`), and closed items with their outcome (landed
+  commit, won't do and why, moved elsewhere) and start and end times. Note the
+  start time when you pick an item up.
+- When repeated attempts leave an item unresolved without new evidence, record
+  whether it is blocked, deferred or using an approach that is not working. For
+  an approach that is not working, change method within the authorized scope,
+  or propose a smaller deliverable or dropping the item; the user decides scope
+  changes and drops. Judge progress by evidence, not age or retry counts;
+  waiting on a dependency or ruling out a hypothesis does not by itself show
+  that an approach is not working.
+- Before archiving a completed plan, save its completed status, completion
+  time and evidence. Apply § Finishing work before marking the whole session
+  completed. Then move the plan to `plans/archive/<topic>-<date>/` beside it.
+
+Sweep other sessions' plans and handoffs only when the user asks, such as
+"what's waiting on me?", and only for the current project. Offer unowned items,
+`blocked-on-user` items and items whose owner has no live session in the host's
+session list or coordination roster, naming each owner. When you cannot tell
+whether an owner is live, or who owns an item, mention it as another session's
+context instead of offering it.

package/rules/modifiers/question-cards.md

@@ -0,0 +1,48 @@
+---
+description: Opt in to question cards beside complete text offers when the host supports them; availability and presentation can vary by host, provider and model.
+after: Offers
+---
+
+## Question cards
+
+This modifier opts in to cards beside text. Availability, invocation and
+presentation can vary by host, provider and model: a card may be unavailable,
+skipped or shown unexpectedly. Keep the complete text offer usable on its
+own; do not promise identical behavior across sessions. If the user chooses
+text only, disable this modifier and do not call question-card tools, even
+when they are exposed.
+
+Asking the user to choose between options is an offer, even when the user
+asked you to ask them, so it gets the full text offer on every host.
+
+When your host gives you a multiple-choice question tool (one that shows the
+user a question with selectable options), send every offer as a question card
+as well as text, unless the choice depends on content only the text carries:
+images, tables, code, links, or a comparison longer than a card option holds.
+Some hosts show the card before the text written ahead of it, so the user
+would answer without that content. Send those offers as text alone.
+
+1. Write the complete text offer first, with every part § Offers lists. A
+   one-line question, a line saying you will ask, or no text at all is not a
+   text offer. The card never replaces it, because some hosts cannot display
+   cards and some drop short text sent beside one.
+2. In the same reply, right after the text offer, call the tool. Do not end
+   the reply between the two.
+3. Ask one card question per offer question, in the same order. Give each
+   option the label it has in the text offer, code included when the offer
+   uses codes, with "(Recommended)" where the text offer has it: for example
+   `1A (Recommended) pylon` under coded offers, not `pylon`. Write each
+   option's description so it stands alone, saying what the option does and
+   what it costs or risks: on some hosts the card is all the user sees before
+   answering. Use multi-select when the options combine. Leave out an "Other"
+   option; hosts add their own free-text choice.
+4. Treat the card's answer as a typed reply naming the same options. On some
+   hosts the answer arrives as a new turn; it still answers the offer.
+
+When no such tool is available, send the text offer alone. Do not search for
+a substitute or call another tool in its place.
+
+When you answer a card that a delegated agent raised, key each answer by the
+question id in the request, because hosts use different ids. Then read the
+agent's result again: some hosts report the task finished while its card
+waits and deliver the real result only after the answer.

package/rules/modifiers/release-batching.md

@@ -0,0 +1,13 @@
+---
+description: Batch approved, compatible changes for releases and audit factual claims before releases or public announcements.
+after: Landing
+reference: ../references/release-batching.md
+---
+
+## Release batching
+
+Landing does not authorize publishing. Follow the repository's release requirements.
+Before preparing or publishing a release or public announcement, read
+[the release procedure](../references/release-batching.md), including its factual
+accuracy audit. Do not publish with unresolved accuracy blockers or expand scope
+to new benchmarks.

package/rules/modifiers/scratch-on-disk.md

@@ -0,0 +1,15 @@
+---
+description: Task scratch lives on disk under the user data directory, never in RAM-backed /tmp.
+after: Durable notes
+---
+
+## Scratch files
+
+Keep task scratch on disk-backed storage, under `tmp/<topic>/` in your notes
+directory (§ Durable notes), even when a tool or harness defaults to `/tmp` or
+to a temp path it pre-approves. On many Linux systems
+`/tmp` is RAM-backed, so large files there compete with running programs for
+memory. Files that can approach 1 GB (databases, traces, downloads, extracted
+archives) never go there, whatever a tool's default says. Write in-progress
+receipts straight to their final location, and delete scratch when the task
+ends.

package/rules/modifiers/shared-host-load.md

@@ -0,0 +1,48 @@
+---
+description: Coordinate shared local work within host-defined resource budgets; isolate measurements and release reservations during remote waits.
+after: Coordination and isolation
+---
+
+## Shared machine load
+
+When local work shares a host, follow its declared CPU, memory and I/O budgets
+and admission procedure. Before resource-intensive builds, tests or tools,
+check current load and running jobs. Choose concurrency and memory controls
+within that budget, accounting for interactive use of the machine.
+
+Classify each local phase and its actual commands, hooks and children. A phase
+is resource-intensive when its expected CPU, memory or I/O demand exceeds the
+host's concurrent-work budget.
+
+Before calling demand unknown, inspect the command, its applicable hooks,
+wrappers and children. When inspection establishes bounded demand within existing
+host limits and the active measurement's light-work allowance, proceed without
+fresh benchmark-owner permission, a collector or a measurement receipt.
+Inspection is sufficient qualification; missing resource samples alone is not
+a blocker. Use the host's admission procedure when inspection cannot establish
+that the complete invocation fits the host's budget and any active measurement's
+light-work allowance. Admit the complete invocation when its children
+need admission, and retain required hooks. This resource permission does not
+lift checkout ownership, shared-write serialization, named input freezes or
+explicit operation-specific user restrictions. A retained benchmark lock alone
+does not suspend permitted light work.
+
+Without a budget or qualification procedure, get
+operator direction before launching parallel local workers or commands that
+build, test, index or process an entire repository or dataset. Bounded reads
+and edits may continue. Coordinate competing phases without blocking whole
+sessions.
+
+Use an exclusive slot when the host policy requires one or a local performance
+measurement needs isolation. Remote inference, light CLI/API work and remote
+waits need no exclusive slot. A memory cap, an agent/model comparison or
+recording elapsed time alone does not make a phase heavy. Record timing
+conditions and concurrent local work for shared or remote evaluations.
+
+Other sessions may continue light reads, edits and remote requests within the
+reservation's budget. Preserve measured files, runtimes, dependencies and
+services. During isolated local performance measurements, the measuring session
+only monitors. Release reservations while waiting on remote work or review.
+
+Constrain work that risks exhausting memory using the host's supported controls.
+Check host evidence of memory pressure before retrying with a larger budget.

package/rules/modifiers/solo-operator.md

@@ -0,0 +1,13 @@
+---
+description: For repositories with one maintainer, the user's direction is the review; no review-gated steps.
+after: Landing
+---
+
+## Solo operator
+
+The user's repositories have no second reviewer: the user's explicit direction
+is the review. Never offer "await review", "open a pull request for review" or
+any other review-gated next step. Land each task through a pull request, so
+the pull request records why the default branch moved; skip it only for
+trivially mechanical changes, or when the user, directly or in the
+repository's own guidance, directs a direct push.

package/rules/modifiers/squash-landing.md

@@ -0,0 +1,22 @@
+---
+description: Pull requests land by squash merge after review-bot findings are handled, and the session's checkout moves off the landed branch.
+after: Landing
+reference: ../references/squash-landing.md
+---
+
+## Squash landing
+
+Prefer squash merges unless the repository requires another strategy or the user
+picks one. Before integration, handling review feedback, or moving off a landed
+branch, read [the squash procedure](../references/squash-landing.md).
+When a review bot reviews pull requests, merge only after it finishes; fix or
+answer all findings, resolve threads, and read the full review body.
+
+During integration, never switch, reset, force-move or remove the session's
+checkout. Default-branch updates must meet the fast-forward and ownership
+conditions in § Landing. After the merge, fetch first; move off a landed branch
+only when its content is in the base and the tree is clean. When the base is
+checked out elsewhere, detach at the fetched base. Never merge, reset or stash
+to move the checkout. Leave app-managed checkouts for the app to retire.
+If the tree is dirty or ownership is uncertain, stand down and record its owner.
+Update the task record and follow § Cleanup after each landing.

package/rules/modifiers/swarmail.md

@@ -0,0 +1,12 @@
+---
+description: Locate Swarmail-owned instructions and tool contracts for local session coordination.
+after: Coordination and isolation
+---
+
+## Swarmail coordination
+
+When Swarmail is connected, read its server instructions and tool contracts
+before using it. If those instructions are unavailable or omit a needed detail,
+read `swarmail --help` and `README.md` in its owning checkout at the installed
+or host-approved revision. If available sources do not establish that detail,
+report it as unverified rather than guessing the product's operations.

package/rules/references/github-actions.md

@@ -0,0 +1,45 @@
+## GitHub Actions
+
+Inspect the current workflows, run logs and effective repository policies before
+changing CI. Distinguish runner startup or action-policy failures from test
+failures, timeouts and missing credentials. Preserve checks and assertions;
+qualify timeout changes with the actual failing operation and comparable runs.
+Give jobs finite timeouts. Cancel an older pull-request run only when a newer
+run for the same pull request covers the same required checks; preserve required
+default-branch and release evidence.
+
+### Choose the concurrency boundary
+
+Independent jobs can run on separate runners. A job's steps normally run in
+sequence, but GitHub also supports native parallel steps. Confirm current
+[workflow syntax](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsparallel)
+before using it; older model knowledge may omit this capability.
+
+- A `parallel` group starts its steps together and waits for the group.
+- `background: true` starts a step without waiting. Use its `id` with `wait` or
+  `cancel`, or use `wait-all` to wait for every active background step, as the
+  dependency and failure policy requires.
+- Parallel steps share a runner, workspace and resource budget. Inspect writes,
+  caches, outputs and prerequisites before overlapping commands. Install shared
+  dependencies first. Do not infer a speedup without measurements.
+- Workflow `concurrency` controls overlapping runs; it does not parallelize steps.
+
+Keep failure propagation and required evidence intact. More parallelism can
+increase contention or duplicate work. Prefer the smallest independent group
+that addresses a measured or operational need.
+
+### Forks and notifications
+
+Establish whether a fork is maintained independently or only hosts contributions
+upstream. Honor that purpose before enabling workflows, publishing or changing
+automation settings. Inspect repository Actions permissions separately from
+workflow triggers and notification subscriptions.
+
+Disabling repository Actions stops ordinary workflows, but enabled Dependabot
+can still run on Actions. Check dependency-update automation separately when
+investigating continuing runs. Keep security alerts and notification preferences
+distinct from update automation; do not silence unrelated failures.
+
+Sources: [parallel-step announcement](https://github.blog/changelog/2026-06-25-actions-steps-can-now-be-run-in-parallel/),
+[Actions settings](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository),
+[Dependabot on Actions](https://docs.github.com/en/code-security/concepts/supply-chain-security/dependabot-on-actions).

package/rules/references/landing.md

@@ -0,0 +1,39 @@
+## Landing
+
+A branch or worktree is an intermediate step. Land a change (merge or push it
+into the remote default branch) only when the user has directed it, for this
+task or as a standing rule in their rules or the repository's guidance. Until
+then, a task finishes committed on its branch with landing offered. Choosing an
+offer option that includes landing, or replying with the accept line when the
+recommended option includes it, is that direction.
+
+At task completion, unlanded commits or uncommitted task changes get one landing
+option, never a bare done or a commit alone; only an explicit user deferral leaves
+them out, recorded with the branch, the commits and the reason. Write it as
+`Land PR #<n>` or `Commit and land <change>`. Landing is the whole sequence in
+this section and § Cleanup; do not list its steps in the option. Name only
+what departs from that sequence, such as a direct merge or a step held for the
+user. Choosing the option authorizes the whole landing, merge included. Land through the path the
+repository requires (pull request or direct push), and never bypass required
+checks. Landing is done when a fresh fetch shows the default branch contains
+the change.
+
+After integration:
+
+- Fetch, then bring the local default branch current. When it is clean,
+  strictly behind and not checked out elsewhere, fast-forward it. When another
+  worktree has it checked out and you know no session or running job is using
+  that worktree (your own main checkout, for example), run `git pull --ff-only`
+  there; unrelated uncommitted files may stay. When you cannot tell, treat it
+  as in use. Confirm the local and fetched remote heads match.
+- If the default branch is diverged, on another branch, in use, or the pull
+  refuses because local edits would be overwritten, leave it and report its
+  path and the blocker. Never merge, reset, stash or switch branches to make it
+  match, and never update other sessions' worktrees or separate clones.
+- Delete the merged remote branch when it is this task's own branch
+  (`git push origin --delete <branch>` when the merge did not); § Cleanup
+  covers branches others may rely on. Before merging a pull request that another open pull
+  request targets, retarget that one to the default branch first.
+- When the change landed by squash, verify the pull request's recorded squash
+  commit is in the fetched default branch and the intended changes landed; the
+  original feature commits need not be ancestors.

package/rules/references/multi-agent.md

@@ -0,0 +1,47 @@
+## Working with other agents
+
+A worker's report that leaves items open without naming a blocker is a
+checkpoint, not completion: send it back naming them, and after two or three
+continuations review the work yourself. A worker with a background command or
+subagent still running is not done. Take its elapsed time from the host's
+durations or timestamps, not from its report. When wall-clock time matters,
+give a budget and restate the elapsed time in each follow-up, or say that an
+earlier correct result beats a later one; budgets are advisory, hard timeouts
+are not. Reuse workers for related follow-ups, do independent work while they
+run instead of polling, and keep workers from delegating further unless asked.
+
+Split standards by where they are enforced. Give implementers the task, file
+boundaries, public APIs and load-bearing architectural constraints, even ones
+no tool can check. Keep style and judgment calls for the review pass, where the
+reviewer reads the applicable guidance itself; a convention that does not fit
+one line with a yes/no test is taste and reviewer-only. What a formatter,
+linter, type check or automated gate can enforce belongs in tooling for both,
+never in prose for either. When no second reviewer runs, the user's direction
+is the only judgment backstop; say so instead of assuming review happened.
+Asking an advisor model is not a second review.
+
+After a model review, fix its findings and run the relevant checks. A fix
+that changes code logic permits a follow-up review; it does not require one.
+Code logic includes control flow, data handling, interfaces, queries and values
+a program reads. Request a follow-up only for a named remaining risk that
+local checks cannot resolve. Batch known fixes first, then focus the review on
+changed logic and unresolved findings. Never restart a whole-change review
+solely because a fix changed logic.
+
+Before a follow-up, record its scope and round limit in the plan. A further
+logic fix does not reset that limit. When the limit is reached, report any
+remaining blocker and get the user's direction before another model round.
+Fixes that touch only docs, comments, changelog text or tests ship on local
+checks. The pull request body names the findings fixed and says when no
+further round ran. Required repository checks and review gates still apply.
+
+Before cleaning up a branch, directory or worktree by hand or on a schedule,
+check that no session of any installed agent host uses it: session records and
+workspace or branch associations as well as processes, including idle, paused,
+disconnected and resumable sessions. Resolve equivalent paths and check
+sessions in child directories before removing a parent. Recheck right before
+deleting; scheduled cleanup skips what it could not verify. When you finish,
+offer an app-managed session's branch to its owner for deletion, unless the
+session is still on it. Before creating a task worktree, check the
+repository's worktree list and report unexplained leftovers; `git worktree
+prune --dry-run` shows stale registrations.

package/rules/references/release-batching.md

@@ -0,0 +1,43 @@
+## Release batching
+
+When preparing or publishing a release, follow the repository's versioning,
+changelog, release-channel, authorization and verification requirements.
+Where those requirements allow it, batch compatible changes instead of
+publishing a release for every landed change. Landing and publishing are
+separate actions; authorization for one does not authorize the other.
+
+Record completed changes in the repository's pending-release record using its
+existing convention or automation. Keep unfinished work in the task plan.
+Before publishing, review approved backlog work and open pull requests with
+their owners. Include compatible changes that are ready or intended for the
+next release. Record the included changes, unfinished items and release cutoff
+or readiness condition in the task plan. Backlog items do not authorize
+implementation or landing. Do not hold a ready batch for unrelated, unapproved
+or indefinite work.
+
+Before any release or public announcement, audit the README, comparisons,
+performance metrics, relevant documentation, announcement plans and drafts,
+and release notes against the intended revision or artifact and current
+verified state. Record which materials were checked and the evidence for
+claims in the task plan. Correct, add, remove or update content to resolve
+outdated instructions, omissions, contradictions and unsupported claims.
+Distinguish released, deployed and planned behavior; give performance claims
+measurement conditions and evidence, and label unverified results. Preserve
+historical results with their tested versions instead of presenting them as
+current measurements.
+
+Recheck affected claims when the candidate or supporting evidence changes.
+Before publishing, resolve unsupported or contradictory claims by correcting,
+qualifying or removing them; record any remaining accuracy blocker. Do not
+publish material with an unresolved accuracy blocker. Use existing evidence;
+this audit does not authorize new benchmarks, probes, source changes outside
+the task, or publication. Follow the owning repository's requirements for any
+needed correction or measurement. An urgent release may narrow the audit to
+its published materials and affected claims, but must still verify them.
+
+An urgent security, regression or compatibility fix can ship without waiting
+for unfinished backlog work. Every release's notes must cover all unreleased
+changes included in its artifact, including an urgent release. Choose the
+version for the combined changes according to the repository's scheme.
+Publishing still requires its normal authorization and checks; this modifier
+adds no permission to tag, publish or change release automation.

package/rules/references/squash-landing.md

@@ -0,0 +1,44 @@
+## Squash landing
+
+Prefer squash merges for pull requests unless the repository requires another
+strategy or the user picks one. With the GitHub CLI that is
+`gh pr merge <n> --squash`; a bare `gh pr merge` can create a merge commit.
+Do not pass `--delete-branch` when other worktrees may hold the head branch;
+delete the remote branch with `git push origin --delete <branch>` instead.
+
+When you integrate a task branch locally instead of through a pull request,
+land it as standard commits, never as a "Merge branch" commit: `git merge
+--squash` then commit with a message in the repository's commit convention,
+or a fast-forward when the base has not moved. After a pull request merges,
+do not also squash the branch locally.
+
+When a review bot reviews pull requests, merge only after its check finishes
+and each finding is fixed or answered with a reason, threads resolved. Read
+the review body too: findings outside the diff arrive there, not as threads.
+
+During integration, never switch, reset or remove the session's own checkout: no
+`checkout` or `switch` to another ref, no `reset` or branch force-move, and no
+`worktree remove` on it. Updating the default branch it has checked out
+(`merge --squash`, `merge --ff-only`, or `pull --ff-only` after a remote merge)
+under the fast-forward conditions in § Landing is expected; report other paths
+to their owners.
+
+After the merge, do not leave the session's own checkout on a landed branch.
+Fetch first, then:
+
+- When the content is fully in the base (a merged pull request whose remote
+  head is deleted, or an empty content diff after a squash) and the tree is
+  clean, move the checkout onto the fetched base: `git switch <base>` once the
+  local base is current, never merge, reset or stash. When another worktree
+  has the base checked out, detach at the fetched base (`git switch --detach
+<remote>/<base>`) and create or switch to a branch before any further
+  commits.
+- When an app manages the checkout, leave it: the app retires it, and the
+  report does not mention it.
+- When the tree is dirty or ownership is in doubt, stand down: record the
+  merged commit, the checkout path and the owner wherever you track the task.
+
+After each landing, update the task list and any active handoff with the
+commit, the verification result and the remaining work, then retire the task
+worktree and branch under § Cleanup. Stop earlier only when the user asks or
+integration is blocked, and report the exact blocker.