@theagilemonkeys/facility 0.3.1

package/src/prompts.mjs

@@ -0,0 +1,64 @@
+// Interactive prompts on node:readline. Zero dependencies.
+import { createInterface } from "node:readline/promises";
+import { bold, dim } from "./ui.mjs";
+
+let rl = null;
+
+function iface() {
+  if (!rl) rl = createInterface({ input: process.stdin, output: process.stdout });
+  return rl;
+}
+
+export function closePrompts() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+/** Free-text question with a default. Empty answer returns the default. */
+export async function ask(question, defaultValue = "") {
+  const suffix = defaultValue ? ` ${dim(`(${defaultValue})`)}` : "";
+  const answer = (await questionOrEof(`  ${bold(question)}${suffix} `)).trim();
+  return answer || defaultValue;
+}
+
+/** Yes/no question. */
+export async function confirm(question, defaultYes = true) {
+  const hint = defaultYes ? "Y/n" : "y/N";
+  const answer = (await questionOrEof(`  ${bold(question)} ${dim(`[${hint}]`)} `))
+    .trim()
+    .toLowerCase();
+  if (!answer) return defaultYes;
+  return answer.startsWith("y");
+}
+
+function questionOrEof(question) {
+  const readline = iface();
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const onClose = () => {
+      if (!settled) {
+        settled = true;
+        const error = new Error("Input ended before the prompt was answered.");
+        error.code = "prompt_eof";
+        reject(error);
+      }
+    };
+    readline.once("close", onClose);
+    readline.question(question).then(
+      (answer) => {
+        if (settled) return;
+        settled = true;
+        readline.removeListener("close", onClose);
+        resolve(answer);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        readline.removeListener("close", onClose);
+        reject(error);
+      },
+    );
+  });
+}

package/src/render.mjs

@@ -0,0 +1,66 @@
+// Template rendering and managed-content insertion.
+//
+// Placeholders are {{UPPER_SNAKE}} with no spaces, so GitHub Actions
+// expressions (`${{ secrets.X }}` — spaces, lowercase, dots) never match and
+// pass through untouched.
+
+/**
+ * Substitute {{VARS}} in a template. A placeholder alone on its line is a
+ * block variable: an empty value removes the whole line, a multi-line value
+ * lands verbatim. Unknown placeholders are left as-is.
+ */
+export function render(template, vars) {
+  const withBlocks = template.replace(
+    /^[ \t]*\{\{([A-Z0-9_]+)\}\}[ \t]*\r?\n/gm,
+    (match, name) => {
+      const value = vars[name];
+      if (value === undefined) return match;
+      if (value === "") return "";
+      return value.endsWith("\n") ? value : `${value}\n`;
+    }
+  );
+  return withBlocks.replace(/\{\{([A-Z0-9_]+)\}\}/g, (match, name) => vars[name] ?? match);
+}
+
+/** True when `content` already contains the facility managed-block marker. */
+export function hasManagedBlock(content) {
+  return content.includes("<!-- facility:start");
+}
+
+/** Append a managed block to existing file content (with a blank line). */
+export function appendManagedBlock(content, block) {
+  const base = content.replace(/\s*$/, "");
+  return base ? `${base}\n\n${block}` : block;
+}
+
+const MODULES_START = "<!-- facility:modules:start -->";
+const MODULES_END = "<!-- facility:modules:end -->";
+
+/** Insert a module's standard section between the modules markers. */
+export function insertModuleSection(standard, section, moduleTitle) {
+  if (standard.includes(`(facility module)`) && standard.includes(`### ${moduleTitle} (facility module)`)) {
+    return { content: standard, inserted: false };
+  }
+  const end = standard.indexOf(MODULES_END);
+  if (end === -1) {
+    // No markers (user removed them): append under a Modules heading instead.
+    const block = `\n## Modules\n\n${section.trim()}\n`;
+    return { content: `${standard.replace(/\s*$/, "")}\n${block}`, inserted: true };
+  }
+  const before = standard.slice(0, end).replace(/[ \t]*$/, "");
+  const after = standard.slice(end);
+  return { content: `${before}${section.trim()}\n\n${after}`, inserted: true };
+}
+
+const HOOK_MARKER = "/* facility:module-rules */";
+
+/** Splice a module's hook rules at the marker in protect-files.mjs. */
+export function insertHookRules(hookSource, fragment, moduleName) {
+  const sentinel = `facility module: ${moduleName}`;
+  if (hookSource.includes(sentinel)) return { content: hookSource, inserted: false };
+  if (!hookSource.includes(HOOK_MARKER)) return { content: hookSource, inserted: false };
+  return {
+    content: hookSource.replace(HOOK_MARKER, `${fragment.trim()}\n\n${HOOK_MARKER}`),
+    inserted: true,
+  };
+}

package/src/ui.mjs

@@ -0,0 +1,30 @@
+// Terminal output helpers. Zero dependencies; ANSI only when it's a TTY and
+// NO_COLOR is unset. Restrained on purpose — the CLI should read like a
+// well-run factory floor, not a slot machine.
+const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
+const ESC = "\u001b";
+
+const wrap = (code) => (text) => (useColor ? `${ESC}[${code}m${text}${ESC}[0m` : String(text));
+
+export const bold = wrap("1");
+export const dim = wrap("2");
+export const accent = wrap("38;5;220"); // facility yellow — reserved for agent work
+export const green = wrap("32");
+export const red = wrap("31");
+export const yellow = wrap("33");
+
+export function banner(version) {
+  console.log("");
+  console.log(`  ${bold("facility")} ${dim(`v${version}`)} ${dim("— the AI software factory for your repo")}`);
+  console.log("");
+}
+
+export function heading(text) {
+  console.log(`\n${bold(text)}`);
+}
+
+export const ok = (text) => console.log(`  ${green("✓")} ${text}`);
+export const skip = (text) => console.log(`  ${dim("—")} ${dim(text)}`);
+export const warn = (text) => console.log(`  ${yellow("!")} ${text}`);
+export const fail = (text) => console.log(`  ${red("✗")} ${text}`);
+export const item = (text) => console.log(`  ${text}`);

package/templates/claude/agents/security-reviewer.md

@@ -0,0 +1,41 @@
+---
+name: security-reviewer
+description: Adversarial reviewer for auth boundaries, secret handling, injection paths, and privilege escalation. Use proactively before merging any change that touches auth, privileged access, external input parsing, CI workflows, or agent-facing surfaces.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a security reviewer. You review a diff in a fresh context, so you are
+not biased toward the code under review. Assume authorization gaps **fail
+silently** — verify the negative case, never trust a prose claim that a
+boundary is enforced.
+
+## What to check
+1. **Secrets**: no credentials, tokens, or signed URLs in code, fixtures,
+   logs, or test snapshots. `.env` handling respects the repo's hooks.
+2. **Input trust**: external input (HTTP, webhooks, issue/PR text consumed by
+   agents, file uploads) is validated at the boundary and never interpolated
+   into shell, SQL, or query builders.
+3. **Authorization**: every new read/write path re-checks permission at the
+   boundary that owns the data; no privileged client or service account leaks
+   into user-facing or agent-facing read paths.
+4. **CI surface**: workflow changes keep actions pinned to full commit SHAs,
+   never echo secrets, never widen `permissions:`, and never expose secrets to
+   fork-originated code.
+5. **Agent surface**: prompts and tool contracts keep untrusted text framed as
+   DATA; no new path lets repository content instruct an agent to exfiltrate
+   or escalate.
+6. **Failure modes**: errors don't leak internals; empty results are
+   permission-safe (they don't hint that hidden data exists).
+
+## How to verify
+- `node guards/run.mjs` — deterministic repo invariants, including the
+  workflow-pinning guard.
+- Targeted greps for the diff's trust boundaries; run the repo's auth/security
+  tests when the diff justifies it.
+
+## Output contract
+Return findings ordered by severity (Blocker / High / Medium), each with
+file:line, the exact risk, and the smallest fix. State which checks you ran
+and their result. Report **only** security/privacy/correctness gaps — not
+style. If you find nothing, say "No security gaps found" and list the checks
+that prove it.

package/templates/claude/agents/standards-reviewer.md

@@ -0,0 +1,31 @@
+---
+name: standards-reviewer
+description: Lead quality reviewer that runs this repo's STANDARD.md completion checklist end to end. Use before finalizing or opening a PR for any change with product behavior.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the lead reviewer enforcing `STANDARD.md` as the development standard
+for the whole team, not only as agent guidance. You review the diff in a fresh
+context and lead with correctness, security, maintainability, and
+product-quality before any polish. Be the adversarial second opinion: report
+only real correctness/security/requirements/quality gaps — do not invent style
+nits or impossible-case concerns.
+
+## Method
+1. Establish scope: read the diff and identify user-facing behavior, affected
+   domains, and risk level.
+2. Walk the **Pull request review standard** and **Completion checklist** from
+   `STANDARD.md`, including any module sections between the
+   `facility:modules` markers.
+3. For any domain that carries real risk, recommend (or dispatch, when doing a
+   deep review) the matching specialist subagent from `.claude/agents/`.
+4. Run the lightest useful verification yourself and escalate based on risk.
+   `node guards/run.mjs` is always cheap and always relevant.
+
+## Output contract
+Produce a verdict: **Ready** / **Ready with follow-ups** / **Not ready**. Then
+findings grouped by severity (Blocker / High / Medium), each with file:line,
+the exact risk, the missed standard, and the smallest fix. Avoid vague asks
+like "clean this up" or "add tests" without naming the missing case. Finish
+with the exact checks you ran and their results. Keep it concise and
+team-lead-ready.

package/templates/claude/commands/open-pr.md

@@ -0,0 +1,21 @@
+---
+description: Open a concise, team-lead-ready PR following STANDARD.md
+---
+
+Open a pull request for the current branch following STANDARD.md's PR rules.
+
+1. Preconditions: branch name is semantic (`feature/...`, `fix/...`, ... —
+   no agent/tool prefixes); commits follow Conventional Commits; the
+   relevant checks from /verify have run in this session — if not, run them
+   first.
+2. Push the branch and create the PR with `gh pr create` targeting
+   {{DEFAULT_BRANCH}}, with:
+   - A Conventional-Commits title describing the product/domain intent.
+   - The body structure from STANDARD.md (Summary / Context / Verification /
+     Linked issues) — tight, no implementation diary, no filler.
+   - The full issue URL when one exists in the branch name, commits, or
+     conversation, as a `Closes #<n>` closing keyword. Never invent issue
+     links.
+3. Mention what was intentionally NOT touched (migrations, analytics,
+   security surface) when a reviewer would otherwise expect it.
+4. Print the PR URL.

package/templates/claude/commands/verify.md

@@ -0,0 +1,16 @@
+---
+description: Run the right checks for the current change and report honestly
+---
+
+Verify the current working-tree change per STANDARD.md's verification ladder.
+
+1. Look at the diff (`git status`, `git diff`) and classify what it touches:
+   pure code, data/migrations, security surface, UI, analytics, agent
+   surface.
+2. Run the lightest relevant checks first, escalating by risk:
+
+{{CHECKS_LIST}}
+
+3. Report a short table: check → result. Name every relevant check you did
+   NOT run and why. Never summarize a failure away — paste the meaningful
+   tail of the output and say what you'd try next.

package/templates/claude/hooks/protect-branch.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Generated by facility — https://github.com/theam/facility
+//
+// PreToolUse hook (Bash). Blocks a small set of unambiguously dangerous
+// commands before they run (exit 2 = deny, stderr is shown to the agent).
+// Deliberately narrow: it guards destructive/irreversible actions, not normal
+// development.
+import { readFileSync } from "node:fs";
+
+const PROTECTED = /^(origin\/)?({{DEFAULT_BRANCH}}|main|master)$/;
+
+function readPayload() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+const command = readPayload()?.tool_input?.command ?? "";
+if (!command) process.exit(0);
+
+const tokens = command.split(/\s+/);
+const has = (t) => tokens.includes(t);
+const targetsProtected = (t) => PROTECTED.test(t) || /:({{DEFAULT_BRANCH}}|main|master)$/.test(t);
+const targetsProtectedRef = tokens.some(targetsProtected);
+const isForce = has("--force") || has("-f") || has("--force-with-lease");
+
+function block(reason) {
+  console.error(`⛔ Blocked by .claude/hooks/protect-branch.mjs\n${reason}`);
+  process.exit(2);
+}
+
+// Recursive force-remove rooted at filesystem root or $HOME.
+if (
+  /\brm\b/.test(command) &&
+  /-[a-z]*r/i.test(command) &&
+  /-[a-z]*f/i.test(command) &&
+  /\s(\/|~|\$HOME)(\s|\/|$)/.test(command)
+) {
+  block("Recursive force-remove of a root or home path is not allowed.");
+}
+
+if (has("git") && has("push") && targetsProtectedRef && isForce) {
+  block("Force-pushing the default branch is not allowed. Use a feature branch + PR.");
+}
+
+if (has("git") && has("push") && targetsProtectedRef) {
+  block("Direct pushes to the default branch are not allowed — open a PR (see STANDARD.md).");
+}
+
+if (/>>?\s*\.?\/?\.env(\.[\w.]+)?\b/.test(command) && !/\.env\.example\b/.test(command)) {
+  block(
+    "Refusing to redirect output into a real .env file (secrets). Edit .env.example for placeholders.",
+  );
+}
+
+process.exit(0);

package/templates/claude/hooks/protect-files.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+// Generated by facility — https://github.com/theam/facility
+//
+// PreToolUse hook (Edit|Write|MultiEdit). Protects files that must not be
+// mutated casually (exit 2 = deny, stderr is shown to the agent).
+//
+// Real .env files hold live secrets — placeholders belong in .env.example.
+// Facility modules may extend this file with extra protections (for example,
+// the database module adds migration immutability).
+import { readFileSync } from "node:fs";
+
+function readPayload() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+const payload = readPayload();
+const filePath = payload?.tool_input?.file_path ?? "";
+if (!filePath) process.exit(0);
+
+function block(reason) {
+  console.error(`⛔ Blocked by .claude/hooks/protect-files.mjs\n${reason}`);
+  process.exit(2);
+}
+
+if (/(^|\/)\.env(\.[\w.]+)?$/.test(filePath) && !/\.env\.example$/.test(filePath)) {
+  block("Refusing to write a real .env file (secrets). Use .env.example for placeholders.");
+}
+
+/* facility:module-rules */
+
+process.exit(0);

package/templates/claude/settings.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "includeCoAuthoredBy": false,
+  "permissions": {
+    "defaultMode": "default",
+    "allow": [
+      {{ALLOW_CHECKS_JSON}}
+      "Bash(node guards/run.mjs)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git add:*)",
+      "Bash(git restore:*)",
+      "Bash(git branch:*)",
+      "Bash(git switch:*)",
+      "Bash(git checkout:*)",
+      "Bash(git commit:*)",
+      "Bash(git fetch:*)",
+      "Bash(git rev-parse:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh issue list:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)"
+    ],
+    "ask": [
+      "Bash(git push:*)",
+      "Bash(gh pr create:*)",
+      "Bash(gh pr merge:*)",
+      "Bash(gh issue create:*)"
+    ],
+    "deny": [
+      "Read(.env)",
+      "Read(.env.local)",
+      "Read(.env.*.local)",
+      "Bash(sudo:*)",
+      "Bash(rm -rf /)",
+      "Bash(rm -rf ~)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)"
+    ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-branch.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/protect-files.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/claude/skills/maintainable-software/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: maintainable-software
+description: Engineering judgment for writing code that stays cheap to change — simplicity, naming, boundaries, duplication, tests. Apply to any feature work, refactor, API design, or architecture decision, in any language.
+---
+
+# Maintainable software
+
+The cost of software is the cost of changing it later. Every rule here
+optimizes for the next reader and the next change, not for the author.
+
+## Simplicity
+
+- Solve the problem in front of you. Speculative generality — the parameter
+  nobody passes, the interface with one implementation — is debt with no
+  loan.
+- Prefer boring constructs. Cleverness needs a comment; boring code doesn't.
+- One concept per unit: a function that needs "and" in its description is two
+  functions.
+
+## Naming
+
+- Names come from the domain, not the implementation: `settleInvoice`, not
+  `processData2`.
+- A name that needs a comment to be understood is the wrong name. Rename
+  first, comment only for what code cannot say (constraints, why-not-the-
+  obvious-way).
+- Inconsistent vocabulary is a bug factory: one concept, one word, repo-wide.
+
+## Boundaries and interfaces
+
+- Narrow interfaces, deep modules: expose the smallest surface that serves
+  the caller; keep the complexity behind it.
+- Dependencies point one way. A module that reaches into its consumers — or
+  into globals — can't be tested or replaced.
+- Side effects live at the edges; the core is data in, data out. If a
+  function both computes and writes, split it.
+
+## Duplication
+
+- Duplicate **shape** is fine; duplicate **concept** is not. Two functions
+  that look alike but change for different reasons should stay apart; one
+  business rule written twice will diverge and one copy will be wrong.
+- Extract on the second real occurrence of the same concept, with a domain
+  name. Extracting on resemblance creates the worst abstraction: the shared
+  helper full of flags.
+
+## Errors
+
+- Make failure explicit at the boundary: validate input where it enters,
+  fail with a message the caller can act on, never swallow.
+- Impossible states should be unrepresentable (types, schemas, constraints)
+  rather than checked everywhere.
+
+## Tests
+
+- Tests protect behavior, not implementation. A test that breaks on a
+  rename is friction; a behavior change that breaks no test is a hole.
+- Test the boundary you'd be afraid to change. If a bug got through, the
+  first fix is the test that would have caught it.
+
+## Changes
+
+- The best diff is the smallest one that fully solves the problem. Refactors
+  travel separately from behavior changes — a reviewer can hold one of them
+  in their head, not both.
+- Leave the campsite slightly cleaner, never reorganized: opportunistic
+  renames yes, opportunistic redesigns no.

package/templates/claude/skills/reviewing-to-standard/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: reviewing-to-standard
+description: Review code changes against this repo's STANDARD.md. Use when reviewing a PR, a diff, or another agent's work — enforces the review order, the comment quality bar, and severity discipline.
+---
+
+# Reviewing to standard
+
+A review exists to change the implementer's next action. Everything else is
+noise.
+
+## Review order (stop-the-line first)
+
+1. **Correctness and fit** — the change does what was asked, no more. Scope
+   creep is a finding, not a bonus.
+2. **Security and privacy** — auth regressions, data exposure, secret
+   handling, injection paths, new attack surface. Verify the negative case;
+   never accept a prose claim that a boundary holds.
+3. **Maintainability** — same concept reused not duplicated, clear ownership
+   boundaries, domain names, side effects visible, easy for the next caller
+   and the next test.
+4. **Standard compliance** — `STANDARD.md` and its module sections were
+   followed. A missed module requirement (seeds, analytics, evidence,
+   exposure) is a product-quality gap, not optional polish.
+5. **Verification evidence** — the right checks ran for the risk taken, and
+   skipped checks are named. `node guards/run.mjs` should be green.
+
+## The comment contract
+
+Every finding carries four things: `file:line`, the exact risk, the smallest
+practical fix, and the standard it missed. Severity is explicit — Blocker /
+High / Medium — and separated from optional suggestions. Never post:
+
+- Style-only nits, unless they hide a real bug or future maintenance cost.
+- Vague asks ("clean this up", "add tests") — name the missing case, command,
+  or assertion instead.
+- Requests for broad rewrites when a narrow change closes the risk.
+
+## Leverage
+
+For domains with real risk, dispatch the matching reviewer subagent from
+`.claude/agents/` and consolidate its findings rather than re-deriving them.
+If the same problem has now appeared twice in reviews, the review is the
+wrong tool: propose the guard (`guards/`) that makes the third occurrence
+impossible, and say so in the review.
+
+## Verdict
+
+End with **Ready / Ready with follow-ups / Not ready**, the checks you ran,
+and nothing else. You never approve or merge — that signature is human.

package/templates/claude/skills/working-to-standard/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: working-to-standard
+description: Apply this repo's STANDARD.md while implementing, refactoring, or fixing. Use for any change that affects product behavior — before editing, while verifying, and when reporting done.
+---
+
+# Working to standard
+
+`STANDARD.md` is the contract; this skill is how it's applied while the work
+is happening, not checked after the fact.
+
+## Before editing
+
+1. Read `STANDARD.md`, including the module sections between the
+   `facility:modules` markers — they carry domain rules (data, analytics,
+   design, AI exposure) that change what "done" means.
+2. Name the user-facing outcome, the affected boundaries, the invariants that
+   must hold, and the rollback surface. If you can't, the task isn't clear
+   enough to edit yet — ask the one question that unblocks it.
+3. Find the local pattern first. The repo's existing shape beats the general
+   best practice; new abstractions need to remove real complexity.
+
+## While editing
+
+- Deliver the WHOLE request as the smallest coherent change — no drive-by
+  refactors, no "phase 1" unless phasing was requested.
+- Keep side effects at the edges and visible: network, database, time,
+  randomness, file system, model calls.
+- Validate input at trust boundaries with the existing schema/parsing
+  patterns; make invalid states hard to represent.
+- When you touch a domain with a reviewer subagent in `.claude/agents/`,
+  apply its checklist as you go — cheaper than failing its review later.
+
+## Verifying
+
+Run the lightest useful checks first, escalate by risk, per the verification
+ladder in `STANDARD.md`. `node guards/run.mjs` is always cheap and always
+relevant. A check you cannot run is reported by name with the reason — never
+claimed.
+
+## Reporting done
+
+One concise summary: what changed and why, the checks you ran with their
+results, and any genuinely out-of-scope follow-ups. Walk the completion
+checklist in `STANDARD.md` before saying done; an unmet item is either fixed
+or explicitly reported, never silent.