trackops 2.0.1 → 2.0.3

package/skills/trackops/locales/en/SKILL.md

@@ -1,13 +1,40 @@
 ---
 name: "trackops"
-description: "Global TrackOps skill for installing and activating local project orchestration with OPERA, environment management, and agent handoff. Use it when the user wants to install TrackOps from skills.sh, bootstrap the runtime with `node scripts/bootstrap-trackops.js`, run `trackops init`, run `trackops opera install`, inspect `trackops opera handoff`, or work through the operational flow of a repository."
+description: "Global TrackOps skill for explaining what TrackOps does, requiring explicit npm runtime installation, and guiding local project and OPERA activation inside each repository."
 ---
 
 # TrackOps
 
 Use this localized file when the conversation and project should run in English.
 
-## Global layer
+TrackOps is for working with agents on real projects without mixing the product itself with the operational layer.
+
+Use this skill when someone:
+
+- wants to start a project with AI agents
+- already has a repository and needs operational structure
+- needs to activate TrackOps and, if needed, OPERA
+- wants the same workflow in English or Spanish
+
+## What this skill does
+
+This skill:
+
+- explains what TrackOps is and when to use it
+- requires an explicit and visible runtime installation
+- guides per-repository activation
+- helps route OPERA into either `direct bootstrap` or `agent handoff`
+
+## What this skill does not do
+
+This skill does not:
+
+- install packages by itself
+- execute remote code silently
+- modify a repository before the runtime exists
+- replace the `trackops` runtime
+
+## Quick flow
 
 Install the marketplace skill with:
 
@@ -15,21 +42,21 @@ Install the marketplace skill with:
 npx skills add Baxahaun/trackops
 ```
 
-Before relying on the CLI, run the bundled skill script:
+Then confirm that the `trackops` runtime exists. If it is missing, ask the user to install it explicitly:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-That bootstrap:
+Rules:
 
-- ensures the npm `trackops` runtime
-- verifies that the global binary can be executed
-- records state in `~/.trackops/runtime.json`
+- the skill must not install packages or execute remote code by itself
+- the runtime is installed through a visible and auditable npm step
+- the skill may verify `trackops --version`, but it must not chain silent installs
+- the skill must not create repository files by itself
 
-It must not create repository files on its own.
-
-## Local project layer
+## Project activation
 
 Inside the repository:
 
@@ -40,7 +67,8 @@ trackops opera install
 
 Core rules:
 
-- treat the global install as non-invasive
+- treat the global skill as an instruction layer
+- treat runtime installation as explicit and separate
 - use `ops/contract/operating-contract.json` as the machine contract when it exists
 - use `ops/project_control.json` as the operational source of truth
 - use `ops/policy/autonomy.json` before approval-sensitive actions
@@ -48,7 +76,7 @@ Core rules:
 - keep generated operational docs under `ops/`
 - use `trackops locale get|set` and `trackops doctor locale` when language matters
 
-## OPERA onboarding
+## How OPERA enters the flow
 
 OPERA no longer assumes every user is technical.
 
@@ -79,8 +107,16 @@ If TrackOps routes bootstrap to the agent:
 trackops opera bootstrap --resume
 ```
 
+## What someone arriving from skills.sh should understand
+
+- the global skill installs instructions into the agent
+- the runtime is installed separately with npm
+- `trackops init` activates the project
+- `trackops opera install` adds the full operating framework only when needed
+- TrackOps separates product and operations so the repository stays manageable
+
 ## Which reference to read and when
 
-- read `locales/en/references/activation.md` only for installation, first use, locale bootstrap, and repository activation
+- read `locales/en/references/activation.md` only for installation, runtime verification, locale bootstrap, and repository activation
 - read `locales/en/references/workflow.md` only when TrackOps is already active and you need day-to-day repository operations
-- read `locales/en/references/troubleshooting.md` only when installation, bootstrap, resume, or environment contract handling fails
+- read `locales/en/references/troubleshooting.md` only when explicit installation, `trackops` detection, resume, or environment contract handling fails

package/skills/trackops/locales/en/references/activation.md

@@ -2,19 +2,21 @@
 
 ## Global install
 
-Install the marketplace skill:
-
 ```bash
 npx skills add Baxahaun/trackops
+npm install -g trackops
+trackops --version
 ```
 
-On first use, ensure the runtime with the bundled skill script:
+The global skill installs instructions for the agent.
 
-```bash
-node scripts/bootstrap-trackops.js
-```
+The `trackops` runtime is installed separately through npm so the step stays visible, auditable, and easy to verify.
+
+Before continuing:
 
-The global skill must not create repository files on its own.
+- confirm that `trackops --version` returns a valid version
+- if it does not, fix PATH or reinstall `trackops`
+- the skill must not try to install the runtime by itself
 
 ## Local activation
 

package/skills/trackops/locales/en/references/troubleshooting.md

@@ -5,18 +5,24 @@
 - Install Node 18+ if Node is missing or too old.
 - Install a Node distribution that includes npm if npm is missing.
 
-## Global install command failed
+## The skill is installed, but `trackops` does not start
 
-- Install from committed GitHub state:
+- Confirm that the global skill exists:
   `npx skills add Baxahaun/trackops`
-- Then ensure the local runtime with:
-  `node scripts/bootstrap-trackops.js`
-- If the install succeeded but the CLI still looks unavailable, confirm that `~/.trackops/runtime.json` exists.
-
-## Runtime bootstrap failed
-
-- Re-run `node scripts/bootstrap-trackops.js`.
-- If npm global permissions fail, configure a user-writable npm prefix instead of using `sudo`.
+- Install or reinstall the runtime explicitly:
+  `npm install -g trackops`
+- Verify:
+  `trackops --version`
+- If the binary still does not respond:
+  - check Node.js (`>= 18`)
+  - check that `npm` exists and works
+  - check PATH and reopen the terminal
+
+## Explicit runtime installation fails
+
+- Re-run `npm install -g trackops`.
+- If `npm` errors, fix that first; the skill cannot continue without the CLI.
+- If the issue is global permissions, use the recommended method for your system or a user-controlled npm prefix.
 
 ## OPERA routed bootstrap to the agent
 

package/skills/trackops/locales/en/references/workflow.md

@@ -1,6 +1,12 @@
 # Workflow
 
-Once TrackOps is active in a repository:
+Precondition:
+
+- the global skill is already installed
+- `trackops --version` responds correctly
+- the repository was already activated with `trackops init`
+
+Use TrackOps when the repository is already managed and you need day-to-day operations.
 
 1. Run `trackops status`.
 2. Run `trackops next`.
@@ -10,17 +16,17 @@ Once TrackOps is active in a repository:
 
 Operational rules:
 
-- In split workspaces, use `ops/project_control.json` as the source of truth.
-- Generated operational docs live in `ops/`.
-- Product code lives in `app/`.
-- Real secrets live in `/.env`.
-- Public environment contract lives in `/.env.example`.
-- `app/.env` is only a compatibility bridge.
+- in split workspaces, use `ops/project_control.json` as the source of truth
+- generated operational docs live in `ops/`
+- product code lives in `app/`
+- real secrets live in `/.env`
+- public environment contract lives in `/.env.example`
+- `app/.env` is only a compatibility bridge
 
 If OPERA is installed:
 
-- `ops/contract/operating-contract.json` holds the machine contract.
-- `ops/genesis.md` holds the compiled human view.
-- `ops/policy/autonomy.json` holds the executable autonomy policy.
-- `ops/bootstrap/` holds onboarding artifacts.
-- `ops/.agent/hub/` and `ops/.agents/skills/` hold managed agent artifacts.
+- `ops/contract/operating-contract.json` holds the machine contract
+- `ops/genesis.md` holds the compiled human view
+- `ops/policy/autonomy.json` holds the executable autonomy policy
+- `ops/bootstrap/` holds onboarding artifacts
+- `ops/.agent/hub/` and `ops/.agents/skills/` hold managed agent artifacts

package/skills/trackops/references/activation.md

@@ -2,23 +2,25 @@
 
 ## Instalacion global
 
-Instala la skill del marketplace:
-
 ```bash
 npx skills add Baxahaun/trackops
+npm install -g trackops
+trackops --version
 ```
 
-En primer uso, asegura el runtime con el script empaquetado de la skill:
+La skill global instala instrucciones para el agente.
 
-```bash
-node scripts/bootstrap-trackops.js
-```
+El runtime `trackops` se instala aparte con npm para que el paso sea visible, auditable y facil de verificar.
+
+Antes de seguir:
 
-La skill global no debe crear archivos dentro de repositorios por si sola.
+- confirma que `trackops --version` devuelve una version valida
+- si no aparece, resuelve PATH o reinstala `trackops`
+- la skill no debe intentar instalar el runtime por su cuenta
 
 ## Activacion local
 
-Dentro de un repositorio:
+Dentro del repo:
 
 ```bash
 trackops init
@@ -39,9 +41,9 @@ OPERA siempre empieza clasificando:
 
 - nivel tecnico
 - estado del proyecto
-- estado de la documentacion
+- estado de documentacion
 
-Si el proyecto aun esta verde o el usuario no es tecnico, TrackOps escribe:
+Si el proyecto esta en fase temprana o el usuario es no tecnico, TrackOps escribe:
 
 - `ops/bootstrap/agent-handoff.md`
 - `ops/bootstrap/agent-handoff.json`
@@ -52,7 +54,7 @@ El agente debe producir:
 - `ops/bootstrap/spec-dossier.md`
 - `ops/bootstrap/open-questions.md` cuando haga falta
 
-Cuando el quality gate pasa, OPERA compila:
+Cuando pasa el quality gate, OPERA compila:
 
 - `ops/contract/operating-contract.json`
 - `ops/genesis.md`
@@ -68,6 +70,6 @@ Controles de idioma:
 
 ```bash
 trackops locale get
-trackops locale set en
+trackops locale set es
 trackops doctor locale
 ```

package/skills/trackops/references/troubleshooting.md

@@ -2,28 +2,34 @@
 
 ## Faltan prerequisitos
 
-- Instala Node 18+ si Node falta o es demasiado antiguo.
-- Instala una distribucion de Node que incluya npm si falta npm.
+- Instala Node 18+ si Node no existe o es demasiado antiguo.
+- Instala una distribucion de Node que incluya npm si npm no existe.
 
-## Fallo al instalar la skill global
+## La skill se instalo, pero `trackops` no arranca
 
-- Instala desde el estado committeado de GitHub:
+- Confirma que la skill global existe:
   `npx skills add Baxahaun/trackops`
-- Luego asegura el runtime local con:
-  `node scripts/bootstrap-trackops.js`
-- Si la instalacion salio bien pero el CLI sigue sin aparecer, confirma que `~/.trackops/runtime.json` exista.
+- Instala o reinstala el runtime de forma explicita:
+  `npm install -g trackops`
+- Verifica:
+  `trackops --version`
+- Si el binario sigue sin responder:
+  - revisa Node.js (`>= 18`)
+  - revisa que `npm` exista y funcione
+  - revisa PATH y reabre la terminal
 
-## Fallo en el bootstrap del runtime
+## La instalacion explicita del runtime falla
 
-- Reejecuta `node scripts/bootstrap-trackops.js`.
-- Si fallan los permisos globales de npm, configura un prefix de usuario en lugar de usar `sudo`.
+- Reejecuta `npm install -g trackops`.
+- Si `npm` devuelve error, resuelvelo primero; la skill no puede continuar sin el CLI.
+- Si el problema es de permisos globales, usa el metodo recomendado para tu sistema o un prefijo npm controlado por el usuario.
 
-## OPERA ha derivado el bootstrap al agente
+## OPERA derivo el bootstrap al agente
 
-Es el comportamiento esperado cuando:
+Esto es esperado cuando:
 
 - el usuario no es tecnico
-- el proyecto sigue en fase idea
+- el proyecto esta en fase idea
 - la documentacion es debil
 
 Usa:
@@ -33,11 +39,11 @@ trackops opera handoff --print
 trackops opera bootstrap --resume
 ```
 
-## El resume no completa
+## `trackops opera bootstrap --resume` no avanza
 
 TrackOps no inventa contexto faltante.
 
-Comprueba que ambos archivos existan y contengan datos utilizables:
+Comprueba que existan ambos archivos y contengan datos utiles:
 
 - `ops/bootstrap/intake.json`
 - `ops/bootstrap/spec-dossier.md`
@@ -46,4 +52,4 @@ Comprueba que ambos archivos existan y contengan datos utilizables:
 
 - Ejecuta `trackops env status`.
 - Ejecuta `trackops env sync`.
-- Si el bridge mode es `copy`, no edites `app/.env` directamente.
+- Si el modo bridge es `copy`, no edites `app/.env` directamente.

package/skills/trackops/references/workflow.md

@@ -1,26 +1,32 @@
-# Workflow
+# Flujo diario
 
-Una vez que TrackOps esta activo en un repositorio:
+Precondicion:
+
+- la skill global ya esta instalada
+- `trackops --version` responde correctamente
+- el repo ya fue activado con `trackops init`
+
+Usa TrackOps cuando el repositorio ya esta gestionado y necesites operar el dia a dia.
 
 1. Ejecuta `trackops status`.
 2. Ejecuta `trackops next`.
 3. Mueve el estado de tareas con `trackops task ...`.
-4. Ejecuta `trackops sync` tras cambios relevantes.
-5. Ejecuta `trackops env status` cuando importen las credenciales.
+4. Ejecuta `trackops sync` despues de cambios relevantes.
+5. Ejecuta `trackops env status` cuando las credenciales importen.
 
 Reglas operativas:
 
-- En workspaces split, usa `ops/project_control.json` como fuente de verdad.
-- La documentacion operativa generada vive en `ops/`.
-- El codigo de producto vive en `app/`.
-- Los secretos reales viven en `/.env`.
-- El contrato publico de entorno vive en `/.env.example`.
-- `app/.env` es solo un puente de compatibilidad.
+- en workspaces split, usa `ops/project_control.json` como fuente de verdad
+- la documentacion operativa generada vive en `ops/`
+- el codigo de producto vive en `app/`
+- los secretos reales viven en `/.env`
+- el contrato publico de entorno vive en `/.env.example`
+- `app/.env` solo es un puente de compatibilidad
 
 Si OPERA esta instalado:
 
-- `ops/contract/operating-contract.json` contiene el contrato de maquina.
-- `ops/genesis.md` contiene la vista humana compilada.
-- `ops/policy/autonomy.json` contiene la politica ejecutable.
-- `ops/bootstrap/` contiene los artefactos de onboarding.
-- `ops/.agent/hub/` y `ops/.agents/skills/` contienen artefactos gestionados de agentes.
+- `ops/contract/operating-contract.json` guarda el contrato de maquina
+- `ops/genesis.md` guarda la vista humana compilada
+- `ops/policy/autonomy.json` guarda la politica ejecutable
+- `ops/bootstrap/` guarda artefactos de onboarding
+- `ops/.agent/hub/` y `ops/.agents/skills/` guardan artefactos gestionados de agente

package/skills/trackops/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "trackops",
-  "shortDescription": "Global TrackOps skill for local project orchestration, agent coordination, bilingual onboarding, and operational automation.",
-  "description": "Installs TrackOps as a global skill, ensures the runtime on first use, lets users choose Spanish or English, activates local project orchestration, and routes OPERA onboarding into either direct bootstrap or agent-led discovery.",
-  "skillVersion": "2.0.1",
-  "trackopsVersion": "2.0.1",
+  "shortDescription": "Global TrackOps skill that explains TrackOps, requires explicit runtime install, and guides per-repository activation.",
+  "description": "Explains what TrackOps does, installs the global skill layer, requires explicit runtime installation with npm, supports Spanish and English, activates TrackOps repository by repository, and routes OPERA onboarding into either direct bootstrap or agent-led discovery.",
+  "skillVersion": "2.0.3",
+  "trackopsVersion": "2.0.3",
   "npmPackage": "trackops",
-  "bootstrapPolicy": "first_use",
+  "bootstrapPolicy": "explicit_install",
   "supportedAgentsV1": [
     "antigravity",
     "claude-code",

package/templates/opera/architecture/dependency-graph.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 flowchart TD
-    A[Global runtime bootstrap] --> B[trackops init]
+    A[Explicit global runtime install] --> B[trackops init]
     B --> C[trackops opera install]
     C --> D{Routing}
     D -->|direct_cli| E[Direct intake]

package/templates/opera/en/architecture/dependency-graph.md

@@ -2,7 +2,7 @@
 
 ```mermaid
 flowchart TD
-    A[Global runtime bootstrap] --> B[trackops init]
+    A[Explicit global runtime install] --> B[trackops init]
     B --> C[trackops opera install]
     C --> D{Routing}
     D -->|direct_cli| E[Direct intake]

package/templates/skills/project-starter-skill/SKILL.md

@@ -104,6 +104,7 @@ Explica el flujo correcto:
 
 ```bash
 npx skills add Baxahaun/trackops
+npm install -g trackops
 trackops init
 trackops opera install
 ```
@@ -122,6 +123,7 @@ Explica el flujo correcto:
 
 ```bash
 npx skills add Baxahaun/trackops
+npm install -g trackops
 trackops init
 trackops opera install
 ```

package/templates/skills/project-starter-skill/locales/en/SKILL.md

@@ -97,6 +97,7 @@ Explain the correct flow:
 
 ```bash
 npx skills add Baxahaun/trackops
+npm install -g trackops
 trackops init
 trackops opera install
 ```

package/skills/trackops/scripts/bootstrap-trackops.js

@@ -1,203 +0,0 @@
-#!/usr/bin/env node
-
-const fs = require("fs");
-const os = require("os");
-const path = require("path");
-const { spawnSync } = require("child_process");
-const runtimeState = require("../../../lib/runtime-state");
-
-const EXIT_CODES = {
-  READY: 0,
-  PREREQ: 1,
-  INSTALL: 2,
-  UNVERIFIABLE: 3,
-};
-
-function getNpmCommand() {
-  return process.platform === "win32" ? "npm.cmd" : "npm";
-}
-
-function readSkillConfig() {
-  const skillFile = path.join(__dirname, "..", "skill.json");
-  return JSON.parse(fs.readFileSync(skillFile, "utf8"));
-}
-
-function getHomeDir() {
-  return process.env.TRACKOPS_BOOTSTRAP_HOME || os.homedir();
-}
-
-function getPrefixOverride() {
-  return process.env.TRACKOPS_BOOTSTRAP_PREFIX || null;
-}
-
-function getInstallSource(config) {
-  return process.env.TRACKOPS_BOOTSTRAP_INSTALL_SOURCE || `${config.npmPackage}@${config.trackopsVersion}`;
-}
-
-function parseMajor(version) {
-  const major = Number(String(version || "").split(".")[0]);
-  return Number.isFinite(major) ? major : null;
-}
-
-function hasSupportedNode() {
-  const major = parseMajor(process.versions.node);
-  return major != null && major >= 18;
-}
-
-function spawnChecked(command, args, extra = {}) {
-  const shell = process.platform === "win32" && /\.(cmd|bat)$/i.test(command);
-  return spawnSync(command, args, {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-    shell,
-    ...extra,
-  });
-}
-
-function spawnNpm(args, extra = {}) {
-  return spawnSync(getNpmCommand(), args, {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"],
-    shell: process.platform === "win32",
-    ...extra,
-  });
-}
-
-function resolvePrefixExecutables(prefix) {
-  if (!prefix) return [];
-  if (process.platform === "win32") {
-    return [
-      path.join(prefix, "trackops.cmd"),
-      path.join(prefix, "trackops.exe"),
-      path.join(prefix, "trackops"),
-    ];
-  }
-  return [path.join(prefix, "bin", "trackops")];
-}
-
-function buildVerificationTargets(prefix) {
-  const targets = [{ command: "trackops", via: "path" }];
-  for (const candidate of resolvePrefixExecutables(prefix)) {
-    targets.push({ command: candidate, via: "prefix" });
-  }
-  return targets;
-}
-
-function readInstalledVersion(prefix) {
-  for (const target of buildVerificationTargets(prefix)) {
-    const result = spawnChecked(target.command, ["--version"]);
-    if (result.error || result.status !== 0) continue;
-    const version = String(result.stdout || "").trim();
-    if (version) {
-      return { version, command: target.command, via: target.via };
-    }
-  }
-  return null;
-}
-
-function verifyRuntime(expectedVersion, prefix) {
-  const installed = readInstalledVersion(prefix);
-  if (!installed) {
-    return { ok: false, reason: "missing-command" };
-  }
-  if (installed.version !== expectedVersion) {
-    return { ok: false, reason: "version-drift", installed };
-  }
-
-  const help = spawnChecked(installed.command, ["help"]);
-  if (help.error || help.status !== 0) {
-    return { ok: false, reason: "help-failed", installed };
-  }
-
-  return { ok: true, installed };
-}
-
-function ensureNpmAvailable() {
-  const result = spawnNpm(["--version"]);
-  return !result.error && result.status === 0;
-}
-
-function runInstall(config, prefix) {
-  const installSource = getInstallSource(config);
-  const args = ["install", "-g"];
-  if (prefix) {
-    args.push("--prefix", prefix);
-  }
-  args.push(installSource);
-
-  const result = spawnNpm(args);
-  return { ...result, installSource };
-}
-
-function writeRuntimeStamp(config, verification) {
-  const previous = runtimeState.readRuntimeState();
-  const payload = runtimeState.writeRuntimeState({
-    ...previous,
-    skill: config.name,
-    skillVersion: config.skillVersion,
-    runtimePackage: config.npmPackage,
-    runtimeVersion: config.trackopsVersion,
-    bootstrapPolicy: config.bootstrapPolicy,
-    supportedAgentsV1: config.supportedAgentsV1,
-    verifiedAt: new Date().toISOString(),
-    verifiedWith: verification.installed.via,
-    executable: verification.installed.command,
-  });
-  return payload;
-}
-
-function printInstallGuidance(prefix) {
-  if (prefix) {
-    console.error(`TrackOps was installed under the custom prefix '${prefix}'.`);
-    console.error("Use that prefix's executable or add it to PATH before trying again.");
-    return;
-  }
-
-  console.error("TrackOps was installed but could not be executed from PATH.");
-  console.error("Add your npm global bin directory to PATH, reopen the terminal, and retry.");
-}
-
-async function main() {
-  const config = readSkillConfig();
-  const prefix = getPrefixOverride();
-
-  if (!hasSupportedNode()) {
-    console.error("TrackOps requires Node.js 18 or newer.");
-    process.exit(EXIT_CODES.PREREQ);
-  }
-
-  if (!ensureNpmAvailable()) {
-    console.error("npm is required to bootstrap the TrackOps runtime.");
-    process.exit(EXIT_CODES.PREREQ);
-  }
-
-  const current = verifyRuntime(config.trackopsVersion, prefix);
-  if (current.ok) {
-    await runtimeState.ensureGlobalLocale({ interactive: false });
-    writeRuntimeStamp(config, current);
-    console.log(`TrackOps runtime ${config.trackopsVersion} is already ready.`);
-    process.exit(EXIT_CODES.READY);
-  }
-
-  const install = runInstall(config, prefix);
-  if (install.error || install.status !== 0) {
-    console.error(`Failed to install ${install.installSource}.`);
-    if (install.stderr) {
-      console.error(install.stderr.trim());
-    }
-    process.exit(EXIT_CODES.INSTALL);
-  }
-
-  const verification = verifyRuntime(config.trackopsVersion, prefix);
-  if (!verification.ok) {
-    printInstallGuidance(prefix);
-    process.exit(EXIT_CODES.UNVERIFIABLE);
-  }
-
-  await runtimeState.ensureGlobalLocale({ interactive: false });
-  writeRuntimeStamp(config, verification);
-  console.log(`TrackOps runtime ${config.trackopsVersion} is ready.`);
-  process.exit(EXIT_CODES.READY);
-}
-
-main();