Workspaces agénticos: submódulos, skills, conocimiento y entrega guiada por especificaciones

En nuestra experiencia, la mayoría de los equipos no tienen un problema de monorepo, sino de coordinación: varios repositorios, un mismo producto y agentes que olvidan el contexto entre sesiones.

Un workspace agéntico es un metarrepósito que no reemplaza los repos de tus aplicaciones, sino que los agrupa. Cada servicio conserva su historial de git independiente, pero los agentes tienen un único punto de entrada: código sincronizado en apps/, skills del workspace, una capa .knowledge/ para guías prácticas y ADRs, y herramientas guiadas por especificaciones (OpenSpec o GitHub Spec Kit) para planificar cambios. Piensa en el workspace como la capa de plataforma: convenciones, skills y especificaciones compartidas de las que dependen los repos apps/* sin fusionar sus historiales.

El July 8, 2026, revisé la documentación oficial de submódulos de Git, los repos y la documentación de OpenSpec y GitHub Spec Kit, el formato abierto Agent Skills en agentskills.io y las guías de Cursor y Claude Code sobre skills y agentes en la nube. Los patrones de flujo de trabajo y las estructuras de directorios que aparecen a continuación combinan esas fuentes primarias con una síntesis editorial de configuraciones de agentes para múltiples repositorios; se indica dónde hay inferencias.

Audiencia: Este artículo está dirigido a ingenieros y arquitectos que implementan el patrón, y también considera a PMs y scrum masters que necesitan entender la cadencia de entrega, los riesgos y qué significa «terminado» en un ciclo de agentes guiado por especificaciones.

En resumen

• Un workspace agéntico es un repo raíz que contiene submódulos (normalmente en apps/), skills (.cursor/skills/ o .claude/skills/), conocimiento duradero (.knowledge/ o docs/) y herramientas de especificación (openspec/ o .specify/ + specs/).
• El ciclo diario es predecible: sincronizar submódulos → consultar el conocimiento → proponer/aplicar una especificación → trabajar dentro de un submódulo → revisar el PR → clasificar los comentarios → actualizar el conocimiento → retrospectiva.
• Los submódulos de Git permiten fijar dependencias de forma auditable (cada actualización es un commit revisado), pero exigen disciplina: incluir los submódulos de forma recursiva al hacer pull, hacer push de sus commits antes que los del repo padre y automatizar las actualizaciones con --remote bajo medidas de protección.
• La actualización del conocimiento funciona mejor como una auditoría programada o activada por un PR, no como una tarea manual de copiar y pegar después de cada merge.
• OpenSpec se adapta a la iteración flexible sobre proyectos existentes mediante especificaciones de cambios; GitHub Spec Kit se adapta a entregas con múltiples fases guiadas por una constitución. Muchos equipos usan OpenSpec en el workspace y Spec Kit en los repos individuales de aplicaciones, o eligen uno de los dos.
• El beneficio (criterio editorial): clonar el workspace y ejecutar el ciclo, en local o en Cursor Cloud Agents / Claude Code on the web, sin reconstruir el contexto desde cero cada vez.

Qué aprenderás aquí

• Qué pertenece a un workspace agéntico y qué permanece en los repos de aplicaciones
• Una estructura de directorios de referencia y un ciclo diario de siete pasos que puedes automatizar
• Cómo mantener actualizados los punteros de submódulos sin romper los flujos de trabajo con HEAD desacoplado
• Cómo .knowledge/ y los ADRs proporcionan un contexto compartido a agentes y personas
• Dónde encajan OpenSpec y Spec Kit en el ciclo y cómo elegir entre ellos
• Fallas comunes —desviaciones, documentación desactualizada y ciclos de revisión— y soluciones prácticas
• Por qué este patrón escala a múltiples copias para agentes en la nube y funcionalidades que abarcan varios repos

El problema: realidad polyrepo, expectativas de monorepo

Los equipos de producto rara vez pueden reunir todo en un solo repositorio. Puedes tener un frontend, una API, un pipeline de datos, Terraform compartido y bibliotecas internas, cada uno con su propia cadencia de releases y sus responsables.

Los agentes intensifican el problema:

• Contexto disperso entre repos, tickets e historiales de chat
• Ninguna guía estable sobre «cómo trabajamos aquí», a menos que alguien vuelva a pegarla en cada sesión
• Funcionalidades que abarcan varios repos planificadas en un documento que nunca se actualiza después de integrar los PRs

Un workspace agéntico no fusiona los historiales de git. Orienta al agente de la misma manera que un buen equipo de plataforma orienta a una persona recién incorporada: estos son los repos, así especificamos el trabajo, esto ya lo decidimos y estas son las skills para las tareas habituales.

Without workspace                    With agentic workspace
─────────────────                    ──────────────────────
Agent opens repo A                   Agent opens workspace root
  → misses repo B context              → syncs apps/* submodules
  → reinvents conventions              → reads .knowledge/conventions.md
  → specs live in chat                 → /opsx:propose or /speckit.specify
  → PR review is ad hoc                → pr-reviewer skill + triage loop

Estructura de referencia

Trata la raíz como un índice conciso. Mantén CLAUDE.md o AGENTS.md por debajo de ~100 líneas y enlaza a archivos de skills y conocimiento que los agentes carguen bajo demanda (divulgación progresiva).

agentic-workspace/
├── AGENTS.md / CLAUDE.md       # Entry point: where to look next (see example below)
├── .gitmodules                 # Submodule manifest
│
├── apps/                       # Submodule mount points
│   ├── web/                    # → github.com/org/web-app
│   ├── api/                    # → github.com/org/api-service
│   └── infra/                  # → github.com/org/terraform
│
├── .cursor/  (or .claude/)
│   ├── skills/
│   │   ├── workspace-sync-submodules/
│   │   ├── get-knowledge/
│   │   ├── update-knowledge/
│   │   ├── audit-knowledge/
│   │   ├── openspec-propose/          # if using OpenSpec
│   │   ├── pr-triage-fix-loop/
│   │   └── session-retrospective/
│   ├── commands/               # Slash aliases for spec workflows
│   └── subagents/              # Focused reviewers (read-only)
│
├── .knowledge/                 # Durable how-to + decisions
│   ├── README.md               # Index for agents
│   ├── conventions.md
│   ├── runbooks/
│   └── adr/
│       └── 001-segment-id-format.md
│
├── openspec/                   # OpenSpec (optional)
│   ├── config.yaml
│   ├── specs/                  # Canonical capability specs
│   └── changes/                # In-flight deltas
│
│   — or —
│
├── .specify/ + specs/          # GitHub Spec Kit (optional)
│
└── llms.txt                    # Optional machine-readable nav index (llmstxt.org)

Punto de entrada mínimo del workspace: mantenlo como un índice, no como un volcado de todas las reglas:

# AGENTS.md

## Repos (submodules under apps/)
- apps/web — customer-facing UI
- apps/api — REST + event handlers
- apps/infra — Terraform modules

## Before planning
1. Run workspace-sync-submodules skill
2. Read @.knowledge/README.md and relevant ADRs

## Spec workflow
- Cross-repo changes: /opsx:propose at workspace root (OpenSpec)
- Single-service work: follow skills in the target apps/* repo

## Skills catalog
See .cursor/skills/*/SKILL.md — load on demand, not all at once.

llms.txt es opcional: es un pequeño archivo de navegación que ayuda a los agentes a descubrir documentación duradera sin recorrer todo el árbol.

Qué permanece en los submódulos de aplicaciones: código de la aplicación, pruebas específicas del servicio, CI del servicio y reglas de agentes locales al repo cuando un equipo es su único responsable.

Qué vive en la raíz del workspace: especificaciones que abarcan varios repos, skills compartidas, conocimiento que cruza servicios y automatización que afecta varias rutas apps/*.

El ciclo diario de siete pasos

Este es el flujo de trabajo al que suelen llegar los equipos una vez que cuentan con skills para cada paso. Los nombres son ilustrativos; adáptalos a tu registro de skills.

        ┌───────────────────────────────────────────────┐
        │  1. workspace-sync-submodules                 │
        │     keep apps/* on agreed branches/commits    │
        │                                               │
        │  2. get-knowledge                             │
        │     ground in .knowledge before planning      │
        │                                               │
        │  3. /opsx:propose → /opsx:apply               │
        │     (or /speckit.specify → … → implement)     │
        │     ── implement inside the target submodule ─│
        │                                               │
        │  4. custom pr-reviewer-agent                  │
        │     audit diff against spec + conventions     │
        │                                               │
        │  5. custom pr-triage-fix-loop                 │
        │     resolve review comments until green       │
        │                                               │
        │  6. update-knowledge                          │
        │     capture ADRs, runbook deltas, spec sync   │
        │                                               │
        │  7. session-retrospective                     │
        │     reflect: what skill/knowledge gap appeared│
        └───────────────────────────────────────────────┘

Paso 1 — Sincronizar submódulos

Objetivo: Que cada sesión de agente comience con los mismos SHA de apps/* que espera tu equipo.

Una skill del workspace encapsula los comandos oficiales de Git:

# Pull parent and recurse into submodules (team-wide default)
git config submodule.recurse true
git pull --recurse-submodules

# Advance submodules to latest on their tracking branch
git submodule update --remote --merge --recursive

# Stage pointer updates in the parent
git add apps/
git commit -m "chore(workspace): bump submodule pointers"

Nota editorial: Fija tags cuando necesites estabilidad; sigue los últimos commits de las ramas cuando necesites actualizaciones diarias. Esa decisión es organizacional, no técnica; consulta Mantener los submódulos actualizados sin sorpresas más adelante.

Nota para arquitectos: Los agentes en la nube (Cursor Cloud, Claude Code on the web) necesitan credenciales para los repos privados de submódulos; el token usado para hacer checkout del repo padre no siempre es suficiente. Los runners de CI deben establecer submodules: recursive en los pasos de checkout; los clones predeterminados dejan apps/* vacío.

Paso 2 — Consultar el conocimiento

Antes de /opsx:propose o /speckit.specify, el agente ejecuta get-knowledge: lee .knowledge/README.md, los ADRs relevantes y cualquier runbook asociado a la capacidad. Este paso cuesta poco en comparación con reconstruir la arquitectura a partir del código fuente en cada tarea.

Para PMs y scrum masters: traten esto como la comprobación de la definición de listo para el trabajo del agente. Si falta conocimiento, el agente debe detenerse y registrar la brecha, no inventar una política.

Paso 3 — Especificar e implementar en el submódulo correcto

Las funcionalidades que abarcan varios repos reciben una especificación a nivel de workspace con tareas identificadas por repo:

## tasks.md (workspace root)

- [ ] apps/api: add UUID column migration
- [ ] apps/api: expose segment lookup endpoint
- [ ] apps/web: map CDP UUID to segment in settings UI
- [ ] .knowledge: document segment ID format in adr/002-...

OpenSpec almacena los cambios en openspec/changes/<feature-id>/; Spec Kit usa carpetas de funcionalidades en specs/<feature-id>/. Para conocer las diferencias entre las herramientas, consulta OpenSpec vs GitHub Spec Kit.

Los commits de implementación se hacen dentro del árbol de trabajo del submódulo; el workspace registra el puntero actualizado cuando se integra el PR del submódulo.

Pasos 4–5 — Revisar y clasificar comentarios

Este es un patrón que puedes construir como skills del workspace, no una afirmación de que todas las herramientas incluyan estos nombres de forma predeterminada. Una skill (o subagente) pr-reviewer-agent comprueba:

• La implementación frente a los escenarios de la especificación
• Las convenciones de .knowledge/conventions.md
• La finalización de tareas que abarcan varios repos

pr-triage-fix-loop convierte los comentarios de revisión en tareas de seguimiento, vuelve a ejecutar las pruebas y hace push hasta que CI esté en verde. Aquí ayudan las herramientas MCP: la API de GitHub para los hilos de revisión, Jira para los tickets vinculados y las herramientas internas de observabilidad para los IDs de trazas mencionados en la especificación. La sección de MCP más adelante muestra la estructura de servidor para esas integraciones.

Pasos 6–7 — Capturar conocimiento y hacer la retrospectiva

update-knowledge extrae hechos duraderos de la carpeta de cambios y los incorpora al conocimiento compartido:

• Un ADR nuevo si la decisión volverá a consultarse
• Una edición del runbook si cambiaron los pasos para el equipo de guardia
• /opsx:archive o el paso equivalente de finalización y archivado de Spec Kit para incorporar las especificaciones a la fuente de verdad canónica

Estos dos pasos van juntos porque la captura de conocimiento debe ocurrir antes de la retrospectiva. session-retrospective es ligero: una nota en markdown por semana que indica qué skill falló, qué documento estaba desactualizado y qué automatización se debe agregar. Esto alimenta el trabajo de plataforma del siguiente sprint.

# session-retrospective/2026-07-08.md

- **Goal:** CDP UUID → segment mapping (cross-repo)
- **Worked:** get-knowledge + /opsx:propose at workspace root
- **Failed:** pr-triage-fix-loop — agent pushed parent before submodule commit
- **Automate next:** pre-push hook for push.recurseSubmodules=check

Cadencia de entrega para PMs y scrum masters

No necesitas ejecutar el ciclo de agentes personalmente para beneficiarte de él. Relaciónalo con las ceremonias que ya conoces:

Orden de merge para funcionalidades que abarcan varios repos: PRs de API/backend antes que los de UI; el PR que actualiza los punteros del workspace va al final. Usa un mismo ID de especificación del workspace en las épicas de Jira/Linear para mantener alineados los tableros.

Skills que querrás tener en el workspace

Las skills siguen el formato abierto emergente Agent Skills: una carpeta con SKILL.md, scripts opcionales y una descripción que los agentes usan para identificar la skill adecuada antes de cargar las instrucciones completas.

Para los ingenieros, la primera skill útil suele ser un wrapper de sincronización de submódulos con medidas de protección:

---
name: workspace-sync-submodules
description: Keep apps/* submodules current and report drift before agent work starts.
---

1. Run `git submodule sync --recursive`.
2. Run `git submodule update --init --recursive`.
3. If asked to refresh pointers, run `git submodule update --remote --merge --recursive`.
4. Report `git submodule status` prefixes (`+`, `-`, `U`) before editing.
5. Never commit inside a submodule unless it is on a named branch.

Las skills del workspace son distintas de las skills del repo dentro de apps/api/.cursor/skills/. Las skills del workspace orquestan; las del repo implementan patrones específicos del servicio (migraciones, estilo de API, etc.). Inferencia editorial: cuando las skills viven dentro de un submódulo, hacer checkout de un SHA más reciente puede cambiar las skills disponibles; fija los SHA si necesitas un comportamiento reproducible de los agentes entre sesiones.

Para conocer el modelo de madurez de skills (prompt → skill → MCP → plugin), consulta La evolución de la orquestación de agentes de IA.

Mantener los submódulos actualizados sin sorpresas

Esta es la queja operativa más común sobre los workspaces basados en submódulos.

Mecánica oficial (respaldada por fuentes)

Git almacena las referencias a submódulos como gitlinks: SHA de commits en el repo padre (documentación de git-submodule). Actualizar el código de origen es un proceso de dos pasos: mover el árbol de trabajo del submódulo y luego hacer commit del nuevo puntero en el repo padre.

Configuraciones habituales de equipo, basadas en opciones documentadas de Git y respaldadas por guías comunitarias sobre submódulos:

git config --global submodule.recurse true
git config --global push.recurseSubmodules on-demand
git config --global status.submodulesummary 1

En automatizaciones, prefiere siempre --merge o --rebase junto con --remote; usar solo --remote puede descartar trabajo del submódulo que aún no tiene commit.

Patrones de automatización

Una variante más madura actualiza un submódulo por PR para que CI pueda atribuir correctamente las fallas. A July 2026, el workflow de aerospike-ce-ecosystem/workspace ofrece un ejemplo.

Protección frente a HEAD desacoplado

git submodule update hace checkout con un HEAD desacoplado. Los agentes y las personas deben crear una rama antes de hacer commit:

cd apps/api
git checkout -b feat/segment-lookup
# ... work ...
git push origin feat/segment-lookup
cd ../..
git add apps/api
git commit -m "chore: point api at feat/segment-lookup"

Incorpora esta regla en workspace-sync-submodules y en .knowledge/conventions.md para que los agentes en la nube no dejen commits huérfanos.

Mantener actualizados el conocimiento y los ADRs

Los archivos estáticos de .knowledge/ se desactualizan rápidamente si su actualización no forma parte del ciclo de entrega.

Qué almacenar

Usa una plantilla de ADR consistente: Estado, Contexto, Decisión, Consecuencias.

Eventos que activan la actualización

1. Al archivar — Cuando OpenSpec archiva un cambio o Spec Kit completa la implementación, update-knowledge extrae las decisiones que vale la pena conservar.
2. Auditoría programada — El subagente audit-knowledge compara semanalmente lo que afirma .knowledge/ con main en apps/* (archivos de muestra, variables de configuración y rutas públicas). El resultado es un PR, no un resumen en el chat.
3. Hook para PRs del equipo — GitHub Action opcional en los repos de aplicaciones: si un PR toca áreas asociadas en .knowledge/index.yaml, agrega un comentario con una lista de verificación para actualizar el conocimiento del workspace. Inferencia editorial: pocos equipos automatizan esto por completo desde el primer día; comienza manualmente y automatiza cuando las asociaciones se estabilicen.

Antipatrón

No pegues descripciones completas de PRs en los ADRs. Enlaza el PR y documenta la decisión y el invariante que necesita el siguiente agente.

OpenSpec vs Spec Kit en el workspace

Ambas herramientas abordan la divergencia de las especificaciones en entregas asistidas por IA; se ubican en la raíz del workspace o en repos individuales de apps/*, según las necesidades de gobernanza.

División práctica (recomendación editorial): En un workspace, la elección incorpora una tercera dimensión: la estructura de git. Cuando una funcionalidad cruza límites de submódulos, el modelo de cambios en la raíz de OpenSpec evita que el patrón de una rama por funcionalidad de Spec Kit entre en conflicto con los punteros de submódulos del workspace.

• Raíz del workspace + OpenSpec para cambios que abarcan varios repos, afectan múltiples rutas apps/* y requieren iteración rápida.
• Repo de aplicación + Spec Kit cuando un solo servicio necesita TDD estricto, cumplimiento normativo o controles entre fases.

Consulta la comparación complementaria para conocer el análisis completo: OpenSpec vs GitHub Spec Kit.

Las skills de Cursor se descubren en .cursor/skills/, según la documentación de skills de Cursor; aplicar esto a Cursor Cloud Agents es una inferencia basada en el mismo modelo de checkout del workspace. El flujo de inicialización de OpenSpec puede generar archivos de skills específicos para Cursor y Claude Code; consulta la documentación de herramientas compatibles de OpenSpec. Spec Kit usa specify init --here --ai cursor-agent, según el README de Spec Kit.

Comparación detallada: OpenSpec vs GitHub Spec Kit. Patrones de Spec Kit para polyrepo: Integrar Spec Kit en repos existentes.

Local y nube: mismo ciclo, distinto harness

El patrón de workspace es independiente del harness. El ciclo se mantiene; solo cambia la forma de ejecutarlo.

Ventaja de escala en la nube (criterio editorial): puedes crear múltiples clones del workspace —uno por rama de funcionalidad o por repo en una iniciativa transversal— sin volver a cargar el contexto manualmente. Cada clon hereda las skills y el conocimiento del mismo commit raíz.

Para el diseño de subagentes en entornos de nube, consulta Diseño de subagentes en la nube y Subagentes de Cursor y Claude Code.

Funcionalidades entre repos: especificación en la raíz, código en los submódulos

El trabajo entre repos falla cuando la especificación vive en el README de una aplicación y el otro equipo nunca la ve.

Patrón:

1. Crea openspec/changes/001-cdp-uuid-to-segment/ (o specs/001-cdp-uuid-to-segment/ para Spec Kit) en la raíz del workspace.
2. Las especificaciones de cambios nombran capacidades asociadas a submódulos (cdp-ingestion, segment-identity, settings-ui).
3. Las tareas incluyen explícitamente las rutas como prefijo: apps/api/..., apps/web/....
4. Abre un PR por submódulo; el orden de merge sigue las dependencias (API antes que UI).
5. Después de integrar todos los PRs, actualiza los punteros de submódulos en el workspace y archiva el cambio.

Workspace spec (single source of truth)
        │
        ├──► apps/api PR #142  (migration + endpoint)
        │
        └──► apps/web PR #89   (UI mapping)
                │
                └──► workspace PR #12 (pointer bumps + archive)

Para PMs: la especificación del workspace es su brief único de la funcionalidad; la planificación del sprint puede vincular tareas con los PRs de cada repo sin dividir la descripción entre tableros.

Herramientas MCP para trazas, clasificación y depuración

Las skills le dicen al agente qué hacer; las herramientas MCP le permiten acceder a sistemas sin scripts hechos a medida.

Configuración MCP típica del workspace (.mcp.json para Claude Code; .cursor/mcp.json para Cursor):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "jira": {
      "command": "npx",
      "args": ["-y", "your-org/mcp-jira-server"]
    }
  }
}

Para GitHub, github/github-mcp-server de GitHub es la opción oficial actual; la implementación de referencia @modelcontextprotocol/server-github que se muestra arriba es la más sencilla para ilustrar el concepto. La entrada de Jira es un marcador de posición; reemplázala con el paquete o comando del servidor MCP que use tu organización. Configura las credenciales en el host (por ejemplo, GITHUB_TOKEN, JIRA_TOKEN) según la documentación de cada servidor MCP; no hagas commit de tokens en el repo del workspace.

• GitHub — PRs, revisiones, comprobaciones, repos de submódulos
• Gestor de incidencias — Jira/Linear para ciclos de clasificación
• Observabilidad — búsqueda de trazas cuando las especificaciones mencionan IDs de solicitud
• Documentación interna — Confluence o equivalente para contexto heredado que aún no está en .knowledge/

Las skills personalizadas combinan llamadas MCP:

• Clasificación — buscar duplicados, adjuntar logs, proponer una rama de corrección
• Depuración — obtener trazas en modo de solo lectura y compararlas con los pasos del runbook en .knowledge/runbooks/
• Informe — resumen semanal de PRs integrados frente a brechas de conocimiento pendientes

Mantén al mínimo los permisos de MCP. Un servidor de clasificación de solo lectura es preferible a un token de administrador con acceso completo a producción en cada agente en la nube.

Para PMs y scrum masters: estas conexiones hacen visible el ciclo de revisión y clasificación en los tableros de entrega: el servidor de GitHub muestra el estado de los PRs y las comprobaciones, y el servidor del gestor de incidencias muestra el estado de los tickets. Así, el progreso se puede auditar sin una reunión manual de seguimiento. Para conocer la construcción de servidores MCP y el recorrido completo de madurez prompt → skill → MCP, consulta La evolución de la orquestación de agentes de IA.

Ventajas y cuándo no vale la pena

Ventajas

1. Escalar las sesiones de agentes — Clona el workspace; las skills y el conocimiento viajan con el SHA del repo.
2. Compartir flujos de trabajo del equipo — Las skills se versionan como código; un git submodule update en el workspace distribuye las mejoras.
3. Planificar una sola vez el trabajo entre repos — Las especificaciones en la raíz con tareas por submódulo reducen el costo de coordinación.
4. Trazabilidad — Las actualizaciones de punteros de submódulos y los ADRs documentan qué cambió y por qué, no solo los logs de chat.

Cuándo conviene una configuración más sencilla

• Un solo repo, un solo equipo — Un AGENTS.md bien escrito y una herramienta de especificaciones pueden ser suficientes.
• Acoplamiento estrecho, releases compartidos — Un monorepo real con Nx/Turborepo/Bazel puede tener un menor costo operativo.
• Cultura contraria a los submódulos — Los subtrees o un registro de paquetes para bibliotecas compartidas evitan los pasos administrativos de los gitlinks; se pierde la auditoría mediante PR por cada puntero, a menos que se replique en otro lugar.

Workspace vs. repo de coordinación (patrón polyrepo más ligero)

Si los pasos administrativos de los submódulos son demasiado costosos, un repo de coordinación sin checkouts de apps/* aún puede contener la especificación canónica y las skills compartidas, mientras los agentes trabajan en un repo a la vez. Ese patrón está documentado en Integrar Spec Kit en repos existentes (polyrepo). Elige el workspace completo cuando los agentes deban editar varios repos en una sesión y la auditoría de punteros sea importante; elige solo coordinación cuando las especificaciones se compartan, pero la implementación permanezca estrictamente separada por repo.

Should I adopt an agentic workspace?
│
├─ One repo, one team?
│   └─ No workspace needed → AGENTS.md + one spec toolkit in-repo
│
├─ Multiple repos, always released together?
│   └─ Consider true monorepo (Nx/Bazel) instead of submodules
│
├─ Multiple repos, independent cadence, submodule-tolerant team?
│   ├─ Agents must touch 2+ repos per feature?
│   │   └─ Full workspace (apps/* submodules + root spec + skills)
│   └─ One agent / one repo per task?
│       └─ Coordination repo only (spec home, no apps/* checkout)
│
└─ Submodule-averse culture?
    └─ Package registry or subtrees + coordination repo for specs

Problemas comunes y solución

Lista de verificación para empezar

1. Crea un repo de workspace vacío con AGENTS.md apuntando a .knowledge/README.md.
2. Agrega un submódulo de aplicación: git submodule add <url> apps/<name>.
3. Instala OpenSpec en la raíz del workspace (para especificaciones que abarcan varios repos) o Spec Kit en la raíz del workspace o en un repo de aplicación (para fases por servicio guiadas por una constitución); ejecuta la inicialización para tu agente (cursor, claude).
4. Agrega primero cuatro skills: workspace-sync-submodules, get-knowledge, update-knowledge y tu skill para proponer especificaciones.
5. Escribe dos archivos de conocimiento: conventions.md y un ADR para una decisión que las personas recién incorporadas siempre interpretan mal.
6. Ejecuta el ciclo de siete pasos en una tarea transversal pequeña antes de abordar una funcionalidad de producción.
7. Agrega automatización para los PRs que actualizan submódulos cuando la sincronización manual se vuelva tediosa.
8. Después de dos o tres ciclos, agrega el paso session-retrospective para registrar brechas en las skills y el conocimiento.

Conclusión

Un workspace agéntico no es una nueva primitiva de git. Es un modelo operativo: submódulos para código en múltiples repos, skills para acciones repetibles de agentes, conocimiento para decisiones que perduran más allá del chat y herramientas de especificación para planificar cambios. El ciclo de siete pasos convierte sesiones improvisadas de agentes en un proceso que los scrum masters pueden entender: sincronizar, contextualizar, especificar, implementar, revisar, clasificar y aprender.

Comienza con un alcance reducido: un workspace, dos submódulos, cuatro skills, una especificación. Automatiza la actualización de submódulos y conocimiento solo después de que funcione el ciclo manual. En nuestra opinión, los equipos que sostienen este patrón tratan el workspace como un producto de plataforma, no como un repo de dotfiles creado para una ocasión.

Fuentes

Fuentes primarias consultadas el July 8, 2026:

• Referencia de submódulos de Git — git-scm.com/docs/git-submodule
• Pro Git: submódulos — git-scm.com/book/en/v2/Git-Tools-Submodules
• OpenSpec — github.com/Fission-AI/OpenSpec, openspec.dev
• GitHub Spec Kit — github.com/github/spec-kit, github.github.com/spec-kit
• Formato abierto emergente Agent Skills — agentskills.io (consultado el July 8, 2026)
• Gestor de submódulos de git de Renovate — docs.renovatebot.com
• Formato de navegación llms.txt — llmstxt.org
• Documentación de skills de Cursor — cursor.com/docs/context/skills
• Guía de la comunidad: submódulos de git para ingeniería de plataforma — tenthirtyam.org, April 16, 2026
• Ejemplo de la comunidad: automatización de actualización de submódulos — workflow de aerospike-ce-ecosystem/workspace

Inferencia editorial (no verificada de forma independiente): división óptima entre OpenSpec en la raíz del workspace y Spec Kit en los repos de aplicaciones; afirmaciones sobre la escalabilidad mediante clones para agentes en la nube; evolución de la auditoría de conocimiento activada por PRs; retrospectiva semanal como retroalimentación para la plataforma. Trata estos puntos como patrones que debes validar con tu equipo, no como garantías de los proveedores.

Artículos relacionados en este devlog:

• OpenSpec vs GitHub Spec Kit
• Integrar Spec Kit en repos existentes (polyrepo)
• Orquestación de IA: prompts, skills, MCP, plugins
• Subagentes de Cursor y Claude Code