Arquitectura

Canalización de tres repositorios

El sistema de documentación y gobernanza abarca tres repositorios, cada uno con una responsabilidad distinta:

Repositorio	Rol
docs-control	Centro de gobernanza central — configuración de repositorios, configuración de protección de ramas, manifiesto de archivos gestionados, flujos de trabajo CI reutilizables, flujos de trabajo de IA de Antigravity, plantillas de flujos de trabajo solicitantes, habilidades de agentes y envío descendente
docs-builder	Imagen de compilación de Docker — orquestación de compilación de Astro + Starlight, dependencias de npm, generación de PDF con Puppeteer, componentes interactivos
docs-theme	Plugin de Astro Starlight — marca compartida, CSS, fuentes, logotipos, componentes de diseño, astro.config.mjs y content.config.ts

Los repositorios de contenido solo necesitan un directorio docs/. El contenedor de compilación y el flujo de trabajo se encargan del resto.

Flujo de datos

Cuando un archivo de plantilla o un flujo de trabajo cambia en docs-control en main:

1. El flujo de trabajo de envío se activa e inicia la aplicación de reglas en cada repositorio descendente
2. El flujo de trabajo de aplicación compara el estado deseado con el estado actual y corrige cualquier desviación
3. El flujo de trabajo de sincronización de archivos detecta archivos gestionados desviados, crea una PR con contenido canónico y la fusiona automáticamente
4. Los flujos de trabajo reutilizables de IA de Antigravity (antigravity-review.yml y antigravity-translate.yml) se ejecutan en las solicitudes de extracción en todos los repositorios inscritos

Automatización de IA de Antigravity

La flota incorpora la automatización de IA de Antigravity (agy) que se ejecuta en ejecutores de GitHub Actions:

Flujo de trabajo	Propósito	Activador y ejecución
Revisión de código de Antigravity (antigravity-review.yml)	Revisión automática de código en PR mediante IA	Se ejecuta al crear o actualizar una PR. Utiliza Gemini 3.6 Flash (High) para auditar las diferencias en busca de vulnerabilidades de seguridad, secretos codificados de forma rígida, fuga de PII y calidad del código, publicando comentarios en la PR.
Traducción de idioma de Antigravity (antigravity-translate.yml)	Traducción automática de documentación mediante IA	Se ejecuta en PRs que modifican docs/en/**/*.md[x]. Ejecuta la habilidad .agents/skills/i18n-translate/SKILL.md para actualizar 12 configuraciones regionales de destino (fr, es, de, pt-br, ja, ko, zh-cn, zh-tw, ar, it, hi, th), actualizar i18n.sourceHash y realizar un commit automático en la rama de la PR.

Modelo de tokens y credenciales

Tres conjuntos de credenciales proporcionan separación con privilegio mínimo:

Token / Secreto	Permisos / Alcance	Utilizado por
REPO_SETTINGS_TOKEN	Administration R/W, Pages R/W, Contents Read, Metadata Read	enforce-repo-settings.yml, dispatch-downstream.yml, update-governed-workflow-pins.yml
REPO_SYNC_TOKEN	Contents R/W, Issues R/W, Pull Requests R/W, Metadata Read	sync-managed-files.yml
ANTIGRAVITY_TOKEN y GCP_PROJECT_ID	Autenticación de IA de Antigravity y acceso al proyecto GCP	antigravity-review.yml, antigravity-translate.yml

El flujo de trabajo de aplicación necesita acceso de administrador para modificar la protección de ramas y la configuración de Pages. El flujo de trabajo de sincronización necesita acceso a contenidos y PR para crear ramas, realizar commits de archivos y fusionar PR. Los flujos de trabajo de IA de Antigravity utilizan credenciales de proyecto dedicadas para autenticarse con Gemini 3.6 Flash.

Autodetección

Docs-control es tanto el proveedor como el consumidor de su propia configuración de gobernanza. Cuando enforce-repo-settings.yml se ejecuta en el propio docs-control (a través del activador push), lo detecta comparando managed_files.source_repo con github.repository. Esto activa la sustitución de self_contexts en la protección de ramas: docs-control utiliza flujos de trabajo directamente (por ejemplo, Shell Unit Tests), mientras que los repositorios descendentes utilizan envolturas solicitantes (por ejemplo, lint / Shell Unit Tests). Consulte la página de configuración para obtener más detalles sobre contexts frente a self_contexts.

Estructura del repositorio

Directorio / Archivo	Propósito
.github/config/repo-settings.json	Configuración central: configuración de repositorio, protección de ramas, permisos de Actions, configuración de Pages y manifiesto de archivos gestionados
.github/config/downstream-repos.json	Registro de repositorios descendentes inscritos
.github/config/docs-sites.json	Metadatos para cada sitio de documentación descendente (etiqueta, URL, descripción) utilizados por la plantilla README
.github/workflows/	Flujos de trabajo reutilizables: aplicación, sincronización de archivos, despliegue de páginas, verificación de temas vinculados, envío, revisión de antigravity y traducción de antigravity
.agents/skills/	Gobernanza de habilidades de agentes: demo-components, i18n-translate
workflows/	Plantillas solicitantes que los repositorios descendentes instalan en .github/workflows/
docs/	Fuente de documentación (compilada y desplegada a través de Astro Starlight)
CONTRIBUTING.md	Reglas del flujo de trabajo de contribución (sincronizadas en todos los repositorios descendentes)
CLAUDE.md	Instrucciones del asistente de IA (sincronizadas en todos los repositorios descendentes)
AGENTS.md	Instrucciones de agentes del repositorio y políticas de gobernanza
README.md.tpl	Plantilla para archivos README descendentes generados dinámicamente
.pre-commit-config.yaml	Configuración de ganchos de pre-commit (sincronizada en todos los repositorios descendentes)
.markdownlint.json	Reglas del linter de Markdown
.yamllint.yaml	Reglas del linter de YAML