trackops 2.0.4 → 2.0.6

package/templates/skills/opera-skill/references/phase-dod.md

@@ -0,0 +1,138 @@
+# Definition of Done por Fase
+
+> Referencia usada por la opera-skill para decidir si una fase puede cerrarse.
+> Cargala solo cuando se pida cerrar fase, se dude del readiness o haya que justificar por que no se puede avanzar.
+
+---
+
+## O — Orquestar
+
+### Objetivo de salida
+Base operativa clara: problema definido, usuario identificado, contrato coherente.
+
+### Criterios obligatorios
+- [ ] Problema principal definido
+- [ ] Usuario objetivo definido
+- [ ] Resultado singular deseado definido y verificable
+- [ ] Fuente de verdad definida
+- [ ] Las 5 preguntas de descubrimiento respondidas (directriz, integraciones, fuente de verdad, payload, reglas)
+- [ ] Preferencias de repositorio y control de versiones preguntadas y registradas
+- [ ] Preferencias de entorno y despliegue preguntadas y registradas
+- [ ] Esquema JSON de Input/Output definido en `genesis.md` (al menos provisional)
+- [ ] Reglas de comportamiento documentadas
+- [ ] `ops/bootstrap/intake.json` completo con campos minimos (incluye `versionControl` y `deployment`)
+- [ ] `ops/bootstrap/spec-dossier.md` escrito con todas las secciones
+- [ ] `ops/contract/operating-contract.json` compilado
+- [ ] `opera-contract-auditor` ejecutado sin contradicciones criticas
+- [ ] `ops/bootstrap/open-questions.md` actualizado si quedan huecos
+- [ ] `task_plan.md` aprobado por el usuario
+
+### Bloqueadores
+- bootstrap en estado `awaiting_agent` o `needs_review`
+- contradicciones criticas detectadas por el auditor
+- campos obligatorios vacios en intake.json
+
+### Senal de delegacion
+- Si falta intake.json o spec-dossier.md → delega a `project-starter-skill`
+- Si hay contradicciones en contrato → delega a `opera-contract-auditor`
+
+---
+
+## P — Probar
+
+### Objetivo de salida
+Entorno verificado, conectividad confirmada, viabilidad tecnica real.
+
+### Criterios obligatorios
+- [ ] Todas las credenciales en `.env` verificadas (existen y no estan vacias)
+- [ ] Entorno de ejecucion revisado y funcional
+- [ ] Conectividad critica confirmada (APIs, servicios externos)
+- [ ] Shapes de respuesta validados contra schema de `genesis.md`
+- [ ] Resultados documentados en `findings.md`
+- [ ] Si algun test falla, la tarea esta marcada como bloqueada con razon documentada
+- [ ] Ningun finding abierto con severity `critical`
+
+### Bloqueadores
+- credenciales ausentes o invalidas
+- servicio externo critico no responde
+- shape de respuesta no coincide con schema
+
+### Senal de delegacion
+- Si hay riesgo al probar sistemas externos → consulta `opera-policy-guard`
+- Si aparecen contradicciones entre pruebas y contrato → delega a `opera-contract-auditor`
+
+---
+
+## E — Estructurar
+
+### Objetivo de salida
+Trabajo implementado, trazado y alineado con contrato y backlog.
+
+### Criterios obligatorios
+- [ ] Tareas relevantes iniciadas y cerradas con TrackOps
+- [ ] Codigo o configuracion implementados y alineados con el contrato
+- [ ] SOPs escritos en `architecture/` cuando la complejidad lo requiera
+- [ ] Grafo de dependencias documentado en `genesis.md` si hay pipeline
+- [ ] Herramientas con side-effects marcadas con META tags (`idempotent`, `side-effect`, `requires-confirmation`)
+- [ ] Commits siguiendo convencion (skill `commiter` activada)
+- [ ] `CHANGELOG.md` actualizado si el flujo del repo lo requiere (skill `changelog-updater`)
+- [ ] Cambios operativos sincronizados con `trackops sync`
+
+### Bloqueadores
+- tareas de implementacion sin iniciar en trackops
+- codigo que contradice el contrato sin justificacion
+- cambios sin commit
+
+### Senal de delegacion
+- Al hacer commit → delega a `commiter`
+- Post-commit → delega a `changelog-updater`
+
+---
+
+## R — Refinar
+
+### Objetivo de salida
+Outputs alineados con contrato, calidad verificada, contradicciones cerradas.
+
+### Criterios obligatorios
+- [ ] Revision de coherencia completada
+- [ ] Salidas validadas contra templates en `templates/` si existen
+- [ ] Formatos de entrega (Markdown, HTML, JSON) verificados
+- [ ] Si hay interfaz: revision visual completada
+- [ ] `opera-contract-auditor` ejecutado sin contradicciones criticas
+- [ ] `opera-policy-guard` consultado para acciones de riesgo
+- [ ] Ningun finding abierto con severity `critical` o `high`
+- [ ] Findings resueltos o explicitamente aceptados por el usuario
+
+### Bloqueadores
+- contradicciones materiales abiertas entre outputs y contrato
+- acciones rojas/amarillas sin resolver
+- findings criticos abiertos
+
+### Senal de delegacion
+- Para validar contrato → delega a `opera-contract-auditor`
+- Para acciones de riesgo → delega a `opera-policy-guard`
+
+---
+
+## A — Automatizar
+
+### Objetivo de salida
+Automatizacion o release listos, entorno verificado, deuda temporal resuelta.
+
+### Criterios obligatorios
+- [ ] `.tmp/` limpio (sin archivos residuales relevantes)
+- [ ] Codigo desplegado o preparado para despliegue segun `intake.json.deployment`
+- [ ] Triggers configurados y verificados (cron, webhooks) si aplica
+- [ ] Smoke test superado en destino
+- [ ] `progress.md` actualizado con estado final
+- [ ] `trackops sync` ejecutado
+- [ ] Si `versionControl.remote` es true: cambios pusheados al remoto
+
+### Bloqueadores
+- automatizacion que rompe politica o entorno
+- smoke test fallando
+- deuda temporal que impide release limpio
+
+### Senal de delegacion
+- Para acciones de deploy → consulta `opera-policy-guard`

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

@@ -1,131 +1,150 @@
----
-name: "project-starter-skill"
-description: "Skill para discovery y estructuracion inicial de proyectos con TrackOps y OPERA. Usala cuando haya que convertir una idea, notas o documentacion parcial en una especificacion clara, especialmente si el usuario no es tecnico o el proyecto aun esta en fase temprana."
-metadata:
-  version: "4.0"
-  type: "global"
-  triggers:
-    - "nuevo proyecto"
-    - "iniciar proyecto"
-    - "project starter"
-    - "scaffold"
-    - "idea de proyecto"
-    - "spec dossier"
----
-
-# Project Starter Skill
-
-Tu trabajo es convertir una idea o una documentacion parcial en un proyecto estructurado y explicable.
-
-## Regla principal
-
-Empieza siempre por la persona, no por la arquitectura.
-
-- identifica el nivel tecnico del usuario
-- adapta el lenguaje y la profundidad a ese nivel
-- si ya existe documentacion, leela y consolidala
-- si no existe documentacion, construye la primera especificacion util desde la idea
-
-## Cuando TrackOps ya esta instalado
-
-Si el repo ya contiene TrackOps u OPERA:
-
-- no ejecutes `trackops init`
-- no recrees `app/`, `ops/` ni el resto del workspace
-- usa `ops/contract/operating-contract.json` como fuente de verdad de maquina si ya existe
-- usa `ops/genesis.md` como vista humana compilada
-- usa `ops/project_control.json` para backlog y estado operativo
-- trabaja sobre `ops/bootstrap/agent-handoff.md`
-- escribe:
-  - `ops/bootstrap/intake.json`
-  - `ops/bootstrap/spec-dossier.md`
-  - `ops/bootstrap/open-questions.md` si quedan vacios importantes
-
-## Lo que debe producir la skill
-
-`ops/bootstrap/intake.json` debe dejar, como minimo:
-
-- `technicalLevel`
-- `projectState`
-- `documentationState`
-- `decisionOwnership`
-- `problemStatement`
-- `targetUser`
-- `singularDesiredOutcome`
-- `userLanguage`
-- `needsPlainLanguage`
-- `recommendedStack`
-- `externalServices`
-- `sourceOfTruth`
-- `payload`
-- `behaviorRules`
-- `architecturalInvariants`
-- `inputSchema`
-- `outputSchema`
-- `pipeline`
-- `templates`
-
-`ops/bootstrap/spec-dossier.md` debe explicar:
-
-- `## Problem statement`
-- `## Target user`
-- `## Singular desired outcome`
-- `## Delivery target`
-- `## Source of truth`
-- flujo funcional principal
-- stack recomendado o stack heredado
-- integraciones externas
-- restricciones relevantes
-
-`ops/bootstrap/open-questions.md` debe listar:
-
-- preguntas que siguen abiertas
-- contradicciones entre idea, repo y documentacion
-- decisiones que TrackOps u OPERA no deben inventar
-
-## Calidad minima antes de entregar
-
-No des por cerrado el discovery si falta alguno de estos campos:
-
-- problema principal
-- usuario objetivo
-- resultado singular deseado
-- objetivo de entrega
-- fuente de verdad
-- schema de entrada y salida, aunque sea provisional
-
-Si algo sigue incierto, dejalo en `open-questions.md` en lugar de inventarlo.
-
-## Si TrackOps aun no esta instalado
-
-No improvises una estructura propia.
-
-Explica el flujo correcto:
-
-```bash
-npx skills add Baxahaun/trackops
-npm install -g trackops
-trackops init
-trackops opera install
-```
-
-Si el usuario solo tiene una idea, deja claro que TrackOps puede derivar el bootstrap a una conversacion guiada con el agente.
-- flujo funcional principal
-- decisiones de stack, si ya existen o si hay que proponerlas
-- integraciones externas
-- restricciones relevantes
-
-## Si TrackOps aun no esta instalado
-
-No improvises una estructura propia.
-
-Explica el flujo correcto:
-
-```bash
-npx skills add Baxahaun/trackops
-npm install -g trackops
-trackops init
-trackops opera install
-```
-
-Si el usuario solo tiene una idea, deja claro que TrackOps puede derivar el bootstrap a una conversacion guiada con el agente.
+---
+name: "project-starter-skill"
+description: "Skill para discovery y estructuracion inicial de proyectos con TrackOps y OPERA. Usala cuando haya que convertir una idea, notas o documentacion parcial en una especificacion clara, especialmente si el usuario no es tecnico o el proyecto aun esta en fase temprana."
+metadata:
+  version: "5.0"
+  type: "global"
+  triggers:
+    - "nuevo proyecto"
+    - "iniciar proyecto"
+    - "project starter"
+    - "scaffold"
+    - "idea de proyecto"
+    - "spec dossier"
+---
+
+# Project Starter Skill
+
+Tu trabajo es convertir una idea o una documentacion parcial en un proyecto estructurado y explicable.
+
+> **IMPORTANTE**: El framework se llama **OPERA** (Orquestar, Probar, Estructurar, Refinar, Automatizar). NUNCA uses "ETAPA", "E.T.A.P.A." ni ningun otro nombre alternativo. El nombre correcto y unico es **OPERA**.
+
+## Regla principal
+
+Empieza siempre por la persona, no por la arquitectura.
+
+- identifica el nivel tecnico del usuario
+- adapta el lenguaje y la profundidad a ese nivel
+- si ya existe documentacion, leela y consolidala
+- si no existe documentacion, construye la primera especificacion util desde la idea
+
+## No asumas — pregunta
+
+Antes de tomar decisiones de infraestructura, repositorio, licencia o stack, **pregunta al usuario**. No des nada por sentado.
+
+### Preguntas de repositorio y control de versiones
+
+Estas preguntas son obligatorias durante el descubrimiento:
+
+1. **Repositorio remoto**: ¿Quieres un repositorio remoto? (si/no)
+2. **Plataforma**: Si si, ¿cual? (GitHub / GitLab / Bitbucket / otro — especificar)
+3. **Repositorio existente**: ¿Ya existe el repositorio o hay que crearlo?
+4. **Visibilidad**: ¿Publico o privado?
+5. **Licencia**: ¿Que licencia de software? (MIT / Apache 2.0 / GPL / propietaria / otra — o "no se, recomiendame")
+6. **Organizacion**: ¿Bajo que usuario u organizacion?
+
+### Preguntas de entorno y despliegue
+
+Complementarias al repositorio:
+
+7. **Entorno de ejecucion**: ¿Donde se ejecutara? (local / servidor / cloud / edge / no se aun)
+8. **CI/CD**: ¿Necesitas integracion continua o despliegue automatico? (si/no/no se)
+9. **Dominio/URL**: ¿Tienes dominio o URL de destino?
+
+Si el usuario no sabe o no tiene preferencia, puedes recomendar, pero **marca la recomendacion como tal** y pide confirmacion antes de proceder. Nunca crees repositorios, licencias ni estructura sin aprobacion explicita.
+
+## Cuando TrackOps ya esta instalado
+
+Si el repo ya contiene TrackOps u OPERA:
+
+- no ejecutes `trackops init`
+- no recrees `app/`, `ops/` ni el resto del workspace
+- usa `ops/contract/operating-contract.json` como fuente de verdad de maquina si ya existe
+- usa `ops/genesis.md` como vista humana compilada
+- usa `ops/project_control.json` para backlog y estado operativo
+- trabaja sobre `ops/bootstrap/agent-handoff.md`
+- escribe:
+  - `ops/bootstrap/intake.json`
+  - `ops/bootstrap/spec-dossier.md`
+  - `ops/bootstrap/open-questions.md` si quedan vacios importantes
+
+## Lo que debe producir la skill
+
+`ops/bootstrap/intake.json` debe dejar, como minimo:
+
+- `technicalLevel`
+- `projectState`
+- `documentationState`
+- `decisionOwnership`
+- `problemStatement`
+- `targetUser`
+- `singularDesiredOutcome`
+- `userLanguage`
+- `needsPlainLanguage`
+- `recommendedStack`
+- `externalServices`
+- `sourceOfTruth`
+- `payload`
+- `behaviorRules`
+- `architecturalInvariants`
+- `inputSchema`
+- `outputSchema`
+- `pipeline`
+- `templates`
+- `versionControl` — objeto con las decisiones de repositorio:
+  - `remote` (boolean)
+  - `platform` (github/gitlab/bitbucket/other/none)
+  - `repoExists` (boolean)
+  - `visibility` (public/private)
+  - `license` (MIT/Apache-2.0/GPL-3.0/proprietary/other)
+  - `org` (usuario u organizacion)
+- `deployment` — objeto con las decisiones de entorno:
+  - `target` (local/server/cloud/edge/undecided)
+  - `cicd` (boolean o null si no decidido)
+  - `domain` (string o null)
+
+`ops/bootstrap/spec-dossier.md` debe explicar:
+
+- `## Problem statement`
+- `## Target user`
+- `## Singular desired outcome`
+- `## Delivery target`
+- `## Source of truth`
+- flujo funcional principal
+- stack recomendado o stack heredado
+- integraciones externas
+- restricciones relevantes
+
+`ops/bootstrap/open-questions.md` debe listar:
+
+- preguntas que siguen abiertas
+- contradicciones entre idea, repo y documentacion
+- decisiones que TrackOps u OPERA no deben inventar
+
+## Calidad minima antes de entregar
+
+No des por cerrado el discovery si falta alguno de estos campos:
+
+- problema principal
+- usuario objetivo
+- resultado singular deseado
+- objetivo de entrega
+- fuente de verdad
+- schema de entrada y salida, aunque sea provisional
+- preferencias de repositorio y control de versiones
+
+Si algo sigue incierto, dejalo en `open-questions.md` en lugar de inventarlo.
+
+## Si TrackOps aun no esta instalado
+
+No improvises una estructura propia.
+
+Explica el flujo correcto:
+
+```bash
+npx skills add Baxahaun/trackops
+trackops init
+trackops opera install
+```
+
+Si el usuario solo tiene una idea, deja claro que TrackOps puede derivar el bootstrap a una conversacion guiada con el agente.