Mapa de habilidades

Kodavio no es solo un conector MCP. Es una capa de trabajo para que Codex pueda entender un sitio WordPress, operar con sus builders y hacer cambios de forma controlada. Las habilidades estan agrupadas por dominio para que sepas cuando pedir una lectura, cuando pedir un plan y cuando autorizar una escritura real.

Diagnostico del sitio

Estas habilidades sirven para entender donde estas antes de tocar nada.

Usalas al empezar una conversacion nueva, al cambiar de sitio o antes de editar una pagina que no conoces.

Sistema de diseno

El sistema de diseno gira alrededor de design.md. Codex lo usa como memoria para mantener coherencia visual entre paginas, builders y frameworks.

El objetivo no es copiar cualquier variable que exista. El objetivo es convertir el estado visual del sitio en una memoria limpia, reutilizable y comprensible para un agente.

Desde 0.1.2, las escrituras de tokens son mas estrictas:

• Una operacion normal solo debe tocar un grupo de tokens.
• Si el agente intenta escribir colores, tipografia, spacing y sombras a la vez, Kodavio lo bloquea salvo que se pase allow_multi_group_theme_write=true.
• replace requiere allow_replace=true porque puede eliminar tokens existentes.
• Para WindPress/Tailwind, anadir colores semanticos significa localizar la fuente real del tema, parchear variables concretas y recompilar/verificar utilidades, no regenerar un tema completo.
• Si no esta claro donde vive la configuracion activa, Codex debe leer primero entradas como main.css, archivos Tailwind/WindPress detectados, variables CSS y memoria design.md, y devolver un plan antes de escribir.

Scope del proyecto

scope.md complementa design.md. Mientras design.md define como se ve el sitio, scope.md define que hay que construir: sitemap, plugins, objetivos, integraciones, formularios, backlog y fases.

Usalo cuando:

• el sitio empieza desde cero;
• quieres que Codex planifique sitemap y plugins antes de crear paginas;
• hay que auditar un sitio existente y proponer mejoras;
• quieres que el agente tenga memoria de negocio y no solo memoria visual.

Primeras abilities: kodavio/scope-read, kodavio/scope-plan-new-site, kodavio/scope-import-from-site, kodavio/scope-gap-analysis, kodavio/site-build-plan y kodavio/site-build-next-step.

Builders y contenido visual

Kodavio puede trabajar con Bricks, Elementor y Gutenberg desde contratos seguros. Tambien puede analizar una pagina en un builder y materializarla en otro mediante un modelo semantico intermedio.

La responsabilidad creativa es del agente. Kodavio/MCP no debe inventar copy ni diseno a partir de un prompt vago; debe explicar que formato necesita el builder y materializar el payload estructurado que Codex ya ha escrito.

kodavio/builder-template-storage-strategy explica donde crear templates/componentes para que una actualizacion del child theme no los pise. Por defecto, Kodavio debe guardar trabajo generado como entidades del builder o contenido de WordPress, no como archivos versionados del tema.

Para conversiones, pide siempre que Codex explique primero la intencion de diseno: secciones, jerarquia, contenido, responsivo, tokens usados, widgets, formularios y partes que no se pueden trasladar automaticamente.

Playbooks del agente

Ademas de las abilities, Kodavio incluye playbooks internos que el agente puede cargar con kodavio/skill-list y kodavio/skill-get. Estos playbooks no escriben nada por si solos: le dicen a Codex como razonar antes de tocar builders, frameworks o plugins complejos.

Playbooks actuales:

• acf-integration
• bricks-build-page
• builder-conversion-advanced
• builder-conversion
• content-model-schema
• design-frameworks
• dynamic-data-binding
• flowtitude-design-scope
• fluent-suite
• gutenberg-build-page
• jetengine-integration
• woocommerce-operations
• wordpress-admin-safe

Para una conversion real de un sitio cliente, lo normal es combinar varios: builder-conversion-advanced, design-frameworks, dynamic-data-binding y despues ACF, JetEngine, Fluent o WooCommerce si aparecen en el sitio.

Crear paginas, templates y patrones

Guardarrailes recientes para Bricks

Kodavio ya no trata la actualizacion de una pagina Bricks existente como "regenera todo" por defecto.

• kodavio/bricks-update-page es una ruta de reemplazo completo y solo debe usarse con update_strategy=replace_full_tree y allow_full_replace=true.
• Para cambios normales, usa kodavio/bricks-tree-read y despues kodavio/bricks-apply-patch.
• Code widgets, HTML opaco, PHP templates y CSS masivo son excepciones. Requieren allow_code_widget=true, una razon clara y explicacion de por que no se puede resolver con nodos nativos.
• Los elementos de texto no son un contenedor para HTML estructural. Si necesitas un h2, section, article, button o layout, Codex debe crear o parchear nodos nativos y cambiar settings.tag cuando aplique, no meter etiquetas dentro de settings.text.
• Si el agente edita una pagina existente, debe preservar secciones validas y devolver el diff: nodos tocados, warnings, verificacion y recuento de elementos.
• Si una maqueta llega como imagen, Codex debe distinguir si es referencia visual o asset final. Como referencia, primero debe proponer estructura, tokens y componentes antes de tocar el builder.

Antes de autorizar una escritura, deberias ver:

• builder elegido y motivo;
• tipo de entidad: page, template, component o pattern;
• estructura de secciones;
• copy, CTAs y jerarquia visual propuestos por el agente;
• elementos/widgets/bloques que usara;
• tokens de design.md aplicados;
• warnings sobre formularios, datos dinamicos o terceros.

Conversion entre builders

El sistema actual evita depender de conversores uno-a-uno para cada pareja. La idea es:

1. Leer la pagina origen.
2. Convertirla a un modelo semantico comun.
3. Crear un plan de materializacion para el builder destino.
4. Generar un borrador nuevo, sin tocar el original.
5. Comparar origen y destino con un diff de fidelidad.
6. Reparar manualmente lo que el modelo marque como delicado.

Esto permite que, cuando se anada otro builder, no haya que escribir un parche aislado para cada combinacion. El nuevo builder debe aportar un adaptador de lectura y otro de escritura al modelo comun.

Exportacion portable

La exportacion crea un contrato dinamico portable para reconstruir paginas o sitios en otro entorno. La primera fase se centra en Bricks y en formularios:

• kodavio/site-export-plan detecta paginas, builders, assets, formularios y bloqueos.
• kodavio/site-export-page exporta una pagina como modelo semantico.
• kodavio/site-export-package crea un paquete JSON en dry_run o lo escribe con confirmacion.

Los formularios Bricks se exportan como contrato seguro: campos, acciones, submit, mensajes y tareas de reconexion. Emails, webhooks y secretos no se copian a ciegas.

Como evaluar una conversion

No midas una conversion solo por "ha creado una pagina". Mide:

Integraciones de terceros

Si otro plugin expone habilidades propias de WordPress, Kodavio puede descubrirlas, leer su metadata y clasificarlas. Eso no significa que deba ejecutarlas automaticamente.

Para plugins complejos como formularios, ecommerce, custom fields o motores de contenido, lo correcto es usar las habilidades de terceros como contrato inspeccionado y crear adaptadores explicitos antes de permitir escrituras reales.

Si tu plugin propio quiere exponer una operacion a Codex, usa el SDK de custom abilities y marca la ability con opt-in explicito para MCP. Asi Kodavio puede descubrirla sin publicar por accidente herramientas internas de otros plugins.

Administracion WordPress

Las habilidades administrativas estan pensadas para ahorrar tiempo sin convertir Codex en un panel de control peligroso.

Ecommerce y analitica

Cuando WooCommerce esta activo, las habilidades de commerce estan pensadas para diagnostico y operaciones acotadas:

• Estado de WooCommerce, moneda, conteos y disponibilidad.
• Listado y lectura segura de productos.
• Actualizacion controlada de precios con dry_run y confirmacion.
• Resumen de pedidos sin datos personales de clientes.
• Resumenes de sitio, contenido y comercio para entender el proyecto.

No uses estas habilidades para decisiones irreversibles sin revisar el impacto comercial. Cambiar precios, stock o reglas de venta puede tener efectos inmediatos.

Como pedir bien una tarea

Un buen prompt contiene cinco piezas:

1. Objetivo: que quieres conseguir.
2. Alcance: paginas, builders, plugins o datos afectados.
3. Seguridad: dry_run, no publicar, no borrar, confirmar antes de escribir.
4. Criterio de calidad: que debe revisar Codex antes de terminar.
5. Evidencia: que resumen, diff, IDs o warnings debe devolverte.

Ejemplo:

Quiero convertir la pagina 123 de Bricks a Gutenberg como borrador nuevo.

Primero:
- lee design.md;
- analiza la pagina origen con modelo semantico;
- identifica formularios, widgets dinamicos y partes delicadas;
- prepara un plan y un dry_run;
- no crees nada hasta que confirme.

Cuando confirme, crea una pagina draft nueva, no modifiques la original y devuelve ID, enlace de edicion, warnings y checklist de revision.

Como leer las respuestas

Cuando una habilidad escribe o prepara cambios deberia devolver campos como:

• success: si la operacion se completo desde el punto de vista del plugin.
• dry_run: si no se guardo nada.
• changed: si hubo cambios reales.
• summary: resumen humano.
• warnings: riesgos, degradaciones o pasos manuales.
• audit: datos de seguimiento, ability, usuario, fecha y objeto afectado.

Si falta alguno en una tarea delicada, pide a Codex que lo confirme antes de seguir.