@theagilemonkeys/facility 0.3.1

package/modules/database/module.json

@@ -0,0 +1,25 @@
+{
+  "name": "database",
+  "title": "Database",
+  "description": "Migrations are immutable and append-only; access control by default; privileged credentials stay out of user-facing paths.",
+  "standardSection": "standard-section.md",
+  "files": [
+    {
+      "from": "agents/data-security-reviewer.md",
+      "to": ".claude/agents/data-security-reviewer.md"
+    },
+    {
+      "from": "guards/migrations-immutable.mjs",
+      "to": "guards/migrations-immutable.mjs"
+    },
+    {
+      "from": "guards/migration-versions.mjs",
+      "to": "guards/migration-versions.mjs"
+    },
+    {
+      "from": "commands/new-migration.md",
+      "to": ".claude/commands/new-migration.md"
+    }
+  ],
+  "hookRules": "hooks/protect-migrations.fragment.mjs"
+}

package/modules/database/standard-section.md

@@ -0,0 +1,20 @@
+### Database (facility module)
+
+Migrations are the durable state of the database. They are **append-only**:
+a change is a NEW migration, never an edit to one that may have been applied
+anywhere. The `migrations-immutable` guard and the `.claude/hooks` rules
+enforce this mechanically.
+
+- New tables and collections start closed: enable row/document-level access
+  control where the platform supports it, deny by default, grant only the
+  minimum required operations.
+- Authorization checks route through one shared helper layer — never inline
+  token/claim parsing inside individual policies or queries.
+- Privileged credentials (service role, admin connections) stay out of
+  user-facing and agent-facing read paths. Any privileged action lives in a
+  reviewed application service with explicit permission checks and tests.
+- Update seed data whenever a feature needs realistic data to test locally.
+  Seeds follow the domain: realistic names, states, relationships, and edge
+  cases — not toy rows that only satisfy a test selector.
+- Empty results must be permission-safe: do not imply hidden data exists when
+  access control returns nothing.

package/modules/design-system/agents/design-reviewer.md

@@ -0,0 +1,37 @@
+---
+name: design-reviewer
+description: Reviews UI changes against the repo's design system and checks that critical UI flows carry browser evidence. Use when a change adds or modifies UI, layout, components, or styling.
+tools: Read, Grep, Glob, Bash
+---
+
+You review product UI against this repository's design system and confirm
+critical flows are verified in a browser. A UI that conflicts with the design
+system is a product-quality issue.
+
+## Authoritative references
+- The design system source of truth declared in `STANDARD.md` (Design system
+  section) — read it before judging.
+- The repo's design tokens / shared component layer — existing values come
+  first.
+
+## What to check
+1. Existing design tokens and helpers are reused before any new value; no
+   ad-hoc colors, spacing, or radii that bypass the token layer.
+2. Components match the system's catalog: shapes, sizes, states, and
+   hierarchy expressed the way the system prescribes.
+3. **Evidence**: UI flow changes include a browser verification note
+   (Playwright run, screenshots), or an explicit reason UI verification did
+   not apply.
+4. Responsive behavior holds at the product's breakpoints when layout, text
+   fit, navigation, modals, or tables can be affected.
+5. Empty, error, and loading states are designed, not accidental.
+
+## How to verify
+- `grep` the diff for raw color/spacing literals that should be tokens.
+- Recommend the smallest browser run that covers the affected flows.
+
+## Output contract
+List design-system violations and missing evidence by severity with file:line
+and the token/helper to use instead. Confirm which critical flows are covered
+by browser evidence. Flag only design-system/UX-correctness gaps, not
+subjective taste.

package/modules/design-system/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "design-system",
+  "title": "Design system",
+  "description": "UI changes conform to your design system and critical flows carry browser evidence.",
+  "standardSection": "standard-section.md",
+  "files": [
+    { "from": "agents/design-reviewer.md", "to": ".claude/agents/design-reviewer.md" }
+  ]
+}

package/modules/design-system/standard-section.md

@@ -0,0 +1,15 @@
+### Design system (facility module)
+
+A UI that conflicts with the design system is a product-quality issue, not a
+matter of taste. Declare your source of truth here (a spec doc, a tokens
+file, a published package) — the design reviewer reads it before judging.
+
+- Use existing design tokens and shared components before inventing values.
+  Ad-hoc colors, spacing, and radii that bypass the token layer are defects.
+- UI flow changes include browser evidence — a Playwright run, screenshots,
+  or a recorded check — or an explicit reason why UI verification did not
+  apply. "It compiles" is not evidence for layout.
+- Verify responsive behavior at the breakpoints your product supports when a
+  change can affect layout, text fit, navigation, modals, or tables.
+- Empty states, error states, and loading states are part of the surface —
+  design them, don't let them fall out of the happy path.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@theagilemonkeys/facility",
+  "version": "0.3.1",
+  "description": "Run an AI crew on your GitHub repo: agents that plan before building, build to your standard, verify on a provisioned environment, and never merge their own work.",
+  "keywords": [
+    "ai",
+    "agents",
+    "sdlc",
+    "claude-code",
+    "github-actions",
+    "code-review",
+    "automation"
+  ],
+  "homepage": "https://github.com/theam/facility#readme",
+  "bugs": "https://github.com/theam/facility/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theam/facility.git",
+    "directory": "packages/cli"
+  },
+  "license": "Apache-2.0",
+  "author": "The Agile Monkeys (https://theagilemonkeys.com)",
+  "type": "module",
+  "bin": {
+    "facility": "bin/facility.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "modules"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "postgres": "^3.4.7"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/src/add.mjs

@@ -0,0 +1,77 @@
+// `facility add <module>` — install a quality module: its STANDARD.md section,
+// its reviewer subagent, its guards, and its hook rules.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { insertHookRules, insertModuleSection } from "./render.mjs";
+import { fail, heading, ok, skip, warn } from "./ui.mjs";
+
+export async function addModule(name, { dir, pkgRoot, banner = true }) {
+  const moduleDir =
+    name.startsWith(".") || isAbsolute(name) ? resolve(dir, name) : join(pkgRoot, "modules", name);
+
+  const manifestPath = join(moduleDir, "module.json");
+  if (!existsSync(manifestPath)) {
+    const available = readdirSync(join(pkgRoot, "modules"), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .join(", ");
+    fail(`Unknown module "${name}". Available: ${available} (or a local path).`);
+    return 1;
+  }
+  const module = JSON.parse(readFileSync(manifestPath, "utf8"));
+  if (banner) heading(`Adding module: ${module.title}`);
+
+  // 1. Files (reviewer subagents, guards) — never overwrite.
+  for (const file of module.files ?? []) {
+    const target = join(dir, file.to);
+    if (existsSync(target)) {
+      skip(`${file.to} exists — left untouched`);
+      continue;
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, readFileSync(join(moduleDir, file.from), "utf8"));
+    ok(file.to);
+  }
+
+  // 2. STANDARD.md section between the facility:modules markers.
+  const standardPath = join(dir, "STANDARD.md");
+  if (module.standardSection && existsSync(standardPath)) {
+    const section = readFileSync(join(moduleDir, module.standardSection), "utf8");
+    const { content, inserted } = insertModuleSection(readFileSync(standardPath, "utf8"), section, module.title);
+    if (inserted) {
+      writeFileSync(standardPath, content);
+      ok(`STANDARD.md — "${module.title}" section`);
+    } else {
+      skip(`STANDARD.md already has the "${module.title}" section`);
+    }
+  } else if (module.standardSection) {
+    warn("STANDARD.md not found — run `facility init` first.");
+  }
+
+  // 3. Hook rules spliced into protect-files.mjs at the module marker.
+  if (module.hookRules) {
+    const hookPath = join(dir, ".claude/hooks/protect-files.mjs");
+    if (existsSync(hookPath)) {
+      const fragment = readFileSync(join(moduleDir, module.hookRules), "utf8");
+      const { content, inserted } = insertHookRules(readFileSync(hookPath, "utf8"), fragment, module.name);
+      if (inserted) {
+        writeFileSync(hookPath, content);
+        ok(".claude/hooks/protect-files.mjs — rules spliced");
+      } else {
+        skip(".claude/hooks/protect-files.mjs already has this module's rules");
+      }
+    }
+  }
+
+  // 4. Record it in the manifest.
+  const facilityManifestPath = join(dir, ".facility.json");
+  if (existsSync(facilityManifestPath)) {
+    const manifest = JSON.parse(readFileSync(facilityManifestPath, "utf8"));
+    if (!manifest.modules?.includes(module.name)) {
+      manifest.modules = [...(manifest.modules ?? []), module.name];
+      writeFileSync(facilityManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    }
+  }
+
+  return 0;
+}

package/src/cli.mjs

@@ -0,0 +1,352 @@
+// facility CLI entry: init · add · doctor.
+import { readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { init } from "./init.mjs";
+import { addModule } from "./add.mjs";
+import { doctor } from "./doctor.mjs";
+import { bootstrapInstance } from "./instance.mjs";
+import { runPlatformCommand } from "./platform.mjs";
+import { banner, bold, dim, item } from "./ui.mjs";
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const version = JSON.parse(readFileSync(join(pkgRoot, "package.json"), "utf8")).version;
+
+function parseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--yes" || arg === "-y") flags.yes = true;
+    else if (arg === "--json") flags.json = true;
+    else if (arg === "--force") flags.force = true;
+    else if (["--help", "--local", "--platform"].includes(arg)) flags[arg.slice(2)] = true;
+    else if (arg.startsWith("--") && arg.includes("=")) {
+      const [key, ...rest] = arg.slice(2).split("=");
+      flags[key] = rest.join("=");
+    } else if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[index + 1];
+      if (next && !next.startsWith("-")) {
+        flags[key] = next;
+        index += 1;
+      } else flags[key] = true;
+    } else if (!arg.startsWith("-")) positional.push(arg);
+  }
+  return { flags, positional };
+}
+
+function help() {
+  banner(version);
+  helpGroup("Build your repo", [
+    ["init", "install the Facility method"],
+    ["add <module>", "add a quality module"],
+    ["doctor", "verify local and platform readiness"],
+  ]);
+  helpGroup("Operate", [
+    ["status", "runs, approvals, issues, and spend at a glance"],
+    ["projects", "create, inspect, update, or archive projects"],
+    ["repos", "connect or create GitHub repositories"],
+    ["agents", "configure agent definitions and schedules"],
+    ["sessions", "trigger, watch, steer, or cancel governed sessions"],
+    ["conversations", "continue durable agent conversations"],
+    ["github", "discover repositories and act on GitHub issues"],
+    ["inbox", "review and decide proposals"],
+    ["issues", "acknowledge and resolve platform issues"],
+    ["kickstart", "preview and open a governed installation PR"],
+    ["upgrade", "open a governed template upgrade PR"],
+  ]);
+  helpGroup("Knowledge & policy", [
+    ["kb", "manage the project knowledge base"],
+    ["tasks", "manage the product-owner task queue"],
+    ["registry", "version contracts, harnesses, and policies"],
+    ["proposals", "create, inspect, and execute approval gates"],
+    ["action-types", "discover proposal payload contracts"],
+    ["budgets", "enforce org, project, and agent budgets"],
+    ["health", "inspect project readiness"],
+    ["outcomes", "inspect pull-request delivery outcomes"],
+    ["catalog", "discover engines, models, permissions, and triggers"],
+  ]);
+  helpGroup("Platform administration", [
+    ["instance bootstrap", "bootstrap a dedicated Facility instance"],
+    ["org", "organization settings"],
+    ["members", "organization membership"],
+    ["roles", "permission policy"],
+    ["keys", "control-plane API credentials"],
+    ["virtual-keys", "project-scoped model credentials"],
+    ["providers", "model-provider credentials"],
+    ["sandboxes", "execution profiles and isolation"],
+    ["integrations", "inbound and outbound webhooks"],
+    ["analytics", "run and reliability trends"],
+    ["spend", "cost attribution"],
+    ["audit", "tamper-evident change ledger"],
+    ["llm-requests", "inspect metering and request envelopes"],
+  ]);
+  helpGroup("Account", [
+    ["login", "verify and save an environment profile"],
+    ["logout", "remove saved profile credentials"],
+    ["profiles", "switch between Facility environments"],
+  ]);
+  console.log("");
+  item(dim("init flags: --yes --force --dir=<path> --branch=<name> --provision=<cmd>"));
+  item(dim('            --checks="cmd1, cmd2" --auth=<api-key|oauth|wif|bedrock|vertex>'));
+  item(dim('            --build-model=<id> --review-model=<id> --plan-model=<id>'));
+  item(dim('            --codex-build-model=<id> --codex-plan-model=<id> --org=<org> --project=<n>'));
+  item(dim('            --preview-image=<image> --preview-command=<cmd> --preview-port=<n> --preview-readiness-path=</health> --preview-ttl-hours=<n>'));
+  item(dim("Run facility <command> --help for precise usage."));
+  item(dim("Global platform flags: --profile <name> --json --timeout <seconds>"));
+  console.log("");
+  item(dim("Docs: https://github.com/theam/facility"));
+  console.log("");
+}
+
+function helpGroup(label, commands) {
+  item(bold(label));
+  const width = Math.max(...commands.map(([command]) => command.length));
+  for (const [command, description] of commands) {
+    item(`  ${bold(`facility ${command.padEnd(width)}`)}  ${dim(description)}`);
+  }
+  console.log("");
+}
+
+export async function main(argv) {
+  const { command, rest } = extractInvocation(argv);
+  const { flags, positional } = parseFlags(rest);
+  const localFlagError = validateLocalFlags(command, flags);
+  if (localFlagError) {
+    if (flags.json) {
+      console.log(JSON.stringify({ error: { code: "invalid_flag", message: localFlagError } }));
+    } else console.error(localFlagError);
+    return 1;
+  }
+  if (flags.dir) flags.dir = resolve(flags.dir);
+
+  if (flags.help && ["init", "add", "doctor"].includes(command)) {
+    localHelp(command);
+    return 0;
+  }
+
+  switch (command) {
+    case "init":
+      return init(flags, pkgRoot, version);
+    case "add": {
+      if (!positional[0]) {
+        help();
+        return 1;
+      }
+      return addModule(positional[0], { dir: flags.dir || process.cwd(), pkgRoot });
+    }
+    case "doctor":
+      return doctor(flags, version);
+    case "instance":
+      if (positional[0] === "bootstrap") return bootstrapInstance(flags);
+      console.error("Usage: facility instance bootstrap [options]");
+      return 1;
+    case "login":
+    case "logout":
+    case "profiles":
+    case "status":
+    case "projects":
+    case "sessions":
+    case "runs":
+    case "conversations":
+    case "github":
+    case "outcomes":
+    case "catalog":
+    case "inbox":
+    case "issues":
+    case "kickstart":
+    case "upgrade":
+    case "keys":
+    case "llm-requests":
+    case "org":
+    case "members":
+    case "roles":
+    case "repos":
+    case "agents":
+    case "providers":
+    case "budgets":
+    case "registry":
+    case "sandboxes":
+    case "tasks":
+    case "virtual-keys":
+    case "kb":
+    case "analytics":
+    case "audit":
+    case "integrations":
+    case "spend":
+    case "proposals":
+    case "action-types":
+    case "health":
+      return runPlatformCommand(command, rest);
+    case "--version":
+    case "-v":
+      console.log(version);
+      return 0;
+    default:
+      if (command && !["help", "--help"].includes(command)) {
+        console.error(`Unknown command: ${command}`);
+      }
+      help();
+      return command === undefined || command === "help" || command === "--help" ? 0 : 1;
+  }
+}
+
+function validateLocalFlags(command, flags) {
+  const allowed = {
+    init: new Set([
+      "yes",
+      "force",
+      "dir",
+      "branch",
+      "provision",
+      "checks",
+      "project",
+      "org",
+      "modules",
+      "auth",
+      "build-model",
+      "review-model",
+      "plan-model",
+      "codex-build-model",
+      "codex-plan-model",
+      "preview-image",
+      "preview-command",
+      "preview-port",
+      "preview-readiness-path",
+      "preview-ttl-hours",
+      "help",
+    ]),
+    add: new Set(["dir", "help"]),
+    doctor: new Set([
+      "dir",
+      "local",
+      "platform",
+      "profile",
+      "url",
+      "key",
+      "allow-insecure",
+      "timeout",
+      "run-guards",
+      "github",
+      "json",
+      "help",
+    ]),
+    instance: new Set([
+      "org-name",
+      "org-slug",
+      "owner-email",
+      "owner-name",
+      "github-user-id",
+      "github-login",
+      "github-account-id",
+      "github-installation-id",
+      "github-account-login",
+      "github-account-type",
+      "json",
+      "help",
+    ]),
+  }[command];
+  if (!allowed) return null;
+  const unknown = Object.keys(flags).filter((flag) => !allowed.has(flag));
+  if (unknown.length) {
+    return `Unknown option${unknown.length === 1 ? "" : "s"}: ${unknown.map((flag) => `--${flag}`).join(", ")}`;
+  }
+  const valueNames =
+    command === "doctor"
+      ? ["dir", "profile", "url", "key", "timeout"]
+      : command === "instance"
+        ? [...allowed].filter((name) => !["json", "help"].includes(name))
+        : command === "init"
+        ? [
+            "dir",
+            "branch",
+            "provision",
+            "checks",
+            "project",
+            "org",
+            "modules",
+            "auth",
+            "build-model",
+            "review-model",
+            "plan-model",
+            "codex-build-model",
+            "codex-plan-model",
+            "preview-image",
+            "preview-command",
+            "preview-port",
+            "preview-readiness-path",
+            "preview-ttl-hours",
+          ]
+        : ["dir"];
+  for (const name of valueNames) {
+    if (name in flags && (typeof flags[name] !== "string" || flags[name].trim() === "")) {
+      return `--${name} requires a value`;
+    }
+  }
+  if (
+    command === "doctor" &&
+    flags.local &&
+    (flags.platform || flags.profile || flags.url || flags.key)
+  ) {
+    return "--local cannot be combined with platform target options";
+  }
+  if (
+    command === "doctor" &&
+    (flags.platform || flags.profile || flags.url || flags.key) &&
+    (flags["run-guards"] || flags.github)
+  ) {
+    return "--run-guards and --github are local-doctor options";
+  }
+  for (const name of [
+    "yes",
+    "force",
+    "help",
+    "local",
+    "platform",
+    "allow-insecure",
+    "run-guards",
+    "github",
+    "json",
+  ]) {
+    if (name in flags && flags[name] !== true) return `--${name} does not take a value`;
+  }
+  return null;
+}
+
+function extractInvocation(argv) {
+  const leading = [];
+  const valueFlags = new Set(["--profile", "--timeout", "--dir", "--url", "--key"]);
+  let index = 0;
+  while (index < argv.length && argv[index]?.startsWith("-") && !["--help", "--version", "-v"].includes(argv[index])) {
+    const flag = argv[index];
+    leading.push(flag);
+    index += 1;
+    if (valueFlags.has(flag) && index < argv.length) {
+      leading.push(argv[index]);
+      index += 1;
+    }
+  }
+  return { command: argv[index], rest: [...leading, ...argv.slice(index + 1)] };
+}
+
+function localHelp(command) {
+  const lines = {
+    init: [
+      "facility init [--dir <path>] [--yes] [--force]",
+      "Detect the repository and install Facility workflows, guards, agents, and policy.",
+    ],
+    add: [
+      "facility add <module> [--dir <path>]",
+      "Add a Facility quality module to an existing installation.",
+    ],
+    doctor: [
+      "facility doctor [--dir <path>] [--run-guards] [--github] [--json] | --platform [--profile <name>] [--timeout <seconds>] [--json] | --url <url> --key <key> [--allow-insecure] [--timeout <seconds>] [--json]",
+      "Verify a local installation or an explicitly selected platform deployment; JSON works in either mode.",
+    ],
+  };
+  const [usage, description] = lines[command];
+  console.log(`\n  ${bold(`facility ${command}`)}`);
+  console.log(`  ${dim(description)}\n`);
+  console.log(`  ${bold("Usage")}\n    ${usage}\n`);
+}