|
All checks were successful
Release & Publish to Nexus / 🚀 Build & Publish Release (push) Successful in 2m26s
|
||
|---|---|---|
| .forgejo/workflows | ||
| bin | ||
| cmd/gountz-cli | ||
| internal | ||
| .gitignore | ||
| DOWNLOAD.md | ||
| go.mod | ||
| go.sum | ||
| go.work | ||
| go.work.sum | ||
| install.sh | ||
| Makefile | ||
| README.md | ||
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
- 2. Compatibilidad Multiplataforma
- 3. Catálogo de Roles Agénticos
- 4. Sistema de Plugins, Reglas y Habilidades
- 5. Servidores MCP Nativos (Go Vertical Slicing)
- 6. Guía de Uso del CLI y TUI
- 7. Seguridad y Aislamiento de Sesiones
- 8. Compilación, Tests e Instalación
- 9. CI/CD y Publicación en Nexus Registry
- 📥 Guía Completa de Descarga e Instalación (DOWNLOAD.md)
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:
- Aislamiento en Git Worktrees: Cada sesión agéntica se ejecuta en un
git worktreeefí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. - Perfiles e Inyección de Entorno: Prepara un
HOMEdedicado (~/.agy-wrapper/profiles/<rol>) con configuraciones (settings.json), dependencias MCP y variables de entorno exclusivas para cada rol. - 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).
- Regla:
git-sovereignty:- Regla:
git-no-autonomous-commits. - Directiva: Prohíbe terminantemente ejecutar
git commit,git pusho alterar ramas sin solicitud explícita del usuario. El código local permanece en el working tree como espacio de revisión humana.
- Regla:
subagent-orchestration:- Regla:
subagent-delegation-protocol. - Habilidades:
subagent-contract-dispatcherysubagent-task-logger. - Directiva: Evita la saturación del contexto delegando tareas a subagentes con contratos JSON. Registra el progreso y logs en
tasks.jsonvía MCP nativo para visibilidad entre agentes concurrentes y purga la memoria volátil al concluir.
- Regla:
forgejo:- Acceso centralizado a repositorios, ramas, issues y pull requests en
https://git.pipis.app.
- Acceso centralizado a repositorios, ramas, issues y pull requests en
4.2 Plugins de dev-expo
tdd-specifications:- Reglas:
tdd-mandateyjest-react-native-testing-standards. - Habilidades:
spec-to-testytdd-cycle-guide. - Directiva: Ciclo Red-Green-Refactor estricto, patrón AAA (Arrange-Act-Assert), identificación del SUT, tests de comportamiento con
@testing-library/react-native, fake timers y aislamiento de mocks nativos.
- Reglas:
typescript-react:- Reglas:
typescript-strict-standards,react-dom-guidelines,react-security-practicesyreact-native-security-standards. - Habilidad:
react-component-scaffold. - Directiva: Prohibición de
any, almacenamiento seguro (expo-secure-store), TLS Certificate Pinning, protección del Native Bridge, eliminación de logs en producción y validación de deep links.
- Reglas:
conventional-commits:- Regla:
conventional-commits-standard. - Habilidad:
commit-message-generator. - Directiva: Estructura SemVer (
feat,fix,refactor,test,chore, etc.) enlazando issues de Forgejo (Closes #ID).
- Regla:
eslint-prettier:- Regla:
eslint-prettier-react-native. - Habilidad:
eslint-prettier-setup. - Directiva: Configuración Flat Config y Prettier,
react-native/no-raw-text, desinfección de estilos en desuso y prevención de conflictos víaeslint-config-prettier.
- Regla:
lefthook:- Regla:
lefthook-configuration-standards. - Habilidad:
lefthook-setup-guide. - Directiva: Git hooks paralelos ultrarrápidos sobre
{staged_files}, auto-stage de formateo (stage_fixed: true) y validación de commits encommit-msg.
- Regla:
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 enBrain/Conocimiento/y cero enlaces rotos.
- Regla:
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.
- Regla:
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 engit.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:pingydev_expo_infopara 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 endownloads/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
- Protección contra Fuga de Secretos en Shell History:
gountz-cli mcp setbloquea explícitamente el paso de secretos por argumentos posicionales o flags (--value). Esto previene que tokens sensibles queden guardados en~/.bash_historyo sean visibles en la tabla de procesos (ps aux).
- Archivos de Credenciales Restringidos:
- Los archivos
credentials.envse escriben con permisos estrictos0600dentro de~/.agy-wrapper/profiles/<rol>/.
- Los archivos
- Sandbox Estricto para el Consultor:
- El rol
consultorse invoca con directivas--sandboxy permisos de solo lectura, impidiendo mutaciones en el sistema de archivos del usuario.
- El rol
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 elPATH
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/binsi 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:
- Ejecuta la suite de pruebas unitarias sobre todos los módulos de Go.
- Realiza compilación cruzada para Linux (
amd64,arm64), macOS (amd64,arm64) y Windows (amd64,arm64). - Empaqueta los binarios (
.tar.gz/.zip) con sus sumas de verificación SHA256. - 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
mainy 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.