@the-open-engine-company/zeroshot 10.3.1 → 10.5.0

package/README.md

@@ -1,6 +1,19 @@
 # `@the-open-engine-company/zeroshot`
 
-Thin installer for the canonical `zeroshot` executable. The package selects the release archive for the current Node platform and architecture, verifies it against that release's `SHA256SUMS`, and installs only the verified executable.
+Installer for the canonical `zeroshot` executable and agent skill. The package selects the release
+archive for the current Node platform and architecture, verifies it against that release's
+`SHA256SUMS`, and installs the executable.
+
+The same managed skill is installed for Codex and GitHub Copilot at
+`$HOME/.agents/skills/zeroshot/SKILL.md`, and for Claude Code at
+`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/zeroshot/SKILL.md`. Reinstalling updates an unchanged
+managed copy. A conflicting or edited skill is preserved; installation fails with the exact path so
+the conflict cannot pass unnoticed.
+
+When set, `CLAUDE_CONFIG_DIR` must be absolute so the global skill has one stable location.
+
+npm 7 and newer do not run uninstall lifecycle scripts. After uninstalling the package, remove the
+two skill directories above manually if their `SKILL.md` files are still unmodified managed copies.
 
 Installation fails closed with `UNSUPPORTED_ZEROSHOT_HOST` when the host has no declared release target. Source compilation and cross-target substitution are not supported.
 

package/bin/zeroshot.js

@@ -11,7 +11,7 @@ try {
   const binary = path.join(__dirname, 'native', executable);
   if (!fs.existsSync(binary)) {
     throw new Error(
-      `NATIVE_BINARY_MISSING: ${binary}; reinstall @the-open-engine-company/zeroshot`
+      `NATIVE_BINARY_MISSING: ${binary}; reinstall @the-open-engine-company/zeroshot with lifecycle scripts enabled`
     );
   }
   const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });

package/install.js

@@ -2,8 +2,9 @@
 'use strict';
 
 const { install } = require('./lib/install');
+const { requireCompleteSkillInstall } = require('./lib/skills');
 
-install().catch((error) => {
+install({ onSkillResults: requireCompleteSkillInstall }).catch((error) => {
   process.stderr.write(`zeroshot install failed: ${error.message}\n`);
   process.exitCode = 1;
 });

package/lib/install.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const https = require('https');
 const path = require('path');
 const { URL } = require('url');
+const { installSkills } = require('./skills');
 const {
   archiveName,
   extractExecutable,
@@ -120,6 +121,13 @@ async function install(options = {}) {
   } finally {
     fs.rmSync(temporary, { force: true });
   }
+  const skillResults = installSkills({
+    packageRoot,
+    homeDirectory: options.homeDirectory,
+    environment: options.environment,
+    uid: options.uid,
+  });
+  if (options.onSkillResults) options.onSkillResults(skillResults);
   return destination;
 }
 

package/lib/skills.js

@@ -0,0 +1,196 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const SKILL_NAME = 'zeroshot';
+const MANAGED_MARKER = 'managed by @the-open-engine-company/zeroshot';
+const MANAGED_PATTERN =
+  /^<!-- managed by @the-open-engine-company\/zeroshot; sha256=([a-f0-9]{64}) -->\n/;
+const TARGETS = Object.freeze([
+  Object.freeze({ id: 'agents', label: 'Codex/GitHub Copilot' }),
+  Object.freeze({ id: 'claude', label: 'Claude Code' }),
+]);
+
+function digest(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function frontmatterEnd(document) {
+  if (!document.startsWith('---\n')) {
+    throw new Error('SKILL_INVALID: SKILL.md needs YAML frontmatter');
+  }
+  const closing = document.indexOf('\n---\n', 4);
+  if (closing === -1) throw new Error('SKILL_INVALID: SKILL.md frontmatter is not closed');
+  return closing + 5;
+}
+
+function managedDocument(canonical) {
+  const offset = frontmatterEnd(canonical);
+  const marker = `<!-- ${MANAGED_MARKER}; sha256=${digest(canonical)} -->\n`;
+  return `${canonical.slice(0, offset)}${marker}${canonical.slice(offset)}`;
+}
+
+function managedSource(document) {
+  let offset;
+  try {
+    offset = frontmatterEnd(document);
+  } catch {
+    return null;
+  }
+  const match = MANAGED_PATTERN.exec(document.slice(offset));
+  if (!match) return null;
+  const source = `${document.slice(0, offset)}${document.slice(offset + match[0].length)}`;
+  return digest(source) === match[1] ? source : null;
+}
+
+function locationResults(homeDirectory, environment) {
+  if (!homeDirectory || !path.isAbsolute(homeDirectory)) {
+    return TARGETS.map((target) => ({
+      ...target,
+      status: 'failed',
+      message: 'user home is unavailable or not absolute',
+    }));
+  }
+  const shared = path.join(homeDirectory, '.agents', 'skills', SKILL_NAME);
+  const configuredClaude = environment.CLAUDE_CONFIG_DIR;
+  const claudeRoot = configuredClaude || path.join(homeDirectory, '.claude');
+  return [
+    { ...TARGETS[0], directory: shared },
+    path.isAbsolute(claudeRoot)
+      ? { ...TARGETS[1], directory: path.join(claudeRoot, 'skills', SKILL_NAME) }
+      : {
+          ...TARGETS[1],
+          status: 'failed',
+          message: 'CLAUDE_CONFIG_DIR must be absolute during package installation',
+        },
+  ];
+}
+
+function lstatIfPresent(filename) {
+  try {
+    return fs.lstatSync(filename);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function atomicWrite(filename, contents) {
+  const temporary = path.join(
+    path.dirname(filename),
+    `.SKILL.md.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`
+  );
+  try {
+    fs.writeFileSync(temporary, contents, { encoding: 'utf8', flag: 'wx', mode: 0o644 });
+    fs.renameSync(temporary, filename);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+function inspectExisting(filename, canonical, managed) {
+  const existingStat = lstatIfPresent(filename);
+  if (!existingStat) return { status: 'installed' };
+  if (!existingStat.isFile() || existingStat.isSymbolicLink()) {
+    return { status: 'conflict', message: 'SKILL.md is not a regular file' };
+  }
+  const existing = fs.readFileSync(filename, 'utf8');
+  if (existing === managed) return { status: 'unchanged' };
+  if (existing === canonical || managedSource(existing) !== null) return { status: 'updated' };
+  return {
+    status: 'conflict',
+    message: 'existing skill is not an unmodified Zeroshot-managed copy',
+  };
+}
+
+function installAt(location, canonical, managed) {
+  if (location.status === 'failed') return location;
+  const filename = path.join(location.directory, 'SKILL.md');
+  try {
+    fs.mkdirSync(location.directory, { recursive: true });
+    const directory = fs.lstatSync(location.directory);
+    if (!directory.isDirectory() || directory.isSymbolicLink()) {
+      return {
+        ...location,
+        path: filename,
+        status: 'conflict',
+        message: 'skill directory is not a regular directory',
+      };
+    }
+    const inspection = inspectExisting(filename, canonical, managed);
+    if (inspection.status === 'unchanged' || inspection.status === 'conflict') {
+      return { ...location, path: filename, ...inspection };
+    }
+    atomicWrite(filename, managed);
+    return { ...location, path: filename, status: inspection.status };
+  } catch (error) {
+    return { ...location, path: filename, status: 'failed', message: error.message };
+  }
+}
+
+function installSkills(options = {}) {
+  const packageRoot = options.packageRoot || path.resolve(__dirname, '..');
+  const source = path.join(packageRoot, 'skills', SKILL_NAME, 'SKILL.md');
+  const canonical = fs.readFileSync(source, 'utf8');
+  const managed = managedDocument(canonical);
+  const homeDirectory = options.homeDirectory ?? os.homedir();
+  const environment = options.environment ?? process.env;
+  const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined);
+  const locations = locationResults(homeDirectory, environment);
+  if (uid === 0 && environment.SUDO_USER && environment.SUDO_USER !== 'root') {
+    return locations.map((location) => ({
+      ...location,
+      status: 'failed',
+      message:
+        'refusing to create user skills from a sudo npm install; use a user-owned npm prefix',
+    }));
+  }
+  return locations.map((location) => installAt(location, canonical, managed));
+}
+
+function humanList(values) {
+  if (values.length < 2) return values[0] || '';
+  if (values.length === 2) return `${values[0]} and ${values[1]}`;
+  return `${values.slice(0, -1).join(', ')}, and ${values.at(-1)}`;
+}
+
+function reportSkillResults(results, output = process.stdout, errorOutput = process.stderr) {
+  const ready = results.filter(({ status }) =>
+    ['installed', 'updated', 'unchanged'].includes(status)
+  );
+  const incomplete = results.filter(
+    ({ status }) => !['installed', 'updated', 'unchanged'].includes(status)
+  );
+  if (ready.length > 0) {
+    output.write(`zeroshot skill ready for ${humanList(ready.map(({ label }) => label))}\n`);
+  }
+  for (const result of incomplete) {
+    const location = result.path ? `${result.path}: ` : '';
+    errorOutput.write(
+      `zeroshot skill not installed for ${result.label}: ${location}${result.message}\n`
+    );
+  }
+  if (incomplete.length > 0) {
+    errorOutput.write(
+      'Re-run npm install with lifecycle scripts enabled after resolving these paths.\n'
+    );
+  }
+  return incomplete.length === 0;
+}
+
+function requireCompleteSkillInstall(results, output, errorOutput) {
+  if (!reportSkillResults(results, output, errorOutput)) {
+    throw new Error('SKILL_INSTALL_INCOMPLETE: Zeroshot skill installation was incomplete');
+  }
+}
+
+module.exports = {
+  installSkills,
+  managedDocument,
+  managedSource,
+  reportSkillResults,
+  requireCompleteSkillInstall,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine-company/zeroshot",
-  "version": "10.3.1",
+  "version": "10.5.0",
   "description": "Verified prebuilt binary installer for the standalone Zeroshot engine",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,7 @@
   "files": [
     "bin/",
     "lib/",
+    "skills/",
     "install.js",
     "targets.json",
     "README.md"

package/skills/zeroshot/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: zeroshot
+description: Use Zeroshot to prepare, run, observe, or troubleshoot explicit multi-agent software work locally or on Zeroshot Cloud. Apply when the user names Zeroshot or asks about its CLI; do not route ordinary local work into Zeroshot without that intent.
+---
+
+# Zeroshot
+
+Zeroshot executes an explicit graph of software agents. Workers make changes; independent verifiers
+judge the evidence, and the graph decides when to repair or deliver. A successful run means the
+graph reached its declared outcome; it does not always mean a pull request was created or merged.
+
+Use the installed CLI help as the exact contract when commands differ from this overview.
+
+## Shape the task
+
+Before submitting, inspect the request, repository guidance, existing issue, and enough code to know:
+
+- the desired behavior and observable success;
+- material constraints and behavior that must remain unchanged;
+- whether a separate worker could implement it and a verifier could judge it.
+
+Fill gaps from available evidence. Choose routine technical details without interrogating the user.
+If an unresolved product choice would materially change the outcome, propose the narrowest supported
+interpretation and ask one focused question. Do not submit while that decision remains unanswered.
+Suggest separate tasks only for independently useful outcomes or real prerequisites.
+
+Never start a Zeroshot run merely because the skill is available. The user must ask to use Zeroshot.
+A worker already executing inside a Zeroshot run should perform its assigned work directly, not start
+another run. A failed Cloud run does not authorize silently implementing the task locally.
+
+## Choose the target
+
+- Local execution omits `--target` and is the only mode that edits the invoking worktree directly.
+- Zeroshot Cloud is built in. Sign in once with `zeroshot target login cloud`, then use
+  `--target cloud` explicitly on Cloud commands.
+- Do not add or set up the built-in Cloud target. Named targets store endpoints and login identity,
+  not repository configuration.
+
+## Reuse profiles and connections
+
+Prefer a saved profile over inventing a graph or runtime. Inspect its input, runtime, and delivery
+behavior before constructing a run:
+
+```console
+zeroshot profile list --target cloud --scope user
+zeroshot profile list --target cloud --scope org
+zeroshot profile show NAME --target cloud --scope org
+zeroshot connection list --target cloud --scope user
+zeroshot connection list --target cloud --scope org
+```
+
+Do not assume a profile creates a pull request. `--pr` requests pull-request delivery and `--ship`
+requests merge delivery when materializing a compatible template; use either only when intended.
+
+## Validate and submit
+
+Put profile input in a JSON file matching the profile's declared schema. Use a stable, non-secret
+submission key for safe retries:
+
+```console
+zeroshot run --title "TASK" --profile org:NAME --input input.json \
+  --target cloud --submission-key KEY --validate-only
+
+zeroshot run --title "TASK" --profile org:NAME --input input.json \
+  --target cloud --submission-key KEY
+```
+
+`--validate-only` materializes and validates without starting a run. A named Cloud profile must
+still be fetched from the target first, so this command requires Cloud access. It does not prove
+connection availability.
+
+For named targets, Zeroshot resolves source from the invoking Git worktree's attached upstream.
+Without an upstream, it requires exactly one GitHub remote. Detached worktrees require explicit
+repository and branch values. Override source only when needed:
+
+```console
+--target cloud --repository OWNER/REPOSITORY --branch BRANCH --revision SHA
+```
+
+Cloud receives the remote revision, not uncommitted files. Check relevant dirty or unpushed work and
+never push or omit it without authorization. Confirm the exact repository, branch, revision, target,
+profile, and delivery intent reported for the run.
+
+## Observe and troubleshoot
+
+Keep the run ID and target:
+
+```console
+zeroshot status RUN_ID --target cloud
+zeroshot watch RUN_ID --target cloud
+zeroshot logs RUN_ID --target cloud
+```
+
+A foreground run streams events. Ctrl-C detaches observation without stopping the run. Use
+`zeroshot force-stop RUN_ID --target cloud` only when the user explicitly intends to stop it.
+
+For command errors, check `zeroshot --version` and the relevant `--help`; do not revive removed
+commands such as `target setup`. If login cannot retain credentials, fix the credential store before
+requesting another device code; `zeroshot target login --help` lists the supported
+`ZEROSHOT_CREDENTIAL_STORE` modes.
+
+For `connection_unavailable`, list connections for the same target and both relevant scopes. A
+static `connection set` replaces the whole named connection, so supply every required field through
+repeated `--field` prompts or JSON stdin. Never put secret values in arguments, task files, runtime
+configuration, issues, or logs.
+
+After an uncertain submission response, reconcile by submission key before retrying. Do not create a
+second logical run. Report submitted, running, verified, delivered, failed, and stopped states
+accurately; submission alone is not completion.