🌀 Rikudo: El Sabio de los Commits

Rikudo es una herramienta CLI potenciada por Inteligencia Artificial, agnóstica del proveedor de IA, diseñada para automatizar y estandarizar el flujo de trabajo de Git y la gestión de tareas en Redmine.

Inspirado en el Sabio de los Seis Caminos, Rikudo utiliza módulos especializados para observar tu código, entender el contexto de tus tareas y mantener la armonía en el repositorio siguiendo las convenciones del equipo.

🚀 Los 6 Caminos de Rikudo

1. Camino Deva (Git): Control total sobre el stage y los commits.
2. Camino Humano (AI): Inteligencia profunda para redactar mensajes técnicos precisos.
3. Camino Animal (Redmine): Invocación y sincronización con el Project Manager.
4. Camino Preta (Summarizer): Absorción y síntesis de archivos de gran tamaño.
5. Camino Naraka (Cache): Memoria persistente basada en hashes de Git para optimizar tokens.
6. Camino Asura (Rate Limiter): Gestión de poder para respetar los límites de las APIs.

✨ Dos Modos de Uso

Rikudo puede usarse de dos maneras:

Modo CLI

Interactúa directamente desde la terminal con un menú interactivo o comandos directos.

Modo MCP (Model Context Protocol)

Actúa como servidor MCP, exponiendo herramientas y prompts para que agentes de IA externos (Claude Code, Gemini CLI, Cursor, etc.) puedan invocar sus funcionalidades.

✨ Características Principales

• 🧠 Agnóstico de IA: Tú eliges el cerebro. Soporte nativo para:

  • Google Gemini (Rápido y eficiente)
  • OpenAI GPT-4o / GPT-3.5 (El estándar)
  • Anthropic Claude (Gran capacidad de contexto)
  • Ollama (Privacidad total con modelos locales como Llama 3)

• 📝 Smart Commits: Analiza tus staged files y genera mensajes siguiendo Conventional Commits basados en tus propias reglas.

• 🚀 PR Generator: Selecciona múltiples commits y genera una descripción de Pull Request completa siguiendo tu plantilla.

• ⚙️ Configuración Flexible: Define tus preferencias globales o por proyecto.

• 🔍 Diagnóstico Integrado: Herramienta test para verificar tus API Keys y conexión con servicios externos.

• 🔌 Servidor MCP: Actúa como skill library para agentes de IA externos mediante el protocolo MCP.

📦 Instalación

npm install -g @dami_deleon/rikudo

Ejecución única (sin instalar)

npx @dami_deleon/rikudo

🚀 Uso Rápido

Modo CLI

Ejecuta el comando en tu terminal dentro de cualquier repositorio git:

rikudo

Esto abrirá el Menú Interactivo donde podrás elegir entre crear commits, PRs o configurar la herramienta.

Comandos Directos

• Crear Commit:

rikudo commit
# O con ticket asociado:
rikudo commit -t 1234

• Crear Pull Request:

rikudo pr
# O con ticket asociado:
rikudo pr -t 1234

• Diagnóstico de Conexión:

rikudo test

• Ver Ticket:

rikudo ticket 1234

• Configuración:

rikudo config

Modo MCP

Para usar Rikudo como servidor MCP con cualquier agente de IA compatible:

rikudo mcp

El servidor se comunica mediante stdio, permitiendo integrarse con cualquier cliente MCP.

Herramientas Disponibles

| Herramienta | Descripción | |------------|-------------| | validate_configuration | Verifica que las variables de entorno necesarias (Redmine, Gitea) estén configuradas correctamente. | | get_ticket_context | Obtiene el contexto completo de un ticket de Redmine (título, descripción, estado, prioridad, custom fields). | | get_git_diff | Retorna el diff de los archivos que están en staging (git add). | | shift_left_start | Flujo shift-left completo: checkout a rama objetivo, crea nueva rama, commit vacío y abre Draft PR en Gitea. Soporta parámetro isWip para usar prefijo "WIP:" en el título. | | update_pm_redmine | Agrega un comentario a un ticket de Redmine para notificar al Project Manager. | | update_custom_fields | Actualiza los campos personalizados (Custom Fields) de un ticket de Redmine. |

Prompts Disponibles

| Prompt | Descripción | |--------|-------------| | start_feature | Inicia el flujo de trabajo para una nueva feature. Obtiene contexto del ticket, genera nombre de rama y prepara el entorno en Gitea con PR en modo WIP. | | review_and_comment | Analiza los cambios staged, genera un comentario técnico y lo publica en Redmine. |

Integración con Agentes IA

Rikudo es compatible con cualquier herramienta de IA que soporte el protocolo MCP, como:

• Claude Code / Claude Desktop
• Gemini CLI
• Cursor
• Windsurf
• Continue
• Y cualquier otro cliente MCP

Agrega esto en la configuración de tu cliente MCP:

{
  "mcpServers": {
    "rikudo": {
      "command": "rikudo",
      "args": ["mcp"]
    }
  }
}

Variables de Entorno para MCP

# Redmine
RIKUDO_REDMINE_URL=https://redmine.tuempresa.com
RIKUDO_REDMINE_API_KEY=tu_redmine_key

# Gitea
RIKUDO_GITEA_URL=https://gitea.tuempresa.com
RIKUDO_GITEA_TOKEN=tu_gitea_token
RIKUDO_GITEA_OWNER=tu_usuario_o_organizacion  # Opcional
RIKUDO_GITEA_REPO=nombre_del_repositorio       # Opcional

Formato de Ramas

Al usar start_feature o shift_left_start, el nombre de rama sigue el formato:

[numero-tarea]-[titulo-tarea-ingles-corto]

Ejemplo: 1234-add-user-authentication

⚙️ Configuración

Rikudo busca un archivo .env en la raíz de tu proyecto para las credenciales sensibles.

# --- Configuración General ---
RIKUDO_AI_PROVIDER=gemini  # Opciones: gemini, openai, claude, ollama

# --- Credenciales de Proveedores (Solo necesitas la que uses) ---
RIKUDO_GEMINI_API_KEY=tu_api_key_aqui
RIKUDO_OPENAI_API_KEY=tu_api_key_aqui
RIKUDO_CLAUDE_API_KEY=tu_api_key_aqui

# --- Ollama (Local) ---
RIKUDO_OLLAMA_URL=http://localhost:11434/api/generate
RIKUDO_OLLAMA_MODEL=llama3

# --- Integraciones ---
RIKUDO_REDMINE_URL=https://redmine.tuempresa.com
RIKUDO_REDMINE_API_KEY=tu_redmine_key

# --- Gitea (para servidor MCP) ---
RIKUDO_GITEA_URL=https://gitea.tuempresa.com
RIKUDO_GITEA_TOKEN=tu_gitea_token
RIKUDO_GITEA_OWNER=tu_usuario_o_organizacion  # Opcional: se obtiene del remote si no se especifica
RIKUDO_GITEA_REPO=nombre_del_repositorio       # Opcional: se obtiene del remote si no se especifica

Plantillas Personalizadas

1. conventions.txt: Reglas para tus commits.
2. pull-request-template.txt: Estructura para tus PRs.

🛠️ Solución de Problemas

rikudo test

Esto validará:

1. Que las variables de entorno existan.
2. Que la API Key sea válida conectando con el proveedor.
3. Que tengas acceso a los servicios externos configurados.

Hecho con ❤️ y TypeScript.