@bompus/house-rules 0.0.0-stage → 0.11.0

package/config.mjs

@@ -0,0 +1,320 @@
+// Selection management for compose.mjs config. JSON is the only settings store.
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+const SHIPPED_SKILLS = join(dirname(fileURLToPath(import.meta.url)), "skills");
+import {
+  composeConfiguration,
+  configurationPath,
+  modifierList,
+  parseFragment,
+  skillSources,
+  splitSections,
+} from "./composition.mjs";
+import { renderConfig, renderHelp } from "./config-view.mjs";
+
+const COMMANDS = ["catalog", "status", "validate", "preview", "set"];
+const TOGGLES = ["enable-modifier", "disable-modifier", "enable-skill", "disable-skill"];
+const revisionOf = (text) =>
+  text === null ? "missing" : createHash("sha256").update(text).digest("hex");
+const object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+function stringList(value, key) {
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || !v.trim()))
+    throw new Error(`${key} must be an array of non-empty strings`);
+  if (new Set(value).size !== value.length) throw new Error(`${key} contains duplicates`);
+}
+
+function validateStructure(config) {
+  if (!object(config)) throw new Error("configuration must be a JSON object");
+  for (const key of ["modifiers", "layers"]) stringList(config[key], key);
+  if (config.skills !== undefined && !object(config.skills))
+    throw new Error("skills must be an object");
+  for (const key of ["include", "exclude", "independent"])
+    stringList(config.skills?.[key], `skills.${key}`);
+}
+
+function validateSelection(config) {
+  validateStructure(config);
+  const known = new Set(modifierList().map((m) => m.name));
+  for (const name of config.modifiers ?? []) {
+    if (!known.has(name)) throw new Error(`unknown modifier "${name}" (see config catalog)`);
+  }
+  if (config.modifiers?.includes("question-cards") && !config.modifiers.includes("coded-offers"))
+    throw new Error(
+      "question-cards requires coded-offers; use --questions cards or disable question-cards",
+    );
+}
+
+export function readConfiguration(path) {
+  // Preserve the caller's config directory: relative layers use the same base as composition.
+  path = resolve(path);
+  let text = null;
+  try {
+    if (!lstatSync(path).isFile())
+      throw new Error("config must be a regular file, not a symlink or directory");
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    if (e.code !== "ENOENT") throw e;
+  }
+  let config = {};
+  try {
+    if (text !== null) config = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch {
+    throw new Error("invalid JSON in configuration");
+  }
+  validateStructure(config);
+  return { path, text, revision: revisionOf(text), config };
+}
+
+export function selectionReport(config, path) {
+  validateSelection(config);
+  const result = composeConfiguration(config, dirname(path));
+  const allSkills = skillSources(
+    { ...config, skills: { ...config.skills, include: undefined, exclude: [] } },
+    dirname(path),
+  );
+  const selected = new Set(config.modifiers ?? []);
+  const modifiers = modifierList().map((m) => ({ ...m, enabled: selected.has(m.name) }));
+  const skills = [...allSkills].map(([name, source]) => ({
+    name,
+    source,
+    origin: source === join(SHIPPED_SKILLS, name) ? "shipped" : relative(dirname(path), source),
+    enabled: result.skills.has(name),
+    explicitOnly:
+      parseFragment(readFileSync(join(source, "SKILL.md"), "utf8"), source).meta[
+        "disable-model-invocation"
+      ] === "true",
+    description:
+      parseFragment(readFileSync(join(source, "SKILL.md"), "utf8"), source).meta.description ?? "",
+  }));
+  const unavailable = (config.skills?.exclude ?? []).filter((name) => !allSkills.has(name));
+  const rules = splitSections(result.rules).sections.map((s) => ({
+    heading: s.heading,
+    source: "core",
+  }));
+  const origins = new Map();
+  for (const f of result.fragments) {
+    for (const section of splitSections(f.body).sections) origins.set(section.heading, f.source);
+  }
+  for (const rule of rules) {
+    rule.source = origins.get(rule.heading) ?? "core";
+    rule.origin =
+      rule.source === "core" || rule.source.startsWith("modifier ")
+        ? rule.source
+        : relative(dirname(path), rule.source);
+  }
+  return {
+    modifiers,
+    skills,
+    rules,
+    unavailable,
+    layers: (config.layers ?? ["."]).map((layer) => resolve(dirname(path), layer)),
+    fragments: result.fragments.map((f) => ({ source: f.source, ...f.meta })),
+    questions: selected.has("question-cards")
+      ? "cards"
+      : selected.has("coded-offers")
+        ? "coded"
+        : "plain",
+    warnings: result.warnings,
+    composedRules: result.rules,
+    hostLoading: "unverified",
+  };
+}
+
+export function changeSelection(config, options, path) {
+  const next = structuredClone(config);
+  const modifiers = new Set(next.modifiers ?? []);
+  const excluded = new Set(next.skills?.exclude ?? []);
+  const included = next.skills?.include === undefined ? null : new Set(next.skills.include);
+  const knownModifiers = new Set(modifierList().map((m) => m.name));
+  // Use discovery even for excluded skills; preserve unrelated existing exclusions.
+  const knownSkills = new Set(
+    skillSources(
+      { ...next, skills: { ...next.skills, include: undefined, exclude: [] } },
+      dirname(path),
+    ).keys(),
+  );
+  for (const [kind, known, choices] of [
+    ["modifier", knownModifiers, modifiers],
+    ["skill", knownSkills, excluded],
+  ]) {
+    const enable = options[`enable-${kind}`] ?? [];
+    const disable = options[`disable-${kind}`] ?? [];
+    for (const name of [...enable, ...disable]) {
+      if (!known.has(name) && !(kind === "modifier" && disable.includes(name) && choices.has(name)))
+        throw new Error(`unknown ${kind} "${name}" (see config catalog)`);
+      if (enable.includes(name) && disable.includes(name))
+        throw new Error(`cannot enable and disable "${name}" together`);
+      if (
+        kind === "modifier" &&
+        options.questions !== undefined &&
+        ["coded-offers", "question-cards"].includes(name)
+      )
+        throw new Error("use --questions or explicit question modifiers, not both");
+    }
+    for (const name of enable) {
+      if (kind === "modifier") choices.add(name);
+      else {
+        choices.delete(name);
+        if (included && existsSync(join(SHIPPED_SKILLS, name, "SKILL.md"))) included.add(name);
+      }
+    }
+    for (const name of disable) {
+      if (kind === "modifier") choices.delete(name);
+      else choices.add(name);
+    }
+  }
+  if (options.questions !== undefined) {
+    if (!["plain", "coded", "cards"].includes(options.questions))
+      throw new Error("--questions must be plain, coded or cards");
+    if (options.questions === "plain") modifiers.delete("coded-offers");
+    else modifiers.add("coded-offers");
+    if (options.questions === "cards") modifiers.add("question-cards");
+    else modifiers.delete("question-cards");
+  }
+  if (JSON.stringify([...modifiers]) !== JSON.stringify(next.modifiers ?? []))
+    next.modifiers = [...modifiers];
+  if (JSON.stringify([...excluded]) !== JSON.stringify(next.skills?.exclude ?? []))
+    next.skills = { ...next.skills, exclude: [...excluded] };
+  if (included) next.skills.include = [...included];
+  selectionReport(next, path); // Composition and legacy-name errors precede every write.
+  return next;
+}
+
+// Cooperating CLI writers share an exclusive lock; expected revision guards stale previews.
+// Manual editors do not share this lock. Recheck before rename, but they can still race that rename.
+export function writeConfiguration(snapshot, next, expected) {
+  if (!expected) throw new Error("--apply requires --expect <revision> from status or a preview");
+  selectionReport(next, snapshot.path);
+  mkdirSync(dirname(snapshot.path), { recursive: true });
+  // Lock aliases of the same parent together without changing relative layer discovery.
+  const lock = `${join(realpathSync(dirname(snapshot.path)), basename(snapshot.path))}.lock`;
+  let lockFd;
+  try {
+    lockFd = openSync(lock, "wx", 0o600);
+  } catch (e) {
+    if (e.code === "EEXIST")
+      throw new Error(
+        `configuration is locked: ${lock}; inspect the owner before removing an abandoned lock`,
+      );
+    throw e;
+  }
+  const temporary = `${snapshot.path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(lockFd, JSON.stringify({ pid: process.pid }));
+    const current = readConfiguration(snapshot.path);
+    if (current.revision !== expected || current.revision !== snapshot.revision)
+      throw new Error("configuration changed since preview; read status and preview again");
+    if (current.text !== null && JSON.stringify(current.config) === JSON.stringify(next))
+      return { changed: false, revision: current.revision };
+    const text = `${JSON.stringify(next, null, 2)}\n`;
+    const fd = openSync(
+      temporary,
+      "wx",
+      current.text === null ? 0o600 : statSync(current.path).mode & 0o777,
+    );
+    try {
+      writeFileSync(fd, text);
+      fsyncSync(fd);
+    } finally {
+      closeSync(fd);
+    }
+    if (readConfiguration(snapshot.path).revision !== current.revision)
+      throw new Error("configuration changed during validation; preview again");
+    renameSync(temporary, snapshot.path);
+    return { changed: true, revision: revisionOf(text) };
+  } finally {
+    try {
+      if (existsSync(temporary)) unlinkSync(temporary);
+    } finally {
+      try {
+        closeSync(lockFd);
+      } finally {
+        unlinkSync(lock);
+      }
+    }
+  }
+}
+
+export function selectionChanges(beforeConfig, afterConfig) {
+  return [
+    { key: "modifiers", before: beforeConfig.modifiers ?? [], after: afterConfig.modifiers ?? [] },
+    {
+      key: "skills.include",
+      before: beforeConfig.skills?.include ?? [],
+      after: afterConfig.skills?.include ?? [],
+    },
+    {
+      key: "skills.exclude",
+      before: beforeConfig.skills?.exclude ?? [],
+      after: afterConfig.skills?.exclude ?? [],
+    },
+  ].filter(({ before, after }) => JSON.stringify(before) !== JSON.stringify(after));
+}
+
+export function configCommand(argv) {
+  const command = argv[0] ?? "help";
+  if (command === "help" || command === "--help") return console.log(renderHelp());
+  if (!COMMANDS.includes(command))
+    throw new Error(`unknown config command "${command}" (see config help)`);
+  const { values } = parseArgs({
+    args: argv.slice(1),
+    options: {
+      config: { type: "string" },
+      help: { type: "boolean" },
+      json: { type: "boolean" },
+      rules: { type: "boolean" },
+      questions: { type: "string" },
+      apply: { type: "boolean" },
+      expect: { type: "string" },
+      ...Object.fromEntries(TOGGLES.map((key) => [key, { type: "string", multiple: true }])),
+    },
+  });
+  if (values.help) return console.log(renderHelp());
+  const changing = Boolean(
+    values.questions !== undefined || TOGGLES.some((key) => values[key]?.length),
+  );
+  if (
+    (changing || values.apply || values.expect !== undefined) &&
+    !["set", "preview"].includes(command)
+  )
+    throw new Error("selection flags belong to config set or preview");
+  if (values.apply && command !== "set") throw new Error("--apply belongs to config set");
+  if (values.expect !== undefined && !values.apply) throw new Error("--expect requires --apply");
+  if (values.rules && values.json) throw new Error("choose --rules or --json, not both");
+  if (values.rules && command !== "preview") throw new Error("--rules belongs to config preview");
+  const snapshot = readConfiguration(configurationPath(values.config));
+  const next = changing ? changeSelection(snapshot.config, values, snapshot.path) : snapshot.config;
+  const report = selectionReport(next, snapshot.path);
+  const changes = selectionChanges(snapshot.config, next);
+  const applied = values.apply ? writeConfiguration(snapshot, next, values.expect) : null;
+  const output = {
+    command,
+    configPath: snapshot.path,
+    exists: values.apply || snapshot.text !== null,
+    revision: applied?.revision ?? snapshot.revision,
+    changes,
+    applied,
+    ...report,
+  };
+  if (values.rules) return process.stdout.write(report.composedRules);
+  if (values.json) console.log(JSON.stringify(output, null, 2));
+  else console.log(renderConfig(output));
+}

package/docs/configuration.md

@@ -0,0 +1,193 @@
+# Configure house rules
+
+Use `node compose.mjs config help` to see the commands. Bun supports the same
+interface. The CLI manages the existing `house-rules.json`; it keeps personal
+layers, independent skill names and unrelated settings.
+
+## Guided selection
+
+Run `node compose.mjs setup --config <config-path>` in a terminal. Bun supports
+the same command. The numbered flow uses ordinary line input; `--plain` selects
+the same flow. Both input and output must be terminals. Redirected input or
+output prints scripting instructions and exits 2 without saving. Use
+`setup --json` for the existing read-only `config status --json` report.
+
+Modifiers and skills have stable row numbers while searching. Use `toggle N`
+or `toggle NAME`, with several choices separated by spaces. `search TEXT`,
+`clear search`, `show selected` and `show all` change visibility only.
+`help N` shows the full description, source and invocation policy.
+Excluding a skill name excludes its personal override as well as the shipped
+copy. Exclusions without a current source remain in the configuration.
+
+Use `questions plain|coded|cards` for question preferences; these modifiers
+are handled together rather than as individual toggles. `next` moves from
+modifiers to skills, then review. `back` keeps the draft. Only `save` on review
+writes configuration. Before a save attempt, `cancel`, end of input or Ctrl-C
+leaves it unchanged.
+A new config with no selection changes is not created.
+
+Review includes personal rule origins and an equivalent `config set` command.
+The command uses POSIX quoting on Unix and PowerShell quoting on Windows.
+Personal prose can override the selected preferences; setup does not interpret
+or edit it. Existing composition errors still block saving. Unknown stored
+modifiers can be removed, and a question preset can repair its prerequisite.
+Malformed configuration, legacy skill names and invalid layers require repair
+outside setup.
+
+If another writer changes configuration before save, setup preserves the
+draft intent and refuses the stale write. Use `refresh` to compare that intent
+with the fresh configuration, then explicitly save again. It never saves a
+fresh comparison automatically. Saving preserves custom keys and their meaning;
+the writer formats JSON, so existing whitespace is not preserved.
+
+If verification fails after saving, configuration may already have changed.
+Inspect `config status` or use `refresh` before another save. Cancelling ends
+the session without undoing an earlier save attempt.
+
+Setup saves selections only. Recompose output separately, then connect the
+chosen hosts. It does not install, update, repair or remove managed output.
+
+## Browse and inspect
+
+```bash
+node compose.mjs config catalog --config <config-path>
+node compose.mjs config status --config <config-path>
+node compose.mjs config validate --config <config-path>
+```
+
+`setup` initially shows current selections. Search for relevant additions or
+use `show all` to browse the complete catalog. Review and saving do not require
+a catalog-wide decision.
+
+`catalog` shows modifiers, skills and rule sections. `status` shows enabled
+selections and effective personal sources. Both use aligned tables, with color
+in a terminal and stacked rows on narrow screens. `NO_COLOR` disables color.
+Use `--json` for structured output without terminal styling.
+
+A missing config is treated as an empty selection without creating files.
+Modifiers are opt-in. Fresh installers copy the sample config with eight skills
+and no modifiers. A missing config or an existing config without `skills.include`
+keeps the full shipped set. The default config path is the same as the composer
+uses. Pass `--config` to choose another.
+
+`skills.include` is an optional list of shipped skill names. An empty list selects
+no shipped skills; later shipped additions stay off unless listed. Unknown names,
+malformed lists and duplicates are errors. Personal layer skills still load and
+override shipped skills, even when the shipped name is absent from the list.
+`skills.exclude` takes precedence across every layer. Existing independent names,
+layers and custom settings retain their behavior. The catalog remains complete
+so you can discover additions without enabling them.
+
+Status distinguishes configured question preferences from effective rule
+sources. Personal rules can override those preferences. Neither status nor
+validation proves what a running agent has loaded.
+
+## Preview and save
+
+```bash
+node compose.mjs config set --config <config-path> \
+  --enable-modifier swarmail --disable-skill hr-read-reddit --questions coded
+```
+
+`set` previews by default. It shows the selection changes, composition summary,
+personal rule overrides and current revision. Repeat the exact command with
+`--apply --expect <revision>` to save the reviewed change. Read the new revision
+from the result before another write.
+
+Toggle flags can repeat. Enable or disable modifiers with `--enable-modifier`
+and `--disable-modifier`; skills use `--enable-skill` and `--disable-skill`.
+Enabling a skill removes its exclusion. When `skills.include` exists, enabling
+a shipped skill also adds it to that list. Enabling a personal-only skill does
+not add a shipped name. Disabling adds an exclusion, retaining the include list,
+unrelated exclusions and custom settings. Configs without an include list keep
+their existing selection behavior.
+
+| Question preset     | Enabled offer modifiers             |
+| ------------------- | ----------------------------------- |
+| `--questions plain` | Neither offer modifier              |
+| `--questions coded` | `coded-offers`                      |
+| `--questions cards` | `coded-offers` and `question-cards` |
+
+Question presets preserve other modifiers. Choose a preset or explicit offer
+modifier toggles, rather than combining both in one command. Cards still depend
+on the agent host, provider and model. Review any personal Offers override
+before saving; the CLI does not rewrite personal prose.
+
+To repair invalid modifier selections, preview changes that produce a valid
+selection. `--questions` can repair the offer dependency; `--disable-modifier`
+can remove an unknown modifier already stored in the config. Malformed config
+structure, unknown enables and unknown disables absent from the config remain
+errors.
+
+`preview` accepts the same selection flags without saving. Add `--rules` to
+print the composed rules, or `--json` for the full report. Unknown choices,
+contradictory flags, malformed config and composition errors stop the command
+before it writes configuration. Older skill names need the
+[skill name upgrade](skill-names.md) before composition.
+
+## Write safeguards
+
+Saving requires the revision reported by status or preview. A stale revision
+fails without overwriting a newer config. Cooperating CLI writers share an
+exclusive `<config-path>.lock` file; a competing writer fails immediately.
+The CLI writes a sibling temporary file, then replaces the config atomically.
+Repeated requests leave an unchanged config's bytes and modification time alone.
+A missing config is created only by explicit apply.
+
+Manual editors do not share the lock. Avoid editing the config while a CLI
+write runs. The CLI checks again before replacement, but cannot exclude a
+manual write racing that final replacement. It refuses symlink config files.
+If an interrupted writer leaves a lock, inspect its recorded process ID and
+confirm that writer has ended before removing the lock. The CLI never removes
+another writer's lock automatically.
+
+## Compose and connect
+
+Saving changes only configuration. Recompose with the existing composer or run
+the installer again. The installer retains previous composed skill directories;
+manual `--skills-out` still requires an empty or absent directory.
+
+```bash
+node compose.mjs --config <config-path> --out <rules-path> \
+  --skills-out <new-skills-directory>
+```
+
+Connecting or copying that output to agent hosts remains a separate setup
+step. Use `hr-house-rules-setup` for the guided workflow. Custom rule prose
+still belongs in layer fragments; the protected completion sections stay
+required.
+
+## Reference output
+
+`--out rules.md` writes selected procedure references to a sibling
+`house-rules-references/` directory. Keep that directory beside the rules file
+when copying it to a host. References do not depend on `skills.include` or
+`skills.exclude`. Core Landing and Reporting always contribute their references; enabled modifiers
+contribute theirs. Reporting is also bundled with `hr-what-next` for standalone
+skill use. Excluding that skill does not remove the core reference. A personal replacement suppresses the resource it replaces.
+
+The `multi-agent` modifier exports its complete agent-work procedure when enabled,
+including review follow-ups and cleanup qualification. It remains independent
+of selected skills; enabling reference output does not enable the modifier.
+
+Use `--references-out <directory>` with `--out` to choose another destination;
+links are rendered relative to the rules file. Keep both locations available.
+Stdout and ordinary composition/configuration API calls retain full inline
+procedures, so existing preview and copy-only workflows need no bundle.
+
+A hash manifest permits repeat exports and updates to previously generated
+files. Modified, missing or unrecognized files in that directory stop generation
+before output writes. Reconcile them explicitly; generation never removes old
+procedure files or unrelated files. Output directories must not overlap.
+
+Core rule frontmatter may name one `reference` or a comma-separated `references`
+list relative to `rules/core.md`. Use only one form; list paths and section headings
+must be distinct and non-empty. Each target must be a regular file within the
+source layer, with one level-2 heading matching the core section holding its
+mandatory link. Default composition expands that section;
+linked output retains its safety boundaries and reading trigger. Modifier
+references use the same validation and output inventory.
+
+For low-level `compose(coreText, fragments)`, use `loadFragments` for personal
+layers so reference paths retain their source ownership. Directly parsed shipped
+modifiers are recognized only when their label and body match the shipped file.

package/docs/npm-release.md

@@ -0,0 +1,45 @@
+# npm release setup
+
+The package name is `@bompus/house-rules`; the executable is `house-rules`.
+It has no runtime dependencies or install hooks. Installing the package does
+not install skills into an agent host. Composition writes the requested rules
+file, its `house-rules-references/` directory when the rules include reference
+procedures, and any `--skills-out` directory.
+
+Keep the `package.json` version, changelog version and `v<version>` tag
+identical.
+
+## First publication
+
+This one-time setup applies to 0.11.0, the first published version. The first publication requires an npm account that owns the `bompus` scope.
+An earlier publication of another package does not establish current login or
+scope access. Authenticate using npm's web login and complete its 2FA approval.
+Do not put credentials into the repository or workflow.
+
+On the selected release commit, run `npm run check:package -- --out <directory>`.
+Publish that verified `house-rules.tgz` with `npm publish <tarball> --access public`.
+Then configure its trusted publisher on npm for GitHub user `bompus`, repository
+`house-rules`, workflow filename `npm-publish.yml`. Enable direct `npm publish`.
+The default staged-publication permission alone does not permit this workflow.
+
+The first GitHub release workflow checks the published tarball integrity and
+skips an identical existing version. Different bytes at the same version fail
+the workflow. Subsequent versions publish automatically after trusted publisher
+setup. Do not create another release solely to test authentication.
+
+## Subsequent releases
+
+Publishing a stable GitHub release triggers `.github/workflows/npm-publish.yml`.
+It verifies that the tagged commit belongs to `main`, checks the package version
+and dated changelog entry, and checks the packed CLI and skill resources before
+publishing the same tarball. Prereleases are excluded.
+
+The workflow uses a GitHub-hosted runner and npm's OIDC trusted publishing.
+It stores no npm token. npm requires Node 22.14 or newer and npm 11.5.1 or newer;
+the workflow uses Node 26. npm automatically supplies provenance for this public
+repository and package. See the [official trusted publishing documentation](https://docs.npmjs.com/trusted-publishers/).
+
+CI runs `npm run check:package -- --bun`. It installs the actual local tarball
+into isolated scratch with lifecycle scripts disabled, exercises the CLI under
+Node and Bun, and compares composed skills and resources with the source.
+Scratch honors `HOUSE_RULES_TEST_TMP` and is removed when the check exits normally.

package/docs/skill-names.md

@@ -0,0 +1,50 @@
+# Upgrading skill names
+
+Every skill shipped by house-rules uses the `hr-` prefix. For example,
+`handoff` becomes `hr-handoff`. Rule headings, modifier names and the
+`house-rules` command stay the same. Skills from other sources keep their names.
+
+## Before updating
+
+1. In `house-rules.json`, replace each shipped skill name in `skills.exclude`
+   with its `hr-` name.
+2. For each personal override of a shipped skill, rename its directory and
+   its frontmatter `name:` to the matching `hr-` name.
+3. Update your skill invocations, rules, links and host settings to use the
+   new names.
+
+Composition refuses unresolved old exclusion names, ambiguous old personal
+folders and legacy frontmatter names in prefixed overrides before writing output. The error names the replacement. Fix the
+config or layer, then compose again. The installer keeps the previous composed
+skills until composition succeeds.
+
+A personal override named `hr-handoff` replaces the shipped `hr-handoff`.
+If your generic `handoff` is a separate skill you intend to keep alongside it,
+record that decision in your config:
+
+```json
+{
+  "skills": {
+    "independent": ["handoff"],
+    "exclude": ["hr-read-reddit"]
+  }
+}
+```
+
+`skills.independent` lets the listed personal skills keep names that match old
+house-rules names. It does not create an alias or replace the prefixed skill.
+`skills.exclude` uses the new names for shipped skills. An old name listed in
+`skills.independent` refers to the independent personal skill and can be excluded
+without excluding its prefixed counterpart. Unrelated personal
+names need no entry in `skills.independent`.
+
+## Connect hosts after composing
+
+If a host reads the whole composed directory, point it at the new composed set.
+If it has individual skill links or copied folders, replace its old house-rules
+entries with the matching prefixed entries. Preserve unrelated skills.
+Restart or reload the host and check that it discovers the new names.
+
+The composer and installer do not edit host files or remove old host entries.
+Do not keep both the old and new house-rules copies active. Historical skill
+invocations need the new names; there are no compatibility aliases.

package/examples/person/house-rules.json

@@ -0,0 +1,15 @@
+{
+  "modifiers": [],
+  "skills": {
+    "include": [
+      "hr-house-rules-setup",
+      "hr-code-review",
+      "hr-diagnosing-bugs",
+      "hr-explain-code",
+      "hr-lean-plan",
+      "hr-test-audit",
+      "hr-plain-prose",
+      "hr-what-next"
+    ]
+  }
+}

package/examples/person/rules/10-tooling.md

@@ -0,0 +1,8 @@
+---
+after: Implementation economy
+---
+
+## My tooling
+
+Use `pnpm` for JavaScript projects unless the repository already uses another
+package manager. Run the project's own lint and test scripts before committing.

package/examples/person/rules/20-reporting.md

@@ -0,0 +1,9 @@
+---
+replaces: Reporting
+---
+
+## Reporting
+
+Lead with the result in one sentence, then a short list of what changed, what
+was checked and what is left. Keep reports under 15 lines unless asked for
+detail.

package/examples/project/AGENTS.md

@@ -0,0 +1,18 @@
+# Example project
+
+## Session
+
+Before your first reply in a session, read § End of every reply and § Offers in
+your user-level house rules in full. They apply here unchanged; this file only
+adds to them and never removes the offer.
+
+## Landing
+
+This repository lands by direct push to `main` after `npm test` passes; that
+is the landing path § Landing asks the repository to name. Never force-push
+`main`.
+
+## Commands
+
+- Install: `npm ci`
+- Test: `npm test`