Configuración¶

Cada fichero de gdd/ y cada clave que gdd lee de él: su tipo, el valor que gdd usa cuando falta la clave y lo que hace. Los ficheros son TOML.

Los ficheros¶

gdd init escribe los cinco primeros ficheros y gdd/generated.toml; gdd adopt escribe gdd/debt.toml. Todos se suben al repositorio con el proyecto.

No existe gdd/release.toml: consulta release.toml.

Un fichero que gdd no puede analizar detiene el comando con el nombre del fichero y el error de TOML. Las claves que gdd no lee se ignoran, salvo donde una sección de abajo diga otra cosa.

Quién puede cambiarlos¶

Toda ruta bajo gdd/ es arnés:

• gdd init pone gdd/** en [protected] all de gdd/rules.toml, así que Path Guard hace fallar a cualquier Builder o Reviewer que la toque, en G2 y en CI (gdd ci hace fallar una rama de Change que cambia una ruta de all).
• gdd init pone gdd/** en la zona roja del arnés de gdd/zones.toml, así que un Change que la planifica es rojo.

Solo una persona cambia estos ficheros, en la rama principal, después de que la persona esté de acuerdo: el Orchestrator propone, la persona decide (las zonas rojas y el plan de un Change rojo se aprueban en la sentada). Un Change que vuelve a editar gdd/zones.toml necesita que las zonas rojas se aprueben de nuevo.

Path Guard juzga un build con las listas [protected] de gdd/rules.toml tal como están ahora y tal como estaban en el commit donde empezó el build: borrar una protección, o el fichero entero, no libera de ella a ningún rol.

project.toml¶

Lo básico del proyecto. gdd init lo escribe a partir de sus flags. Es el fichero que marca la raíz del proyecto: gdd busca gdd/project.toml en la carpeta donde se ejecuta y en las carpetas superiores, y se niega a ejecutarse fuera de un proyecto (not a GDD project).

Lo leen gdd status (name, language, platform), todo comando que necesita los stacks (stack) y los agentes, cuyos comandos les indican que lo lean (language, scenario_runner).

name = "notes"
description = "A command-line notes tool"
language = "en"   # language the agents use with the human
platform = "cli"   # mobile | desktop | web | cli | other
stack = ["python"]   # the stack sheets (gdd stacks)
scenario_runner = "pytest-bdd"

zones.toml¶

El mapa de zonas: qué rutas tienen qué color. Lo leen gdd classify, gdd new-change, gdd prepare, las puertas (para clasificar el Change y para la comprobación de alcance), gdd status y gdd gate zones. El Orchestrator mapea las zonas rojas al final de Discover; el humano las aprueba (gdd gate zones ok). Consulta Cómo elige el riesgo las puertas.

El color de una ruta es el más alto entre las zonas que la cubren; una ruta que no cubre ninguna zona toma default. El color de un Change es el más alto entre sus rutas, elevado a su --min-color cuando este es más alto.

Patrones de ruta: ** atraviesa carpetas (docs/** cubre todo lo que hay dentro de docs; **/x también cubre x en la raíz), * y ? se quedan dentro de una carpeta. *.md cubre README.md pero no notes/readme.md.

Nivel superior¶

[[zone]]¶

Una tabla por zona, tantas como quieras, en el orden del fichero. Cuando varias zonas del mismo color cubren una ruta, la primera da su motivo.

gdd init escribe tres zonas: docs/** y *.md en verde; el arnés (gdd/**, bin/**, .github/**, .claude/**, .agents/**, .opencode/**, .gdd/bin/**) en rojo; la cadena de suministro de los stacks (por ejemplo pyproject.toml, uv.lock, osv-scanner.toml, osv-scanner-licenses.toml) en rojo.

La aprobación de las zonas rojas guarda un hash de cada [[zone]] cuyo color es red, con todas sus claves. Cualquier cambio en una zona roja, incluida una clave añadida, pide una aprobación nueva.

rules.toml¶

La tabla de reglas: qué puertas pide cada color y cada vía, dónde viven los escenarios, los límites de cada bucle y las rutas que cada rol no debe tocar. Lo leen gdd classify, gdd new-change, gdd prepare, gdd g2, gdd g3, gdd guard, gdd scope, gdd launch, gdd resume, gdd merge, gdd release, gdd selftest y gdd ci.

Nivel superior¶

[acceptance]¶

G3 cuenta las líneas de los ficheros .feature de dir y sus subcarpetas que empiezan por Scenario:, Scenario Outline:, Escenario: o Esquema del escenario:.

[limits]¶

[spike]¶

[parallel]¶

gdd init no la escribe.

[versions]¶

gdd init no la escribe.

[color]¶

Lo que pide cada color en cada vía. Un color tiene una tabla propia, [color.<color>], y una por vía, [color.<color>.fast] y [color.<color>.full]. La regla de un color en una vía es su tabla de vía cuando la tiene, y si no, su tabla de color. Una tabla de vía no hereda de la tabla de color: una clave que omite toma el valor por defecto de abajo. Un color que el fichero no menciona recibe los valores por defecto.

Cuando el fichero no tiene ninguna sección [color], gdd usa en su lugar la tabla que lleva incorporada:

gdd init escribe las mismas tablas con mutation = false para el amarillo, y review en todas las vías.

El núcleo de GDD no se puede desactivar para el rojo. Una tabla roja (con o sin vía) que diga mutation = false, reviewer = false, g4_if_g1 = false o review = "quick" hace que se rechace el fichero entero:

error: gdd/rules.toml: red changes always get mutation testing, the Reviewer and the human G4 (the core of GDD): remove color.red.full.mutation = false from gdd/rules.toml

También se rechazan una profundidad de revisión distinta de quick o deep y un color distinto de green, yellow o red. El rojo nunca va por la vía rápida: [color.red.fast] no se usa nunca.

La vía de un Change es fast cuando su color no es rojo, no tiene escenarios nuevos ni cambiados y se creó con --resumable; en otro caso, full. Consulta Vías.

[protected]¶

Las rutas que cada rol no debe cambiar, como patrones (consulta zones.toml). Path Guard las comprueba en G2 y G3, antes y después de los comandos, tras cada ronda del modo test y en gdd guard.

Un rol no debe tocar las rutas de all más las de su propia lista. Con independencia de estas listas, cualquier rol falla Path Guard cuando un fichero de escenarios aprobado en G1 ha cambiado después de la aprobación.

gdd init escribe all como gdd/**, bin/**, .github/**, .claude/**, .agents/**, .opencode/**, .gdd/bin/**, AGENTS.md y CLAUDE.md, y builder_build y builder_test a partir de las fichas de stack.

models.toml¶

Quién hace cada rol: un agente (integración) y su modelo. Lo leen gdd new-change, gdd classify y gdd prepare (el modelo de cada rol entra en la decisión del Change), gdd launch y gdd resume (qué agente arrancar), gdd status y gdd agents. gdd init lo escribe a partir de --agents y de los valores por defecto de cada agente; consulta Roles.

[orchestrator]
integration = "claude"
model = "opus"

[builder.green]
integration = "claude"
model = "haiku"

[builder.yellow]
integration = "claude"
model = "sonnet"

[builder.red]
integration = "claude"
model = "opus"

[builder_test]
integration = "claude"
model = "sonnet"

[reviewer]
integration = "codex"
model = "gpt-6-astra"
effort = "high"

[families]
"claude" = "anthropic"
"codex" = "openai"

[orchestrator], [builder.\<color>], [builder_test], [reviewer]¶

El modelo de cada rol. [builder.<color>] es el Builder en modo build para los Changes de ese color (green, yellow, red); [builder_test] es el Builder en modo test para todos los colores; [orchestrator] replanifica un Change atascado en G2; [reviewer] revisa cada Change que tiene Reviewer. Un rol sin tabla no tiene agente: su llamada falla.

Las demás claves de una tabla de rol se guardan, tal cual, en la decisión del Change.

[families]¶

A qué familia de modelos pertenece cada modelo. El Reviewer debe ser de una familia distinta de la del Builder, para no compartir sus puntos ciegos.

La familia de un modelo es la de la primera clave, en el orden del fichero, por la que empieza el nombre de su modelo o con la que coincide su integración; si no hay ninguna, la propia integración. gdd init escribe una clave por agente: claude es anthropic, codex es openai, opencode es minimax.

[session]¶

gdd init no la escribe.

Un Change recibe una sesión compartida solo cuando [builder_test] y su [builder.<color>] usan la misma integración y la ficha de ese agente dice cómo reanudar una sesión (hoy, Claude Code); si no, se ejecuta con sesiones separadas y gdd status dice por qué. El Reviewer y el Orchestrator nunca se unen a ella. gdd launch y gdd resume leen esta tabla desde el checkout principal.

[env]¶

gdd init no la escribe.

[prices.\<model>]¶

gdd init no la escribe. El precio de un modelo, para los agentes que no informan de su coste (Codex): una tabla por nombre de modelo, tal como lo escribe model.

La estimación va a la línea de la llamada en el log. El registro del Change, y por tanto el presupuesto del Spike, guarda solo lo que informó el agente.

commands.toml¶

Los comandos que ejecutan las máquinas: los comandos de las puertas, las herramientas de Learn, cómo contar la deuda conocida, el test que falla del autotest y los pasos de release. Cada comando es una línea de shell que se ejecuta con sh -c desde la raíz del proyecto, sin nada en su entrada estándar; pasa con el código de salida 0. gdd init escribe este fichero a partir de las fichas de stack (lo que imprime gdd stacks compose) seguidas de la sección [release]. El texto que escribe un agente nunca llega a un shell: solo llegan estos comandos.

Nivel superior¶

[g2]¶

Los comandos de la puerta del bucle (G2, Loop Gate), que se ejecutan en cada ronda del Builder y con gdd g2.

• Un valor vacío, o que no es una cadena, no está configurado: nunca se ejecuta y no se lista.
• Una puerta sin ningún comando configurado falla (G2 not configured).
• Un comando cuyo nombre empieza por mutation solo se ejecuta cuando el Change necesita mutation testing (pruebas de mutación); si no, aparece en skipped.
• Cada comando recibe GDD_CHANGE, GDD_COLOR, GDD_DIFF_FILES y GDD_FEATURES; consulta Variables de entorno.
• Un comando que falla conserva, en el informe de la puerta, las 40 primeras líneas de su salida que informan de un fallo (empiezan por error o contienen FAILED, Failed, failed, panicked, Error:, Traceback o ✘), y después los últimos 2500 caracteres.

Las fichas de stack llaman a los comandos de G2 lint, types, unit, acceptance y architecture.

[g3]¶

Los comandos de la puerta de integración (G3, Merge Gate), que ejecuta la receta después de G2 y también gdd g3. Mismas reglas que [g2]. Las fichas de stack los llaman acceptance_full, lockfile, security, dependencies, secrets y mutation. gdd status avisa cuando ningún comando de [g3] empieza por mutation: los Changes rojos se quedarían sin mutation testing.

gdd adopt ejecuta una vez cada comando de G2 y G3, salvo aquellos cuyo nombre empieza por acceptance, mutation o secrets.

[learn]¶

Las herramientas que gdd learn ejecuta una vez sobre el proyecto: avisos, nunca una puerta.

Las fichas de stack las llaman duplication y unused.

[count]¶

Cómo contar lo que informa un comando con deuda conocida, para que su deuda tenga un techo (un trinquete).

Un comando con deuda conocida que falla pasa la puerta mientras su recuento se mantenga igual o por debajo del recuento de gdd/debt.toml. Informar de más, o un recuento que gdd no puede leer, hace fallar la puerta.

[selftest]¶

El test que falla a propósito en el autotest del arnés (gdd selftest, comprobación 1).

[protected]¶

gdd init también escribe aquí la tabla [protected] de las fichas de stack compuestas. gdd no la lee de este fichero: las listas que usa Path Guard están en gdd/rules.toml.

[release]¶

Los pasos de release. Los leen gdd merge, gdd release y gdd selftest. Cada paso ejecuta su comando, nunca otra cosa, dentro de [limits] command_seconds, con GDD_CHANGE y, cuando el Change ya tiene versión, GDD_VERSION.

Un valor vacío cuenta como si no hubiera comando.

release.toml¶

Un proyecto no tiene gdd/release.toml. Los pasos de release están en la tabla [release] de gdd/commands.toml: gdd init los añade ahí a partir de su plantilla.

generated.toml¶

Lo que gdd init escribió una vez y lo que se le pidió, para que gdd upgrade pueda generar los mismos ficheros con un gdd más reciente y fusionarlos con las ediciones del proyecto. Lo escribe gdd init; lo reescribe gdd upgrade en su rama gdd-upgrade. No lo edites a mano.

Nivel superior¶

[answers]¶

gdd upgrade rechaza un proyecto sin este fichero o sin [answers].

debt.toml¶

La deuda conocida de un proyecto que ya tenía código: los comandos de puerta que fallaban cuando se ejecutó gdd adopt. Avisan en lugar de hacer fallar una puerta hasta que un Change consigue que cada uno pase. Lo escribe gdd adopt, que hace un commit solo con él y se niega a ejecutarse una vez que existe; una fusión elimina la deuda que sus puertas saldaron y rebaja los recuentos que sus puertas informaron más bajos.

adopted = "2026-10-30"

[[debt]]
command = "lint"
gate = "g2"
since = "2026-10-30"
count = 3

Nivel superior¶

[[debt]]¶

Un fichero de deuda que gdd no puede leer hace fallar la comprobación debt de la puerta, y la primera comprobación de gdd selftest, que somete G2 a la misma deuda.

Ver también¶

• Puertas: qué ejecuta cada puerta con estos ajustes, por color.
• Stacks: de dónde salen los comandos y las rutas protegidas de gdd init.
• Ajustar las puertas: cambia comandos y límites paso a paso.
• Referencia de comandos: los flags que rellenan estos ficheros.