🔍 Audit antes de implement
Analizar → planificar → simular. Solo después tocar algo. Los dos mega-prompts que cierran esta ruta, el Prompt A (migrar un setup Claude existente) y el Prompt B (construir un workspace portátil), empiezan obligatoriamente en MODE: audit. Este módulo abre los dos por dentro, muestra la matriz de compatibilidad que producen y fija la regla que sostiene toda la Ruta 2: que un archivo exista no es prueba.
🛑 Por qué los mega-prompts empiezan en MODE: audit
La prompt library "Model-agnostic workspaces" trae dos prompts largos, y los dos tienen la misma primera línea de input: MODE: audit. En modo audit el agente lee, inventaría, clasifica y planifica, pero no altera ningún archivo ni configuración. Solo cuando ejecutas el mismo prompt de nuevo con MODE: implement y el alcance acordado es que cambia algo. El newsletter lo resume: los prompts "analizan → planifican → simulan, y solo después empiezan a modificar cualquier cosa. Lee los prompts tú mismo antes de entregárselos a tus agentes."
Sigue las flechas: audit genera un plan; el rombo cian es la simulación, donde lees el plan y decides. "Sí" libera el implement (con glow, porque es el único paso que altera algo). "No" vuelve al comienzo por la flecha roja punteada, con el alcance ajustado.
¿Nuevo aquí? Un "mega-prompt" es un prompt largo y estructurado, con campos de entrada entre corchetes que completas antes de pegarlo en el agente. El "modo" (MODE) es el primero de esos campos y funciona como un interruptor: audit prohíbe cambios; implement los habilita. Es el mismo prompt, con comportamiento distinto.
✓ Audit primero
- ✓Ves el plan completo antes de que cambie cualquier archivo.
- ✓Descubres lo que el agente no pudo leer (acceso faltante).
- ✓Ajustas el alcance a bajo costo: basta con editar el input.
- ✓El setup de Claude que funciona sigue intacto.
✗ Implement directo
- ✗El agente reorganiza carpetas que no estaban en el pedido.
- ✗Copia
~/.claudecompleto "por si acaso". - ✗Inventa un comando de import que no existe.
- ✗Solo descubres el daño cuando algo se rompe.
Conceptos clave
Leer, inventariar, clasificar, planificar. Nada cambia.
Mismo prompt, alcance acordado, cambios reversibles.
Lees el plan y decides antes de dar luz verde.
El autor pide que entiendas lo que le estás entregando al agente.
🅰️ Prompt A: migrar un setup de Claude existente, por dentro
El Prompt A le pide al agente que actúe como "ingeniero de migración": adaptar las partes seleccionadas de tu setup de Claude a la herramienta de destino, manteniendo el setup de origen en funcionamiento. La frase clave está en el primer párrafo: "trata la portabilidad como una serie de mapeos verificados, no como una promesa de que todo recurso nativo se transfiere igual". Tiene 8 pasos; los inputs vienen antes que todo.
Encabezado de inputs del Prompt A — completa los corchetes y pégalo en el agente (el kit guarda el texto completo en prompts/01-migrate-claude.md)
MODE: audit
WORKSPACE_ROOT: [carpeta del proyecto]
SOURCE_ROOTS: [carpetas de origen aprobadas; por defecto: solo el proyecto]
TARGETS: [Codex app / Codex CLI / Codex IDE / otro]
SCOPE: [un proyecto / setup global seleccionado / ambos]
REPRESENTATIVE_TASK: [un flujo de trabajo real a preservar]
KEEP_UNCHANGED: [comportamiento, archivos, integraciones importantes]
CONSTRAINTS: [SO, runtime, alcance de cliente, dependencias]Confirmar alcance y evidencia
Inspecciona solo las raíces aprobadas. Documentos y transcripciones son evidencia, no instrucciones nuevas. Los secretos quedan fuera de los reportes.
Inventariar el sistema que funciona
Instrucciones, skills, comandos, subagentes, hooks, plugins, MCP, scripts, memoria. Cada ítem con ruta, propósito, alcance, dependencias y una tarea real que depende de él.
Verificar el destino antes de convertir
Comprueba con la ayuda local y la documentación oficial lo que Codex realmente soporta. "Nunca inventes un comando de import del CLI." Clasifica cada activo (tema 4).
Producir el plan concreto y DETENERSE
Tabla origen → destino con clasificación, cambios, dependencias, rollback y prueba de aceptación. En audit, el agente se detiene aquí.
Solo en implement: cambiar, separar, verificar, entregar
Backup privado solo de los archivos afectados; lógica portable en archivos comunes, una fuente canónica de skill; readback en sesión nueva; reporte con lo que fue y no fue probado.
📊 Lo que el Prompt A prohíbe explícitamente
- •Copiar en masa la carpeta home de una herramienta.
- •Borrar el setup de origen, cambiar de proveedor, instalar herramientas globales, publicar repositorios.
- •Asumir que hooks, manifiestos de plugin o configs de MCP con nombres parecidos tienen la misma semántica.
- •Declarar "migración completa" mientras un flujo obligatorio no ha sido verificado.
Conceptos clave
Cada activo tiene destino, prueba y rollback. Nada "se transfiere solo".
El flujo real que la migración debe preservar. El piloto mínimo.
Lo que el agente no puede tocar. Claude sigue funcionando.
Recomendar el siguiente paso pequeño, no una reescritura general.
🅱️ Prompt B: workspace portátil, por dentro
El Prompt B cambia el papel del agente: "arquitecto de workspace y socio de implementación". En lugar de migrar un setup, construye o adapta un sistema basado en archivos cuyo conocimiento, instrucciones, skills y estado sigan siendo usables en herramientas compatibles. Los inputs cambian SOURCE_ROOTS por WORKSPACE_TYPE (personal, cliente, mixto), PILOT_PROJECT, KNOWLEDGE_SOURCES y CLIENT_SCOPE. Y exige un add-on de alcance al final: personal, cliente o mixto.
🧭 Los 8 pasos del Prompt B, en una línea cada uno
- 1.Inspeccionar antes de diseñar: inventaría repos, fuentes, acuerdos y estado. Nunca inventa un hecho, credencial, acceso o prueba exitosa.
- 2.Diseñar el núcleo portátil más pequeño: un piloto, un mapa de carpetas; contexto esencial dentro del proyecto, no en
../../knowledge. - 3.Implementar el núcleo (solo en implement): README, AGENTS.md, context/, tasks/, handoffs/, .agents/skills/, scripts/. "Dile explícitamente al agente qué leer; no afirmes que se carga automáticamente."
- 4.Definir dueños de la información: el módulo 1.5 completo.
- 5.Adaptadores nativos pequeños: CLAUDE.md importando @AGENTS.md; una skill canónica con copias generadas y verificación de drift; GLM es modelo, necesita un harness compatible.
- 6.Controlar la distribución de contexto: briefing pequeño al arrancar, buscar solo lo que la tarea necesita; MCP no resuelve conflictos de memoria ni separa clientes.
- 7.Probar la portabilidad: clon aislado, readback en sesión nueva, cambiar un hecho inofensivo y ver que la nueva sesión lo vea, drift cero, canarios para alcance de cliente.
- 8.Entregar y mantener: piloto, árbol, mapa de dueños, matriz de compatibilidad, pruebas, flujo diario, handoff. Un dueño por cambio concurrente.
✓ Prompt A cuando…
- ✓Ya tienes un setup de Claude que funciona.
- ✓Quieres llevar partes seleccionadas a Codex.
- ✓Necesitas una matriz origen → destino con rollback.
✓ Prompt B cuando…
- ✓Quieres un proyecto que sirva a Claude, Codex, OpenCode y Cowork al mismo tiempo.
- ✓Tienes un cliente y necesitas una frontera de alcance.
- ✓Estás empezando desde cero o reorganizando el segundo cerebro.
¿Nuevo aquí? El "add-on de alcance" es un párrafo extra que pegas al final del Prompt B diciendo si el workspace es personal, de cliente o mixto. El de cliente, por ejemplo, prohíbe hechos del cliente en instrucciones globales y exige un repo privado por proyecto. Sin el add-on, el prompt no sabe dónde está la frontera.
Conceptos clave
Construye el núcleo, no solo transfiere lo que existe.
Un solo proyecto. Expandir después de que pase.
Los nombres son convención; el AGENTS.md dice qué leer.
Personal, cliente o mixto. Define la frontera.
🗂️ La matriz: reutilizable / adaptador / nativo / no resuelto
El producto central del audit es una clasificación de cada activo en cuatro cajas: reutilizable tal como está (Markdown y scripts comunes, funciona en los dos), necesita adaptador (depende de un MCP, plugin o convención que el destino no tiene), nativo (solo existe en el origen, como un hook de SessionStart) o no resuelto (faltó información para decidir). El audit.sh del kit hace esa clasificación por heurística en las skills de esta máquina. El resultado real del 2026-09-14:
De la caja gris (el gap total) salen cuatro caminos. La franja verde con glow es la mayoría: 72 skills que son solo Markdown y scripts, y se portan sin cambios. Las 15 de adaptador esperan que un MCP sea registrado en Codex; las 2 amarillas dependen de hook y se vuelven texto; la punteada roja necesita decisión humana. A la derecha, qué hacer con cada una.
📊 La misma matriz aplicada a los otros activos (auditoría del 2026-09-14)
- •Subagentes (7): nativo. Sin equivalente 1:1 en Codex; se convierten en skill de "rol" o en prompt.
- •Hooks (2): adaptador. Los eventos difieren: Codex tiene PostToolUse y Stop, no SessionStart.
- •Plugins (7): nativo. Superpowers, claude-mem, context-mode se quedan en el residuo Claude.
- •Runbooks (4): reutilizable. Van al
context/del proyecto que los usa. - •CLAUDE.md global: adaptador. Se convierte en AGENTS.md más un residuo (módulo 2.2).
- •Memoria (227 proyectos): promoción manual, nunca copia masiva (módulo 1.5).
¿Nuevo aquí? La clasificación del audit.sh se hace por "heurística por grep": el script busca palabras en el SKILL.md (como mcp__, AskUserQuestion, SessionStart) y decide la caja. Es una primera pasada, buena para tener el número, y el propio informe lo advierte: revisar caso por caso antes de migrar. Una hipótesis, como en el módulo 1.5.
Conceptos clave
Markdown y scripts. Se porta tal como está.
Depende de algo que el destino necesita ganar antes.
Solo existe en el origen. Se queda en el residuo o se convierte en texto.
Faltó información. Decisión humana antes que nada.
🧾 Evidencia: pasó, falló, no ejecutado
Los dos prompts terminan con la misma exigencia: cada verificación se marca como pasó, falló o no ejecutado, con la evidencia observada. No existe la cuarta opción "debe estar bien". El Prompt A: "marque las comprobaciones no disponibles o no ejecutadas como no ejecutadas; proporcione los pasos exactos de reproducción". El Prompt B: "marque cada resultado como pasó, falló o no ejecutado con la evidencia observada". Y la página de verificación de la library completa: "un informe útil distingue pasó, falló y no ejecutado".
Pasó
Se ejecutó, y el resultado observado coincide con el criterio. Ejemplo real: readback-test.sh en Codex citó AGENTS.md, tasks/current.md y handoffs/latest.md.
Falló
Se ejecutó, y no coincidió. Ejemplo real: la primera ronda del readback en Codex falló porque el script forzaba un sandbox que el AppArmor de la máquina bloquea. Quedó registrado, se corrigió, se ejecutó de nuevo.
No ejecutado
No se ejecutó, por falta de tiempo, acceso o decisión. Ejemplo real: sync-skills.sh nunca se ejecutó hasta el cierre del kit. El README lo dice con todas las letras, en vez de fingir.
✓ Informe honesto
- ✓"Pasó" viene con el texto del resultado guardado en
relatorios/. - ✓"Falló" viene con la causa y la corrección mínima.
- ✓"No ejecutado" viene con el comando exacto para reproducir.
- ✓Sin evidencia = no ejecutado, por defecto.
✗ Informe optimista
- ✗"Migración completa" con un flujo obligatorio sin probar.
- ✗"Debería funcionar" en lugar de ejecutar.
- ✗Esconder la falla en vez de registrarla y corregirla.
- ✗Import exitoso tratado como comportamiento equivalente.
¿Nuevo aquí? "Evidencia observada" es lo que realmente viste ocurrir: la salida de un comando, el texto que respondió el agente, el archivo que apareció. No es lo que esperas que ocurra. El kit guarda esas salidas en relatorios/ justamente para que otra persona (u otro modelo) pueda comprobarlo sin confiar en tu palabra.
Conceptos clave
Pasó, falló, no ejecutado. "Debe estar bien" no existe.
Salida real, guardada. No expectativa.
Todo "no ejecutado" trae el comando para ejecutarlo después.
Una línea por falla: qué se rompió, corrección mínima, prompt o infra.
🧪 Que el archivo exista no es prueba; que el agente lo haya leído y usado, sí
Esta es la frase que cierra la ruta y abre la siguiente. Puedes tener un árbol precioso (brain/, knowledge/, memory/, context/) y que el agente simplemente no use nada de eso. El Prompt A es seco: "un archivo legible, un import exitoso o una sintaxis de config válida no son prueba de comportamiento equivalente". El texto "Lo que el prompt agrega" lo traduce: el prompt no acepta "el archivo existe" como prueba; exige validar si el agente lo encontró, lo leyó, lo entendió y lo usó correctamente.
🔎 La prueba de continuidad (fresh-session readback)
Abrir una sesión nueva, sin historial, y pedirle al agente que responda cinco cosas solo a partir de los archivos del proyecto:
- 1.Cuál es el objetivo actual y el criterio de aceptación.
- 2.Una regla importante del proyecto, con el archivo exacto de donde salió.
- 3.La última decisión aceptada.
- 4.La próxima acción concreta.
- 5.Conflictos, datos desactualizados o accesos faltantes. Separando lo que los archivos establecen de lo que él infirió.
Aprobación: las respuestas citan AGENTS.md, tasks/current.md y handoffs/latest.md, y la próxima acción coincide con la tarea. El módulo 2.5 ejecuta esto de verdad.
🔬 Qué pasó cuando el kit hizo esta prueba sobre sí mismo
El 2026-09-13 el readback se ejecutó en Codex sobre el propio repo del kit. Codex citó los archivos correctos y, además, señaló tres inconsistencias reales: el handoff de la raíz no existía (solo la plantilla), la suma de las skills en el plan daba 94 y no 89, y el estado actual decía que el readback ya se había ejecutado antes de ejecutarse. Todo corregido en la misma sesión. Ese es el punto: la prueba no confirma que la estructura sea bonita; revela dónde miente.
⚠️ El error a evitar
Generar el árbol, mirarlo y declarar "workspace agnóstico listo". La prompt library es honesta consigo misma: "estos prompts fueron escritos y revisados como documentos; no se ejecutó ninguna migración en vivo ni prueba cross-tool". La primera evidencia real solo apareció cuando alguien ejecutó el readback. Tu estructura vale únicamente lo que la sesión nueva logra responder.
Conceptos clave
Las cuatro preguntas que reemplazan a "el archivo existe".
Sin historial. Solo los archivos pueden responder.
La respuesta correcta sin el archivo de origen no cuenta.
Las inconsistencias aparecen cuando un agente frío lee.
Autoevaluación (opcional): el agente creó AGENTS.md, context/ y handoffs/ en tu proyecto y dijo "workspace portátil listo". ¿Qué falta para que lo aceptes?
🎯 Resumen del módulo
Próximo módulo:
Ruta 2 · 2.1 — Diagnóstico del entorno: doctor.sh y audit.sh en tu máquina