@bompus/house-rules 0.0.0-stage → 0.11.0

package/skills/hr-handoff/scripts/check-reconciliation.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+// Offline accounting check. See ../references/reconciliation.md for the input
+// format and limits. No writes, host queries, or semantic-completeness claim.
+// Exit 0: mechanically complete; 1: invalid/unreadable; 2: valid but partial.
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+const errors = [];
+const gaps = [];
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const text = (value) => typeof value === "string" && value.trim().length > 0;
+const states = ["done", "open", "deferred"];
+const key = (source, record) => JSON.stringify([source, record]);
+
+function requireText(value, label) {
+  if (!text(value)) errors.push(`${label}: expected nonempty text`);
+}
+
+function list(value, label) {
+  if (Array.isArray(value)) return value;
+  errors.push(`${label}: expected an array`);
+  return [];
+}
+
+function entries(value, label) {
+  return list(value, label).filter((entry, index) => {
+    if (object(entry)) return true;
+    errors.push(`${label}[${index}]: expected an object`);
+    return false;
+  });
+}
+
+function timestamp(value, label) {
+  if (
+    !text(value) ||
+    !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(value) ||
+    !Number.isFinite(Date.parse(value)) ||
+    new Date(value).toISOString().slice(0, 19) !== value.slice(0, 19)
+  ) {
+    errors.push(`${label}: expected a UTC ISO timestamp`);
+    return 0;
+  }
+  return Date.parse(value);
+}
+
+function unique(entries, label) {
+  const map = new Map();
+  for (const entry of entries) {
+    requireText(entry.id, `${label}.id`);
+    if (map.has(entry.id)) errors.push(`${label}: duplicate id ${entry.id}`);
+    map.set(entry.id, entry);
+  }
+  return map;
+}
+
+function check(receipt, directory) {
+  if (!object(receipt)) throw new Error("receipt: expected an object");
+  if (receipt.version !== 1) errors.push("version: expected 1");
+  requireText(receipt.owner, "owner");
+  if (!["complete", "partial"].includes(receipt.coverage)) {
+    errors.push("coverage: expected complete or partial");
+  }
+  const sources = unique(entries(receipt.sources, "sources"), "source");
+  const items = unique(entries(receipt.items, "items"), "item");
+  const records = new Map();
+  const outcomes = new Map();
+  if (sources.size === 0) gaps.push("no source snapshots supplied");
+
+  for (const source of sources.values()) {
+    const label = `source ${source.id}`;
+    requireText(source.file, `${label}.file`);
+    requireText(source.snapshot, `${label}.snapshot`);
+    const declared = list(source.gaps, `${label}.gaps`);
+    for (const gap of declared) {
+      requireText(gap, `${label}.gaps[]`);
+      gaps.push(`${label}: ${gap}`);
+    }
+    if (source.expectedRecords === null) gaps.push(`${label}: total unknown`);
+    else if (!Number.isSafeInteger(source.expectedRecords) || source.expectedRecords < 0) {
+      errors.push(`${label}.expectedRecords: expected a nonnegative integer or null`);
+    }
+    if (!text(source.file)) continue;
+    let raw;
+    try {
+      raw = readFileSync(resolve(directory, source.file), "utf8");
+    } catch (error) {
+      if (error.code === "ENOENT" && declared.length > 0) {
+        gaps.push(`${label}: snapshot unavailable`);
+      } else errors.push(`${label}: cannot read snapshot (${error.code ?? "error"})`);
+      continue;
+    }
+    let data;
+    try {
+      data = JSON.parse(raw);
+    } catch {
+      errors.push(`${label}: invalid snapshot JSON`);
+      continue;
+    }
+    if (!object(data)) {
+      errors.push(`${label}: snapshot must be an object`);
+      continue;
+    }
+    const rows = unique(entries(data.records, `${label}.records`), `${label} record`);
+    if (Number.isSafeInteger(source.expectedRecords) && source.expectedRecords !== rows.size) {
+      gaps.push(`${label}: expected ${source.expectedRecords} records, read ${rows.size}`);
+    }
+    for (const row of rows.values()) {
+      requireText(row.text, `${label} record ${row.id}.text`);
+      records.set(key(source.id, row.id), row);
+      if (row.outcome !== undefined) {
+        if (!object(row.outcome) || !states.includes(row.outcome.state)) {
+          errors.push(`${label} record ${row.id}: invalid outcome`);
+          continue;
+        }
+        const item = row.outcome.item;
+        if (!items.has(item))
+          errors.push(`${label} record ${row.id}: unknown outcome item ${item}`);
+        const at = timestamp(row.at, `${label} record ${row.id}.at`);
+        const events = outcomes.get(item) ?? [];
+        events.push({ ...row.outcome, at, source: source.id, record: row.id });
+        outcomes.set(item, events);
+      }
+    }
+  }
+
+  const accounting = new Map();
+  for (const row of entries(receipt.accounting, "accounting")) {
+    const ref = key(row.source, row.record);
+    const label = `accounting ${row.source}/${row.record}`;
+    if (!records.has(ref)) errors.push(`${label}: unknown source record`);
+    if (accounting.has(ref)) errors.push(`${label}: duplicate accounting`);
+    const mapped = row.items === undefined ? [] : list(row.items, `${label}.items`);
+    if (mapped.length > 0 === text(row.context)) {
+      errors.push(`${label}: supply item IDs or a context-only reason`);
+    }
+    for (const item of mapped) {
+      if (!items.has(item)) errors.push(`${label}: unknown item ${item}`);
+    }
+    accounting.set(ref, mapped);
+  }
+  for (const ref of records.keys()) {
+    if (!accounting.has(ref)) errors.push(`unaccounted record ${ref}`);
+  }
+
+  function evidence(value, label, item) {
+    const refs = entries(value, `${label}.evidence`);
+    if (refs.length === 0) errors.push(`${label}: evidence required`);
+    for (const ref of refs) {
+      const id = key(ref.source, ref.record);
+      if (!records.has(id)) errors.push(`${label}: unknown evidence ${id}`);
+      if (item && !accounting.get(id)?.includes(item)) {
+        errors.push(`${label}: evidence ${id} is not mapped to this item`);
+      }
+    }
+  }
+
+  for (const item of items.values()) {
+    const label = `item ${item.id}`;
+    requireText(item.owner, `${label}.owner`);
+    requireText(item.next, `${label}.next`);
+    if (!states.includes(item.state)) errors.push(`${label}: invalid state`);
+    evidence(item.evidence, label, item.id);
+    const events = (outcomes.get(item.id) ?? []).sort((a, b) => a.at - b.at);
+    for (let i = 0; i < events.length; i++) {
+      const event = events[i];
+      if (!accounting.get(key(event.source, event.record))?.includes(item.id)) {
+        errors.push(`${label}: outcome ${event.source}/${event.record} is not mapped to this item`);
+      }
+      const previous = events[i - 1];
+      if (previous?.at === event.at && previous.state !== event.state) {
+        errors.push(`${label}: conflicting outcomes at the same time`);
+      }
+      if (previous?.state === "done" && event.state !== "done" && event.reopens !== true) {
+        errors.push(`${label}: reopening needs a declared later request or contradictory evidence`);
+      }
+    }
+    const latest = events.at(-1);
+    if (latest && latest.state !== item.state) {
+      errors.push(`${label}: state ${item.state} contradicts latest outcome ${latest.state}`);
+    }
+    if (
+      latest &&
+      !item.evidence?.some?.((ref) => ref.source === latest.source && ref.record === latest.record)
+    ) {
+      errors.push(`${label}: latest outcome must be included in its evidence`);
+    }
+  }
+
+  const git = receipt.git;
+  if (!object(git)) errors.push("git: explicit inventory required, including when empty");
+  else {
+    requireText(git.scope, "git.scope");
+    timestamp(git.checkedAt, "git.checkedAt");
+    evidence(git.evidence, "git");
+    const seen = new Set();
+    for (const group of ["ownedPrs", "dependencyPrs"]) {
+      for (const [index, pr] of list(git[group], `git.${group}`).entries()) {
+        const label = `git.${group}[${index}]`;
+        if (!object(pr)) {
+          errors.push(`${label}: expected an object`);
+          continue;
+        }
+        let url;
+        try {
+          url = new URL(pr.url);
+        } catch {
+          errors.push(`${label}: invalid URL`);
+        }
+        if (url && (url.protocol !== "https:" || url.username || url.password)) {
+          errors.push(`${label}: expected an HTTPS URL without credentials`);
+        }
+        if (seen.has(pr.url)) errors.push(`${label}: duplicate PR across inventories`);
+        seen.add(pr.url);
+        requireText(pr.owner, `${label}.owner`);
+        if (group === "ownedPrs" && pr.owner !== receipt.owner) {
+          errors.push(`${label}: owner differs from receipt owner; record dependencies separately`);
+        }
+        if (group === "dependencyPrs" && pr.owner === receipt.owner) {
+          errors.push(`${label}: self-owned PR belongs in ownedPrs`);
+        }
+        if (!["open", "closed", "merged"].includes(pr.state))
+          errors.push(`${label}: invalid state`);
+        timestamp(pr.checkedAt, `${label}.checkedAt`);
+        requireText(pr.next, `${label}.next`);
+        evidence(pr.evidence, label);
+      }
+    }
+    for (const [index, commit] of list(git.commitsWithoutPr, "git.commitsWithoutPr").entries()) {
+      const label = `git.commitsWithoutPr[${index}]`;
+      if (!object(commit)) {
+        errors.push(`${label}: expected an object`);
+        continue;
+      }
+      for (const field of ["repo", "branch", "sha", "next"])
+        requireText(commit[field], `${label}.${field}`);
+      if (typeof commit.sha !== "string" || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i.test(commit.sha)) {
+        errors.push(`${label}: expected a full Git object ID`);
+      }
+      if (commit.owner !== receipt.owner) errors.push(`${label}: owner differs from receipt owner`);
+      evidence(commit.evidence, label);
+    }
+  }
+  if (receipt.coverage === "complete" && gaps.length > 0) {
+    errors.push("complete coverage claimed despite source gaps");
+  }
+  if (receipt.coverage === "partial" && gaps.length === 0)
+    gaps.push("receipt declares partial coverage");
+  return { sources: sources.size, records: records.size, items: items.size };
+}
+
+let counts = { sources: 0, records: 0, items: 0 };
+try {
+  if (process.argv.length !== 3) throw new Error("usage: check-reconciliation.mjs <receipt.json>");
+  const file = resolve(process.argv[2]);
+  counts = check(JSON.parse(readFileSync(file, "utf8")), dirname(file));
+} catch (error) {
+  // Avoid printing an input excerpt from JSON.parse or filesystem paths.
+  errors.push(
+    error instanceof SyntaxError
+      ? "receipt: invalid JSON"
+      : error.code
+        ? `receipt: ${error.code}`
+        : error.message,
+  );
+}
+const partial = gaps.length > 0;
+const status = errors.length > 0 ? "invalid" : partial ? "partial" : "complete";
+console.log(
+  JSON.stringify(
+    {
+      status,
+      ...counts,
+      errors,
+      gaps,
+      limits:
+        "Checks supplied accounting and declared outcomes only. Does not prove semantic completeness, export completeness, live PR state, or landing authorization.",
+    },
+    null,
+    2,
+  ),
+);
+process.exitCode = errors.length > 0 ? 1 : partial ? 2 : 0;

package/skills/hr-house-rules-setup/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: hr-house-rules-setup
+description: "Set up or change house rules for this user: pick opt-in modifiers, create the personal layer, compose the rules file and connect it to each agent host. Use when the user asks to install, configure or change their house rules or modifiers."
+disable-model-invocation: true
+---
+
+# House rules setup
+
+The user's choices live in a personal layer, by default
+`~/.config/house-rules/`: `house-rules.json`, plus optional `rules/` and
+`skills/` directories. Composition never edits host files; connecting a host
+is a separate step the user approves.
+
+The commands below use `node`. If only Bun is installed, replace `node` with
+`bun` in every `compose.mjs` command.
+
+For a user working directly in a terminal, use `node compose.mjs setup` for
+numbered selection, review and explicit save. Read `docs/configuration.md`
+for commands and safeguards. Saving completes only configuration selection;
+composition and approved host connection remain separate steps below.
+For an agent running without a terminal, use the preview/apply workflow below.
+
+1. Find the house-rules checkout (the directory holding `compose.mjs`;
+   `install.sh` puts it in `${XDG_DATA_HOME:-~/.local/share}/house-rules`,
+   `install.ps1` in `%LOCALAPPDATA%\house-rules`).
+   When there is none, ask the user where to clone it.
+   Done when the checkout and the user's config path are known.
+2. Inspect `node compose.mjs config status --config <path>`.
+   If status reports legacy skill names, stop inspection. Read the config and follow
+   `docs/skill-names.md` before continuing. If catalog or status reports
+   `unknown modifier` or `question-cards requires coded-offers`, read the config
+   for current choices. Follow `docs/configuration.md` and preview the user's
+   selection in step 3
+   with `--disable-modifier <name>` or `--questions`.
+   For any other status failure, show the error and preserve the existing file
+   or filesystem object. Show skill choices from the README's Skills table and
+   known personal skill directories. Stop before `config set`, composition or
+   host writes. Ask the user how to repair the configuration or select a usable
+   path. For `config must be a regular file, not a symlink or directory`, ask
+   them to select or create a regular config file. Resume this step after the
+   agreed repair or selected path passes `config validate`.
+   Preserve existing selections. Fresh installers use the sample config's small
+   skill set with no modifiers. When initializing a missing config manually,
+   show `examples/person/house-rules.json` and get the user's selection before
+   creating it; the CLI treats a missing config as the legacy full skill set.
+   Explain the current selection briefly. Ask about additions only when the
+   user's stated workflow needs them, or they ask to customize it. Use
+   `config catalog` to find those choices; show the full catalog only on request.
+   Personal skills override shipped ones. Keep independent names, layers,
+   unrelated settings and exclusions.
+
+   If the user wants Swarmail, offer its modifier. When its MCP tools are absent,
+   point to https://github.com/bompus/swarmail and ask before installing it.
+   If they want different question presentation, offer plain text, coded text,
+   or coded text with cards using `--questions plain|coded|cards`. Cards still
+   require a complete text offer. Explain that host, provider and model behavior
+   varies; card availability and presentation are unverified until checked.
+   Both text-only choices prohibit card tools. If personal rules still request
+   cards, resolve that conflict before changing those rules or composing.
+   Done when the user selects relevant changes or keeps the current setup.
+
+3. Use `node compose.mjs config set --config <path>` with the selected
+   modifier and skill toggles or question preset. It previews
+   without saving. Read every change and personal rule override; resolve any
+   conflict before writing. Repeat those flags with `--apply --expect <revision>`
+   using the preview's revision. Done when it exits 0 and status confirms the
+   selection. A stale revision requires a fresh preview, not a blind retry.
+   The CLI preserves layers, custom settings and unrelated exclusions; it
+   does not edit personal rule prose or connect hosts. Read
+   `docs/configuration.md` for flags, write safeguards and lock recovery.
+   Create `rules/` and `skills/` beside the config when the user needs them.
+   Explain the file format once. A rules file starts with frontmatter naming
+   `replaces:`, `after:`, `before:` or `removes:` and a core heading, then its
+   own `## ` heading; without frontmatter it is appended at the end. A skill in
+   the personal `skills/` replaces the house-rules skill of the same name.
+4. Run `node compose.mjs --config <path> --out <personal dir>/rules.md`. Done
+   when it exits 0; on an error, show it and fix the named file.
+5. Ask which hosts the user runs, then show what connecting each one changes
+   and ask before writing:
+   - Claude Code: add `@<personal dir>/rules.md` on its own line in
+     `~/.claude/CLAUDE.md`.
+   - Hosts without file includes (for example a global `AGENTS.md`): copy the
+     composed file there between `<!-- house-rules:start -->` and
+     `<!-- house-rules:end -->` lines, replacing only that block on later runs.
+     Place the `house-rules-references/` directory beside that file, because
+     the written rules link to it.
+   - Hosts with a settings screen for user rules: paste the stdout output of
+     `node compose.mjs --config <path>`, which keeps the procedures inline.
+     Keep everything else in those files. Done when every chosen host is
+     connected or the user declined it.
+6. For skills, compose them with `--skills-out <dir>` into a directory that
+   does not exist yet or is empty; when the previous run's directory is in the
+   way, ask before removing it. Then point or copy each host's skills
+   directory at it, again with approval.
+7. When the user asks to evaluate reply behavior, use `evals/end-of-reply/run.mjs`
+   against their selected models.
+
+For a repository, suggest the pointer pattern in `examples/project/AGENTS.md`:
+point at § End of every reply and § Offers instead of restating them, and add
+only what the project changes.

package/skills/hr-house-rules-setup/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: House Rules Setup"
+  short_description: "Choose modifiers, create your layer, connect hosts"
+policy:
+  allow_implicit_invocation: false

package/skills/hr-issue-tracker-setup/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: hr-issue-tracker-setup
+description: "Configure a project's issue tracker and conventions for domain terms and architecture decision records (ADRs). Use when explicitly asked to establish or change those conventions; reuse existing configuration. General agent, CI and development-environment setup are outside this workflow."
+disable-model-invocation: true
+---
+
+# Project tracker setup
+
+Make the project's tracker and domain-document conventions usable from its
+agent guidance. Configure only the conventions the user requested.
+
+## Establish what already exists
+
+Read the project's instruction root and the tracker, glossary and ADR guidance
+it names. Follow existing links before searching for another system. Identify
+which tracker owns tasks, where its records live, and how domain terms and
+decisions are recorded. A convention can be complete without a separate glossary
+or ADR directory.
+
+When the requested configuration already works, report its entry points and
+leave it alone. Other workflows do not require this setup to run first.
+
+## Resolve the missing conventions
+
+Reuse the project's tracker and document locations. Do not create a second
+tracker, replace an established one or impose glossary/ADR files by default.
+If a choice is missing, ask only for the decisions that change the requested
+configuration, such as which tracker to use or whether to record domain terms.
+Use the active host's decision format and existing user answers.
+
+Document how the chosen tracker represents tasks, child decisions, supporting
+evidence, blockers and ready work. Use its existing concepts; add fields or
+structure only when a missing distinction prevents the requested workflow.
+
+## Update and verify the owning guidance
+
+Edit the project's canonical guidance in place. Its instruction root should
+point to the tracker and detailed domain-document conventions rather than
+repeat them. Preserve project safeguards and generated loading adapters;
+use their owning generator when an adapter needs updating.
+
+Keep shared personal skills in their configured shared source and installation
+scope. Project-only skills belong with the project. This workflow does not
+install skills, configure agent accounts or set up CI and developer tooling.
+
+Run the project's applicable guidance checks and verify the documented entry
+points from the intended workspace. Report what changed, what was already
+configured and any decision or check still unresolved. Do not claim runtime
+loading from a file update alone.

package/skills/hr-issue-tracker-setup/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Issue tracker setup"
+  short_description: "Configure project tracker and domain-doc conventions"
+policy:
+  allow_implicit_invocation: false

package/skills/hr-lean-plan/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: hr-lean-plan
+description: "Draft or critique an implementation plan in the conversation, with the fewest moving parts, before implementation. Use when asked to plan, review or tighten an approach without changing files or writing code; saving a plan file or implementing the work falls outside this read-only mode."
+disable-model-invocation: true
+---
+
+# Lean plan
+
+A plan is cheap to change and code is not. This skill spends effort on the plan
+so the build has less to do. It has two modes with one bar: **write** a plan
+from a request, or **critique** a plan someone else wrote. Either way the output
+is a plan or a review of one; change no files and write no code here.
+
+The bar: every step produces an outcome someone can check, and no step survives
+that the goal does not need.
+
+## Pin the goal
+
+Before drafting steps, write down four things:
+
+- **Done means**: what is observably true when the work is finished.
+- **Out of scope**: what a reader might expect but this work will not do.
+- **Must not regress**: behavior, data, interfaces or performance that has to
+  stay as it is.
+- **The real constraint**: the one limit that shapes the plan, such as a
+  deadline, a frozen interface, a migration window or a team boundary.
+
+Read the code, docs and config that touch the goal before asking anything. Ask
+only questions whose answer would change the plan's shape; a detail you can
+choose sensibly, choose and record as an assumption.
+
+Push back on an unclear request before planning around it. Name what is
+unclear, why it blocks a good plan and what would settle it. Common causes:
+a scope verb such as "improve" or "clean up" with no measurable result;
+constraints that conflict; no named owner for the change; a solution stated
+before the problem; a load-bearing decision (schema, API, flag strategy)
+left for implementation; a term with no settled meaning in this codebase;
+several goals with no priority between them.
+
+When an answer that decides the shape is missing, stop there: return the
+questions and an outline headed **Provisional, pending answers**, with each
+open question marked where
+it would change a step.
+
+## Shrink before you sequence
+
+Look for a framing that deletes work before ordering it:
+
+- Can an existing module, table, flag or endpoint carry the new behavior? Grow
+  the code that already owns that idea rather than adding a layer, service
+  or package for one feature.
+- Does the plan need a migration, feature flag, compatibility shim or a second
+  code path running beside the first? Each one has to be built, tested and later
+  removed. Keep it only when the must-not-regress list or the real constraint
+  requires it, and say which.
+- Would a narrower done-state, agreed with the user, remove a whole phase?
+  Offer it rather than assuming it.
+- Does a step increase coupling or state in a cohesive module, or move work
+  across its boundary? Name the payoff and the behavior it could affect.
+  Route cross-cutting concerns such as auth, caching and error handling through
+  their existing owning layer. A new layer needs a reason the current one
+  cannot meet the goal.
+
+Count the moving parts the plan adds: new files, modules, services,
+dependencies, config keys, flags, migrations, background jobs and parallel
+paths. A smaller count that still meets the done-state is the better plan.
+
+## Write each step
+
+Each step carries these slots:
+
+- **Outcome**: a concrete state of the system, not an activity. "Orders API
+  returns `shipped_at`" is an outcome; "work on the orders API" is not.
+- **Owner**: the person, team, agent or module that holds it.
+- **Check**: how anyone confirms the outcome, tied to that outcome.
+- **Depends on**: earlier steps it needs, or "none".
+
+Steps such as "handle edge cases", "refactor as needed", "clean up" or "add
+tests" are defects: name the cases, the refactor or the behavior under test,
+or delete the step. For each step ask what breaks if it is removed; if nothing
+in the done-state does, remove it.
+
+Watch for conditionals. Several steps that say "if X, also do Y" mean a
+decision has not been made. Make that decision, or a short time-boxed spike
+whose result is the decision, an explicit early step, then write the later
+steps for the chosen branch only.
+
+## Order and slice
+
+- Put the riskiest unknown first, so a bad answer changes the plan while it is
+  still cheap.
+- Slice the work into pieces that can each merge on their own and leave the
+  system working. A slice that only makes sense once the next one lands is half
+  of a larger slice. Splitting the same coupling across pull requests does not
+  remove it.
+- Check whether feature-specific behavior leaks into shared runtime paths.
+  Keep unrelated callers' behavior intact and name the boundary that does so;
+  isolation does not automatically require a new service or wrapper.
+- Mark steps with no dependency between them as parallel.
+- Make each cutover atomic. When it cannot be, name the intermediate state the
+  system will sit in, how long it may stay there, and how to roll back from it.
+
+## Verify against outcomes
+
+Verification answers "is the done-state true and did nothing on the
+must-not-regress list break?" Map each done-state item to the check that proves
+it: a test of the behavior at its real boundary, a command, a query, a
+measurement or a manual observation with its expected result. "Add tests" with
+no named behavior is not verification. When a check needs a test, `hr-test-audit`
+decides whether that test is worth writing.
+
+## Plan layout
+
+Lay the plan out as:
+
+1. Goal: done means, out of scope, must not regress, real constraint.
+2. Assumptions you made and open questions, if any.
+3. The approach in two to four sentences, including what you chose not to
+   build and why.
+4. Steps, each with outcome, owner, check and dependencies.
+5. Cutover and rollback, when the system passes through an intermediate state.
+6. Moving-part count.
+
+Use a table or diagram only when it changes how someone carries out the plan,
+such as a dependency graph that shows which slices run in parallel. Prose and
+lists cover the rest.
+
+## Critiquing a plan
+
+Read the plan against the sections above, then report three things in order:
+
+1. **Blocks starting**: missing goal slots, undecided branches, steps with no
+   checkable outcome or owner, cutovers with no rollback, feature work routed
+   through shared paths with no isolation, and PR splits that leave the same
+   coupling in place and cannot merge independently.
+2. **Would make it smaller**: steps, layers, flags, migrations or parallel paths
+   that can go, each with the reason and the moving-part count before and after.
+3. **Revised outline**: the plan rewritten in the layout above, short enough to
+   compare with the original side by side.
+
+Quote the plan's own wording when pointing at a defect. When the plan is
+already lean, say so and list only what blocks starting.

package/skills/hr-lean-plan/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "HR: Lean plan"
+  short_description: "Draft or critique a lean plan without file changes"
+policy:
+  allow_implicit_invocation: false