trackops 1.0.1 → 1.1.0

package/scripts/smoke-tests.js

@@ -0,0 +1,445 @@
+#!/usr/bin/env node
+
+const assert = require("assert");
+const fs = require("fs");
+const http = require("http");
+const net = require("net");
+const os = require("os");
+const path = require("path");
+const { spawn, spawnSync } = require("child_process");
+
+const ROOT = path.resolve(__dirname, "..");
+const BIN = path.join(ROOT, "bin", "trackops.js");
+const SKILL_VALIDATE = path.join(ROOT, "scripts", "validate-skill.js");
+const SKILL_BOOTSTRAP = path.join(ROOT, "skills", "trackops", "scripts", "bootstrap-trackops.js");
+
+function getNpmCommand() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
+function runNode(args, cwd, envOverrides = {}) {
+  const result = spawnSync(process.execPath, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, ...envOverrides },
+  });
+  assert.strictEqual(result.status, 0, result.stderr || result.stdout || `fallo ejecutando ${args.join(" ")}`);
+  return result.stdout;
+}
+
+function runNodeResult(args, cwd, envOverrides = {}) {
+  return spawnSync(process.execPath, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, ...envOverrides },
+  });
+}
+
+function runCommand(command, args, cwd, envOverrides = {}) {
+  return spawnSync(command, args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, ...envOverrides },
+  });
+}
+
+function runNpm(args, cwd, envOverrides = {}) {
+  return spawnSync(getNpmCommand(), args, {
+    cwd,
+    encoding: "utf8",
+    env: { ...process.env, ...envOverrides },
+    shell: process.platform === "win32",
+  });
+}
+
+function git(args, cwd) {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+  assert.strictEqual(result.status, 0, result.stderr || result.stdout || `git ${args.join(" ")} fallo`);
+  return result.stdout.trim();
+}
+
+function wait(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function get(port, pathname, host = "127.0.0.1") {
+  return new Promise((resolve, reject) => {
+    const req = http.get({ host, port, path: pathname }, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => resolve({ status: res.statusCode, body }));
+    });
+    req.on("error", reject);
+  });
+}
+
+function extractLocalPort(output) {
+  const match = String(output || "").match(/- Local:\s+http:\/\/[^\s:]+:(\d+)/);
+  return match ? Number(match[1]) : null;
+}
+
+function hasExternalIpv4() {
+  return Object.values(os.networkInterfaces()).some((entries) => (
+    (entries || []).some((entry) => entry && entry.family === "IPv4" && !entry.internal)
+  ));
+}
+
+function isPortFree(port, host = "127.0.0.1") {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once("error", () => resolve(false));
+    server.once("listening", () => {
+      server.close(() => resolve(true));
+    });
+    server.listen(port, host);
+  });
+}
+
+function findFreePort(host = "127.0.0.1") {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(0, host, () => {
+      const address = server.address();
+      const port = typeof address === "object" && address ? address.port : null;
+      server.close((closeError) => {
+        if (closeError) reject(closeError);
+        else resolve(port);
+      });
+    });
+  });
+}
+
+function occupyPort(port, host = "127.0.0.1") {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("busy");
+    });
+    server.once("error", reject);
+    server.listen(port, host, () => resolve(server));
+  });
+}
+
+function startDashboard(cwd, args = [], envOverrides = {}) {
+  const env = { ...process.env, ...envOverrides };
+  const child = spawn(process.execPath, [BIN, "dashboard", ...args], {
+    cwd,
+    env,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+
+  let output = "";
+  child.stdout.on("data", (chunk) => { output += chunk.toString("utf8"); });
+  child.stderr.on("data", (chunk) => { output += chunk.toString("utf8"); });
+
+  return {
+    child,
+    output: () => output,
+  };
+}
+
+async function waitForDashboard(session) {
+  const startedAt = Date.now();
+
+  while (Date.now() - startedAt < 15000) {
+    if (session.child.exitCode != null) {
+      throw new Error(`el dashboard termino antes de iniciar:\n${session.output()}`);
+    }
+
+    const port = extractLocalPort(session.output());
+    if (port) {
+      try {
+        const response = await get(port, "/api/state");
+        if (response.status === 200) {
+          return { port, output: session.output() };
+        }
+      } catch (_error) {
+        // sigue esperando
+      }
+    }
+
+    await wait(250);
+  }
+
+  throw new Error(`el dashboard no respondio a tiempo:\n${session.output()}`);
+}
+
+async function stopDashboard(session) {
+  if (!session || !session.child || session.child.exitCode != null) return;
+  session.child.kill("SIGTERM");
+  await wait(500);
+  if (session.child.exitCode == null) {
+    session.child.kill("SIGKILL");
+    await wait(250);
+  }
+}
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+
+function packCurrentPackage(tempRoot) {
+  const result = runNpm(["pack", ROOT], tempRoot);
+  assert.strictEqual(result.status, 0, result.stderr || result.stdout || "npm pack fallo");
+  const tarballName = String(result.stdout || "").trim().split(/\r?\n/).pop();
+  const tarballPath = path.join(tempRoot, tarballName);
+  assert.ok(fs.existsSync(tarballPath), `no se encontro el tarball ${tarballPath}`);
+  return tarballPath;
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function initGitRepo(repo) {
+  git(["init"], repo);
+  git(["config", "user.email", "smoke@example.com"], repo);
+  git(["config", "user.name", "Smoke Runner"], repo);
+}
+
+function commitAll(repo, message) {
+  git(["add", "."], repo);
+  git(["commit", "-m", message], repo);
+}
+
+async function main() {
+  runNode([SKILL_VALIDATE], ROOT);
+
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "trackops-smoke-"));
+  const tarballPath = packCurrentPackage(tempRoot);
+  const packageVersion = readJson(path.join(ROOT, "package.json")).version;
+
+  const bootstrapHome = path.join(tempRoot, "bootstrap-home");
+  const bootstrapPrefix = path.join(tempRoot, "bootstrap-prefix");
+  fs.mkdirSync(bootstrapHome, { recursive: true });
+  fs.mkdirSync(bootstrapPrefix, { recursive: true });
+
+  const bootstrapEnv = {
+    TRACKOPS_BOOTSTRAP_HOME: bootstrapHome,
+    TRACKOPS_BOOTSTRAP_PREFIX: bootstrapPrefix,
+    TRACKOPS_BOOTSTRAP_INSTALL_SOURCE: tarballPath,
+  };
+
+  const firstBootstrap = runCommand(process.execPath, [SKILL_BOOTSTRAP], tempRoot, bootstrapEnv);
+  assert.strictEqual(firstBootstrap.status, 0, firstBootstrap.stderr || firstBootstrap.stdout || "bootstrap skill fallo");
+  assert.match(firstBootstrap.stdout, /TrackOps runtime .* is ready/i);
+
+  const runtimeStamp = readJson(path.join(bootstrapHome, ".trackops", "runtime.json"));
+  assert.strictEqual(runtimeStamp.runtimeVersion, packageVersion);
+  assert.strictEqual(runtimeStamp.skill, "trackops");
+  assert.strictEqual(runtimeStamp.bootstrapPolicy, "first_use");
+
+  const installedCli = path.join(bootstrapPrefix, "node_modules", "trackops", "bin", "trackops.js");
+  assert.ok(fs.existsSync(installedCli), "el runtime instalado debe existir dentro del prefijo aislado");
+  const installedVersion = runNode([installedCli, "--version"], tempRoot);
+  assert.strictEqual(installedVersion.trim(), packageVersion);
+
+  const secondBootstrap = runCommand(process.execPath, [SKILL_BOOTSTRAP], tempRoot, bootstrapEnv);
+  assert.strictEqual(secondBootstrap.status, 0, secondBootstrap.stderr || secondBootstrap.stdout || "bootstrap idempotente fallo");
+  assert.match(secondBootstrap.stdout, /already ready/i);
+
+  const untouchedRepo = path.join(tempRoot, "untouched-repo");
+  fs.mkdirSync(untouchedRepo, { recursive: true });
+  const bootstrapNoRepoMutation = runCommand(process.execPath, [SKILL_BOOTSTRAP], untouchedRepo, bootstrapEnv);
+  assert.strictEqual(bootstrapNoRepoMutation.status, 0, bootstrapNoRepoMutation.stderr || bootstrapNoRepoMutation.stdout || "bootstrap repetido fallo");
+  assert.ok(!fs.existsSync(path.join(untouchedRepo, "project_control.json")), "la skill global no debe crear artefactos de proyecto por si sola");
+
+  const helpOutput = runNode([BIN, "help"], ROOT);
+  assert.doesNotMatch(helpOutput, /\btrackops agent\b/i);
+  assert.match(helpOutput, /workspace status\|migrate/i);
+  assert.match(helpOutput, /env status\|sync/i);
+  assert.match(helpOutput, /release \[--push\]/i);
+
+  const versionOutput = runNode([BIN, "--version"], ROOT);
+  assert.strictEqual(versionOutput.trim(), packageVersion);
+
+  const splitProject = path.join(tempRoot, "split-demo");
+  fs.mkdirSync(splitProject, { recursive: true });
+  runNode([BIN, "init"], splitProject);
+
+  assert.ok(fs.existsSync(path.join(splitProject, ".trackops-workspace.json")));
+  assert.ok(fs.existsSync(path.join(splitProject, ".env")));
+  assert.ok(fs.existsSync(path.join(splitProject, ".env.example")));
+  assert.ok(fs.existsSync(path.join(splitProject, "app")));
+  assert.ok(fs.existsSync(path.join(splitProject, "ops", "project_control.json")));
+  assert.ok(fs.existsSync(path.join(splitProject, "app", ".env")));
+  assert.ok(fs.existsSync(path.join(splitProject, "app", ".env.example")));
+  assert.ok(!fs.existsSync(path.join(splitProject, "project_control.json")));
+  assert.ok(!fs.existsSync(path.join(splitProject, "task_plan.md")));
+
+  const splitControl = readJson(path.join(splitProject, "ops", "project_control.json"));
+  assert.strictEqual(splitControl.meta.workspace.layout, "split");
+  assert.strictEqual(splitControl.meta.environment.rootEnvFile, ".env");
+
+  const statusFromWorkspace = runNode([BIN, "status"], splitProject);
+  const statusFromApp = runNode([BIN, "status"], path.join(splitProject, "app"));
+  const statusFromOps = runNode([BIN, "status"], path.join(splitProject, "ops"));
+  assert.match(statusFromWorkspace, /Layout: split/);
+  assert.match(statusFromApp, /Layout: split/);
+  assert.match(statusFromOps, /Layout: split/);
+
+  const nextOutput = runNode([BIN, "next"], splitProject);
+  assert.match(nextOutput, /ops-bootstrap/);
+
+  runNode([BIN, "sync"], splitProject);
+  for (const file of ["task_plan.md", "progress.md", "findings.md"]) {
+    assert.ok(fs.existsSync(path.join(splitProject, "ops", file)), `${file} no fue generado en ops/`);
+  }
+
+  const envStatus = runNode([BIN, "env", "status"], splitProject);
+  assert.match(envStatus, /Root \.env:/);
+  assert.match(envStatus, /App bridge:/);
+
+  const nonEmptyProject = path.join(tempRoot, "non-empty");
+  fs.mkdirSync(nonEmptyProject, { recursive: true });
+  writeJson(path.join(nonEmptyProject, "package.json"), { name: "existing-app", version: "1.0.0" });
+  const initNonEmpty = runNodeResult([BIN, "init"], nonEmptyProject);
+  assert.notStrictEqual(initNonEmpty.status, 0, "init debe abortar en directorios no vacios");
+  assert.match(`${initNonEmpty.stdout}\n${initNonEmpty.stderr}`, /workspace migrate/i);
+
+  writeJson(path.join(splitProject, "app", "package.json"), {
+    name: "split-demo",
+    version: "1.0.0",
+    dependencies: { openai: "^4.0.0" },
+    scripts: { test: "echo ok" },
+  });
+  runNode([BIN, "opera", "install", "--locale", "en", "--non-interactive"], splitProject);
+
+  assert.ok(fs.existsSync(path.join(splitProject, "ops", "genesis.md")));
+  assert.ok(fs.existsSync(path.join(splitProject, "ops", ".agent", "hub", "agent.md")));
+  assert.ok(fs.existsSync(path.join(splitProject, "ops", ".agents", "skills", "_registry.md")));
+  assert.ok(!fs.existsSync(path.join(splitProject, "genesis.md")));
+
+  const operaControl = readJson(path.join(splitProject, "ops", "project_control.json"));
+  assert.strictEqual(operaControl.meta.locale, "en");
+  assert.strictEqual(operaControl.meta.opera.installed, true);
+  assert.ok(operaControl.meta.environment.requiredKeys.includes("OPENAI_API_KEY"));
+  const envRootText = fs.readFileSync(path.join(splitProject, ".env"), "utf8");
+  assert.match(envRootText, /OPENAI_API_KEY=/);
+
+  const defaultPortFree = await isPortFree(4173);
+  const defaultDashboard = startDashboard(splitProject);
+
+  try {
+    const ready = await waitForDashboard(defaultDashboard);
+    const state = await get(ready.port, "/api/state");
+    const envPayload = await get(ready.port, "/api/env");
+    const localSkills = await get(ready.port, "/api/skills/local");
+    const discoverSkills = await get(ready.port, "/api/skills/discover");
+
+    assert.strictEqual(state.status, 200);
+    assert.strictEqual(envPayload.status, 200);
+    assert.strictEqual(localSkills.status, 200);
+    assert.strictEqual(discoverSkills.status, 200);
+
+    const statePayload = JSON.parse(state.body);
+    assert.strictEqual(statePayload.project.layout, "split");
+    assert.strictEqual(statePayload.project.workspaceRoot, splitProject);
+    assert.strictEqual(statePayload.project.appRoot, path.join(splitProject, "app"));
+    assert.strictEqual(statePayload.project.opsRoot, path.join(splitProject, "ops"));
+    assert.ok(Array.isArray(statePayload.env.requiredKeys));
+    assert.ok(!Object.prototype.hasOwnProperty.call(statePayload.env, "values"));
+
+    const envState = JSON.parse(envPayload.body);
+    assert.ok(envState.requiredKeys.includes("OPENAI_API_KEY"));
+    assert.ok(envState.missingKeys.includes("OPENAI_API_KEY"));
+
+    if (defaultPortFree) {
+      assert.strictEqual(ready.port, 4173, `se esperaba usar 4173 cuando estaba libre:\n${ready.output}`);
+    }
+  } finally {
+    await stopDashboard(defaultDashboard);
+  }
+
+  const blocked4173 = await isPortFree(4173) ? await occupyPort(4173) : null;
+  const fallbackDashboard = startDashboard(splitProject);
+  try {
+    const ready = await waitForDashboard(fallbackDashboard);
+    assert.notStrictEqual(ready.port, 4173, `deberia haber evitado 4173 ocupado:\n${ready.output}`);
+    assert.match(ready.output, /Local:/);
+  } finally {
+    await stopDashboard(fallbackDashboard);
+    if (blocked4173) blocked4173.close();
+  }
+
+  const strictPort = await findFreePort();
+  const occupiedStrictPort = await occupyPort(strictPort);
+  try {
+    const strictResult = runNodeResult([BIN, "dashboard", "--strict-port", "--port", String(strictPort)], splitProject);
+    assert.notStrictEqual(strictResult.status, 0, "el dashboard deberia fallar con --strict-port si el puerto esta ocupado");
+    assert.match(`${strictResult.stdout}\n${strictResult.stderr}`, /already in use|esta en uso/i);
+  } finally {
+    occupiedStrictPort.close();
+  }
+
+  const publicPort = await findFreePort("0.0.0.0");
+  const publicDashboard = startDashboard(splitProject, ["--public", "--port", String(publicPort)]);
+  try {
+    const ready = await waitForDashboard(publicDashboard);
+    if (hasExternalIpv4()) {
+      assert.match(ready.output, /- Network:/);
+    }
+  } finally {
+    await stopDashboard(publicDashboard);
+  }
+
+  const noClipboardPort = await findFreePort();
+  const noClipboardDashboard = startDashboard(splitProject, ["--port", String(noClipboardPort)], {
+    PATH: "",
+    Path: "",
+  });
+  try {
+    const ready = await waitForDashboard(noClipboardDashboard);
+    const state = await get(ready.port, "/api/state");
+    assert.strictEqual(state.status, 200);
+  } finally {
+    await stopDashboard(noClipboardDashboard);
+  }
+
+  const legacyProject = path.join(tempRoot, "legacy-demo");
+  fs.mkdirSync(legacyProject, { recursive: true });
+  initGitRepo(legacyProject);
+  writeJson(path.join(legacyProject, "package.json"), { name: "legacy-demo", version: "1.0.0" });
+  runNode([BIN, "init", "--legacy-layout"], legacyProject);
+  runNode([BIN, "opera", "install", "--locale", "en", "--no-bootstrap"], legacyProject);
+  fs.writeFileSync(path.join(legacyProject, ".env"), "OPENAI_API_KEY=\n", "utf8");
+  fs.writeFileSync(path.join(legacyProject, ".env.example"), "OPENAI_API_KEY=\n", "utf8");
+  commitAll(legacyProject, "legacy fixture");
+
+  runNode([BIN, "workspace", "migrate"], legacyProject);
+  assert.ok(fs.existsSync(path.join(legacyProject, ".trackops-workspace.json")));
+  assert.ok(fs.existsSync(path.join(legacyProject, "app", "package.json")));
+  assert.ok(fs.existsSync(path.join(legacyProject, "ops", "project_control.json")));
+  assert.ok(fs.existsSync(path.join(legacyProject, ".env")));
+  assert.ok(fs.existsSync(path.join(legacyProject, "app", ".env")));
+  assert.ok(!fs.existsSync(path.join(legacyProject, "project_control.json")));
+  const migratedPackage = readJson(path.join(legacyProject, "app", "package.json"));
+  assert.ok(!migratedPackage.scripts || !migratedPackage.scripts["ops:status"]);
+  assert.match(git(["branch", "--list"], legacyProject), /backup\/trackops-workspace-/);
+
+  const releaseProject = path.join(tempRoot, "release-demo");
+  fs.mkdirSync(releaseProject, { recursive: true });
+  initGitRepo(releaseProject);
+  runNode([BIN, "init"], releaseProject);
+  writeJson(path.join(releaseProject, "app", "package.json"), { name: "release-demo", version: "1.0.0" });
+  fs.writeFileSync(path.join(releaseProject, "app", "index.js"), "console.log('release');\n", "utf8");
+  commitAll(releaseProject, "split fixture");
+  git(["checkout", "-b", "develop"], releaseProject);
+  runNode([BIN, "release"], releaseProject);
+  const publishFiles = git(["ls-tree", "--name-only", "master"], releaseProject).split(/\r?\n/).filter(Boolean);
+  assert.ok(publishFiles.includes("package.json"));
+  assert.ok(publishFiles.includes(".env.example"));
+  assert.ok(!publishFiles.includes("ops"));
+  assert.ok(!publishFiles.includes(".trackops-workspace.json"));
+
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+  console.log("Smoke tests OK");
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/scripts/sync-skill-version.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const PACKAGE_FILE = path.join(ROOT, "package.json");
+const SKILL_FILE = path.join(ROOT, "skills", "trackops", "skill.json");
+
+function main() {
+  const pkg = JSON.parse(fs.readFileSync(PACKAGE_FILE, "utf8"));
+  const skill = JSON.parse(fs.readFileSync(SKILL_FILE, "utf8"));
+
+  skill.skillVersion = pkg.version;
+  skill.trackopsVersion = pkg.version;
+
+  fs.writeFileSync(SKILL_FILE, `${JSON.stringify(skill, null, 2)}\n`, "utf8");
+  console.log(`Synced skills/trackops/skill.json to version ${pkg.version}.`);
+}
+
+main();

package/scripts/validate-skill.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.resolve(__dirname, "..");
+const PACKAGE_FILE = path.join(ROOT, "package.json");
+const SKILL_DIR = path.join(ROOT, "skills", "trackops");
+const SKILL_FILE = path.join(SKILL_DIR, "skill.json");
+const REQUIRED_FILES = [
+  path.join(SKILL_DIR, "SKILL.md"),
+  path.join(SKILL_DIR, "skill.json"),
+  path.join(SKILL_DIR, "scripts", "bootstrap-trackops.js"),
+  path.join(SKILL_DIR, "references", "activation.md"),
+  path.join(SKILL_DIR, "references", "workflow.md"),
+  path.join(SKILL_DIR, "references", "troubleshooting.md"),
+];
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+function main() {
+  const pkg = JSON.parse(fs.readFileSync(PACKAGE_FILE, "utf8"));
+  const skill = JSON.parse(fs.readFileSync(SKILL_FILE, "utf8"));
+  const skillMd = fs.readFileSync(path.join(SKILL_DIR, "SKILL.md"), "utf8");
+
+  for (const file of REQUIRED_FILES) {
+    if (!fs.existsSync(file)) {
+      fail(`Missing required skill file: ${path.relative(ROOT, file)}`);
+    }
+  }
+
+  if (!Array.isArray(pkg.files) || !pkg.files.includes("skills/")) {
+    fail("package.json must publish the skills/ directory.");
+  }
+
+  if (skill.name !== "trackops") {
+    fail("skills/trackops/skill.json must declare name 'trackops'.");
+  }
+
+  if (skill.skillVersion !== pkg.version || skill.trackopsVersion !== pkg.version) {
+    fail(`skills/trackops/skill.json must be synced to package version ${pkg.version}.`);
+  }
+
+  if (skill.npmPackage !== pkg.name) {
+    fail(`skills/trackops/skill.json must target npm package '${pkg.name}'.`);
+  }
+
+  if (skill.bootstrapPolicy !== "first_use") {
+    fail("skills/trackops/skill.json must use bootstrapPolicy 'first_use'.");
+  }
+
+  const supportedAgents = Array.isArray(skill.supportedAgentsV1) ? skill.supportedAgentsV1 : [];
+  for (const agent of ["antigravity", "claude-code", "codex", "cursor", "gemini-cli", "github-copilot", "kiro-cli"]) {
+    if (!supportedAgents.includes(agent)) {
+      fail(`skills/trackops/skill.json must include supported agent '${agent}'.`);
+    }
+  }
+
+  if (!skill.distribution || skill.distribution.source !== "Baxahaun/trackops") {
+    fail("skills/trackops/skill.json must declare distribution.source 'Baxahaun/trackops'.");
+  }
+
+  if (skill.distribution.skill !== "trackops") {
+    fail("skills/trackops/skill.json must declare distribution.skill 'trackops'.");
+  }
+
+  if (skill.distribution.fullDepth !== true) {
+    fail("skills/trackops/skill.json must declare distribution.fullDepth true.");
+  }
+
+  for (const requiredPhrase of [
+    "npx skills add Baxahaun/trackops --skill trackops --full-depth",
+    "node scripts/bootstrap-trackops.js",
+    "trackops init",
+    "trackops opera install",
+  ]) {
+    if (!skillMd.includes(requiredPhrase)) {
+      fail(`skills/trackops/SKILL.md must mention '${requiredPhrase}'.`);
+    }
+  }
+
+  console.log("skills/trackops validated successfully.");
+}
+
+main();

package/skills/trackops/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: "trackops"
+description: "Global TrackOps skill that prepares your agent for local project orchestration and operational automation, ensures the runtime on first use, and guides per-project activation with optional OPERA."
+metadata:
+  version: "1.1.0"
+  type: "global"
+  triggers:
+    - "install trackops"
+    - "skills.sh"
+    - "bootstrap trackops"
+    - "trackops init"
+    - "trackops opera install"
+---
+
+# TrackOps
+
+Use this skill in two layers:
+
+1. Global skill layer
+   Install it with:
+
+   ```bash
+   npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+   ```
+
+   Replace `codex` with any supported target: `antigravity`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `github-copilot`, or `kiro-cli`.
+
+   Before relying on the CLI, run:
+
+   ```bash
+   node scripts/bootstrap-trackops.js
+   ```
+
+2. Local project layer
+   Activate TrackOps inside the current repository with:
+
+   ```bash
+   trackops init
+   ```
+
+   Add OPERA only when explicitly requested:
+
+   ```bash
+   trackops opera install
+   ```
+
+Core rules:
+
+- Treat the global skill install as non-invasive.
+- In split workspaces, use `ops/project_control.json` as the operational source of truth.
+- In legacy repos, use `project_control.json` at the repository root.
+- Prefer `trackops status`, `trackops next`, and `trackops sync` over hand-editing generated docs.
+- Treat `trackops init --with-opera` as a shortcut, not as the primary mental model.
+- TrackOps manages `/.env` and `/.env.example` at workspace root. Do not print or persist secret values.
+- Remember that skills installs from committed Git state.
+
+Read references only when needed:
+
+- `references/activation.md`
+  for install and activation flow
+- `references/workflow.md`
+  for day-to-day repo operation
+- `references/troubleshooting.md`
+  for bootstrap or environment issues

package/skills/trackops/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "TrackOps"
+  short_description: "Global TrackOps skill for local project orchestration and operational automation"

package/skills/trackops/references/activation.md

@@ -0,0 +1,39 @@
+# Activation
+
+## Global install
+
+The marketplace skill prepares TrackOps globally for the agent. It must not create repo files by itself.
+
+Install it with:
+
+```bash
+npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+```
+
+Replace `codex` with any supported target: `antigravity`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `github-copilot`, or `kiro-cli`.
+
+Before using TrackOps commands, run:
+
+```bash
+node scripts/bootstrap-trackops.js
+```
+
+That bootstrap validates prerequisites, installs or updates the TrackOps runtime, and records state in `~/.trackops/runtime.json`.
+
+## Local activation
+
+Inside a repository, the normal flow is:
+
+```bash
+trackops init
+trackops opera install
+```
+
+Rules:
+
+- Use `trackops init` when the repo is not yet managed by TrackOps.
+- By default, `trackops init` creates a split workspace with `app/`, `ops/`, `/.env`, `/.env.example`, and `.trackops-workspace.json`.
+- Use `trackops opera install` only after `trackops init` and only when the user wants OPERA.
+- Use `trackops init --with-opera` only as an explicit shortcut.
+- Use `trackops init --legacy-layout` only for compatibility with the old single-root layout.
+- Never assume that a global skill install authorizes local repo mutations by default.