trackops 1.0.0

package/templates/etapa/references/etapa-cycle.md

@@ -0,0 +1,193 @@
+# El Ciclo E.T.A.P.A. — Referencia Completa
+
+Este documento detalla cada fase del ciclo con sus reglas, procedimientos y Definitions of Done.
+
+---
+
+## 1️⃣ E — Estrategia (Visión y Lógica)
+
+### Descubrimiento
+
+Haz al usuario las 5 preguntas clave:
+
+1. **Directriz Principal**: ¿Cuál es el resultado singular deseado?
+2. **Integraciones**: ¿Qué servicios externos necesitamos? ¿Están listas las claves?
+3. **Fuente de la Verdad**: ¿Dónde viven los datos primarios?
+4. **Carga Útil (Payload)**: ¿Cómo y dónde debe entregarse el resultado final?
+5. **Reglas de Comportamiento**: Restricciones o tono específico.
+
+### Regla "Datos-Primero"
+
+Antes de pasar a la siguiente fase, DEBES definir el **Esquema de Datos JSON** (Input/Output) en `genesis.md`.
+
+Ejemplo de schema en genesis.md:
+
+```json
+{
+  "input": {
+    "source": "API externa",
+    "schema": {
+      "id": "string (UUID)",
+      "timestamp": "ISO 8601",
+      "data": "object"
+    }
+  },
+  "output": {
+    "destination": "webhook POST",
+    "schema": {
+      "processed_id": "string (UUID)",
+      "result": "object",
+      "status": "enum: success|error"
+    }
+  }
+}
+```
+
+### Definition of Done — Fase E
+
+- [ ] Las 5 preguntas de descubrimiento están respondidas.
+- [ ] Esquema JSON de Input/Output definido en `genesis.md`.
+- [ ] Reglas de comportamiento documentadas en `genesis.md`.
+- [ ] `task_plan.md` tiene plano aprobado por el usuario.
+
+---
+
+## 2️⃣ T — Tests (Conectividad)
+
+Verifica las tuberías antes de pasar el agua. El objetivo es confirmar que todos los servicios externos responden y devuelven datos con la forma esperada.
+
+### Procedimiento
+
+1. **Verificación de credenciales**: Lee `.env` y confirma que todas las claves necesarias existen y no están vacías.
+2. **Handshake**: Construye scripts mínimos en `tools/` (ej: `test_api.py`) para verificar cada servicio.
+3. **Validación de Shape**: No basta con un HTTP 200. Verifica que la respuesta coincide con el schema definido en `genesis.md`. Compara campos, tipos de datos y estructura.
+4. **Bloqueo**: Si algún test falla, NO procedas a la fase de Arquitectura. Documenta el fallo en `findings.md`.
+
+### Ejemplo de test mínimo
+
+```python
+# tools/test_api.py
+import os
+import requests
+
+API_KEY = os.getenv("API_KEY")
+BASE_URL = os.getenv("API_BASE_URL")
+
+def test_connection():
+    """Verifica conexión y shape de respuesta."""
+    response = requests.get(f"{BASE_URL}/health", headers={"Authorization": f"Bearer {API_KEY}"})
+    assert response.status_code == 200, f"Expected 200, got {response.status_code}"
+    data = response.json()
+    assert "id" in data, "Missing 'id' field in response"
+    assert "status" in data, "Missing 'status' field in response"
+    print("✅ API connection and shape validated")
+
+if __name__ == "__main__":
+    test_connection()
+```
+
+### Definition of Done — Fase T
+
+- [ ] Todas las credenciales `.env` verificadas (existen y no están vacías).
+- [ ] Scripts `test_*.py` ejecutados y pasando.
+- [ ] Respuestas de APIs validadas contra el schema de `genesis.md`.
+- [ ] Resultados documentados en `findings.md`.
+
+---
+
+## 3️⃣ A — Arquitectura (La Construcción de 3 Capas)
+
+### Capa 1: Arquitectura (`architecture/`)
+
+SOPs (Standard Operating Procedures) técnicos en Markdown. Cada SOP define:
+
+- Propósito del script.
+- Entradas esperadas (con referencia al schema en `genesis.md`).
+- Salidas producidas.
+- Casos extremos y cómo manejarlos.
+- Dependencias con otras herramientas.
+
+**Regla**: Si la lógica cambia, actualiza el SOP **antes** que el código.
+
+### Capa 2: Navegación (El Agente)
+
+Capa de razonamiento. Enruta datos entre SOPs y herramientas. No ejecuta lógica de negocio directamente; delega a los scripts.
+
+### Capa 3: Herramientas (`tools/`)
+
+- Scripts atómicos y deterministas.
+- Las variables de entorno van en `.env`.
+- Usa `.tmp/` para todas las operaciones intermedias.
+- Cada script hace UNA cosa bien.
+
+### Regla de Idempotencia
+
+Toda herramienta DEBE ser idempotente. Herramientas con side-effects irreversibles se marcan:
+
+```python
+# META: side-effect: true
+# META: idempotent: false
+# META: requires-confirmation: true
+```
+
+### Grafo de Dependencias
+
+Si una herramienta produce output que consume otra, documéntalo en `genesis.md` bajo `## Pipeline`:
+
+```markdown
+## Pipeline
+### tool_fetch.py → tool_transform.py
+- Output: `.tmp/raw_data.json`
+- Formato: JSON array según schema X
+```
+
+### Definition of Done — Fase A
+
+- [ ] SOPs escritos en `architecture/` para cada herramienta.
+- [ ] Scripts implementados en `tools/`.
+- [ ] Grafo de dependencias documentado en `genesis.md`.
+- [ ] Tests de integración entre herramientas pasando.
+- [ ] Herramientas con side-effects marcadas con META tags.
+
+---
+
+## 4️⃣ P — Pulido (Refinamiento)
+
+### Templates de Output
+
+Toda salida del sistema se valida contra una plantilla definida en `templates/`. Las plantillas se referencian desde `genesis.md` bajo `## Templates`.
+
+El pulido no es subjetivo; es verificable contra una plantilla. Si el output no coincide con el template, no pasa.
+
+### Refinamiento de Carga Útil
+
+Formatea todas las salidas (Markdown, HTML, JSON limpio) para entrega profesional según lo definido en `genesis.md`.
+
+### UX/UI
+
+Si el proyecto tiene interfaz, aplica diseños limpios e intuitivos según las especificaciones.
+
+### Definition of Done — Fase P
+
+- [ ] Todas las salidas validadas contra sus templates en `templates/`.
+- [ ] Formatos de entrega (Markdown, HTML, JSON) verificados.
+- [ ] Si hay interfaz: revisión visual completada.
+
+---
+
+## 5️⃣ A — Automatización (Despliegue)
+
+### Procedimiento
+
+1. **Limpieza**: Elimina residuos de `.tmp/`.
+2. **Transferencia**: Mueve la lógica finalizada a producción/nube.
+3. **Configuración**: Establece los disparadores (Cron, Webhooks).
+4. **Smoke Test**: Verificación mínima en el entorno de producción.
+
+### Definition of Done — Fase A (final)
+
+- [ ] `.tmp/` limpio (sin archivos residuales).
+- [ ] Código desplegado en destino final.
+- [ ] Triggers configurados y verificados.
+- [ ] Smoke test en producción pasando.
+- [ ] `progress.md` actualizado con estado final.

package/templates/etapa/registry.md

@@ -0,0 +1,28 @@
+# Skills Registry — {{PROJECT_NAME}}
+
+> Índice de skills instaladas en este proyecto. Gestionado automáticamente por `trackops skill`.
+
+---
+
+## Skills Instaladas
+
+_Sin skills instaladas. Usa `trackops skill install <nombre>` para añadir una._
+
+---
+
+## Cómo Usar una Skill
+
+1. Identifica el contexto en `.agent/hub/router.md`.
+2. Abre el archivo `SKILL.md` de la skill correspondiente.
+3. Sigue las instrucciones del protocolo definido en la skill.
+
+---
+
+## Gestión
+
+```bash
+trackops skill list          # Ver skills instaladas
+trackops skill catalog       # Ver skills disponibles
+trackops skill install <n>   # Instalar una skill
+trackops skill remove <n>    # Desinstalar una skill
+```

package/templates/etapa/router.md

@@ -0,0 +1,39 @@
+# Router de Skills
+
+## Propósito
+Este archivo define las reglas de enrutamiento entre el agente principal y las skills disponibles. Cuando el agente detecta un contexto específico, consulta estas reglas para decidir qué skill invocar.
+
+## Reglas de Enrutamiento
+
+### Contexto: Commit de código
+- **Trigger**: El usuario pide hacer un commit o se completa un cambio de código.
+- **Skill**: `commiter`
+- **Acción**: Consulta la skill para formatear el mensaje de commit.
+
+### Contexto: Post-commit
+- **Trigger**: Se acaba de realizar un commit exitoso.
+- **Skill**: `changelog-updater`
+- **Acción**: Ejecuta el script de actualización del changelog.
+
+### Contexto: Inicialización de proyecto
+- **Trigger**: El usuario quiere crear un nuevo proyecto.
+- **Skill**: `project-starter-skill` (global)
+- **Acción**: Ejecutar el protocolo de inicialización completo.
+
+### Contexto: Seguimiento operativo
+- **Trigger**: Se va a empezar, retomar o cerrar un bloque de trabajo.
+- **Skill**: No aplica skill externa.
+- **Acción**: Ejecutar `trackops status`, tomar la siguiente tarea con `trackops next` y mantener `project_control.json` como fuente de verdad operativa.
+
+## Cómo Añadir Nuevas Reglas
+
+Cada regla sigue este formato:
+
+```markdown
+### Contexto: [descripción]
+- **Trigger**: [qué activa la regla]
+- **Skill**: [nombre de la skill]
+- **Acción**: [qué debe hacer el agente]
+```
+
+Al instalar una nueva skill con `trackops skill install <nombre>`, añade su regla de enrutamiento aquí.

package/templates/hooks/post-checkout

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx trackops refresh-repo --quiet >/dev/null 2>&1 || true

package/templates/hooks/post-commit

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx trackops refresh-repo --quiet >/dev/null 2>&1 || true

package/templates/hooks/post-merge

@@ -0,0 +1,2 @@
+#!/bin/sh
+npx trackops refresh-repo --quiet >/dev/null 2>&1 || true

package/templates/opera/agent.md

@@ -0,0 +1,26 @@
+# Agente del Proyecto: {{PROJECT_NAME}}
+
+## Identidad
+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`.
+
+## 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`.
+
+## Skills Disponibles
+Consulta `.agent/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.
+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.
+6. Al terminar, pasa la tarea a `review`, `complete` o `block` y ejecuta `trackops sync`.

package/templates/opera/genesis.md

@@ -0,0 +1,94 @@
+# {{PROJECT_NAME}} — Genesis
+
+> **La Constitución del proyecto.** Este documento es la fuente de verdad. Antes de tomar cualquier decisión arquitectónica o de implementación, consulta este archivo. Si un script contradice lo definido aquí, el script está mal.
+
+---
+
+## 1. Directriz Principal
+
+_¿Cuál es el resultado singular deseado de este proyecto?_
+
+> TODO: Definir el objetivo principal del proyecto.
+
+---
+
+## 2. Integraciones Externas
+
+_¿Qué servicios externos necesitamos? ¿Están listas las claves?_
+
+| Servicio | Estado | Clave / Config |
+|----------|--------|----------------|
+| —        | —      | —              |
+
+---
+
+## 3. Fuente de la Verdad
+
+_¿Dónde viven los datos primarios?_
+
+> TODO: Describir la fuente de datos principal.
+
+---
+
+## 4. Carga Útil (Payload)
+
+_¿Cómo y dónde debe entregarse el resultado final?_
+
+> TODO: Describir destino y formato de entrega.
+
+---
+
+## 5. Reglas de Comportamiento
+
+_Restricciones, tono y reglas específicas del dominio._
+
+> TODO: Definir restricciones de negocio.
+
+---
+
+## Esquema de Datos
+
+> **Regla "Datos-Primero"**: Este schema debe estar definido antes de escribir cualquier código.
+
+```json
+{
+  "input": {
+    "source": "",
+    "schema": {}
+  },
+  "output": {
+    "destination": "",
+    "schema": {}
+  }
+}
+```
+
+---
+
+## Invariantes Arquitectónicas
+
+_Decisiones técnicas inamovibles. Cambiarlas requiere aprobación explícita (Nivel Rojo)._
+
+- TODO: Listar invariantes.
+
+---
+
+## Pipeline
+
+_Documenta el grafo de dependencias entre herramientas._
+
+<!-- Ejemplo:
+### tool_fetch.py → tool_transform.py
+- Output: `.tmp/raw_data.json`
+- Formato: JSON array según schema X
+-->
+
+---
+
+## Templates
+
+_Referencias a las plantillas de output definidas en `templates/`._
+
+<!-- Ejemplo:
+- `templates/report.md` — Plantilla para reportes
+-->

package/templates/opera/references/autonomy-and-recovery.md

@@ -0,0 +1,117 @@
+# Gobernanza, Autonomía y Recuperación
+
+Este documento define los niveles de permiso, el protocolo de auto-reparación y el sistema de rollback para el proyecto.
+
+---
+
+## 🚦 Matriz de Autonomía (Semáforo)
+
+### 🔴 NIVEL ROJO — Detente y Pide Permiso
+
+Estas acciones requieren aprobación explícita del usuario antes de ejecutarse:
+
+- Modificar la estructura de datos o reglas en `genesis.md`.
+- Eliminar datos persistentes o archivos fuera de `.tmp/`.
+- Despliegue final a producción (Fase de Automatizar).
+- Envío de comunicaciones reales a terceros (emails, webhooks con side-effects).
+- Creación de repositorios o recursos en servicios externos (GitHub, cloud).
+- Modificar configuraciones de acceso o seguridad.
+
+### 🟡 NIVEL AMARILLO — Avanza con Precaución
+
+Estas acciones se pueden ejecutar pero requieren documentación inmediata:
+
+- Instalación de dependencias nuevas.
+- Modificaciones a la estructura de directorios.
+- Cambios en el pipeline documentado en `genesis.md`.
+
+### 🟢 NIVEL VERDE — Avanza con Confianza
+
+Estas acciones no requieren permiso:
+
+- Creación, edición y corrección de scripts en `tools/`.
+- Lectura de archivos y documentación.
+- Ejecución de pruebas (Tests).
+- Actualización de `progress.md`, `findings.md` y `task_plan.md`.
+- Instalación de skills del ecosistema.
+- Escritura y limpieza de archivos en `.tmp/`.
+- Auto-Reparación (con límite de reintentos).
+
+---
+
+## 🛠️ Principio de Auto-Templado (Self-Annealing)
+
+Cuando una herramienta falla o ocurre un error en Nivel Verde, sigue este protocolo:
+
+### Procedimiento
+
+1. **Analizar**: Lee el stack trace completo. No adivines la causa.
+2. **Parchear**: Arregla el script en `tools/`.
+3. **Probar**: Verifica que el arreglo funciona ejecutando el script.
+4. **Actualizar Memoria**: Documenta el aprendizaje en `findings.md` o en el SOP correspondiente en `architecture/` para que el error nunca se repita.
+
+### Límite de Reintentos
+
+**Máximo 3 intentos de auto-reparación por error.** Si al tercer intento el error persiste:
+
+1. **Escalar a Nivel Rojo** — Pide intervención humana.
+2. **Documentar el bloqueo** en `findings.md` con:
+
+```markdown
+## Bloqueo: [nombre del error]
+### Fecha: [YYYY-MM-DD]
+### Script: [tools/nombre.py]
+
+### Stack Trace
+[pegar stack trace completo]
+
+### Intentos de Reparación
+1. **Intento 1**: [qué se intentó] → [resultado]
+2. **Intento 2**: [qué se intentó] → [resultado]
+3. **Intento 3**: [qué se intentó] → [resultado]
+
+### Hipótesis del Problema Raíz
+[análisis de por qué crees que falla]
+
+### Acción Requerida
+[qué necesitas del usuario para desbloquear]
+```
+
+### Lo que NO es Auto-Templado
+
+- No es reintentar ciegamente el mismo comando esperando un resultado diferente.
+- No es ignorar el error y continuar.
+- No es cambiar el schema en `genesis.md` para que el error "desaparezca".
+
+---
+
+## 🔄 Protocolo de Rollback
+
+Si una fase posterior invalida una decisión de una fase anterior, NO modifiques `genesis.md` directamente.
+
+### Procedimiento
+
+1. **Documentar** en `CHANGELOG.md` qué cambio se necesita y por qué.
+2. **Solicitar aprobación** (Nivel Rojo).
+3. **Una vez aprobado**, actualizar `genesis.md` con nueva versión:
+
+```markdown
+## Versión 1.1 — [fecha]
+
+### Cambio
+- [descripción precisa del cambio]
+
+### Motivo
+- [por qué la versión anterior era incorrecta o insuficiente]
+
+### Impacto
+- [qué scripts/SOPs necesitan actualizarse como consecuencia]
+```
+
+4. **Propagar el cambio**: Actualizar todos los scripts y SOPs afectados.
+5. **Re-ejecutar tests**: Verificar que los cambios no rompen nada.
+6. **Actualizar `progress.md`** con el rollback documentado.
+
+### Regla de Oro
+
+El historial de decisiones nunca se borra. Cada versión de `genesis.md` queda registrada en `CHANGELOG.md`. Esto permite entender por qué se tomó una decisión y por qué se cambió, evitando ciclos de decisiones contradictorias.