A-ISL Compile (compilador dentro del agente)
Emites archivos bin-<stackId>/ desde ISL (pila por defecto react-js → bin-react-js). Están permitidos los CLIs builder / queue / packet / lock / preflight. El uso de isl-generator / Gemini / OpenAI de pago está prohibido.
Funciona con cualquier agente de codificación que cargue este skill (Cursor, Claude Code, GitHub Copilot, …). Mismo runtime npm desde la raíz del repositorio.
Puerta de solicitud del usuario (no negociable)
La modificación de bin solo se realiza mediante compile y solo, por supuesto, a petición del usuario.
- Entra en este skill / escribe bajo
bin-*solo cuando el humano pida explícitamente compilar (ej: "compila", "/a-isl-compile", "build bin", "regenerate implementation", "run compile for …"). - Mensajes solo de especificación, ideas de funcionalidades en lenguaje natural o ajustes de UX sin una solicitud explícita de compilación NO DEBEN desencadenar escrituras de implementación — envíalos a a-isl-spec-author (o fase de Spec) y detente.
- No compiles automáticamente después de ediciones de Spec "porque la demo se rompería" o "para completar el ciclo".
- Las carpetas de implementación se actualizan solo a través de este flujo de trabajo Compile (packet → write → lock). No trates parches ad-hoc bajo
bin-*como la ruta A-ISL a menos que el humano pida explícitamente una excepción única. - Si el humano no ha pedido compilar: rechaza editar
bin-*y dile que necesita una solicitud explícita de compilación.
Cuándo usarlo
- El humano terminó la fase Spec y pide construir/compilar/regenerar
- Alinear el
bin-<stack>/de un proyecto con los*.isl.mdactualizados porque el humano solicitó Compile
Restricciones estrictas
- No ejecutes generadores de pago o clientes de codegen API.
- Tú escribes cada archivo de implementación bajo el directorio bin de la pila desde el
targetPathdel packet (código completo, sin stubs TODO). - Actualizar
gen-lock.jsonsolo no es compilación — solo haz lock después de escrituras reales bajobin-<stack>/. - Si ISL es ambiguo o contradictorio: detente e indica al usuario que vuelva a a-isl-spec-author. No inventes requisitos.
- No abras
vendor/isl-spec/durante Compile (solo Spec Agent), a menos que el usuario lo pida explícitamente. - Prefiere una unidad a la vez mediante
queue --next+ packet ligero. No cargues el JSON completo de la cola o el.build.mdcompleto por defecto.
Directorio de salida
Por defecto: bin-<stackId> junto a las especificaciones (ej: --stack react-js → bin-react-js). Sobrescribir con --bin si es necesario. El mismo espacio de trabajo puede contener bin-react-js y bin-csharp uno al lado del otro.
Flujo de trabajo de bajo consumo de tokens (por defecto)
preflight → builder (una vez) → bucle: queue --next → packet → [tests luego] write impl → (batch) lock
→ (opcional) npm run verify
0. Preflight (una vez)
npm run preflight -- --root examples/connect-four-workspace
Solo puerta estructural/gráfico/lint — no prueba la corrección de la implementación. Si falla, corrige Spec/lint antes de compilar.
1. Builder (una vez por lote)
npm run builder -- examples/connect-four-workspace
El orden topológico vive en build/build-manifest.json (propiedad del script). No inventes el orden de compilación.
2. Solo la siguiente unidad
npm run queue -- --root examples/connect-four-workspace --next
Pasa --stack <id> en cada llamada queue/packet en el bucle (por defecto react-js → bin-react-js/):
npm run queue -- --root <project> --next --stack blazor
npm run packet -- --root <project> --next --stack blazor
Ids: react-js, blazor, winforms, csharp (solo biblioteca), python, python-fastapi. Opcional --bin <path> sobrescribe la carpeta de salida.
Recompilación dirigida — cuando el humano pide regenerar una o unas pocas unidades (el lock las saltaría si no):
npm run queue -- --root <project> --next --only dungeon --stack react-js
npm run packet -- --root <project> --next --only dungeon --stack react-js
# o packet por nombre:
npm run packet -- --root <project> --only dungeon --stack react-js
--only puede repetirse. Tokens: nombre base de la unidad (dungeon), dungeon.isl.md, o ./dungeon. Razón en JSON de cola: force-only. No uses --force a nivel de workspace cuando solo se solicita un subconjunto.
Usa next.buildFile / next.targetPath. Si next es null, detente (cola vacía).
Usa el queue completo --json solo cuando el humano pide una vista general.
3. Packet ligero (contexto por defecto)
npm run packet -- --root examples/connect-four-workspace --build-file "<abs.build.md>"
# o
npm run packet -- --root examples/connect-four-workspace --next
El packet incluye: SOURCE markdown para esta unidad, ruta objetivo, subconjunto de restricciones de pila, rutas a archivos de dependencia en el mismo bin-<stack>/.
Excluye blobs inline .ref.md.
Escribe archivos desde el packet (ver orden EXT-001 abajo). Importa módulos de dependencia reales desde las rutas listadas.
3a. Búsqueda de declaración de dependencia (EXT-002)
Cuando necesites la declaración exacta de un símbolo de dependencia (método / función / tipo) antes de escribir esta unidad:
npm run lookup-decl -- --stack <id> --name <NombreSpecOCall> --file <ruta-abs-o-rel-bin> [--workspace <project>]
# o escanea una carpeta bin (archivos generados *.test.* / *.Tests.cs se saltan a menos que --include-tests):
npm run lookup-decl -- --stack <id> --name <Nombre> --dir <bin-<stack>> --workspace <project>
- Salida 0 = acierto, 2 =
no_match, 3 = error de uso / ruta / pila. - Lee stdout JSON: usa
candidates[selected](signatureText,leadingContext,enclosingType,kindpor candidato). No inventes expresiones regulares ni abras todo el archivo de dependencia para buscar firmas. - Los patrones y
callSymbolviven en la configuración de la pila (declaration-patterns.ts/stacks.config.ts) — el skill debe solo invocar este CLI. - Las rutas deben resolverse bajo
--workspacey un segmentobin-*(escape de symlink → salida 3).
3b. EXT-001 Pruebas generadas (cuando Spec opta por ello)
Escenarios verificables = Escenarios de Prueba con tanto `id: …` como - Call: … (ver docs/isl-agent-profile.md). El Autor de Spec decide; cualquier rol puede optar.
Por unidad, mismo turno:
- Si SOURCE tiene ≥1 escenario elegible: sobrescribe el archivo de prueba generado primero (ruta = nombre base de impl +
stack.verify.testSuffixbajo el mismobin-<stack>/, ej:domain-sheet.test.js/domain-sheet.Tests.cs). Afirma solo desde escenarios de Spec + Firma; mapeaCall→ símbolo víastack.verify.callSymbol(as-is|pascal-case|snake-caseenstacks.config.ts). react-js Domain/Logic: cada Call DEBE ser una exportación nombrada; las pruebas DEBENimport { <Call> } from "./<file>"— nuncaimport Unit from …; Unit().<Call>(). Si el workspace tienebench/call-map.json, resuelveexportdesde"<unidad>.<Call>"e importa ese nombre (mismo contrato que score congelado). No inventes casos para escenarios solo en prosa; no abras/edites el archivo de impl antes de escribir el archivo de prueba. - Luego escribe la impl en
targetPathpara que satisfaga esas pruebas y el Contrato. react-js Domain/Logic:export function <Call>/export const <Call>para cada Capacidad; PROHIBIDO exportar por defecto una fábrica que envuelva capacidades. - Si cero escenarios elegibles: solo escribe impl; elimina un archivo de prueba generado previamente para esa unidad si aún existe. Sigue usando exportaciones de capacidad nombradas para Domain/Logic.
- Si la verificación falla: puedes
--onlyrecompilar solo impl (mantén el archivo de prueba). NO DEBES reescribir pruebas para que pasen (incluyendo cambiar imports nombrados por fábricas por defecto). Si el escenario/Call/esperado parece incorrecto → DETENTE y envía al humano a a-isl-spec-author. - Después de un lote de Domain/Logic (u otro elegible), puedes sugerir
npm run verify -- --root <project> --stack <id>; no exijas verde para hacer lock. Lock sigue siendo un caché de hash de build.
Recompilación completa de unidad después de cambio de Spec: regenera el archivo de prueba completo desde el Spec actual, luego la impl (no una fusión con pruebas antiguas).
4. Lock (lote cuando sea posible)
Después de 1–5 escrituras exitosas:
npm run lock -- --root examples/connect-four-workspace --build-file "<abs1>" --build-file "<abs2>"
5. Agrupación por complejidad (higiene de contexto)
Una sesión larga de agente que compila muchas unidades tiende a subimplementar las últimas o paquetes grandes (contexto lleno de bins anteriores). Prefiere:
| Tipo de unidad | Cómo compilar |
|---|---|
| Hoja / pequeña | Mismo agente, lote de varios queue --next → write → lock |
| Pesada / hub | Agente fresco / nuevo chat: --only <unidad> → packet → implementa cada capacidad en SOURCE → lock |
| Reparación después de revisión/playtest | Agente fresco + --only en la(s) unidad(es) que fallan solamente |
Trata una unidad como pesada si se cumple alguna de estas (independiente de la pila):
- SOURCE largo / muchas capacidades
####en un.isl.md - Alto fan-in: muchas otras unidades la Referencian, o Referencia muchos deps
- Presentación o Lógica que orquesta una gran parte del grafo (shell / facade / sesión límite)
- El packet o compilación previa de esa unidad tiene historial de Flows omitidos
No generes un agente por hoja por defecto (costo). No ejecutes todo un workspace grande en un solo agente sin refrescar en hubs.
Indicación para una unidad pesada: raíz del repo, --stack, --only <unidad>, "implementa cada capacidad en SOURCE; sin Flows omitidos." Sigue agent-skills/a-isl-compile/SKILL.md (o la copia host bajo .cursor/skills, .claude/skills, o .github/skills).
Tabla de escalada (cuando el acceso ligero no es suficiente)
| Situación | Acción |
|---|---|
| Packet ok, bins de dep existen, ISL claro | Solo ligero → escribe archivo |
Salida de packet / missingDependencyBins | DETENTE — corrige cola/orden; no inventes APIs |
| Necesitas declaración/firma exacta de un dep | npm run lookup-decl (EXT-002); usa JSON selected — no inventes APIs |
lookup-decl salida 2 (no_match) | Revisa Spec Call/nombre + ruta del dep; no inventes firmas |
| Packet incompleto / sin marcador SOURCE | Lee el fullBuildFile de esta unidad una vez |
| ISL ambiguo / contradictorio | DETENTE → Spec Agent; sin inmersión en vendor |
| Humano solicita auditoría de reconstrucción completa | --force / queue completo --json permitido |
Reglas de escritura por unidad
Encabezado en cada archivo generado:
/**
* DO NOT EDIT THIS FILE DIRECTLY
* ----------------------------------
* This file was generated by ISL Compiler.
* Source: <nombre-base-del-.isl.md>
* Edita el archivo ISL en su lugar.
*/
Sigue las reglas de la pila (react-js por defecto). Implementación completa — sin stubs TODO.
Rutas
| Herramienta | Entrada |
|---|---|
| Preflight | npm run preflight -- --root <project> |
| Builder | npm run builder -- <project> |
| Queue next | npm run queue -- --root <project> --next |
| Packet | npm run packet -- --root <project> --next |
| Lock | npm run lock -- --root <project> --build-file <abs>… |
| Verify | npm run verify -- --root <project> [--stack <id>] [--only <unit>] |
| Lookup decl | `npm run lookup-decl -- --stack --name --file |
| Lint | npm run lint -- <file.isl.md> |