toolfactory 0.2.0 → 0.2.4

package/README.md

@@ -22,7 +22,7 @@ generated and every surface still installs, builds and publishes.
 - **Gemini CLI extension** — `gemini extensions install https://github.com/GoatInAHat/toolfactory`
 - **OpenClaw plugin** — `openclaw plugins install --link hosts/openclaw` from a checkout
 - **Hermes plugin** — `hermes plugins install https://github.com/GoatInAHat/toolfactory#hosts/hermes/toolfactory_hermes`
-- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.2.0.tgz`
+- **DSH plugin** (experimental) — `dsh plugin --profile <profile> add ./hosts/dsh` from a checkout, or the release tarball `toolfactory-dsh-0.2.4.tgz`
 - **Web app** — `npx -y toolfactory mcp --http --open` serves the operations page beside the
   MCP endpoint on one port and opens it; over MCP or a skill, the `web` operation does the same and
   returns the URL.

package/dist/bindings/typescript.js

@@ -719,7 +719,7 @@ export function scaffold(project) {
         engines: { node: NODE_ENGINES },
         scripts: {
             build: "tsc -p tsconfig.json",
-            test: "vitest run --passWithNoTests",
+            test: "vitest run --dir src --passWithNoTests",
             "test:live": LIVE_TEST_SCRIPT,
         },
         dependencies: {

package/dist/bindings/typescript.test.js

@@ -1,9 +1,10 @@
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, symlinkSync, writeFileSync, } from "node:fs";
 import { createServer as createNetServer } from "node:http";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { stripVTControlCharacters } from "node:util";
 import { describe, expect, it } from "vitest";
 import { ToolConfigSchema } from "../model.js";
 import { cliCommand, cli as cliFiles, kernel, kernelCommand, liveTest, scaffold, } from "./typescript.js";
@@ -198,6 +199,33 @@ async function waitForInitialize(url, deadlineMs, token) {
         }
     }
 }
+describe.skipIf(!existsSync(repoNodeModules))("typescript scaffold test commands", () => {
+    it("runs core tests without collecting host or live tests, preserving the explicit live lane", () => {
+        const root = mkdtempSync(join(tmpdir(), "toolfactory-test-scope-"));
+        symlinkSync(repoNodeModules, join(root, "node_modules"), "dir");
+        writeFileSync(join(root, "package.json"), text(scaffold(project(["cli"])), "package.json"));
+        const writeTest = (path, body) => {
+            mkdirSync(dirname(join(root, path)), { recursive: true });
+            writeFileSync(join(root, path), body);
+        };
+        const passing = 'import { it } from "vitest"; it("core receipt", () => {});';
+        const failing = 'import { it } from "vitest"; it("scope sentinel", () => { throw new Error("outside core"); });';
+        writeTest("src/core.test.ts", passing);
+        writeTest("hosts/openclaw/src/index.test.ts", failing);
+        writeTest("hosts/browser/tests/background.test.ts", failing);
+        writeTest("tests/live.test.ts", failing);
+        const run = (script) => spawnSync("npm", ["run", script], { cwd: root, encoding: "utf8" });
+        const core = run("test");
+        expect(core.status, core.stdout + core.stderr).toBe(0);
+        expect(stripVTControlCharacters(core.stdout)).toMatch(/Tests\s+1 passed/);
+        writeTest("src/core.test.ts", failing);
+        expect(run("test").status).toBe(1);
+        writeTest("tests/live.test.ts", passing);
+        const live = run("test:live");
+        expect(live.status, live.stdout + live.stderr).toBe(0);
+        expect(stripVTControlCharacters(live.stdout)).toMatch(/Tests\s+1 passed/);
+    });
+});
 describe.skipIf(!existsSync(repoNodeModules))("typescript kernel, really run over http", () => {
     it("serves tools/list over --http, and requires the token minted by --pair", {
         timeout: 60_000,

package/dist/commands.d.ts

@@ -2,6 +2,7 @@ import { type BootstrapResult, type CreateRepoResult } from "./hosts/github.js";
 import type { Binding, Command, Project, SurfaceId } from "./model.js";
 import { type Drift } from "./project/apply.js";
 import { type GateStep } from "./project/gate.js";
+import { type PromptReviewReport } from "./prompt/review.js";
 import { type Coverage } from "./report/coverage.js";
 export interface InitOptions {
     root: string;
@@ -186,3 +187,8 @@ export declare function bootstrapRepo(args: {
 }): BootstrapResult;
 export declare function doctor(): DoctorReport;
 export declare const SURFACES: readonly ["skill", "agent-plugins", "claude", "codex", "cursor", "mcp", "mcp-registry", "cli", "npm", "pypi", "openclaw-native", "hermes-native", "clawhub", "web", "dsh", "workflows", "agents", "readme", "gemini", "mcpb", "browser-extension", "vscode-extension", "cargo", "nuget", "maven-central", "rubygems", "packagist", "go-module", "homebrew", "winget", "scoop", "chocolatey", "apt", "rpm"];
+/** `review-prompt`: the codex-prompt-standard loop's evaluator (see `src/prompt/review.ts`). */
+export declare function reviewPrompt(input: {
+    prompt: string;
+    reference?: string;
+}): PromptReviewReport;

package/dist/commands.js

@@ -10,6 +10,7 @@ import { parseEnv } from "node:util";
 import { getBinding } from "./bindings/index.js";
 import { LIVE_TEST_COMMAND } from "./bindings/python.js";
 import { createRepo, githubSlug, LIVE_ENVIRONMENT, bootstrapRepo as prepareRepository, } from "./hosts/github.js";
+import { coreCopyDrift } from "./hosts/openclaw.js";
 import { assertValidName, projectName } from "./identity/name.js";
 import { introspect as runIntrospect, snapshot } from "./introspect/index.js";
 import { assertNoSensitiveArgument, defaultSurfaces, isInstructionOnly, SURFACE_IDS, ToolConfigSchema, } from "./model.js";
@@ -19,6 +20,7 @@ import { droppedSurfaces, previousTag, toolAtRef } from "./project/history.js";
 import { loadProject, OPS_PATH, TOOL_PATH, TOOLFACTORY_VERSION, toOperation, } from "./project/load.js";
 import { readLock } from "./project/lock.js";
 import { buildPlan, TOOL_SCHEMA_PATH } from "./project/plan.js";
+import { reviewPrompt as evaluatePrompt } from "./prompt/review.js";
 import { computeCoverage } from "./report/coverage.js";
 import { PLUGIN_SCHEMA_ID } from "./surfaces/agent-plugins.js";
 import { reloadLine, SETUP_PATH } from "./surfaces/agents.js";
@@ -237,11 +239,16 @@ export async function check(root = ".") {
     const project = loadProject(root);
     assertNoSensitiveArgument(project.tool.config, project.operations);
     const drift = checkPlan(project.root, buildPlan(project), TOOLFACTORY_VERSION);
+    const hostDrift = coreCopyDrift(project.root);
     const ops = isInstructionOnly(project.tool) ? undefined : await snapshot(project);
     if (ops?.changed)
         drift.unshift({ kind: "changed", path: OPS_PATH });
+    drift.push(...hostDrift);
     if (drift.length) {
-        throw new Error(`${drift.length} generated file(s) out of date; run \`toolfactory ${ops?.changed ? "introspect" : "build"}\`:\n${drift.map((d) => `  ${d.kind}: ${d.path}`).join("\n")}`);
+        const remedy = hostDrift.length
+            ? "\nthe materialized host core copy is stale: cp -r dist/. hosts/openclaw/node_modules/toolfactory/dist/"
+            : "";
+        throw new Error(`${drift.length} generated file(s) out of date; run \`toolfactory ${ops?.changed ? "introspect" : "build"}\`:\n${drift.map((d) => `  ${d.kind}: ${d.path}`).join("\n")}${remedy}`);
     }
     return { project, drift };
 }
@@ -549,7 +556,7 @@ function secretsSummary(report) {
     if (!rows.length)
         return undefined;
     const missing = rows.filter((row) => !row.local).map((row) => row.name);
-    return `Secrets: ${rows.length - missing.length} of ${rows.length} present in .env${missing.length ? ` (missing ${missing.join(", ")})` : ""}. \`toolfactory secrets\` prints where each one is set, per host and per registry.`;
+    return `Secrets: ${rows.length - missing.length} of ${rows.length} present in .env${missing.length ? ` (missing ${missing.join(", ")})` : ""}. \`toolfactory secrets-usage\` prints where each one is set, per host and per registry.`;
 }
 /** The project as the previous tag left it, plus the surfaces it published that are now gone. */
 function retractable(project, tag, tool) {
@@ -660,3 +667,7 @@ export function doctor() {
     return { toolfactory: TOOLFACTORY_VERSION, node: process.version, tools };
 }
 export const SURFACES = SURFACE_IDS;
+/** `review-prompt`: the codex-prompt-standard loop's evaluator (see `src/prompt/review.ts`). */
+export function reviewPrompt(input) {
+    return evaluatePrompt(input);
+}

package/dist/hosts/openclaw.d.ts

@@ -1,4 +1,12 @@
 import type { Project } from "../model.js";
+import type { Drift } from "../project/apply.js";
 export declare const DRIFT_ENTRY: string;
 /** Human-readable drift lines; empty means the generator still mirrors upstream. */
 export declare function scaffoldDrift(project: Project): string[];
+/**
+ * The copy is what the plugin's runtime lookup resolves, and nothing syncs it: after the core
+ * gains an operation, a stale copy still registers the tool but every call fails with
+ * "operation … is missing from the core package". Opt-in via a MATERIALIZED marker, so
+ * npm-installed cores in generated tools are never compared against a workspace build.
+ */
+export declare function coreCopyDrift(root: string): Drift[];

package/dist/hosts/openclaw.js

@@ -8,13 +8,13 @@
  * `validate()` step reaches it: one Command like every other validator.
  */
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { argv, exit, stderr, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
 import { loadProject } from "../project/load.js";
-import { HOST_DIR, surface } from "../surfaces/openclaw-native.js";
+import { HOST_DIR, OPENCLAW_SCAFFOLD, surface } from "../surfaces/openclaw-native.js";
 export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
 /** Per-tool values: the scaffold writes its own, and the projection is expected to differ. */
 const PER_TOOL_KEYS = new Set(["name", "version", "description"]);
@@ -33,6 +33,9 @@ function overridden(project) {
         paths.add(".peerDependencies.openclaw");
         paths.add(".openclaw.compat.pluginApi");
     }
+    // Shipped skills append to `files`; upstream's entries must still survive (checked below).
+    if (openclaw?.skills?.length)
+        paths.add(".files");
     return paths;
 }
 /**
@@ -68,10 +71,25 @@ function planned(files, path) {
 export function scaffoldDrift(project) {
     const files = surface.plan(project);
     const directory = mkdtempSync(join(tmpdir(), "toolfactory-openclaw-"));
-    // Prefer the openclaw the plugin pins as a devDependency over whatever is on PATH.
+    // The probe must run the exact openclaw this project pins (author override or the
+    // scaffold default) - never whatever happens to be on PATH, which made the drift verdict
+    // environment-dependent: the scaffold openclawVersion is the running CLI own version.
+    const pin = project.tool.openclaw?.devDependencies?.openclaw ?? OPENCLAW_SCAFFOLD.devDependencies.openclaw;
     const pinned = join(project.root, HOST_DIR, "node_modules/.bin/openclaw");
     try {
-        execFileSync(existsSync(pinned) ? pinned : "openclaw", ["plugins", "init", "tf-probe", "--type", "tool", "--directory", join(directory, "probe")], { stdio: "pipe" });
+        const probe = existsSync(pinned)
+            ? { command: pinned, pre: [] }
+            : { command: "npx", pre: ["--yes", `openclaw@${pin}`] };
+        execFileSync(probe.command, [
+            ...probe.pre,
+            "plugins",
+            "init",
+            "tf-probe",
+            "--type",
+            "tool",
+            "--directory",
+            join(directory, "probe"),
+        ], { stdio: "pipe" });
         const scaffold = (path) => readFileSync(join(directory, "probe", path), "utf8");
         const skip = overridden(project);
         const drift = [
@@ -80,12 +98,60 @@ export function scaffoldDrift(project) {
                 ? []
                 : ["vitest.config.ts: upstream template changed"]),
         ];
+        if (project.tool.openclaw?.skills?.length) {
+            const upstream = JSON.parse(scaffold("package.json")).files ?? [];
+            const ours = JSON.parse(planned(files, "package.json")).files ?? [];
+            const lost = upstream.filter((entry) => !ours.includes(entry));
+            if (lost.length)
+                drift.push(`package.json.files lost upstream entries: ${lost.join(", ")}`);
+        }
         return drift;
     }
     finally {
         rmSync(directory, { recursive: true, force: true });
     }
 }
+/**
+ * The copy is what the plugin's runtime lookup resolves, and nothing syncs it: after the core
+ * gains an operation, a stale copy still registers the tool but every call fails with
+ * "operation … is missing from the core package". Opt-in via a MATERIALIZED marker, so
+ * npm-installed cores in generated tools are never compared against a workspace build.
+ */
+export function coreCopyDrift(root) {
+    // Resolves HOST_DIR lazily: this module sits in an import cycle with
+    // surfaces/openclaw-native.js (DRIFT_ENTRY), so nothing may touch its exports at module scope.
+    const copy = join(root, HOST_DIR, "node_modules", "toolfactory");
+    if (!existsSync(join(copy, "MATERIALIZED")))
+        return [];
+    const source = join(root, "dist");
+    if (!existsSync(source))
+        return [];
+    return treeDrift(source, join(copy, "dist"), join(HOST_DIR, "node_modules", "toolfactory", "dist"));
+}
+/** Byte-compare two trees in both directions; `label` prefixes every reported path. */
+function treeDrift(source, copy, label) {
+    if (!existsSync(copy))
+        return [{ kind: "changed", path: label }];
+    const drift = [];
+    for (const name of new Set([...readdirSync(source), ...readdirSync(copy)])) {
+        const ours = join(source, name);
+        const theirs = join(copy, name);
+        const oursDir = existsSync(ours) && statSync(ours).isDirectory();
+        const theirsDir = existsSync(theirs) && statSync(theirs).isDirectory();
+        if (oursDir || theirsDir) {
+            if (oursDir && theirsDir)
+                drift.push(...treeDrift(ours, theirs, join(label, name)));
+            else
+                drift.push({ kind: "changed", path: join(label, name) });
+        }
+        else if (!existsSync(ours) ||
+            !existsSync(theirs) ||
+            !readFileSync(ours).equals(readFileSync(theirs))) {
+            drift.push({ kind: "changed", path: join(label, name) });
+        }
+    }
+    return drift;
+}
 if (argv[1] === DRIFT_ENTRY) {
     const drift = scaffoldDrift(loadProject(argv[2] ?? "."));
     if (drift.length) {

package/dist/hosts/openclaw.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hosts/openclaw.test.js

@@ -0,0 +1,58 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { coreCopyDrift } from "./openclaw.js";
+const roots = [];
+function staged() {
+    const root = mkdtempSync(join(tmpdir(), "tf-core-copy-"));
+    roots.push(root);
+    return root;
+}
+function put(root, path, content) {
+    const file = join(root, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
+}
+afterEach(() => {
+    for (const root of roots.splice(0))
+        rmSync(root, { recursive: true, force: true });
+});
+describe("coreCopyDrift", () => {
+    it("skips copies without the MATERIALIZED marker (npm-installed cores)", () => {
+        const root = staged();
+        put(root, "dist/ops.js", "new");
+        put(root, "hosts/openclaw/node_modules/toolfactory/dist/ops.js", "old");
+        expect(coreCopyDrift(root)).toEqual([]);
+    });
+    it("skips when the workspace has no dist yet", () => {
+        const root = staged();
+        put(root, "hosts/openclaw/node_modules/toolfactory/MATERIALIZED", "");
+        expect(coreCopyDrift(root)).toEqual([]);
+    });
+    it("passes when the materialized copy matches the dist", () => {
+        const root = staged();
+        put(root, "dist/ops.js", "same");
+        put(root, "dist/deep/command.js", "same");
+        put(root, "hosts/openclaw/node_modules/toolfactory/MATERIALIZED", "");
+        put(root, "hosts/openclaw/node_modules/toolfactory/dist/ops.js", "same");
+        put(root, "hosts/openclaw/node_modules/toolfactory/dist/deep/command.js", "same");
+        expect(coreCopyDrift(root)).toEqual([]);
+    });
+    it("flags stale, missing, and extra files in the copy", () => {
+        const root = staged();
+        put(root, "dist/ops.js", "new");
+        put(root, "dist/gone.js", "still here");
+        put(root, "hosts/openclaw/node_modules/toolfactory/MATERIALIZED", "");
+        put(root, "hosts/openclaw/node_modules/toolfactory/dist/ops.js", "old");
+        put(root, "hosts/openclaw/node_modules/toolfactory/dist/extra.js", "leftover");
+        const paths = coreCopyDrift(root)
+            .map((d) => d.path)
+            .sort();
+        expect(paths).toEqual([
+            "hosts/openclaw/node_modules/toolfactory/dist/extra.js",
+            "hosts/openclaw/node_modules/toolfactory/dist/gone.js",
+            "hosts/openclaw/node_modules/toolfactory/dist/ops.js",
+        ]);
+    });
+});

package/dist/hosts/web.d.ts

@@ -1,4 +1,5 @@
 import type { Project } from "../model.js";
 export declare const DRIFT_ENTRY: string;
+export declare function differs(label: string, upstream: unknown, pinned: unknown): string[];
 /** Human-readable drift lines; empty means the generators still write what WEB_SCAFFOLD says. */
 export declare function scaffoldDrift(project: Project): string[];

package/dist/hosts/web.js

@@ -15,6 +15,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { argv, exit, stderr, stdout } from "node:process";
 import { fileURLToPath } from "node:url";
+import { inspect, isDeepStrictEqual } from "node:util";
 import { loadProject } from "../project/load.js";
 import { surface, TAILWIND_CSS, WEB_DIR, WEB_SCAFFOLD } from "../surfaces/web.js";
 export const DRIFT_ENTRY = fileURLToPath(import.meta.url);
@@ -30,10 +31,12 @@ function planned(files, path) {
 function parse(text) {
     return JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, ""));
 }
-function differs(label, upstream, pinned) {
-    return JSON.stringify(upstream) === JSON.stringify(pinned)
+export function differs(label, upstream, pinned) {
+    return isDeepStrictEqual(upstream, pinned)
         ? []
-        : [`${label}: upstream and WEB_SCAFFOLD no longer agree`];
+        : [
+            `${label}: upstream ${inspect(upstream, { sorted: true })}, pinned ${inspect(pinned, { sorted: true })}`,
+        ];
 }
 /** Human-readable drift lines; empty means the generators still write what WEB_SCAFFOLD says. */
 export function scaffoldDrift(project) {

package/dist/hosts/web.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hosts/web.test.js

@@ -0,0 +1,8 @@
+import { expect, it } from "vitest";
+import { differs } from "./web.js";
+it("compares scaffold objects by values, not key insertion order", () => {
+    expect(differs("deps", { a: "1", b: "2" }, { b: "2", a: "1" })).toEqual([]);
+    expect(differs("deps", { a: "1" }, { a: "2" })).toHaveLength(1);
+    expect(differs("deps", { a: "1" }, { a: "1", b: "2" })).toHaveLength(1);
+    expect(differs("array", ["a", "b"], ["b", "a"])).toHaveLength(1);
+});

package/dist/model.d.ts

@@ -162,6 +162,7 @@ export declare const ToolConfigSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         activation: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         pluginApi: z.ZodOptional<z.ZodString>;
+        skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
         dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
@@ -257,6 +258,15 @@ export interface Command {
     cwd?: string;
     env?: Record<string, string>;
 }
+/** One `.agents/skills/<name>/` directory a plugin surface ships, read at load time. */
+export interface ProjectSkill {
+    name: string;
+    /** Files of the skill directory, relative and sorted; content as UTF-8 text. */
+    files: {
+        path: string;
+        content: string;
+    }[];
+}
 export interface Project {
     root: string;
     tool: ToolConfig;
@@ -267,6 +277,8 @@ export interface Project {
     toolfactoryVersion: string;
     /** From the root package.json `packageManager` field; npm when absent. */
     packageManager?: PackageManager;
+    /** Skills `openclaw.skills` declares, read once so projectors stay pure. */
+    skills?: ProjectSkill[];
 }
 export interface Surface {
     id: SurfaceId;

package/dist/model.js

@@ -176,6 +176,10 @@ export const ToolConfigSchema = z
             .string()
             .optional()
             .describe("Plugin API range for compat.pluginApi and the openclaw peer dependency."),
+        skills: z
+            .array(z.string())
+            .optional()
+            .describe("Skill directories under `.agents/skills/` that the OpenClaw plugin ships; OpenClaw loads them through the manifest's `skills` roots."),
         dependencies: z.record(z.string(), z.string()).optional(),
         peerDependencies: z.record(z.string(), z.string()).optional(),
         devDependencies: z.record(z.string(), z.string()).optional(),

package/dist/ops.d.ts

@@ -151,6 +151,32 @@ export declare const operations: (import("./toolfactory/types.js").Operation<z.Z
             reason: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+}, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
+    prompt: z.ZodString;
+    reference: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    verdict: z.ZodEnum<{
+        pass: "pass";
+        polish: "polish";
+        revise: "revise";
+    }>;
+    sections: z.ZodObject<{
+        present: z.ZodArray<z.ZodString>;
+        missing: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+    checks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            fail: "fail";
+            pass: "pass";
+            warn: "warn";
+        }>;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    directives: z.ZodArray<z.ZodString>;
+    reference: z.ZodOptional<z.ZodObject<{
+        sectionsMissingHere: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>> | import("./toolfactory/types.js").Operation<z.ZodObject<{
     root: z.ZodDefault<z.ZodString>;
     path: z.ZodString;

package/dist/ops.js

@@ -153,6 +153,30 @@ export const operations = [
         annotations: { readOnlyHint: true },
         handler: async ({ root }) => commands.coverage(root),
     }),
+    operation({
+        name: "review-prompt",
+        description: "Evaluate a prompt draft against the codex-prompt-standard rubric: anatomy sections, convention checks, and concrete directives. Draft, run this, fix what it flags, and re-run until it passes.",
+        input: z.object({
+            prompt: z.string().min(1).describe("The prompt draft to evaluate"),
+            reference: z
+                .string()
+                .optional()
+                .describe("The closest reference prompt's full text, fetched per the standard (an OpenAI Codex core prompt); sections it has that the draft lacks become the bar"),
+        }),
+        output: z.object({
+            verdict: z.enum(["pass", "polish", "revise"]),
+            sections: z.object({ present: z.array(z.string()), missing: z.array(z.string()) }),
+            checks: z.array(z.object({
+                id: z.string(),
+                status: z.enum(["pass", "warn", "fail"]),
+                detail: z.string(),
+            })),
+            directives: z.array(z.string()),
+            reference: z.object({ sectionsMissingHere: z.array(z.string()) }).optional(),
+        }),
+        annotations: { readOnlyHint: true, idempotentHint: true },
+        handler: async ({ prompt, reference }) => commands.reviewPrompt({ prompt, reference }),
+    }),
     operation({
         name: "adopt",
         description: "Stop regenerating one file; it becomes the author's (recorded as manual in the lock).",
@@ -208,7 +232,7 @@ export const operations = [
         handler: async (args) => commands.bootstrapRepo(args),
     }),
     operation({
-        name: "secrets",
+        name: "secrets-usage",
         description: "Every credential this project's surfaces need — the tool's own sensitive config keys and the release registries' tokens — with where each one is set, whether it is present locally and on GitHub, and (check) whether the registry accepts it. Never a value.",
         input: z.object({
             root,

package/dist/project/gate.js

@@ -250,13 +250,19 @@ export function packageSteps(project, options = {}) {
     }
     if (has(project, "openclaw-native")) {
         // ClawHub's reusable workflow has no build step of its own, so the tarball it publishes has
-        // to arrive already built (`package_artifact_name`).
+        // to arrive already built (`package_artifact_name`). Consumers install this tarball outside
+        // the monorepo, where the checkout-relative `file:../..` core dependency cannot resolve, so
+        // pack against the npm-published core of the same release and restore the workspace manifest.
         steps.push({
             name: "OpenClaw plugin tarball",
             run: [
                 `npm --prefix ${OPENCLAW_HOST_DIR} install`,
                 `npm --prefix ${OPENCLAW_HOST_DIR} run build`,
+                `v=$(node -p "require('./package.json').version")`,
+                `cp ${OPENCLAW_HOST_DIR}/package.json ${OPENCLAW_HOST_DIR}/package.json.prepack`,
+                `(cd ${OPENCLAW_HOST_DIR} && npm pkg set dependencies.toolfactory=$v)`,
                 `npm pack ./${OPENCLAW_HOST_DIR} --pack-destination ${RELEASE_DIR}`,
+                `mv ${OPENCLAW_HOST_DIR}/package.json.prepack ${OPENCLAW_HOST_DIR}/package.json`,
             ].join(" && "),
         });
     }

package/dist/project/history.d.ts

@@ -82,6 +82,7 @@ export declare function toolAtRef(root: string, ref: string): {
         }[] | undefined;
         activation?: Record<string, unknown> | undefined;
         pluginApi?: string | undefined;
+        skills?: string[] | undefined;
         dependencies?: Record<string, string> | undefined;
         peerDependencies?: Record<string, string> | undefined;
         devDependencies?: Record<string, string> | undefined;

package/dist/project/load.js

@@ -1,6 +1,6 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { join, resolve } from "node:path";
+import { join, relative, resolve, sep } from "node:path";
 import { z } from "zod";
 import { readIdentityFile } from "../identity/read.js";
 import { CAPABILITIES, isInstructionOnly, PACKAGE_MANAGERS, ToolConfigSchema, } from "../model.js";
@@ -62,6 +62,22 @@ function readPackageManager(root) {
     }
     return name;
 }
+/** `.agents/skills/<name>/` as a shippable unit: every file, sorted, content in memory. */
+function readProjectSkill(root, name) {
+    const directory = join(root, ".agents", "skills", name);
+    if (!existsSync(directory)) {
+        throw new Error(`openclaw.skills declares "${name}" but ${join(".agents", "skills", name)} does not exist`);
+    }
+    const files = readdirSync(directory, { recursive: true, withFileTypes: true })
+        .filter((entry) => entry.isFile())
+        .map((entry) => join(entry.parentPath, entry.name))
+        .sort()
+        .map((absolute) => ({
+        path: relative(directory, absolute).replaceAll(sep, "/"),
+        content: readFileSync(absolute, "utf8"),
+    }));
+    return { name, files };
+}
 export function loadProject(rootInput = ".") {
     const root = resolve(rootInput);
     const toolPath = join(root, TOOL_PATH);
@@ -76,6 +92,7 @@ export function loadProject(rootInput = ".") {
         identity: identityFile.identity,
         identityExtra: identityFile.extra,
         operations: isInstructionOnly(tool) ? [] : readOps(root),
+        skills: (tool.openclaw?.skills ?? []).map((name) => readProjectSkill(root, name)),
         toolfactoryVersion: TOOLFACTORY_VERSION,
         packageManager: readPackageManager(root),
     };

package/dist/prompt/review.d.ts

@@ -0,0 +1,23 @@
+export interface PromptReviewInput {
+    prompt: string;
+    /** The closest reference prompt's full text (canon §1: fetch it before evaluating). */
+    reference?: string;
+}
+export interface CheckResult {
+    id: string;
+    status: "pass" | "warn" | "fail";
+    detail: string;
+}
+export interface PromptReviewReport {
+    verdict: "pass" | "polish" | "revise";
+    sections: {
+        present: string[];
+        missing: string[];
+    };
+    checks: CheckResult[];
+    directives: string[];
+    reference?: {
+        sectionsMissingHere: string[];
+    };
+}
+export declare function reviewPrompt(input: PromptReviewInput): PromptReviewReport;