plan-orquestar

¿Qué hace plan-orquestar?

Puente entre un documento de plan y /orchestrate custom emitiendo una invocación lista para pegar por paso. La habilidad es solo generativa — nunca ejecuta /orchestrate. El usuario pega cada línea cuando esté listo.

Cuándo activar

• El usuario tiene un documento de plan de varios pasos (PRD, RFC, plan de implementación) y quiere ejecutarlo mediante /orchestrate.
• El usuario dice "orquestar este plan", "dame prompts de orchestrate para cada paso", "compón cadenas para este plan".
• Existe un plan paso a paso pero el usuario no quiere seleccionar agentes manualmente por paso.

Saltar cuando:

• El trabajo es un paso ad-hoc → llamar /orchestrate custom directamente.
• El plan es ilegible o está vacío. La falta de numeración explícita por sí sola no es condición de salto — ver el caso límite "Sin pasos claros" más abajo.

Entradas

<ruta-plan> [--lang=python|typescript|go|rust|cpp|java|kotlin|flutter|auto] [--scope=all|step:<n>|range:<a>-<b>] [--dry-run]

• <ruta-plan> — obligatorio; ruta relativa o absoluta (se acepta @docs/...).
• --lang — variante de lenguaje del revisor; por defecto auto (detectado del proyecto).
• --scope — limita los pasos emitidos; por defecto all.
• --dry-run — imprime solo la descomposición y la justificación de la cadena; no emitir prompts finales.

Forma autorizada de /orchestrate (no desviarse)

{ORCH_CMD} custom "<agente1>,<agente2>,...,<agenteN>" "<descripción de la tarea>"

Donde {ORCH_CMD} se determina en la Fase 0 (ver más abajo). La cadena de comando en la salida emitida siempre usa una forma concreta — nunca ambas, nunca un marcador de posición.

• custom es una cadena secuencial; la TRANSFERENCIA de cada agente alimenta al siguiente.
• Lista de agentes separada por comas. Sin espacios preferiblemente; se tolera un espacio.
• No existen banderas --mode / --gate / --agents=... — nunca inventarlas.
• Los nombres de agentes provienen del catálogo de esta habilidad. Las comillas dobles incrustadas en la descripción de la tarea se escapan como \".

Forma de instalación de ECC y espacios de nombres

Dos formas de instalación determinan el prefijo tanto en el comando slash como en cada nombre de agente. Las dos DEBEN mantenerse sincronizadas — una forma por salida, nunca mezcladas:

Sea <home-claude> el directorio home de Claude Code: ~/.claude en macOS/Linux, %USERPROFILE%\.claude en Windows. Resuélvelo como la plataforma anfitriona resuelve el directorio home del usuario (no codificar ~).

Forma	Detección	{ORCH_CMD}	Formato del nombre del agente
Instalación como plugin (2.0.0+)	<home-claude>/plugins/marketplaces/ecc/ existe	/ecc:orchestrate	ecc:<nombre>
Instalación básica heredada	Lo anterior ausente; archivos de agente bajo <home-claude>/agents/	/orchestrate	<nombre>

Por qué importa: bajo la instalación como plugin, los agentes se registran como ecc:tdd-guide. Los nombres simples fuerzan coincidencias difusas, que fallan intermitentemente bajo llamadas paralelas. Bajo el legado, las formas prefijadas no están registradas y fallan directamente.

Catálogo de agentes disponibles (debe elegir de estos)

Generales:

• planner — reformulación de requisitos, descomposición de riesgos, planificación de pasos
• architect — arquitectura, diseño de sistemas, propuestas de refactorización
• tdd-guide — escribir pruebas → implementar → 80%+ cobertura
• code-reviewer — revisión de código genérica
• security-reviewer — auditoría de seguridad, OWASP, fuga de secretos
• refactor-cleaner — código muerto, duplicados, limpieza tipo knip
• doc-updater — documentación, mapa de código, README
• docs-lookup — consultas de API de bibliotecas de terceros (Context7)
• e2e-runner — orquestación de pruebas extremo a extremo
• database-reviewer — esquema PostgreSQL, migración, rendimiento
• harness-optimizer — configuración local del arnés de agente
• loop-operator — bucles autónomos de larga duración
• chief-of-staff — triaje multicanal (rara vez adecuado para pasos de plan)

Resolvedores de errores de compilación:

• build-error-resolver (genérico) / cpp-build-resolver / go-build-resolver / java-build-resolver / kotlin-build-resolver / rust-build-resolver / pytorch-build-resolver

Revisores de código:

• python-reviewer / typescript-reviewer / go-reviewer / rust-reviewer / cpp-reviewer / java-reviewer / kotlin-reviewer / flutter-reviewer

Un nombre de agente mal escrito falla /orchestrate. Verificar contra esta lista antes de emitir.

Cómo funciona

Fase 0 — Detectar modo ECC + lenguaje

1. Leer <ruta-plan>. Si falta o está vacío, informar y detenerse.

2. Detectar la forma de instalación de ECC una vez y congelarla en MODO_ECC. Algoritmo (ejecutar en orden, detenerse en la primera coincidencia):

   1. Si <home-claude>/plugins/marketplaces/ecc/ existe → MODO_ECC=plugin.
   2. Si no, si <home-claude>/agents/ existe y contiene al menos un archivo de agente ECC (por ejemplo tdd-guide.md, code-reviewer.md) → MODO_ECC=legacy.
   3. Si no → por defecto MODO_ECC=legacy y emitir una advertencia de una línea al inicio de la salida: > Advertencia: no se pudo detectar la instalación de ECC; usando la forma heredada por defecto. Si usas la instalación como plugin, edita los prefijos manualmente.
   4. Si ambos marcadores existen (instalación mixta), plugin gana — el espacio de nombres del plugin es el único que resuelve nombres de agentes sin coincidencias difusas.

   A partir de este punto, cada línea emitida usa el prefijo correspondiente tanto en el comando slash como en cada nombre de agente. Nunca emitir ambas formas en la misma salida.

3. Resolver --lang. Cuando es auto, ejecutar una detección políglota:

   • Probar marcadores: pyproject.toml / uv.lock / requirements.txt → python; package.json → typescript; go.mod → go; Cargo.toml → rust; CMakeLists.txt o *.cpp de nivel superior → cpp; pom.xml / build.gradle (Java) → java; build.gradle.kts o Kotlin de nivel superior → kotlin; pubspec.yaml → flutter.
   • Desempate políglota: si más de un marcador coincide, elegir el lenguaje cuyos archivos fuente superen en número a los demás (contar con git ls-files, excluyendo vendor/, node_modules/, dist/, build/, .venv/, archivos generados y accesorios de prueba obvios). En caso de empate o cuando ningún lenguaje supere el 60% de los archivos fuente, establecer lang=unknown.
   • Sin marcador coincidente → establecer lang=unknown.
   • lang=unknown es un centinela — no es un nombre de agente. Las reglas 4 y 5 de la Fase 2 lo convierten en code-reviewer / build-error-resolver al momento de componer la cadena.

4. Detectar un sub-perfil PyTorch: cuando lang=python y cualquiera de pyproject.toml / requirements.txt / uv.lock declara una dependencia de torch, establecer pytorch=true. Esto solo afecta la selección de la cadena build (regla de Fase 2 más abajo); el revisor sigue siendo python-reviewer.

5. Normalizar cualquier nombre de agente declarado en el plan: si el texto del plan referencia agentes por su forma prefijada del plugin (por ejemplo ecc:tdd-guide), eliminar el prefijo para obtener el nombre del catálogo antes de validar o componer cadenas. El re-prefijado ocurre solo en el momento de la salida según MODO_ECC (Fase 4). Nunca permitir que un nombre prefijado fluya hacia la composición de la cadena — se prefijaría doblemente en modo plugin.

Fase 1 — Descomponer pasos

Identificar "unidades de paso" en orden de prioridad:

1. Numeración explícita: ## Paso N / ### Fase N / ## N. ... / lista ordenada de nivel superior.
2. Una columna "Paso" en una tabla.
3. Bloques separados por --- con encabezados que comienzan con verbo.
4. De lo contrario, tratar cada H2 como un paso.

Por paso extraer id (basado en 1), título (≤ 80 caracteres), intención (1–3 oraciones), etiquetas.

Fase 2 — Etiquetar y elegir cadena

Etiquetar por intención (multi-etiqueta permitida; la cadena se construye a partir de la primaria + secundarias apiladas):

Las palabras desencadenantes a continuación se comparan sin distinción de mayúsculas/minúsculas. Los planes multilingües se admiten haciendo coincidir las raíces de las palabras en cualquier idioma siempre que el significado se alinee con las palabras desencadenantes en inglés listadas.

Etiqueta	Palabras desencadenantes	Cadena predeterminada
design	architecture, design, choose, evaluate, RFC	planner,architect
plan	plan, breakdown, milestone	planner
impl	implement, build, add, create, port	tdd-guide,<lang>-reviewer
test	test, coverage, e2e, integration	tdd-guide,e2e-runner
refactor	refactor, cleanup, dedupe, split	architect,refactor-cleaner,<lang>-reviewer
migration	migrate, upgrade, rewrite, port	architect,tdd-guide,<lang>-reviewer
db	schema, migration, index, SQL, Postgres, alembic, sqlmodel	database-reviewer,<lang>-reviewer
security	encrypt, auth, secret, OWASP, PII	security-reviewer,<lang>-reviewer
build	build, compile, lint failure, CI	<lang>-build-resolver (fallback a build-error-resolver)
docs	docs, readme, codemap, changelog	doc-updater
lookup	lookup, reference, API usage	docs-lookup
review	review, audit, verify	<lang>-reviewer,code-reviewer
loop	loop, autonomous, watchdog	loop-operator

Reglas de composición de cadenas:

1. Selección de etiqueta primaria: cuando un paso coincide con múltiples etiquetas, la primera en orden de la tabla (parte superior de la tabla = mayor prioridad) es la primaria; el resto son secundarias. Las reglas de composición 2 y 3 a continuación manejan combinaciones específicas de múltiples etiquetas explícitamente; de lo contrario, agregar cadenas secundarias en orden de la tabla de etiquetas.
2. impl + security → tdd-guide,<lang>-reviewer,security-reviewer.
3. impl + db → tdd-guide,database-reviewer,<lang>-reviewer.
4. Desduplicar la cadena resultante (conservar la primera aparición). Por ejemplo, review + lang=unknown daría code-reviewer,code-reviewer después de la regla 5; la desduplicación lo reduce a code-reviewer.
5. <lang>-reviewer se resuelve como code-reviewer cuando lang=unknown.
6. <lang>-build-resolver se resuelve como build-error-resolver cuando lang=unknown. Caso especial: si la Fase 0 estableció pytorch=true, usar pytorch-build-resolver para cadenas build independientemente de <lang>. No existe python-build-resolver; --lang=python sin pytorch=true se resuelve como build-error-resolver.
7. Pasos sin etiquetas: si ninguna palabra desencadenante coincide, establecer la cadena como code-reviewer y escribir no se encontró etiqueta; cadena solo de revisión por defecto bajo "Justificación de la cadena".
8. Longitud de la cadena ≤ 4 después de la desduplicación. Si se excede, eliminar la etiqueta más débil (lookup y docs primero).
9. No emparejar planner y architect en una cadena impl (desperdicio de tokens). Emparejarlos solo en pasos design.
10. Los pasos etiquetados impl, refactor o migration terminan con un agente de clase revisor — cualquiera de <lang>-reviewer, code-reviewer, security-reviewer o database-reviewer. El revisor más específico del dominio gana la posición final (por ejemplo, la regla 2 impl+security termina con security-reviewer; la regla 3 impl+db termina con <lang>-reviewer porque database-reviewer ya controla la migración antes en la cadena). Los pasos test y build están controlados por sus propios validadores (e2e-runner y el resolvedor de compilación respectivamente) y no requieren un revisor adicional.

Fase 3 — Comprimir descripción de la tarea

Cada <descripción de la tarea> emitida debe:

• Ser autocontenida (el primer agente no necesita tener el documento del plan abierto).
• Comenzar con [Plan: <ruta>#step-<id>].
• Incluir de 1 a 3 criterios de aceptación verificables.
• Incluir un guardia de alcance (Fuera de alcance: ...) solo si el plan declara uno para este paso. Heredar textualmente. Si el plan no tiene una declaración de fuera de alcance, omitir la cláusula por completo — no inventar una.
• Tener de 200 a 600 caracteres; una línea; comillas " incrustadas escapadas como \"; sin saltos de línea literales.

Fase 4 — Salida

Emitir Markdown usando la forma determinada por MODO_ECC. La salida usa una forma en todo momento — cada {ORCH_CMD} y cada nombre de agente se renderiza con el prefijo correspondiente de la Fase 0. No emitir ambas formas; no incluir instrucciones "esta es forma de plugin" / "eliminar el prefijo" en la salida renderizada.

Reglas de renderizado concretas:

• {ORCH_CMD} = /ecc:orchestrate bajo plugin, /orchestrate bajo legacy.
• {AGENTE(nombre)} = ecc:<nombre> bajo plugin, <nombre> bajo legacy.
• La columna "Cadena" de la tabla de resumen usa la misma renderización {AGENTE(nombre)}.
• Los bloques bash por paso contienen solo el comando ejecutable. Sin comentarios # forma plugin o # forma legacy — la forma es implícita y uniforme en toda la salida.

Estructura de la salida:

# Resultado de Plan-Orquestar

**Plan**: `<ruta>`
**Idioma**: `<detectado-o-dado>`
**Modo ECC**: `<plugin | legacy>`
**Pasos**: <N>
**Alcance**: <all | step:n | range:a-b>

## Resumen de pasos

| # | Título | Etiquetas | Cadena |
|---|---|---|---|
| 1 | ... | impl, db | `{AGENTE(tdd-guide)},{AGENTE(database-reviewer)},{AGENTE(python-reviewer)}` |
| ... | | | |

---

## Paso 1 — <título>

**Intención**: <1–3 oraciones>
**Etiquetas**: <a, b>
**Justificación de la cadena**: <por qué esta cadena; qué agente cierra el ciclo>

```bash
{ORCH_CMD} custom "{AGENTE(tdd-guide)},{AGENTE(database-reviewer)},{AGENTE(python-reviewer)}" "[Plan: docs/foo.md#step-1] <descripción comprimida de la tarea>; Aceptación: <1–3 ítems>; Fuera de alcance: <…>"
```

La notación {ORCH_CMD} y {AGENTE(...)} arriba describe la sustitución que esta habilidad realiza en tiempo de ejecución. El Markdown realmente emitido contiene las cadenas resueltas, nunca los marcadores de posición.

Agregar un bloque final de "Ejecución por lotes" que agregue el comando de cada paso en orden para que el usuario pueda pegarlos todos a la vez. Omitir el bloque por lotes en modo solo resumen (ver caso límite "Plan grande"): cuando solo se emite la tabla de resumen, no hay comandos por paso que agregar.

Fase 5 — Autoverificación (ejecutar antes de emitir)

• Cada agente en cada cadena proviene del catálogo (después de eliminar cualquier prefijo ecc: que apareciera en el plan; ver Fase 0 paso 5).
• El {ORCH_CMD} resuelto y cada {AGENTE(...)} resuelto usan la misma forma (plugin o legacy) — nunca mezclados en una misma salida.
• Sin anotaciones # forma plugin / # forma legacy ni instrucciones "eliminar el prefijo" en la salida renderizada.
• Sin campos inventados --mode / --gate / --agents=....
• Cada descripción de tarea es de una sola línea, entre comillas dobles, con comillas incrustadas escapadas.
• Cada descripción de tarea comienza con [Plan: <ruta>#step-<id>] e incluye Aceptación (1–3 ítems). La cláusula Fuera de alcance: está presente solo cuando se hereda del plan.
• Sin agente duplicado en ninguna cadena después de la desduplicación de la Fase 2.
• Longitud de la cadena ≤ 4.
• Los pasos etiquetados impl/refactor/migration terminan con un agente de clase revisor (<lang>-reviewer, code-reviewer, security-reviewer o database-reviewer). Los pasos test/build terminan con su validador específico.
• Cada paso tiene al menos una etiqueta (por defecto review).

Casos límite

Sin pasos claros

El plan carece de divisiones explícitas (H2, numeración). En este caso, tratar todo el plan como un solo paso con id=1 y título "Análisis completo del plan". Elegir la cadena según las etiquetas dominantes detectadas en todo el documento.

Plan grande

15 pasos. Presentar solo la tabla de resumen y solicitar confirmación antes de emitir los bloques bash por paso. El mensaje debe decir explícitamente: "Este plan tiene N pasos. ¿Quieres que genere las invocaciones completas de /orchestrate para cada paso (s/n)?" Si la respuesta es negativa, detenerse después de la tabla. El bloque de ejecución por lotes nunca se emite en modo solo resumen.

Plan sin extensión de archivo

El usuario pasa una ruta sin extensión o un contenido en línea. Intentar detectar el formato por el contenido (JSON → buscar claves steps, phases, milestones; Markdown → analizar como de costumbre; texto sin formato → tratar como análisis de pasos básico). Si falla, informar y pedir una ruta de archivo.

Políglota verdadero

El proyecto contiene marcadores para múltiples lenguajes pero la repartición de archivos reales está equilibrada (ningún lenguaje supera el 60%). lang=unknown como se describe arriba. Los pasos reciben revisores genéricos a menos que el usuario pase --lang explícitamente.

---

Registro de cambios

• v1 — implementación inicial que une plan documentado y /orchestrate.