trackops 1.0.1 → 2.0.0

package/templates/skills/opera-policy-guard/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: "opera-policy-guard"
+description: "Skill para interpretar la politica ejecutable de OPERA y decidir que acciones requieren aprobacion explicita."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Policy Guard
+
+Usa esta skill cuando vayas a ejecutar acciones con riesgo operativo, efectos externos o cambios destructivos.
+
+## Fuente principal
+
+- `ops/policy/autonomy.json`
+
+## Debes responder
+
+- si la accion es verde, amarilla o roja
+- si requiere aprobacion explicita
+- que efecto externo produce
+- que alternativa segura existe si no hay permiso
+
+## Regla
+
+Si la politica deja dudas, no asumas permiso. Marca la accion como bloqueada hasta aclararlo.

package/templates/skills/opera-policy-guard/locales/en/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: "opera-policy-guard"
+description: "Skill for interpreting the OPERA executable policy and deciding which actions require explicit approval."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Policy Guard
+
+Use this skill before actions with operational risk, external side effects, or destructive changes.
+
+## Primary source
+
+- `ops/policy/autonomy.json`
+
+## You must answer
+
+- whether the action is green, yellow, or red
+- whether it requires explicit approval
+- what external side effect it causes
+- what safe alternative exists if approval is missing
+
+## Rule
+
+If the policy is ambiguous, do not assume permission. Mark the action as blocked until it is clarified.

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

@@ -1,204 +1,129 @@
 ---
 name: "project-starter-skill"
-description: "Skill global para inicializar proyectos completos usando el protocolo O.P.E.R.A. (Orquestar, Probar, Estructurar, Refinar, Automatizar). Usa esta skill siempre que el usuario quiera crear un nuevo proyecto, inicializar una estructura de agente, configurar un repositorio, o arrancar cualquier automatización desde cero. También se activa cuando el usuario menciona 'nuevo proyecto', 'iniciar proyecto', 'configurar proyecto', 'opera', 'project starter', 'scaffold', o cualquier intención de comenzar algo nuevo que necesite estructura."
+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: "3.0"
+  version: "4.0"
   type: "global"
   triggers:
-    - "iniciar proyecto"
     - "nuevo proyecto"
-    - "configurar proyecto"
-    - "opera"
+    - "iniciar proyecto"
     - "project starter"
     - "scaffold"
-    - "inicializar"
----
-
-# 🚀 ProjectStarterSkill — O.P.E.R.A. v3.0
-
-## Identidad
-
-Eres el **Piloto del Sistema**. Tu misión es construir automatización determinista y autorreparable usando el protocolo O.P.E.R.A.
-
-## Filosofía
-
-- Fiabilidad sobre velocidad. Nunca adivines lógica de negocio.
-- Los LLMs son probabilísticos, pero tu código debe ser **determinista**.
-- Cada fase tiene un **Definition of Done** verificable. No avanzas sin cumplirlo.
-- `genesis.md` es la ley. Si un script la contradice, el script está mal.
-
+    - "idea de proyecto"
+    - "spec dossier"
 ---
 
-## Protocolo de Inicialización
-
-Este protocolo se ejecuta secuencialmente y sin excepciones al crear un nuevo proyecto.
-
-### Paso 1 — Descubrimiento
-
-Antes de crear cualquier archivo, haz al usuario estas preguntas:
-
-| # | Pregunta | Propósito |
-|---|----------|-----------|
-| 1 | ¿Cuál es el resultado singular deseado? | Directriz principal |
-| 2 | ¿Qué servicios externos necesitamos? ¿Están listas las claves? | Integraciones |
-| 3 | ¿Dónde viven los datos primarios? | Fuente de la verdad |
-| 4 | ¿Cómo y dónde debe entregarse el resultado final? | Carga útil |
-| 5 | ¿Restricciones, tono o reglas específicas? | Reglas de comportamiento |
-
-También pregunta:
-- ¿Repositorio **público o privado**?
-- ¿Tipo de **licencia**? (MIT, Apache 2.0, GPL v3, Propietario)
-
-### Paso 2 — Inicialización con Ops
-
-Ejecuta la inicialización del sistema operativo:
-
-```bash
-npx trackops init --with-opera
-```
+# Project Starter Skill
 
-Esto crea `project_control.json`, instala OPERA y registra el proyecto.
+Tu trabajo es convertir una idea o una documentacion parcial en un proyecto estructurado y explicable.
 
-### Paso 3 — Poblar genesis.md
+## Regla principal
 
-Con las respuestas del descubrimiento, completa `genesis.md` con:
+Empieza siempre por la persona, no por la arquitectura.
 
-1. **Esquema de Datos JSON** (Input/Output) — esto es obligatorio antes de escribir código.
-2. **Reglas de comportamiento** — restricciones de negocio.
-3. **Invariantes arquitectónicas** — decisiones técnicas inamovibles.
+- 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
 
-Esto es la regla "Datos-Primero": si el schema no está definido en `genesis.md`, no se escribe código.
+## Cuando TrackOps ya esta instalado
 
-### Paso 4 — Completar task_plan.md
+Si el repo ya contiene TrackOps u OPERA:
 
-Ejecuta `trackops sync` para regenerar `task_plan.md` y luego ajusta:
-- Fases y objetivos.
-- **Definition of Done** por cada fase (ver referencia `references/opera-cycle.md`).
-- Checklist verificable.
+- 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
 
-### Paso 5 — Skills Base
+## Lo que debe producir la skill
 
-1. Instala las skills obligatorias:
-   ```bash
-   trackops skill install commiter
-   trackops skill install changelog-updater
-   ```
-2. Analiza la definición del proyecto en `genesis.md`.
-3. Busca skills adicionales con `trackops skill catalog` y **recomienda** (no instales sin aprobación) las que apliquen.
+`ops/bootstrap/intake.json` debe dejar, como minimo:
 
-### Paso 6 — Repositorio
+- `technicalLevel`
+- `projectState`
+- `documentationState`
+- `decisionOwnership`
+- `problemStatement`
+- `targetUser`
+- `singularDesiredOutcome`
+- `userLanguage`
+- `needsPlainLanguage`
+- `recommendedStack`
+- `externalServices`
+- `sourceOfTruth`
+- `payload`
+- `behaviorRules`
+- `architecturalInvariants`
+- `inputSchema`
+- `outputSchema`
+- `pipeline`
+- `templates`
 
-1. Crea el repositorio en GitHub (público o privado según elección).
-2. Genera `README.md` con la descripción del proyecto basada en `genesis.md`.
-3. Crea `LICENSE` según la elección del usuario.
-4. Inicializa `CHANGELOG.md` con entrada de creación.
-5. Realiza el primer commit (usa la skill `commiter`).
+`ops/bootstrap/spec-dossier.md` debe explicar:
 
-### Paso 7 — Freno de Mano 🛑
+- `## Problem statement`
+- `## Target user`
+- `## Singular desired outcome`
+- `## Delivery target`
+- `## Source of truth`
+- flujo funcional principal
+- stack recomendado o stack heredado
+- integraciones externas
+- restricciones relevantes
 
-Tienes **prohibido** escribir scripts en `tools/` hasta que:
+`ops/bootstrap/open-questions.md` debe listar:
 
-- [ ] Las preguntas de descubrimiento estén respondidas.
-- [ ] El esquema de datos esté definido en `genesis.md`.
-- [ ] `task_plan.md` tenga un plano aprobado con Definition of Done.
-- [ ] La estructura `.agent/` y `.agents/` esté creada.
-- [ ] El repositorio esté inicializado.
+- preguntas que siguen abiertas
+- contradicciones entre idea, repo y documentacion
+- decisiones que TrackOps u OPERA no deben inventar
 
----
+## Calidad minima antes de entregar
 
-## El Ciclo O.P.E.R.A.
+No des por cerrado el discovery si falta alguno de estos campos:
 
-Una vez completada la inicialización, el proyecto avanza a través de las fases definidas. Para el detalle completo de cada fase, lee:
-```
-references/opera-cycle.md
-```
+- problema principal
+- usuario objetivo
+- resultado singular deseado
+- objetivo de entrega
+- fuente de verdad
+- schema de entrada y salida, aunque sea provisional
 
-### Resumen de Fases OPERA
+Si algo sigue incierto, dejalo en `open-questions.md` en lugar de inventarlo.
 
-| Fase | Nombre | Foco | Entregable clave |
-|------|--------|------|-------------------|
-| **O** | Orquestar | Visión y lógica | Schema JSON en `genesis.md` |
-| **P** | Probar | Conectividad | Scripts de test pasando |
-| **E** | Estructurar | Construcción en 3 capas | SOPs + tools + tests de integración |
-| **R** | Refinar | Refinamiento | Outputs validados contra templates |
-| **A** | Automatizar | Despliegue | Triggers configurados + smoke test |
+## Si TrackOps aun no esta instalado
 
-### La Arquitectura de 3 Capas
+No improvises una estructura propia.
 
-| Capa | Ubicación | Función |
-|------|-----------|---------|
-| Arquitectura | `architecture/` | SOPs técnicos en Markdown. Si la lógica cambia, actualiza el SOP **antes** que el código. |
-| Navegación | El Agente | Capa de razonamiento. Enruta datos entre SOPs y herramientas. |
-| Herramientas | `tools/` | Scripts atómicos y deterministas. Variables en `.env`. Temporales en `.tmp/`. |
+Explica el flujo correcto:
 
----
-
-## Gobernanza y Recuperación
-
-Para la matriz de autonomía (semáforo), el protocolo de auto-reparación y el sistema de rollback, lee:
-```
-references/autonomy-and-recovery.md
+```bash
+npx skills add Baxahaun/trackops
+trackops init
+trackops opera install
 ```
 
-### Resumen Rápido
-
-**🔴 NIVEL ROJO** (Pide permiso): Modificar `genesis.md`, eliminar datos persistentes, desplegar a producción, enviar comunicaciones externas, crear repos.
+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
 
-**🟢 NIVEL VERDE** (Avanza): Crear/editar scripts, leer archivos, ejecutar tests, actualizar logs, auto-reparar (máx. 3 intentos).
+## Si TrackOps aun no esta instalado
 
----
+No improvises una estructura propia.
 
-## Estructura de Archivos
+Explica el flujo correcto:
 
+```bash
+npx skills add Baxahaun/trackops
+trackops init
+trackops opera install
 ```
-proyecto/
-├── .agent/
-│   ├── hub/
-│   │   ├── agent.md              # Instrucciones del agente
-│   │   └── router.md             # Enrutamiento a skills
-│   └── hub/
-│       ├── agent.md              # Instrucciones del agente
-│       └── router.md             # Enrutamiento a skills
-├── .agents/
-│   └── skills/
-│       ├── _registry.md          # Índice de skills instaladas
-│       └── [skill-name]/
-│           └── SKILL.md          # Contenido de skills
-├── genesis.md                    # 📜 La Constitución
-├── task_plan.md                  # 🗺️ El Mapa (autogenerado)
-├── progress.md                   # 📓 El Diario (autogenerado)
-├── findings.md                   # 📖 La Biblioteca (autogenerado)
-├── CHANGELOG.md                  # 📋 El Historial
-├── architecture/                 # 📘 El Manual (SOPs)
-├── tools/                        # ⚙️ Los Motores
-├── templates/                    # 📐 Las Plantillas
-├── .tmp/                         # 🔧 El Taller
-├── .env                          # 🔑 Las Llaves
-├── project_control.json          # 🎛️ Control Operativo
-├── README.md
-├── LICENSE
-└── .gitignore
-```
-
----
 
-## Checklist de Inicialización
-
-```markdown
-- [ ] Preguntas de descubrimiento respondidas
-- [ ] trackops init ejecutado
-- [ ] genesis.md poblado con schema y reglas
-- [ ] task_plan.md con Definition of Done por fase
-- [ ] progress.md generado
-- [ ] findings.md generado
-- [ ] .agent/hub/agent.md configurado
-- [ ] .agent/hub/router.md configurado
-- [ ] .agents/skills/_registry.md creado
-- [ ] Skills base instaladas (commiter, changelog-updater)
-- [ ] Repositorio GitHub creado
-- [ ] README.md generado
-- [ ] LICENSE creada
-- [ ] CHANGELOG.md inicializado
-- [ ] .gitignore configurado
-- [ ] Primer commit realizado
-```
+Si el usuario solo tiene una idea, deja claro que TrackOps puede derivar el bootstrap a una conversacion guiada con el agente.

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

@@ -0,0 +1,104 @@
+---
+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
+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.