trackops 2.0.4 → 2.0.5

package/templates/skills/project-starter-skill/locales/en/SKILL.md

@@ -1,105 +1,143 @@
----
-name: "project-starter-skill"
-description: "Skill for discovery and early project structuring with TrackOps and OPERA. Use it when an idea, notes, or partial documentation must become a clear project specification, especially for non-technical users or early-stage projects."
-metadata:
-  version: "4.0"
-  type: "global"
----
-
-# Project Starter Skill
-
-Your job is to turn an idea or partial documentation into a structured, explainable project.
-
-## Core rule
-
-Start from the person, not from the architecture.
-
-- identify the user's technical level
-- adapt language and depth to that level
-- if documentation exists, read it and consolidate it
-- if documentation does not exist, build the first useful specification from the idea
-
-## When TrackOps is already installed
-
-If the repository already contains TrackOps or OPERA:
-
-- do not run `trackops init`
-- do not recreate `app/`, `ops/`, or the workspace
-- use `ops/contract/operating-contract.json` as the machine source of truth when it already exists
-- use `ops/genesis.md` as the compiled human view
-- use `ops/project_control.json` for backlog and operational state
-- work from `ops/bootstrap/agent-handoff.md`
-- write:
-  - `ops/bootstrap/intake.json`
-  - `ops/bootstrap/spec-dossier.md`
-  - `ops/bootstrap/open-questions.md` when important gaps remain
-
-## What the skill must produce
-
-`ops/bootstrap/intake.json` must include at least:
-
-- `technicalLevel`
-- `projectState`
-- `documentationState`
-- `decisionOwnership`
-- `problemStatement`
-- `targetUser`
-- `singularDesiredOutcome`
-- `userLanguage`
-- `needsPlainLanguage`
-- `recommendedStack`
-- `externalServices`
-- `sourceOfTruth`
-- `payload`
-- `behaviorRules`
-- `architecturalInvariants`
-- `inputSchema`
-- `outputSchema`
-- `pipeline`
-- `templates`
-
-`ops/bootstrap/spec-dossier.md` must explain:
-
-- `## Problem statement`
-- `## Target user`
-- `## Singular desired outcome`
-- `## Delivery target`
-- `## Source of truth`
-- the main functional flow
-- recommended or inherited stack
-- external integrations
-- relevant constraints
-
-`ops/bootstrap/open-questions.md` must list:
-
-- questions still open
-- contradictions between the idea, the repository, and the documents
-- decisions that TrackOps or OPERA must not invent
-
-## Minimum quality bar before handing off
-
-Do not treat discovery as complete if any of these are missing:
-
-- problem statement
-- target user
-- singular desired outcome
-- delivery target
-- source of truth
-- input and output schema, even if still provisional
-
-If something is still uncertain, write it to `open-questions.md` instead of inventing it.
-
-## If TrackOps is not installed yet
-
-Do not invent your own structure.
-
-Explain the correct flow:
-
-```bash
-npx skills add Baxahaun/trackops
-npm install -g trackops
-trackops init
-trackops opera install
-```
-
-If the user only has an idea, make it explicit that TrackOps can route bootstrap into an agent-led discovery conversation.
+---
+name: "project-starter-skill"
+description: "Skill for discovery and early project structuring with TrackOps and OPERA. Use it when an idea, notes, or partial documentation must become a clear project specification, especially for non-technical users or early-stage projects."
+metadata:
+  version: "5.0"
+  type: "global"
+---
+
+# Project Starter Skill
+
+Your job is to turn an idea or partial documentation into a structured, explainable project.
+
+> **IMPORTANT**: The framework is called **OPERA** (Orchestrate, Prove, Establish, Refine, Automate). NEVER use "ETAPA", "E.T.A.P.A.", or any other alternative name. The correct and only name is **OPERA**.
+
+## Core rule
+
+Start from the person, not from the architecture.
+
+- identify the user's technical level
+- adapt language and depth to that level
+- if documentation exists, read it and consolidate it
+- if documentation does not exist, build the first useful specification from the idea
+
+## Do not assume — ask
+
+Before making decisions about infrastructure, repositories, licenses, or stack, **ask the user**. Do not take anything for granted.
+
+### Repository and version control questions
+
+These questions are mandatory during discovery:
+
+1. **Remote repository**: Do you want a remote repository? (yes/no)
+2. **Platform**: If yes, which? (GitHub / GitLab / Bitbucket / other — specify)
+3. **Existing repository**: Does the repository already exist, or should it be created?
+4. **Visibility**: Public or private?
+5. **License**: What software license? (MIT / Apache 2.0 / GPL / proprietary / other — or "I don't know, recommend one")
+6. **Organization**: Under which user or organization?
+
+### Environment and deployment questions
+
+Complementary to the repository:
+
+7. **Runtime environment**: Where will it run? (local / server / cloud / edge / not sure yet)
+8. **CI/CD**: Do you need continuous integration or automatic deployment? (yes/no/not sure)
+9. **Domain/URL**: Do you have a domain or target URL?
+
+If the user doesn't know or has no preference, you may recommend, but **mark the recommendation as such** and ask for confirmation before proceeding. Never create repositories, licenses, or structure without explicit approval.
+
+## When TrackOps is already installed
+
+If the repository already contains TrackOps or OPERA:
+
+- do not run `trackops init`
+- do not recreate `app/`, `ops/`, or the workspace
+- use `ops/contract/operating-contract.json` as the machine source of truth when it already exists
+- use `ops/genesis.md` as the compiled human view
+- use `ops/project_control.json` for backlog and operational state
+- work from `ops/bootstrap/agent-handoff.md`
+- write:
+  - `ops/bootstrap/intake.json`
+  - `ops/bootstrap/spec-dossier.md`
+  - `ops/bootstrap/open-questions.md` when important gaps remain
+
+## What the skill must produce
+
+`ops/bootstrap/intake.json` must include at least:
+
+- `technicalLevel`
+- `projectState`
+- `documentationState`
+- `decisionOwnership`
+- `problemStatement`
+- `targetUser`
+- `singularDesiredOutcome`
+- `userLanguage`
+- `needsPlainLanguage`
+- `recommendedStack`
+- `externalServices`
+- `sourceOfTruth`
+- `payload`
+- `behaviorRules`
+- `architecturalInvariants`
+- `inputSchema`
+- `outputSchema`
+- `pipeline`
+- `templates`
+- `versionControl` — object with repository decisions:
+  - `remote` (boolean)
+  - `platform` (github/gitlab/bitbucket/other/none)
+  - `repoExists` (boolean)
+  - `visibility` (public/private)
+  - `license` (MIT/Apache-2.0/GPL-3.0/proprietary/other)
+  - `org` (user or organization)
+- `deployment` — object with environment decisions:
+  - `target` (local/server/cloud/edge/undecided)
+  - `cicd` (boolean or null if undecided)
+  - `domain` (string or null)
+
+`ops/bootstrap/spec-dossier.md` must explain:
+
+- `## Problem statement`
+- `## Target user`
+- `## Singular desired outcome`
+- `## Delivery target`
+- `## Source of truth`
+- the main functional flow
+- recommended or inherited stack
+- external integrations
+- relevant constraints
+
+`ops/bootstrap/open-questions.md` must list:
+
+- questions still open
+- contradictions between the idea, the repository, and the documents
+- decisions that TrackOps or OPERA must not invent
+
+## Minimum quality bar before handing off
+
+Do not treat discovery as complete if any of these are missing:
+
+- problem statement
+- target user
+- singular desired outcome
+- delivery target
+- source of truth
+- input and output schema, even if still provisional
+- repository and version control preferences
+
+If something is still uncertain, write it to `open-questions.md` instead of inventing it.
+
+## If TrackOps is not installed yet
+
+Do not invent your own structure.
+
+Explain the correct flow:
+
+```bash
+npx skills add Baxahaun/trackops
+trackops init
+trackops opera install
+```
+
+If the user only has an idea, make it explicit that TrackOps can route bootstrap into an agent-led discovery conversation.

package/templates/skills/project-starter-skill/references/opera-cycle.md

@@ -1,193 +1,195 @@
-# El Ciclo O.P.E.R.A. — Referencia Completa
-
-Este documento detalla cada fase del ciclo con sus reglas, procedimientos y Definitions of Done.
-
----
-
-## 1️⃣ O — Orquestar (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 O
-
-- [ ] 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️⃣ P — Probar (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 Estructurar. 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 P
-
-- [ ] 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️⃣ E — Estructurar (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 E
-
-- [ ] 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️⃣ R — Refinar (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 refinamiento 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 R
-
-- [ ] 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 — Automatizar (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
-
-- [ ] `.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.
+# El Ciclo O.P.E.R.A. — Referencia Completa
+
+> **IMPORTANTE**: El framework se llama **OPERA** (Orquestar, Probar, Estructurar, Refinar, Automatizar). NO uses "ETAPA", "E.T.A.P.A." ni ningún otro nombre alternativo. El nombre correcto y único es **OPERA**.
+
+Este documento detalla cada fase del ciclo con sus reglas, procedimientos y Definitions of Done.
+
+---
+
+## 1️⃣ O — Orquestar (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 O
+
+- [ ] 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️⃣ P — Probar (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 Estructurar. 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 P
+
+- [ ] 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️⃣ E — Estructurar (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 E
+
+- [ ] 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️⃣ R — Refinar (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 refinamiento 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 R
+
+- [ ] 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 — Automatizar (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
+
+- [ ] `.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.