Guía para Agentes de IA / AI Agent Guide

Esta guía complementa las instrucciones de AGENTS.md y describe cómo generar o corregir documentación en este monorepo. La plantilla de README de Nivel 3 y la de los índices de Nivel 1 y Nivel 2 son README_Template.md.

Alcance / Scope

Los agentes ayudan principalmente con documentación, verificación y revisiones puntuales. El autor implementa los lenguajes para practicar; generar código nuevo requiere una petición explícita.

Roles / Roles

ES: Cada encargo lo firma un rol del catálogo de AGENT_ROLES.md, que declara qué decide cada rol, qué no le corresponde y con qué perfil de modelo trabaja. Este documento y las plantillas de scripts/prompts/ lo usan como fuente única: no repiten el reparto.

EN: Every request is signed by one role from the catalogue in AGENT_ROLES.md, which states what each role decides, what it must not do and with which model profile it works. This document and the templates under scripts/prompts/ treat it as the single source: they do not repeat the split.

Delegación y alcance / Delegation and scope

ES: La delegación se puede hacer de dos maneras y las dos conviven:

  1. Delega el autor. glot prompt <encargo> imprime el encargo y el autor lo envía a un agente: el chat del editor o glot ask con GLOT_DELEGATE definido en su entorno. Esa configuración es suya, vive fuera del repositorio y no se versiona.
  2. El agente hace el paso. El agente que recibe el encargo no ejecuta los comandos de delegación (glot prompt, glot ask): lee las fuentes que el encargo declara —reglas, especificación y módulos homologados del lenguaje— y realiza el trabajo.
Pieza / Piece Sí hace / Does No hace / Does not
glot Orquesta y ejecuta los comandos de terminal, resuelve catálogo y estado, captura salidas reales y arma el encargo No piensa por el agente ni ejecuta los encargos
Agente de IA / AI agent Lee las reglas, la especificación y los módulos homologados, y escribe el artefacto del paso No ejecuta prompt/ask, no decide el cierre, no commitea ni empuja
Autor / Author Decide, configura su delegado, revisa, commitea, empuja y cierra —

EN: Delegation can be done in two ways and both coexist:

  1. The author delegates. glot prompt <request> prints the request and the author sends it to an agent: the editor’s chat or glot ask with GLOT_DELEGATE set in their environment. That configuration is theirs, it lives outside the repository and is not versioned.
  2. The agent performs the step. The agent receiving the request does not run the delegation commands (glot prompt, glot ask): it reads the sources the request declares —rules, specification and the language’s standardised modules— and does the work.

ES: Consecuencia de límites: el agente no usa cuentas, cuotas ni credenciales del autor (nada de copilot -p, gh auth o tokens) y no introduce en los artefactos rutas absolutas de la máquina (/home/{usuario}/…) ni salidas de compilación con rutas de otro equipo. La identidad pública del autor en manifiestos y licencias (maintainers, author, copyright) no es una credencial y no se retira. El autor conserva el control: puede hacer por sí mismo cualquier paso, y el agente solo cubre los que se le presenten como encargo.

EN: Scope consequence: the agent does not use the author’s accounts, quotas or credentials (no copilot -p, gh auth or tokens) and does not introduce machine absolute paths (/home/{user}/…) or build output with another machine’s paths into any artefact. The author’s public identity in manifests and licences (maintainers, author, copyright) is not a credential and is not removed. The author keeps control: they can do any step themselves, and the agent only covers the ones presented to it as a request.

Antes de escribir / Before writing

  1. Ejecutar git status --short y git submodule status en la raíz.
  2. Comprobar la rama del submódulo afectado.
  3. Leer la especificación y docs/ROADMAP.md.
  4. No tocar una rama de trabajo activa (feat/..., fix/..., etc.) sin autorización.
  5. Verificar que el estado indicado en el roadmap corresponde a código, tests y documentación existentes.

Niveles de documentación / Documentation levels

Nivel / Level Archivo / File Base / Source
1 — Lenguaje / Language {lenguaje}/README.md README del lenguaje equivalente
2 — Fase / Phase {lenguaje}/core/README.md o {lenguaje}/core/{fase}/README.md READMEs de fases existentes
3 — Módulo / Module {lenguaje}/core/{fase}/{modulo}/README.md README_Template.md

Reglas / Rules

Autoridad, bases y conflictos / Authority, references and conflicts

ES: Las instrucciones de actuación delimitan qué puede hacer el agente. Dentro de ese alcance, la especificación fija operaciones, casos, resultados, invariantes y complejidad; las reglas de fase fijan los mecanismos educativos permitidos. Las capacidades verificadas del lenguaje determinan cómo expresarlos, no autorizan cambiar el contrato. Si la especificación y la fase se contradicen, o el lenguaje no puede cumplirlas, se bloquea el artefacto afectado y se consulta al autor antes de cambiarlo. Una convención preferida no es una imposibilidad. Las desviaciones se tramitan mediante ruleset/DEVIATION_POLICY.md.

EN: Acting instructions limit what the agent may do. Within that scope, the specification defines operations, cases, results, invariants and complexity; phase rules define the educational mechanisms allowed. Verified language capabilities determine their expression, not permission to change the contract. If specification and phase conflict, or the language cannot satisfy them, block the affected artefact and consult the author before changing it. A preferred convention is not an impossibility. Use the deviation policy linked above.

ES: Para la forma, las bases del mismo lenguaje son, en orden persistente: {lenguaje}/core/algorithms/data_structures_basics/ y {lenguaje}/core/foundations/numbers/, hasta cambiar explícitamente esta regla. Inspecciona código, pruebas, runner, manifiesto y README pertinentes. Son referencias, no moldes: Numbers puede aportar un patrón que Basics no ejercita. Justifica por aspecto lo reutilizado según los temas y variantes del módulo. Si una base falta, no está homologada o es el propio módulo, decláralo; usa la otra si basta o reporta el bloqueo, sin inventar un reemplazo.

EN: For form, same-language references have persistent priority: {language}/core/algorithms/data_structures_basics/, then {language}/core/foundations/numbers/, until this rule is explicitly changed. Inspect relevant code, tests, runner, manifest and README. They are references, not moulds: Numbers can supply a pattern absent from Basics. Justify reuse per aspect according to module topics and variants. Declare a missing, unhomologated or self-referencing base; use the other if sufficient, otherwise report a blocker without inventing a replacement.

ES: Una representación no define todos los ADT: preferir arrays en un módulo de secuencias u ordenamiento no impone arrays, índices consecutivos ni capacidad máxima a listas enlazadas, árboles o grafos. Solo se validan límites que pertenezcan al contrato actual. Un límite físico del entorno se documenta como tal; no se presenta como propiedad intrínseca de la estructura.

EN: One representation does not define every ADT: preferring arrays in a sequence or sorting module does not impose arrays, consecutive indices or maximum capacity on linked lists, trees or graphs. Validate only limits belonging to the current contract. Document physical environment limits as such, not as intrinsic structure properties.

ES: Al redactar o revisar una especificación, distingue comportamiento observable de intención educativa: indica qué algoritmo o representación debe construirse manualmente, qué operaciones de biblioteca están prohibidas y qué primitivas o almacenamiento sí se permiten. El SME adapta la forma sin borrar esa intención; el SDET prueba resultados e invariantes observables, y el Validator revisa también el código para comprobar restricciones que una suite verde no demuestra. Una mejora de complejidad no autoriza sustituir lo que se está aprendiendo. Al revisar documentación anterior aplica sus requisitos explícitos; si la intención es ambigua, solicita decisión al autor antes de declarar incumplimientos o extender restricciones de otro módulo.

EN: When writing or reviewing a specification, distinguish observable behaviour from educational intent: state which algorithm or representation must be built manually, which library operations are forbidden and which primitives or storage are permitted. The SME adapts form without removing that intent; the SDET tests observable results and invariants, while the Validator also reads code to check constraints green tests cannot prove. Better complexity does not authorise replacing the learning objective. Review older documentation against its explicit requirements; if intent is ambiguous, request an author decision before declaring violations or extending another module’s restrictions.

  • Mantener el formato bilingüe español/inglés.
  • Usar enlaces GitHub Pages donde lo exijan las guías de documentación.
  • Copiar solo salidas reales de compilación y tests.
  • Explicar las adaptaciones del lenguaje, incluido TCO y la estructura de tests.
  • No marcar un módulo o fase como completado sin verificación.
  • No ejecutar git push ni crear commits salvo instrucción explícita.
  • Al finalizar código y documentación, completar ROADMAP_UPDATE_CHECKLIST.md y actualizar ROADMAP.md en el mismo cambio.

Evolución por fase / Phase evolution

README_Template.md es la plantilla única de Nivel 3, y también fija la estructura de los índices (Nivel 1 y Nivel 2). Se puede ampliar cuando una fase introduce conceptos nuevos, pero no se crean copias por lenguaje ni plantillas paralelas con nombres distintos.

Fase / Phase Concepto / Concept
0 — Foundations Recursión, acumulador, iteración y TCO
1 — Algorithms Pure Indicadores de fallo compatibles, sin excepciones; contrato explícito con una sola implementación
2 — Contiguous Processing Validación y excepciones
3 — Algorithms on Structures Contratos abstractos cuando un algoritmo consume estructuras intercambiables
4 — Abstraction & Persistence Option/Result, Maybe/Either y modelado
5 — Math Tipos numéricos y representación de matrices y vectores
6–7 — UI y Web Interfaces de puerto y adaptador e inyección de dependencias

🔌 Contrato, abstracción e interfaces / Contract, abstraction and interfaces

ES: El contrato es lo que el módulo promete —operaciones, semántica, orden observable, límites y complejidad— y es normativo y global: no cambia de un lenguaje a otro. La forma de declararlo es idiomática y local: Ada usa la package specification, C un encabezado con un tipo opaco, Haskell la lista de exportación del módulo, y Java la API pública de una clase o una interface. Separar ambos planos es la ocultación de información de Parnas (1972) y la abstracción de datos de Liskov (1974): la especificación es independiente de la representación, y la notación elegida no altera el contrato.

EN: The contract is what the module promises —operations, semantics, observable order, limits and complexity— and it is normative and global: it does not change from language to language. The way it is declared is idiomatic and local: Ada uses the package specification, C a header with an opaque type, Haskell the module’s export list, and Java a class’s public API or an interface. Separating both planes is Parnas’s information hiding (1972) and Liskov’s data abstraction (1974): the specification is independent of the representation, and the chosen notation does not alter the contract.

Notación idiomática del contrato / Idiomatic notation of the contract

ES: La tabla agrupa por familia de notación, no por lenguaje: el contrato se declara siempre en la forma que ese lenguaje usa para separar «qué hace» de «cómo lo hace». La tercera columna indica si el lenguaje tiene una construcción dedicada para un contrato aparte; usarla con una sola implementación es abstracción prematura.

EN: The table groups by notation family, not by language: the contract is always declared in the shape that language uses to separate “what it does” from “how it does it”. The third column states whether the language has a dedicated construct for a separate contract; using it with a single implementation is premature abstraction.

Familia / Family Declaración del contrato / Contract declaration Contrato aparte / Separate contract
Ada package specification (público) y package body (oculto) No hace falta: la propia especificación ya es el contrato
C, Assembly, COBOL, Forth Encabezado o sección de declaraciones; tipo opaco o puntero incompleto No existe; el contrato es el encabezado
C++ Encabezado con class/struct; private oculta la representación Clase abstracta o método virtual puro cuando hay más de una implementación
Java, C#, Kotlin, Scala, Dart Miembros públicos de la clase interface o abstract class cuando hay más de una implementación
Rust Módulo con pub trait cuando hay más de una implementación
Swift, Objective-C Miembros públicos protocol
Go Nombres exportados del paquete interface implícita; se declara cuando se consume polimórficamente
Haskell, OCaml, F# Lista de exportación del módulo o firma .mli Clase de tipos o firma de módulo cuando hay más de una implementación
Elm, Erlang, Elixir, Gleam, Clojure, Common Lisp, Scheme, Prolog Exportación del módulo y sus funciones behaviour, protocolo o multimétodo cuando hay más de una implementación
Python, Ruby, Perl, Raku, Lua, Tcl/Tk API documentada y convenida Protocol/ABC/rol o módulo de contrato cuando hay más de una implementación

Momento de adopción por fase / Adoption moment per phase

Fase / Phase Qué se exige / What is required Por qué / Why
0 — Foundations El contrato se declara en la notación natural del lenguaje; sin contratos aparte El programa es una función y no hay nada que abstraer
1 — Algorithms Pure Igual: contrato normativo y representación libre. No se exige interface/trait/protocol Hay una implementación por estructura; abstraer antes de tener lo concreto es prematuro (HtDP: abstract after concrete)
3 — Algorithms on Structures Primer uso con sentido: cuando un algoritmo debe consumir estructuras intercambiables (cola de prioridad de Dijkstra; pila y cola de BFS, DFS y backtracking) Es el caso de las operaciones genéricas de SICP §2.4–2.5: la abstracción se justifica cuando existen varias representaciones de la misma interfaz
4 — Abstraction & Persistence Contratos formales con varias implementaciones reales (consultas crudas frente a ORM, parsers intercambiables) y tipos de retorno Option/Result Meyer (1988): el contrato se especifica con precondiciones, postcondiciones e invariantes; sustituibilidad de Liskov
6–7 — UI y Web Interfaces de puerto y adaptador, inyección de dependencias y dobles de prueba La capa de aplicación depende de abstracciones y no de implementaciones

ES: Consecuencia para las especificaciones: la de Fase 1 fija comportamiento (resultado de éxito, resultado de fallo, límites, orden y complejidad) y deja libre la forma; no puede exigir una construcción que solo tiene sentido cuando aparece un segundo consumidor o una segunda implementación. Una especificación que obligue a interface donde hay una sola implementación es un hallazgo, igual que una que deje sin definir qué devuelve una operación.

EN: Consequence for specifications: a Phase 1 specification fixes behaviour (success result, failure result, limits, order and complexity) and leaves the form free; it cannot require a construct that only makes sense once a second consumer or a second implementation appears. A specification that mandates an interface where there is a single implementation is a finding, as is one that leaves undefined what an operation returns.

ES: Referencias que sostienen este calendario: Parnas, On the Criteria To Be Used in Decomposing Systems into Modules (1972); Liskov y Guttag, Abstraction and Specification in Program Development (1986); Abelson y Sussman, SICP §2.1 (barrera de abstracción) frente a §2.4–2.5 (operaciones genéricas); Felleisen et al., How to Design Programs (la abstracción llega después de lo concreto); Meyer, Object-Oriented Software Construction (1988); Cormen et al., CLRS (el ADT «cola de prioridad» se especifica aparte del heap que lo implementa).

EN: References supporting this calendar: Parnas, On the Criteria To Be Used in Decomposing Systems into Modules (1972); Liskov and Guttag, Abstraction and Specification in Program Development (1986); Abelson and Sussman, SICP §2.1 (abstraction barrier) versus §2.4–2.5 (generic operations); Felleisen et al., How to Design Programs (abstraction comes after the concrete); Meyer, Object-Oriented Software Construction (1988); Cormen et al., CLRS (the “priority queue” ADT is specified apart from the heap implementing it).

🔀 Adaptaciones idiomáticas / Idiomatic adaptations

ES: Una adaptación idiomática es la desviación declarada y justificada del pseudocódigo o de la ubicación esperada cuando el lenguaje no puede hacer lo que el pseudocódigo hace. No es estilo: es lo que el lenguaje no soporta (mutación, índices enteros, null, bucles). Desarrolla la regla «explicar las adaptaciones del lenguaje» de arriba y se escribe en la tabla Adaptaciones idiomáticas de README_Template.md; una desviación sin fila es un hallazgo.

EN: An idiomatic adaptation is the declared and justified deviation from the pseudocode or the expected location when the language cannot do what the pseudocode does. It is not style: it is what the language does not support (mutation, integer indices, null, loops). It develops the “explain the language’s adaptations” rule above and goes in the Idiomatic adaptations table of README_Template.md; a deviation with no row is a finding.

ES: Esta guía fija las reglas, que no cambian de un módulo a otro. El indicador de fallo de cada lenguaje (qué devuelve C, qué caso omite Haskell) es estado del módulo: vive en la tabla Indicadores de fallo de su README y se escribe al implementarlo, no aquí. EN: This guide states the rules, which do not change from module to module. Each language’s failure indicator is module state: it lives in its README’s Failure indicators table and is written when implementing, not here.

Reglas de una adaptación / Rules for an adaptation

  1. El contrato manda. La adaptación cambia la forma, nunca el resultado observable: mismos casos, mismo orden, misma complejidad prometida. Si cambia el resultado, es un defecto y se reporta.
  2. Sin atajos de biblioteca. En Fase 1 están prohibidas las rutinas de ordenamiento, búsqueda o selección (sort, min, max…) de la biblioteca estándar para el paso interno del algoritmo.
  3. Mecanismos según la fase. En Fase 1, el contrato se declara con un indicador compatible con el tipo de retorno (null, nil, None, #f, -1, nothing cuando sea representable). No se añaden Option/Maybe/Result ni excepciones por preferencia idiomática; se introducen según la tabla de evolución por fase. La restricción no prohíbe los opcionales nativos permitidos ni los enlaces opcionales internos de una estructura.
  4. Una fila por desviación, con qué dice la especificación, qué hace el código y por qué.
  5. Los tests también se adaptan y se declaran. Si un caso no es representable, se omite y se dice en Cobertura de pruebas; no se sustituye por otro caso ni se inventa un centinela imposible.
  6. Nunca se silencia. Una línea del pseudocódigo que no se puede seguir se cita en la justificación, tal cual; no se esconde en un comentario del código.

Familias de limitación / Limitation families

ES: Los desafíos no se enumeran por lenguaje (50 filas dirían lo mismo 50 veces) sino por familia. Un lenguaje puede estar en varias filas.

EN: Challenges are not listed per language (50 rows would repeat themselves) but by limitation family. A language may appear in several rows.

Familia / Family Lenguajes típicos / Typical languages Adaptación declarada / Declared adaptation
Sin mutación razonable Haskell, Elm, Erlang, Gleam, PureScript, Scheme, Clojure, Common Lisp, Prolog, F# Devolver una colección nueva o recurrir sobre listas, con la misma complejidad prometida
Sin índices enteros ni bucles Prolog, Haskell, Erlang, Scheme, Common Lisp, Forth Recursión sobre lista (con acumulador cuando no haya TCO) y cabeza/cola
Sin null/nil en un tipo de valor Haskell, Elm, Erlang, Gleam, Rust, Swift, V, Vala, Zig, C++, OCaml, PureScript, Tcl/Tk… El caso de entrada nula no representable se omite solo según la cláusula de adaptación; los demás fallos conservan el indicador del contrato si el tipo lo admite. No se introduce Option/Maybe antes de su fase
Opcional nativo disponible C#, F#, Ballerina, Kotlin, Nim, Crystal, TypeScript Usar el opcional del lenguaje como indicador, sin envoltorios añadidos
Capacidad fija y overflow C, Ada, Assembly, COBOL, Forth Presupuesto de memoria declarado; el overflow es un caso probado, no un accidente
Centinela -1 y tipos de índice lenguajes con índices sin signo o basados en 1 El indicador nativo del lenguaje y su fila en la tabla de adaptaciones
Suite y runner Prolog (plunit), Tcl/Tk, Forth, COBOL, Ada, Rust La ubicación que el framework espera (tests/, src/, t/) se declara como desviación

Formato de la fila / Row format

Columna / Column Qué va / What goes in Reglas / Rules
Especificación / Specification La línea o sección que no se puede seguir tal cual Cita el texto, no lo parafrasees
Adaptación / Adaptation Qué hace el código en su lugar Nombra la construcción del lenguaje (int[]?, recursión sobre listas, vector interno)
Justificación / Justification La limitación y qué se conserva Di qué se mantiene del contrato y qué caso se omite si aplica

ES: Ejemplos genéricos: el caso nulo no representable se omite y se declara; un lenguaje sin bucles ni mutación resuelve con recursión sobre listas; un layout con tests/ del framework en lugar de test/run_tests.ext se declara como desviación de la ubicación esperada.

EN: Generic examples: a not representable null case is omitted and declared; a language with no loops or mutation solves it by recursion over lists; a layout with the framework’s tests/ instead of test/run_tests.ext is declared as a deviation from the expected location.

Qué NO es una adaptación / What is NOT an adaptation

  • Usar la colección optimizada del lenguaje para construir una estructura que el módulo existe para construir, salvo que el propio módulo lo declare.
  • Cambiar un caso de prueba porque «en este lenguaje es más natural así».
  • Saltarse el aislamiento de tests: si la función muta la entrada, cada caso copia su fixture.
  • Añadir dependencias que la guía de inicialización no declara.
  • Silenciar una desviación en un comentario del código en vez de en el README.