🧱 Instalar el núcleo portátil
Ya tienes un AGENTS.md portátil (módulo 2.2). Ahora llega la estructura que carga el contexto: context/, tasks/, handoffs/. Un script copia el esqueleto sin sobrescribir nada, tú lo completas con hechos fechados, y una prueba en un clon aislado demuestra que el proyecto funciona por sí solo.
🧱 init-core.sh: creado vs mantenido
El núcleo portátil es la carpeta-esqueleto que el kit llama template/: AGENTS.md, CLAUDE.md, README.md, context/, tasks/, handoffs/, .agents/skills/ y scripts/check.sh. El script init-core.sh copia ese esqueleto a tu proyecto con una única regla: nunca sobrescribe lo que ya existe. Cada archivo sale marcado como [criado] o [mantido].
La caja grande es tu proyecto. Los archivos azules son instrucciones y lectura humana; las carpetas cian guardan el contenido que viaja entre runtimes. Esos nombres son una convención del kit; ningún runtime los carga por sí solo: es el AGENTS.md el que indica leerlos.
💻 Ejemplo copy-run: instalar el núcleo
Objetivo: copiar el esqueleto a un proyecto tuyo sin tocar nada de lo que ya existe.
cd ~/projetos/agente-claude-codex
scripts/init-core.sh ~/projetos/<tu-proyecto>Cómo verificar: la salida lista cada archivo con una de las dos etiquetas. En un proyecto que ya tenía README y CLAUDE.md, el resultado esperado se parece a este:
[criado] AGENTS.md
[mantido] CLAUDE.md
[mantido] README.md
[criado] context/overview.md
[criado] context/current-state.md
[criado] context/sources.md
[criado] context/decisions/0000-00-00-modelo.md
[criado] tasks/current.md
[criado] handoffs/latest.md
[criado] .agents/skills/.gitkeep
[criado] scripts/check.sh
Agora preencha: ~/projetos/<tu-proyecto>/AGENTS.md, context/overview.md, tasks/current.mdPor qué importa "mantido": la primera versión del kit sugería cp -r template/. projeto/, que borraría el README y el CLAUDE.md reales de un proyecto. El script nació para cerrar exactamente ese hueco. Cada paso del kit tiene que ser reversible, y sobrescribir no lo es.
Conceptos clave
El conjunto mínimo de archivos que hace que cualquier runtime entienda un proyecto.
La fuente del esqueleto, dentro del kit.
El contrato del script: crea lo que falta, respeta lo que existe.
Los nombres solo funcionan porque el AGENTS.md ordena leerlos.
📅 Completar overview.md con hechos fechados
El esqueleto está ahí, pero vacío. El primer archivo a completar es context/overview.md: qué es el proyecto, para quién, y los hechos verificados. Cada hecho lleva fuente y fecha, porque un agente que lee "el servidor corre en el puerto 8000" necesita saber si eso era cierto ayer o hace un año. El template ya trae el encabezado con ID, alcance, fuente, fecha de observación, estado y "revisar en".
✓ Hecho bien escrito
- ✓"Codex CLI 0.154.0 no tiene comando
import; el import de un clic solo está en la app de escritorio." (fuente:codex --help, 2026-09-13) - ✓"MCP en Claude: magnific, metricool. En Codex: ninguno." (fuente: audit.sh, 2026-09-13)
- ✓Sección separada para "Hipótesis (no verificadas)": "la clasificación heurística de 71 skills es correcta en su mayoría".
✗ Hecho que va a engañar al agente
- ✗"Codex tiene import." Sin fecha ni fuente, y ya era falso en el CLI.
- ✗"Prefiero flux2-klein" mezclado con hechos técnicos: preferencia disfrazada de hecho.
- ✗Copiar los 869 archivos de la memoria de Claude dentro del overview. Eso es materia prima, no fuente.
📄 El overview real del kit (resumido)
# Overview — agente-claude-codex
- ID: overview | Alcance: este repo | Fuente: docs/ (3 textos + PDF) y auditoría local
- Fecha: 2026-09-13 | Estado: aceptado | Revisar: al cambiar la versión de Codex o de Claude Code
## Qué es
Kit de migración/agnosticismo: scripts de auditoría y adaptación + template de núcleo portátil.
## Hechos verificados (2026-09-13)
- Codex CLI 0.154.0 no tiene comando `import`; el import "de un clic" es de la app de escritorio.
- Claude Code 2.1.270 con 116 skills; Codex con 27.
- MCP en Claude: magnific, metricool. En Codex: ninguno.
## Hipótesis (no verificadas)
- La clasificación heurística de 71 skills como "reutilizable" es correcta en su mayoría.Consejo práctico: la línea "Revisar: al cambiar la versión de Codex" es un disparador de actualización. Sin ella, el overview envejece en silencio y el agente empieza a citar hechos muertos con la misma confianza que los vivos.
Conceptos clave
Afirmación + fuente + fecha de observación.
borrador / aceptado / revocado; el agente sabe en qué confiar.
Lo que crees, lejos de lo que verificaste.
Cuándo hay que volver a comprobar el hecho.
🎯 tasks/current.md: objetivo, responsable, criterio, próxima acción
El overview dice qué es el proyecto. El tasks/current.md dice qué se está haciendo ahora. Es el archivo que lee una sesión nueva para saber por dónde continuar, y también es lo que va a exigir la prueba de readback (módulo 2.5): "¿cuál es el objetivo y cuál es la próxima acción concreta?". Cinco campos, siempre los mismos: objetivo, dueño, criterio de terminado verificable, próxima acción, bloqueos.
📄 Ejemplo completo: el tasks/current.md del propio kit
# Tarea actual
- Objetivo: validar el piloto — skill `session-handoff` portada a Codex vía polyskill
y readback pasando en los dos runtimes.
- Dueño: Nei (decide piloto y skills); el agente ejecuta.
- Criterio de terminado: `scripts/readback-test.sh . both` genera respuestas que citan
AGENTS.md/tasks/handoffs en ambos; `scripts/sync-skills.sh drift` sin DRIFT.
- Próxima acción concreta: Fase 0 del plan — `scripts/adapt-instructions.sh ~/.claude`,
revisar, guardar `~/.codex/AGENTS.md`, readback en `~/projetos/wifi`.
- Bloqueos: ninguno.Fíjate: el criterio de terminado es un comando con resultado observable, no "cuando esté bien". La próxima acción empieza con un verbo y cita el script exacto.
Objetivo
Una frase. Si necesitas dos, son dos tareas.
Dueño
Quién decide y quién ejecuta. El humano define, el agente registra.
Criterio de terminado
Un comando o una observación que cualquier runtime puede reproducir.
Próxima acción concreta
Verbo + archivo o comando. Es lo que la sesión nueva hace primero.
Bloqueos
Lo que solo el dueño puede decidir. "Ninguno" también es una respuesta.
Conceptos clave
El agente entiende el trabajo actual, no solo el historial.
Comando con salida esperada, nunca sensación.
Evita que el agente decida lo que le corresponde al humano.
Siempre los mismos; el readback depende de eso.
📜 Primera decisión en context/decisions/
Una decisión es distinta de un hecho. Un hecho se verifica; una decisión se acepta. Por eso cada decisión se convierte en un archivo propio en context/decisions/, con la fecha en el nombre, estado (propuesta, aceptada, revocada), contexto, la decisión en sí y las consecuencias. Cuando dos archivos no coinciden, la decisión aceptada gana sobre la más reciente. Esto resuelve el problema clásico: "¿cuál de las versiones es la correcta?".
📄 La primera decisión real del kit
# context/decisions/2026-09-13-docs-fora-do-git.md
# Decisión: docs/ queda fuera de git
- Fecha: 2026-09-13 | Estado: propuesta (espera al dueño) | Fuente: sesión de creación del repo
## Contexto
docs/ contiene un post traducido y una prompt library de terceros. Publicarlo en un repo
público redistribuye ese material.
## Decisión
`.gitignore` excluye docs/ hasta que el dueño elija: repo privado, o mantener solo
reescrituras propias.El estado quedó en "propuesta" a propósito: el agente propuso, el dueño todavía no tomó la decisión final. En el readback, Codex señaló exactamente eso: "no hay decisión aceptada, solo una propuesta". Era la lectura correcta.
✓ Se convierte en decisión
- ✓"Los secretos quedan en
.envy se referencian, nunca se copian." - ✓"Las skills de adaptador solo entran en Codex después de registrar el MCP."
- ✓"El autor del commit sigue a la cuenta de destino."
✗ No es decisión
- ✗"Codex tiene 27 skills." Eso es un hecho; va en el overview.
- ✗"Correr el sync-skills mañana." Eso es próxima acción; va en tasks.
- ✗"Creo que polyskill va a funcionar." Hipótesis; overview, sección propia.
Regla de conflicto: cuando un handoff antiguo dice A y una decisión aceptada dice B, vale B. El timestamp más nuevo no gana; ganan el origen y la aceptación. Es la misma lógica del superseded_by que vas a ver en el Proyecto 3 de la Trilha 3.
Conceptos clave
Un archivo por decisión, con estado explícito.
De dónde vino y quién la aceptó ganan sobre la fecha.
El agente propone; el dueño acepta. Nunca al revés.
AAAA-MM-DD-asunto.md: se ordena solo.
✅ scripts/check.sh: la verificación mínima
La plantilla incluye un script de ocho líneas que responde una sola pregunta: ¿los archivos obligatorios existen y no están vacíos? Parece poco, pero es la diferencia entre "creo que lo llené" y "está lleno". Revisa AGENTS.md, README.md, los cuatro de context/, tasks/current.md y handoffs/latest.md, y sale con código 1 si falta cualquiera.
💻 Ejemplo copy-run: ejecutar el check
Objetivo: confirmar que el núcleo está completo antes de cualquier readback.
cd ~/projetos/<seu-projeto>
bash scripts/check.sh; echo "exit=$?"Cómo verificar: todo [ok] y exit=0. Un [FALTA] significa archivo ausente o vacío, y el exit pasa a 1, así que se puede usar en un pipeline.
[ok] AGENTS.md
[ok] README.md
[ok] context/overview.md
[ok] context/current-state.md
[ok] context/sources.md
[ok] tasks/current.md
[ok] handoffs/latest.md
exit=0🔍 El script completo, para que veas que no hay magia
#!/usr/bin/env bash
set -e; cd "$(dirname "$0")/.."
for f in AGENTS.md README.md context/overview.md context/current-state.md \
context/sources.md tasks/current.md handoffs/latest.md; do
[ -s "$f" ] && echo "[ok] $f" || { echo "[FALTA] $f"; rc=1; }
done; exit ${rc:-0}El -s prueba "existe y tiene tamaño mayor que cero". Una plantilla copiada pero sin llenar igual pasa; por eso el check es mínimo, y el readback del módulo 2.5 es la prueba de verdad.
Consejo práctico: agrega al check lo que sea específico de tu proyecto (build, tests, lint). El kit deja el archivo corto a propósito: es tuyo para extenderlo.
Conceptos clave
Existe y no está vacío; nada más que eso.
0 pasó, 1 faltó; sirve para automatización.
Agrega los checks reales del proyecto.
Que el archivo exista ≠ que el agente lo haya usado. Eso es el readback.
📦 Clon aislado: ¿el proyecto funciona solo?
Aquí está la trampa más común de un workspace "portátil": funciona en tu máquina porque depende de una carpeta vecina, de un ../../knowledge, de un symlink a ~/.claude. El Prompt B lo exige explícitamente: copia o clona el proyecto solo en un lugar limpio y verifica los archivos y comandos. Si el check pasa en el clon, el contexto esencial está dentro del proyecto. Si no pasa, encontraste una dependencia oculta.
A la izquierda el proyecto "funciona" porque se apoya en cosas fuera de él (punteado gris). A la derecha, en el clon, solo existe lo que se hizo commit. Si el check pasa aquí, el contexto es portátil de verdad.
💻 Ejemplo copy-run: la prueba de clon aislado
Objetivo: probar que el núcleo sobrevive fuera de tu carpeta original. Usa el propio repo como origen del clon, sin red.
cd ~/projetos/<seu-projeto>
git add -A && git commit -m "núcleo portátil" # el clon solo ve lo que está en commit
rm -rf /tmp/clone && git clone -q . /tmp/clone
bash /tmp/clone/scripts/check.sh; echo "exit=$?"Cómo verificar: siete [ok] y exit=0. Fue exactamente esta prueba la que el kit ejecutó el 2026-09-13 y pasó. Si aparece [FALTA] en un archivo que existe en tu carpeta, no estaba en commit o era un symlink hacia afuera.
init-core.sh
Esqueleto copiado sin sobrescribir.
overview + tasks + decisión
Hechos con fecha, tarea con criterio, primera decisión con estado.
check.sh local
Siete ok. Todavía no prueba nada sobre portabilidad.
check.sh en el clon
Siete ok otra vez. Ahora sí: el proyecto funciona por sí solo. El siguiente paso es el readback.
⚠️ El error que debes evitar
Saltarse el clon porque "en mi máquina funciona". Un workspace que depende de ~/.claude/runbooks o de una carpeta hermana se va a romper en Codex, en dsh y en cualquier clon de otra persona. La prueba cuesta treinta segundos y es la única evidencia de que la capa es portátil.
Conceptos clave
Copia en un lugar limpio, solo con lo que está en git.
Carpeta vecina, symlink, config global.
Exigencia del Prompt B: nada que exista solo en ../../.
Si algo viene de afuera, el AGENTS.md dice cómo obtenerlo.
Autoevaluación (opcional): el check.sh pasó en tu carpeta pero falló en el clon aislado. ¿Qué muestra esto?
🎯 Resumen del módulo
Próximo módulo:
2.4 — Skills canónicas con polyskill: una fuente, N runtimes