A-ISL Compile (compilador no agente)
Você gera bin-<stackId> a partir de ISL (stack padrão react-js → bin-react-js). CLIs Builder / queue / packet / lock / preflight são permitidos. isl-generator / Gemini / OpenAI pagos são proibidos.
Funciona com qualquer agente de codificação que carregue esta habilidade (Cursor, Claude Code, GitHub Copilot, …). Mesmo runtime npm a partir da raiz do repositório.
Portão de solicitação do usuário (não negociável)
La modifica alla bin viene fatta solo tramite compile e solo ovviamente su richiesta dell'utente.
- Entre nesta habilidade / escreva em
bin-*apenas quando o humano pedir explicitamente para compilar (ex:compila,/a-isl-compile, "build bin", "regenerate implementation", "run compile for …"). - Mensagens apenas de Spec, ideias de funcionalidades em linguagem natural ou ajustes de UX sem uma solicitação explícita de compilação NÃO DEVEM acionar escrita de implementação — envie-os para a-isl-spec-author (ou fase de Spec) e pare.
- Não compile automaticamente após edições de Spec "porque a demo quebraria" ou "para finalizar o ciclo".
- As pastas de implementação são atualizadas apenas através deste fluxo de Compile (packet → write → lock). Não trate patches avulsos em
bin-*como o caminho A-ISL, a menos que o humano peça explicitamente uma exceção única. - Se o humano não pediu para compilar: recuse-se a editar
bin-*e diga que eles precisam de uma solicitação explícita de compilação.
Quando usar
- Humano terminou a fase de Spec e pede para construir/compilar/regenerar
- Alinhar o
bin-<stack>/de um projeto com*.isl.mdatualizados porque o humano solicitou Compile
Restrições rígidas
- Não execute geradores pagos ou clientes de codegen de API.
- Você escreve cada arquivo de implementação sob o diretório bin do stack a partir do
targetPathdo pacote (código completo, sem stubs TODO). - Atualizar
gen-lock.jsonsozinho não é compilação — apenas lock após escritas reais embin-<stack>/. - Se o ISL for ambíguo ou contraditório: pare e diga ao usuário para retornar a a-isl-spec-author. Não invente requisitos.
- Não abra
vendor/isl-spec/durante o Compile (apenas Spec Agent), a menos que o usuário peça explicitamente. - Prefira uma unidade por vez via
queue --next+ pacote leve. Não carregue o JSON completo da fila ou o.build.mdcompleto por padrão.
Diretório de saída
Padrão: bin-<stackId> ao lado das especificações (ex: --stack react-js → bin-react-js). Substitua com --bin se necessário. O mesmo workspace pode conter bin-react-js e bin-csharp lado a lado.
Fluxo de trabalho de baixo token (padrão)
preflight → builder (uma vez) → loop: queue --next → packet → [tests então] write impl → (batch) lock
→ (opcional) npm run verify
0. Preflight (uma vez)
npm run preflight -- --root examples/connect-four-workspace
Apenas portão estrutural/grafo/lint — não prova a correção da implementação. Se falhar, corrija Spec/lint antes de compilar.
1. Builder (uma vez por lote)
npm run builder -- examples/connect-four-workspace
A ordem topológica está em build/build-manifest.json (de propriedade do script). Você não inventa a ordem de compilação.
2. Apenas próxima unidade
npm run queue -- --root examples/connect-four-workspace --next
Passe --stack <id> em todas as chamadas queue/packet no loop (padrão 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 (apenas biblioteca), python, python-fastapi. Opcional --bin <path> substitui a pasta de saída.
Recompilação direcionada — quando o humano pede para regenerar uma ou algumas unidades (o lock as pularia):
npm run queue -- --root <project> --next --only dungeon --stack react-js
npm run packet -- --root <project> --next --only dungeon --stack react-js
# ou packet por nome:
npm run packet -- --root <project> --only dungeon --stack react-js
--only pode ser repetido. Tokens: nome base da unidade (dungeon), dungeon.isl.md, ou ./dungeon. Razão no JSON da fila: force-only. Não use --force em todo o workspace quando apenas um subconjunto é solicitado.
Use next.buildFile / next.targetPath. Se next for null, pare (fila vazia).
Use fila --json completa apenas quando o humano pedir uma visão geral.
3. Pacote leve (contexto padrão)
npm run packet -- --root examples/connect-four-workspace --build-file "<abs.build.md>"
# ou
npm run packet -- --root examples/connect-four-workspace --next
O pacote inclui: markdown SOURCE para esta unidade, caminho de destino, subconjunto de restrição de stack, caminhos para arquivos de dependência no mesmo bin-<stack>/.
Exclui blobs .ref.md inline.
Escreva arquivos a partir do pacote (veja ordem EXT-001 abaixo). Importe módulos de dependência reais dos caminhos listados.
3a. Consulta de declaração de dependência (EXT-002)
Quando você precisar da declaração exata de um símbolo de dependência (método / função / tipo) antes de escrever esta unidade:
npm run lookup-decl -- --stack <id> --name <SpecOrCallName> --file <abs-or-rel-bin-path> [--workspace <project>]
# ou escaneie uma pasta bin (arquivos *.test.* / *.Tests.cs gerados são ignorados a menos que --include-tests):
npm run lookup-decl -- --stack <id> --name <Name> --dir <bin-<stack>> --workspace <project>
- Saída 0 = encontrado, 2 =
no_match, 3 = erro de uso / caminho / stack. - Leia o JSON stdout: use
candidates[selected](signatureText,leadingContext,enclosingType,kindpor candidato). Não invente regexes ou abra o arquivo de dep inteiro para caçar assinaturas. - Padrões e
callSymbolestão na configuração do stack (declaration-patterns.ts/stacks.config.ts) — a habilidade deve apenas invocar esta CLI. - Os caminhos devem ser resolvidos sob
--workspacee um segmentobin-*(escape de symlink → saída 3).
3b. EXT-001 Testes gerados (quando Spec opta por participar)
Cenários verificáveis = Cenários de Teste com ambos `id: …` e - Call: … (veja docs/isl-agent-profile.md). O Autor de Spec decide; qualquer função pode optar por participar.
Por unidade, no mesmo turno:
- Se SOURCE tem ≥1 cenário elegível: substitua o arquivo de teste gerado primeiro (caminho = nome base da impl +
stack.verify.testSuffixsob o mesmobin-<stack>/, ex:domain-sheet.test.js/domain-sheet.Tests.cs). Afirme apenas a partir de cenários Spec + Assinatura; mapeieCall→ símbolo viastack.verify.callSymbol(as-is|pascal-case|snake-caseemstacks.config.ts). react-js Domain/Logic: cada Call DEVE ser uma exportação nomeada; testes DEVEMimport { <Call> } from "./<file>"— nuncaimport Unit from …; Unit().<Call>(). Se o workspace tembench/call-map.json, resolvaexportde"<unit>.<Call>"e importe esse nome (mesmo contrato do score congelado). Não invente casos para cenários só em prosa; não abra/edite o arquivo de impl antes do arquivo de teste ser escrito. - Em seguida, escreva a impl em
targetPathde modo que satisfaça esses testes e o Contrato. react-js Domain/Logic:export function <Call>/export const <Call>para cada Capability; PROIBIDO factory de exportação padrão encapsulando capabilities. - Se zero cenários elegíveis: escreva apenas a impl; delete um arquivo de teste gerado anteriormente para essa unidade se ainda existir. Ainda use exportações nomeadas de capability para Domain/Logic.
- Em caso de falha de verify: você pode recompilar com
--onlyapenas a impl (mantenha o arquivo de teste). NÃO DEVE reescrever testes para fazê-los passar (incluindo mudar imports nomeados para factories padrão). Se o cenário/Call/esperado parecer errado → PARE e envie o humano para a-isl-spec-author. - Após um lote de Domain/Logic (ou outro elegível), você pode sugerir
npm run verify -- --root <project> --stack <id>; não exija verde para fazer lock. Lock permanece um cache de hash de build.
Recompilação completa da unidade após mudança de Spec: regenere o arquivo de teste inteiro a partir do Spec atual, depois a impl (não uma mesclagem com testes antigos).
4. Lock (lote quando possível)
Após 1–5 escritas bem-sucedidas:
npm run lock -- --root examples/connect-four-workspace --build-file "<abs1>" --build-file "<abs2>"
5. Agrupamento por complexidade (higiene de contexto)
Uma longa sessão de agente que compila muitas unidades tende a subimplementar unidades posteriores ou grandes pacotes (contexto preenchido com bins anteriores). Prefira:
| Tipo de unidade | Como compilar |
|---|---|
| Folha / pequena | Mesmo agente, lote vários queue --next → escreva → lock |
| Pesada / hub | Agente novo / novo chat: --only <unit> → packet → implemente todas as capabilities em SOURCE → lock |
| Reparo após revisão/playtest | Agente novo + --only na(s) unidade(s) com falha apenas |
Trate uma unidade como pesada se qualquer uma destas condições for verdadeira (independente de stack):
- SOURCE longo / muitas capabilities
####em um.isl.md - Alto fan-in: muitas outras unidades a Referenciam, ou ela Referencia muitas deps
- Apresentação ou Lógica que orquestra uma grande parte do grafo (shell / facade / session boundary)
- Packet ou compilação anterior dessa unidade tem histórico de Flows omitidos
Não crie um agente por folha por padrão (custo). Não execute um workspace grande inteiro em um agente sem atualizar nos hubs.
Prompt para uma unidade pesada: raiz do repositório, --stack, --only <unit>, "implemente toda capability em SOURCE; nenhum Flow omitido." Siga agent-skills/a-isl-compile/SKILL.md (ou a cópia do host em .cursor/skills, .claude/skills, ou .github/skills).
Tabela de escalação (quando o acesso leve não é suficiente)
| Situação | Ação |
|---|---|
| Packet ok, bins de dep existem, ISL claro | Apenas leve → escreva arquivo |
Packet saída / missingDependencyBins | PARE — corrija fila/ordem; não invente APIs |
| Precisa da declaração/assinatura exata de uma dep | npm run lookup-decl (EXT-002); use selected do JSON — não invente APIs |
lookup-decl saída 2 (no_match) | Re-verifique Spec Call/nome + caminho da dep; não invente assinaturas |
| Packet incompleto / sem marcador SOURCE | Leia o fullBuildFile desta unidade uma vez |
| ISL ambíguo / contraditório | PARE → Spec Agent; nenhum mergulho em vendor |
| Humano solicita auditoria completa de rebuild | --force / fila completa --json permitido |
Regras de escrita por unidade
Cabeçalho em cada arquivo gerado:
/**
* DO NOT EDIT THIS FILE DIRECTLY
* ----------------------------------
* This file was generated by ISL Compiler.
* Source: <basename-of-.isl.md>
* Edit the ISL file instead.
*/
Siga as regras do stack (react-js padrão). Implementação completa — sem stubs TODO.
Caminhos
| Ferramenta | 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> |