amElnagdy/delegate-skills

Pi Delegate

Eres el orquestador. Delega una tarea de codificación acotada a un implementador independiente - el CLI agente de codificación Pi - luego revisa lo que produjo y confirma los cambios tú mismo. Tú escribes el brief y eres dueño del juicio; el implementador hace cambios en su propia sesión; tú verificas y confirmas.

El bucle solo necesita un comando de shell y acceso a archivos, por lo que cualquier orquestador comparable puede ejecutarlo.

Cuándo NO usar esto

• La tarea es lo suficientemente pequeña como para hacerla en línea; la sobrecarga de delegación no vale la pena.
• El CLI pi no está instalado o autenticado.
• Necesitas un implementador en un entorno aislado. Pi no tiene entorno aislado ni modos de permisos; --read-only restringe la superficie de herramientas, pero una ejecución con capacidad de escritura se ejecuta sin solicitudes.

Requisitos previos (verificar una vez)

1. Instala pi con npm install -g @earendil-works/pi-coding-agent.
2. Autentica: /login dentro de pi para un proveedor de suscripción, o una variable de entorno de clave API / archivo de autenticación de pi para un proveedor de clave API.
3. Confirma que pi --version funcione.
4. Trabaja en, o apunta --cd a, el repositorio git de destino.

Elegir el modelo (opcional)

Omite --model para usar el valor predeterminado configurado de pi. Para elegir otro, selecciona de pi --list-models y pasa un id explícito o patrón como <provider>/<model-id> o sonnet:high. El relay solo acepta letras, dígitos y . _ : / - (el valor llega a un shell en Windows), por lo que los patrones glob con * no se reenvían.

El bucle

Ejecuta estos cinco pasos por tarea. Los pasos 1, 4 y 5 requieren juicio; 2 y 3 son mecánicos.

1. Escribir el brief

Pi solo ve el texto que envías más lo que puede inspeccionar en el espacio de trabajo - sin historial de chat ni contexto compartido. Incluye el objetivo, el estado actual, qué cambiar, qué no tocar, las compuertas reales del proyecto y un contrato de informe. Dile a pi que no confirme. Mantén una tarea por brief. Pi carga automáticamente los archivos de contexto AGENTS.md/CLAUDE.md del espacio de trabajo y sus padres, por lo que las instrucciones del repositorio llegan sin necesidad de incluirlas en línea. Consulta references/writing-the-brief.md.

2. Despachar

Usa el relay incluido. Envía el brief a pi --mode json en la entrada estándar, captura el flujo de eventos JSON y escribe result.json. (<skill-dir> es la carpeta instalada que contiene este SKILL.md.)

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# elegir un modelo:                          añade --model <id from pi --list-models>
# elegir un proveedor:                       añade --provider <name>
# ejecución solo lectura (revisión/diagnóstico):  añade --read-only
# confiar en recursos .pi del proyecto:             añade --approve
# reanudar la sesión más reciente:          añade --resume-last  (brief delta solamente)
# reanudar una sesión específica:               añade --session <id> (brief delta solamente)
# límite de tiempo estricto (watchdog):              añade --timeout 2h  (el predeterminado de 30m es adecuado para ejecuciones cortas; los briefs de implementación suelen necesitar 1-2h)
# ver todas las opciones:                         node .../relay.mjs --help

El directorio de trabajo del proceso hijo fija el espacio de trabajo. El relay escribe los artefactos en el directorio temporal del sistema por defecto y nunca confirma. Consulta references/dispatch-and-poll.md.

3. Esperar a que termine

El relay se bloquea hasta que pi finaliza. Ejecútalo con la función de comando en segundo plano del orquestador, o en segundo plano en el shell y espera a que aparezca result.json. Un error de uso previo a la ejecución sale con código 2 y no escribe ningún resultado; una falta de pi sale con código 127 y escribe status: "pi_unavailable".

Confía en el estado del proceso y el árbol de trabajo más que en una pantalla de progreso. La finalización significa que el proceso terminó y result.json existe. El informe completo de pi es el campo finalMessage en result.json (también impreso completo en la salida estándar entre los marcadores de informe).

4. Revisar - no confiar en el autoinforme

Trata el mensaje final de pi y las afirmaciones de compuertas como afirmaciones:

• Vuelve a ejecutar las compuertas del proyecto tú mismo.
• Lee el diff contra el brief, comenzando con touchedFiles.
• Ejecuta los skills de guardia relevantes si están instalados.
• Realiza migraciones de ida y vuelta y busca referencias colgantes después de eliminaciones o renombres.

Consulta references/review-and-land.md.

5. Confirmar

El implementador edita el árbol de trabajo; el orquestador confirma. Confirma solo después de que las compuertas pasen y el diff se sostenga. Si se necesita retrabajo, envía un brief delta con --resume-last o --session <id>, luego revisa de nuevo.

Autonomía y permisos

Pi no tiene entorno aislado ni modos de permisos. Una ejecución headless predeterminada lee, escribe, edita y ejecuta comandos de shell sin solicitudes - los controles son:

1. --read-only restringe las herramientas invocables de pi a --tools read,grep,find,ls en todas las herramientas integradas, de extensión y personalizadas. El código de extensión instalado aún se ejecuta con los permisos del host del usuario.
2. El relay pasa --no-approve por defecto, por lo que las configuraciones .pi, extensiones y skills del proyecto permanecen no confiables. --approve es la opción explícita para un repositorio que el usuario confía.
3. touchedFiles y el diff son el registro de lo que cambió. Inspecciónalos después de cada ejecución.

Modelo de autorización

La delegación es algo en lo que el humano opta. Una vez que lo ha hecho ("ejecuta esta cola", "procede"), confirmar trabajo verificado que pase las compuertas es el contrato acordado. Quedan dos límites: muestra, no absorbas (informa las decisiones de diseño de pi, giros defendibles pero no solicitados y críticas no bloqueantes) y detente por cambios de alcance (si la finalización correcta necesita ir más allá del brief, pregunta en lugar de expandir el mandato). Consulta references/review-and-land.md.

Referencias

• references/writing-the-brief.md - estructura, contrato de informe, compuertas reales, entrega por entrada estándar y briefs delta.
• references/dispatch-and-poll.md - banderas, artefactos, result.json, sondeo y recuperación de fallos.
• references/review-and-land.md - lista de verificación de revisión, límite de confirmación y retrabajo a través de sesiones de pi.
• references/multi-task-queues.md - colas secuenciales, arrastre de restricciones, seguimiento de progreso y el pase de coherencia final.