@ingeniomaps/cauce 0.1.0

package/engine/teams/registry.js

@@ -0,0 +1,85 @@
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+function teamFile(root, slug) {
+  if (!SLUG.test(slug || '')) throw new Error(`team inválido: ${slug || '(vacío)'}`)
+  return path.join(root, 'teams', slug, 'team.json')
+}
+
+function agentMatches(root, slug) {
+  const catalog = path.join(root, 'agents')
+  let types = []
+  try {
+    types = fs.readdirSync(catalog, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+  } catch { return [] }
+  return types
+    .map((entry) => path.join(catalog, entry.name, slug, 'SKILL.md'))
+    .filter((file) => fs.existsSync(file))
+}
+
+function read(root, slug) {
+  const file = teamFile(root, slug)
+  if (!fs.existsSync(file)) throw new Error(`no existe teams/${slug}/team.json`)
+  let manifest
+  try { manifest = JSON.parse(fs.readFileSync(file, 'utf8')) } catch (error) {
+    throw new Error(`teams/${slug}/team.json inválido: ${error.message}`)
+  }
+  return { file, manifest }
+}
+
+function validate(root, slug) {
+  const { manifest } = read(root, slug)
+  const errors = []
+  if (manifest.schemaVersion !== 1) errors.push('schemaVersion debe ser 1')
+  if (manifest.slug !== slug) errors.push(`slug debe ser ${slug}`)
+  for (const field of ['name', 'purpose', 'entryAgent', 'facilitator']) {
+    if (typeof manifest[field] !== 'string' || !manifest[field].trim()) errors.push(`falta ${field}`)
+  }
+  if (!Array.isArray(manifest.stages) || !manifest.stages.length) errors.push('stages debe contener etapas')
+  if (!Array.isArray(manifest.guardrails) || !manifest.guardrails.length) errors.push('guardrails debe contener controles')
+  if (!Array.isArray(manifest.completion) || !manifest.completion.length) errors.push('completion debe contener criterios')
+
+  const agents = new Set([manifest.entryAgent, manifest.facilitator])
+  for (const agent of Object.values(manifest.decisionOwners || {})) agents.add(agent)
+  for (const agent of manifest.conditionalAgents || []) agents.add(agent)
+  const seen = new Set()
+  for (const stage of manifest.stages || []) {
+    if (!SLUG.test(stage.id || '')) errors.push(`id de etapa inválido: ${stage.id || '(vacío)'}`)
+    else if (seen.has(stage.id)) errors.push(`etapa duplicada: ${stage.id}`)
+    for (const dependency of stage.dependsOn || []) {
+      if (!seen.has(dependency)) errors.push(`${stage.id}: dependencia inexistente o posterior ${dependency}`)
+    }
+    seen.add(stage.id)
+    agents.add(stage.agent)
+    if (!Array.isArray(stage.produces) || !stage.produces.length) errors.push(`${stage.id}: falta produces`)
+    if (typeof stage.exitGate !== 'string' || !stage.exitGate.trim()) errors.push(`${stage.id}: falta exitGate`)
+  }
+  for (const agent of agents) {
+    if (!SLUG.test(agent || '')) errors.push(`slug de agente inválido: ${agent || '(vacío)'}`)
+    else {
+      const matches = agentMatches(root, agent)
+      if (!matches.length) errors.push(`agente inexistente: ${agent}`)
+      if (matches.length > 1) errors.push(`agente ambiguo: ${agent}`)
+    }
+  }
+  const workflow = path.join(root, 'teams', slug, 'WORKFLOW.md')
+  if (!fs.existsSync(workflow)) errors.push('falta WORKFLOW.md')
+  return { errors, stages: (manifest.stages || []).length, agents: agents.size, manifest }
+}
+
+function list(root) {
+  const catalog = path.join(root, 'teams')
+  try {
+    return fs.readdirSync(catalog, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => fs.existsSync(path.join(catalog, entry.name, 'team.json')))
+      .map((entry) => entry.name)
+      .sort()
+  } catch { return [] }
+}
+
+module.exports = { list, read, validate }

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ingeniomaps/cauce",
+  "version": "0.1.0",
+  "description": "Sistema portable de planificación y ejecución verificable para cualquier proyecto",
+  "type": "commonjs",
+  "bin": {
+    "cauce": "engine/cli/ops.js"
+  },
+  "files": [
+    "engine/",
+    "template/",
+    "agents/",
+    "teams/",
+    "automatization/",
+    ".github/workflows/",
+    "LICENSE"
+  ],
+  "scripts": {
+    "ops": "node engine/cli/ops.js",
+    "check": "node engine/cli/ops.js check template/planning",
+    "tree": "node engine/cli/ops.js tree template/planning --no-color",
+    "automation:check": "node engine/cli/ops.js automation check .",
+    "integration:check": "node engine/cli/ops.js integration check template jira",
+    "test": "bash test/hooks-smoke.sh && node --test test/*.test.js",
+    "coverage": "bash test/coverage.sh",
+    "ci": "npm run check && npm run automation:check && npm run integration:check && npm run coverage"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "npm@11.16.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ingeniomaps/cauce.git"
+  },
+  "license": "MIT"
+}

package/teams/.gitkeep

@@ -0,0 +1 @@
+

package/teams/product-development/WORKFLOW.md

@@ -0,0 +1,54 @@
+# Product Development Team
+
+## Cómo activarlo
+
+Usar este equipo cuando exista un problema de producto que requiera discovery, diseño, construcción, validación, lanzamiento y aprendizaje coordinados. Empezar con una petición como:
+
+```text
+Usa el team product-development para evaluar y desarrollar esta oportunidad:
+<problema, usuarios, contexto, restricciones y evidencia disponible>
+```
+
+Leer `team.json`, el contexto de `organization/` y el `SKILL.md` del agente activo. Ejecutar una etapa a la vez. Guardar cada artefacto en el sistema de planificación de la empresa o presentarlo al usuario; no crear una fuente de verdad paralela dentro de esta carpeta.
+
+## Protocolo de handoff
+
+Cada handoff debe incluir:
+
+```markdown
+Etapa y agente:
+Outcome perseguido:
+Entradas y evidencia utilizadas:
+Artefactos producidos:
+Decisiones tomadas, decisor y fecha:
+Supuestos, incertidumbre y dissent:
+Riesgos, guardrails y bloqueos:
+Preguntas para la siguiente etapa:
+Exit gate: cumplido / no cumplido
+Autorizaciones pendientes:
+```
+
+No avanzar si el exit gate no se cumple. El agente siguiente puede devolver el handoff cuando falte evidencia, autoridad, contrato o criterio verificable.
+
+## Selección de ingeniería
+
+La etapa `build` usa Backend Engineer como owner predeterminado del handoff, no como ejecutor universal. Engineering Manager y Software Architect seleccionan los agentes necesarios según la arquitectura:
+
+- Frontend Engineer para interfaces web.
+- Mobile Engineer para aplicaciones móviles.
+- Backend Engineer para servicios y lógica de servidor.
+- Data/ML/MLOps Engineers para datos o modelos en producción.
+- DevOps/SRE/Cloud Architect para plataforma, delivery o confiabilidad.
+
+La selección no autoriza asignar personas, ejecutar código ni cambiar producción.
+
+## Consultas condicionales
+
+Incorporar Security Engineer y Privacy Compliance Specialist temprano cuando haya datos sensibles, identidad, pagos, exposición pública, abuso o decisiones de alto impacto. Incorporar UI Designer para sistema visual, Technical Writer para documentación y Customer Support Specialist para readiness de soporte. Data Analyst participa al inicio si falta baseline y siempre en la revisión posterior cuando existan datos autorizados.
+
+## Prueba rápida
+
+```bash
+make team-check TEAM=product-development
+node engine/cli/ops.js team show product-development
+```

package/teams/product-development/team.json

@@ -0,0 +1,106 @@
+{
+  "schemaVersion": 1,
+  "slug": "product-development",
+  "name": "Product Development Team",
+  "purpose": "Convertir un problema validado de usuario en una entrega segura, usable, operable y medible.",
+  "entryAgent": "product-manager",
+  "facilitator": "project-manager",
+  "decisionOwners": {
+    "value_and_priority": "product-manager",
+    "user_evidence": "user-researcher",
+    "experience": "ux-designer",
+    "technical_design": "software-architect",
+    "capacity_and_assignment": "engineering-manager",
+    "quality_evidence": "qa-engineer",
+    "release": "release-manager"
+  },
+  "conditionalAgents": [
+    "data-analyst",
+    "ui-designer",
+    "frontend-engineer",
+    "backend-engineer",
+    "mobile-engineer",
+    "security-engineer",
+    "privacy-compliance-specialist",
+    "technical-writer",
+    "customer-support-specialist"
+  ],
+  "stages": [
+    {
+      "id": "frame",
+      "agent": "product-manager",
+      "dependsOn": [],
+      "produces": ["opportunity-brief", "outcome-and-guardrails"],
+      "exitGate": "Problema, usuario, outcome, baseline, límites y decisión requerida están explícitos."
+    },
+    {
+      "id": "research",
+      "agent": "user-researcher",
+      "dependsOn": ["frame"],
+      "produces": ["research-evidence", "needs-and-risks"],
+      "exitGate": "La evidencia diferencia hallazgos, hipótesis y preguntas abiertas sin inventar consenso."
+    },
+    {
+      "id": "shape",
+      "agent": "ux-designer",
+      "dependsOn": ["research"],
+      "produces": ["journey-and-flows", "usability-risks"],
+      "exitGate": "El flujo cubre estados críticos, errores, accesibilidad, control y recuperación del usuario."
+    },
+    {
+      "id": "architect",
+      "agent": "software-architect",
+      "dependsOn": ["frame", "shape"],
+      "produces": ["architecture-decision", "interfaces-and-quality-attributes"],
+      "exitGate": "Opciones y tradeoffs están documentados; interfaces, riesgos y reversibilidad son verificables."
+    },
+    {
+      "id": "plan",
+      "agent": "engineering-manager",
+      "dependsOn": ["architect"],
+      "produces": ["delivery-plan", "ownership-and-capacity"],
+      "exitGate": "Los equipos dueños validaron estimaciones, capacidad, dependencias y criterios de integración."
+    },
+    {
+      "id": "build",
+      "agent": "backend-engineer",
+      "dependsOn": ["plan"],
+      "produces": ["working-increment", "implementation-evidence"],
+      "exitGate": "El incremento mínimo funciona en entorno autorizado y conserva contratos, controles y pruebas."
+    },
+    {
+      "id": "verify",
+      "agent": "qa-engineer",
+      "dependsOn": ["build"],
+      "produces": ["quality-evidence", "residual-risk"],
+      "exitGate": "Criterios, regresiones, riesgos y evidencia adversa están visibles; no quedan bloqueos ocultos."
+    },
+    {
+      "id": "release",
+      "agent": "release-manager",
+      "dependsOn": ["verify"],
+      "produces": ["release-readiness", "rollout-and-rollback"],
+      "exitGate": "Owners autorizados aceptaron readiness, observabilidad, soporte, rollout, abort y rollback."
+    },
+    {
+      "id": "learn",
+      "agent": "data-analyst",
+      "dependsOn": ["release"],
+      "produces": ["outcome-review", "follow-up-recommendation"],
+      "exitGate": "Outcome y guardrails se comparan con baseline; se decide mantener, iterar, escalar o retirar."
+    }
+  ],
+  "guardrails": [
+    "Cada agente conserva los límites y autorizaciones de su SKILL.md.",
+    "Ningún handoff convierte una propuesta en aprobación o ejecución.",
+    "Los owners resuelven decisiones; el facilitador sólo mantiene flujo y evidencia.",
+    "Los agentes condicionales se incorporan por riesgo, plataforma y alcance, no por rutina.",
+    "Se conserva evidencia adversa, dissent, incertidumbre y decisiones pendientes."
+  ],
+  "completion": [
+    "Outcome y guardrails medidos contra baseline.",
+    "Entrega aceptada y operable con owner, soporte y observabilidad.",
+    "Riesgos residuales aceptados por la autoridad correspondiente.",
+    "Decisión posterior registrada: mantener, iterar, escalar o retirar."
+  ]
+}

package/template/AGENTS.md

@@ -0,0 +1,61 @@
+# {{PROJECT_NAME}} — reglas de construcción
+
+Este archivo gobierna el qué y el cuándo. `planning/PROTOCOL.md` gobierna el flujo y
+`planning/rules/` el cómo.
+
+## Mapa real
+
+Completar antes de la primera tarea:
+
+- Qué producto se construye.
+- Qué repos o servicios existen y dónde viven.
+- Dónde documenta cada servicio sus comandos de test, lint y build.
+- Qué directorios son legacy o están fuera de alcance.
+
+El mapa no debe duplicar documentación técnica: enlaza a la fuente de verdad de cada servicio.
+
+## Integraciones y ambientes
+
+Por defecto, todo sistema externo se considera real y de solo lectura. Sin aprobación humana explícita:
+
+- no desplegar, publicar, enviar mensajes ni escribir en producción;
+- no cobrar, reembolsar, gastar créditos ni llamar APIs con costo de forma repetida;
+- no editar secretos, credenciales, DNS, permisos o cuentas;
+- no borrar datos ni ejecutar migraciones irreversibles.
+
+Documentar excepciones concretas aquí. Un entorno de desarrollo o sandbox debe nombrarse explícitamente.
+
+## Cómo leer el estado
+
+Antes de abrir un archivo de `planning/`, preguntarle al CLI: es determinista, no gasta contexto y no
+muta nada.
+
+- `node tools/ops.js context planning` — gate, mutex de WIP y la tarea que corresponde ahora, con su
+  aceptación y sus criterios. Es la entrada correcta para empezar a trabajar.
+- `node tools/ops.js tree planning` — panorama de roadmap, backlog, WIP, inbox y done.
+- `node tools/ops.js check planning` — validación de contratos y trazabilidad.
+
+Los tres aceptan `--json`. Leer `BACKLOG.md`, `WIP.md` o `HUMAN_ACTIONS.md` completos sólo cuando haga
+falta editarlos o cuando el CLI no responda la pregunta.
+
+## Autonomía
+
+El runner puede implementar una tarea promovida dentro del servicio declarado, crear pruebas y hacer
+refactors locales necesarios para su aceptación.
+
+Debe detenerse cuando falte una decisión de producto, credencial, cuenta o acción externa; cuando una
+verificación siga roja tras un intento razonable; o al cruzar un hito si el protocolo exige checkpoint.
+Registra la acción exacta en `planning/HUMAN_ACTIONS.md` y, si bloquea todo, crea
+`planning/AWAITING_REVIEW.md`.
+
+Nunca amplía el alcance, promueve sus propias ideas, reescribe el proceso durante una tarea, usa
+`git add .`/`git add -A`, hace push/force/amend, ni afirma éxito sin evidencia real.
+
+## Definición de terminado
+
+1. La aceptación se observa y queda cubierta por pruebas cuando existe superficie testeable.
+2. Tests, lint, tipos y build aplicables terminan con exit code real.
+3. QA valida el comportamiento por el camino real, no por un atajo interno.
+4. La deuda residual va a `planning/INBOX.md`.
+5. El cambio se commitea por tarea en el repo del servicio y el hash real queda en `DONE.md`.
+6. `node tools/ops.js check planning` queda verde.

package/template/Makefile

@@ -0,0 +1,58 @@
+.DEFAULT_GOAL := help
+
+.PHONY: help check tree context automation-check
+.PHONY: require-agent agent-learn agent-propose agent-evaluate
+.PHONY: install-claude install-codex install-gemini install-antigravity
+.PHONY: doctor-claude doctor-codex doctor-gemini doctor-antigravity
+
+help: ## Muestra los comandos disponibles y su propósito
+	@awk 'BEGIN {FS = ":.*## "; printf "Uso: make <comando>\n\n"} \
+	/^[a-zA-Z0-9_-]+:.*## / {printf "  %-18s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+check: ## Valida planning e integraciones
+	@node tools/ops.js check planning
+
+tree: ## Muestra roadmap, backlog, WIP y Done
+	@node tools/ops.js tree planning
+
+context: ## Muestra el contexto mínimo de la tarea vigente
+	@node tools/ops.js context planning
+
+automation-check: ## Comprueba hooks, workflows y adaptadores
+	@node tools/ops.js automation check .
+
+require-agent:
+	@test -n "$(AGENT)" || (echo "Falta AGENT=<slug>" >&2; exit 2)
+
+agent-learn: require-agent ## Prepara el informe semanal de AGENT=<slug>
+	@node tools/ops.js learn "$(AGENT)"
+
+agent-propose: require-agent ## Consolida una propuesta para AGENT=<slug>
+	@node tools/ops.js learn "$(AGENT)" --proposal
+
+agent-evaluate: require-agent ## Evalúa controles y casos de AGENT=<slug>
+	@node tools/ops.js evaluate "$(AGENT)"
+
+install-claude: ## Instala hooks y workflows para Claude
+	@node tools/ops.js automation install . claude
+
+install-codex: ## Instala hooks para Codex
+	@node tools/ops.js automation install . codex
+
+install-gemini: ## Instala contexto, comandos y configuración para Gemini
+	@node tools/ops.js automation install . gemini
+
+install-antigravity: ## Instala el plugin Cauce para Antigravity CLI
+	@node tools/ops.js automation install . antigravity
+
+doctor-claude: ## Diagnostica la instalación de Claude
+	@node tools/ops.js automation doctor . claude
+
+doctor-codex: ## Diagnostica la instalación de Codex
+	@node tools/ops.js automation doctor . codex
+
+doctor-gemini: ## Diagnostica la instalación de Gemini
+	@node tools/ops.js automation doctor . gemini
+
+doctor-antigravity: ## Diagnostica la instalación de Antigravity CLI
+	@node tools/ops.js automation doctor . antigravity

package/template/README.md

@@ -0,0 +1,21 @@
+# {{PROJECT_NAME}} Ops
+
+Sistema de intención, ejecución y memoria del proyecto. Empieza en `planning/FLOW.md` y configura las
+raíces de código en `ops.config.json`.
+
+```bash
+node tools/ops.js check planning
+node tools/ops.js tree planning
+node tools/ops.js context planning
+node tools/ops.js team check product-development
+```
+
+- `organization/`: contexto estable de producto y negocio.
+- `agents/roles/`: cargos de IA reutilizables; cada agente lee el contexto de `organization/`.
+- `agents/workflows/`, `agents/coordinators/` y `agents/specialists/`: categorías extensibles para otros tipos de agentes.
+- `teams/`: composiciones de varios agentes y sus handoffs.
+- `planning/`: roadmap, cola aprobada, trabajo en vuelo, evidencia e historial.
+- `AGENTS.md`: límites de autonomía y acciones que requieren una persona.
+- `integrations/`: adaptadores externos, snapshots y borradores curables.
+
+Modo instalado: `{{MODE}}`.

package/template/automatization/AGENTS.md

@@ -0,0 +1,67 @@
+# automatization/ — reglas del wiring de agentes
+
+Este archivo gobierna cualquier cambio dentro de `automatization/`. La constitución general del proyecto
+está en `../AGENTS.md`; la especificación del proceso está en `../planning/PROTOCOL.md`. Este directorio
+implementa y conecta ese proceso con runners concretos: no redefine producto, prioridades ni estado.
+
+## Mapa y fuentes de verdad
+
+| Ruta | Responsabilidad |
+|---|---|
+| `hooks/` | Entradas estables; la lógica vive en `.ops/engine/hooks/run.js`. |
+| `workflows/` | Recorridos portables; las fases pertenecen a `planning/PROTOCOL.md`. |
+| `runners/` | Adaptadores que declaran su contrato en `manifest.json`. |
+
+Los archivos instalados bajo `.claude/`, `.codex/`, `.gemini/` o `.agents/` son destinos materializados.
+Nunca se convierten en una segunda fuente de verdad: se cambia primero `automatization/` y se reinstala con
+`ops automation install` o el alias de `make` correspondiente.
+
+## Invariantes de cambio
+
+- Mantén el proceso agnóstico al runner. Si una fase cambia, actualiza `planning/PROTOCOL.md` y su workflow
+  en el mismo cambio; un adaptador solo traduce eventos, rutas y formatos.
+- Mantén los guards deterministas y sin red. Un wrapper `guard-*.sh` solo delega al motor compartido; no
+  copies lógica de seguridad entre runners.
+- Declara capacidades reales. No anuncies hooks, workflows, instrucciones o checkpointing que la herramienta
+  no ejecute de forma nativa; documenta cualquier degradación.
+- Conserva configuraciones existentes al instalar. No sobrescribas archivos divergentes ni preferencias,
+  permisos, secretos o autenticación del usuario.
+- Las integraciones son generales. Los workflows reciben `provider`; Jira es un adaptador, no una dependencia
+  del núcleo ni del workflow base.
+- Toda acción remota, publicación, deploy, escritura en un proveedor o uso de credenciales sigue necesitando
+  la autorización definida en `../AGENTS.md`.
+
+## Contrato de un runner
+
+Cada `runners/<nombre>/` debe incluir `README.md` y `manifest.json`, declarar el ejecutable usado, configuración,
+instrucciones, artefactos y capacidades, y proporcionar archivos fuente válidos para todos sus destinos.
+
+Al añadir o cambiar un runner:
+
+1. Usa las rutas y el protocolo vigentes documentados oficialmente por la herramienta.
+2. Traduce su entrada y salida al motor compartido cuando sus eventos tengan otro schema.
+3. Añádelo al registro del CLI, a los aliases de instalación/doctor y a la documentación general.
+4. Prueba una operación permitida y al menos un bloqueo real; no basta validar que el JSON parsea.
+
+Antigravity (`agy`) es el runner Google recomendado para cuentas individuales y proyectos nuevos. Gemini CLI
+se mantiene como adaptador separado para Enterprise, Google Cloud y API keys mientras continúe soportado. No
+mezcles sus rutas: Antigravity usa personalizaciones de workspace en `.agents/`; Gemini usa `.gemini/`.
+
+## Verificación obligatoria
+
+Antes de cerrar un cambio en este directorio ejecuta:
+
+```bash
+node tools/ops.js automation check .       # instancia generada
+node engine/cli/ops.js automation check .  # desarrollo del toolkit
+```
+
+En el toolkit ejecuta además `node --test test/hooks.test.js test/runners.test.js test/workflows.test.js`. Si
+cambia instalación o materialización, valida `ops init` en un directorio temporal, instala el runner y ejecuta
+`automation doctor`. No autentiques una cuenta ni llames servicios externos para probar el wiring.
+
+## Límites
+
+No edites `planning/BACKLOG.md`, `WIP.md` o `DONE.md` desde hooks o instaladores. No hagas que `ops init` active
+un runner silenciosamente. No agregues lógica de negocio, nombres de servicios de un proyecto, tokens, rutas
+personales ni modelos concretos a esta capa reusable.

package/template/automatization/README.md

@@ -0,0 +1,19 @@
+# Automatización de {{PROJECT_NAME}}
+
+Wiring local entre `planning/PROTOCOL.md` y el runner elegido. El proyecto empieza en modo manual y seguro;
+activar un runner requiere completar su adaptador bajo `runners/`.
+
+- `config.json`: runner activo y gates requeridos.
+- `hooks/`: implementaciones específicas del runner.
+- `workflows/`: recorridos específicos del runner.
+- `runners/`: instalación y configuración por herramienta.
+
+No copies reglas del protocolo aquí: enlázalas y mecaniza únicamente lo comprobable.
+
+```bash
+node tools/ops.js automation check .
+node tools/ops.js automation install . codex
+```
+
+También puede usarse `make install-claude`, `make install-codex` o `make install-gemini`.
+Valida después con `make doctor-claude`, `make doctor-codex` o `make doctor-gemini`.

package/template/automatization/config.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "runner": "manual",
+  "protocol": "planning/PROTOCOL.md",
+  "gates": {
+    "destructiveCommands": true,
+    "secrets": true,
+    "integrationSnapshots": true,
+    "verifyBeforeCommit": true,
+    "validateOnStop": true,
+    "humanCheckpointBetweenMilestones": true
+  }
+}

package/template/automatization/hooks/.gitkeep

@@ -0,0 +1 @@
+

package/template/automatization/runners/README.md

@@ -0,0 +1,13 @@
+# Runners
+
+Esta instancia incluye adaptadores instalables para Claude, Codex, Antigravity y Gemini, pero ninguno se
+activa automáticamente. Antigravity (`agy`) es la opción Google recomendada para cuentas individuales y
+proyectos nuevos. Gemini se conserva para Enterprise, Google Cloud y API keys.
+
+```bash
+make install-antigravity
+make doctor-antigravity
+```
+
+Usa el alias equivalente para otro runner. La instalación conserva configuración existente y `doctor`
+comprueba archivos y disponibilidad del CLI sin autenticarse.

package/template/automatization/workflows/.gitkeep

@@ -0,0 +1 @@
+

package/template/integrations/AGENTS.md

@@ -0,0 +1,14 @@
+# integrations/ — reglas para sistemas externos
+
+`config.json` registra proveedores y cada subcarpeta contiene configuración no secreta, staging y
+propuestas. La conexión y normalización viven en `.ops/engine/integrations/`; no implementes clientes de API
+dentro de esta carpeta.
+
+Toda integración se considera de solo lectura. `writeback-plan` solo calcula intención y nunca autoriza ni
+ejecuta una escritura. No guardes tokens, headers, cookies ni credenciales en configuración o staging.
+
+No edites `remote.json` ni `sync-state.json`: pertenecen al sincronizador. Cura `draft.md` y
+`proposed/*.md`, valida y usa las operaciones explícitas de reconciliación. Una lectura parcial o fallida no
+autoriza limpieza de staging.
+
+Las promociones son locales y llegan únicamente a `planning/roadmap/`; nunca modifican BACKLOG, WIP o DONE.

package/template/integrations/README.md

@@ -0,0 +1,21 @@
+# Integraciones de {{PROJECT_NAME}}
+
+Los proveedores se registran en `config.json`. Todos siguen el ciclo:
+
+```text
+API externa (lectura) → staging tipado → draft.md → review/reconcile → planning/roadmap
+```
+
+`remote.json` es evidencia remota; `draft.md` es curación local. Nunca guardar secretos aquí.
+
+```bash
+node tools/ops.js integration list .
+node tools/ops.js integration check .
+node tools/ops.js integration sync . jira
+node tools/ops.js integration writeback-plan . jira
+node tools/ops.js integration promote . jira KEY-123
+```
+
+El motor compara base reconciliada, remoto actual y curación local. Usa `reset` para adoptar el remoto,
+`reconcile` para conservar la edición local sobre la nueva base y `rebase` para reparar hashes mecánicos.
+Ninguno de esos comandos escribe en el proveedor.

package/template/integrations/config.json

@@ -0,0 +1,10 @@
+{
+  "schemaVersion": 1,
+  "providers": {
+    "jira": {
+      "adapter": "jira",
+      "enabled": false,
+      "config": "jira/config.json"
+    }
+  }
+}

package/template/integrations/jira/README.md

@@ -0,0 +1,59 @@
+# Jira — sincronización y curación de solo lectura
+
+## Activación
+
+1. Cambia `enabled` a `true` aquí y en `../config.json`.
+2. Configura `baseUrl` y `jql`.
+3. Exporta las variables nombradas en `auth`; no pegues valores en JSON.
+4. Ejecuta `integration check` y luego `integration sync`.
+
+La búsqueda JQL tiene timeout, límite de páginas y detección de ciclos. Basic auth usa email y API token;
+Bearer también está soportado. `candidateAssigneeEnv` es opcional: si se configura, solo las incidencias cuyo
+`accountId` coincida son candidatas; las demás son contexto y su draft se regenera siempre.
+
+## Staging y promoción
+
+Cada incidencia aparece en `staging/<tipo>/KEY/`, donde el tipo puede ser `epics`, `stories`, `tasks`,
+`subtasks` o `items`:
+
+```text
+KEY/
+├── remote.json  # remoto actual + base reconciliada
+└── draft.md     # curación local
+```
+
+Edita únicamente el draft:
+
+- `state: ready` cuando esté curado.
+- `service`: ruta responsable.
+- `promotionKind: epic|story`.
+- Para story: `promotionEpic: NNN` y `promotionCriteria: C1`.
+
+Después ejecuta `integration check` e `integration promote`. Nada entra directamente al BACKLOG.
+
+## Conflictos y reconciliación
+
+```bash
+node tools/ops.js integration reset . jira KEY-123
+node tools/ops.js integration rebase . jira KEY-123
+node tools/ops.js integration reconcile . jira KEY-123
+```
+
+- `reset`: descarta curación y adopta Jira.
+- `rebase`: recalcula la base mecánica sin cambiar el draft.
+- `reconcile`: acepta el remoto actual como base y conserva la curación como salida pendiente.
+
+Tras una lectura completa, los items intactos ausentes se limpian. Los curados, `ready` o promovidos se
+conservan con `missingFromRemote: true`.
+
+## Propuestas y write-back
+
+`proposed/*.md` representa items que todavía no existen en Jira. Una propuesta aprobada exige tipo,
+servicio, estimación y, salvo una épica, un padre presente en staging.
+
+```bash
+node tools/ops.js integration writeback-plan . jira
+```
+
+El plan combina curaciones salientes y propuestas, bloqueando contextos, ausentes y conflictos. No ejecuta
+red. `writeBack` debe permanecer `false`: no existe un ejecutor remoto aprobado.