Siempre Listo Escuela
← Volver al listado de tecnologías ← Índice de Organic Driven Development (ODD)

Explorador, worker y verificador

Por: Artiko
oddsubagentesrolesmodelos

Explorador, worker y verificador

Objetivos

  • Comparar qué puede y qué no puede hacer cada rol.
  • Interpretar el formato de retorno de un worker.
  • Conocer dónde se configura el modelo de cada rol.

Las definiciones citadas son las de OpenCode, en internal/assets/opencode/agents/, que el proyecto usa como referencia de paridad con Gentle Shell. Otros runtimes expresan lo mismo con sus propias herramientas.

Los tres roles

flowchart LR
    P["Parent<br/>decide, conversa, opera Git"] -->|"necesita un mapa"| E["Explorador<br/>solo lectura"]
    P -->|"unidad con motivo"| W["Worker<br/>escribe dentro de su superficie"]
    P -->|"punto de alto riesgo"| V["Verificador<br/>solo lectura, con sondas"]
    E -->|"mapa con evidencia"| P
    W -->|"resultado y validación"| P
    V -->|"veredicto por S#"| P
AspectoExploradorWorkerVerificador
Edita el repositorioNoSolo en su superficieNo
Ejecuta comandosNoSolo los autorizados por el parentLos autorizados y sus sondas en copia temporal
Lee el documentoHasta ## LogHasta ## LogCompleto
DelegaNoNoNo
Commit o pushNoNoNo
Lentes de revisiónNoNo, ni herramientas de revisiónNo
RetornaMapa con evidenciaFormato estructuradoHasta ~2k tokens y sondas

Ningún subagente hace commit: el parent es dueño de esa operación.

El explorador

Es el contrato más breve. Mapea archivos, símbolos, relaciones e incertidumbre dentro del alcance entregado. Prefiere codegraph_explore para preguntas estructurales si hay índice, y usa read, grep y glob como alternativa solo cuando CodeGraph no está disponible o falla.

No edita, no ejecuta comandos ni corrige lo que encuentra. Su regla de cierre es la de todo el sistema: nunca afirmar evidencia que no observó.

El worker

Se describe como el escritor de implementación propiedad del paquete. Sus reglas se organizan por temas.

Contexto antes de trabajar

  1. Cargar cada skill listado en ## Skills to load before work, sin redescubrir el registro.
  2. Tomar del parent la tarea, los criterios, el contexto, las superficies exactas y los comandos de validación.
  3. Leer el documento de feature hasta ## Log. Sus especificaciones mandan sobre cualquier resumen del traspaso.
  4. Inspeccionar el árbol de trabajo y conservar cambios preexistentes.
  5. Si hay algo ambiguo en alcance, propiedad o criterios, detenerse con interaction_required. Nunca adivinar.

No lee memoria persistente para obtener contexto: el parent selecciona y reenvía las observaciones relevantes.

Herramientas prohibidas

ProhibiciónEjemplos
Leer datos sensiblesSecretos, credenciales, llaves privadas, .env
Escribir fuera de la superficieIncluso mediante redirección, copias temporales, formateadores o scripts
Comandos destructivosrm, git reset, git clean, git checkout, git restore, git rebase
Operaciones de entregagit add, git commit, git push, publicar o lanzar versiones
Efectos no autorizadosInstaladores, dependencias, migraciones o scripts arbitrarios

Límite de correcciones

Corre primero las pruebas enfocadas. Las suites amplias, builds, formateadores y linters solo corren si el parent lo autoriza. Hay un intento de corrección por cada comprobación fallida, y un segundo solo si la misma comprobación sigue fallando tras un arreglo real. Luego se detiene y devuelve partial.

El formato de retorno

status: completed | partial | blocked | interaction_required
summary: <qué cambió y por qué>
files_changed:
  - <ruta>: <cambio>
tdd_evidence:
  - RED: <falla observada o excepción justificada>
  - GREEN: <paso observado o excepción justificada>
  - PRESERVE/REFACTOR: <evidencia cuando aplica>
validation:
  - <comando exacto>: <resultado observado>
risks:
  - <riesgo restante o ninguno>
review_focus:
  - <rutas o comportamientos a verificar>
skill_resolution: paths-injected | paths-invalid | none

Qué significa cada estado

flowchart TD
    A["Fin del worker"] --> B{"¿Terminó y todos los comandos pasan?"}
    B -->|"Sí"| C["completed"]
    B -->|"No"| D{"¿Qué lo impide?"}
    D -->|"Decisión humana"| E["interaction_required<br/>opciones cerradas"]
    D -->|"Bloqueo técnico: herramienta o acceso"| F["blocked"]
    D -->|"Hizo una parte o falla una comprobación"| G["partial"]

La regla clave de estos estados es no pretender que algo terminó. El contrato lo dice con esta frase: un traspaso limpio vale más que simular que la tarea está completa.

Una decisión humana nunca se informa como blocked, y un comando requerido que falla obliga a partial, salvo que esté nombrado en ## Known environmental failures.

Frontera con la revisión

El worker no busca, pide ni invoca herramientas de revisión. Su autoinforme es verificación, y la revisión nativa, cuando corre, es una comprobación externa en la que no puede influir.

El verificador

El capítulo 13 cubre sus sondas y la severidad. En cuanto a restricciones:

  • No edita ni corrige hallazgos.
  • No ejecuta comandos no aprobados, no altera uno autorizado, no instala dependencias ni muta el repositorio.
  • Una mutación inesperada se trata como bloqueo: se informa, sin limpiarla.
  • No usa lentes de revisión. RDD sigue siendo independiente y del parent.

Verify y RDD no son lo mismo

Una especificación del proyecto contiene la distinción en palabras del mantenedor:

“El verify es para ver temas de los Specs, rdd es para tener un punto de vista externo del trabajo realidad para realizar hallazgos según categorías, las 4R.”

odd/tasks/verify-always-rdd-high.md, S5

VerificadorRevisión RDD
Pregunta¿Cumple lo pedido?¿Qué problemas ve alguien de afuera?
GuíaEspecificacionesLentes 4R
CuándoPunto de alto riesgo nombradoCandidato high o pedido explícito, con RDD activo
OrdenAntesDespués

Modelos por rol

Cada rol se puede asignar a un modelo. La asignación depende del cliente y se inspecciona en la TUI, en la pantalla Configure Models. La documentación aclara que aplica a roles genéricos y de revisión, no a una matriz formal de fases.

Codex

El código define estos valores por defecto, vigentes en el commit revisado. Los nombres de modelos cambian con frecuencia, de modo que conviene comprobarlos en tu versión.

Presetodd-explorerodd-workerodd-verify
LowCostgpt-6.1-luna, highgpt-6.1-luna, mediumgpt-6.1-sol, medium
Recommendedgpt-6.1-luna, highgpt-6.1-luna, highgpt-6.1-sol, medium
Powerfulgpt-6.1-luna, highgpt-6.1-sol, highgpt-6.1-astra, xhigh

Las claves guardadas sdd-cheap, sdd-mid y sdd-strong siguen legibles para asignaciones personalizadas existentes, pero no determinan los valores por defecto de ODD.

Claude Code

La pantalla de modelos ofrece los presets balanced, performance y economy para los roles odd-explorer, odd-worker y odd-verify, y una opción de personalización por rol.

OpenCode

Se instalan los subagentes gentle-ai-explore, gentle-ai-worker y gentle-ai-verify, gestionados como parte de la configuración.

Pi

Gentle Shell es dueño de las asignaciones de modelos en ese runtime.

Actividad

Escribe el retorno que debería dar un worker en estos dos casos, usando el formato anterior:

  1. Terminó el código y la prueba enfocada pasa, pero la suite que le pediste falla en una prueba no relacionada que no figura en ## Known environmental failures.
  2. Necesita saber si puede tocar un archivo que está fuera de su superficie.
Una posible solución
  1. status: partial. El comando fallido se informa en validation y la prueba se menciona en risks. Un comando requerido que falla fuerza este estado.
  2. status: interaction_required, con la ruta exacta como opción cerrada de aprobar o declinar. No es blocked, porque es una decisión humana.

Autoevaluación

  1. ¿Quién hace los commits de una tarea con writers?

    • A. El worker que terminó último
    • B. El parent
    • C. El verificador
    • D. Un subagente de entrega

  2. Un worker necesita una decisión de producto. ¿Qué estado devuelve?

    • A. partial
    • B. blocked
    • C. completed
    • D. interaction_required

  3. ¿Quién selecciona las observaciones de memoria que recibe un worker?

    • A. El parent
    • B. El propio worker con mem_search
    • C. Engram, de forma automática
    • D. El verificador

  4. ¿Qué pregunta responde cada uno según la fuente?

    • A. El verificador busca estilo y RDD busca requisitos
    • B. Ambos hacen lo mismo con distinto modelo
    • C. El verificador compara con las especificaciones y RDD da una vista externa con lentes
    • D. RDD reemplaza al verificador cuando está activo
Respuestas
  1. B. Los workers tienen prohibido hacer git add o git commit.
  2. D. Las decisiones humanas nunca se informan como blocked.
  3. A. “Do not read persistent memory for context. The parent selects and forwards relevant observations.”
  4. C. Es la distinción de verify-always-rdd-high.md, y la revisión nunca reemplaza la verificación del nivel.

Lista de control

  • Sé qué puede hacer cada rol y quién opera Git.
  • Uso partial, blocked e interaction_required con su significado.
  • Distingo verificación contra especificaciones de revisión externa.
  • Sé dónde se configura el modelo de cada rol.

Fuentes

internal/assets/opencode/agents/gentle-ai-explore.md, gentle-ai-worker.md, gentle-ai-verify.md, internal/model/codex_model.go, internal/tui/screens/claude_model_picker.go, internal/components/opencodeagents/agents.go, docs/agents.md, docs/pi.md, odd/tasks/verify-always-rdd-high.md.

← Volver al listado de tecnologías ← Índice de Organic Driven Development (ODD)