trackops 1.1.0 → 2.0.1

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

@@ -0,0 +1,86 @@
+---
+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."
+---
+
+# TrackOps
+
+Use this localized file when the conversation and project should run in English.
+
+## Global layer
+
+Install the marketplace skill with:
+
+```bash
+npx skills add Baxahaun/trackops
+```
+
+Before relying on the CLI, run the bundled skill script:
+
+```bash
+node scripts/bootstrap-trackops.js
+```
+
+That bootstrap:
+
+- 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.
+
+## Local project layer
+
+Inside the repository:
+
+```bash
+trackops init
+trackops opera install
+```
+
+Core rules:
+
+- treat the global install as non-invasive
+- 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
+- use `/.env` and `/.env.example` as the environment contract
+- keep generated operational docs under `ops/`
+- use `trackops locale get|set` and `trackops doctor locale` when language matters
+
+## OPERA onboarding
+
+OPERA no longer assumes every user is technical.
+
+TrackOps classifies:
+
+- user technical level
+- current project state
+- available documentation
+
+Then it chooses one of two routes:
+
+- `direct bootstrap`
+  for technical users and already-defined repositories
+- `agent handoff`
+  for early ideas, non-technical users, or weak documentation
+
+If TrackOps routes bootstrap to the agent:
+
+- read `ops/bootstrap/agent-handoff.md`
+- or print it with `trackops opera handoff --print`
+- require these outputs:
+  - `ops/bootstrap/intake.json`
+  - `ops/bootstrap/spec-dossier.md`
+  - `ops/bootstrap/open-questions.md` when important gaps remain
+- resume with:
+
+```bash
+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/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

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

@@ -0,0 +1,73 @@
+# Activation
+
+## Global install
+
+Install the marketplace skill:
+
+```bash
+npx skills add Baxahaun/trackops
+```
+
+On first use, ensure the runtime with the bundled skill script:
+
+```bash
+node scripts/bootstrap-trackops.js
+```
+
+The global skill must not create repository files on its own.
+
+## Local activation
+
+Inside a repository:
+
+```bash
+trackops init
+trackops opera install
+```
+
+By default, `trackops init` creates a split workspace with:
+
+- `app/`
+- `ops/`
+- `/.env`
+- `/.env.example`
+- `.trackops-workspace.json`
+
+## OPERA routing
+
+OPERA always starts by classifying:
+
+- technical level
+- project state
+- documentation state
+
+If the project is still early or the user is non-technical, TrackOps writes:
+
+- `ops/bootstrap/agent-handoff.md`
+- `ops/bootstrap/agent-handoff.json`
+
+The agent must produce:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+- `ops/bootstrap/open-questions.md` when needed
+
+When the quality gate passes, OPERA compiles:
+
+- `ops/contract/operating-contract.json`
+- `ops/genesis.md`
+- `ops/policy/autonomy.json`
+
+Resume with:
+
+```bash
+trackops opera bootstrap --resume
+```
+
+Locale controls:
+
+```bash
+trackops locale get
+trackops locale set en
+trackops doctor locale
+```

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

@@ -0,0 +1,49 @@
+# Troubleshooting
+
+## Missing prerequisites
+
+- 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
+
+- Install from committed GitHub state:
+  `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`.
+
+## OPERA routed bootstrap to the agent
+
+This is expected when:
+
+- the user is non-technical
+- the project is still in idea stage
+- documentation is weak
+
+Use:
+
+```bash
+trackops opera handoff --print
+trackops opera bootstrap --resume
+```
+
+## Resume does not complete
+
+TrackOps will not invent missing context.
+
+Check that both files exist and contain usable data:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+
+## Environment looks inconsistent
+
+- Run `trackops env status`.
+- Run `trackops env sync`.
+- If bridge mode is `copy`, do not edit `app/.env` directly.

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

@@ -0,0 +1,26 @@
+# Workflow
+
+Once TrackOps is active in a repository:
+
+1. Run `trackops status`.
+2. Run `trackops next`.
+3. Move task state with `trackops task ...`.
+4. Run `trackops sync` after meaningful changes.
+5. Run `trackops env status` when credentials matter.
+
+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.
+
+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.

package/skills/trackops/references/activation.md

@@ -1,39 +1,73 @@
-# Activation
+# Activacion
 
-## Global install
+## Instalacion global
 
-The marketplace skill prepares TrackOps globally for the agent. It must not create repo files by itself.
-
-Install it with:
+Instala la skill del marketplace:
 
 ```bash
-npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y
+npx skills add Baxahaun/trackops
 ```
 
-Replace `codex` with any supported target: `antigravity`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `github-copilot`, or `kiro-cli`.
-
-Before using TrackOps commands, run:
+En primer uso, asegura el runtime con el script empaquetado de la skill:
 
 ```bash
 node scripts/bootstrap-trackops.js
 ```
 
-That bootstrap validates prerequisites, installs or updates the TrackOps runtime, and records state in `~/.trackops/runtime.json`.
+La skill global no debe crear archivos dentro de repositorios por si sola.
 
-## Local activation
+## Activacion local
 
-Inside a repository, the normal flow is:
+Dentro de un repositorio:
 
 ```bash
 trackops init
 trackops opera install
 ```
 
-Rules:
+Por defecto, `trackops init` crea un workspace split con:
+
+- `app/`
+- `ops/`
+- `/.env`
+- `/.env.example`
+- `.trackops-workspace.json`
+
+## Routing de OPERA
+
+OPERA siempre empieza clasificando:
+
+- nivel tecnico
+- estado del proyecto
+- estado de la documentacion
+
+Si el proyecto aun esta verde o el usuario no es tecnico, TrackOps escribe:
+
+- `ops/bootstrap/agent-handoff.md`
+- `ops/bootstrap/agent-handoff.json`
+
+El agente debe producir:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+- `ops/bootstrap/open-questions.md` cuando haga falta
 
-- 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.
+Cuando el quality gate pasa, OPERA compila:
+
+- `ops/contract/operating-contract.json`
+- `ops/genesis.md`
+- `ops/policy/autonomy.json`
+
+Reanuda con:
+
+```bash
+trackops opera bootstrap --resume
+```
+
+Controles de idioma:
+
+```bash
+trackops locale get
+trackops locale set en
+trackops doctor locale
+```

package/skills/trackops/references/troubleshooting.md

@@ -1,34 +1,49 @@
 # Troubleshooting
 
-## Missing prerequisites
+## Faltan prerequisitos
 
-- If Node is missing or older than 18, install Node 18+ first.
-- If npm is missing, install a Node distribution that includes npm.
+- Instala Node 18+ si Node falta o es demasiado antiguo.
+- Instala una distribucion de Node que incluya npm si falta npm.
 
-## skills cannot find the TrackOps skill
+## Fallo al instalar la skill global
 
-- Install from the repository root:
-  `npx skills add Baxahaun/trackops --skill trackops --full-depth --global --agent codex -y`
-- Confirm the remote repository already contains the latest committed skill changes.
-- Remember that skills installs from committed Git state, not from uncommitted local changes.
+- Instala desde el estado committeado de GitHub:
+  `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.
 
-## Global npm install failed
+## Fallo en el bootstrap del runtime
 
-- Re-run `node scripts/bootstrap-trackops.js` and inspect stderr.
-- If npm global permissions are blocked, configure a user-writable npm prefix instead of relying on `sudo`.
+- Reejecuta `node scripts/bootstrap-trackops.js`.
+- Si fallan los permisos globales de npm, configura un prefix de usuario en lugar de usar `sudo`.
 
-## Runtime cannot be verified
+## OPERA ha derivado el bootstrap al agente
 
-If installation succeeds but `trackops` is still not executable:
+Es el comportamiento esperado cuando:
 
-- Check whether the npm global bin directory is on `PATH`.
-- Re-open the terminal after updating shell profile settings.
-- Re-run `node scripts/bootstrap-trackops.js` once `trackops --version` works.
+- el usuario no es tecnico
+- el proyecto sigue en fase idea
+- la documentacion es debil
 
-## Workspace environment looks inconsistent
+Usa:
 
-If a split workspace is active and tools do not see the expected environment file:
+```bash
+trackops opera handoff --print
+trackops opera bootstrap --resume
+```
 
-- Run `trackops env status` to inspect required, present, and missing keys without exposing values.
-- Run `trackops env sync` to recreate `/.env`, `/.env.example`, and the `app/.env` bridge.
-- If bridge mode is `copy`, do not edit `app/.env` directly; TrackOps regenerates it from the root `.env`.
+## El resume no completa
+
+TrackOps no inventa contexto faltante.
+
+Comprueba que ambos archivos existan y contengan datos utilizables:
+
+- `ops/bootstrap/intake.json`
+- `ops/bootstrap/spec-dossier.md`
+
+## El entorno parece inconsistente
+
+- Ejecuta `trackops env status`.
+- Ejecuta `trackops env sync`.
+- Si el bridge mode es `copy`, no edites `app/.env` directamente.

package/skills/trackops/references/workflow.md

@@ -1,20 +1,26 @@
 # Workflow
 
-Once TrackOps is active in a repository, operate in this order:
+Una vez que TrackOps esta activo en un repositorio:
 
-1. Run `trackops status` to inspect focus, phase, blockers, and repo state.
-2. Run `trackops next` to identify the next ready task.
-3. Update task state with `trackops task ...` as work progresses.
-4. Run `trackops sync` after meaningful changes so generated docs stay aligned.
-5. Run `trackops env status` when the project depends on credentials or external services.
+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.
 
-Operational rules:
+Reglas operativas:
 
-- In split workspaces, use `ops/project_control.json` as the source of truth.
-- In legacy repos, use `project_control.json` at repo root.
-- In split workspaces, generated operational docs live under `ops/`.
-- Product code lives under `app/`.
-- Use `/.env` for real secrets and `/.env.example` for the public environment contract.
-- `app/.env` is only a compatibility bridge.
-- If OPERA is installed, use `ops/genesis.md`, `ops/.agent/hub/`, and `ops/.agents/skills/_registry.md` as managed framework artifacts.
-- Keep the global skill layer separate from the local project layer.
+- 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.
+
+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.

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

@@ -4,6 +4,7 @@ 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,
@@ -129,10 +130,9 @@ function runInstall(config, prefix) {
 }
 
 function writeRuntimeStamp(config, verification) {
-  const runtimeDir = path.join(getHomeDir(), ".trackops");
-  const runtimeFile = path.join(runtimeDir, "runtime.json");
-  fs.mkdirSync(runtimeDir, { recursive: true });
-  const payload = {
+  const previous = runtimeState.readRuntimeState();
+  const payload = runtimeState.writeRuntimeState({
+    ...previous,
     skill: config.name,
     skillVersion: config.skillVersion,
     runtimePackage: config.npmPackage,
@@ -142,8 +142,8 @@ function writeRuntimeStamp(config, verification) {
     verifiedAt: new Date().toISOString(),
     verifiedWith: verification.installed.via,
     executable: verification.installed.command,
-  };
-  fs.writeFileSync(runtimeFile, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+  });
+  return payload;
 }
 
 function printInstallGuidance(prefix) {
@@ -157,7 +157,7 @@ function printInstallGuidance(prefix) {
   console.error("Add your npm global bin directory to PATH, reopen the terminal, and retry.");
 }
 
-function main() {
+async function main() {
   const config = readSkillConfig();
   const prefix = getPrefixOverride();
 
@@ -173,6 +173,7 @@ function main() {
 
   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);
@@ -193,6 +194,7 @@ function main() {
     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);

package/skills/trackops/skill.json

@@ -1,9 +1,9 @@
 {
   "name": "trackops",
-  "shortDescription": "Global TrackOps skill for local project orchestration and operational automation with AI agents.",
-  "description": "Installs TrackOps as a global skill, prepares your agent for local project orchestration, ensures the runtime on first use, and guides per-project activation with optional OPERA.",
-  "skillVersion": "1.1.0",
-  "trackopsVersion": "1.1.0",
+  "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",
   "npmPackage": "trackops",
   "bootstrapPolicy": "first_use",
   "supportedAgentsV1": [

package/templates/opera/agent.md

@@ -4,23 +4,24 @@
 Eres el agente principal del proyecto **{{PROJECT_NAME}}**. Operas bajo el protocolo O.P.E.R.A. v3.0.
 
 ## Fuente de Verdad
-Tu fuente de verdad es `genesis.md`. Antes de tomar cualquier decisión, consulta este archivo.
-Para el seguimiento operativo y el estado del backlog, usa `project_control.json`.
+Tu fuente de verdad de maquina es `ops/contract/operating-contract.json`.
+Tu vista humana compilada es `ops/genesis.md`.
+Para el seguimiento operativo y el estado del backlog, usa `ops/project_control.json`.
 
 ## Comportamiento
-- Sigue las reglas de comportamiento definidas en `genesis.md`.
-- Respeta la Matriz de Autonomía (Semáforo) para determinar qué acciones puedes tomar.
-- Gestiona tareas y estados desde `project_control.json`.
-- No edites manualmente `task_plan.md`, `progress.md` ni `findings.md`; se regeneran con `trackops sync`.
+- Sigue las reglas definidas en `ops/contract/operating-contract.json` y reflejadas en `ops/genesis.md`.
+- Respeta `ops/policy/autonomy.json` para determinar qué acciones puedes tomar sin aprobacion.
+- Gestiona tareas y estados desde `ops/project_control.json`.
+- No edites manualmente `ops/task_plan.md`, `ops/progress.md` ni `ops/findings.md`; se regeneran con `trackops sync`.
 
 ## Skills Disponibles
-Consulta `.agents/skills/_registry.md` para ver las skills instaladas.
+Consulta `ops/.agents/skills/_registry.md` para ver las skills instaladas.
 También puedes buscar nuevas skills con `trackops skill catalog`.
 
 ## Ciclo de Trabajo
 1. Ejecuta `trackops status` al inicio de cada bloque de trabajo.
-2. Consulta `genesis.md` para entender los datos y reglas.
+2. Consulta `ops/contract/operating-contract.json` y `ops/genesis.md` para entender el contrato y su vista humana.
 3. Usa `trackops next` para ver la siguiente cola priorizada.
 4. Antes de implementar, marca la tarea con `trackops task start <task-id>`.
-5. Usa el router (`.agent/hub/router.md`) para saber qué skill aplicar.
+5. Usa el router (`ops/.agent/hub/router.md`) para saber que skill aplicar.
 6. Al terminar, pasa la tarea a `review`, `complete` o `block` y ejecuta `trackops sync`.

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

@@ -0,0 +1,24 @@
+# Dependency Graph
+
+```mermaid
+flowchart TD
+    A[Global runtime bootstrap] --> B[trackops init]
+    B --> C[trackops opera install]
+    C --> D{Routing}
+    D -->|direct_cli| E[Direct intake]
+    D -->|agent_handoff| F[agent-handoff.md/json]
+    F --> G[intake.json + spec-dossier.md]
+    E --> H[quality-report.json]
+    G --> H
+    H --> I[operating-contract.json]
+    I --> J[genesis.md]
+    I --> K[task_plan.md / progress.md / findings.md]
+    I --> L[dashboard + API state]
+    I --> M[env sync + policy enforcement]
+```
+
+## Notes
+
+- `ops/project_control.json` is the operational source of truth for backlog and session state.
+- `ops/contract/operating-contract.json` is the machine contract.
+- `ops/genesis.md` is a compiled human view.

package/templates/opera/architecture/runtime-automation.md

@@ -0,0 +1,24 @@
+# SOP - Runtime Automation
+
+## Objective
+
+Keep validation automatic on every relevant change.
+
+## Trigger policy
+
+- Validate on push to `develop` and `master`.
+- Validate on pull requests targeting `develop` or `master`.
+- Allow manual execution with workflow dispatch.
+
+## Validation circuit
+
+1. Install Node 18 and 20.
+2. Install runtime dependencies.
+3. Run `npm run release:check`.
+4. Fail fast on any smoke, skill or packaging regression.
+
+## Release hygiene
+
+- Do not publish if `release:check` fails.
+- Do not treat local runtime state as deployable proof.
+- Re-run smoke after structural or locale changes.

package/templates/opera/architecture/runtime-operations.md

@@ -0,0 +1,34 @@
+# SOP - Runtime Operations
+
+## Purpose
+
+Define the minimum operating procedure to keep a TrackOps + OPERA workspace healthy.
+
+## Inputs
+
+- `ops/project_control.json`
+- `ops/contract/operating-contract.json`
+- `ops/policy/autonomy.json`
+- `ops/bootstrap/quality-report.json`
+
+## Core checks
+
+1. Run `trackops status`.
+2. Run `trackops opera status`.
+3. Run `trackops env status`.
+4. Confirm `contract readiness` is not `hypothesis` for active delivery work.
+5. Confirm `legacyStatus` is `supported`.
+
+## Recovery path
+
+1. If bootstrap is incomplete, run `trackops opera handoff --print`.
+2. If discovery artifacts already exist, run `trackops opera bootstrap --resume`.
+3. If operational docs drift, run `trackops sync`.
+4. If managed artifacts drift, run `trackops opera upgrade --stable`.
+
+## Exit criteria
+
+- Runtime status is readable.
+- OPERA status is readable.
+- Contract and policy files exist.
+- No critical blocker remains undocumented.