Vision general

Agent Squad es un monorepo TypeScript sobre Bun con tres piezas principales y un substrato de ejecucion detras.

Piezas del repositorio

Workspace	Rol	Stack
apps/api	API del substrato: rutas HTTP, discovery de Nova, orquestacion de operaciones, FORGE	Hono sobre Bun
apps/web	Experiencia del usuario: onboarding, propuesta de squad, oficina, Acuerdo de Operacion	SvelteKit 5
packages/substrate-spec	Catalogo de operaciones versionado y sus templates	TypeScript puro

El grafo del codigo cuenta hoy alrededor de 489 modulos, 224 rutas, 444 interfaces y 27 paquetes internos. La API es el corazon: expone las rutas, coordina el discovery, y despacha operaciones a la capa durable.

Planos del substrato

El diseno separa el plano de control soberano de la plomeria alquilada:

• Plano de control (nuestro): el catalogo de operaciones versionado, la credencial soberana Bearer, el Tool Broker con grants y una politica default-deny, y el discovery de Nova.
• Plano de ejecucion durable: Inngest ejecuta las operaciones como pasos idempotentes; Postgres es la fuente de verdad.
• Plano generativo: FORGE genera y ejecuta codigo del modelo en un sandbox por proceso, gobernado por una allowlist de capabilities forjables.

Rutas principales de la API

Extraidas del grafo del codigo. Son los puntos de entrada reales del substrato:

• /api/discovery/chat y /api/discovery/charter: el discovery conversacional de Nova y el Acuerdo de Operacion.
• /api/workspaces/:id/chat y /api/workspaces/:id/compose: interaccion y composicion de trabajo por workspace.
• /api/intents: intents que disparan operaciones del substrato.
• /api/forge/*: superficie de FORGE.
• /api/approvals y /api/approvals/*: los puntos de decision humana.
• /api/slo: senales de salud y objetivos de servicio.
• /oauth/youtube/*: integracion de publicacion.

El flujo de una necesidad

1. El usuario describe su necesidad en lenguaje natural en el onboarding.
2. Nova interpreta, propone una triada de agentes (entre 2 y 3), y ajusta la propuesta hasta que el usuario confirma. No hay eleccion manual de un catalogo: Nova propone.
3. En el Acuerdo de Operacion, Nova explica como trabaja el squad: el alcance de cada agente, donde se espera una decision del humano, y donde empieza la responsabilidad de cada uno.
4. El trabajo se traduce en operaciones del catalogo, que corren en la capa durable con reintentos y estado en Postgres.
5. Los approvals marcan los puntos donde el humano decide antes de que el substrato avance.

Segui con El substrato soberano para el detalle de cada plano.