Compilation A-ISL (compilateur dans l'agent)
Vous émettez le dossier bin-<stackId>/ à partir de l'ISL (stack par défaut react-js → bin-react-js). Les CLIs Builder / queue / packet / lock / preflight sont autorisés. Les outils payants isl-generator / Gemini / OpenAI sont interdits.
Fonctionne avec n'importe quel agent de codage qui charge ce skill (Cursor, Claude Code, GitHub Copilot, …). Même runtime npm depuis la racine du dépôt.
Porte de demande utilisateur (non négociable)
La modification du dossier bin-* se fait uniquement via la compilation et uniquement sur demande explicite de l'utilisateur.
- Entrez dans ce skill / écrivez sous
bin-*uniquement lorsque l'humain demande explicitement de compiler (par ex. "compile", "/a-isl-compile", "build bin", "regenerate implementation", "run compile for …"). - Les messages uniquement de spécification, les idées de fonctionnalités en langage naturel ou les ajustements UX sans demande explicite de compilation NE DOIVENT PAS déclencher d'écritures d'implémentation — envoyez-les à a-isl-spec-author (ou phase de Spécification) et arrêtez-vous.
- Ne compilez pas automatiquement après des modifications de Spec "parce que la démo se casserait" ou "pour terminer la boucle".
- Les dossiers d'implémentation sont mis à jour uniquement via ce workflow de Compilation (paquet → écriture → verrouillage). Ne traitez pas les correctifs ad-hoc sous
bin-*comme le chemin A-ISL sauf si l'humain demande explicitement une exception ponctuelle. - Si l'humain n'a pas demandé de compiler : refusez de modifier
bin-*et dites qu'il a besoin d'une demande de compilation explicite.
Quand utiliser
- L'humain a terminé la phase de Spécification et demande à construire/compiler/régénérer
- Aligner les
bin-<stack>/d'un projet avec les*.isl.mdmis à jour parce que l'humain a demandé la Compilation
Contraintes strictes
- N'exécutez pas de générateurs payants ou de clients API de génération de code.
- Vous écrivez chaque fichier d'implémentation sous le dossier bin de la stack à partir du
targetPathdu paquet (code complet, pas de stubs TODO). - Mettre à jour
gen-lock.jsonseul n'est pas une compilation — ne verrouillez qu'après de vraies écritures sousbin-<stack>/. - Si l'ISL est ambigu ou contradictoire : arrêtez-vous et dites à l'utilisateur de retourner vers a-isl-spec-author. N'inventez pas d'exigences.
- N'ouvrez pas
vendor/isl-spec/pendant la Compilation (Agent de Spec uniquement), sauf demande explicite de l'utilisateur. - Préférez une unité à la fois via
queue --next+ paquet léger. Ne chargez pas le JSON complet de la file d'attente ou le.build.mdcomplet par défaut.
Dossier de sortie
Par défaut : bin-<stackId> à côté des specs (par ex. --stack react-js → bin-react-js). Remplacez avec --bin si nécessaire. Un même espace de travail peut contenir bin-react-js et bin-csharp côte à côte.
Workflow à faible consommation de tokens (par défaut)
preflight → builder (une fois) → boucle : queue --next → packet → [tests puis] écriture impl → (par lot) lock
→ (optionnel) npm run verify
0. Preflight (une fois)
npm run preflight -- --root examples/connect-four-workspace
Porte structurelle/graphe/lint uniquement — ne prouve pas la correction de l'implémentation. En cas d'échec, corrigez la Spec/lint avant de compiler.
1. Builder (une fois par lot)
npm run builder -- examples/connect-four-workspace
L'ordre topologique se trouve dans build/build-manifest.json (propriété du script). Vous n'inventez pas l'ordre de compilation.
2. Unité suivante uniquement
npm run queue -- --root examples/connect-four-workspace --next
Passez --stack <id> à chaque appel queue/packet dans la boucle (par défaut 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 (bibliothèque uniquement), python, python-fastapi. Optionnel --bin <path> remplace le dossier de sortie.
Recompilation ciblée — lorsque l'humain demande de régénérer une ou quelques unités (le verrouillage les ignorerait autrement) :
npm run queue -- --root <project> --next --only dungeon --stack react-js
npm run packet -- --root <project> --next --only dungeon --stack react-js
# ou packet par nom :
npm run packet -- --root <project> --only dungeon --stack react-js
--only peut être répété. Tokens : nom de base de l'unité (dungeon), dungeon.isl.md, ou ./dungeon. Raison dans le JSON de la file : force-only. N'utilisez pas --force à l'échelle de l'espace de travail si seul un sous-ensemble est demandé.
Utilisez next.buildFile / next.targetPath. Si next est null, arrêtez-vous (file vide).
Utilisez la file --json complète uniquement lorsque l'humain demande une vue d'ensemble.
3. Paquet léger (contexte par défaut)
npm run packet -- --root examples/connect-four-workspace --build-file "<abs.build.md>"
# ou
npm run packet -- --root examples/connect-four-workspace --next
Le paquet inclut : le markdown SOURCE pour cette unité, le chemin cible, le sous-ensemble de contraintes de stack, les chemins vers les fichiers de dépendance dans le même bin-<stack>/.
Il exclut les blobs .ref.md intégrés.
Écrivez les fichiers à partir du paquet (voir ordre EXT-001 ci-dessous). Importez les modules de dépendance réels depuis les chemins listés.
3a. Recherche de déclaration de dépendance (EXT-002)
Lorsque vous avez besoin de la déclaration exacte d'un symbole de dépendance (méthode / fonction / type) avant d'écrire cette unité :
npm run lookup-decl -- --stack <id> --name <SpecOrCallName> --file <abs-or-rel-bin-path> [--workspace <project>]
# ou analysez un dossier bin (les fichiers générés *.test.* / *.Tests.cs sont ignorés sauf --include-tests) :
npm run lookup-decl -- --stack <id> --name <Name> --dir <bin-<stack>> --workspace <project>
- Code de sortie 0 = trouvé, 2 =
no_match, 3 = erreur d'utilisation / chemin / stack. - Lisez le JSON de sortie standard : utilisez
candidates[selected](signatureText,leadingContext,enclosingType,kindpar candidat). N'inventez pas d'expressions régulières et n'ouvrez pas le fichier de dépendance complet pour rechercher des signatures. - Les motifs et
callSymbolse trouvent dans la configuration de la stack (declaration-patterns.ts/stacks.config.ts) — le skill doit uniquement invoquer cette CLI. - Les chemins doivent se résoudre sous
--workspaceet un segmentbin-*(échappement de lien symbolique → code 3).
3b. EXT-001 Tests générés (lorsque la Spec opte)
Scénarios éligibles à la vérification = Scénarios de Test avec à la fois `id: …` et - Call: … (voir docs/isl-agent-profile.md). L'Auteur de Spec décide ; n'importe quel rôle peut opter.
Par unité, même tour :
- Si SOURCE a ≥1 scénario éligible : écrasez le fichier de test généré d'abord (chemin = nom de base de l'impl +
stack.verify.testSuffixsous le mêmebin-<stack>/, par ex.domain-sheet.test.js/domain-sheet.Tests.cs). Affirmez uniquement à partir des scénarios Spec + Signature ; mappezCall→ symbole viastack.verify.callSymbol(as-is|pascal-case|snake-casedansstacks.config.ts). react-js Domaine/Logique : chaque Call DOIT être une exportation nommée ; les tests DOIVENTimport { <Call> } from "./<file>"— jamaisimport Unit from …; Unit().<Call>(). Si l'espace de travail abench/call-map.json, résolvez l'exportdepuis"<unit>.<Call>"et importez ce nom (même contrat que le score figé). N'inventez pas de cas pour les scénarios en prose uniquement ; n'ouvrez/ne modifiez pas le fichier d'impl avant que le fichier de test soit écrit. - Écrivez ensuite l'impl à
targetPathpour qu'elle satisfasse ces tests et le Contrat. react-js Domaine/Logique :export function <Call>/export const <Call>pour chaque Capacité ; INTERDIT l'export par défaut d'une fabrique encapsulant les capacités. - Si zéro scénario éligible : écrivez l'impl uniquement ; supprimez un fichier de test généré précédemment pour cette unité s'il existe encore. Utilisez toujours des exports nommés de capacité pour Domaine/Logique.
- En cas d'échec de vérification : vous pouvez
--onlyrecompiler l'impl uniquement (conservez le fichier de test). NE DEVEZ PAS réécrire les tests pour les faire passer (y compris en changeant les imports nommés en fabriques par défaut). Si le scénario/Call/résultat attendu semble erroné → ARRÊTEZ-VOUS et envoyez l'humain vers a-isl-spec-author. - Après un lot Domaine/Logique (ou autre éligible), vous pouvez suggérer
npm run verify -- --root <project> --stack <id>; n'exigez pas le vert pour verrouiller. Le verrouillage reste un cache de hash de build.
Recompilation complète de l'unité après modification de la Spec : régénérez le fichier de test entier à partir de la Spec actuelle, puis l'impl (pas une fusion avec les anciens tests).
4. Verrouillage (par lot si possible)
Après 1 à 5 écritures réussies :
npm run lock -- --root examples/connect-four-workspace --build-file "<abs1>" --build-file "<abs2>"
5. Regroupement par agent selon la complexité (hygiène du contexte)
Une longue session d'agent qui compile plusieurs unités tend à sous-implanter les paquets ultérieurs ou volumineux (contexte rempli par les bins précédents). Préférez :
| Type d'unité | Comment compiler |
|---|---|
| Feuille / petite | Même agent, regroupez plusieurs queue --next → écriture → verrouillage |
| Lourde / hub | Nouvel agent / nouvelle discussion : --only <unit> → paquet → implémentez chaque capacité dans SOURCE → verrouillage |
| Réparation après revue/test | Nouvel agent + --only sur la/les unité(s) défaillante(s) uniquement |
Traitez une unité comme lourde si l'une de ces conditions est vraie (indépendant de la stack) :
- Longue SOURCE / nombreuses capacités
####dans un seul.isl.md - Fort fan-in : beaucoup d'autres unités la référencent, ou elle référence beaucoup de dépendances
- Présentation ou Logique qui orchestre une grande partie du graphe (shell / façade / frontière de session)
- Le paquet ou la compilation précédente de cette unité a un historique de Flux omis
Ne lancez pas un agent par feuille par défaut (coût). N'exécutez pas un grand espace de travail entier dans un seul agent sans vous rafraîchir sur les hubs.
Invite pour une unité lourde : racine du dépôt, --stack, --only <unit>, "implémentez chaque capacité dans SOURCE ; aucun Flux omis." Suivez agent-skills/a-isl-compile/SKILL.md (ou la copie hôte sous .cursor/skills, .claude/skills, ou .github/skills).
Table d'escalade (lorsque l'accès léger ne suffit pas)
| Situation | Action |
|---|---|
| Paquet OK, bins de dépendances existent, ISL clair | Léger uniquement → écrire le fichier |
Sortie du paquet / missingDependencyBins | ARRÊTEZ-VOUS — corrigez la file/l'ordre ; n'inventez pas d'API |
| Besoin de la déclaration/signature exacte d'une dépendance | npm run lookup-decl (EXT-002) ; utilisez le JSON selected — n'inventez pas d'API |
lookup-decl code 2 (no_match) | Revérifiez le Call/nom Spec + chemin de dépendance ; n'inventez pas de signatures |
| Paquet incomplet / pas de marqueur SOURCE | Lisez le fullBuildFile de cette unité une fois |
| ISL ambigu / contradictoire | ARRÊTEZ-VOUS → Agent de Spec ; pas de plongée dans vendor |
| L'humain demande un audit complet de reconstruction | --force / file --json complète autorisée |
Règles d'écriture par unité
En-tête sur chaque fichier généré :
/**
* NE PAS MODIFIER CE FICHIER DIRECTEMENT
* ---------------------------------------
* Ce fichier a été généré par le compilateur ISL.
* Source : <nom-de-base-du-.isl.md>
* Modifiez le fichier ISL à la place.
*/
Suivez les règles de la stack (react-js par défaut). Implémentation complète — pas de stubs TODO.
Chemins
| Outil | Entrée |
|---|---|
| Preflight | npm run preflight -- --root <project> |
| Builder | npm run builder -- <project> |
| File suivante | npm run queue -- --root <project> --next |
| Paquet | npm run packet -- --root <project> --next |
| Verrouillage | npm run lock -- --root <project> --build-file <abs>... |
| Vérification | npm run verify -- --root <project> [--stack <id>] [--only <unit>] |
| Recherche de déclaration | `npm run lookup-decl -- --stack --name --file |
| Lint | npm run lint -- <file.isl.md> |