facult 2.4.0 → 2.5.1

package/README.md

@@ -282,6 +282,8 @@ bunx fclt index
 
 This seeds `<repo>/.ai` from the built-in Facult operating-model pack and writes a merged project index/graph under `<repo>/.ai/.facult/ai/`.
 
+Wide learning-review automations should use this same bootstrap when they hit a local writable repo with durable project-local signal but no repo-local `.ai` yet.
+
 ### 4. Inspect what you have
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.4.0",
+  "version": "2.5.1",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",

package/src/adapters/factory.ts

@@ -0,0 +1,228 @@
+import { basename, extname } from "node:path";
+import { renderCanonicalText } from "../agents";
+import { generateMcpConfig, parseMcpConfig } from "./mcp";
+import { parseSkillsDir } from "./skills";
+import type {
+  CanonicalMcpConfig,
+  CanonicalMcpServer,
+  ParsedManagedAgentFile,
+  RenderManagedAgentOptions,
+  ToolAdapter,
+} from "./types";
+import { detectExplicitVersion } from "./version";
+
+const FRONTMATTER_LINE_SPLIT_REGEX = /\r?\n/;
+const FACTORY_AGENT_FRONTMATTER_REGEX =
+  /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const LEADING_WHITESPACE_REGEX = /^\s+/;
+const TRAILING_WHITESPACE_REGEX = /\s+$/;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function escapeTomlMultiline(value: string): string {
+  return value.replace(/"""/g, '\\"""');
+}
+
+function escapeYamlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+function stringifyFrontmatter(values: Record<string, string>): string {
+  return Object.entries(values)
+    .map(([key, value]) => `${key}: ${escapeYamlString(value)}`)
+    .join("\n");
+}
+
+function parseFrontmatterScalar(value: string): string {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    const quote = trimmed[0];
+    const inner = trimmed.slice(1, -1);
+    if (quote === '"') {
+      try {
+        return JSON.parse(trimmed);
+      } catch {
+        return inner;
+      }
+    }
+    return inner;
+  }
+  return trimmed;
+}
+
+function parseFrontmatter(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of text.split(FRONTMATTER_LINE_SPLIT_REGEX)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const separator = trimmed.indexOf(":");
+    if (separator === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, separator).trim();
+    const value = parseFrontmatterScalar(trimmed.slice(separator + 1));
+    if (key) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function normalizeFactoryServer(
+  server: CanonicalMcpServer
+): CanonicalMcpServer {
+  if (!isPlainObject(server.vendorExtensions)) {
+    return server;
+  }
+
+  const { type, ...vendorExtensions } = server.vendorExtensions;
+  return {
+    ...server,
+    transport:
+      typeof type === "string" && !server.transport ? type : server.transport,
+    vendorExtensions:
+      Object.keys(vendorExtensions).length > 0 ? vendorExtensions : undefined,
+  };
+}
+
+function parseFactoryMcp(config: unknown): CanonicalMcpConfig {
+  const parsed = parseMcpConfig(config);
+  for (const [name, server] of Object.entries(parsed.servers)) {
+    parsed.servers[name] = normalizeFactoryServer({ ...server });
+  }
+  return parsed;
+}
+
+function generateFactoryMcp(
+  canonical: CanonicalMcpConfig
+): Record<string, unknown> {
+  const generated = generateMcpConfig(canonical, "mcpServers");
+  const servers = generated.mcpServers;
+  if (!isPlainObject(servers)) {
+    return generated;
+  }
+
+  for (const [name, value] of Object.entries(servers)) {
+    if (!isPlainObject(value)) {
+      continue;
+    }
+    const { transport, ...server } = value as Record<string, unknown>;
+    const inferredType =
+      (typeof transport === "string" ? transport : undefined) ??
+      (typeof server.url === "string"
+        ? "http"
+        : typeof server.command === "string"
+          ? "stdio"
+          : undefined);
+    if (inferredType && typeof server.type !== "string") {
+      server.type = inferredType;
+    }
+    if (typeof server.disabled !== "boolean") {
+      server.disabled = false;
+    }
+    servers[name] = server;
+  }
+
+  return generated;
+}
+
+async function renderFactoryAgent(
+  options: RenderManagedAgentOptions
+): Promise<string> {
+  const parsed = Bun.TOML.parse(options.raw) as Record<string, unknown>;
+  const name =
+    typeof parsed.name === "string"
+      ? parsed.name
+      : basename(options.targetPath, extname(options.targetPath));
+  const description =
+    typeof parsed.description === "string" ? parsed.description : undefined;
+  const instructions =
+    typeof parsed.developer_instructions === "string"
+      ? parsed.developer_instructions
+      : "";
+  const renderedInstructions = await renderCanonicalText(instructions, {
+    homeDir: options.homeDir,
+    rootDir: options.rootDir,
+    projectRoot: options.projectRoot,
+    targetTool: options.tool,
+    targetPath: options.targetPath,
+  });
+
+  const frontmatter = stringifyFrontmatter({
+    name,
+    ...(description ? { description } : {}),
+    model: "inherit",
+  });
+  const body = renderedInstructions.trim();
+
+  return body
+    ? `---\n${frontmatter}\n---\n\n${body}\n`
+    : `---\n${frontmatter}\n---\n`;
+}
+
+async function parseFactoryManagedAgentFile(
+  path: string
+): Promise<ParsedManagedAgentFile | null> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    return null;
+  }
+
+  const raw = await file.text();
+  const match = raw.match(FACTORY_AGENT_FRONTMATTER_REGEX);
+  if (!match) {
+    return null;
+  }
+
+  const [, frontmatterRaw, bodyRaw] = match;
+  const frontmatter = parseFrontmatter(frontmatterRaw ?? "");
+  const name = frontmatter.name || basename(path, extname(path));
+  const description = frontmatter.description || undefined;
+  const body = (bodyRaw ?? "")
+    .replace(LEADING_WHITESPACE_REGEX, "")
+    .replace(TRAILING_WHITESPACE_REGEX, "");
+  const lines = [`name = ${JSON.stringify(name)}`];
+  if (description) {
+    lines.push(`description = ${JSON.stringify(description)}`);
+  }
+  lines.push("", 'developer_instructions = """');
+  if (body) {
+    lines.push(escapeTomlMultiline(body));
+  }
+  lines.push('"""', "");
+
+  return {
+    name,
+    raw: lines.join("\n"),
+    sourcePath: path,
+  };
+}
+
+export const factoryAdapter: ToolAdapter = {
+  id: "factory",
+  name: "Factory",
+  versions: ["v1"],
+  detectVersion: detectExplicitVersion,
+  getDefaultPaths: () => ({
+    mcp: "~/.factory/mcp.json",
+    skills: ["~/.factory/skills", ".factory/skills"],
+    agents: ["~/.factory/droids", ".factory/droids"],
+  }),
+  parseMcp: (config) => parseFactoryMcp(config),
+  generateMcp: (canonical) => generateFactoryMcp(canonical),
+  parseSkills: async (skillsDir) => await parseSkillsDir(skillsDir),
+  agentFileExtension: ".md",
+  renderAgent: async (options) => await renderFactoryAgent(options),
+  parseManagedAgentFile: async (path) =>
+    await parseFactoryManagedAgentFile(path),
+};

package/src/adapters/index.ts

@@ -3,6 +3,7 @@ import { claudeDesktopAdapter } from "./claude-desktop";
 import { clawdbotAdapter } from "./clawdbot";
 import { codexAdapter } from "./codex";
 import { cursorAdapter } from "./cursor";
+import { factoryAdapter } from "./factory";
 import { referenceAdapter } from "./reference";
 import type { ResolveVersionOptions, ToolAdapter } from "./types";
 
@@ -64,6 +65,7 @@ export async function resolveAdapterVersion(
 registerAdapter(referenceAdapter);
 registerAdapter(cursorAdapter);
 registerAdapter(codexAdapter);
+registerAdapter(factoryAdapter);
 registerAdapter(claudeCliAdapter);
 registerAdapter(claudeDesktopAdapter);
 registerAdapter(clawdbotAdapter);

package/src/adapters/types.ts

@@ -18,6 +18,21 @@ export interface CanonicalSkill {
   path?: string;
 }
 
+export interface RenderManagedAgentOptions {
+  raw: string;
+  rootDir: string;
+  tool: string;
+  targetPath: string;
+  homeDir?: string;
+  projectRoot?: string;
+}
+
+export interface ParsedManagedAgentFile {
+  name: string;
+  raw: string;
+  sourcePath: string;
+}
+
 export interface AdapterDefaultPaths {
   mcp?: string;
   skills?: string | string[];
@@ -34,6 +49,13 @@ export interface ToolAdapter {
   parseSkills?: (skillsDir: string) => Promise<CanonicalSkill[]>;
   generateMcp?: (canonical: CanonicalMcpConfig, version?: string) => unknown;
   generateSkillsDir?: (skills: CanonicalSkill[]) => Promise<void>;
+  agentFileExtension?: string;
+  renderAgent?: (
+    options: RenderManagedAgentOptions
+  ) => Promise<string> | string;
+  parseManagedAgentFile?: (
+    path: string
+  ) => Promise<ParsedManagedAgentFile | null>;
   getDefaultPaths?: () => AdapterDefaultPaths;
 }
 

package/src/cli-context.ts

@@ -16,6 +16,11 @@ export interface ParsedCliContext {
   sourceKind?: AssetSourceKind;
 }
 
+function missingProjectAiRootMessage(pathValue?: string): string {
+  const suffix = pathValue ? `: ${pathValue}` : "";
+  return `No project-local .ai root found${suffix}. Run "fclt templates init project-ai" in the repo first, or pass --root <repo>/.ai.`;
+}
+
 function expandHomePath(pathValue: string, home: string): string {
   if (pathValue === "~") {
     return home;
@@ -173,9 +178,7 @@ export function resolveCliContextRoot(args?: {
   if (args?.rootArg) {
     const rootDir = coerceCanonicalRoot(args.rootArg, homeDir);
     if (scope === "project" && !projectRootFromAiRoot(rootDir, homeDir)) {
-      throw new Error(
-        `Project scope requires a repo-local .ai root: ${rootDir}`
-      );
+      throw new Error(missingProjectAiRootMessage(rootDir));
     }
     return rootDir;
   }
@@ -187,9 +190,7 @@ export function resolveCliContextRoot(args?: {
   if (scope === "project") {
     const projectRoot = findNearestProjectAiRoot(cwd);
     if (!projectRoot) {
-      throw new Error(
-        "No project-local .ai root found from the current directory"
-      );
+      throw new Error(missingProjectAiRootMessage(cwd));
     }
     return projectRoot;
   }

package/src/index-builder.ts

@@ -1,6 +1,7 @@
 import { mkdir, readdir } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
+import { getAdapter } from "./adapters";
 import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
 import {
   type AssetScope,
@@ -31,6 +32,10 @@ interface AssetEntryBase {
   shadow?: boolean;
 }
 
+function managedAgentFileExtension(tool: string): string {
+  return getAdapter(tool)?.agentFileExtension ?? ".toml";
+}
+
 export interface SkillEntry {
   name: string;
   path: string;
@@ -1213,6 +1218,7 @@ function registerManagedRenderedTargets(args: {
   const nodes = args.graph.nodes;
   for (const toolState of toolStates) {
     if (toolState.agentsDir) {
+      const extension = managedAgentFileExtension(toolState.tool);
       for (const entry of Object.values(args.index.agents)) {
         const sourceNodeId = sourceNodeIdForEntry({
           kind: "agent",
@@ -1221,7 +1227,10 @@ function registerManagedRenderedTargets(args: {
         if (!nodes[sourceNodeId]) {
           continue;
         }
-        const targetPath = join(toolState.agentsDir, `${entry.name}.toml`);
+        const targetPath = join(
+          toolState.agentsDir,
+          `${entry.name}${extension}`
+        );
         registerRenderedTargetNode({
           graph: args.graph,
           currentScope: args.currentScope,

package/src/manage.ts

@@ -203,6 +203,19 @@ function defaultToolPaths(
       skillsDir: toolBase(".antigravity", "skills"),
       mcpConfig: toolBase(".antigravity", "mcp.json"),
     },
+    factory: {
+      tool: "factory",
+      skillsDir: projectRoot
+        ? join(projectRoot, ".factory", "skills")
+        : homePath(home, ".factory", "skills"),
+      mcpConfig: projectRoot
+        ? join(projectRoot, ".factory", "mcp.json")
+        : homePath(home, ".factory", "mcp.json"),
+      agentsDir: projectRoot
+        ? join(projectRoot, ".factory", "droids")
+        : homePath(home, ".factory", "droids"),
+      toolHome: projectRoot ? undefined : homePath(home, ".factory"),
+    },
   };
 
   const adapterDefaults = (tool: string): ToolPaths | null => {
@@ -436,6 +449,69 @@ async function loadCanonicalAgents(
   return await loadAgentsFromRoot(homePath(rootDir, "agents"));
 }
 
+function managedAgentFileExtension(tool: string): string {
+  return getAdapter(tool)?.agentFileExtension ?? ".toml";
+}
+
+async function renderManagedAgentFile(args: {
+  agent: { name: string; sourcePath: string; raw: string };
+  homeDir: string;
+  rootDir: string;
+  tool: string;
+  targetPath: string;
+}): Promise<string> {
+  const adapter = getAdapter(args.tool);
+  if (adapter?.renderAgent) {
+    return await adapter.renderAgent({
+      raw: args.agent.raw,
+      homeDir: args.homeDir,
+      rootDir: args.rootDir,
+      projectRoot:
+        projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
+      tool: args.tool,
+      targetPath: args.targetPath,
+    });
+  }
+
+  return await renderCanonicalText(args.agent.raw, {
+    homeDir: args.homeDir,
+    rootDir: args.rootDir,
+    projectRoot: projectRootFromAiRoot(args.rootDir, args.homeDir) ?? undefined,
+    targetTool: args.tool,
+    targetPath: args.targetPath,
+  });
+}
+
+async function loadManagedAgentsFromTool(args: {
+  tool: string;
+  agentsDir: string;
+}): Promise<{ name: string; sourcePath: string; raw: string }[]> {
+  const adapter = getAdapter(args.tool);
+  if (!adapter?.parseManagedAgentFile) {
+    return await loadAgentsFromRoot(args.agentsDir);
+  }
+
+  const extension = managedAgentFileExtension(args.tool);
+  const entries = await readdir(args.agentsDir, { withFileTypes: true }).catch(
+    () => [] as import("node:fs").Dirent[]
+  );
+  const out: { name: string; sourcePath: string; raw: string }[] = [];
+
+  for (const entry of entries) {
+    if (!(entry.isFile() && entry.name.endsWith(extension))) {
+      continue;
+    }
+    const sourcePath = join(args.agentsDir, entry.name);
+    const parsed = await adapter.parseManagedAgentFile(sourcePath);
+    if (!parsed) {
+      continue;
+    }
+    out.push(parsed);
+  }
+
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
 interface AutomationEntry {
   name: string;
   sourceDir: string;
@@ -637,14 +713,15 @@ async function planAgentFileChanges({
   const contents = new Map<string, string>();
   const sources = new Map<string, string>();
   const desiredPaths = new Set<string>();
+  const extension = managedAgentFileExtension(tool);
 
   for (const agent of agents) {
-    const target = homePath(agentsDir, `${agent.name}.toml`);
-    const rendered = await renderCanonicalText(agent.raw, {
+    const target = homePath(agentsDir, `${agent.name}${extension}`);
+    const rendered = await renderManagedAgentFile({
+      agent,
       homeDir,
       rootDir,
-      projectRoot: projectRootFromAiRoot(rootDir, homeDir) ?? undefined,
-      targetTool: tool,
+      tool,
       targetPath: target,
     });
     desiredPaths.add(target);
@@ -659,7 +736,7 @@ async function planAgentFileChanges({
   const remove = new Set<string>();
 
   for (const entry of existing) {
-    if (!(entry.isFile() && entry.name.endsWith(".toml"))) {
+    if (!(entry.isFile() && entry.name.endsWith(extension))) {
       continue;
     }
     const p = homePath(agentsDir, entry.name);
@@ -1214,11 +1291,15 @@ function logManagedImportPlan(tool: string, plan: ExistingManagedImportPlan) {
 }
 
 async function planExistingToolAgentAdoption(args: {
+  tool: string;
   rootDir: string;
   agentsDir: string;
 }): Promise<ExistingManagedImportPlan> {
   const plan = emptyManagedImportPlan();
-  const agents = await loadAgentsFromRoot(args.agentsDir);
+  const agents = await loadManagedAgentsFromTool({
+    tool: args.tool,
+    agentsDir: args.agentsDir,
+  });
   for (const agent of agents) {
     const canonicalPath = join(
       args.rootDir,
@@ -1245,12 +1326,16 @@ async function planExistingToolAgentAdoption(args: {
 }
 
 async function adoptExistingToolAgents(args: {
+  tool: string;
   rootDir: string;
   agentsDir: string;
   conflictMode: "keep-canonical" | "keep-existing";
 }): Promise<ExistingManagedItem[]> {
   const adopted: ExistingManagedItem[] = [];
-  const agents = await loadAgentsFromRoot(args.agentsDir);
+  const agents = await loadManagedAgentsFromTool({
+    tool: args.tool,
+    agentsDir: args.agentsDir,
+  });
   for (const agent of agents) {
     const canonicalPath = join(
       args.rootDir,
@@ -2019,6 +2104,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
     asManagedSkillPlan(existingSkillPlan),
     toolPaths.agentsDir
       ? await planExistingToolAgentAdoption({
+          tool,
           rootDir,
           agentsDir: toolPaths.agentsDir,
         })
@@ -2142,6 +2228,7 @@ export async function manageTool(tool: string, opts: ManageOptions = {}) {
   }
   if (toolPaths.agentsDir && opts.adoptExisting) {
     const result = await adoptExistingToolAgents({
+      tool,
       rootDir,
       agentsDir: toolPaths.agentsDir,
       conflictMode: importConflictMode,
@@ -3006,6 +3093,7 @@ async function repairManagedCanonicalContent(args: {
 
   if (args.entry.agentsBackup) {
     const items = await adoptExistingToolAgents({
+      tool: args.entry.tool,
       rootDir: args.rootDir,
       agentsDir: args.entry.agentsBackup,
       conflictMode: "keep-canonical",

package/src/remote.ts

@@ -341,7 +341,7 @@ Use this memory for pattern continuity:
 - For wide reviews, partition evidence by cwd first; do not let one repo's evidence stand in for another.
 - Grounding: prefer evidence from session messages, tool calls, shell commands, diffs, tests, commits, and touched files.
 - Threshold: only encode signal when you can name what was learned, why it matters, and the most plausible destination.
-- Scope: default to project writeback unless the signal clearly belongs in global doctrine or a shared capability.
+- Scope: default to project writeback only when the repo has a project-local \`.ai\` root. If a local writable repo is missing one, bootstrap baseline project AI state with \`fclt templates init project-ai\` before retrying project-scoped writeback. If bootstrap fails or the repo is not writable, treat that as the blocker instead of silently falling back to global runtime state.
 - Promote to global only when the same signal appears across multiple repos or clearly targets shared doctrine, shared agents, or shared skills.
 - Verification: distinguish one-off friction from a repeated pattern before escalating it.
 - If available, use [$feedback-loop-setup]({{feedbackLoopSkill}}) when the review needs stronger feedback loops or verification framing.
@@ -367,6 +367,8 @@ Grounding rules:
 
 Decision rules:
 - Use \`fclt ai writeback add\` when the signal, target asset, and scope are clear.
+- Before attempting project-scoped writeback, verify the cwd has a repo-local \`.ai\` root. If it does not and the cwd is a local writable repo, run \`fclt templates init project-ai\` from that repo root, then continue. If bootstrap fails or the repo is not writable, report the writeback as blocked by missing project AI state rather than falling back to merged/global runtime state.
+- Before passing \`--asset\`, verify the target resolves in the Facult graph. If the destination is a raw file path or otherwise not graph-backed, report that as a missing-asset blocker instead of retrying blind.
 - Use \`fclt ai evolve\` only when repeated signal is strong enough to justify a reviewable capability change.
 - Prefer project scope unless the learning clearly belongs in shared global doctrine, shared agents, shared skills, or other cross-project capability.
 - For wide automations, require repeated evidence across more than one cwd before recommending a global/shared capability change unless the target is obviously global.

package/src/scan.ts

@@ -601,6 +601,19 @@ function defaultSourceSpecs(
         "~/.codex/mcp.json",
       ],
     },
+    {
+      id: "factory",
+      name: "Factory",
+      candidates: ["~/.factory", "~/.factory/mcp.json"],
+      skillDirs: ["~/.factory/skills"],
+      configFiles: ["~/.factory/mcp.json"],
+      assets: [
+        {
+          kind: "agents-instructions",
+          patterns: ["~/.factory/AGENTS.md"],
+        },
+      ],
+    },
     {
       id: "claude",
       name: "Claude (CLI)",
@@ -784,6 +797,13 @@ function defaultSourceSpecs(
         },
       ],
     },
+    {
+      id: "factory-project",
+      name: "Factory (project)",
+      candidates: [join(cwd, ".factory")],
+      skillDirs: [join(cwd, ".factory", "skills")],
+      configFiles: [join(cwd, ".factory", "mcp.json")],
+    },
   ];
 
   if (includeGitHooks) {
@@ -1288,7 +1308,12 @@ async function buildFromRootResult(args: {
         }
         continue;
       }
-      if (name === ".codex" || name === ".agents" || name === ".clawdbot") {
+      if (
+        name === ".codex" ||
+        name === ".agents" ||
+        name === ".clawdbot" ||
+        name === ".factory"
+      ) {
         await scanToolDotDir(child);
         continue;
       }