Coding Assistant

El brazo de implementación del lab. Delega tasks de code-writing a un coding sub-agent sandboxed a través de scoped prompts. Revisa, integra y testea el resultado.

Status

Implemented. El Coding Assistant es el mecanismo del lab para delegar implementation tasks. Es una thin wrapper que el Coordinator invoca cuando el usuario pide código.

Role

El Coding Assistant es responsable de:

Recibir una code-writing task del Coordinator.
Redactar un prompt que describa el goal y los boundaries (NO la implementación).
Invocar al coding sub-agent con el prompt.
Revisar el código que produce el sub-agent.
Integrar el código en el target project.
Correr los tests del proyecto.
Reportar el resultado al Coordinator.

El Coding Assistant no escribe código directamente. Es un architect y un reviewer, no un coder. El coding sub-agent es el coder.

Architecture

El Coding Assistant es un proceso que orquesta al coding sub-agent:

Loading diagram…

Component	Purpose
Prompt Drafter	Compone el prompt a partir de la task y del project context.
Coding Sub-agent	El coder externo. El Assistant nunca escribe código.
Reviewer	Inspecciona el código en busca de issues obvios.
Integrator	Mueve el código al proyecto.
Test Runner	Corre los tests del proyecto.

Coding sub-agent

El coding sub-agent es una herramienta CLI externa (Codex, en el caso del lab). Tiene las siguientes propiedades:

Corre en un entorno sandboxed.
Tiene su propio context window.
Puede leer los ficheros del proyecto (dentro del sandbox).
Puede correr shell commands (dentro del sandbox).
Tiene su propia memoria (separada de la del Coordinator).

El Assistant se comunica con el sub-agent a través del CLI del sub-agent. El CLI está documentado en Cheatsheet → Codex CLI.

Sandbox and trust

El coding sub-agent corre en un sandbox. El sandbox level es configurable por invocación:

Level	What the sub-agent can do
`read-only`	Lee ficheros; no puede modificar nada.
`workspace-write`	Lee y escribe dentro del project directory.
`full`	Lee y escribe cualquier cosa que el host pueda.

El default es workspace-write para tasks de code-generation. El nivel full se reserva para tasks que requieren acceso de producción (raro; solo con autorización explícita del usuario).

El sandbox se configura por proyecto. La configuración vive en el main configuration file del framework. Un proyecto que no tenga configuración cae a read-only.

Para los proyectos del lab, la configuración está en {workspace-root}/{project}/.agents/config.toml (o en la config global del framework). El formato es:

[projects."{workspace-root}/{project}"]
trust_level = "trusted"

El nivel trusted es equivalente a workspace-write.

Prompting

El Coding Assistant redacta el prompt. El prompt tiene la siguiente estructura:

# Goal
What the task is. One paragraph.
 
# Context
The relevant files, the relevant skills, the relevant
architecture decisions. Citations to the project's
`AGENTS.md`, `SKILL.md`, and `TOOL.md`.
 
# Constraints
What the sub-agent must NOT do. Examples: do not modify
unrelated files, do not commit, do not push.
 
# Acceptance criteria
How the result will be evaluated. Examples: the tests
pass, the lint passes, the documentation is updated.
 
# Reference
Links to relevant docs in the project.

El prompt describe what to build, no cómo construirlo. Nunca se incluye código pre-escrito; el sub-agent escribe código original a partir de la descripción.

El prompt se escribe en inglés. La explicación de cara al usuario (qué está haciendo el Assistant y por qué) se hace en el idioma del usuario (español para Kone).

Workflow

El workflow del Coding Assistant es el loop canónico "design → prompt → code → review → integrate → test".

Loading diagram…

El Assistant itera en los pasos "review" y "test" hasta que el resultado sea aceptable. El loop está acotado por un número máximo de iteraciones (default 3).

Code review

El Assistant revisa el código antes de integrarlo. La review es informal pero consistente:

El código sigue las conventions del proyecto.
El código hace lo que pedía el prompt.
El código no introduce dependencias nuevas sin justificación.
El código no modifica ficheros no relacionados.
El código incluye tests (si el proyecto tiene tests).
El código incluye documentation (si el proyecto tiene documentation requirements).
El código no contiene secrets, credentials ni datos personales.

Si la review falla, el Assistant devuelve la review al sub-agent con una explicación clara de lo que tiene que cambiar. El sub-agent revisa y devuelve el código.

Integration

El Assistant integra el código así:

Lee los ficheros que escribió el sub-agent.
Los mueve a la ubicación correcta en el proyecto.
Actualiza los ficheros relacionados (imports, configs).
Actualiza la documentation (si el proyecto tiene documentation rule).
Verifica que el proyecto sigue compilando.

El Assistant usa el directory layout y las file-naming conventions del proyecto. Las conventions están documentadas en el AGENTS.md o README.md del proyecto.

Test running

El Assistant corre los tests del proyecto tras la integración. El test command es específico del proyecto:

Node project: npm test o pnpm test.
Python project: pytest o unittest.
Mixed project: ambos.

El Assistant corre los tests y parsea el output. Si los tests pasan, la task está completa. Si los tests fallan, el Assistant devuelve el fallo al sub-agent con el error output.

El coding sub-agent puede ser matado por el OS (SIGKILL) cuando su task es demasiado grande. El síntoma es exit code 137 y una log line que contiene Killed. Esta es una hard constraint del entorno del sub-agent.

Recovery procedure

Cuando el sub-agent es matado, el Assistant sigue este procedimiento:

Do not write the code by hand. La recovery rule es absoluta. El Assistant nunca escribe código directamente.
Identifica la task que mató al sub-agent. Suele ser el fichero más grande o la fase más compleja.
Splitea la task en prompts más pequeños. La recommended rule: one file per prompt. Los prompts más pequeños tienen menor memory y menor latency.
Vuelve a correr con un timeout más largo (recomendado: 120-180s para tasks pequeñas).
Si el sub-agent sigue muriendo, considera un split más agresivo: primero el header-only del fichero, luego la implementación, luego los tests.

Si el sub-agent no se puede recuperar tras tres intentos con prompts progresivamente más pequeños, el Assistant se detiene y pide ayuda al Coordinator. El Coordinator puede necesitar ajustar el entorno (memory, swap) o usar un execution path distinto.

La recovery rule está documentada en Runbook → Coding Assistant killed by timeout.

Git

El Coding Assistant nunca hace commit, push ni pull. Git es responsabilidad del Coordinator. El Assistant deja los cambios sin commitear; el usuario decide cuándo commitear y qué escribir en el commit message.

El Assistant puede usar git status y git diff para verificar los cambios; no corre git commit, git push ni git pull.

Configuration

La configuration del Coding Assistant:

Field	Type	Default	Purpose
`coding_assistant.subagent_cli`	string	`codex`	El CLI command del sub-agent.
`coding_assistant.max_iterations`	integer	`3`	Máx. iteraciones de review/test.
`coding_assistant.timeout_s`	integer	`180`	Per-invocation timeout.
`coding_assistant.prompt_template`	string	(ver arriba)	El prompt template.
`coding_assistant.trust_level`	string	`workspace-write`	El sandbox level por defecto.

Failure modes

Failure	Assistant response
Sub-agent is killed by timeout	Aplicar la recovery procedure (split prompts).
Sub-agent returns invalid code	Devolver la review; iterar.
Tests fail	Devolver el fallo; iterar.
Project does not have a configuration	Caer a `read-only`; surface un warning.
Git conflict	Surface el conflict; pedir al usuario que lo resuelva.
Sub-agent is unavailable	Surface el error; ofrecer reintentar más tarde.
Sub-agent introduces a security issue	Rechazar el código; surface el issue al usuario.

El failure catalog completo está en Failure Catalog.

Future work

Multi-file prompts. Soporte para prompts que abarcan múltiples ficheros en una sola invocación, con boundaries explícitos.
Patch mode. Soporte para enviar un diff de vuelta al sub-agent en lugar del fichero completo.
Test-driven prompts. Generar el prompt a partir de un fichero de tests.
Sub-agent failover. Soporte para múltiples sub-agents con failover automático.