trackops 1.0.1 → 2.0.0

package/templates/opera/en/architecture/runtime-operations.md

@@ -0,0 +1,34 @@
+# SOP - Runtime Operations
+
+## Purpose
+
+Define the minimum operating procedure required to keep a TrackOps + OPERA workspace healthy.
+
+## Inputs
+
+- `ops/project_control.json`
+- `ops/contract/operating-contract.json`
+- `ops/policy/autonomy.json`
+- `ops/bootstrap/quality-report.json`
+
+## Core checks
+
+1. Run `trackops status`.
+2. Run `trackops opera status`.
+3. Run `trackops env status`.
+4. Confirm `contract readiness` is not `hypothesis` for active delivery work.
+5. Confirm `legacyStatus` is `supported`.
+
+## Recovery path
+
+1. If bootstrap is incomplete, run `trackops opera handoff --print`.
+2. If discovery artifacts already exist, run `trackops opera bootstrap --resume`.
+3. If operational docs drift, run `trackops sync`.
+4. If managed artifacts drift, run `trackops opera upgrade --stable`.
+
+## Exit criteria
+
+- Runtime status is readable.
+- OPERA status is readable.
+- Contract and policy files exist.
+- No critical blocker remains undocumented.

package/templates/opera/en/genesis.md

@@ -0,0 +1,79 @@
+# {{PROJECT_NAME}} — Genesis
+
+> **The Constitution of the project.** This document is the source of truth. Before making any architectural or implementation decision, consult this file. If a script contradicts what is defined here, the script is wrong.
+
+---
+
+## 1. Desired Outcome
+
+_What is the single desired outcome of this project?_
+
+> {{DESIRED_OUTCOME}}
+
+---
+
+## 2. External Integrations
+
+_Which external services do we need? Are credentials ready?_
+
+| Service | Status | Key / Config |
+|---------|--------|--------------|
+{{SERVICES_TABLE}}
+
+---
+
+## 3. Source of Truth
+
+_Where does the primary data live?_
+
+> {{SOURCE_OF_TRUTH}}
+
+---
+
+## 4. Payload
+
+_How and where should the final result be delivered?_
+
+> {{PAYLOAD}}
+
+---
+
+## 5. Behavior Rules
+
+_Domain constraints, tone, and specific rules._
+
+{{BEHAVIOR_RULES}}
+
+---
+
+## Data Schema
+
+> **Data-first rule**: this schema must exist before any code is written.
+
+```json
+{{DATA_SCHEMA}}
+```
+
+---
+
+## Architectural Invariants
+
+_Non-negotiable technical decisions. Changing them requires explicit approval._
+
+{{ARCHITECTURAL_INVARIANTS}}
+
+---
+
+## Pipeline
+
+_Document the dependency graph between tools._
+
+{{PIPELINE_ITEMS}}
+
+---
+
+## Templates
+
+_References to output templates defined under `templates/`._
+
+{{TEMPLATE_ITEMS}}

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

@@ -0,0 +1,23 @@
+# Autonomy and Recovery
+
+Use this reference to decide when the agent can continue autonomously and when it must stop for confirmation.
+
+## Red level
+
+Ask for confirmation before:
+- Changing `genesis.md` in a way that alters the contract.
+- Deleting persistent data.
+- Creating repositories or external resources.
+- Deploying to production.
+
+## Green level
+
+Proceed autonomously for:
+- Reading and editing local source files.
+- Running tests and checks.
+- Updating operational docs.
+- Repairing deterministic errors after a bounded number of attempts.
+
+## Recovery rule
+
+If a later phase invalidates an earlier decision, document the proposed change first, request approval, and only then update `genesis.md` and the operational record.

package/templates/opera/en/references/opera-cycle.md

@@ -0,0 +1,62 @@
+# The O.P.E.R.A. Cycle — Complete Reference
+
+This document describes each phase, its rules, its procedures, and its Definition of Done.
+
+---
+
+## O — Orchestrate
+
+Answer the five discovery questions, define the input/output schema in `genesis.md`, document behavior rules, and make sure the plan is approved before moving forward.
+
+### Definition of Done
+- [ ] Discovery questions answered.
+- [ ] Input/output schema defined in `genesis.md`.
+- [ ] Behavior rules documented in `genesis.md`.
+- [ ] `task_plan.md` reviewed and accepted.
+
+---
+
+## P — Prove
+
+Validate credentials, run minimal connectivity checks, and confirm that external systems return data that matches the schema in `genesis.md`.
+
+### Definition of Done
+- [ ] Required credentials verified.
+- [ ] Connectivity tests executed and passing.
+- [ ] Response shapes validated against `genesis.md`.
+- [ ] Findings documented.
+
+---
+
+## E — Establish
+
+Build the three-layer structure: SOPs in `architecture/`, atomic tools in `tools/`, and explicit dependency flow in `genesis.md`.
+
+### Definition of Done
+- [ ] SOPs written.
+- [ ] Tools implemented.
+- [ ] Dependency graph documented.
+- [ ] Integration tests passing.
+
+---
+
+## R — Refine
+
+Validate outputs against templates and ensure delivery formats match the expected payload.
+
+### Definition of Done
+- [ ] Outputs validated against templates.
+- [ ] Delivery formats reviewed.
+- [ ] UI review completed when applicable.
+
+---
+
+## A — Automate
+
+Clean temporary artifacts, configure triggers, deploy the final logic, and run a smoke test in the target environment.
+
+### Definition of Done
+- [ ] `.tmp/` cleaned.
+- [ ] Deployment completed.
+- [ ] Triggers configured.
+- [ ] Smoke test passing.

package/templates/opera/en/registry.md

@@ -0,0 +1,28 @@
+# Skills Registry — {{PROJECT_NAME}}
+
+> Index of installed skills in this project. Managed automatically by `trackops skill`.
+
+---
+
+## Installed Skills
+
+_No skills installed yet. Use `trackops skill install <name>` to add one._
+
+---
+
+## How to Use a Skill
+
+1. Identify the context in `.agent/hub/router.md`.
+2. Open the corresponding `SKILL.md`.
+3. Follow the workflow defined in that skill.
+
+---
+
+## Management
+
+```bash
+trackops skill list
+trackops skill catalog
+trackops skill install <name>
+trackops skill remove <name>
+```

package/templates/opera/en/reviews/delivery-audit.md

@@ -0,0 +1,18 @@
+# Delivery Audit
+
+## Scope
+
+Review the final output shape against the active templates and compiled contract.
+
+## Checklist
+
+- `ops/genesis.md` matches the current contract.
+- `ops/task_plan.md`, `ops/progress.md` and `ops/findings.md` are synchronized.
+- Public copy matches runtime behavior.
+- API and dashboard reflect the same operational state.
+- Visual review completed when a UI change exists.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/en/reviews/integration-audit.md

@@ -0,0 +1,18 @@
+# Integration Audit
+
+## Scope
+
+Review credentials, connectivity assumptions and external response shapes before expanding delivery.
+
+## Checklist
+
+- Required keys identified from the contract and environment contract.
+- Missing keys documented without exposing secret values.
+- External services listed in the contract.
+- Response shapes aligned with `ops/contract/operating-contract.json`.
+- Findings recorded in `ops/findings.md` when applicable.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/en/router.md

@@ -0,0 +1,49 @@
+# Skills Router
+
+## Purpose
+This file defines the routing rules between the main agent and the available skills. When the agent detects a specific context, it should consult these rules and choose the right skill.
+
+## Routing Rules
+
+### Context: Code commit
+- **Trigger**: The user asks for a commit or a code change has just been completed.
+- **Skill**: `commiter`
+- **Action**: Use the skill to format the commit message.
+
+### Context: Post-commit
+- **Trigger**: A successful commit has just happened.
+- **Skill**: `changelog-updater`
+- **Action**: Run the changelog update flow.
+
+### Context: Agent-led project start
+- **Trigger**: The user has an idea, partial specification, or TrackOps has generated `ops/bootstrap/agent-handoff.md`.
+- **Skill**: `project-starter-skill`
+- **Action**: Turn the user context into `ops/bootstrap/intake.json`, `ops/bootstrap/spec-dossier.md`, and `ops/bootstrap/open-questions.md` when needed.
+
+### Context: Contract audit
+- **Trigger**: `ops/contract/operating-contract.json` or `ops/bootstrap/quality-report.json` exists and there are doubts about gaps or contradictions.
+- **Skill**: `opera-contract-auditor`
+- **Action**: Audit consistency, gaps, and false precision before execution continues.
+
+### Context: Operational risk
+- **Trigger**: The action affects persistent data, deployments, external side effects, or sensitive permissions.
+- **Skill**: `opera-policy-guard`
+- **Action**: Read `ops/policy/autonomy.json` and decide whether explicit approval is required.
+
+### Context: Operational tracking
+- **Trigger**: A work block is about to start, resume, or close.
+- **Skill**: No external skill.
+- **Action**: Run `trackops status`, take the next task with `trackops next`, use `ops/contract/operating-contract.json` as the machine contract, and keep `ops/project_control.json` as the backlog source of truth.
+
+## Adding New Rules
+
+Use this format for each new rule:
+
+```markdown
+### Context: [description]
+- **Trigger**: [what activates the rule]
+- **Skill**: [skill name]
+- **Action**: [what the agent should do]
+```
+
+When a new skill is installed with `trackops skill install <name>`, add its routing rule here.

package/templates/opera/genesis.md

@@ -1,94 +1,79 @@
-# {{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
--->
+# {{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?_
+
+> {{DESIRED_OUTCOME}}
+
+---
+
+## 2. Integraciones Externas
+
+_¿Qué servicios externos necesitamos? ¿Están listas las claves?_
+
+| Servicio | Estado | Clave / Config |
+|----------|--------|----------------|
+{{SERVICES_TABLE}}
+
+---
+
+## 3. Fuente de la Verdad
+
+_¿Dónde viven los datos primarios?_
+
+> {{SOURCE_OF_TRUTH}}
+
+---
+
+## 4. Carga Útil (Payload)
+
+_¿Cómo y dónde debe entregarse el resultado final?_
+
+> {{PAYLOAD}}
+
+---
+
+## 5. Reglas de Comportamiento
+
+_Restricciones, tono y reglas específicas del dominio._
+
+{{BEHAVIOR_RULES}}
+
+---
+
+## Esquema de Datos
+
+> **Regla "Datos-Primero"**: Este schema debe estar definido antes de escribir cualquier código.
+
+```json
+{{DATA_SCHEMA}}
+```
+
+---
+
+## Invariantes Arquitectónicas
+
+_Decisiones técnicas inamovibles. Cambiarlas requiere aprobación explícita (Nivel Rojo)._
+
+{{ARCHITECTURAL_INVARIANTS}}
+
+---
+
+## Pipeline
+
+_Documenta el grafo de dependencias entre herramientas._
+
+{{PIPELINE_ITEMS}}
+
+---
+
+## Templates
+
+_Referencias a las plantillas de output definidas en `templates/`._
+
+{{TEMPLATE_ITEMS}}

package/templates/opera/reviews/delivery-audit.md

@@ -0,0 +1,18 @@
+# Delivery Audit
+
+## Scope
+
+Review the final output shape against the active templates and compiled contract.
+
+## Checklist
+
+- `ops/genesis.md` matches the current contract.
+- `ops/task_plan.md`, `ops/progress.md` and `ops/findings.md` are synchronized.
+- Public copy matches runtime behavior.
+- API and dashboard reflect the same operational state.
+- Visual review completed when a UI change exists.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/reviews/integration-audit.md

@@ -0,0 +1,18 @@
+# Integration Audit
+
+## Scope
+
+Review credentials, connectivity assumptions and external response shapes before expanding delivery.
+
+## Checklist
+
+- Required keys identified from the contract and environment contract.
+- Missing keys documented without exposing secret values.
+- External services listed in the contract.
+- Response shapes aligned with `ops/contract/operating-contract.json`.
+- Findings recorded in `ops/findings.md` when applicable.
+
+## Result
+
+- Status: pending review
+- Notes: replace this section with project-specific evidence.

package/templates/opera/router.md

@@ -15,15 +15,25 @@ Este archivo define las reglas de enrutamiento entre el agente principal y las s
 - **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: Arranque asistido del proyecto
+- **Trigger**: El usuario tiene una idea, una especificación parcial o TrackOps ha generado `ops/bootstrap/agent-handoff.md`.
+- **Skill**: `project-starter-skill`
+- **Acción**: Convertir el contexto del usuario en `ops/bootstrap/intake.json`, `ops/bootstrap/spec-dossier.md` y `ops/bootstrap/open-questions.md` cuando haga falta.
+
+### Contexto: Auditoria del contrato
+- **Trigger**: Existe `ops/contract/operating-contract.json` o `ops/bootstrap/quality-report.json` y hay dudas sobre huecos o contradicciones.
+- **Skill**: `opera-contract-auditor`
+- **Acción**: Auditar consistencia, huecos y pseudoprecision antes de seguir ejecutando.
+
+### Contexto: Riesgo operativo
+- **Trigger**: La accion afecta datos persistentes, despliegues, efectos externos o permisos sensibles.
+- **Skill**: `opera-policy-guard`
+- **Acción**: Consultar `ops/policy/autonomy.json` y decidir si hace falta aprobacion explicita.
 
 ### 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.
+- **Acción**: Ejecutar `trackops status`, tomar la siguiente tarea con `trackops next`, usar `ops/contract/operating-contract.json` como contrato de maquina y mantener `ops/project_control.json` como fuente de verdad operativa del backlog.
 
 ## Cómo Añadir Nuevas Reglas
 

package/templates/skills/changelog-updater/locales/en/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: "changelog-updater"
+description: "Automatically update CHANGELOG.md from the latest commit after a successful commit."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# Changelog Updater
+
+Use this skill right after a successful commit to update `CHANGELOG.md` from the git history. It should parse the latest commit, classify it using Conventional Commit semantics, and append the entry to the proper dated section.

package/templates/skills/commiter/locales/en/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: "commiter"
+description: "Generate commit messages in English following strict Conventional Commits rules with emojis."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# Commit Writer
+
+Use this skill whenever a commit message must be generated. The message must follow Conventional Commits, keep the scope explicit when relevant, and preserve the emoji convention used by the project.

package/templates/skills/opera-contract-auditor/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: "opera-contract-auditor"
+description: "Skill para auditar el contrato operativo de OPERA, detectar huecos, contradicciones y pseudoprecision antes de seguir ejecutando."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Contract Auditor
+
+Usa esta skill cuando exista `ops/contract/operating-contract.json` o cuando OPERA haya dejado `ops/bootstrap/quality-report.json`.
+
+## Objetivo
+
+Validar si el contrato operativo ya es suficientemente coherente para pasar de discovery a ejecucion.
+
+## Debes revisar
+
+- `ops/contract/operating-contract.json`
+- `ops/bootstrap/quality-report.json`
+- `ops/bootstrap/open-questions.md`
+- `ops/genesis.md`
+
+## Checklist minimo
+
+- el problema y el usuario objetivo estan definidos
+- el resultado singular deseado es verificable
+- la fuente de verdad esta clara
+- input y output schema no se contradicen
+- no hay reglas de comportamiento ambiguas
+- las integraciones externas son coherentes con el contrato
+- las preguntas abiertas siguen abiertas de forma explicita o estan resueltas
+
+## Salida esperada
+
+- identificar contradicciones o lagunas concretas
+- proponer solo las correcciones necesarias
+- no inventar decisiones de negocio no confirmadas

package/templates/skills/opera-contract-auditor/locales/en/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: "opera-contract-auditor"
+description: "Skill for auditing the OPERA operating contract, spotting gaps, contradictions, and false precision before execution continues."
+metadata:
+  version: "1.0"
+  type: "project"
+---
+
+# OPERA Contract Auditor
+
+Use this skill when `ops/contract/operating-contract.json` already exists or when OPERA has produced `ops/bootstrap/quality-report.json`.
+
+## Goal
+
+Validate whether the operating contract is coherent enough to move from discovery into execution.
+
+## Review these files
+
+- `ops/contract/operating-contract.json`
+- `ops/bootstrap/quality-report.json`
+- `ops/bootstrap/open-questions.md`
+- `ops/genesis.md`
+
+## Minimum checklist
+
+- the problem and target user are defined
+- the singular desired outcome is verifiable
+- the source of truth is clear
+- input and output schema do not contradict each other
+- behavior rules are not ambiguous
+- external integrations match the contract
+- open questions are either explicitly open or clearly resolved
+
+## Expected output
+
+- identify concrete contradictions or gaps
+- propose only the corrections that are actually needed
+- do not invent unconfirmed business decisions