trackops 1.0.1 → 2.0.0

package/skills/trackops/SKILL.md

@@ -0,0 +1,89 @@
+---
+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: "2.0.0"
+  type: "global"
+  triggers:
+    - "install trackops"
+    - "skills.sh"
+    - "trackops init"
+    - "trackops opera install"
+    - "opera handoff"
+---
+
+# TrackOps
+
+Use this skill in two layers.
+
+## 1. Global skill layer
+
+Install it with:
+
+```bash
+npx skills add Baxahaun/trackops
+```
+
+Before relying on the CLI, run:
+
+```bash
+node scripts/bootstrap-trackops.js
+```
+
+That bootstrap ensures the `trackops` runtime and records state in `~/.trackops/runtime.json`.
+
+## 2. Local project layer
+
+Inside a repository:
+
+```bash
+trackops init
+trackops opera install
+```
+
+Core rules:
+
+- treat the global skill 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 for backlog and state
+- use `ops/policy/autonomy.json` before approval-sensitive actions
+- use `/.env` and `/.env.example` as the environment contract
+- keep generated operational docs under `ops/`
+- support `trackops locale get|set` and `trackops doctor locale` when language matters
+
+## OPERA onboarding
+
+OPERA no longer assumes every user is technical.
+
+When OPERA starts, 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`
+- the agent must produce:
+  - `ops/bootstrap/intake.json`
+  - `ops/bootstrap/spec-dossier.md`
+  - `ops/bootstrap/open-questions.md` when important gaps remain
+- then resume with:
+
+```bash
+trackops opera bootstrap --resume
+```
+
+Read references only when needed:
+
+- `references/activation.md`
+- `references/workflow.md`
+- `references/troubleshooting.md`

package/skills/trackops/agents/openai.yaml

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

package/skills/trackops/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:
+
+```bash
+node scripts/bootstrap-trackops.js
+```
+
+The global skill must not create repository files by itself.
+
+## 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 then produces:
+
+- `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/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/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/scripts/bootstrap-trackops.js

@@ -0,0 +1,203 @@
+#!/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();

package/skills/trackops/skill.json

@@ -0,0 +1,29 @@
+{
+  "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.0",
+  "trackopsVersion": "2.0.0",
+  "npmPackage": "trackops",
+  "bootstrapPolicy": "first_use",
+  "supportedAgentsV1": [
+    "antigravity",
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "github-copilot",
+    "kiro-cli"
+  ],
+  "distribution": {
+    "source": "Baxahaun/trackops",
+    "skill": "trackops",
+    "fullDepth": true
+  },
+  "repository": {
+    "provider": "github",
+    "owner": "Baxahaun",
+    "repo": "trackops",
+    "skillPath": "skills/trackops"
+  }
+}

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.

package/templates/opera/en/agent.md

@@ -0,0 +1,27 @@
+# Project Agent: {{PROJECT_NAME}}
+
+## Identity
+You are the primary agent for **{{PROJECT_NAME}}**. You operate under the O.P.E.R.A. v3.0 protocol.
+
+## Source of Truth
+Your machine source of truth is `ops/contract/operating-contract.json`.
+Your compiled human view is `ops/genesis.md`.
+For operational tracking and backlog state, use `ops/project_control.json`.
+
+## Behavior
+- Follow the rules defined in `ops/contract/operating-contract.json` and reflected in `ops/genesis.md`.
+- Respect `ops/policy/autonomy.json` to determine which actions are allowed without approval.
+- Manage tasks and states from `ops/project_control.json`.
+- Do not edit `ops/task_plan.md`, `ops/progress.md`, or `ops/findings.md` manually; regenerate them with `trackops sync`.
+
+## Available Skills
+Check `ops/.agents/skills/_registry.md` to see installed skills.
+You can also discover new skills with `trackops skill catalog`.
+
+## Work Cycle
+1. Run `trackops status` at the beginning of each work block.
+2. Read `ops/contract/operating-contract.json` and `ops/genesis.md` to understand the contract and its human view.
+3. Use `trackops next` to inspect the prioritized queue.
+4. Before implementing, mark the task with `trackops task start <task-id>`.
+5. Use the router in `ops/.agent/hub/router.md` to choose the right skill.
+6. When you finish, move the task to `review`, `complete`, or `block`, then run `trackops sync`.

package/templates/opera/en/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/en/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.