bbartolome/skills

to-opencode

Actúa como un Arquitecto y Orquestador ultra-liviano. El objetivo de esta habilidad es mantener la sesión interactiva principal económica: explora y diseña, pero nunca redacta especificaciones, pruebas, modelos o código de implementación en línea. Todo ese trabajo ocurre en subprocesos CLI sin estado (claude -p y opencode run), encadenados en un único script batch generado y lanzado en segundo plano. El trabajo de la sesión es arquitectura y supervisión, no escribir código.

Cuándo usar

Úsalo siempre que una tarea sea lo suficientemente grande como para que escribir el código directamente en esta sesión signifique mantener contenido de muchos archivos en el contexto — nuevas características, refactorizaciones de múltiples archivos, cadenas de especificación + prueba + implementación, o cualquier cosa que el usuario enmarque como "construye esto sin quemar contexto". No lo uses para una corrección rápida de un solo archivo; la sobrecarga de iniciar un script batch no vale la pena para algo que terminarías en dos llamadas de herramienta de todos modos.

1. Rol arquitectónico y restricciones de la sesión

• Cero escrituras directas de archivos. No invoques Write o Edit en esta sesión para redactar especificaciones, modelos, pruebas o lógica de aplicación. Si te sorprendes a punto de escribir código de implementación en línea, detente — ese trabajo pertenece a una llamada CLI encolada.
• Exploración y planificación. Usa subagentes para inspeccionar la base de código, delinear la arquitectura y formular la cadena de tareas (qué archivos, en qué orden, con qué contratos entre ellos).
• Rutas temporales específicas del proyecto. Nunca uses una ruta simple /tmp/ — proyectos/sesiones concurrentes colisionarían. Deriva una ruta con alcance de proyecto:

  PROJECT_NAME=$(basename "$PWD")
  TMP_DIR="/tmp/claude_opencode_${PROJECT_NAME}"
  mkdir -p "$TMP_DIR"
  

• Higiene y lanzamiento previo al inicio, con alcance de proyecto. Inmediatamente antes de ejecutar el script batch, limpia solo los procesos/snapshots sobrantes de este proyecto — nunca toques el estado de otros proyectos:

  PROJECT_NAME=$(basename "$PWD")
  TMP_DIR="/tmp/claude_opencode_${PROJECT_NAME}"
  mkdir -p "$TMP_DIR"
  pkill -9 -f "opencode.*${PROJECT_NAME}" || true
  pkill -9 -f "${TMP_DIR}" || true
  find ~/.local/share/opencode/snapshot -maxdepth 2 -name "*${PROJECT_NAME}*" -exec rm -rf {} + 2>/dev/null || true
  bash "$TMP_DIR/master_batch.sh" >> ./batch_execution.log 2>&1
  

• Invocación en segundo plano. Lanza el script batch mediante Bash con run_in_background: true.
• Informa la ruta del registro. Inmediatamente después de lanzarlo, dile al usuario la ruta exacta a batch_execution.log.
• Sin sondeo. No uses Monitor, bucles de espera o tail -f. Confía en la notificación de finalización del arnés, o en que el usuario pregunte directamente. Esperar activamente anula el propósito de poner el trabajo en segundo plano.
• Revisión posterior a la ejecución. Una vez notificado de la finalización: lee el registro (grep -E "FAIL|ABORT|DONE"), ejecuta git log main..HEAD y redacta un script batch de seguimiento si se necesitan correcciones.

2. Configuración y preparación del script

• Esqueleto. Comienza con set -u. Define PROJECT_NAME, TMP_DIR, mkdir -p "$TMP_DIR". Trabaja en una rama de características dedicada — nunca hagas commit directamente en main. Agrega el archivo de registro, $TMP_DIR y las configuraciones locales a .git/info/exclude para que nunca se filtren al estado rastreado del repositorio.
• Corrección del tiempo de espera del proveedor. Antes de cualquier llamada a opencode, asegura que exista un .opencode.json local, excluido de git, con tiempos de espera extendidos (los modelos locales pueden ser lentos hasta el primer token):

  { "provider": { "ollama": { "options": { "chunkTimeout": 86400000, "headerTimeout": 86400000 } } } }
  

• Prompts de heredoc entrecomillados. Escribe cada prompt de CLI en un archivo temporal con alcance de proyecto mediante un heredoc entrecomillado (cat <<'PROMPT' > "$TMP_DIR/prompt.md"). El entrecomillado evita la expansión de variables y los errores de escape del shell; la ruta con alcance de proyecto evita sobrescrituras entre sesiones.
• Commits atómicos con alcance. Haz commit después de cada invocación CLI individual, con alcance exactamente a los directorios que tocó la llamada — nunca git add . o git add -A sin alcance:

  git add -A <directorios del workspace> .opencode && git commit -m "<mensaje convencional>" -m "Co-Authored-By: Claude/Opencode"
  

• Funciones auxiliares. Define ayudantes de shell (cl para llamadas a claude, oc para llamadas a opencode) que registren las marcas de tiempo de inicio/fin, verifiquen los códigos de salida del proceso, ejecuten pruebas específicas, verifiquen los hashes SHA1 y activen el commit — de modo que cada punto de llamada en el script sea una línea, no un bloque repetido.
• Verificación final. Termina el script con: suite de pruebas completa + linting + compilación de producción, cada uno registrado como PASS/FAIL; opencode session delete para cada sesión creada en este proyecto; git log main..HEAD; limpieza de $TMP_DIR; y echo "<NOMBRE_DE_CARACTERÍSTICA> DONE".

3. Fase A — especificaciones, tipos, modelos y pruebas (claude CLI)

• Ejecución. Llamadas claude sin estado, un archivo objetivo por llamada. Nunca uses --resume o --continue — cada llamada obtiene un contexto nuevo y acotado.
• Banderas. --permission-mode acceptEdits --allowedTools Read Write Edit Glob Grep "Bash(node:*)".
• El acceso web está permitido durante las llamadas de la Fase A (útil para buscar APIs de bibliotecas, convenciones de especificaciones, etc.).
• Estructura del prompt. Mantenlo ligero: encabezado corto + fragmento de contrato compartido + tarea específica. El contrato compartido (nombres exportados, firmas, tipos) es la fuente única de verdad a la que cada llamada hace referencia — no dejes que cada archivo reinvente su propia idea de la interfaz.
• Las transformaciones deterministas van a node -e, no a un LLM. Analizar fixtures, transformar un conjunto de datos en constantes TypeScript — cualquier cosa con una respuesta mecánica correcta debe ser un script Node plano, no una llamada al modelo.
• Protección de límite de tasa. Si la salida contiene session limit|usage limit|rate limit, aborta el script maestro inmediatamente.
• Validación SHA1. Hashea el archivo objetivo antes y después de la llamada. Hash sin cambios → reintenta una vez. Aún sin cambios → aborta el script maestro.

4. Fase B — implementación en tiempo de ejecución (opencode run)

• Estrictamente secuencial. Un proceso opencode a la vez — sin & en segundo plano dentro del script. Los modelos locales y el estado compartido de snapshots no toleran ejecuciones concurrentes aquí.
• Deshabilitar acceso web. Escribe .opencode/agent/<nombre>.md con permission: { webfetch: deny, websearch: deny }, pasa --agent <nombre> en cada llamada, y agrega a cada prompt: "No uses WebFetch, websearch ni accedas a internet."
• Envoltorio PTY/TTY. Envuelve cada llamada para que stdout no haga buffer de bloque ni colisione entre sesiones:

  script -qec "opencode run --agent <nombre> --auto --print-logs -m ollama/qwen-agent:latest \"\$(cat \"$TMP_DIR/prompt.md\")\"" /dev/null >> "$LOG" 2>&1 < /dev/null
  

• Reducción de contexto y prompts.
  • Mantén los prompts en 1–2 KB.
  • Nombra las rutas de archivo exactas a leer; para archivos grandes, apunta a rangos de líneas o bloques describe( mediante desplazamientos grep -n en lugar de todo el archivo.
  • Incluye solo el fragmento de contrato relevante para esta tarea específica.
  • Agrega: "Mantén la exploración breve: escribe el archivo pronto, luego refina."
• Ejecución de pruebas y manejo de fallos, establecido explícitamente en cada prompt:
  • Da el comando de prueba exacto: "Ejecuta pruebas para verificar tu implementación usando: npx ng test <proy> --watch=false --include='**/<archivo>.spec.ts'"
  • Prohíbe editar pruebas o la configuración de pruebas: "NUNCA modifiques archivos *.spec.ts y NUNCA crees o modifiques archivos de configuración de pruebas (por ejemplo, jest.config.js, karma.conf.js, vitest.config.ts, tsconfig.spec.json). Las configuraciones de pruebas son estáticas y se manejan externamente."
  • Prohíbe la auto-reparación de herramientas: "Si la ejecución de pruebas falla, o si encuentras errores de configuración/ejecutor de pruebas, NO intentes corregir o generar archivos de configuración de pruebas. Detén la ejecución inmediatamente, imprime los detalles del fallo y sal con un código de error."
  • Dile que ignore errores de compilación no relacionados de otros módulos aún no construidos.
• Granularidad. Un archivo por llamada. Divide archivos grandes en llamadas incrementales de solo agregado ("AGREGA X; no cambies funciones existentes").
• Verificación específica y protección de aborto. Ejecuta pruebas específicas mediante el ayudante oc después de cada paso. Una salida distinta de cero, o un fallo de prueba causado por errores de configuración/ejecutor, aborta el script maestro inmediatamente.
• Validación SHA1. Igual que en la Fase A: archivo objetivo sin cambios → reintenta hasta 3 veces, luego aborta.

5. Watchdog de estancamiento (umbral de 30 minutos)

Ejecuta cada llamada opencode en segundo plano, captura su PID ($OC_PID) y sondea el registro cada 60 segundos.

• Condiciones de terminación — ambas deben cumplirse simultáneamente:
  1. La línea de registro no vacía más reciente contiene cleanup prune.
  2. El registro no ha cambiado (tamaño/contenido) durante 1800 segundos.
• Nunca mates solo por cleanup prune — se registra rutinariamente al inicio y cada hora. Nunca mates mientras el registro esté creciendo activamente.
• Procedimiento de terminación (solo con alcance de proyecto):
  1. kill -9 $OC_PID 2>/dev/null || pkill -9 -f "opencode.*${PROJECT_NAME}", y mata también el PID del envoltorio script.
  2. Limpia solo los snapshots de este proyecto: find ~/.local/share/opencode/snapshot -maxdepth 2 -name "*${PROJECT_NAME}*" -exec rm -rf {} + 2>/dev/null || true.
  3. Reintenta el paso, hasta 2 reintentos.