Onboarding técnico · trabajo real dentro de las barandas

Guía del practicante
de Agent Squad

El arco tiene dos etapas: primero el anillo de verificación (el asiento con mejor vista del sistema entero), después una pieza del catálogo con tu nombre. Todo lo de esta guía es verificable con un comando: acá nada "está listo" porque alguien lo diga, está listo porque algo lo recorrió y lo probó.

REPO agent-squad-app STACK Bun · Hono · SvelteKit 2 con Svelte 5 · Postgres · Inngest ACTUALIZADA 2026-10-24
0/0

DÍA 0 El entorno: que todo corra antes de tocar nada

Cada checkpoint tiene su comando y su resultado esperado. Si un número no te da, NO sigas: avisale a tu mentor con el output completo: un entorno torcido te va a hacer perder días persiguiendo fantasmas.

MAPA El sistema en 10 lecturas, en este orden

No leas "todo el repo": leé estas 10 piezas en orden y anotá UNA pregunta por archivo para tu mentor. El orden importa: va del borde al corazón.

01

docs/superpowers/plans/

Cómo se especifica acá: cada task con archivos exactos y un bloque Done when verificable (116 de los 126 planes de esa carpeta lo traen, al 24-oct-2026). Vas a escribir los tuyos igual.

02

apps/api/src/index.ts

El arranque del servidor completo (705 líneas): qué rutas van detrás de qué guardia (bearer, token de delegación, límites de ritmo). Notá el idleTimeout: 255 y preguntate por qué existe: es una cicatriz real. El default de Bun (10 s) mataba el streaming del chat cuando el modelo razonaba en silencio, y 255 es lo máximo que Bun acepta.

03

apps/api/src/middleware/rate-limit.ts

Una ventana deslizante con reloj inyectable (55 líneas). Es la clase magistral de "cómo hacer testeable algo que depende del tiempo". Después buscá en index.ts qué límites usa cada ruta.

04

packages/substrate-spec/src/templates/standup-digest-v1.ts

Una plantilla es un grafo tipado de pasos: qué operación hace cada uno, qué reintentos tiene, dónde está la compuerta humana. Casi ningún paso trae actor fijo (solo el evaluador system:evaluator y el dueño humano human:owner): el resto se ata al roster del workspace al lanzar. Acá entendés qué ES el trabajo en este sistema.

05

apps/api/src/inngest/operations/index.ts

El catálogo en ejecución: 71 handlers registrados (el catálogo tiene 75 pares id@versión, al 24-oct-2026). Los que faltan no son un olvido: human_gate.approve y human_task los resuelve el propio motor (la corrida queda esperando a una persona), y slack.post y github.gist_create solo se pueden despachar si FORGE forjó una capacidad con ese id. Cuando entiendas por qué, entendiste la arquitectura.

06

apps/api/src/substrate/launch-plan.ts

assertHumanGatePresent: la gobernanza escrita como código. Ningún plan que pase por launchCompiledPlan (los que compone Nova y los SuperSkills propios) puede lanzarse sin un gate humano terminal, y todo gate tiene que fallar al vencer: la auto-aprobación no existe.

07

apps/api/src/substrate/nova-compose.ts

El lugar donde el modelo "diseña" planes, y por eso de los más vigilados: solo operaciones del catálogo, grafo sin ciclos (isAcyclic), tope de 16 pasos y de 4 pasos con modelo, y el costo estimado (cost_estimate) lo calcula el servidor. Mirá también los 7 desenlaces posibles. La filosofía de la casa: validá al modelo, no le creas.

08

apps/web/src/hooks.server.ts

El guardián de CADA request: cookie, refresh de sesión, gate de acceso que falla cerrado (error al leer = no autorizado), workspace del usuario y gate de onboarding. Mirá también el triple candado del bypass de tests (dev, CI=true y NODE_ENV distinto de production).

09

apps/web/src/lib/stores/userState.ts

La cola de escritura: por qué dos escrituras del estado del usuario no se pisan, la generación que corta a una pestaña que quedó del otro lado de un reset, y el revert si la escritura falla. Todo estado del usuario pasa por acá, nunca por un fetch directo.

10

db/substrate/migrations/0001_init.sql

El modelo de datos fundacional: intents, artifacts y claims, con la regla de que todo claim y artifact tiene un camino de linaje hasta su origen. Leé los comentarios SQL, que explican cada porqué (ojo: el de las 3072 dimensiones quedó viejo, los embeddings de hoy son de 384). Después leé apps/api/db/substrate/migrations/0044_orquestacion_v2_fase0.sql, donde nacen las corridas (runs, run_events, work_items) que reemplazaron a plans, traces y step_executions.

ETAPA 1 El anillo de verificación

Semanas 1-3. Para verificar un paso tenés que entender todas las capas que atraviesa, por eso se empieza acá.

Misión 1 · tu primer test E2E

Escribí un spec E2E nuevo con el mock del motor

Elegí con tu mentor un flujo chico sin cubrir. El patrón de la casa: la web se prueba contra un mock del motor en el puerto 4998: sin LLM, sin producción, determinista.

  1. Leé tests/e2e/16b-nova-compose.spec.ts y tests/e2e/helpers/substrate-mock.ts: ahí está el patrón completo (handlers por endpoint, beforeEach que resetea estado).
  2. Si tu flujo necesita un endpoint que el mock no tiene, agregale el handler calcando uno existente.
  3. Escribí el spec: primero el caso feliz, después el caso en que el motor falla (¿qué ve el usuario si devuelve 500?). En Svelte 5, waitForLoadState('networkidle') antes de cada click: sin ese gate, los listeners pueden no estar montados.
  4. Corré TODO dos veces: los tests que pasan "a veces" no pasan.
Done when

ETAPA 2 Una pieza del catálogo con tu nombre

Semanas 4+. La Operation es LA unidad de aprendizaje: contrato tipado, costo, reintentos, evaluación. Chica, real y segura.

Misión 2 · tu primera Operation

Construí una operation determinista de punta a punta

Con tu mentor definan una operation SIN LLM (ej.: una transformación de texto, un agregado sobre claims existentes). Sin modelo en el medio, el feedback es instantáneo y aprendés el contrato puro.

  1. Definí la spec (un archivo en packages/substrate-spec/src/operations/) y agregala a la lista REGISTERED de operations/catalog.ts: id versionado (tuop.algo@1.0.0), inputs y output tipados, side_effects declarado. Mirá cómo lo hace audience.load: no usa modelo y solo lee un archivo.
  2. TDD: escribí el test del handler ANTES del handler (patrón de los tests vecinos en apps/api/src/inngest/operations/).
  3. Implementá el handler en apps/api/src/inngest/operations/ y registralo en operations/index.ts con registerOperation.
  4. Probá que un plan que la usa pasa la validación del catálogo, y que tu operation declara su costo aunque sea $0: devolvé costoSinLlamada() (apps/api/src/substrate/costo-operacion.ts). Un costo sin el campo de caja se lee como desconocido, y a partir de ahí la corrida deja de autorizar gasto adicional.
Done when

REGLAS Las 8 de la casa, cada una con su cicatriz

Ninguna es teórica: todas salieron de un incidente real. Conocer la cicatriz es lo que evita repetirla.

R1
Test primero, código después.Los planes de acá traen "Done when" por algo: si no sabés cómo se verifica, no sabés qué estás construyendo.
R2
CI=true para todo E2E local.Sin eso el bypass de auth no se activa y vas a "encontrar" regresiones que no existen.
R3
Al mockear el módulo LLM, mockeá SOLO generateLLMText.La suite del motor corre sin gateway y con LLM_CALLS_PERSIST=off (apps/api/vitest.config.ts): un test que llame al modelo de verdad cuesta plata y no tiene que escribir en llm_calls. Y un mock que reemplaza exports de más tapa comportamiento real. (El origen fue un incidente de junio con el runner nativo de Bun, donde el mock de módulos es global; no se reverificó hoy.)
R4
Identidad, sesiones y auth no se tocan en pasantía.Ahí los errores no son aprendizajes: son incidentes de seguridad.
R5
Todo estado del usuario va por la write-queue.El endpoint guarda el estado con una generación (state_generation): una pestaña que quedó del otro lado de un reset recibe un 409 y no puede revivir lo borrado. La cola de userState.ts ordena las escrituras y revierte si una falla; un fetch directo se salta las dos cosas.
R6
Texto que ve el usuario: cero jerga técnica.En la oficina se dice "equipo", "trabajo" y "SuperSkill", no "draft", "template" u "operación". El vocabulario técnico es nuestro, no del usuario (hay pruebas que lo cuidan, por ejemplo apps/web/src/lib/office/manifiesto-line.test.ts).
R7
Probás con TU cuenta de prueba, nunca con la de un cliente, y lo sintético se limpia.Cada usuario tiene su propio workspace y las cuentas de prueba se reinician seguido (scripts/reset-user.sh), pero lo que lanzás en producción consume modelos reales y deja datos. Tu mentor limpia tu workspace de prueba al terminar el lab, y vos nunca aprobás ni borrás nada que no hayas creado vos.
R8
Web y motor se despliegan por separado y ninguno espera al otro.La web sale por el job deploy del CI y la API por un cron cada 3 minutos que despliega solo con el CI verde. Durante esa ventana el motor viejo habla con la web nueva, o al revés (un comentario de apps/web/src/lib/squads/store.ts lo cuenta con un caso real). Diseñá cada cambio de contrato para que sobreviva a las dos mitades: aditivo, con valores por defecto, y que degrade sin romper.

VOCAB Ocho palabras y ya hablás el idioma

TérminoQué es
IntentEl pedido por escrito: qué quiere lograr quién. El punto de partida auditado de toda ejecución.
GrafoLa plantilla de un plan compilada a un grafo tipado de nodos (graphs y graph_nodes), validado por el servidor antes de existir.
OperationLa unidad de trabajo con contrato: inputs tipados → output + costo. 75 pares id@versión en el catálogo (71 ids distintos), al 24-oct-2026.
CorridaUna ejecución concreta del grafo (runs), con su acta de eventos (run_events) y un work item por cada nodo despachado, con su costo real. Reemplazó a la trace del motor viejo.
ArtifactLo producido (digest, brief, video…), direccionable por contenido, con máquina de estados.
ClaimUn hecho tipado (sujeto, predicado, objeto) con provenance: el nodo que lo produjo. La memoria del equipo, consultable con SQL.
Human gateLa compuerta: la corrida queda en awaiting_human hasta que una persona decide en la app. El plazo es de 72 h y, si vence, el gate falla: nunca se auto aprueba.
SuperSkillLa palabra de producto para un flujo empaquetado: de fábrica o promovido por el usuario.

"No te escondemos en una esquina inofensiva: te damos trabajo real dentro de las mismas barandas que le pusimos a la IA. Si la arquitectura contiene a un modelo impredecible, te contiene a vos, y por eso desde la semana uno tu trabajo cuenta."

La regla de la casa para practicantes