trackops 2.0.3 → 2.0.5

package/templates/skills/opera-skill/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: "opera-skill"
+description: "Skill local de OPERA para coordinar el trabajo dentro de un repositorio con OPERA activado. Usala cuando el usuario pregunte en que fase esta el proyecto, que hacer a continuacion, que comando TrackOps ejecutar, si se puede avanzar de fase, si hace falta delegar a otra skill, o si una accion debe bloquearse por bootstrap, contrato o riesgo."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Skill — Director Tecnico
+
+## Que es esta skill
+
+Coordinador operativo de OPERA dentro del repositorio. Esta skill dirige al agente principal: le dice en que fase y estado esta el proyecto, que comandos de TrackOps debe usar, cuando debe bloquear avance, y cuando debe delegar en skills especializadas.
+
+## Que no es esta skill
+
+- no implementa codigo
+- no instala el runtime ni crea la estructura del repo
+- no sustituye al agente implementador
+- no inventa contrato ni decisiones de negocio
+- no ejecuta deploy directamente
+
+## Rol
+
+Director tecnico operativo.
+
+- primero decide
+- luego delega o ejecuta
+- nunca improvisa el estado del proyecto
+
+> **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**.
+
+## Fuentes de verdad y orden de lectura
+
+1. `ops/project_control.json` — backlog y estado operativo
+2. `ops/contract/operating-contract.json` — contrato de maquina
+3. `ops/policy/autonomy.json` — politica de autonomia
+4. `ops/bootstrap/quality-report.json` si existe
+5. `ops/bootstrap/open-questions.md` si existe
+6. `ops/genesis.md` — vista humana compilada
+
+Reglas:
+- `genesis.md` nunca sustituye al contrato estructurado
+- si `project_control.json` y `operating-contract.json` se contradicen, el contrato gana para semantica de maquina y el backlog gana para estado operativo
+
+## Regla absoluta inicial
+
+Antes de asumir nada, ejecuta:
+
+```bash
+trackops status
+```
+
+- si `trackops status` falla, no sigas
+- si no existe TrackOps activo, redirige a la skill global `trackops`
+- si OPERA no esta instalado, indica `trackops opera install`
+
+## Como decidir el modo operativo
+
+Clasifica el trabajo en uno de estos modos:
+
+### `bootstrap_pending`
+Se activa si `meta.opera.bootstrap.status` es:
+- `awaiting_intake`
+- `awaiting_agent`
+- `ready_for_ingest`
+- `needs_review`
+
+### `contract_blocked`
+Se activa si:
+- `quality.contractReadiness` esta en `hypothesis` o `provisional`
+- y existen huecos criticos u open questions que bloquean implementacion o cambio de fase
+
+### `risk_gate`
+Se activa si la accion pedida:
+- toca produccion
+- modifica datos persistentes
+- ejecuta despliegues
+- requiere secretos
+- activa side effects externos
+- o la politica no es inequivoca
+
+### `normal_flow`
+Todo lo demas.
+
+---
+
+## Matriz fase x estado
+
+## O — Orquestar
+
+### Objetivo
+Convertir intencion, evidencia y contexto en base operativa clara.
+
+### Artefactos esperados
+- bootstrap resuelto o encaminado
+- `intake.json`, `spec-dossier.md`
+- `sourceOfTruth`, `singularDesiredOutcome`
+- schemas al menos provisionales
+- contrato coherente o listo para auditar
+
+### Comandos recomendados
+- `trackops status`
+- `trackops opera status`
+- `trackops opera handoff --print` si `awaiting_agent`
+- `trackops opera bootstrap --resume` si `ready_for_ingest`
+
+### Skills delegables
+- `project-starter-skill` para discovery
+- `opera-contract-auditor` cuando exista contrato
+
+### Bloqueo
+No pasar de O si el DoD de O no se cumple.
+
+---
+
+## P — Probar
+
+### Objetivo
+Verificar entorno, integraciones, shapes y viabilidad tecnica real.
+
+### Artefactos esperados
+- credenciales verificadas
+- entorno revisado
+- conectividad basica confirmada
+- findings documentados si algo falla
+
+### Comandos recomendados
+- `trackops status`
+- `trackops env status`
+- `trackops workspace status`
+
+### Skills delegables
+- `opera-policy-guard` si la prueba toca sistemas externos o datos sensibles
+- `opera-contract-auditor` si aparecen contradicciones entre pruebas y contrato
+
+### Bloqueo
+No pasar de P si el entorno o las integraciones criticas no estan verificadas.
+
+---
+
+## E — Estructurar
+
+### Objetivo
+Implementar y estructurar trabajo real manteniendo contrato, backlog y trazabilidad.
+
+### Artefactos esperados
+- cambios de codigo o configuracion alineados al contrato
+- tareas iniciadas/cerradas con TrackOps
+- SOPs o estructura operativa si aplica
+
+### Comandos recomendados
+- `trackops status`
+- `trackops next`
+- `trackops task start <task-id>`
+- `trackops sync` al cerrar cambios estructurales o tareas
+
+### Skills delegables
+- `commiter` cuando se vaya a hacer commit
+- `changelog-updater` tras commit si el flujo del repo lo mantiene
+
+### Bloqueo
+No pasar de E si el trabajo implementado no esta reflejado en estado/tareas/contrato.
+
+---
+
+## R — Refinar
+
+### Objetivo
+Alinear outputs con contrato, revisar calidad y cerrar contradicciones.
+
+### Artefactos esperados
+- revision de coherencia
+- findings resueltos o explicitos
+- politica consultada si hay riesgo
+
+### Comandos recomendados
+- `trackops status`
+- `trackops sync`
+
+### Skills delegables
+- `opera-contract-auditor`
+- `opera-policy-guard`
+
+### Bloqueo
+No pasar de R si siguen existiendo contradicciones materiales o una accion roja/amarilla sin resolver.
+
+---
+
+## A — Automatizar
+
+### Objetivo
+Formalizar release, despliegue y automatizacion operativa con seguridad.
+
+### Artefactos esperados
+- pipeline/automatizacion listos
+- smoke tests superados
+- `.tmp` sin deuda relevante
+- release/deploy preparados segun el proyecto
+
+### Comandos recomendados
+- `trackops status`
+- `trackops workspace status`
+- `trackops env status`
+- `trackops sync`
+
+### Skills delegables
+- `opera-policy-guard`
+
+### Bloqueo
+No pasar de A si la automatizacion rompe politica, entorno o readiness operativo.
+
+---
+
+## Politica de delegacion
+
+### Delegaciones permitidas
+- `project-starter-skill` — cuando bootstrap esta pendiente o el proyecto sigue en discovery
+- `opera-contract-auditor` — cuando hay huecos, contradicciones o dudas de readiness
+- `opera-policy-guard` — cuando hay riesgo, side effects o permisos dudosos
+- `commiter` — cuando el usuario pida commit o el bloque de implementacion ya este listo
+- `changelog-updater` — despues de commit, si el flujo del repo lo requiere
+
+### Delegaciones prohibidas
+- skills no instaladas
+- skills no listadas en `_registry.md`
+- delegacion paralela masiva
+- delegacion mientras el proyecto sigue bloqueado por bootstrap o politica, salvo a las skills que resuelven ese bloqueo
+
+## Politica de comandos TrackOps
+
+### Siempre
+- `trackops status`
+
+### Solo cuando OPERA esta presente
+- `trackops opera status`
+
+### Solo para bootstrap
+- `trackops opera handoff --print`
+- `trackops opera bootstrap --resume`
+
+### Solo para entorno
+- `trackops env status`
+
+### Solo para workspace
+- `trackops workspace status`
+
+### Solo para backlog/ejecucion
+- `trackops next`
+- `trackops task start <task-id>`
+
+### Solo para documentacion operativa
+- `trackops sync`
+
+La skill no debe sugerir comandos destructivos o de release si antes no ha pasado por politica/riesgo cuando corresponde.
+
+## Bloqueo de avance
+
+Si el usuario pide avanzar de fase ("pasemos a la siguiente fase", "esto ya esta listo", "cerramos OPERA", "vamos a release"):
+
+1. identifica la fase actual
+2. carga `references/phase-dod.md`
+3. verifica los criterios
+4. responde con:
+   - `puedes avanzar`
+   - o `no puedes avanzar y faltan estos puntos`
+
+No dejes pasar por intuicion.
+
+## Que referencia leer y cuando
+
+- lee `references/phase-dod.md` cuando se pida cerrar fase, se dude del readiness o el agente tenga que justificar por que no puede avanzar
+- lee la skill `project-starter-skill` cuando estes en Fase O y necesites hacer discovery
+- lee la skill `opera-contract-auditor` cuando necesites validar el contrato operativo
+- lee la skill `opera-policy-guard` cuando vayas a ejecutar acciones con riesgo
+
+## Idioma
+
+Si la conversacion y el proyecto deben trabajar en ingles, lee `locales/en/SKILL.md` antes de seguir.

package/templates/skills/opera-skill/locales/en/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: "opera-skill"
+description: "Local OPERA skill for coordinating work within an OPERA-activated repository. Use it when the user asks which phase the project is in, what to do next, which TrackOps command to run, whether it's safe to advance phases, whether to delegate to another skill, or whether an action should be blocked by bootstrap, contract, or risk."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Skill — Technical Director
+
+## What this skill is
+
+Operational coordinator for OPERA within the repository. This skill directs the main agent: tells it which phase and state the project is in, which TrackOps commands to use, when to block advancement, and when to delegate to specialized skills.
+
+## What this skill is not
+
+- does not implement code
+- does not install the runtime or create the repo structure
+- does not replace the implementing agent
+- does not invent contract or business decisions
+- does not execute deployments directly
+
+## Role
+
+Operational technical director.
+
+- first decide
+- then delegate or execute
+- never improvise the project state
+
+> **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**.
+
+## Sources of truth and reading order
+
+1. `ops/project_control.json` — backlog and operational state
+2. `ops/contract/operating-contract.json` — machine contract
+3. `ops/policy/autonomy.json` — autonomy policy
+4. `ops/bootstrap/quality-report.json` if it exists
+5. `ops/bootstrap/open-questions.md` if it exists
+6. `ops/genesis.md` — compiled human view
+
+Rules:
+- `genesis.md` never replaces the structured contract
+- if `project_control.json` and `operating-contract.json` contradict each other, the contract wins for machine semantics and the backlog wins for operational state
+
+## Absolute initial rule
+
+Before assuming anything, run:
+
+```bash
+trackops status
+```
+
+- if `trackops status` fails, stop
+- if there is no active TrackOps, redirect to the global `trackops` skill
+- if OPERA is not installed, indicate `trackops opera install`
+
+## How to determine operational mode
+
+Classify work into one of these modes:
+
+### `bootstrap_pending`
+Activated if `meta.opera.bootstrap.status` is:
+- `awaiting_intake`
+- `awaiting_agent`
+- `ready_for_ingest`
+- `needs_review`
+
+### `contract_blocked`
+Activated if:
+- `quality.contractReadiness` is `hypothesis` or `provisional`
+- and there are critical gaps or open questions blocking implementation or phase change
+
+### `risk_gate`
+Activated if the requested action:
+- touches production
+- modifies persistent data
+- executes deployments
+- requires secrets
+- triggers external side effects
+- or the policy is ambiguous
+
+### `normal_flow`
+Everything else.
+
+---
+
+## Phase x state matrix
+
+## O — Orchestrate
+
+### Goal
+Convert intention, evidence, and context into a clear operational base.
+
+### Expected artifacts
+- bootstrap resolved or in progress
+- `intake.json`, `spec-dossier.md`
+- `sourceOfTruth`, `singularDesiredOutcome`
+- schemas at least provisional
+- contract coherent or ready for audit
+
+### Recommended commands
+- `trackops status`
+- `trackops opera status`
+- `trackops opera handoff --print` if `awaiting_agent`
+- `trackops opera bootstrap --resume` if `ready_for_ingest`
+
+### Delegable skills
+- `project-starter-skill` for discovery
+- `opera-contract-auditor` when contract exists
+
+### Blocking
+Do not pass O if the O DoD is not met.
+
+---
+
+## P — Prove
+
+### Goal
+Verify environment, integrations, shapes, and real technical viability.
+
+### Expected artifacts
+- credentials verified
+- environment reviewed
+- basic connectivity confirmed
+- findings documented if something fails
+
+### Recommended commands
+- `trackops status`
+- `trackops env status`
+- `trackops workspace status`
+
+### Delegable skills
+- `opera-policy-guard` if testing touches external systems or sensitive data
+- `opera-contract-auditor` if contradictions appear between tests and contract
+
+### Blocking
+Do not pass P if the environment or critical integrations are not verified.
+
+---
+
+## E — Establish
+
+### Goal
+Implement and structure real work while maintaining contract, backlog, and traceability.
+
+### Expected artifacts
+- code or configuration changes aligned with contract
+- tasks started/closed with TrackOps
+- SOPs or operational structure if applicable
+
+### Recommended commands
+- `trackops status`
+- `trackops next`
+- `trackops task start <task-id>`
+- `trackops sync` when closing structural changes or tasks
+
+### Delegable skills
+- `commiter` when committing
+- `changelog-updater` after commit if the repo workflow requires it
+
+### Blocking
+Do not pass E if implemented work is not reflected in state/tasks/contract.
+
+---
+
+## R — Refine
+
+### Goal
+Align outputs with contract, review quality, and close contradictions.
+
+### Expected artifacts
+- coherence review
+- findings resolved or explicit
+- policy consulted if risk exists
+
+### Recommended commands
+- `trackops status`
+- `trackops sync`
+
+### Delegable skills
+- `opera-contract-auditor`
+- `opera-policy-guard`
+
+### Blocking
+Do not pass R if material contradictions or unresolved red/yellow actions remain.
+
+---
+
+## A — Automate
+
+### Goal
+Formalize release, deployment, and operational automation with safety.
+
+### Expected artifacts
+- pipeline/automation ready
+- smoke tests passed
+- `.tmp` without relevant debt
+- release/deploy prepared per project requirements
+
+### Recommended commands
+- `trackops status`
+- `trackops workspace status`
+- `trackops env status`
+- `trackops sync`
+
+### Delegable skills
+- `opera-policy-guard`
+
+### Blocking
+Do not pass A if automation breaks policy, environment, or operational readiness.
+
+---
+
+## Delegation policy
+
+### Allowed delegations
+- `project-starter-skill` — when bootstrap is pending or the project is still in discovery
+- `opera-contract-auditor` — when there are gaps, contradictions, or readiness doubts
+- `opera-policy-guard` — when there is risk, side effects, or dubious permissions
+- `commiter` — when the user requests a commit or the implementation block is ready
+- `changelog-updater` — after commit, if the repo workflow requires it
+
+### Prohibited delegations
+- skills not installed
+- skills not listed in `_registry.md`
+- massive parallel delegation
+- delegation while the project is blocked by bootstrap or policy, except to skills that resolve that block
+
+## TrackOps command policy
+
+### Always
+- `trackops status`
+
+### Only when OPERA is present
+- `trackops opera status`
+
+### Only for bootstrap
+- `trackops opera handoff --print`
+- `trackops opera bootstrap --resume`
+
+### Only for environment
+- `trackops env status`
+
+### Only for workspace
+- `trackops workspace status`
+
+### Only for backlog/execution
+- `trackops next`
+- `trackops task start <task-id>`
+
+### Only for operational documentation
+- `trackops sync`
+
+The skill must not suggest destructive or release commands without first passing through policy/risk when applicable.
+
+## Advancement blocking
+
+If the user asks to advance phases ("let's move to the next phase", "this is done", "let's close OPERA", "let's release"):
+
+1. identify the current phase
+2. load `references/phase-dod.md`
+3. verify the criteria
+4. respond with:
+   - `you can advance`
+   - or `you cannot advance, these points are missing`
+
+Do not let it pass by intuition.
+
+## Which reference to read and when
+
+- read `references/phase-dod.md` when asked to close a phase, when doubting readiness, or when the agent needs to justify why it cannot advance
+- read the `project-starter-skill` when in Phase O and discovery is needed
+- read the `opera-contract-auditor` when the operating contract needs validation
+- read the `opera-policy-guard` when about to execute risky actions
+
+## Language
+
+Use this localized file when the conversation and project should run in English.

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

@@ -0,0 +1,138 @@
+# Definition of Done per Phase
+
+> Reference used by opera-skill to decide whether a phase can be closed.
+> Load it only when asked to close a phase, when doubting readiness, or when justifying why advancement is not possible.
+
+---
+
+## O — Orchestrate
+
+### Exit goal
+Clear operational base: problem defined, user identified, contract coherent.
+
+### Mandatory criteria
+- [ ] Main problem defined
+- [ ] Target user defined
+- [ ] Singular desired outcome defined and verifiable
+- [ ] Source of truth defined
+- [ ] The 5 discovery questions answered (directive, integrations, source of truth, payload, rules)
+- [ ] Repository and version control preferences asked and recorded
+- [ ] Environment and deployment preferences asked and recorded
+- [ ] JSON Input/Output schema defined in `genesis.md` (at least provisional)
+- [ ] Behavior rules documented
+- [ ] `ops/bootstrap/intake.json` complete with minimum fields (includes `versionControl` and `deployment`)
+- [ ] `ops/bootstrap/spec-dossier.md` written with all sections
+- [ ] `ops/contract/operating-contract.json` compiled
+- [ ] `opera-contract-auditor` executed without critical contradictions
+- [ ] `ops/bootstrap/open-questions.md` updated if gaps remain
+- [ ] `task_plan.md` approved by user
+
+### Blockers
+- bootstrap in `awaiting_agent` or `needs_review` state
+- critical contradictions detected by auditor
+- mandatory fields empty in intake.json
+
+### Delegation signal
+- If intake.json or spec-dossier.md is missing → delegate to `project-starter-skill`
+- If contract has contradictions → delegate to `opera-contract-auditor`
+
+---
+
+## P — Prove
+
+### Exit goal
+Environment verified, connectivity confirmed, real technical viability.
+
+### Mandatory criteria
+- [ ] All credentials in `.env` verified (exist and are not empty)
+- [ ] Execution environment reviewed and functional
+- [ ] Critical connectivity confirmed (APIs, external services)
+- [ ] Response shapes validated against `genesis.md` schema
+- [ ] Results documented in `findings.md`
+- [ ] If any test fails, the task is marked as blocked with documented reason
+- [ ] No open findings with `critical` severity
+
+### Blockers
+- missing or invalid credentials
+- critical external service not responding
+- response shape does not match schema
+
+### Delegation signal
+- If risk when testing external systems → consult `opera-policy-guard`
+- If contradictions appear between tests and contract → delegate to `opera-contract-auditor`
+
+---
+
+## E — Establish
+
+### Exit goal
+Work implemented, traced, and aligned with contract and backlog.
+
+### Mandatory criteria
+- [ ] Relevant tasks started and closed with TrackOps
+- [ ] Code or configuration implemented and aligned with contract
+- [ ] SOPs written in `architecture/` when complexity requires it
+- [ ] Dependency graph documented in `genesis.md` if pipeline exists
+- [ ] Tools with side-effects marked with META tags (`idempotent`, `side-effect`, `requires-confirmation`)
+- [ ] Commits following convention (`commiter` skill activated)
+- [ ] `CHANGELOG.md` updated if the repo workflow requires it (`changelog-updater` skill)
+- [ ] Operational changes synchronized with `trackops sync`
+
+### Blockers
+- implementation tasks not started in trackops
+- code that contradicts contract without justification
+- uncommitted changes
+
+### Delegation signal
+- When committing → delegate to `commiter`
+- Post-commit → delegate to `changelog-updater`
+
+---
+
+## R — Refine
+
+### Exit goal
+Outputs aligned with contract, quality verified, contradictions closed.
+
+### Mandatory criteria
+- [ ] Coherence review completed
+- [ ] Outputs validated against templates in `templates/` if they exist
+- [ ] Delivery formats (Markdown, HTML, JSON) verified
+- [ ] If there is an interface: visual review completed
+- [ ] `opera-contract-auditor` executed without critical contradictions
+- [ ] `opera-policy-guard` consulted for risky actions
+- [ ] No open findings with `critical` or `high` severity
+- [ ] Findings resolved or explicitly accepted by user
+
+### Blockers
+- material contradictions open between outputs and contract
+- unresolved red/yellow actions
+- critical open findings
+
+### Delegation signal
+- To validate contract → delegate to `opera-contract-auditor`
+- For risky actions → delegate to `opera-policy-guard`
+
+---
+
+## A — Automate
+
+### Exit goal
+Automation or release ready, environment verified, temporal debt resolved.
+
+### Mandatory criteria
+- [ ] `.tmp/` clean (no relevant residual files)
+- [ ] Code deployed or prepared for deployment per `intake.json.deployment`
+- [ ] Triggers configured and verified (cron, webhooks) if applicable
+- [ ] Smoke test passed at destination
+- [ ] `progress.md` updated with final state
+- [ ] `trackops sync` executed
+- [ ] If `versionControl.remote` is true: changes pushed to remote
+
+### Blockers
+- automation that breaks policy or environment
+- failing smoke test
+- temporal debt preventing clean release
+
+### Delegation signal
+- For deploy actions → consult `opera-policy-guard`