trackops 2.0.1 → 2.0.2

package/README.md

@@ -15,62 +15,59 @@
 </p>
 
 <p align="center">
-  <a href="#español">Español</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#english">English</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://baxahaun.github.io/trackops/">Web</a>
+  <a href="#espanol">Espanol</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="#english">English</a>&nbsp;&nbsp;·&nbsp;&nbsp;<a href="https://baxahaun.github.io/trackops/">Web</a>
 </p>
 
 ---
 
-## Español
+## Espanol
 
-TrackOps es un sistema local de orquestación y automatización operativa para proyectos y desarrollo asistido por agentes IA.
+TrackOps es un sistema local de orquestacion y automatizacion operativa para proyectos y desarrollo asistido por agentes IA.
 
 Hace tres cosas:
 
-1. prepara a tu agente con una skill global
+1. prepara al agente con una skill global
 2. activa control operativo dentro de cada repo
-3. media entre el usuario y el agente cuando el proyecto todavía está poco definido
+3. media entre el usuario y el agente cuando el proyecto aun esta poco definido
 
 ### Modelo actual
 
 TrackOps trabaja en dos capas:
 
 1. `skill global`
-   se instala una vez en tu agente o CLI
-2. `activación local por proyecto`
-   se ejecuta cuando decides gestionar un repo concreto
+   se instala una vez en el agente
+2. `runtime + activacion local`
+   se instalan y ejecutan cuando decides gestionar una maquina y un repo concretos
 
-La activación local tiene dos caminos:
+La activacion local tiene dos caminos:
 
 - `arranque asistido por agente`
-  para ideas tempranas, usuarios poco técnicos o documentación insuficiente
+  para ideas tempranas, usuarios poco tecnicos o documentacion insuficiente
 - `bootstrap directo`
-  para proyectos ya definidos y usuarios técnicos
+  para proyectos ya definidos y usuarios tecnicos
 
-### Instalación global
+### Instalacion global
 
-TrackOps se distribuye como skill global:
+Instala la skill global:
 
 ```bash
 npx skills add Baxahaun/trackops
 ```
 
-La skill:
-
-- prepara el agente
-- asegura el runtime en el primer uso real
-- no modifica repos por sí sola
-
-### Primer uso
-
-En el primer uso, la skill ejecuta:
+Instala el runtime de forma explicita:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-Ese bootstrap valida `Node.js >= 18`, valida `npm`, instala o actualiza `trackops` y registra el estado en `~/.trackops/runtime.json`.
+Esta separacion es intencional:
+
+- la skill se audita como capa de instrucciones
+- el runtime se instala con un paso visible y verificable
+- no hay instalacion transitiva oculta desde la propia skill
 
-### Activación local
+### Activacion local
 
 Dentro de un repo:
 
@@ -79,12 +76,12 @@ trackops init
 trackops opera install
 ```
 
-Semántica:
+Semantica:
 
 - `trackops init`
   activa TrackOps en el repo
 - `trackops opera install`
-  añade OPERA cuando quieres el framework operativo completo
+  anade OPERA cuando quieres el framework operativo completo
 - `trackops init --with-opera`
   existe como atajo
 - `trackops init --legacy-layout`
@@ -92,30 +89,30 @@ Semántica:
 
 ### Workspace split
 
-Por defecto, TrackOps separa producto y operación:
+Por defecto, TrackOps separa producto y operacion:
 
 ```text
 mi-proyecto/
-├── .trackops-workspace.json
-├── .env
-├── .env.example
-├── app/
-│   └── ...producto real...
-└── ops/
-    ├── project_control.json
-    ├── contract/
-    │   └── operating-contract.json
-    ├── policy/
-    │   └── autonomy.json
-    ├── task_plan.md
-    ├── progress.md
-    ├── findings.md
-    ├── genesis.md
-    ├── bootstrap/
-    ├── .agent/
-    ├── .agents/
-    ├── .githooks/
-    └── .tmp/
+|- .trackops-workspace.json
+|- .env
+|- .env.example
+|- app/
+|  \- ...producto real...
+\- ops/
+   |- project_control.json
+   |- contract/
+   |  \- operating-contract.json
+   |- policy/
+   |  \- autonomy.json
+   |- task_plan.md
+   |- progress.md
+   |- findings.md
+   |- genesis.md
+   |- bootstrap/
+   |- .agent/
+   |- .agents/
+   |- .githooks/
+   \- .tmp/
 ```
 
 Fuente de verdad operativa:
@@ -127,9 +124,9 @@ Fuente de verdad operativa:
 
 #### Tengo una idea
 
-Si el usuario no es técnico, el proyecto está en fase idea, o no hay documentación suficiente, OPERA no sigue con preguntas de arquitectura en terminal. En su lugar:
+Si el usuario no es tecnico, el proyecto esta en fase idea, o no hay documentacion suficiente, OPERA no sigue con preguntas de arquitectura en terminal. En su lugar:
 
-1. pregunta nivel técnico, estado del proyecto y documentación disponible
+1. pregunta nivel tecnico, estado del proyecto y documentacion disponible
 2. genera un handoff en `ops/bootstrap/agent-handoff.md`
 3. espera a que el agente produzca:
    - `ops/bootstrap/intake.json`
@@ -143,9 +140,9 @@ trackops opera bootstrap --resume
 
 #### Ya tengo un repo
 
-Si el usuario es técnico y el proyecto ya tiene suficiente contexto, OPERA sigue por bootstrap directo, compila `ops/contract/operating-contract.json` y recompila `ops/genesis.md`.
+Si el usuario es tecnico y el proyecto ya tiene suficiente contexto, OPERA sigue por bootstrap directo, compila `ops/contract/operating-contract.json` y recompila `ops/genesis.md`.
 
-También puedes forzar el modo:
+Tambien puedes forzar el modo:
 
 ```bash
 trackops opera install --bootstrap-mode handoff
@@ -161,12 +158,12 @@ Flags disponibles:
 
 ### Entorno y secretos
 
-TrackOps gestiona un contrato explícito de entorno:
+TrackOps gestiona un contrato explicito de entorno:
 
 - `/.env`
   secretos reales del workspace
 - `/.env.example`
-  contrato público de variables
+  contrato publico de variables
 - `app/.env`
   puente de compatibilidad
 
@@ -194,28 +191,9 @@ trackops locale set es
 trackops doctor locale
 ```
 
-### Trabajo diario
-
-```bash
-trackops status
-trackops next
-trackops sync
-trackops env status
-trackops dashboard
-```
-
-Reglas:
-
-- usa `trackops status` para leer foco, fase y bloqueadores
-- usa `trackops next` para ver la siguiente tarea lista
-- usa `trackops sync` para regenerar docs operativos
-- no edites a mano `task_plan.md`, `progress.md` ni `findings.md`
-
 ### CLI principal
 
-#### Core
-
-| Comando | Descripción |
+| Comando | Descripcion |
 |---|---|
 | `trackops init [--with-opera] [--locale es\|en] [--name "..."] [--no-bootstrap] [--legacy-layout]` | Inicializa TrackOps |
 | `trackops status` | Muestra estado operativo |
@@ -229,28 +207,23 @@ Reglas:
 | `trackops doctor locale` | Explica el origen del idioma efectivo |
 | `trackops release [--push]` | Publica la rama configurada desde `app/` |
 | `trackops dashboard` | Lanza el dashboard local |
-
-#### OPERA
-
-| Comando | Descripción |
-|---|---|
 | `trackops opera install [--bootstrap-mode ...] [--technical-level ...] [--project-state ...] [--docs-state ...] [--decision-ownership ...]` | Instala OPERA y decide la ruta de bootstrap |
-| `trackops opera bootstrap [--resume]` | Continúa el bootstrap o ingiere el resultado del agente |
+| `trackops opera bootstrap [--resume]` | Continua el bootstrap o ingiere el resultado del agente |
 | `trackops opera handoff [--print\|--json]` | Muestra el handoff listo para copiar al agente |
-| `trackops opera status` | Muestra estado de instalación y bootstrap |
+| `trackops opera status` | Muestra estado de instalacion y bootstrap |
 | `trackops opera configure` | Reconfigura idioma o fases |
-| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la versión estable actual |
+| `trackops opera upgrade --stable [--reset]` | Reescribe artefactos gestionados a la version estable actual |
 
 ### Skills del proyecto
 
 Hay dos conceptos distintos:
 
 - la skill global `trackops`
-  prepara el sistema
+  prepara al agente y guia el flujo
 - `trackops skill ...`
   gestiona skills nativas del proyecto en `ops/.agents/skills/`
 
-### Publicación
+### Publicacion
 
 Antes de publicar:
 
@@ -264,7 +237,7 @@ npm run release:check
 
 `trackops release` publica solo `app/`, incluye `.env.example` y no publica `/.env`, `ops/` ni `.trackops-workspace.json`.
 
-Guía ampliada: [UserGUIDE.md](./UserGUIDE.md)
+Guia ampliada: [UserGUIDE.md](./UserGUIDE.md)
 
 ---
 
@@ -274,7 +247,7 @@ TrackOps is a local orchestration and operational automation system for projects
 
 It does three things:
 
-1. prepares your agent with a global skill
+1. prepares the agent with a global skill
 2. activates operational control inside each repository
 3. mediates between the user and the agent when the project is still loosely defined
 
@@ -283,9 +256,9 @@ It does three things:
 TrackOps works in two layers:
 
 1. `global skill`
-   installed once in the agent or CLI
-2. `local per-project activation`
-   run when you decide to manage a specific repository
+   installed once in the agent
+2. `runtime + local activation`
+   installed and used when you decide to manage a specific machine and repository
 
 Local activation has two paths:
 
@@ -296,23 +269,24 @@ Local activation has two paths:
 
 ### Global install
 
-Install the global skill with:
+Install the global skill:
 
 ```bash
 npx skills add Baxahaun/trackops
 ```
 
-The skill prepares the agent, ensures the runtime on first use, and does not mutate repositories by itself.
-
-### First use
-
-On first use the skill runs:
+Install the runtime explicitly:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-It validates `Node.js >= 18`, validates `npm`, installs or updates `trackops`, and records state in `~/.trackops/runtime.json`.
+This split is intentional:
+
+- the skill is audited as an instruction layer
+- the runtime is installed through a visible and verifiable step
+- there is no hidden transitive install from the skill itself
 
 ### Local activation
 
@@ -329,25 +303,25 @@ TrackOps separates product and operations by default:
 
 ```text
 my-project/
-├── .trackops-workspace.json
-├── .env
-├── .env.example
-├── app/
-└── ops/
-    ├── project_control.json
-    ├── contract/
-    │   └── operating-contract.json
-    ├── policy/
-    │   └── autonomy.json
-    ├── task_plan.md
-    ├── progress.md
-    ├── findings.md
-    ├── genesis.md
-    ├── bootstrap/
-    ├── .agent/
-    ├── .agents/
-    ├── .githooks/
-    └── .tmp/
+|- .trackops-workspace.json
+|- .env
+|- .env.example
+|- app/
+\- ops/
+   |- project_control.json
+   |- contract/
+   |  \- operating-contract.json
+   |- policy/
+   |  \- autonomy.json
+   |- task_plan.md
+   |- progress.md
+   |- findings.md
+   |- genesis.md
+   |- bootstrap/
+   |- .agent/
+   |- .agents/
+   |- .githooks/
+   \- .tmp/
 ```
 
 Operational source of truth:
@@ -395,6 +369,13 @@ TrackOps manages:
 - `app/.env`
   compatibility bridge
 
+Use:
+
+```bash
+trackops env status
+trackops env sync
+```
+
 ### Language
 
 TrackOps can work with:
@@ -410,19 +391,9 @@ trackops locale set en
 trackops doctor locale
 ```
 
-### Daily workflow
-
-```bash
-trackops status
-trackops next
-trackops sync
-trackops env status
-trackops dashboard
-```
-
 ### Main CLI
 
-Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff` and `trackops opera bootstrap --resume`.
+Core and OPERA commands follow the same contract as the Spanish section above, including `trackops opera handoff`, `trackops opera bootstrap --resume`, and the explicit `npm install -g trackops` runtime step.
 
 ### Publishing
 

package/locales/en.json

@@ -125,8 +125,8 @@
   "cli.help.skill.desc": "Manage skills.",
   "cli.help.help.desc": "Show this help.",
   "cli.help.globalWorkflow": "Global agent workflow:",
-  "cli.help.globalWorkflow.line1": "Install with 'npx skills add Baxahaun/trackops'",
-  "cli.help.globalWorkflow.line2": "and the global/agent flags you need; then use 'trackops init' and 'trackops opera install' explicitly inside each project.",
+  "cli.help.globalWorkflow.line1": "Install the skill with 'npx skills add Baxahaun/trackops' and then the runtime with 'npm install -g trackops'.",
+  "cli.help.globalWorkflow.line2": "Then verify with 'trackops --version' and use 'trackops init' and 'trackops opera install' explicitly inside each project.",
   "cli.usage.workspace": "Usage: trackops workspace <status|migrate>",
   "cli.usage.env": "Usage: trackops env <status|sync>",
   "cli.usage.opera": "Usage: trackops opera <install|bootstrap|handoff|status|configure|upgrade>",

package/locales/es.json

@@ -125,8 +125,8 @@
   "cli.help.skill.desc": "Gestiona skills.",
   "cli.help.help.desc": "Muestra esta ayuda.",
   "cli.help.globalWorkflow": "Flujo global del agente:",
-  "cli.help.globalWorkflow.line1": "Instala con 'npx skills add Baxahaun/trackops'",
-  "cli.help.globalWorkflow.line2": "y los flags globales/de agente que necesites; despues usa 'trackops init' y 'trackops opera install' de forma explicita dentro de cada proyecto.",
+  "cli.help.globalWorkflow.line1": "Instala la skill con 'npx skills add Baxahaun/trackops' y luego el runtime con 'npm install -g trackops'.",
+  "cli.help.globalWorkflow.line2": "Despues verifica con 'trackops --version' y usa 'trackops init' y 'trackops opera install' de forma explicita dentro de cada proyecto.",
   "cli.usage.workspace": "Uso: trackops workspace <status|migrate>",
   "cli.usage.env": "Uso: trackops env <status|sync>",
   "cli.usage.opera": "Uso: trackops opera <install|bootstrap|handoff|status|configure|upgrade>",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackops",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Operational project control with task management, document generation, multi-project dashboard, and optional OPERA methodology",
   "main": "lib/control.js",
   "bin": {

package/scripts/skills-marketplace-smoke.js

@@ -108,9 +108,9 @@ function main() {
   assert.ok(installed.length >= 1, `trackops skill was not installed under ${homeRoot}`);
 
   const installedSkillDir = installed[0];
-  assert.ok(fs.existsSync(path.join(installedSkillDir, "scripts", "bootstrap-trackops.js")));
   assert.ok(fs.existsSync(path.join(installedSkillDir, "references", "activation.md")));
   assert.ok(fs.existsSync(path.join(installedSkillDir, "skill.json")));
+  assert.ok(!fs.existsSync(path.join(installedSkillDir, "scripts", "bootstrap-trackops.js")));
 
   fs.rmSync(tempRoot, { recursive: true, force: true });
   console.log("skills marketplace smoke OK");

package/scripts/smoke-tests.js

@@ -11,7 +11,6 @@ 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";
@@ -220,17 +219,12 @@ async function main() {
   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 explicitInstall = runNpm(["install", "-g", "--prefix", bootstrapPrefix, tarballPath], tempRoot, bootstrapEnv);
+  assert.strictEqual(explicitInstall.status, 0, explicitInstall.stderr || explicitInstall.stdout || "instalacion global explicita fallo");
 
   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");
   assert.ok(["es", "en"].includes(runtimeStamp.locale), "el bootstrap global debe fijar un idioma");
 
   const installedCli = path.join(bootstrapPrefix, "node_modules", "trackops", "bin", "trackops.js");
@@ -238,16 +232,6 @@ async function main() {
   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);

package/scripts/validate-skill.js

@@ -10,7 +10,6 @@ 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"),
@@ -48,8 +47,8 @@ function main() {
     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'.");
+  if (skill.bootstrapPolicy !== "explicit_install") {
+    fail("skills/trackops/skill.json must use bootstrapPolicy 'explicit_install'.");
   }
 
   const supportedAgents = Array.isArray(skill.supportedAgentsV1) ? skill.supportedAgentsV1 : [];
@@ -73,7 +72,8 @@ function main() {
 
   for (const requiredPhrase of [
     "npx skills add Baxahaun/trackops",
-    "node scripts/bootstrap-trackops.js",
+    "npm install -g trackops",
+    "trackops --version",
     "trackops init",
     "trackops opera install",
     "trackops opera bootstrap --resume",
@@ -83,6 +83,20 @@ function main() {
     }
   }
 
+  for (const forbiddenPhrase of [
+    "node scripts/bootstrap-trackops.js",
+    "ensures the runtime on first use",
+    "asegura el runtime en el primer uso",
+  ]) {
+    if (skillMd.includes(forbiddenPhrase)) {
+      fail(`skills/trackops/SKILL.md must not mention '${forbiddenPhrase}'.`);
+    }
+  }
+
+  if (fs.existsSync(path.join(SKILL_DIR, "scripts", "bootstrap-trackops.js"))) {
+    fail("skills/trackops must not publish scripts/bootstrap-trackops.js.");
+  }
+
   console.log("skills/trackops validated successfully.");
 }
 

package/skills/trackops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "trackops"
-description: "Skill global de TrackOps para instalar y activar la orquestacion local de proyectos con OPERA, entorno y handoff a agentes. Usala cuando el usuario quiera instalar TrackOps desde skills.sh, bootstrapear el runtime con `node scripts/bootstrap-trackops.js`, ejecutar `trackops init`, ejecutar `trackops opera install`, revisar `trackops opera handoff`, o trabajar sobre el flujo operativo de un repositorio."
+description: "Skill global de TrackOps para preparar al agente, exigir la instalacion explicita del runtime con npm y guiar la activacion local de TrackOps y OPERA dentro de cada repositorio."
 ---
 
 # TrackOps
@@ -15,19 +15,19 @@ Instala la skill del marketplace con:
 npx skills add Baxahaun/trackops
 ```
 
-Antes de depender del CLI, ejecuta el script empaquetado de la skill:
+Despues, confirma que el runtime `trackops` existe. Si no esta disponible, pide al usuario que lo instale de forma explicita:
 
 ```bash
-node scripts/bootstrap-trackops.js
+npm install -g trackops
+trackops --version
 ```
 
-Ese bootstrap:
+Reglas:
 
-- asegura el runtime npm de `trackops`
-- valida que el binario global sea ejecutable
-- registra estado en `~/.trackops/runtime.json`
-
-No debe crear archivos dentro de un repositorio por si solo.
+- la skill no debe instalar paquetes ni ejecutar codigo remoto por si sola
+- el runtime se instala con un paso visible y auditable
+- la skill puede verificar `trackops --version`, pero no debe encadenar instalaciones silenciosas
+- la skill no debe crear archivos dentro de un repositorio por si sola
 
 ## Capa local del proyecto
 
@@ -40,7 +40,8 @@ trackops opera install
 
 Reglas base:
 
-- trata la instalacion global como no invasiva
+- trata la skill global como capa de instrucciones
+- trata la instalacion del runtime como explicita y separada
 - usa `ops/contract/operating-contract.json` como contrato de maquina cuando exista
 - usa `ops/project_control.json` como fuente de verdad operativa
 - usa `ops/policy/autonomy.json` antes de acciones sensibles
@@ -81,6 +82,6 @@ trackops opera bootstrap --resume
 
 ## Que referencia leer y cuando
 
-- lee `references/activation.md` solo para instalacion, primer uso, locale bootstrap y activacion de un repo
+- lee `references/activation.md` solo para instalacion, verificacion del runtime, locale bootstrap y activacion de un repo
 - lee `references/workflow.md` solo cuando TrackOps ya esta activo y haga falta operar el dia a dia del repositorio
-- lee `references/troubleshooting.md` solo cuando fallen la instalacion, el bootstrap, el resume o el contrato de entorno
+- lee `references/troubleshooting.md` solo cuando fallen la instalacion explicita, la deteccion de `trackops`, el resume o el contrato de entorno

package/skills/trackops/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "TrackOps"
-  short_description: "Bootstrap TrackOps and activate OPERA"
-  default_prompt: "Use $trackops to bootstrap the TrackOps runtime and activate OPERA in this repository."
+  short_description: "Guide explicit TrackOps install and activate OPERA"
+  default_prompt: "Use $trackops to install the global skill, require explicit npm installation of the TrackOps runtime, and then activate TrackOps and OPERA in this repository."
 
 policy:
   allow_implicit_invocation: true

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

@@ -1,6 +1,6 @@
 ---
 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 preparing the agent, requiring explicit npm runtime installation, and guiding local TrackOps and OPERA activation inside each repository."
 ---
 
 # TrackOps
@@ -15,19 +15,19 @@ 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`
-
-It must not create repository files on its own.
+- 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
 
 ## Local project layer
 
@@ -40,7 +40,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
@@ -81,6 +82,6 @@ trackops opera bootstrap --resume
 
 ## 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 for secure agent guidance, explicit runtime install, bilingual onboarding, and local project orchestration.",
+  "description": "Installs TrackOps as a global skill, requires explicit runtime installation with npm, 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.2",
+  "trackopsVersion": "2.0.2",
   "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();