Orquestrador de Requisitos

Orquestador de Requisitos

Convierte una solicitud de software en trabajo verificable de forma independiente, manteniendo un único agente controlador responsable del alcance, dependencias, evidencia e integración. Esta skill es un orquestador, no un generador de instrucciones.

Selecciona un modo semántico

• analyze: investiga la solicitud y la base de código, mantiene el libro de registro y produce un plan de ejecución sin modificar código. Es el modo predeterminado cuando no se ha solicitado implementación.
• diagnose: reproduce y explica un fallo notificado, separando la causa raíz confirmada, la evidencia, las incógnitas y las rutas de reparación recomendadas. El diagnóstico es el entregable; no modifiques código.
• execute: despacha trabajo acotado, revisa los resultados devueltos y completa la integración. Entra solo cuando el usuario haya autorizado la implementación o ejecución.
• challenge: prueba un requisito, descomposición o diseño existente en busca de omisiones y riesgos sin cambiar su objetivo de producto confirmado. Consulta references/challenge.md.

Estos son modos semánticos a nivel de skill. No invocan ni requieren el Modo Plan nativo de una plataforma, EnterPlanMode o agentes obligatorios de Exploración/Plan. Usa los modos nativos solo cuando sean independientemente útiles y compatibles con las restricciones del usuario.

Para una tarea de causa raíz única sin delegación, usa el bucle de control directamente. Lee references/spec-driven.md para dar forma a la especificación (requisitos, escenarios de aceptación, contratos). Lee references/context-grounding.md antes de descomponer en una base de código existente. Lee references/decomposition.md cuando haya más de una tarea candidata, un límite de servicio/dominio, una decisión de planificación o un fallo de construcción/despliegue donde el estado del repositorio pueda ser causal. Lee references/verification.md para los estándares de evidencia de aceptación. Lee references/ledger.md cuando el trabajo tenga múltiples tareas, agentes, sesiones o plataformas. Lee references/mutation.md cuando la ejecución reescriba, elimine o propague un cambio a través de más de un artefacto existente, o escriba en un sistema externo. Ejecuciones trabajadas: references/examples/feature-example.md y references/examples/bug-example.md.

En diagnose, informa el fallo observado o reproducido, la causa raíz confirmada y la evidencia, los elementos no verificados, el impacto y las rutas de reparación recomendadas. Detente ahí a menos que el usuario autorice por separado execute.

Bucle de control

1. Establece el objetivo, alcance, criterios de aceptación, restricciones y hechos de código verificados. Fundamenta primero las incógnitas (references/context-grounding.md), luego expresa el resultado como una especificación: requisitos, escenarios de aceptación y contratos (references/spec-driven.md). Investiga los hechos descubribles; pregunta al usuario solo por las decisiones que afecten materialmente el alcance, la aceptación o la dirección. Antes de descomponer, consulta la base de conocimiento de capacidades (ver references/knowledge-base.md) para extraer las habilidades existentes relevantes para el objetivo y una comparación del mismo dominio; prefiere reutilizar o importar una capacidad conocida en lugar de investigar desde cero, y registra las capacidades elegidas en el libro de registro.
   • Lee las lecciones de proyectos anteriores si existen (references/experience.md) y trátalas como hechos candidatos a verificar, no como dogma.
   • Para una construcción no trivial, después de la especificación produce un diseño técnico (references/tech-design.md) — arquitectura, diseño detallado, alternativas, preocupaciones transversales — y persiste los artefactos bajo el diseño docs/ (references/deliverables.md).
2. Para un error o fallo notificado, intenta una reproducción local proporcionada antes de afirmar una causa raíz. Compara el fallo observado con el informe. Hasta que se reproduzca o esté respaldado por evidencia directa equivalente, etiqueta las declaraciones de causa raíz como hipótesis y expresa lo que permanece sin verificar.
3. Elige un eje de descomposición primario y crea tareas acotadas. Deriva los contratos compartidos y congelalos antes del trabajo dependiente o en paralelo (references/spec-driven.md). Registra las dependencias y los contratos entre tareas explícitamente. Refleja los grupos de tareas resultantes en un TODO por fases (ver Superficie de progreso).
4. Mantén exactamente un agente controlador. El controlador es propietario del libro de registro, las decisiones de despacho, el estado de revisión, la replanificación y la integración final.
5. Despacha solo tareas con un contrato completo. Lee references/agent-contract.md antes del primer despacho. Antes de despachar escrituras a cualquier sistema más allá del árbol de trabajo local, ejecuta la verificación previa del sistema de destino a continuación.
6. Acepta un resultado de trabajador en review, verifica su evidencia y límites contra los estándares de evidencia de aceptación (references/verification.md), luego márcalo como completed o devuélvelo con hallazgos específicos. Para una mutación masiva o externa, verifica mediante una lectura de retorno independiente y un delta estructural, no el recuento de éxito informado por la herramienta.
7. Recalcula las dependencias afectadas después de descubrimientos, fallos o cambios de alcance. Reelabora la rama afectada más pequeña.
8. Declara la solicitud completa solo después de que las comprobaciones a nivel de tarea, los contratos entre tareas y cada escenario de aceptación pasen juntos; la puerta de extremo a extremo se define en references/verification.md. Al completar, añade cualquier lección calificativa específica del proyecto al registro de experiencias (references/experience.md). Mejorar la propia skill a partir de la ejecución es una acción optativa separada — ofrecida solo cuando una lección es general y recurrente, aplicada solo si el usuario la elige, nunca automática (ver references/experience.md).

Superficie de progreso

Mantén un TODO por fases visible sincronizado con el libro de registro para que el usuario vea el progreso a nivel de fase y paso, no solo prosa. El libro de registro sigue siendo la fuente de verdad detallada (dependencias, alcances, contratos, evidencia); el TODO por fases es su vista de progreso.

• Inicializa una fase por grupo de descomposición, luego una fase de aceptación final (para un flujo de error, Diagnóstico / Reparación / Verificación; para un flujo de funcionalidad, los grupos de funcionalidad seguidos de Aceptación completa). Cada elemento es una tarea acotada o paso de verificación, expresado como un resultado en 5–10 palabras.
• Impúlsalo con la lista de tareas nativa de la plataforma, nunca con un árbol formateado a mano. En Claude/omp usa la herramienta todo: init con list: [{phase, items}], luego start/done por elemento. En Codex usa su mecanismo de plan/actualización de plan.
• Avanza el estado a partir del progreso real: marca un elemento como en progreso cuando se despacha su tarea, y como completado solo después de que el controlador registre completed en el libro de registro. Los recuentos de fase (N/M) rastrean entonces la aceptación verificada, no el despacho.
• Mantén los dos consistentes: un elemento TODO corresponde exactamente a una tarea del libro de registro o paso de verificación. Recalcula ambos juntos durante la replanificación.
• En analyze y diagnose, las fases son pasos de investigación o diagnóstico y completarlos no modifica código.

Artefactos entregables

Separa los documentos publicables del estado de orquestación interno: los documentos orientados al lector van bajo docs/ (docs/prd/ especificación, docs/tech-design/ diseño); el libro de registro, el plan y las lecciones son estado de trabajo interno bajo .ai-work/ — nunca bajo docs/, y gitignorados para un proyecto publicable. Consulta references/deliverables.md.

Para cualquier construcción no trivial, produce un diseño técnico después de la especificación y antes de execute: arquitectura, diseño detallado, alternativas consideradas y preocupaciones transversales (references/tech-design.md). Omítelo para una corrección de causa raíz única donde la especificación más una lista de tareas sea suficiente.

Revisa por ti mismo cada entregable Markdown generado antes de la entrega: vuelve a leerlo y confirma que se renderiza como lo verá el lector — estructura intacta, los bloques delimitados/Mermaid realmente se analizan (repréntalos, no los mires), los enlaces se resuelven. Un fallo de análisis/renderización es un defecto que debes corregir ahora. Consulta references/deliverables.md y la fila Document / diagram artifact en references/verification.md.

Cuando el entregable sea un proyecto independiente, "completado" incluye ser publicable: un README (qué/por qué, requisitos previos, instalación, ejemplos de uso, configuración, arquitectura, prueba, limitaciones, licencia, descargo de responsabilidad), una LICENCIA y un .gitignore que excluya la salida de compilación, secretos y .ai-work/. Verifica que los comandos del README realmente se ejecuten. Consulta references/deliverables.md.

Verificación previa del sistema de destino

Antes de despachar escrituras a cualquier sistema que no sea el árbol de trabajo local — un wiki, sistema de tickets, base de datos o API remota — verifica de antemano:

• el permiso de escritura y el alcance exacto que necesitan las operaciones planificadas, incluyendo eliminar o mover si el plan lo requiere;
• los límites de velocidad y si los fallos son silenciosos; elige concurrencia segura y un reintento o retroceso;
• que el resultado se pueda leer de vuelta para verificar.

Descubre una capacidad faltante aquí, no a mitad del lote. Si un permiso o alcance requerido no está disponible, trátalo como un bloqueante: indica exactamente qué falta y la concesión más pequeña que desbloquea, y detente antes de cualquier aplicación parcial.

Enrutamiento de plataforma

• Para Codex, lee references/codex-adapter.md.
• Para Claude, lee references/claude-adapter.md.
• Al transferir el control entre ellos, escribe y confirma una instantánea de traspaso antes de que el controlador anterior deje de despachar.
• Trellis es opcional. Lee references/trellis-adapter.md solo cuando se apliquen sus señales de escalamiento o el usuario lo solicite.

Límites no negociables

Estos son invariantes de tipo NO DEBE, independientemente de la redacción; mantenlos pocos y precisos. En otras partes de esta skill, califica la fuerza de la regla con las palabras clave RFC 2119 — DEBE / DEBERÍA / PUEDE, significativas solo en mayúsculas — y úsalas con moderación: reserva DEBE / NO DEBE para corrección o daño, deja las preferencias como DEBERÍA / PUEDE. Acompaña cada prohibición con el "hacer en su lugar" positivo: para agentes, las reglas solo negativas no son fiables (incitan el comportamiento que prohíben), así que un pequeño conjunto de límites duros más valores predeterminados positivos es la forma robusta, no una lista de verificación obligatoria en constante crecimiento.

• No trates la posición en el árbol de tareas como dependencia de ejecución.
• No permitas que los trabajadores expandan su alcance de escritura silenciosamente.
• No ejecutes agentes de escritura en paralelo a menos que las dependencias estén resueltas, los alcances de escritura no se superpongan, los contratos compartidos estén congelados y la validación sea independiente.
• Un trabajador puede enviar trabajo para revisión; solo el controlador puede marcarlo como completado.
• Al cambiar artefactos existentes, no borres y reescribas nada que la tarea no haya creado y no pueda regenerar; inserta o parchea en el lugar, márcalo con un marcador seguro para reejecución y verifica mediante lectura de retorno independiente.
• No afirmes un valor derivado (clasificación, etiqueta, resumen, calificación de riesgo o recomendación) más allá de su fuente verificada; marca una derivación no verificada como tal en lugar de inventar un valor.
• No actives Trellis simplemente porque exista .trellis/.
• analyze y diagnose son de solo lectura. Un permiso de plataforma o aprobación de plan nativo no autoriza ediciones. Entra en execute solo después de una instrucción separada del usuario que autorice la implementación.
• No entregues un entregable sin consumirlo como lo haría su lector: renderiza el documento y ejecuta los comandos README/uso desde la raíz del repositorio exactamente como están escritos. (Haz en su lugar: renderiza diagramas, ejecuta los comandos, corrige las roturas antes de la entrega).
• No llames completado a un proyecto independiente sin un README funcional, LICENCIA y .gitignore, o con artefactos internos .ai-work/ confirmados. (Haz en su lugar: envía el andamio publicable; mantén el estado de orquestación fuera del repositorio).