Acciones predefinidas: acciones.json y el motor

Esta parte es la que te pertenece: el esquema es la especificación de tu herramienta. Si se lo pides a la IA, tendrás la herramienta de otra persona. OpenCode, cerrado. Crea acciones.json en la raíz del repo partiendo de este ejemplo:

Campo a campo

Tipos de acción

Filtros: qué ficheros se tocan

Dentro de filtro. Si pones varios, el fichero tiene que cumplirlos todos.

Plantillas de nombre

Para renombrar. Son huecos entre llaves que el motor rellena con el formato de Python (str.format): lo de detrás de los dos puntos es el formato.

Si en cada prompt tuvieras que pegar tu esquema entero, acabarías harto y, peor, una vez se te olvidaría. Para eso existen las skills: un fichero Markdown con conocimiento concreto (cómo es tu acciones.json y qué reglas sigue el código que lo lee) que el agente carga cuando lo necesita.

Antes de crearla, el mapa de lo que puedes poner en tu repo para personalizar a OpenCode:

Crea la carpeta .opencode/skills/acciones-json/ y dentro el fichero SKILL.md (en mayúsculas) con este contenido. Adáptalo a tu esquema si has cambiado campos:

• Lo de arriba entre --- es el frontmatter. name tiene que ser igual que el nombre de la carpeta (acciones-json), en minúsculas y con guiones.
• description es lo más importante: el agente solo ve el nombre y la descripción de cada skill, y con eso decide si la carga. Por eso dice qué es y, sobre todo, cuándo usarla («siempre que crees o cambies acciones o el código que las lee»). Sin descripción, la skill no le llega al modelo.
• Cuando la tarea encaja, el agente llama a su herramienta skill y entonces sí lee el fichero entero. Así no gasta contexto con tu esquema cuando le pides otra cosa.
• La última regla es para el agente y para ti: si el esquema cambia, la skill cambia. Una skill desactualizada enseña mal.

Compruébalo. OpenCode no recarga la configuración en caliente: sal (ctrl+c) y vuelve a abrirlo en la carpeta del repo. Escribe /skills: tiene que aparecer acciones-json. Desde la terminal también puedes verlo con opencode debug skill.

Un programa que borra ficheros no puede fiarse de un JSON escrito a mano. Primero se comprueba todo el fichero y solo si está bien se toca el disco. Y cuando algo falla, el mensaje tiene que decir qué acción y qué campo: «Error en la configuración» no sirve; «Acción «renombrar-fotos», campo «plantilla»: es obligatorio en acciones de tipo renombrar» te lo arregla en 10 segundos.

Abre una sesión nueva (/new) y pasa al agente plan con Tab. Fíjate en lo corto que es el prompt: @acciones.json adjunta tu fichero y la skill pone el resto.

Carga la skill acciones-json y lee @acciones.json.
Quiero validar acciones.json ANTES de ejecutar nada:
- src/tareas/errores.py con TareasError, ConfigError y AccionNoValida;
- src/tareas/config.py con cargar(ruta) -> list[dict];
- la orden «tareas validar» en src/tareas/cli.py.
No toques nada todavía: dime qué ficheros crearías o cambiarías, qué clases
y funciones tendrán y qué casos de error vas a detectar.

Lee el plan. ¿Ha entendido tu esquema? ¿Se olvida de algún caso (nombre repetido, regex rota)? Corrígelo ahí mismo. Cuando el plan te convenza, Tab para pasar a build:

Hazlo según el plan. Criterio de aceptación:
- TareasError (codigo_salida = 1), ConfigError (codigo_salida = 3) y
  AccionNoValida(accion, campo, motivo) → «Acción «X», campo «Y»: motivo».
- JSON roto → ConfigError con línea y columna.
- Cada mensaje dice QUÉ acción y QUÉ campo fallan, en español.
- «tareas validar»: «✔ N acciones válidas» en verde, o el error en rojo
  SIN traceback y saliendo con e.codigo_salida.
Solo esos tres ficheros, sin dependencias nuevas.
Termina ejecutando: uv run tareas validar

Con tu opencode.json de la Sesión 1, cada edición te pide permiso: lee el diff antes de aceptar. uv run tareas validar sí lo puede ejecutar solo, porque está en tu lista de órdenes permitidas.

Para auditar, esto es lo que deberías obtener. Las excepciones heredan unas de otras: la CLI capturaTareasError una sola vez y cada error trae su código de salida.

Y así es, resumido, config.py. No lo copies: es la referencia para comparar con lo que te haya hecho el agente.

Prueba la orden y su código de salida (en tu terminal, o desde OpenCode con ! delante):

Casos feos que pruebas TÚ

Haz una copia (pruebas/roto.json), estropéala a propósito de cada una de estas formas y ejecuta uv run tareas --config pruebas/roto.json validar. Ninguno puede acabar en traceback. Si alguno falla, explícaselo al agente con el mensaje que has visto, no con «no va».

Aquí aparecen las clases de verdad. Una clase base Accion define lo que toda acción sabe hacer (ejecutar) y cada subclase (Mover, Copiar, Renombrar,Borrar) solo implementa lo suyo en aplicar. El método estático Accion.desde_config(dict) es una fábrica: recibe un diccionario del JSON y devuelve el objeto de la clase que toca. Gracias a eso, el motor no tiene ni un if tipo == …: añadir un tipo nuevo es escribir una subclase más.

El Motor recibe la carpeta de la orden (o el origen de la acción), selecciona los ficheros que cumplen el filtro y se los pasa a la acción, que devuelve un informe: una lista deResultado (qué fichero, a qué destino, en qué estado).

Sesión nueva (/new). Primero en plan: «Carga la skill acciones-json y explícame cómo harías acciones.py y motor.py: clases, métodos y cómo garantizas que --simular no toca el disco». Cuando el plan te cuadre, en build:

Carga la skill acciones-json. Crea src/tareas/acciones.py y src/tareas/motor.py:
1. acciones.py: dataclass Resultado(origen, destino, estado: hecho | simulado | saltado);
   clase base abstracta Accion con ejecutar(ficheros, simular) y aplicar(fichero, n, simular)
   abstracto; fábrica Accion.desde_config(dict) con un registro de subclases (nada de
   if/elif por tipo); subclases Mover, Copiar, Renombrar y Borrar (destructiva = True).
2. motor.py: clase Motor(acciones) con seleccionar(carpeta, filtro) y
   ejecutar(nombre, carpeta, simular) -> list[Resultado]. Sin carpeta, usa "origen".
   Acción o carpeta inexistente → TareasError con mensaje humano.
Con simular=True no se toca NADA del disco (ni mkdir). Nunca sobrescribir: sufijo « (1)».
No toques cli.py y NO ejecutes ninguna acción: las pruebo yo.
Al terminar, dime qué pasa si ejecuto dos veces seguidas la misma acción de mover y por qué.

Código de referencia resumido para auditar:

La interfaz: acciones, ejecutar, --simular, --si y --config

La CLI es la capa fina que une todo. Tres piezas nuevas:

• tareas acciones: tabla con nombre, tipo y descripción de lo que hay en acciones.json.
• tareas ejecutar NOMBRE [CARPETA] --simular --si: la orden que hace el trabajo.
• --config RUTA: opción global (va antes de la orden: tareas --config otra.json acciones). Por defecto, ./acciones.json.

Sesión nueva, plan y luego build con:

Amplía SOLO @src/tareas/cli.py (Typer + Rich). Ya existen config.cargar, Motor y las Accion.
1. Opción global --config RUTA en @app.callback (por defecto ./acciones.json), guardada en ctx.obj.
2. «tareas acciones»: tabla Rich con nombre, tipo y descripción.
3. «tareas ejecutar NOMBRE [CARPETA] --simular --si»:
   - --simular: tabla «fichero → destino» con estado «simulado», sin tocar nada;
   - acción destructiva sin --simular ni --si → typer.confirm(..., abort=True);
   - resumen final: N hechos, N simulados, N saltados; si ningún fichero cumple el filtro, dilo.
4. Códigos de salida: 0 bien · 1 TareasError · 2 uso (Typer) · 3 ConfigError.
   Nunca un traceback ante errores previsibles: mensaje en rojo y typer.Exit(e.codigo_salida).
No toques acciones.py ni motor.py. Termina con: uv run tareas --help

El fragmento clave de cli.py: fíjate en cómo se captura una sola excepción base para todo.

Lo que deberías ver (fíjate en el sufijo « (1)»: ya había una factura.pdf en el destino):

$ uv run tareas ejecutar ordenar-descargas ~/pruebas-tareas/Descargas --simular
              ordenar-descargas (SIMULACIÓN: no se ha tocado nada)
┏━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┓
┃ Fichero               ┃ Destino                                 ┃ Estado   ┃
┡━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━┩
│ apuntes de redes.docx │ ~/Documentos/PDF/apuntes de redes.docx  │ simulado │
│ factura.pdf           │ ~/Documentos/PDF/factura (1).pdf        │ simulado │
└───────────────────────┴─────────────────────────────────────────┴──────────┘
2 ficheros · 0 hechos · 2 simulados · 0 saltados
Para hacerlo de verdad, repite la orden sin --simular.

Linux y macOS (bash/zsh)

Windows (PowerShell)

Añadir una acción siempre sigue los mismos pasos: proponer el JSON, revisarlo, validar y probar con --simular. Cuando repites un prompt, lo conviertes en un comando personalizado: un fichero Markdown en .opencode/commands/ que se invoca con / y su nombre. Crea .opencode/commands/nueva-accion.md:

• El nombre del fichero es el nombre del comando: nueva-accion.md → /nueva-accion.
• Frontmatter: description es lo que ves en la lista al escribir /; agent: build hace que se ejecute con el agente que puede editar (igualmente te pedirá permiso para cada cambio).
• $ARGUMENTS se sustituye por todo lo que escribas detrás del comando.
• !`git status --short` ejecuta esa orden en la raíz del repo antes de enviar el prompt y mete su salida: el agente sabe qué ficheros tienes sin guardar.
• El paso 2 del comando («propón primero la entrada JSON y espera mi visto bueno») es el que mantiene la decisión en tus manos.

Sal de OpenCode, vuelve a abrirlo y úsalo para tu 2.ª acción:

Lee la entrada JSON que te propone: ¿el filtro coge solo las capturas? ¿La plantilla es la que tú quieres? ¿El destino está en ~/pruebas-tareas mientras pruebas? Corrige lo que no te guste antes de dar el visto bueno. Al final te dirá qué orden con --simular debes probar: la ejecutas tú. Repite con tu 3.ª acción (una idea tuya, no un ejemplo de esta página).

El agente que escribe el código no es el mejor para revisarlo: ya está convencido de que está bien. Un subagente es otro agente, con su propio prompt y sus propios permisos, que trabaja en una conversación aparte y devuelve el resultado. Crea .opencode/agents/revisor.md:

• El nombre del fichero es el nombre del agente: revisor.md → @revisor.
• mode: subagent: no aparece al cambiar con Tab (eso es para plan y build); se le llama con @revisor, o el agente principal lo lanza si su description encaja con lo que necesita.
• permission: edit: deny y webfetch: deny lo dejan en solo lectura; de bash solo puede usar git diff, git log y git status; cualquier otra orden está bloqueada ("*": deny va primero y las excepciones después: gana la última regla que coincide). Aunque quisiera, no puede «arreglarte» nada ni ejecutar tus acciones.
• temperature: 0.1 pide respuestas poco creativas (un revisor tiene que ser previsible), si el modelo del centro la admite; si no, se ignora sin romper nada.
• El cuerpo es su prompt de sistema: qué revisar y en qué formato responder.

Sal, vuelve a abrir OpenCode (en la terminal, opencode agent list debe mostrar revisor) y pídele:

Además, OpenCode trae /review, que revisa los cambios sin commitear. La rutina a partir de hoy: antes de cada commit de código, /review o @revisor.

Un ADR (Architecture Decision Record, registro de decisión de arquitectura) es un documento corto que cuenta una decisión técnica importante: qué decidiste, por qué y qué alternativas descartaste. Se escribe para la persona que llegue dentro de seis meses (muchas veces, tú mismo) y se pregunte «¿por qué narices está hecho así?». Los equipos profesionales los guardan numerados en docs/adr/ y no se borran: si cambias de opinión, escribes uno nuevo que sustituye al anterior.

Tu primera decisión de arquitectura es la de esta semana. Crea docs/adr/0001-configuracion-externa.md con esta plantilla y termínala con TUS razones (los huecos [...]).

Puedes usar al agente en plan (no puede editar) como abogado del diablo: «Lee @docs/adr/0001-configuracion-externa.md y dame 3 argumentos en contra de mi decisión y una alternativa que no haya considerado». Pero el texto final es tuyo: en la defensa te preguntaré por él.

«Lo que no sabes explicar, no lo entregas». Antes de dar por buena cada acción, pasa esta auditoría en~/pruebas-tareas:

Prueba en otro sistema si puedes. En el aula tienes Linux; si en casa usas Windows o macOS, clona el repo allí y repite los bloques de prueba del paso 4. Los fallos típicos aparecen aquí: rutas con \, tildes que salen como ñ (falta encoding="utf-8") o colores raros en una consola antigua. Cada fallo que encuentres y arregles es un commit con historia.

Un commit por pieza, hecho por ti (el agente no hace commits ni push: lo dice tu AGENTS.md y lo bloquea tu opencode.json). Los ficheros de .opencode/ también se commitean: son parte de tu proyecto. Algo así, con tus palabras:

Y en docs/prompts.md, los prompts de la validación, del motor y de la CLI, con una línea por prompt de qué tuviste que corregir de lo que hizo el agente y qué te señaló el revisor. Es la prueba de que auditaste.