Documentacion completa

Referencia Tecnica

Arquitectura de paquetes, git hooks, guidelines, agentes IA, MCPs, configuracion y catalogo de proyectos.

Monorepo — tres paquetes, un ecosistema

Arquitectura del monorepo

Los tres paquetes viven en un unico monorepo pnpm (geniova-developer-kit). El bootstrapper verifica, el wizard configura, los hooks protegen.

01
@geniova/developer-kit

Bootstrapper

Paquete publico en npm. Punto de entrada que verifica prerrequisitos y lanza el wizard privado.

  • Monorepo: packages/developer-kit
  • Comando: npx @geniova/developer-kit init
  • git, node >=18, pnpm, gh, firebase-tools
  • claude, karajan
  • Auth GitHub + membresia org
  • Auth Firebase CLI
02
@geniova-technologies/geniova-kit

Wizard

Paquete privado en GitHub Packages. Wizard interactivo que configura el entorno de desarrollo global.

  • Monorepo: packages/wizard
  • Instala 4 MCPs obligatorios
  • Configura Karajan y BecarIA
  • Todo automatico, sin intervencion manual
03
@geniova/git-hooks

Git Hooks

Hooks, guidelines y MCP Server. Proteccion del repositorio y contexto para agentes IA.

  • Monorepo: packages/git-hooks
  • Comandos: init, generate, run
  • 8 checks automaticos
  • 13 guidelines de codigo
  • 5 agentes IA soportados
  • MCP Server con 8 herramientas
Proteccion del repositorio

Git Hooks

8 checks automaticos que se ejecutan en pre-commit, commit-msg y pre-push para proteger la calidad del codigo.

Hook Check Descripcion Bloquea
pre-commit Lint ESLint + Stylelint en archivos staged Si
pre-commit Regression Detecta cambios CSS/JS que deshacen fixes previos Warning
pre-commit No AI refs Bloquea commits con referencias a IA en archivos Si
commit-msg AI en mensaje Valida que el mensaje de commit no mencione IA Si
pre-push SSH Valida que el remote usa SSH en lugar de HTTPS Si
pre-push Identity Verifica git user.email contra emails permitidos Si
pre-push Rebase Requiere rebase sobre origin/main antes de push Si
pre-push Diff summary Muestra estadisticas del push (archivos, lineas) Info
Estandares de codigo

Guidelines

13 guias que definen los estandares de desarrollo para todos los proyectos Geniova. Se instalan automaticamente con npx @geniova/git-hooks init. Puedes leerlas o descargarlas desde aqui.

1

code-style.md

SOLID, DRY, KISS, YAGNI, vanilla JS + JSDoc

2

naming-conventions.md

Archivos, variables, CSS, Firebase

3

error-handling.md

Fallos explicitos, boundaries, logging

4

testing.md

TDD, Vitest/Playwright, cobertura minima

5

security.md

Validacion, secrets, Firebase rules

6

ui-ux.md

Modales, toast, accesibilidad, responsive

7

commits-and-prs.md

Conventional Commits, PRs pequenas

8

dependencies.md

Evaluacion, versionado

9

implementation-plan.md

Cuando y como planificar implementaciones

10

file-protection.md

No sobreescrituras accidentales

11

firebase-patterns.md

Colecciones, reglas, Cloud Functions

12

astro-lit-patterns.md

SSG, View Transitions, Lit

13

git-firebase-identity.md

Verificacion de identidad

Contexto para IA

Agentes IA soportados

El wizard genera automaticamente archivos de guidelines para cada agente IA cuando ejecutas npx @geniova/git-hooks init en un repo. No necesitas crearlos manualmente.

Claude Code

CLAUDE.md

GitHub Copilot

.github/copilot-instructions.md

OpenAI Codex

AGENTS.md

Google Gemini

.gemini/styleguide.md

Cursor

.cursorrules

Los archivos generados usan marcadores @geniova/git-hooks:start y @geniova/git-hooks:end para delimitar el contenido gestionado. El contenido fuera de estos marcadores se preserva al regenerar con generate.

Integraciones

MCPs obligatorios

Los 4 MCPs se instalan automaticamente por el wizard. Se configuran en la configuracion global de Claude Code, no necesitas hacer nada manualmente.

Obligatorio

Planning Game

Gestion de proyectos agiles basada en eXtreme Programming.

  • Cards: tasks, bugs, epics, proposals, QA
  • Sprints, developers, stakeholders
  • ADRs (Architecture Decision Records)
  • Integracion con todos los agentes IA
Obligatorio

Karajan

Orquestacion multi-agente para desarrollo y review.

  • Roles: Coder, Reviewer, Solomon, Tester, Security
  • Code review con BecarIA integration
  • PR-oriented pipeline
  • Ejecucion local con keys del developer
Obligatorio

Chrome DevTools

Verificacion visual y depuracion desde el agente IA.

  • Screenshots y snapshots de UI
  • Consola y network debugging
  • Pruebas de interaccion de usuario
  • Validacion responsive y accesibilidad
Obligatorio

SonarQube

Analisis estatico de calidad de codigo. Requiere Docker para el servidor local.

  • Code smells, bugs, vulnerabilidades
  • Quality gates por proyecto
  • Servidor local: docker compose -f ~/sonarqube/docker-compose.yml up -d
  • Analisis: npx @sonar/scan
Personalizacion

Configuracion: .githooksrc.json

Este archivo se genera automaticamente con npx @geniova/git-hooks init en la raiz de cada proyecto. No necesitas crearlo manualmente. Se muestra aqui como referencia de las opciones disponibles para personalizacion.

.githooksrc.json
{
  "historyDepth": 10,
  "lint": { "enabled": true },
  "regression": { "enabled": true, "maxFiles": 20 },
  "aiRefs": {
    "enabled": true,
    "extraPatterns": [],
    "allowInFiles": [".claude/*"]
  },
  "commitMsg": { "enabled": true },
  "push": {
    "enabled": true,
    "allowedEmails": ["*@geniova.com"],
    "rebaseCheck": true,
    "diffSummary": true,
    "baseBranch": "main",
    "maxLines": 300
  }
}
Variables de entorno

Cada opcion de configuracion puede ser sobreescrita con variables de entorno:

GENIOVA_HOOKS_LINT_ENABLED GENIOVA_HOOKS_REGRESSION_ENABLED GENIOVA_HOOKS_AIREFS_ENABLED GENIOVA_HOOKS_COMMITMSG_ENABLED GENIOVA_HOOKS_PUSH_ENABLED GENIOVA_HOOKS_PUSH_REBASECHECK GENIOVA_HOOKS_PUSH_DIFFSUMMARY GENIOVA_HOOKS_PUSH_MAXLINES
MCP Server de git-hooks

8 herramientas

Herramientas expuestas por el MCP Server de @geniova/git-hooks para integracion con agentes IA.

01

init_project

Setup completo en directorio

02

generate_guidelines

Regenerar archivos de guidelines

03

list_guidelines

Listar guidelines disponibles

04

get_guideline

Obtener contenido de una guia

05

get_full_guidelines

Todas las guias concatenadas

06

list_targets

Listar agentes soportados

07

get_project_config

Obtener .githooksrc.json

08

run_hook

Ejecutar un hook manualmente