ptmrio/harness-subagent

Harness Subagent

Envía otro agente de codificación como un subagente de un solo disparo, luego sintetiza.

Principio central: el harness es un subagente, no un oráculo. Un modelo que revisa su propio trabajo reproduce sus propios puntos ciegos. Ese valor se destruye si se reenvía la respuesta sin juzgarla.

Voz del orquestador: nivel CTO — breve, conciso, viñetas, vistas previas ASCII cuando sean mejores que la prosa. Mantente alineado con el operador humano (superficie suposiciones; pregunta sobre acciones irreversibles y preferencias de producto no resueltas; no inventes alcance en silencio).

Ruta pegajosa: si el hijo alcanza límites de uso/tasa (o cualquier fallo suave que tiente a un intercambio), no redirijas a otro backend o modelo. Reporta el fallo, marca NO VERIFICADO / bloqueado, pregunta una vez. Excepción: una consulta sin-veredicto de la misma familia / "qué harness" es una fuga de anidamiento — reescribe la valla de identidad, relanza una vez, el mismo backend; no preguntes y no cambies. En un bucle de orquestación completo, detén la lista de verificación — no continúes a etapas posteriores sin el entregable de la etapa fallida (p. ej., no Implementar si Prácticas murió por un límite).

No elijas un harness por un estereotipo de tarea a menos que la configuración del usuario tenga esa clave (ver references/user-config.md). Orden de enrutamiento: esta expresión → configuración del usuario → preguntar una vez. Mismo protocolo para cada backend. Mapa de personalidad de rol y Súperpoderes: references/roles.md (canónico).

Por defecto, Revisar (no editar archivos de la aplicación). Permitir escrituras en la aplicación solo cuando el usuario (o un plan aprobado) solicite Implementar. Revisar y Visual pueden crear archivos temporales y escribir informes.

Niveles de comando (no mezclar)

Este skill es de un solo disparo. El hijo no debe volver a entrar en él. Los CLI de proveedores pueden permitir Agente anidado/spawn_agent; eso no es una licencia para ejecutar este protocolo de nuevo.

Nivel	Quién	Comandos	Prohibido como "tuyo"
L0	Humano	/harness-subagent, "orquestar", harness nombrado, pin self	Banderas de spawn.sh
L1	Padre que cargó este skill	scripts/spawn.sh --backend --mode, enrutamiento de configuración, salto de misma familia, preguntar una vez, sintetizar	Poner invocaciones de spawn.sh en el resumen; preguntar al hijo qué harness
L2	CLI spawn.sh lanzado	Solo Súperpoderes de rol, Playwright / tomas nombradas, report.md	Este skill, spawn.sh, requesting-code-review, "¿qué harness?", consulta de misma familia

L1 invoca scripts/spawn.sh --mode .... Ese argv no es una instrucción para el hijo. Si eres L2 (HARNESS_SUBAGENT_RUN establecido, o el prompt comienza ERES EL TRABAJADOR), deja de leer este protocolo de spawn y haz el trabajo resumido.

spawn.sh exporta HARNESS_SUBAGENT_RUN y establece CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1. Un spawn.sh anidado muere (la variable ya está establecida).

Orquestar vs un solo disparo

Precedencia (evaluar en orden):

1. La reducción de un solo trabajo gana al un solo disparo — la expresión nombra un trabajo (segunda opinión, revisar este diff, implementar solo ..., reescribir el README, investigar X) → un resumen, un spawn. Un "Orquesta esto —" inicial no fuerza el bucle completo.
2. El bucle completo explícito gana — el usuario dice "ejecuta el bucle completo" / nombra prácticas+implementar+revisar juntos / "orquesta esta característica de principio a fin" abierto sin un sustantivo de un solo trabajo → lista de verificación completa a continuación. Un harness nombrado aquí solo fija el backend para cada etapa (o configuración por etapa); no colapsa el bucle en un solo disparo.
3. De lo contrario, pregunta una vez qué quieren (bucle completo vs un trabajo).

Lista de verificación de bucle completo (omitir pasos ya hechos o renunciados por el usuario; un trabajo por spawn):

1. Prácticas — Investigar (o padre self si está fijado): exactamente dos anclajes — una guía oficial de Anthropic + una de OpenAI. Opcionalmente complementar (no reemplazar) con Cursor/xAI cuando la pila/harness los haga relevantes. Citar + fecha.
2. Implementar — porción limitada contra esas prácticas. Pegar la tabla TDD completa de roles.md.
3. Validar — code-review (adversarial). Agregar code-review-visual cuando haya UI.
4. Coherencia final — padre por defecto self (o un spawn corto de Revisar): lógica, redundancia, cordura general contra los dos anclajes y la solicitud original.

Si alguna etapa está bloqueada (incluyendo límites de ruta pegajosa), detente y pregunta — no te saltes.

Elegir un backend

Nunca generes la propia familia del padre a menos que el usuario la haya nombrado en este turno (padre Grok → no grok; padre Claude Code → no claude; padre Codex → no codex; padre Antigravity → no agy). Un harness por pregunta a menos que el usuario haya pedido múltiples opiniones.

La familia es el producto/CLI padre, no el id del modelo. Cursor Agent, cursor-agent y Grok Bot son cursor (incluso cuando el modelo es Grok). El CLI Build de Grok es grok. Claude Code es claude. Codex CLI es codex. Antigravity CLI es agy. El CLI Gemini heredado es gemini (una familia diferente; no lo trates como agy). Un padre Cursor con defaults.implement = "cursor" salta y pregunta una vez — ese token es un backend, no self. Fija self cuando esta sesión deba hacer el trabajo.

El usuario dice	Binario (PATH)	Modelo por defecto (última serie)	Pensamiento por defecto	Banderas
Claude, Opus, Fable, ask-claude	claude	opus (también fable, sonnet, haiku)	xhigh	references/backend-claude.md
GPT, Codex, Sol, Terra, Luna, ask-gpt	codex	gpt-5.6-sol	xhigh	references/backend-codex.md
Grok, ask-grok	grok	grok-4.6	xhigh	references/backend-grok.md
Gemini, Antigravity, agy, ask-gemini	agy	predeterminado del proveedor (omitir --model; listar: agy models)	high	references/backend-agy.md
No especificado	Clave defaults.* coincidente en la configuración del usuario (spec, spec-ui, plan, plan-ui, implement, implement-ui, writer, research, code-review, code-review-visual, ...) si está establecida y (el backend no es de la familia padre, o el valor es de clase self); de lo contrario pregunta una vez. Aliases de revisión: code-review-task / code-review-adversarial / code-review-adverserial / review → code-review (ver orden de resolución en user-config).	Config [models] / [effort], de lo contrario predeterminados de la tabla	—	references/user-config.md

Si el usuario fija un id de modelo, úsalo. Cursor Agent / OpenCode / Droid / CLI Gemini heredado: references/more-clis.md (no en scripts/spawn.sh). El token de configuración gemini es ese CLI heredado, no un alias de agy.

Lista lo que esta máquina realmente tiene:

claude --help
codex debug models --bundled
grok models
agy models
cursor-agent --list-models

Windows PowerShell: Get-Command claude,codex,grok,agy. No codifiques ~/.local/bin/.... agent en PATH suele ser Grok Build, no Cursor. El CLI de Cursor es cursor-agent.

No hay un skill harness-spawn. Stubs obsoletos ask-claude / ask-gpt / ask-grok: este skill.

Configuración del usuario

Opcional. Sobrevive a las actualizaciones del skill. Nunca almacenes preferencias en el clon del skill (npx skills add se distribuye a todos los directorios de agentes).

• Si $HARNESS_SUBAGENT_CONFIG está establecido: ese archivo. Archivo faltante → pregunta una vez (no caigas).
• De lo contrario: ${XDG_CONFIG_HOME:-$HOME/.config}/harness-subagent/config.toml

Esquema, búsqueda y ruta de escritura "siempre usar X": references/user-config.md. No crees el archivo a menos que el usuario pida fijarlo.

Si el valor de defaults.* coincidente es self, orchestrator, parent o you, haz el trabajo en esta sesión. No escribas un resumen. No llames a scripts/spawn.sh. Un backend de la familia padre (grok mientras eres Grok) no es self — salta y pregunta una vez a menos que esta expresión nombre ese harness.

SO, temp, stdin

Los agentes padres a menudo canalizan stdin. Trátalo como hostil.

	Linux / macOS / WSL	Windows cmd	Windows PowerShell
Directorio de ejecución	${TMPDIR:-/tmp}/harness-subagent/<run-id>	%TEMP%\harness-subagent\<id>	Join-Path $env:TEMP "harness-subagent\<id>"
Spawn	bash <skill>/scripts/spawn.sh ...	Git Bash en la ruta del script	Git Bash argv de archivo (abajo) — nunca una receta -lc entre comillas dobles

Invoca scripts/spawn.sh desde el directorio del skill del SKILL.md que cargaste este turno (ruta en el encabezado del skill). npx skills add -g distribuye copias; no mezcles ~/.claude/skills, ~/.cursor/skills y ~/.agents/skills en una sesión.

cwd / -C / --cwd debe ser una ruta que el CLI entienda (WSL /mnt/d/... vs Windows D:\...). No mezcles Windows claude.exe en WSL.

Capturas de pantalla visuales: Claude y Cursor Agent necesitan --add-dir "$RUN" con tomas en $RUN. agy Revisar/Visual también; agy Implementar no debe pasar --add-dir (hace de $RUN un espacio de trabajo escribible). Grok: copia las tomas en --project (árbol de la aplicación), nunca solo en $RUN — Grok no puede leer el directorio de ejecución temporal. Codex: -i (script --image).

Windows PowerShell (problemas — no saltar)

PowerShell expande $(...), cat y $RUN antes de que bash los vea. Un & bash -lc "claude ... $(cat $RUN/brief.md) > $RUN/last.md" entre comillas dobles buscará D:\c\Users\..., escribirá last.md en /, o pasará un prompt vacío/aplanado. system32\bash.exe es WSL — no puede ver %TEMP% como /c/....

1. Fija Git Bash: "$env:ProgramFiles\Git\bin\bash.exe" (confirma Test-Path; no uses WSL bash).
2. Escribe brief.md con la herramienta de escritura (UTF-8). No hagas Out-File / > desde PowerShell 5.1 (UTF-16LE + NULs).
3. Ejecuta el script del skill como argumentos, ejecuta en segundo plano la llamada de Shell (block_until_ms: 0 en Cursor):

& "$env:ProgramFiles\Git\bin\bash.exe" -- "<skill-dir>\scripts\spawn.sh" --backend claude --mode review --project "D:/Code/app" --run "C:/Users/<you>/AppData/Local/Temp/harness-subagent/<id>"

4. Lista el directorio de ejecución con Shell (Get-ChildItem / ls). Cursor Glob está limitado al espacio de trabajo y perderá %TEMP%.
5. Dos lanzamientos fallidos → detente. Responde desde la evidencia del padre. Marca el harness como NO VERIFICADO. No inventes una tercera receta de comillas.

Si este padre solo permite automáticamente algunos CLI, el spawn se bloqueará en bash / bash.exe, este script o el backend objetivo (codex, ...). Pide al usuario que los permita, o usa un modo de aprobación que pueda permitir el único spawn. No codifiques una lista blanca de máquina.

El spawn fija el permiso equivalente a Auto: Claude/Grok --permission-mode auto. Codex todos los modos --approve-for-me (no pases también --sandbox: mutex 0.147). agy Implementar --dangerously-skip-permissions (agy no tiene Auto clasificador; esto es YOLO). agy Revisar lo omite. Claude Revisar aún omite Editar/Escribir en --tools (Bash permanece para archivos temporales). No pases --ask-for-approval a codex exec (solo TUI; exec lo rechaza). La restricción de edición de la aplicación es el resumen (No edites archivos de la aplicación.), no un sandbox de solo lectura.

Protocolo compartido

0. Puerta. Nombra la única cosa que no puedes responder desde este repositorio / este contexto. Si no puedes nombrarla, no generes — a menos que esta expresión ya haya nombrado un harness (la expresión aún gana; writer=self no suprime "Pídele a Claude que reescriba el README"). Nombrar, estilo, formato y "ya lo intenté" que ya es la respuesta no valen una ejecución. Escritura/investigación sostenida (una reescritura del README, una búsqueda competitiva) no es "nombrar": genera cuando la ruta resuelta es un CLI.
1. Escribe brief.md bajo el directorio de ejecución temporal (nunca dentro del repositorio).
2. Genera scripts/spawn.sh en segundo plano (minutos; un tiempo de espera en primer plano mata el gasto). No copies ni edites el script.
3. Espera hasta que el proceso salga. Luego lee $RUN/last.md y $RUN/capture-status.txt. Proceso aún en ejecución + sin VEREDICTO aún → no terminado. spawn.sh ya prefiere $RUN/report.md sobre la salida estándar final y normaliza las líneas de negrita/VEREDICTO:. Si el estado es límite-de-uso o sin-veredicto, marca el harness como NO VERIFICADO / bloqueado — no inventes un veredicto y no redirijas backends (ruta pegajosa). Excepción: sin-veredicto que es una consulta de la misma familia / "qué harness" es una fuga de anidamiento — reescribe la valla de identidad y relanza una vez (el mismo backend). No relances un trabajo terminado debido a un preámbulo.
4. Sintetiza — nunca solo pegues.

Escribir el resumen

Descripción de la tarea, no un volcado de datos. No pegues diffs o contenidos de archivos — nombra rutas y una investigación limitada. Excepción: archivos inaccesibles desde el directorio de trabajo (capturas bajo el directorio de ejecución temporal).

• Prefiere archivos/símbolos nombrados sobre "explora el repositorio."
• Diff: rango exacto, git diff <A>..<B> -- <rutas...>.
• Visual/confirmar: prohíbe git log, git diff de árbol completo, volcados de estado. spawn.sh --image es solo para Codex. Claude: copia capturas en $RUN (ya recibe --add-dir "$RUN"). Grok: copia capturas en --project. Nombra los archivos en el resumen.
• Pon la evidencia del padre bajo Lo que ya se intentó. Prefiere "verifica esto" sobre "redescubre." Si ya ejecutaste gh/curl y Codex Revisar puede carecer de red, pon la salida aquí y prohíbe volver a ejecutar esos comandos.
• Anulación del producto: si el usuario bloqueó una decisión de producto, dílo.

Seis partes, en orden:

1. Valla de identidad del hijo — pega primero, textualmente, de references/roles.md. Nunca escribas scripts/spawn.sh o --mode visual en el resumen (L2 lo trata como una orden para reorquestar).
2. Objetivo — una oración que nombre el veredicto / entregable (sugerencia del objetivo de la tarjeta de rol).
3. Dónde mirar — rutas, comandos limitados, símbolos; lista blanca de edición si es Implementar.
4. Lo que ya se intentó
5. Lo que cambiaría mi opinión — evidencia concluyente (Revisar) o puertas de aceptación (Implementar).
6. Formato de retorno — pega de references/roles.md: el contrato de retorno del rol (incluye escribe report.md antes de la limpieza), mapa de Súperpoderes (nombres exactos), debe/no debe, y para implementar/implement-ui la tabla de política TDD completa (nunca "ver roles.md" solo). La tarjeta de rol gana sobre cualquier redacción de stub más antigua. Nombra la ruta del directorio de ejecución para report

... [truncado para traducción]