aiblueprint-cli 1.4.99 → 1.4.100

package/agents-config/skills/use-artifacts/assets/local-runtime.js

@@ -0,0 +1,299 @@
+/*
+ * local-runtime.js: local artifact capabilities shim. No Anthropic API,
+ * no claude.ai runtime, no network calls. Everything runs on plain
+ * browser APIs (Blob, <a download>, timers, in-memory cache).
+ *
+ * It mirrors the claude.ai artifact runtime surface (contract 0.1.14):
+ *   - window.claude.downloads.save({filename, data})
+ *   - window.claude.mcp.callTool / watchTool / listTools / invalidate
+ *
+ * If a real claude.ai runtime already installed a member, the shim
+ * leaves it untouched, so the same feature code is portable to a
+ * genuinely published artifact without changes.
+ *
+ * Local data sources replace viewer connectors. Register them BEFORE
+ * feature code runs:
+ *
+ *   window.claudeLocal.registerTool("Analytics", "get_stats",
+ *     async (input) => ({ visits: 1234 }));            // live local source
+ *   window.claudeLocal.registerTool("Analytics", "snapshot",
+ *     { visits: 1234 }, { description: "Static snapshot 2026-07-22" });
+ *
+ * Then use the standard surface:
+ *   const r = await window.claude.mcp.callTool("Analytics", "get_stats", { range: "7d" });
+ *   render(r.payload);
+ */
+(function () {
+  "use strict";
+  if (typeof window === "undefined") return;
+
+  var root = window.claude;
+  if (!root || typeof root !== "object") {
+    root = {};
+    try { window.claude = root; } catch (e) { return; }
+  }
+
+  /* ------------------------------ downloads ------------------------------ */
+
+  var EXT_ALLOWLIST = ["gif", "png", "jpg", "jpeg", "webp", "mp4", "webm", "txt", "json", "md"];
+  var MIME_BY_EXT = {
+    gif: "image/gif", png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg",
+    webp: "image/webp", mp4: "video/mp4", webm: "video/webm",
+    txt: "text/plain", json: "application/json", md: "text/markdown"
+  };
+  var MAX_BYTES = 16 * 1024 * 1024;
+  var promptOpen = false;
+
+  function downloadsError(code, message) {
+    return { code: code, message: message };
+  }
+
+  function toBlob(data, mime) {
+    if (typeof data === "string" && data.length) return new Blob([data], { type: mime });
+    if (data instanceof Blob && data.size) return new Blob([data], { type: mime });
+    if (data instanceof ArrayBuffer && data.byteLength) return new Blob([data], { type: mime });
+    if (ArrayBuffer.isView(data) && data.byteLength) return new Blob([data], { type: mime });
+    return null;
+  }
+
+  if (!root.downloads) {
+    root.downloads = {
+      save: function (request) {
+        return new Promise(function (resolve, reject) {
+          if (promptOpen) {
+            return reject(downloadsError("rate_limited", "A save prompt is already open."));
+          }
+          if (!request || typeof request !== "object") {
+            return reject(downloadsError("bad_request", "save() takes {filename, data}."));
+          }
+          var filename = request.filename;
+          if (typeof filename !== "string" || !filename || filename.length > 512) {
+            return reject(downloadsError("bad_request", "filename must be a non-empty string of at most 512 chars."));
+          }
+          var clean = filename.replace(/[\/\\:*?"<>|]+/g, "-").trim();
+          var dot = clean.lastIndexOf(".");
+          var ext = (dot > 0 ? clean.slice(dot + 1) : "").toLowerCase();
+          if (EXT_ALLOWLIST.indexOf(ext) === -1) {
+            return reject(downloadsError("rejected_extension",
+              "Extension \"." + ext + "\" is outside the allowlist: " + EXT_ALLOWLIST.join(" ")));
+          }
+          var blob = toBlob(request.data, MIME_BY_EXT[ext]);
+          if (!blob) {
+            return reject(downloadsError("bad_request",
+              "data must be a non-empty string, Blob, ArrayBuffer, or ArrayBufferView."));
+          }
+          if (blob.size > MAX_BYTES) {
+            return reject(downloadsError("too_large", "File is over 16 MiB (" + blob.size + " bytes)."));
+          }
+          promptOpen = true;
+          var accepted;
+          try {
+            accepted = window.confirm('Save "' + clean + '" (' + blob.size + " bytes)?");
+          } finally {
+            promptOpen = false;
+          }
+          if (!accepted) {
+            return reject(downloadsError("declined", "The viewer declined the save."));
+          }
+          var url = URL.createObjectURL(blob);
+          var a = document.createElement("a");
+          a.href = url;
+          a.download = clean;
+          document.body.appendChild(a);
+          a.click();
+          a.remove();
+          setTimeout(function () { URL.revokeObjectURL(url); }, 10000);
+          resolve({ status: "saved" });
+        });
+      }
+    };
+  }
+
+  /* --------------------------------- mcp --------------------------------- */
+
+  var SEP = "\u0000";
+  var registry = {};  // "server\0tool" -> {source, isStatic, description}
+  var cache = {};     // identity -> {result, storedAt}
+  var watchers = {};  // identity -> [{handler, timer, refresh}]
+
+  function key(server, tool) { return server + SEP + tool; }
+
+  function canonical(value) {
+    if (value === undefined || value === null) return "null";
+    if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
+    if (typeof value === "object") {
+      return "{" + Object.keys(value).sort().map(function (k) {
+        return JSON.stringify(k) + ":" + canonical(value[k]);
+      }).join(",") + "}";
+    }
+    return JSON.stringify(value);
+  }
+
+  function identity(server, tool, input) {
+    return key(server, tool) + SEP + canonical(input);
+  }
+
+  function mcpError(code, server, message, extra) {
+    var err = { code: code, message: message };
+    if (server !== undefined) err.server = server;
+    if (extra) Object.keys(extra).forEach(function (k) { err[k] = extra[k]; });
+    return err;
+  }
+
+  function envelope(payload) {
+    var text = typeof payload === "string" ? payload : JSON.stringify(payload);
+    var result = { content: [{ type: "text", text: text }], payload: payload };
+    if (payload !== null && typeof payload === "object") result.structuredContent = payload;
+    return result;
+  }
+
+  function cachedCopy(entry, revalidating) {
+    var copy = {};
+    Object.keys(entry.result).forEach(function (k) { copy[k] = entry.result[k]; });
+    copy.cache = { storedAt: entry.storedAt, revalidating: !!revalidating };
+    return copy;
+  }
+
+  function notifyData(id, result) {
+    (watchers[id] || []).forEach(function (w) {
+      try { w.handler({ type: "data", result: result }); } catch (e) { /* page bug */ }
+    });
+  }
+
+  function execute(server, tool, input) {
+    var entry = registry[key(server, tool)];
+    if (!entry) {
+      return Promise.reject(mcpError("server_not_connected", server,
+        'No local source registered for "' + server + '" / "' + tool +
+        '". Call window.claudeLocal.registerTool(...) before feature code runs.'));
+    }
+    try { JSON.stringify(input === undefined ? null : input); } catch (e) {
+      return Promise.reject(mcpError("bad_request", server, "input must be plain JSON."));
+    }
+    return Promise.resolve()
+      .then(function () {
+        return entry.isStatic ? entry.source : entry.source(input === undefined ? null : input);
+      })
+      .then(function (payload) {
+        var result = envelope(payload);
+        cache[identity(server, tool, input)] = { result: result, storedAt: Date.now() };
+        return result;
+      })
+      .catch(function (e) {
+        if (e && e.code) throw e;
+        throw mcpError("tool_error", server, (e && e.message) || String(e), { result: e });
+      });
+  }
+
+  if (!root.mcp) {
+    root.mcp = {
+      callTool: function (server, tool, input, options) {
+        if (typeof server !== "string" || typeof tool !== "string") {
+          return Promise.reject(mcpError("bad_request", undefined, "server and tool must be strings."));
+        }
+        var opts = options || {};
+        var id = identity(server, tool, input);
+        var entry = cache[id];
+        var staleTime = 0;
+        var refresh = false;
+        if (opts.cache && typeof opts.cache === "object") {
+          staleTime = Math.min(opts.cache.staleTime || 0, 300000);
+          refresh = !!opts.cache.refresh;
+        }
+        if (opts.cache === false) entry = null;
+        if (refresh) entry = null;
+        if (entry && Date.now() - entry.storedAt < staleTime) {
+          return Promise.resolve(cachedCopy(entry, false));
+        }
+        return execute(server, tool, input).then(function (result) {
+          notifyData(id, result);
+          return result;
+        });
+      },
+
+      watchTool: function (server, tool, input, handler, options) {
+        if (typeof handler !== "function") {
+          throw new TypeError("watchTool handler must be a function.");
+        }
+        var opts = options || {};
+        var id = identity(server, tool, input);
+        var w = { handler: handler, timer: null, refresh: null };
+        (watchers[id] = watchers[id] || []).push(w);
+
+        w.refresh = function () {
+          execute(server, tool, input)
+            .then(function (result) { notifyData(id, result); })
+            .catch(function (err) {
+              try { w.handler({ type: "error", error: err }); } catch (e) { /* page bug */ }
+            });
+        };
+
+        Promise.resolve().then(function () {
+          var entry = cache[id];
+          if (entry) {
+            try { w.handler({ type: "data", result: cachedCopy(entry, false) }); } catch (e) { /* page bug */ }
+          } else {
+            w.refresh();
+          }
+        });
+
+        if (opts.refetchInterval) {
+          w.timer = setInterval(w.refresh, Math.max(5000, opts.refetchInterval));
+        }
+
+        var done = false;
+        return function unsubscribe() {
+          if (done) return;
+          done = true;
+          if (w.timer) clearInterval(w.timer);
+          watchers[id] = (watchers[id] || []).filter(function (x) { return x !== w; });
+        };
+      },
+
+      invalidate: function (server, tool, input) {
+        Object.keys(cache).forEach(function (id) {
+          var match = true;
+          if (server !== undefined) match = id.indexOf(server + SEP) === 0;
+          if (match && tool !== undefined) match = id.indexOf(key(server, tool) + SEP) === 0;
+          if (match && input !== undefined) match = id === identity(server, tool, input);
+          if (match) {
+            delete cache[id];
+            var subs = watchers[id] || [];
+            if (subs.length) subs[0].refresh();
+          }
+        });
+        return Promise.resolve();
+      },
+
+      listTools: function () {
+        var byServer = {};
+        Object.keys(registry).forEach(function (k) {
+          var parts = k.split(SEP);
+          (byServer[parts[0]] = byServer[parts[0]] || []).push({
+            name: parts[1],
+            description: registry[k].description || ""
+          });
+        });
+        return Promise.resolve({
+          servers: Object.keys(byServer).map(function (s) {
+            return { server: s, authStatus: "connected", tools: byServer[s] };
+          })
+        });
+      }
+    };
+  }
+
+  /* --------------------------- local registration ------------------------ */
+
+  window.claudeLocal = window.claudeLocal || {};
+  window.claudeLocal.registerTool = function (server, tool, source, opts) {
+    if (typeof server !== "string" || typeof tool !== "string") {
+      throw new TypeError("registerTool(server, tool, source): server and tool must be strings.");
+    }
+    registry[key(server, tool)] = {
+      source: source,
+      isStatic: typeof source !== "function",
+      description: (opts && opts.description) || ""
+    };
+  };
+})();

package/agents-config/skills/use-artifacts/scripts/create_artifact.py

@@ -271,7 +271,7 @@ TODO: Record how the artifact was opened or tested, including browser/runtime ch
 def main() -> int:
     parser = argparse.ArgumentParser(description="Create a local HTML artifact workspace.")
     parser.add_argument("title", help="Short artifact title or slug")
-    parser.add_argument("--style", default="black-grid", help="use-style style name")
+    parser.add_argument("--style", default="custom", help="style label recorded in the manifest (requested, project:<app-name>, or subject-specific)")
     parser.add_argument("--kind", default="thinking", help="artifact kind")
     args = parser.parse_args()
 

package/agents-config/skills/use-delegate/SKILL.md

@@ -1,6 +1,10 @@
 ---
 name: use-delegate
 description: "Delegation mode: the host agent (Claude or Codex) plans and reviews while heavy work runs on cheap executors: OpenCode Kimi K3, Codex GPT-5.6 terra/sol. Use when the user invokes /use-delegate, says 'use delegate', 'delegate mode', 'orchestrator mode', or wants to save tokens/rate limits."
+disable-model-invocation: true
+metadata:
+  opencode/autoinvoke: "false"
+  opencode/slash: "true"
 ---
 
 # Use Delegate

package/agents-config/skills/use-delegate/agents/openai.yaml

@@ -0,0 +1,10 @@
+interface:
+  display_name: "Use Delegate"
+  short_description: "Delegate heavy work to OpenCode Kimi K3 and Codex"
+  icon_small: "./assets/codex-icon.svg"
+  icon_large: "./assets/codex-icon.svg"
+  brand_color: "#802F83"
+  default_prompt: "Use $use-delegate to orchestrate this task through cheap executors."
+
+policy:
+  allow_implicit_invocation: false

package/agents-config/skills/use-delegate/assets/codex-icon.svg

@@ -0,0 +1,20 @@
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="use-delegate skill icon"
+  class="lucide lucide-bot"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M12 8V4H8" />
+  <rect width="16" height="12" x="4" y="8" rx="2" />
+  <path d="M2 14h2" />
+  <path d="M20 14h2" />
+  <path d="M15 13v2" />
+  <path d="M9 13v2" />
+</svg>

package/agents-config/skills/use-goal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: use-goal
-description: Use when the user asks to create, draft, set, start, or refine a Codex or Claude Code /goal objective for persistent multi-turn work.
+description: Use when the user asks to create, draft, set, start, or refine a Codex or Claude Code `/goal` objective for persistent multi-turn work.
 ---
 
 # Use Goal
@@ -31,11 +31,31 @@ If Goal tools are available in Codex, use them rather than only printing a slash
 
 ## Goal Shape
 
-Before writing or creating the Goal, think through the verification strategy. Inspect repository docs, package scripts, tests, CI config, benchmark scripts, failing logs, linked issue text, plans, or referenced files when the evidence surface is not obvious.
+Before writing or creating the Goal, think through the verification strategy. Do a short discovery pass when the evidence surface is not already obvious:
 
-Identify which command, artifact, report, screenshot, benchmark, source document, or manual check can prove completion. Prefer existing project commands and documented workflows over invented validation. If no reliable verification surface exists, ask one concise question or make the Goal explicitly require creating one.
+- Inspect repository docs, package scripts, test commands, CI config, benchmark scripts, failing logs, linked issue text, plans, or referenced files.
+- Identify which command, artifact, report, screenshot, benchmark, source document, or manual check can prove completion.
+- For external libraries, APIs, or current product behavior, use the appropriate docs/research skill before relying on memory.
+- Prefer existing project commands and documented workflows over inventing new validation.
+- If no reliable verification surface exists, ask one concise question or make the Goal explicitly require creating one.
 
-Write one compact objective with the outcome, verification surface, constraints, boundaries, iteration policy, and blocked stop condition. For long-running implementation work, include the files to inspect first, exact proof commands, checkpoint behavior, and a short progress log requirement.
+For broad refactors, deletions, migrations, moving files, or "remove all X" goals, read `references/verification-harnesses.md` before creating the Goal. Default to a measurable harness: establish a baseline count/list first, then make the Goal continue until the validation command exits successfully at the target condition, such as count `0`.
+
+Write the Goal as a compact, well-formatted contract with these fields embedded in natural language:
+
+1. Outcome: what must be true when the work is done.
+2. Verification surface: the tests, commands, benchmarks, artifacts, reports, logs, source material, or other concrete evidence that proves it.
+3. Constraints: what must not regress or be violated.
+4. Boundaries: allowed files, tools, repositories, data, and resources when relevant.
+5. Iteration policy: how to choose the next best action after each attempt.
+6. Blocked stop condition: when to stop and what to report if no defensible path remains.
+
+For long-running implementation work, also include:
+
+- one objective and one stopping condition
+- the files, docs, issue, logs, or plan the agent should inspect first
+- the commands or artifacts that prove progress
+- checkpoint behavior and a short progress log requirement
 
 Prefer this pattern:
 
@@ -43,18 +63,59 @@ Prefer this pattern:
 <desired end state>, verified by <specific evidence>, while preserving <constraints>. Use <allowed inputs, tools, or boundaries>. Between iterations, <how to choose and record the next best action>. If blocked or no valid paths remain, stop with <attempted paths, evidence gathered, blocker, and next input needed>.
 ```
 
+For implementation Goals, include exact command names when known:
+
+```text
+<desired end state>, verified by `<test or build command>` and <artifact/manual check>, while preserving <constraints>. First inspect <files/docs/logs>. Work in checkpoints: after each change, run the narrowest relevant verification, record the result, and choose the next smallest defensible step. Stop only when the verification passes, or stop blocked with the failed command output, attempted paths, and the missing input needed.
+```
+
+Keep the objective non-empty and at most 4,000 characters. If the needed instructions are longer, create or point to a file and make the Goal refer to that file.
+
 ## Create Or Draft
 
-When goal tools are available, check the current Goal first. Create a new one only when the user explicitly asks for it and no active Goal blocks it. Do not overwrite, clear, pause, or resume an existing Goal unless explicitly requested.
+When goal tools are available, use this order:
+
+1. Call the status tool first to check whether a Goal already exists.
+2. If the user explicitly asked to create, set, start, or use a new Goal and no Goal exists, call the create tool with the refined objective.
+3. Set a token budget only when the user explicitly provided one.
+4. If a Goal already exists, do not overwrite, clear, pause, or resume it unless the user explicitly asks for that lifecycle action.
+
+For Codex, this means calling `get_goal` first, then `create_goal` with the refined objective when creation is requested and no active Goal blocks it. Read `references/codex-goal.md` before doing so.
+
+For Claude Code, `/goal <condition>` is a real slash command, but the model cannot launch it unless the harness exposes a slash-command dispatch tool. If no dispatch tool is available, return the exact manual `/goal ...` command, ask the user to paste/run it, and wait for confirmation before continuing Goal-driven work. Do not say Claude Code lacks `/goal`, do not call it Codex-only, and do not substitute a task list or goal file as equivalent unless the user explicitly asks for that fallback. Read `references/claude-code-goal.md` before drafting or instructing a Claude Code Goal.
 
 If the user asks only to draft, rewrite, explain, or refine a Goal, return the final `/goal ...` text instead of activating it.
 
+Ask a clarifying question only when a missing detail would make the Goal unverifiable or unsafe. Prefer one concise question. Otherwise infer conservative defaults from the repository, task, and available evidence.
+
 ## Evidence Rules
 
-Completion must be evidence-based. Do not mark a Goal complete because the work seems likely done, because a budget is exhausted, or because no more work is planned. Only mark it complete after verifying the stated stopping condition. If blocked, report the attempted paths, evidence gathered, blocker, and exact input or external change needed.
+Completion must be evidence-based. Do not mark a Goal complete because the work seems likely done. First compare the objective to concrete evidence such as changed files, command output, tests, benchmarks, generated artifacts, logs, or source-backed research findings.
+
+If a budget limit is reached, stop substantive work, summarize progress and blockers, and identify the next useful step. Do not treat budget exhaustion as completion.
+
+If blocked, report the attempted paths, evidence gathered, blocker, and exact input or external change that would unlock progress.
+
+If status reports become vague, tighten the Goal instead of adding more one-off instructions. Name the current checkpoint, what was verified, what remains, and what should cause a pause.
+
+Only mark a Goal complete after verifying the stated stopping condition. Only mark it blocked when the same blocking condition has repeated enough that no meaningful progress is possible without user input or an external change.
 
 ## References
 
-- `references/codex-goal.md`: Codex Goal mode, tools, lifecycle, and completion rules.
-- `references/claude-code-goal.md`: Claude Code `/goal` command, evaluator, and manual activation.
-- `references/verification-harnesses.md`: measurable validation for refactors, deletions, migrations, and moves.
+- `references/codex-goal.md`: Use for Codex Goal mode, `get_goal` / `create_goal`, CLI/app `/goal`, feature setup, and completion/blocking rules.
+- `references/claude-code-goal.md`: Use for Claude Code manual `/goal`, evaluator behavior, requirements, status, clear/resume behavior, and non-interactive usage.
+- `references/verification-harnesses.md`: Use for measurable refactor, deletion, migration, move, rename, dependency-removal, and "remove all X" Goals.
+
+## Good Examples
+
+```text
+/goal Reduce p95 checkout latency below 120 ms, verified by the checkout benchmark, while keeping the correctness suite green. Use only the checkout service, benchmark fixtures, and related tests. Between iterations, record what changed, what the benchmark showed, and the next best experiment to try. If the benchmark cannot run or no valid paths remain, stop with the attempted paths, the evidence gathered, the blocker, and the next input needed.
+```
+
+```text
+/goal Make the checkout test suite pass on the current branch, verified by the repository's documented test command, while preserving public API behavior. Use the failing tests, adjacent implementation files, and existing test helpers. Between iterations, inspect the latest failure, make the smallest defensible change, and rerun the relevant test surface. If no valid path remains, stop with the failures, changes tried, and the missing decision or dependency.
+```
+
+```text
+/goal Produce the strongest evidence-backed reproduction report for the provided paper using available materials and local resources. Attempt the headline claims where feasible, verify outputs where possible, and end with a report that separates confirmed findings, approximate reconstructions, blocked claims, and remaining uncertainty.
+```

package/agents-config/skills/use-goal/agents/openai.yaml

@@ -1,6 +1,6 @@
 interface:
   display_name: "Use Goal"
-  short_description: "Create evidence-based Codex or Claude Code goals"
+  short_description: "Use when the user asks to create, draft, set, start, or..."
   icon_small: "./assets/codex-icon.svg"
   icon_large: "./assets/codex-icon.svg"
   brand_color: "#C70A64"

package/agents-config/skills/use-goal/assets/codex-icon.svg

@@ -1,4 +1,18 @@
-<svg role="img" aria-label="use-goal skill icon" width="64" height="64" viewBox="0 0 64 64" xmlns="http://www.w3.org/2000/svg">
-  <rect width="64" height="64" rx="16" fill="#C70A64"/>
-  <path d="M20 20h24v6H26v8h14v6H26v4h18v6H20V20Z" fill="#fff"/>
+<!-- @license lucide-static v1.24.0 - ISC -->
+<svg role="img" aria-label="use-goal skill icon"
+  class="lucide lucide-sparkles"
+  xmlns="http://www.w3.org/2000/svg"
+  width="128"
+  height="128"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="#F5F5F5"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M11.017 2.814a1 1 0 0 1 1.966 0l1.051 5.558a2 2 0 0 0 1.594 1.594l5.558 1.051a1 1 0 0 1 0 1.966l-5.558 1.051a2 2 0 0 0-1.594 1.594l-1.051 5.558a1 1 0 0 1-1.966 0l-1.051-5.558a2 2 0 0 0-1.594-1.594l-5.558-1.051a1 1 0 0 1 0-1.966l5.558-1.051a2 2 0 0 0 1.594-1.594z" />
+  <path d="M20 2v4" />
+  <path d="M22 4h-4" />
+  <circle cx="4" cy="20" r="2" />
 </svg>

package/agents-config/skills/use-goal/references/claude-code-goal.md

@@ -2,16 +2,64 @@
 
 Use this reference when the active agent is Claude Code.
 
-Official reference: https://code.claude.com/docs/en/goal
+Official reference:
 
-Claude Code uses `/goal` to set a completion condition for the current session. `/goal <condition>` starts Goal mode, `/goal` shows its state, and `/goal clear` removes it. Only one Goal can be active per session.
+- https://code.claude.com/docs/en/goal
 
-The condition must describe one measurable end state and the proof Claude must surface in the transcript. Include constraints, the files or logs to inspect first, checkpoint reporting, and a bounded blocked stop clause when useful. Goal conditions can be up to 4,000 characters.
+## Manual Activation
 
-If the harness cannot dispatch slash commands, output the exact `/goal ...` command and ask the user to paste it manually. Do not replace it with a task list or call `/goal` Claude-only.
+Claude Code has `/goal`, but the model cannot launch it unless the harness exposes a slash-command dispatch tool. If no dispatch tool is available, output the exact `/goal ...` command, ask the user to paste/run it manually, and wait for confirmation before continuing Goal-driven work.
 
-Prefer:
+Do not say Claude Code lacks `/goal`. Do not call `/goal` Codex-only. Do not replace `/goal` with a task list, TODO list, or goal file and describe it as equivalent. Those can be supporting artifacts only when the user asks for them or when they are useful after the manual `/goal` command has been provided.
+
+If the user asks to continue without manually pasting the command, continue normal work only after acknowledging that no Claude Code Goal is active.
+
+## Command Surface
+
+Claude Code uses `/goal` to set a completion condition for the current session.
+
+- `/goal <condition>` sets the Goal and immediately starts a turn using the condition as the directive.
+- `/goal` with no argument shows the current state, evaluated turns, token spend, and latest evaluator reason.
+- `/goal clear` removes the active Goal before it is met.
+- `stop`, `off`, `reset`, `none`, and `cancel` are aliases for `clear`.
+- `/clear` starts a new conversation and removes any active Goal.
+- `claude -p "/goal <condition>"` can run a Goal non-interactively until the condition is met or the process is interrupted.
+
+Only one Goal can be active per Claude Code session. Setting a new `/goal <condition>` replaces the active Goal. Do not overwrite an existing Goal unless the user explicitly asks to replace it.
+
+If an active Goal existed when a Claude Code session ended, it is restored on `--resume` or `--continue`; the condition carries over, but the timer, turn count, and token-spend baseline reset.
+
+## Requirements
+
+Claude Code `/goal` requires Claude Code v2.1.139 or later.
+
+It only runs in trusted workspaces because it uses the hooks system. It is unavailable when hooks are disabled through `disableAllHooks` or restricted through `allowManagedHooksOnly`; Claude Code should explain that condition when the command fails.
+
+## Evaluator Behavior
+
+Claude Code evaluates the Goal after each turn with a separate small fast model. A "no" result starts another turn and passes the evaluator reason as guidance. A "yes" result clears the Goal and records the achieved condition in the transcript.
+
+The evaluator does not call tools, read files, or run commands independently. It judges only the condition and what Claude has surfaced in the conversation so far. Therefore the Goal must require Claude to put the proof in the transcript.
+
+Good Claude Code Goal conditions include:
+
+- one measurable end state, such as a passing test, clean build, target count, or empty queue
+- a stated check, such as a command exiting `0`, a generated report, or a reviewed artifact
+- constraints that matter, such as files not to modify or behavior not to regress
+- a bounded stop clause when useful, such as "or stop after 20 turns with the remaining blocker"
+
+Goal conditions can be up to 4,000 characters. If the instructions are longer, put details in a file and make the Goal point to that file.
+
+## Claude Code Draft Pattern
+
+Prefer this pattern:
+
+```text
+/goal <desired end state>, verified by <proof Claude must surface in the transcript>, while preserving <constraints>. First inspect <files/docs/logs>. After each turn, report the current checkpoint, command/artifact result, remaining gap, and next smallest step. Stop when the proof is in the transcript, or after <bound> with attempted paths, evidence, blocker, and needed input.
+```
+
+For test or build work:
 
 ```text
-/goal <desired end state>, verified by <proof surfaced in the transcript>, while preserving <constraints>. First inspect <files/docs/logs>. After each turn, report the checkpoint, command result, remaining gap, and next smallest step. Stop when the proof is present, or after <bound> with attempted paths, evidence, blocker, and needed input.
+/goal <desired end state>, verified by `<test/build command>` exiting 0 with the relevant output included in the transcript, while preserving <constraints>. First inspect <files/logs>. After each turn, rerun the narrowest relevant check and summarize the result. Stop only when the command output proves success, or stop after <bound> with the failing output, attempted fixes, and missing input.
 ```

package/agents-config/skills/use-goal/references/codex-goal.md

@@ -1,6 +1,6 @@
 # Codex Goal Reference
 
-Use this reference when the active agent is OpenAI Codex.
+Use this reference when the active agent is OpenAI Codex, including the Codex app, IDE extension, or CLI.
 
 Official references:
 
@@ -8,8 +8,63 @@ Official references:
 - https://developers.openai.com/codex/app/commands
 - https://developers.openai.com/codex/cli/slash-commands
 
-`/goal <objective>` starts Goal mode. `/goal` views the current Goal. `/goal pause`, `/goal resume`, and `/goal clear` manage lifecycle. Objectives must be non-empty and at most 4,000 characters.
+## Command Surface
 
-When Goal tools are available, call `get_goal` before lifecycle actions and create a new Goal only when the user explicitly asks and no active Goal exists. Do not overwrite an existing Goal without explicit permission. If Goals are unavailable, tell the user to enable `[features] goals = true` or run `codex features enable goals`.
+`/goal <objective>` starts Goal mode. `/goal` views the current Goal. `/goal pause`, `/goal resume`, and `/goal clear` manage lifecycle.
 
-A strong Goal defines one objective and stopping condition, initial files/docs, exact proof commands or artifacts, non-regression constraints, checkpoint behavior, and the evidence to report if blocked.
+Goal objectives must be non-empty and at most 4,000 characters. For longer instructions, create or point to a file and make the Goal refer to that file.
+
+If `/goal` is missing, tell the user to enable Goals with:
+
+```toml
+[features]
+goals = true
+```
+
+They can also run:
+
+```bash
+codex features enable goals
+```
+
+## Tool Contract
+
+When Codex Goal tools are available, use the tools instead of printing a slash command for activation:
+
+1. Call `get_goal` before any lifecycle action.
+2. If the user asked to create, set, start, activate, or use a new Goal and no active Goal exists, call `create_goal` with the refined objective.
+3. Pass `token_budget` only when the user explicitly provided a budget.
+4. If a Goal already exists, do not overwrite, clear, pause, resume, mark complete, or mark blocked unless the user explicitly asked for that lifecycle action or the active Goal's stated status condition is actually met.
+
+Use slash-command text only when the user asks for a draft, the tool surface is unavailable, or the target is a separate Codex session.
+
+## Codex Goal Shape
+
+A strong Codex Goal should define:
+
+- one objective and one stopping condition
+- the files, docs, issue, logs, or plan Codex should inspect first
+- the commands, artifacts, screenshots, benchmarks, reports, or manual checks that prove progress
+- constraints that must not regress
+- checkpoint behavior and compact progress logging
+- the exact blocked stop condition and what evidence to report
+
+Prefer this pattern:
+
+```text
+<desired end state>, verified by <specific evidence>, while preserving <constraints>. Use <allowed inputs, tools, or boundaries>. Between iterations, <how to choose and record the next best action>. If blocked or no valid paths remain, stop with <attempted paths, evidence gathered, blocker, and next input needed>.
+```
+
+For implementation Goals, include exact commands when known:
+
+```text
+<desired end state>, verified by `<test or build command>` and <artifact/manual check>, while preserving <constraints>. First inspect <files/docs/logs>. Work in checkpoints: after each change, run the narrowest relevant verification, record the result, and choose the next smallest defensible step. Stop only when the verification passes, or stop blocked with the failed command output, attempted paths, and the missing input needed.
+```
+
+## Completion And Blocking
+
+Completion must be evidence-based. Compare the active Goal to concrete evidence in the thread: changed files, command output, tests, benchmarks, generated artifacts, logs, screenshots, or source-backed research findings.
+
+Do not mark a Goal complete because the work seems likely done, because a budget is exhausted, or because no more work is planned. Only mark it complete after verifying the stated stopping condition.
+
+Only mark a Goal blocked when the stated blocker has repeated enough that no meaningful progress is possible without user input or an external change. Report the attempted paths, gathered evidence, exact blocker, and input needed.