@theagilemonkeys/facility 0.11.3 → 0.12.0

package/README.md

@@ -1,69 +1,83 @@
 # @theagilemonkeys/facility
 
-The command-line half of [Facility](https://github.com/theam/facility) —
-open-source, self-hosted tooling for running AI coding agents as part of a
-reviewable delivery process, with the humans, the gates and the evidence in one
-place.
+The Facility CLI installs and validates the small repository contract used by
+Facility 0.12. Day-to-day story work happens through the Facility MCP server or
+web application.
 
-One binary with two jobs, and you rarely need both:
+```bash
+cd your-repository
+npx @theagilemonkeys/facility init
+npx @theagilemonkeys/facility doctor
+```
+
+Node.js 24 LTS is recommended; Node.js 22 is supported from 22.13.0.
+
+## Initialize a repository
 
-- **A client for a Facility platform.** Dispatch agents, follow sessions, decide
-  proposals, inspect spend, manage projects and repositories — everything the
-  web application does, from a terminal or a script.
-- **An installer for a repository.** When a team wants the process running in
-  its own CI, invoked from issue comments, `facility init` writes the workflows,
-  the standard, the skills and the guards into the repository.
+Interactive init detects the GitHub remote, package manager, setup command,
+development command, and application port. For automation, provide the values
+explicitly:
 
 ```bash
-npx @theagilemonkeys/facility --help
+npx @theagilemonkeys/facility init --yes \
+  --repo=acme/application \
+  --provision='pnpm install --frozen-lockfile' \
+  --start='docker compose up -d' \
+  --preview-readiness-command='curl --fail http://localhost:3000/health' \
+  --service-port=3000
 ```
 
-Node.js 24 LTS recommended; Node.js 22 supported from 22.13.0. Zero
-configuration to read; one dependency.
+`init` writes exactly two kinds of project-owned configuration:
 
-**Early software.** Facility is published while it is still being built: the
-API is young, generated files change shape between `0.x` releases, and no
-upgrade path is promised across them. Apache-2.0 means what it says — no
-warranty, use at your own risk.
+- `.facility.yml` describes the repositories, setup command, development
+  command, readiness check, and exposed services for a persistent workspace.
+- `.agents/*.md` describes each agent's prompt, engine, model, and manual, MCP,
+  UI, scheduled, or GitHub triggers.
 
-## Talking to a platform
+Existing files are preserved unless `--force` is explicit. Agent manifests do
+not contain permission profiles: every enabled agent receives the same full
+workspace and GitHub maintainer capability for the connected project.
 
-```bash
-npx @theagilemonkeys/facility login --url https://facility.example.com --key fak_…
-npx @theagilemonkeys/facility status      # runs, approvals, issues and spend at a glance
-npx @theagilemonkeys/facility inbox       # review and decide pending proposals
-npx @theagilemonkeys/facility sessions    # trigger, watch, steer or cancel agent runs
+Init creates `architect`, `builder`, `pr-reviewer`, `address-review`,
+`ci-doctor`, and `security-audit`. Model flags customize the initial templates:
+
+```text
+--build-model=<id>        --review-model=<id>
+--plan-model=<id>         --codex-build-model=<id>
+--codex-plan-model=<id>
 ```
 
-Platform commands take a global `--json`, `--profile <name>` and
-`--timeout <seconds>`, so the CLI is as usable from a script as from a prompt.
-It speaks the same versioned REST API and obeys the same permissions as the web
-application: what your key cannot do, the CLI will not do either.
+Use `--dir=<path>` to configure another checkout. Existing targets are
+preserved independently; `--force` overwrites only `.facility.yml` and those
+six agent files. Review them before using force because they are project-owned
+configuration.
+
+## Validate locally
 
-## Installing the process into a repository
+`doctor` checks the seven-file contract locally. It never connects to a
+Facility instance and supports machine-readable output with `--json`.
 
 ```bash
-cd your-repository
-npx @theagilemonkeys/facility init
-npx @theagilemonkeys/facility doctor --run-guards --github
+npx @theagilemonkeys/facility doctor --json
 ```
 
-`init` asks about the package manager, the default branch, the commands that
-provision an environment and verify a change, then writes GitHub workflows for
-planning, building, reviewing and repairing, plus `STANDARD.md`, agent
-instructions, skills, deterministic guards, and a `.facility.json` recording the
-answers. It never overwrites an existing generated file unless you pass
-`--force`, and it appends to `AGENTS.md` and `CLAUDE.md` inside a delimited
-managed block rather than replacing them.
+Doctor provides fast local feedback; the server's strict manifest parsers and
+a real disposable workspace remain authoritative for runtime acceptance.
+
+## Bootstrap an instance
 
-This is the second step, not the entry price: a repository connected to a
-Facility platform is operated entirely from the platform, without a single file
-being added to it.
+Instance operators can create the first organization, owner, and GitHub App
+installation with `facility instance bootstrap`. See the
+[Facility documentation](https://github.com/theam/facility/tree/main/apps/docs/docs)
+for deployment and MCP setup.
 
-## Documentation
+Bootstrap requires `DATABASE_URL` and explicit organization, owner GitHub
+identity, account, and installation values. It is safe to repeat only with the
+exact same binding and refuses a different binding when instance data exists.
+Run `facility instance bootstrap --help` for the full command.
 
-- [CLI reference](https://github.com/theam/facility/blob/main/apps/docs/docs/reference/cli.md)
-- [Self-hosting guide](https://github.com/theam/facility/blob/main/apps/docs/docs/self-host/quickstart.md)
-- [Repository and issues](https://github.com/theam/facility)
+Facility 0.x is early software and does not promise in-place database upgrades
+between minor versions. Facility 0.12 specifically requires a new database
+rather than a 0.11 in-place migration.
 
-Apache-2.0 · an initiative by [The Agile Monkeys](https://theagilemonkeys.com)
+Apache-2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theagilemonkeys/facility",
-  "version": "0.11.3",
-  "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.",
+  "version": "0.12.0",
+  "description": "Create and validate Facility 0.12 repository workspace and agent manifests.",
   "keywords": [
     "ai",
     "agents",
@@ -27,8 +27,7 @@
   "files": [
     "bin",
     "src",
-    "templates",
-    "modules"
+    "templates"
   ],
   "engines": {
     "node": "^22.13.0 || ^24.0.0"

package/src/cli.mjs

@@ -1,12 +1,10 @@
-// facility CLI entry: init · add · doctor.
+// Facility 0.12 CLI entry: repository kickstart, validation, and instance bootstrap.
 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)), "..");
@@ -20,7 +18,7 @@ function parseFlags(args) {
     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 === "--help") flags.help = true;
     else if (arg.startsWith("--") && arg.includes("=")) {
       const [key, ...rest] = arg.slice(2).split("=");
       flags[key] = rest.join("=");
@@ -38,63 +36,21 @@ function parseFlags(args) {
 
 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("Configure a repository", [
+    ["init", "write .facility.yml and the .agents catalog"],
+    ["doctor", "verify the workspace contract"],
   ]);
-  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"],
+  item(dim("Run stories through Facility's MCP server or web UI."));
+  console.log("");
+  helpGroup("Instance administration", [
+    ["instance bootstrap", "create the first organization, owner, and GitHub installation"],
   ]);
   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("init flags: --yes --force --dir=<path> --repo=<owner/name> --provision=<cmd> --start=<cmd>"));
+  item(dim("            --service-port=<n> --preview-readiness-command=<cmd>"));
   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('            --codex-build-model=<id> --codex-plan-model=<id>'));
   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("");
@@ -121,7 +77,7 @@ export async function main(argv) {
   }
   if (flags.dir) flags.dir = resolve(flags.dir);
 
-  if (flags.help && ["init", "add", "doctor"].includes(command)) {
+  if (flags.help && ["init", "doctor"].includes(command)) {
     localHelp(command);
     return 0;
   }
@@ -129,56 +85,12 @@ export async function main(argv) {
   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);
@@ -198,40 +110,20 @@ function validateLocalFlags(command, flags) {
       "yes",
       "force",
       "dir",
-      "branch",
       "provision",
-      "checks",
-      "project",
+      "start",
+      "repo",
+      "service-port",
+      "preview-readiness-command",
       "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",
     ]),
+    doctor: new Set(["dir", "json", "help"]),
     instance: new Set([
       "org-name",
       "org-slug",
@@ -254,29 +146,23 @@ function validateLocalFlags(command, flags) {
   }
   const valueNames =
     command === "doctor"
-      ? ["dir", "profile", "url", "key", "timeout"]
+      ? ["dir"]
       : command === "instance"
         ? [...allowed].filter((name) => !["json", "help"].includes(name))
         : command === "init"
         ? [
             "dir",
-            "branch",
             "provision",
-            "checks",
-            "project",
+            "start",
+            "repo",
+            "service-port",
+            "preview-readiness-command",
             "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) {
@@ -284,29 +170,10 @@ function validateLocalFlags(command, flags) {
       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`;
@@ -315,34 +182,18 @@ function validateLocalFlags(command, flags) {
 }
 
 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)] };
+  return { command: argv[0], rest: argv.slice(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.",
+      "Detect the repository and install .facility.yml plus the shared .agents catalog.",
     ],
     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.",
+      "facility doctor [--dir <path>] [--json]",
+      "Verify the repository's .facility.yml and .agents catalog.",
     ],
   };
   const [usage, description] = lines[command];

package/src/detect.mjs

@@ -1,7 +1,5 @@
-// Stack detection: read the target repo and propose sensible defaults so
-// `init` asks six short questions instead of twenty.
-import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 function readJson(path) {
@@ -14,7 +12,11 @@ function readJson(path) {
 
 function git(cwd, args) {
   try {
-    return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return execFileSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
   } catch {
     return "";
   }
@@ -23,105 +25,33 @@ function git(cwd, args) {
 export function detect(dir) {
   const pkg = readJson(join(dir, "package.json"));
   const scripts = pkg?.scripts ?? {};
-
   const packageManager = existsSync(join(dir, "pnpm-lock.yaml"))
     ? "pnpm"
     : existsSync(join(dir, "yarn.lock"))
       ? "yarn"
-      : existsSync(join(dir, "package-lock.json"))
+      : existsSync(join(dir, "package-lock.json")) || pkg
         ? "npm"
-        : pkg
-          ? "npm"
-          : "none";
-
-  const runner = packageManager === "none" ? null : packageManager === "npm" ? "npm run" : `${packageManager} run`;
-  const checks = [];
-  if (runner) {
-    for (const name of ["typecheck", "lint", "test", "build"]) {
-      if (scripts[name]) checks.push(`${runner} ${name}`);
-    }
-  }
-
-  const provision = runner && scripts["setup"] ? `${runner} setup` : "";
-
-  const isGitRepo = git(dir, ["rev-parse", "--is-inside-work-tree"]) === "true";
-  let defaultBranch = "main";
-  const originHead = git(dir, ["symbolic-ref", "refs/remotes/origin/HEAD"]);
-  if (originHead) defaultBranch = originHead.replace("refs/remotes/origin/", "");
-  else {
-    const current = git(dir, ["branch", "--show-current"]);
-    if (current) defaultBranch = current;
-  }
-
-  let org = "";
+        : "none";
+  const runner =
+    packageManager === "none" ? null : packageManager === "npm" ? "npm run" : `${packageManager} run`;
+  const provision = runner && scripts.setup ? `${runner} setup` : "";
+  const start =
+    existsSync(join(dir, "compose.yml")) || existsSync(join(dir, "docker-compose.yml"))
+      ? "docker compose up -d"
+      : runner && scripts.dev
+        ? `${runner} dev`
+        : runner && scripts.start
+          ? `${runner} start`
+          : "";
   const remote = git(dir, ["remote", "get-url", "origin"]);
-  const remoteMatch = remote.match(/[/:]([^/:]+)\/([^/]+?)(\.git)?$/);
-  if (remoteMatch) org = remoteMatch[1];
-
-  const migrationDirs = ["migrations", "supabase/migrations", "db/migrations", "prisma/migrations"].filter((d) =>
-    existsSync(join(dir, d))
-  );
-
-  // Existing check workflows (by their `name:`), so the doctor knows what to
-  // watch. Facility's own workflows are excluded — the watchtower covers them.
-  const workflowNames = [];
-  const deploymentProviders = new Set();
-  try {
-    for (const file of readdirSync(join(dir, ".github/workflows"))) {
-      if (!/\.ya?ml$/.test(file) || file.startsWith("facility-")) continue;
-      const workflow = readFileSync(join(dir, ".github/workflows", file), "utf8");
-      const nameMatch = workflow.match(/^name:\s*["']?([^"'\n]+)["']?\s*$/m);
-      if (nameMatch) workflowNames.push(nameMatch[1].trim());
-      detectDeploymentProvider(workflow, deploymentProviders);
-    }
-  } catch {}
-  if (existsSync(join(dir, "vercel.json"))) deploymentProviders.add("vercel");
-  if (existsSync(join(dir, "netlify.toml"))) deploymentProviders.add("netlify");
-  if (existsSync(join(dir, "fly.toml"))) deploymentProviders.add("fly.io");
-  if (existsSync(join(dir, "render.yaml"))) deploymentProviders.add("render");
-  if (existsSync(join(dir, "Dockerfile"))) deploymentProviders.add("container-image");
-  const board = detectBoard(dir, org);
-  const facility = readJson(join(dir, ".facility.json"));
+  const match = remote.match(/[/:]([^/:]+)\/([^/]+?)(\.git)?$/);
 
   return {
-    isGitRepo,
-    defaultBranch,
+    isGitRepo: git(dir, ["rev-parse", "--is-inside-work-tree"]) === "true",
     packageManager,
-    checks,
     provision,
-    org,
-    workflowNames,
-    deploymentProviders: [...deploymentProviders].sort(),
-    board,
-    previewConfigured: facility?.preview?.enabled === true,
-    suggestedModules: migrationDirs.length ? ["database"] : [],
-    existing: {
-      agentsMd: existsSync(join(dir, "AGENTS.md")),
-      claudeMd: existsSync(join(dir, "CLAUDE.md")),
-      claudeSettings: existsSync(join(dir, ".claude/settings.json")),
-      standard: existsSync(join(dir, "STANDARD.md")),
-    },
+    start,
+    org: match?.[1] ?? "",
+    repository: match ? `${match[1]}/${match[2]}` : "",
   };
 }
-
-function detectDeploymentProvider(content, providers) {
-  const lower = content.toLowerCase();
-  if (lower.includes("vercel")) providers.add("vercel");
-  if (lower.includes("netlify")) providers.add("netlify");
-  if (lower.includes("flyctl") || lower.includes("fly.io")) providers.add("fly.io");
-  if (lower.includes("cloudflare") || lower.includes("wrangler")) providers.add("cloudflare");
-  if (lower.includes("amazon-ecr") || lower.includes("amazon-ecs")) providers.add("aws");
-  if (lower.includes("render.com")) providers.add("render");
-}
-
-function detectBoard(dir, fallbackOrg) {
-  for (const path of ["AGENTS.md", "CLAUDE.md", "README.md"]) {
-    try {
-      const match = readFileSync(join(dir, path), "utf8").match(
-        /github\.com\/orgs\/([^/\s]+)\/projects\/(\d+)/i,
-      );
-      if (match?.[2]) return { org: match[1] || fallbackOrg, project: Number(match[2]) };
-    } catch {}
-  }
-  return null;
-}