trackops 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xavier Crespo Gríman — Baxahaun AI Venture Studio (https://baxahaun.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,358 @@
+<p align="center">
+  <img src="docs/assets/TrackOps.webp" alt="TrackOps" width="400" />
+</p>
+
+<h1 align="center">TrackOps</h1>
+
+<p align="center">
+  <strong>El motor operativo open-source para desarrolladores que construyen con IA.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/trackops"><img src="https://img.shields.io/npm/v/trackops?color=D97706&style=flat-square" alt="npm" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/licencia-MIT-22C55E?style=flat-square" alt="MIT" /></a>
+  <img src="https://img.shields.io/badge/dependencias-0-D97706?style=flat-square" alt="0 deps" />
+  <img src="https://img.shields.io/badge/node-%3E%3D18-333?style=flat-square" alt="Node 18+" />
+</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>
+</p>
+
+<br/>
+
+---
+
+## Español
+
+### El Problema: La IA es rápida. El caos también.
+
+Escribir código con asistentes de IA (Cursor, Copilot, Claude Code, agentes autónomos) es increíblemente rápido. Pero a medida que el proyecto crece, **la IA pierde el contexto**, olvida las prioridades y el proyecto se convierte en una pesadilla de mantenimiento.
+
+Tu agente no sabe qué tarea es prioritaria. No sabe qué está bloqueado. No sabe en qué fase estás. Y tú terminas repitiendo instrucciones en cada prompt.
+
+### La Solución: TrackOps
+
+TrackOps es un **motor operativo local de código abierto** que actúa como puente entre tú (el humano) y tus agentes de IA.
+
+**Tú** gestionas el proyecto visualmente a través de un elegante **Dashboard Web local**. TrackOps compila automáticamente ese estado en **archivos Markdown hiper-estructurados** (`task_plan.md`, `progress.md`, `findings.md`) que tu IA lee para saber exactamente qué hacer, qué reglas seguir y qué prioridades existen.
+
+> **La IA se encarga del código. TrackOps se encarga del proyecto.**
+
+<br/>
+
+### Por qué TrackOps se volverá indispensable en tu flujo
+
+| | |
+|---|---|
+| **Adopción en 10 segundos** | Un solo comando: `npx trackops init`. Cero configuración, cero dependencias, cero bases de datos. |
+| **Contexto determinista** | No dejes que la IA adivine. TrackOps sincroniza la verdad absoluta de tu proyecto en archivos Markdown que las IAs entienden nativamente. |
+| **Dashboard local premium** | Interfaz web profesional que corre en tu terminal. Sin telemetría, sin nube, **100% privado**. |
+| **Integración Git nativa** | TrackOps sabe cuándo haces commit, merge o checkout, capturando la salud del repositorio de forma automática. |
+| **Portfolio multi-proyecto** | Registra todos tus proyectos y navega entre ellos desde un solo dashboard. |
+| **Framework OPERA** | Metodología de desarrollo con agentes IA en 5 fases: Orquestar, Probar, Estructurar, Refinar, Automatizar. |
+| **Ecosistema de Skills** | Plugins modulares que dotan a tu proyecto de capacidades automatizadas: `trackops skill install <nombre>`. |
+
+<br/>
+
+### Inicio Rápido
+
+No necesitas instalar nada globalmente. Ve a cualquier proyecto y ejecuta:
+
+```bash
+npx trackops init               # Inicializa el motor en tu proyecto
+npx trackops dashboard           # Levanta el centro de control web
+```
+
+El flujo desde consola en tu día a día:
+
+```bash
+npx trackops status              # Salud del proyecto y bloqueos
+npx trackops next                # Siguiente tarea priorizada
+npx trackops task start T-001    # Empieza a trabajar
+npx trackops sync                # Genera contexto Markdown para tu IA
+```
+
+<br/>
+
+### Arquitectura de 3 Capas
+
+Diseñado para escalar desde un script de fin de semana hasta infraestructura empresarial.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Capa 3 · Ecosistema de Skills                      │
+│  Plugins modulares para automatizar capacidades     │
+│  trackops skill install / list / remove / catalog   │
+├─────────────────────────────────────────────────────┤
+│  Capa 2 · Framework OPERA (opcional)                │
+│  Enrutamiento de agentes y metodología estructurada │
+│  trackops opera install / configure / status        │
+├─────────────────────────────────────────────────────┤
+│  Capa 1 · Motor Core (siempre activo)               │
+│  CLI + Servidor Web Local + Generador de Markdown   │
+│  tareas · dashboard · registro · git hooks · sync   │
+└─────────────────────────────────────────────────────┘
+```
+
+<br/>
+
+### Metodología OPERA
+
+Framework opcional de 5 fases para desarrollo estructurado con IA. Cada fase tiene un **Definition of Done** verificable:
+
+| Fase | Nombre | Foco | Entregable |
+|------|--------|------|------------|
+| **O** | Orquestar | Visión, datos, reglas de negocio | Schema JSON en `genesis.md` |
+| **P** | Probar | Conectividad y validación | Scripts de test pasando |
+| **E** | Estructurar | Construcción en 3 capas | SOPs + tools + integración |
+| **R** | Refinar | Refinamiento y calidad | Outputs validados |
+| **A** | Automatizar | Despliegue y triggers | Triggers + smoke test |
+
+Las fases son totalmente configurables por proyecto vía `project_control.json`.
+
+<br/>
+
+### Referencia de Comandos
+
+<details>
+<summary><strong>Motor Core</strong></summary>
+
+| Comando | Descripción |
+|---------|-------------|
+| `trackops init [--with-opera] [--locale es\|en]` | Inicializar en el directorio actual |
+| `trackops status` | Estado: foco, fase, tareas, bloqueadores, repo |
+| `trackops next` | Próximas tareas ejecutables priorizadas |
+| `trackops sync` | Regenerar task_plan.md, progress.md, findings.md |
+| `trackops dashboard` | Lanzar dashboard web local |
+| `trackops task <acción> <id> [nota]` | start, review, complete, block, pending, cancel, note |
+| `trackops refresh-repo [--quiet]` | Actualizar runtime con estado del repo |
+| `trackops register` | Registrar en el portfolio multi-proyecto |
+| `trackops projects` | Listar proyectos registrados |
+
+</details>
+
+<details>
+<summary><strong>OPERA</strong></summary>
+
+| Comando | Descripción |
+|---------|-------------|
+| `trackops opera install` | Instalar metodología OPERA |
+| `trackops opera status` | Estado de instalación e integridad |
+| `trackops opera configure [--phases '...']` | Reconfigurar fases o idioma |
+| `trackops opera upgrade` | Actualizar templates a la versión del paquete |
+
+</details>
+
+<details>
+<summary><strong>Skills</strong></summary>
+
+| Comando | Descripción |
+|---------|-------------|
+| `trackops skill install <nombre>` | Instalar skill del catálogo |
+| `trackops skill list` | Listar skills instaladas |
+| `trackops skill remove <nombre>` | Desinstalar skill |
+| `trackops skill catalog` | Ver skills disponibles |
+
+</details>
+
+<br/>
+
+### Estructura del Proyecto
+
+```
+mi-proyecto/
+├── project_control.json       # Fuente de verdad operativa
+├── task_plan.md               # Plan de tareas (auto-generado)
+├── progress.md                # Diario de progreso (auto-generado)
+├── findings.md                # Hallazgos (auto-generado)
+├── genesis.md                 # Constitución del proyecto (OPERA)
+├── .agent/hub/                # Identidad del agente + router (OPERA)
+└── .agents/skills/            # Skills instaladas (OPERA)
+```
+
+<br/>
+
+### Apoya el Proyecto
+
+TrackOps es y siempre será **libre, gratuito y de código abierto** (MIT). Construimos esto para resolver un problema real de la comunidad de desarrolladores.
+
+Si TrackOps te ha ayudado a recuperar el control de tus proyectos con IA:
+
+1. **Dale una estrella en GitHub** — ayuda enormemente a la visibilidad.
+2. **Comparte TrackOps** con tu equipo y en tus redes.
+3. **Contribuye** — Pull Requests, reporte de bugs y nuevas Skills son siempre bienvenidos.
+
+<br/>
+
+---
+
+## English
+
+### The Problem: AI is fast. So is chaos.
+
+Writing code with AI assistants (Cursor, Copilot, Claude Code, autonomous agents) is incredibly fast. But as the project grows, **the AI loses context**, forgets priorities, and the project becomes a maintenance nightmare.
+
+Your agent doesn't know which task is a priority. It doesn't know what's blocked. It doesn't know what phase you're in. And you end up repeating instructions in every prompt.
+
+### The Solution: TrackOps
+
+TrackOps is a **local, open-source operational engine** that acts as a bridge between you (the human) and your AI agents.
+
+**You** manage the project visually through an elegant **local Web Dashboard**. TrackOps automatically compiles that state into **hyper-structured Markdown files** (`task_plan.md`, `progress.md`, `findings.md`) that your AI reads to know exactly what to do, what rules to follow, and what priorities exist.
+
+> **AI handles the code. TrackOps handles the project.**
+
+<br/>
+
+### Why TrackOps will become essential in your workflow
+
+| | |
+|---|---|
+| **10-second adoption** | One command: `npx trackops init`. Zero config, zero dependencies, zero databases. |
+| **Deterministic context** | Don't let AI guess. TrackOps syncs the absolute truth of your project into Markdown files that AIs understand natively. |
+| **Premium local dashboard** | Professional web interface running in your terminal. No telemetry, no cloud, **100% private**. |
+| **Native Git integration** | TrackOps knows when you commit, merge, or checkout, capturing repository health automatically. |
+| **Multi-project portfolio** | Register all your projects and navigate between them from a single dashboard. |
+| **OPERA Framework** | AI development methodology in 5 phases: Orchestrate, Prove, Establish, Refine, Automate. |
+| **Skills ecosystem** | Modular plugins that give your project automated capabilities: `trackops skill install <name>`. |
+
+<br/>
+
+### Quick Start
+
+No global install needed. Go to any project and run:
+
+```bash
+npx trackops init               # Initialize the engine in your project
+npx trackops dashboard           # Launch the web control center
+```
+
+Your daily workflow from the console:
+
+```bash
+npx trackops status              # Project health and blockers
+npx trackops next                # Next prioritized task
+npx trackops task start T-001    # Start working
+npx trackops sync                # Generate Markdown context for your AI
+```
+
+<br/>
+
+### 3-Layer Architecture
+
+Designed to scale from a weekend script to enterprise infrastructure.
+
+```
+┌─────────────────────────────────────────────────────┐
+│  Layer 3 · Skills Ecosystem                         │
+│  Modular plugins for automated capabilities         │
+│  trackops skill install / list / remove / catalog   │
+├─────────────────────────────────────────────────────┤
+│  Layer 2 · OPERA Framework (optional)               │
+│  Agent routing and structured methodology           │
+│  trackops opera install / configure / status        │
+├─────────────────────────────────────────────────────┤
+│  Layer 1 · Core Engine (always active)              │
+│  CLI + Local Web Server + Markdown Generator        │
+│  tasks · dashboard · registry · git hooks · sync    │
+└─────────────────────────────────────────────────────┘
+```
+
+<br/>
+
+### OPERA Methodology
+
+Optional 5-phase framework for structured AI-assisted development. Each phase has a verifiable **Definition of Done**:
+
+| Phase | Name | Focus | Deliverable |
+|-------|------|-------|-------------|
+| **O** | Orchestrate | Vision, data, business rules | JSON schema in `genesis.md` |
+| **P** | Prove | Connectivity and validation | Passing test scripts |
+| **E** | Establish | 3-layer build | SOPs + tools + integration |
+| **R** | Refine | Refinement and quality | Validated outputs |
+| **A** | Automate | Deployment and triggers | Triggers + smoke test |
+
+Phases are fully configurable per project via `project_control.json`.
+
+<br/>
+
+### Command Reference
+
+<details>
+<summary><strong>Core Engine</strong></summary>
+
+| Command | Description |
+|---------|-------------|
+| `trackops init [--with-opera] [--locale es\|en]` | Initialize in current directory |
+| `trackops status` | State: focus, phase, tasks, blockers, repo |
+| `trackops next` | Next prioritized executable tasks |
+| `trackops sync` | Regenerate task_plan.md, progress.md, findings.md |
+| `trackops dashboard` | Launch local web dashboard |
+| `trackops task <action> <id> [note]` | start, review, complete, block, pending, cancel, note |
+| `trackops refresh-repo [--quiet]` | Update runtime with repo state |
+| `trackops register` | Register in multi-project portfolio |
+| `trackops projects` | List registered projects |
+
+</details>
+
+<details>
+<summary><strong>OPERA</strong></summary>
+
+| Command | Description |
+|---------|-------------|
+| `trackops opera install` | Install OPERA methodology |
+| `trackops opera status` | Installation state and integrity |
+| `trackops opera configure [--phases '...']` | Reconfigure phases or locale |
+| `trackops opera upgrade` | Update templates to package version |
+
+</details>
+
+<details>
+<summary><strong>Skills</strong></summary>
+
+| Command | Description |
+|---------|-------------|
+| `trackops skill install <name>` | Install skill from catalog |
+| `trackops skill list` | List installed skills |
+| `trackops skill remove <name>` | Uninstall skill |
+| `trackops skill catalog` | Show available skills |
+
+</details>
+
+<br/>
+
+### Project Structure
+
+```
+my-project/
+├── project_control.json       # Operational source of truth
+├── task_plan.md               # Task plan (auto-generated)
+├── progress.md                # Progress log (auto-generated)
+├── findings.md                # Findings library (auto-generated)
+├── genesis.md                 # Project constitution (OPERA)
+├── .agent/hub/                # Agent identity + router (OPERA)
+└── .agents/skills/            # Installed skills (OPERA)
+```
+
+<br/>
+
+### Support the Project
+
+TrackOps is and will always be **free and open-source** (MIT). We built this to solve a real problem in the developer community.
+
+If TrackOps has helped you regain control of your AI-assisted projects:
+
+1. **Star us on GitHub** — it helps enormously with visibility.
+2. **Share TrackOps** with your team and on social media.
+3. **Contribute** — Pull Requests, bug reports, and new Skills are always welcome.
+
+<br/>
+
+---
+
+<p align="center">
+  <a href="https://baxahaun.com"><strong>Xavier Crespo Gríman</strong></a> · <a href="https://baxahaun.com">Baxahaun AI Venture Studio</a>
+  <br/>
+  <a href="LICENSE">MIT License</a> · 2026
+</p>

package/bin/trackops.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+const path = require("path");
+const config = require("../lib/config");
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+function resolveRoot() {
+  const root = config.resolveProjectRoot();
+  if (!root) {
+    console.error("No project_control.json found in this directory or any parent.");
+    process.exit(1);
+  }
+  return root;
+}
+
+function run() {
+  try {
+    switch (command) {
+      case "init":
+        require("../lib/init").cmdInit(args);
+        break;
+
+      case "status":
+        require("../lib/control").cmdStatus(resolveRoot());
+        break;
+
+      case "next":
+        require("../lib/control").cmdNext(resolveRoot());
+        break;
+
+      case "sync":
+        require("../lib/control").cmdSync(resolveRoot());
+        break;
+
+      case "dashboard":
+        require("../lib/server").run();
+        break;
+
+      case "refresh-repo":
+        require("../lib/control").cmdRefreshRepo(resolveRoot(), args);
+        break;
+
+      case "install-hooks":
+        require("../lib/control").cmdInstallHooks(resolveRoot());
+        break;
+
+      case "task":
+        require("../lib/control").cmdTask(resolveRoot(), args);
+        break;
+
+      case "register":
+        require("../lib/registry").cmdRegister(config.resolveProjectRoot() || process.cwd());
+        break;
+
+      case "projects":
+        require("../lib/registry").cmdList();
+        break;
+
+      case "opera": {
+        const opera = require("../lib/opera");
+        const sub = args[0];
+        const root = config.resolveProjectRoot() || process.cwd();
+        if (sub === "install") opera.cmdInstall(root, args.slice(1));
+        else if (sub === "status") opera.cmdStatus(root);
+        else if (sub === "configure") opera.cmdConfigure(root, args.slice(1));
+        else if (sub === "upgrade") opera.cmdUpgrade(root);
+        else { console.log("Usage: trackops opera <install|status|configure|upgrade>"); }
+        break;
+      }
+
+      case "skill": {
+        const skills = require("../lib/skills");
+        const sub = args[0];
+        const root = config.resolveProjectRoot() || process.cwd();
+        if (sub === "install") skills.cmdInstall(root, args[1]);
+        else if (sub === "list") skills.cmdList(root);
+        else if (sub === "remove") skills.cmdRemove(root, args[1]);
+        else if (sub === "catalog") skills.cmdCatalog();
+        else { console.log("Usage: trackops skill <install|list|remove|catalog> [name]"); }
+        break;
+      }
+
+      case "help":
+      case "--help":
+      case "-h":
+      case undefined:
+        require("../lib/control").cmdHelp();
+        break;
+
+      default:
+        console.error(`Unknown command: ${command}`);
+        console.error("Run 'trackops help' for usage.");
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+run();

package/lib/config.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_PHASES = [
+  { id: "O", label: "Orquestar", index: 1 },
+  { id: "P", label: "Probar", index: 2 },
+  { id: "E", label: "Estructurar", index: 3 },
+  { id: "R", label: "Refinar", index: 4 },
+  { id: "A", label: "Automatizar", index: 5 },
+];
+
+const DEFAULT_LOCALE = "es";
+
+function resolveProjectRoot(startDir) {
+  let dir = path.resolve(startDir || process.cwd());
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    if (fs.existsSync(path.join(dir, "project_control.json"))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function controlFilePath(root) {
+  return path.join(root, "project_control.json");
+}
+
+function runtimeFilePath(root) {
+  return path.join(root, ".tmp", "project-control-runtime.json");
+}
+
+function docFilePaths(root) {
+  return {
+    taskPlan: path.join(root, "task_plan.md"),
+    progress: path.join(root, "progress.md"),
+    findings: path.join(root, "findings.md"),
+  };
+}
+
+function getPhases(control) {
+  if (
+    Array.isArray(control.meta?.phases) &&
+    control.meta.phases.length > 0
+  ) {
+    return control.meta.phases;
+  }
+  return DEFAULT_PHASES;
+}
+
+function getLocale(control) {
+  return control.meta?.locale || DEFAULT_LOCALE;
+}
+
+function isOperaInstalled(control) {
+  return control.meta?.opera?.installed === true;
+}
+
+function getOperaVersion(control) {
+  return control.meta?.opera?.version || null;
+}
+
+// Backwards-compat aliases
+function isEtapaInstalled(control) { return isOperaInstalled(control); }
+function getEtapaVersion(control) { return getOperaVersion(control); }
+
+function loadControl(root) {
+  const filePath = controlFilePath(root);
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+function saveControl(root, control) {
+  control.meta = control.meta || {};
+  control.meta.updatedAt = new Date().toISOString();
+  const filePath = controlFilePath(root);
+  fs.writeFileSync(filePath, JSON.stringify(control, null, 2) + "\n", "utf8");
+}
+
+module.exports = {
+  DEFAULT_PHASES,
+  DEFAULT_LOCALE,
+  resolveProjectRoot,
+  controlFilePath,
+  runtimeFilePath,
+  docFilePaths,
+  getPhases,
+  getLocale,
+  isOperaInstalled,
+  getOperaVersion,
+  isEtapaInstalled,
+  getEtapaVersion,
+  loadControl,
+  saveControl,
+};