facult 2.14.0 → 2.15.1

package/README.md

@@ -15,10 +15,6 @@
   </a>
 </div>
 
-<p align="center">
-  <img alt="fclt demo" src="./Ghostty.gif">
-</p>
-
 `fclt` is a CLI for managing AI capability across tools and projects.
 
 It gives instructions, snippets, skills, agents, MCP definitions, automations, and tool config a shared home. It can inspect what already exists, consolidate duplicates, render selected capability into tools like Codex and Claude, and preserve real-work friction as writeback that can later become reviewed improvements.
@@ -143,6 +139,8 @@ fclt templates init operating-model --global
 fclt index --global
 ```
 
+On first install, `fclt` seeds `AGENTS.global.md` from existing global agent docs such as `~/.codex/AGENTS.md` or `~/.claude/CLAUDE.md` when they exist, then appends the Facult operating-model frame. The packaged template is only the fallback.
+
 Refresh an existing operating-model pack without overwriting local edits:
 
 ```bash
@@ -219,7 +217,7 @@ Canonical capability can include:
 - `mcp/`: MCP server definitions and overlays
 - `automations/`: scheduled review loops
 - `tools/<tool>/`: tool config and rules
-- `AGENTS.global.md`: composed agent guidance
+- `snippets/templates/agents-global.md`: source template materialized as `AGENTS.global.md`
 
 Refs let markdown point at canonical assets without hard-coding paths:
 
@@ -418,6 +416,7 @@ Start with:
 - [Project `.ai`](./docs/project-ai.md): repo-owned capability and project sync policy
 - [Built-in pack](./docs/built-in-pack.md): packaged work-unit, writeback, and evolution defaults
 - [Built-in pack upgrades](./docs/pack-upgrades.md): non-destructive refresh behavior for existing `.ai` roots
+- [Codex plugin](./docs/codex-plugin.md): installable Codex skills and MCP tools for fclt workflows
 - [Writeback and evolution](./docs/writeback-evolution.md): the feedback-loop workflow and review surfaces
 - [Managed mode](./docs/managed-mode.md): when to let `fclt` write tool files
 - [Roadmap](./docs/roadmap.md): current gaps and planned work
@@ -426,7 +425,7 @@ Start with:
 
 ### Does fclt run an MCP server?
 
-Not yet as a first-party runtime. Today, `fclt` is CLI-first. You can scaffold MCP definitions that delegate to the CLI, and a dedicated plugin/MCP surface is on the roadmap.
+The core product is still CLI-first. The first-party Codex plugin includes a small stdio MCP wrapper that delegates to the installed `fclt` binary for status, doctor, paths, setup, writeback, and evolution workflows. See [Codex plugin](./docs/codex-plugin.md).
 
 ### Does fclt have to manage Codex or Claude files?
 

package/assets/packs/facult-operating-model/{AGENTS.global.md → snippets/templates/agents-global.md}

@@ -1,9 +1,9 @@
 # Global Agent Instructions
 
-This file is the global entry template for the operating-model pack. It should
-stay small and composed from snippets. Put detailed doctrine in instructions,
-workflow execution in skills, and local/private preferences in user-owned or
-project-owned assets outside the public pack.
+This template materializes as `AGENTS.global.md` when the operating-model pack is
+installed. It should stay small and composed from snippets. Put detailed
+doctrine in instructions, workflow execution in skills, and local/private
+preferences in user-owned or project-owned assets outside the public pack.
 
 ## Working mode
 

package/docs/README.md

@@ -14,6 +14,7 @@ The concepts guide includes the [feedback-loop diagram](./assets/fclt-capability
 - [Project `.ai`](./project-ai.md): how repo-local capability works without leaking project review state into the repo.
 - [Built-in pack](./built-in-pack.md): the packaged operating-model layer for writeback and evolution.
 - [Built-in pack upgrades](./pack-upgrades.md): non-destructive refresh behavior for existing `.ai` roots.
+- [Codex plugin](./codex-plugin.md): installable Codex skills and MCP tools for fclt workflows.
 - [Writeback and evolution](./writeback-evolution.md): how real-work friction becomes reviewable capability changes.
 - [Managed mode](./managed-mode.md): when to let `fclt` write tool files, and how adoption works.
 - [Security and trust](./security-trust.md): source trust, audit, secrets, and commit hygiene.

package/docs/built-in-pack.md

@@ -31,11 +31,19 @@ Agents:
 - `scope-promoter`
 - `integration-auditor`
 
-Global doc:
+Entry template:
 
-- `AGENTS.global.md`
+- `snippets/templates/agents-global.md`
 
-`AGENTS.global.md` is the composed entry template for global agent guidance. It should stay small and point to snippets and instructions rather than becoming the only place where guidance lives.
+The template materializes as `AGENTS.global.md` when installed into a canonical `.ai` root. The source lives under snippets/templates so the pack itself models composition instead of treating the root global doc as a special hand-maintained asset. The installed `AGENTS.global.md` should stay small and point to snippets and instructions rather than becoming the only place where guidance lives.
+
+On first install, `fclt` preserves existing guidance when it can:
+
+- global installs seed `AGENTS.global.md` from existing global agent docs such as `~/.codex/AGENTS.md` or `~/.claude/CLAUDE.md`
+- project installs seed from the repo's existing `AGENTS.md` or `CLAUDE.md`
+- the packaged template is only the fallback when no existing guidance is found
+
+Seeded `AGENTS.global.md` files are treated as user-owned. They are not marked as pack-owned in the update manifest, so future `--update` runs skip them instead of replacing them with the fallback template.
 
 ## When It Becomes Active
 

package/docs/codex-plugin.md

@@ -0,0 +1,57 @@
+# Codex Plugin
+
+`fclt` ships a first-party Codex plugin at:
+
+```text
+plugins/fclt/
+```
+
+The plugin is for agent-led operation. After install, Codex gets focused skills for setup, writeback, evolution, and capability review, plus an MCP server wrapper that exposes common `fclt` CLI actions as tools.
+
+## What It Includes
+
+- `fclt-setup`: install, update, inspect, initialize, and repair fclt setup.
+- `fclt-writeback`: record and review durable writebacks from real work.
+- `fclt-evolution`: turn repeated writeback into reviewed capability proposals.
+- `fclt-capability-review`: inspect global/project capability roots and scope changes.
+- `fclt` MCP server: stdio wrapper around the installed `fclt` CLI.
+
+The MCP wrapper intentionally delegates to the local `fclt` binary instead of duplicating core logic. Set `FCLT_BIN` if Codex should call a specific binary.
+
+## MCP Tools
+
+The plugin exposes:
+
+- `fclt_status`
+- `fclt_doctor`
+- `fclt_paths`
+- `fclt_init_operating_model`
+- `fclt_writeback_add`
+- `fclt_writeback_review`
+- `fclt_evolve`
+
+These tools are thin wrappers around CLI commands and return command output. Mutating tools still rely on the normal fclt safety model: dry-run first when available, review broad changes before apply, and preserve existing user guidance.
+
+## Install In Codex
+
+From this repository, the plugin can be rendered into the Codex plugin marketplace by managed sync:
+
+```bash
+fclt manage codex --global
+fclt sync codex --global
+```
+
+That writes plugin files under the Codex plugin location and updates the personal marketplace entry. Use managed sync only when you want `fclt` to write Codex tool files.
+
+For local plugin development, run the lightweight checks that ship with the repository:
+
+```bash
+node plugins/fclt/scripts/fclt-mcp.cjs --self-test
+bun run check
+```
+
+## Recommended Agent Use
+
+Use the plugin skills as the first interface. Use MCP tools when a Codex workflow benefits from structured calls for status, doctor, paths, writeback, or evolution review.
+
+Do not create writeback/evolution noise. Record strong signal, group repeated signal, then propose the smallest concrete capability change.

package/docs/pack-upgrades.md

@@ -54,7 +54,13 @@ Review skipped files before deciding whether to merge changes manually, keep the
 
 ## AGENTS.global.md
 
-The pack includes `AGENTS.global.md` as a composed entry template. It is not meant to hold every rule.
+The pack source stores the composed entry template at `snippets/templates/agents-global.md`. During install or update, `fclt` materializes that template as `AGENTS.global.md` in the target `.ai` root.
+
+That installed `AGENTS.global.md` is not meant to hold every rule.
+
+If first install finds existing agent guidance, `fclt` seeds `AGENTS.global.md` from it and appends the Facult operating-model frame. Global installs look for existing global tool docs such as `~/.codex/AGENTS.md` and `~/.claude/CLAUDE.md`; project installs look for repo-local `AGENTS.md` or `CLAUDE.md`.
+
+Seeded files are user-owned. They are intentionally excluded from the pack manifest so `--update` skips them unless you explicitly replace them with `--force` or edit them manually.
 
 Use:
 

package/docs/roadmap.md

@@ -16,6 +16,7 @@ This roadmap tracks remaining product direction for `fclt`.
 - JSON-first `inventory`.
 - `sync --adopt-live` for explicit promotion of live tool edits.
 - Managed sync local-edit protection for rendered docs, config, MCP, and skills.
+- Initial first-party Codex plugin with setup/writeback/evolution/capability-review skills and a CLI-backed MCP wrapper.
 
 ## Current Priorities
 
@@ -48,11 +49,11 @@ This roadmap tracks remaining product direction for `fclt`.
    - Add graph visibility.
    - Include them in status and sync plans.
 
-7. Add a first-party Codex plugin and MCP surface.
-   - Expose safe read/write operations over existing `fclt` behavior.
+7. Expand the first-party Codex plugin and MCP surface.
+   - Add richer setup planning tools beyond the initial CLI wrapper.
    - Keep the CLI and canonical `.ai` roots as the source of truth.
    - Gate high-risk global changes behind explicit review.
-   - Bundle agent-facing skills for work units, writeback, evolution, capability search, and automation setup.
+   - Add more focused agent-facing skills for automation setup, capability search, and upgrade flows.
 
 8. Tighten selector consistency.
    - Use one selector grammar across `list`, `show`, `graph`, `enable`, `disable`, `trust`, `audit`, writeback, and evolution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "facult",
-  "version": "2.14.0",
+  "version": "2.15.1",
   "description": "Manage canonical AI capabilities, sync surfaces, and evolution state.",
   "type": "module",
   "license": "MIT",
@@ -33,6 +33,11 @@
     "bin/facult.cjs",
     "docs/**/*.md",
     "docs/**/*.png",
+    "plugins/fclt/.codex-plugin/*.json",
+    "plugins/fclt/.mcp.json",
+    "plugins/fclt/**/*.cjs",
+    "plugins/fclt/**/*.js",
+    "plugins/fclt/**/*.md",
     "src/**/*.ts",
     "!src/**/*.test.ts",
     "README.md",

package/plugins/fclt/.codex-plugin/plugin.json

@@ -0,0 +1,31 @@
+{
+  "name": "fclt",
+  "version": "0.1.0",
+  "description": "Codex workflows and MCP tools for fclt setup, writeback, evolution, and capability review.",
+  "license": "MIT",
+  "keywords": [
+    "fclt",
+    "facult",
+    "codex",
+    "skills",
+    "mcp",
+    "writeback",
+    "evolution"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "fclt",
+    "shortDescription": "Capability loops for Codex",
+    "longDescription": "Install and operate fclt from Codex: initialize AI capability roots, inspect setup health, record writebacks, review evolution proposals, and keep skills, snippets, instructions, automations, and MCP surfaces improving over time.",
+    "developerName": "Hack Dance",
+    "category": "Productivity",
+    "capabilities": ["Read", "Write", "MCP"],
+    "defaultPrompt": [
+      "Use fclt to check this repo's AI capability setup.",
+      "Record useful fclt writeback from this work.",
+      "Review fclt evolution proposals and next actions."
+    ],
+    "brandColor": "#166534"
+  }
+}

package/plugins/fclt/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "fclt": {
+      "command": "node",
+      "args": ["./scripts/fclt-mcp.cjs"],
+      "env": {
+        "FCLT_BIN": "fclt"
+      }
+    }
+  }
+}

package/plugins/fclt/scripts/fclt-mcp.cjs

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawn } = require("node:child_process");
+
+const FCLT_BIN = process.env.FCLT_BIN || "fclt";
+const DEFAULT_TIMEOUT_MS = Number(process.env.FCLT_MCP_TIMEOUT_MS || 60_000);
+const CONTENT_LENGTH_RE = /Content-Length:\s*(\d+)/i;
+
+const tools = [
+  {
+    name: "fclt_status",
+    description:
+      "Return fclt status for the current, global, or project scope.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_doctor",
+    description: "Run read-only fclt doctor checks and return JSON output.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_paths",
+    description: "Return canonical, generated, review, and runtime fclt paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_init_operating_model",
+    description: "Install or update the built-in operating-model pack.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["global", "project"] },
+        cwd: { type: "string" },
+        update: { type: "boolean" },
+        dryRun: { type: "boolean" },
+        force: { type: "boolean" },
+      },
+      required: ["scope"],
+    },
+  },
+  {
+    name: "fclt_writeback_add",
+    description: "Record a durable fclt writeback with evidence.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+        kind: { type: "string" },
+        summary: { type: "string" },
+        asset: { type: "string" },
+        evidence: { type: "string" },
+        confidence: {
+          type: "string",
+          enum: ["low", "medium", "high"],
+        },
+      },
+      required: ["kind", "summary"],
+    },
+  },
+  {
+    name: "fclt_writeback_review",
+    description: "List, group, or summarize current fclt writebacks.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+        mode: { type: "string", enum: ["list", "group", "summarize"] },
+        by: { type: "string" },
+      },
+    },
+  },
+  {
+    name: "fclt_evolve",
+    description: "List, propose, draft, or review fclt evolution proposals.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: { type: "string", enum: ["auto", "global", "project"] },
+        cwd: { type: "string" },
+        action: {
+          type: "string",
+          enum: ["list", "propose", "draft", "review", "show"],
+        },
+        id: { type: "string" },
+      },
+    },
+  },
+];
+
+function scopeArgs(scope) {
+  if (scope === "global") {
+    return ["--global"];
+  }
+  if (scope === "project") {
+    return ["--project"];
+  }
+  return [];
+}
+
+function boolFlag(name, value) {
+  return value ? [name] : [];
+}
+
+function stringFlag(name, value) {
+  return typeof value === "string" && value.trim() ? [name, value] : [];
+}
+
+function commandForTool(name, args = {}) {
+  switch (name) {
+    case "fclt_status":
+      return ["status", ...scopeArgs(args.scope), "--json"];
+    case "fclt_doctor":
+      return ["doctor", ...scopeArgs(args.scope), "--json"];
+    case "fclt_paths":
+      return ["paths", ...scopeArgs(args.scope), "--json"];
+    case "fclt_init_operating_model":
+      return [
+        "templates",
+        "init",
+        "operating-model",
+        ...scopeArgs(args.scope),
+        ...boolFlag("--update", args.update),
+        ...boolFlag("--dry-run", args.dryRun),
+        ...boolFlag("--force", args.force),
+        "--json",
+      ];
+    case "fclt_writeback_add":
+      return [
+        "ai",
+        "writeback",
+        ...scopeArgs(args.scope),
+        "add",
+        "--kind",
+        args.kind,
+        "--summary",
+        args.summary,
+        ...stringFlag("--asset", args.asset),
+        ...stringFlag("--evidence", args.evidence),
+        ...stringFlag("--confidence", args.confidence),
+      ];
+    case "fclt_writeback_review": {
+      const mode = args.mode || "list";
+      return [
+        "ai",
+        "writeback",
+        ...scopeArgs(args.scope),
+        mode,
+        ...stringFlag("--by", args.by),
+      ];
+    }
+    case "fclt_evolve": {
+      const action = args.action || "list";
+      return [
+        "ai",
+        "evolve",
+        ...scopeArgs(args.scope),
+        action,
+        ...(args.id ? [args.id] : []),
+      ];
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+function runFclt(args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn(FCLT_BIN, args, {
+      cwd: cwd || process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+    }, DEFAULT_TIMEOUT_MS);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString();
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({
+        code,
+        text: [
+          `$ ${FCLT_BIN} ${args.join(" ")}`,
+          stdout.trim(),
+          stderr.trim() ? `stderr:\n${stderr.trim()}` : "",
+        ]
+          .filter(Boolean)
+          .join("\n\n"),
+      });
+    });
+  });
+}
+
+function send(message) {
+  const body = JSON.stringify(message);
+  process.stdout.write(
+    `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`
+  );
+}
+
+async function handle(message) {
+  if (!message || message.id == null) {
+    return;
+  }
+
+  try {
+    if (message.method === "initialize") {
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          protocolVersion: "2025-06-18",
+          capabilities: { tools: {} },
+          serverInfo: { name: "fclt", version: "0.1.0" },
+        },
+      });
+      return;
+    }
+    if (message.method === "tools/list") {
+      send({ jsonrpc: "2.0", id: message.id, result: { tools } });
+      return;
+    }
+    if (message.method === "tools/call") {
+      const { name, arguments: args = {} } = message.params || {};
+      const command = commandForTool(name, args);
+      const result = await runFclt(command, args.cwd);
+      send({
+        jsonrpc: "2.0",
+        id: message.id,
+        result: {
+          isError: result.code !== 0,
+          content: [{ type: "text", text: result.text }],
+        },
+      });
+      return;
+    }
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: { code: -32_601, message: `Method not found: ${message.method}` },
+    });
+  } catch (error) {
+    send({
+      jsonrpc: "2.0",
+      id: message.id,
+      error: {
+        code: -32_000,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    });
+  }
+}
+
+let buffer = Buffer.alloc(0);
+
+process.stdin.on("data", (chunk) => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const headerEnd = buffer.indexOf("\r\n\r\n");
+    if (headerEnd === -1) {
+      return;
+    }
+    const header = buffer.slice(0, headerEnd).toString("utf8");
+    const match = CONTENT_LENGTH_RE.exec(header);
+    if (!match) {
+      buffer = Buffer.alloc(0);
+      return;
+    }
+    const length = Number(match[1]);
+    const frameEnd = headerEnd + 4 + length;
+    if (buffer.length < frameEnd) {
+      return;
+    }
+    const body = buffer.slice(headerEnd + 4, frameEnd).toString("utf8");
+    buffer = buffer.slice(frameEnd);
+    handle(JSON.parse(body)).catch((error) => {
+      send({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32_000,
+          message: error instanceof Error ? error.message : String(error),
+        },
+      });
+    });
+  }
+});
+
+if (process.argv.includes("--self-test")) {
+  console.log(
+    JSON.stringify({ tools: tools.map((tool) => tool.name) }, null, 2)
+  );
+  process.exit(0);
+}

package/plugins/fclt/skills/fclt-capability-review/SKILL.md

@@ -0,0 +1,51 @@
+---
+description: Inspect fclt capability roots, docs, snippets, skills, agents, MCP, and automations.
+tags: [fclt, capability, review, inventory]
+---
+
+# fclt-capability-review
+
+## When To Use
+Use this skill when Codex needs to understand what capability exists before changing it.
+
+Use it for:
+
+- checking global and project `.ai` roots
+- finding relevant skills, snippets, instructions, agents, MCP servers, or automations
+- deciding whether a change belongs in global or project scope
+- checking whether managed rendering is enabled or needed
+- reviewing public/private boundaries before publishing docs or pack assets
+
+## Workflow
+
+```bash
+fclt status --json
+fclt inventory --json
+fclt list skills
+fclt list instructions
+fclt list snippets
+fclt graph AGENTS.global.md
+```
+
+For project work:
+
+```bash
+fclt status --project --json
+fclt inventory --project --json
+```
+
+## Rules
+
+- Read existing repo guidance before proposing project capability.
+- Use project scope for repo-specific commands, tests, architecture, or team workflow.
+- Use global scope only for broadly reusable behavior.
+- Keep generated state and review artifacts out of repo-local `.ai`.
+- Prefer adding or updating the smallest unit: instruction, snippet, skill, agent, MCP config, or automation.
+
+## Output
+
+- capability roots found
+- relevant assets
+- scope recommendation
+- missing or stale capability
+- safe next command