No description
Find a file
tomasjs 10ccd1cca7
All checks were successful
Release & Publish to Nexus / 🚀 Build & Publish Release (push) Successful in 2m26s
fix: messages
2026-09-20 22:16:49 +00:00
.forgejo/workflows feat: agregar actualizacion cli 2026-09-20 22:02:56 +00:00
bin fix: messages 2026-09-20 22:16:49 +00:00
cmd/gountz-cli feat: agregar actualizacion cli 2026-09-20 22:02:56 +00:00
internal fix: messages 2026-09-20 22:16:49 +00:00
.gitignore fix: testing mcp 2026-09-20 09:51:08 +00:00
DOWNLOAD.md feat: agregar actualizacion cli 2026-09-20 22:02:56 +00:00
go.mod feat: start project 2026-09-20 07:02:13 +00:00
go.sum feat: start project 2026-09-20 07:02:13 +00:00
go.work feat: new changes 2026-09-20 12:22:31 +00:00
go.work.sum feat: new changes 2026-09-20 12:22:31 +00:00
install.sh feat: agregar actualizacion cli 2026-09-20 22:02:56 +00:00
Makefile feat: agregar actualizacion cli 2026-09-20 22:02:56 +00:00
README.md feat: agregar actualizacion cli 2026-09-20 22:02:56 +00:00

gountz-agentic

Orquestador agéntico multirrol de alto rendimiento en Go para Google Antigravity CLI (agy). Aísla entornos de desarrollo, credenciales, servidores MCP, plugins, habilidades (skills) y directivas (rules) en espacios de trabajo independientes sin interferencias entre roles ni contaminación del repositorio principal.


Índice


1. Concepto y Arquitectura

agy es la herramienta de línea de comandos oficial de Google Antigravity. gountz-agentic actúa como la capa de orquestación y control que:

  1. Aislamiento en Git Worktrees: Cada sesión agéntica se ejecuta en un git worktree efímero dentro de .git/agy-worktrees/<uuid>. El agente trabaja en una rama aislada (agy/<rol>/<uuid>) sin riesgo de corromper la rama de trabajo principal.
  2. Perfiles e Inyección de Entorno: Prepara un HOME dedicado (~/.agy-wrapper/profiles/<rol>) con configuraciones (settings.json), dependencias MCP y variables de entorno exclusivas para cada rol.
  3. Control Total del Usuario: Prohíbe cualquier mutación no autorizada en Git; el historial de versiones permanece como una herramienta de revisión exclusiva para el usuario.

2. Compatibilidad Multiplataforma

El orquestador está diseñado para ejecutarse de manera nativa en:

  • Linux (Nativo / Contenedores)
  • macOS (Apple Silicon / Intel)
  • Windows Nativo (PowerShell y CMD sin requerir WSL)
  • WSL2 (Windows Subsystem for Linux)

Optimizaciones para Windows:

  • Resolución de variables %USERPROFILE%, %HOMEDRIVE%, %HOMEPATH% y %LOCALAPPDATA%.
  • Detección automática de ejecutables con extensión .exe (WinGet, Scoop, Go binaries).
  • Manejo de enlaces simbólicos sin privilegios de administrador mediante fallback automático a copia de tokens OAuth.
  • Terminación de procesos limpia mediante APIs nativas de os.Process.Kill.

3. Catálogo de Roles Agénticos

Rol Documento de Identidad Modo de Operación Servidores MCP Asociados
dev-expo internal/agentes/dev-expo/AGENTS.md Desarrollo completo, TDD, refactorización y UI dev-expo-mcp, figma, forgejo
devops internal/agentes/devops/AGENTS.md SRE, infraestructura, CI/CD y gestión de PRs/Issues forgejo
consultor internal/agentes/consultor/AGENTS.md Auditoría técnica y arquitectura (Read-Only Sandbox) forgejo (lectura)
brain-documentador internal/agentes/brain-documentador/AGENTS.md Gestión de conocimiento en Obsidian, Kepano y Machado roadmap-mcp, ytdl-mcp, forgejo

4. Sistema de Plugins, Reglas y Habilidades

El ecosistema de plugins sigue los estándares de OpenSpec / Agent Skills con divulgación progresiva (progressive disclosure), donde el motor indexa metadatos y carga reglas y habilidades bajo demanda.

internal/agentes/
├── _common/
│   ├── mcp/                             # Servidor MCP Forgejo + Tasks (Go)
│   │   └── internal/tasks/              # Slice vertical de memoria volátil y logs
│   └── plugins/
│       ├── agentic-authoring/           # Estándares para skills, rules y plugin.json
│       ├── forgejo/                     # Integración con git.pipis.app
│       ├── git-sovereignty/             # Prohibición de commits autónomos
│       └── subagent-orchestration/      # Delegación, contratos JSON y task logger
├── dev-expo/
│   ├── mcp/                             # Servidor MCP Dev-Expo (Go)
│   ├── AGENTS.md                        # Prompt del sistema
│   └── plugins/
│       ├── conventional-commits/        # Estándar SemVer v1.0.0
│       ├── eslint-prettier/             # Linting y formateo para React Native
│       ├── lefthook/                    # Git hooks paralelos de alta velocidad
│       ├── tdd-specifications/          # Mandato TDD + Jest + RNTL
│       └── typescript-react/            # TypeScript estricto y Seguridad móvil
├── devops/
│   └── AGENTS.md
├── consultor/
│   └── AGENTS.md
└── brain-documentador/
    ├── mcp/
    │   ├── roadmap/                     # Servidor MCP Roadmap (Go)
    │   └── ytdl/                        # Servidor MCP YouTube DL (Go)
    ├── AGENTS.md                        # Prompt del sistema
    └── plugins/
        ├── active-study/                # Metodología de estudio activo Machado
        └── obsidian-brain/              # Taxonomía Kepano y notas atómicas

4.1 Plugins Globales (_common)

  • agentic-authoring:
    • Regla: AGENTS.md.
    • Habilidades: author-skill, author-rule, author-plugin.
    • Directiva: Estándar y generadores agénticos para construir componentes semánticos de Antigravity (frontmatter YAML estricto, divulgación progresiva, límites de 24 KB y manifiestos plugin.json).
  • git-sovereignty:
    • Regla: git-no-autonomous-commits.
    • Directiva: Prohíbe terminantemente ejecutar git commit, git push o alterar ramas sin solicitud explícita del usuario. El código local permanece en el working tree como espacio de revisión humana.
  • subagent-orchestration:
  • forgejo:
    • Acceso centralizado a repositorios, ramas, issues y pull requests en https://git.pipis.app.

4.2 Plugins de dev-expo

4.3 Plugins de brain-documentador

  • obsidian-brain:
    • Regla: AGENTS.md.
    • Habilidades: manage-knowledge, process-roadmap, process-web-article, process-youtube-video.
    • Directiva: Taxonomía Kepano, preservación íntegra de fuentes crudas (Kepano Raw Archive en Brain/Fuentes/), notas atómicas conceptuales en Brain/Conocimiento/ y cero enlaces rotos.
  • active-study:
    • Regla: AGENTS.md.
    • Habilidades: plan-study-curriculum, generate-flashcards, track-recall-session.
    • Directiva: Metodología Jon Machado adaptada a ingeniería de software: estudio curricular ondulado, vaciado en frío y repetición espaciada orientada a comprensión causal y trade-offs.

5. Servidores MCP Nativos (Go Vertical Slicing)

Los servidores MCP están implementados en Go con arquitectura Vertical Slicing (internal/<slice>/handler.go) y comunicación estándar JSON-RPC sobre stdin/stdout:

forgejo-mcp (Compartido / Common)

Requiere la variable canónica FORGEJO_TOKEN para la API de Forgejo (las herramientas de tasks operan localmente sin requerir token):

  • repos: Búsqueda, metadatos y ramas en git.pipis.app.
  • issues: Listado, creación y gestión de tickets.
  • pulls: Inspección de diffs y revisiones de PRs.
  • user: Perfil y permisos del usuario autenticado.
  • tasks: Memoria volátil, logger atómico y coordinación en paralelo para subagentes (task_register, task_log, task_update, task_list, task_get, task_clear).

dev-expo-mcp (Exclusivo dev-expo)

  • greeting: Saludo contextual del agente.
  • diagnostics: ping y dev_expo_info para comprobación de salud del entorno.

roadmap-mcp (Exclusivo brain-documentador)

  • validate: Validador exhaustivo de integridad para bóvedas Obsidian (Brain/), enlaces rotos y notas huérfanas.
  • extract: Extractor nativo de artículos web a Markdown limpio en downloads/articulos/.
  • audit-sources: Auditor y sincronizador de archivos crudos Kepano Raw Archive.
  • section: Consultor y filtrador de secciones temáticas de roadmaps.

ytdl-mcp (Exclusivo brain-documentador)

  • download: Descarga y extracción de transcripciones y contenido estructurado de YouTube.

6. Guía de Uso del CLI y TUI

Al ejecutar gountz-cli sin argumentos, se despliega la interfaz gráfica interactiva en terminal (TUI) con diagnóstico en tiempo real y selector de roles:

gountz-cli

Comandos de Línea de Comandos:

# Iniciar sesión agéntica aislada (por defecto: dev-expo)
gountz-cli start [--workspace <rol>]

# Listar todas las sesiones activas en el repositorio
gountz-cli session list

# Inspeccionar los cambios realizados por el agente en su worktree
gountz-cli session diff <uuid>

# Integrar la rama efímera de la sesión a la rama base
gountz-cli session finish <uuid>

# Cancelar la sesión y eliminar el worktree sin dejar rastro en Git
gountz-cli session abort <uuid>

# Forzar cierre del proceso agéntico y liberar recursos
gountz-cli session kill <uuid>

# Limpiar worktrees huérfanos y ramas agénticas obsoletas
gountz-cli session clean

# Comprobar el estado de configuración de secretos y MCP del rol
gountz-cli mcp status [--workspace <rol>]

# Configurar credencial de forma segura (prompt interactivo enmascarado)
gountz-cli mcp set <VAR> [--workspace <rol>]

# Configurar credencial de forma segura mediante STDIN (ideal para CI o scripts)
echo "$FORGEJO_TOKEN" | gountz-cli mcp set FORGEJO_TOKEN --workspace dev-expo --stdin

# Sincronizar y materializar plugins, MCPs y skills en el perfil
gountz-cli sync [--workspace <rol>]

# Gestión de memoria volátil y logs de tareas/subagentes en el perfil
gountz-cli task list [--workspace <rol>] [--status <status>]
gountz-cli task get <id> [--workspace <rol>]
gountz-cli task clear [--workspace <rol>] [--force]

# Diagnóstico integral del sistema, binarios y variables de entorno
gountz-cli doctor

# Actualización del CLI y servidores MCP desde Forgejo / Nexus (con auto-sync)
gountz-cli update [--check] [--force] [--version <v>]

7. Seguridad y Aislamiento de Sesiones

  1. Protección contra Fuga de Secretos en Shell History:
    • gountz-cli mcp set bloquea explícitamente el paso de secretos por argumentos posicionales o flags (--value). Esto previene que tokens sensibles queden guardados en ~/.bash_history o sean visibles en la tabla de procesos (ps aux).
  2. Archivos de Credenciales Restringidos:
    • Los archivos credentials.env se escriben con permisos estrictos 0600 dentro de ~/.agy-wrapper/profiles/<rol>/.
  3. Sandbox Estricto para el Consultor:
    • El rol consultor se invoca con directivas --sandbox y permisos de solo lectura, impidiendo mutaciones en el sistema de archivos del usuario.

8. Compilación, Tests e Instalación

Requisitos Previos:

  • Go 1.20 o superior
  • Git 2.20 o superior
  • Google Antigravity CLI (agy) instalado en el PATH

Comandos del Makefile:

# Ejecutar toda la suite de pruebas unitarias e integración (100% pasando)
make test

# Compilar los binarios en ./bin (gountz-cli, forgejo-mcp, dev-expo-mcp, roadmap-mcp, ytdl-mcp)
make build

# Instalar binarios directamente en ~/.local/bin
make install

# Limpiar binarios generados
make clean

Nota: La primera vez que se inicia un rol con gountz-cli start, el orquestador compilará e instalará automáticamente los servidores MCP correspondientes en ~/.local/bin si aún no existen.


9. CI/CD y Publicación en Nexus Registry

El proyecto incluye un pipeline automatizado de Forgejo Actions (.forgejo/workflows/release.yml) que:

  1. Ejecuta la suite de pruebas unitarias sobre todos los módulos de Go.
  2. Realiza compilación cruzada para Linux (amd64, arm64), macOS (amd64, arm64) y Windows (amd64, arm64).
  3. Empaqueta los binarios (.tar.gz / .zip) con sus sumas de verificación SHA256.
  4. Publica los artefactos directamente en un repositorio Raw de Nexus Registry.

Secretos Requeridos en Forgejo:

Para habilitar la publicación, configure los siguientes secretos en el repositorio (Settings > Actions > Secrets):

Secreto Descripción Ejemplo
NEXUS_URL URL base de la instancia de Sonatype Nexus https://nexus.pipis.app o http://nexus:8081
NEXUS_USERNAME Usuario con permisos de subida/despliegue en el repositorio deployer-ci
NEXUS_PASSWORD Contraseña o token del usuario de Nexus ••••••••••••••••
NEXUS_REPOSITORY Nombre del repositorio destino (formato Raw) raw-releases o gountz-binaries

Flujo de Publicación por Tags (Versionado Semántico):

  • Pushes regulares a main y PRs: Ejecutan exclusivamente la suite de tests (go test) para validación de integración continua.
  • Publicación de una versión: Para publicar una versión oficial en Nexus, crea y sube un tag con formato SemVer (vX.Y.Z):
    # 1. Crear el tag de la versión
    git tag v1.0.0
    
    # 2. Subir el tag al repositorio en Forgejo
    git push origin v1.0.0
    
  • El pipeline detectará el tag, compilará la matriz para todos los sistemas operativos y publicará los binarios bajo la versión 1.0.0.