mcp-efficiency-engine 0.1.0

package/.github/CODEOWNERS

@@ -0,0 +1,40 @@
+# Code Owners for MCP Efficiency Engine
+# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
+
+# Specs and architecture
+/specs/                                   @Sertxito
+/AGENTS.md                                @Sertxito
+/ARCHITECTURE.md                          @Sertxito
+/CLAUDE.md                                @Sertxito
+
+# Routing and orchestration
+/scripts/intake/                          @Sertxito
+/orchestrator/                            @Sertxito
+/observability/                           @Sertxito
+
+# Skills and agents configuration
+/.github/skills/                          @Sertxito
+/.github/agents/                          @Sertxito
+/.github/prompts/                         @Sertxito
+
+# Policies and standards
+/policies/                                @Sertxito
+/optimization/                            @Sertxito
+/autodocs/                                @Sertxito
+
+# Repository intake and context
+/repo-intake/                             @Sertxito
+/context/                                 @Sertxito
+/repo-registry/                           @Sertxito
+
+# Project structure
+/projects/                                @Sertxito
+
+# Root configuration files
+/.gitignore                               @Sertxito
+/README.md                                @Sertxito
+/requirements.txt                         @Sertxito
+
+# GitHub workflows and automation
+/.github/workflows/                       @Sertxito
+/.github/instructions/                    @Sertxito

package/.github/GITHUB_MCP_INTEGRATION.md

@@ -0,0 +1,366 @@
+# GitHub MCP Integration
+
+Controlador central para operaciones automatizadas en GitHub mediante Model Context Protocol (MCP).
+
+## Referencia Oficial
+
+- **GitHub MCP Server:** https://github.com/github/github-mcp-server
+- **MCP Specification:** https://modelcontextprotocol.io/
+- **GitHub API Docs:** https://docs.github.com/en/rest
+
+## Propósito
+
+Replicar la estrategia de `boost_sertxIA` para tener control total sobre el repositorio a través de MCP, permitiendo:
+
+- Automatización de flujos Git (branches, commits, pushes)
+- Gestión de issues y pull requests programáticamente
+- Control de releases y tags
+- Gestión de repositorio (colaboradores, configuración)
+- Integración directa con workflows automatizados
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────┐
+│  GitHub Copilot / Agent                 │
+│  (vscode, scripts, automation)          │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  MCP GitHub Server                      │
+│  (Local MCP runtime)                    │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  GitHub REST API v3                     │
+│  (Authenticated via PAT token)          │
+└──────────────────┬──────────────────────┘
+                   │
+                   ▼
+┌─────────────────────────────────────────┐
+│  GitHub Repository                      │
+│  (Sertxito/mcp-efficiency-engine)       │
+└─────────────────────────────────────────┘
+```
+
+## Herramientas Disponibles (MCP GitHub)
+
+### Rama (Branch) Management
+- `create_branch` - Crear rama desde ref específica
+- `list_branches` - Listar ramas del repo
+- `get_branch` - Obtener detalles de rama
+
+### Archivo (File) Operations
+- `get_file_contents` - Leer contenido de archivo
+- `create_or_update_file` - Crear/actualizar archivo con commit
+- `delete_file` - Eliminar archivo
+- `push_files` - Hacer push de múltiples archivos en batch
+
+### Commits
+- `get_commit` - Obtener detalles de commit
+- `list_commits` - Listar commits (con filtros)
+
+### Pull Requests
+- `create_pull_request` - Crear PR con título, descripción
+- `create_pull_request_with_copilot` - Crear PR con análisis de Copilot
+- `list_pull_requests` - Listar PRs (estado, autores, labels)
+- `pull_request_read` - Leer detalles de PR específica
+- `pull_request_review_write` - Hacer review de PR
+- `merge_pull_request` - Mergear PR a rama target
+- `add_reply_to_pull_request_comment` - Responder comentarios en PR
+
+### Issues
+- `issue_read` - Leer detalles de issue
+- `issue_write` - Crear/actualizar issues
+- `list_issues` - Listar issues (con filtros: estado, labels, asignados)
+- `add_issue_comment` - Comentar en issue
+- `list_issue_fields` - Obtener campos de issue (tipos, labels)
+
+### Repository Management
+- `create_repository` - Crear nuevo repo
+- `fork_repository` - Fork de repo
+- `list_repository_collaborators` - Listar colaboradores
+- `get_teams` - Listar equipos con acceso
+- `get_team_members` - Miembros de equipo específico
+
+### Releases & Tags
+- `list_releases` - Listar releases (con pre-releases, drafts)
+- `get_release_by_tag` - Obtener release por tag
+- `get_tag` - Información de tag específico
+- `get_latest_release` - Última release publicada
+
+### Authentication
+- `get_me` - Usuario autenticado (para verificar permisos)
+
+### Copilot Integration (When Available)
+- `assign_copilot_to_issue` - Asignar Copilot para resolver issue
+- `request_copilot_review` - Solicitar review de Copilot en PR
+- `get_copilot_job_status` - Estado de job de Copilot
+
+## Casos de Uso Implementables
+
+### 1. Automatización de Control de Versión
+```
+Script → Detecta cambios en rama feature
+       → Crea PR automáticamente
+       → Ejecuta validaciones en CI
+       → Auto-merge si pasan todas
+       → Crea release si tag detectado
+```
+
+### 2. Gestión de Issues y Documentación
+```
+Issue creado → Copilot asignado automáticamente
+            → Genera PR con solución
+            → Linkea a documentación relevante
+            → Auto-cierra si resolución verificada
+```
+
+### 3. Pipeline de Contenido a Redes Sociales
+```
+(Similar a boost_sertxIA GitHub Devlog Maintainer)
+Repo update → Detecta cambios significativos
+          → Genera análisis técnico
+          → Crea devlog en autodocs/site/devlog/
+          → Genera posts para LinkedIn
+          → Crea Issues de tracking
+```
+
+### 4. Sincronización Multi-Repo
+```
+Cambio en mcp-efficiency-engine
+→ MCP detecta vía webhook
+→ Replica cambios en boost_sertxIA (cuando aplique)
+→ Crea PRs de sincronización
+→ Mantiene repos alineados
+```
+
+## Configuración Requerida
+
+### ⚠️ IMPORTANTE: No Necesitas Instalar MCP Server
+
+Los scripts usan **GitHub CLI (`gh`)** que está disponible por defecto. No necesitas `@github/mcp-github-server` en npm.
+
+### 1. GitHub CLI Setup (Obligatorio)
+
+```bash
+# Windows
+winget install GitHub.cli
+
+# macOS
+brew install gh
+
+# Linux
+sudo apt install gh
+
+# Verificar
+gh auth status
+```
+
+### 2. GitHub Personal Access Token (PAT)
+
+```bash
+# En Windows - Credential Manager:
+cmdkey /add:github.com /user:your-username /pass:ghp_xxxxxxxxxxxxxxxxxxxx
+
+# En PowerShell (sesión):
+$env:GITHUB_TOKEN = "ghp_xxxxxxxxxxxxxxxxxxxx"
+
+# En PowerShell (permanente):
+Add-Content $PROFILE "`n`$env:GITHUB_TOKEN = 'ghp_xxxxxxxxxxxxxxxxxxxx'"
+
+# En Linux/macOS:
+export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"
+echo 'export GITHUB_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"' >> ~/.bashrc
+```
+
+**Token requerido con scopes:**
+- `repo` — Acceso a repositorios
+- `workflow` — Permisos para workflows
+
+### 3. Verificar Setup
+
+```powershell
+gh auth status
+gh repo view Sertxito/mcp-efficiency-engine
+```
+
+## Scripts de Automatización
+
+### `scripts/github/sync-repo.ps1`
+Mantiene sincronización entre repos principales.
+
+```powershell
+param(
+  [string]$SourceRepo = "Sertxito/mcp-efficiency-engine",
+  [string]$TargetRepo = "Sertxito/boost_sertxIA",
+  [string]$FilesPattern = "projects/**"
+)
+
+# 1. Detectar cambios en SourceRepo
+# 2. Filtrar por FilesPattern
+# 3. Crear rama en TargetRepo
+# 4. Aplicar cambios
+# 5. Crear PR con link a commit original
+```
+
+### `scripts/github/create-devlog.ps1`
+Genera devlog técnico a partir de commits recientes.
+
+```powershell
+param(
+  [string]$Repo = "Sertxito/mcp-efficiency-engine",
+  [int]$CommitsToAnalyze = 10
+)
+
+# 1. Obtener últimos N commits
+# 2. Analizar cambios (análisis MCP via codegraph)
+# 3. Generar markdown con insights
+# 4. Crear file en autodocs/site/devlog/
+# 5. Abrir PR automáticamente
+```
+
+### `scripts/github/manage-issues.ps1`
+Gestiona issues con Copilot y automatización.
+
+```powershell
+param(
+  [ValidateSet("assign", "review", "close")]
+  [string]$Action = "assign"
+)
+
+# Acciones:
+# - assign: Asigna Copilot a issues sin asignar
+# - review: Solicita review de Copilot en PRs abiertas
+# - close: Auto-cierra issues si solución en PR merged
+```
+
+## Integración con Workflows Existentes
+
+### GitHub Actions Workflow Enhancement
+
+```yaml
+# .github/workflows/sync-to-boost.yml
+name: Sync to boost_sertxIA
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'projects/**'
+      - '.github/specs/**'
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Setup MCP GitHub
+        run: npm install -g @github/mcp-github-server
+      
+      - name: Run sync via MCP
+        run: |
+          pwsh scripts/github/sync-repo.ps1 \
+            -SourceRepo "${{ github.repository }}" \
+            -TargetRepo "Sertxito/boost_sertxIA"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### CI Workflow Integration
+
+```yaml
+# En .github/workflows/ci.yml
+
+- name: Assign Copilot to review
+  if: success()
+  run: |
+    pwsh scripts/github/manage-issues.ps1 -Action review
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+- name: Create devlog from commits
+  if: contains(github.event.head_commit.message, '[devlog]')
+  run: |
+    pwsh scripts/github/create-devlog.ps1 -CommitsToAnalyze 5
+  env:
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## Estrategia de Seguridad
+
+### Token Management
+
+1. **Nunca commitar tokens en Git**
+   ```gitignore
+   .env
+   .env.local
+   secrets.*
+   ```
+
+2. **Usar GitHub Secrets en CI/CD**
+   ```yaml
+   - name: Use token from secrets
+     env:
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+   ```
+
+3. **Scope del PAT**
+   - `repo` - Acceso completo a repositorios públicos y privados
+   - `workflow` - Permisos para workflows
+   - `admin:repo_hook` - Para webhooks si es necesario
+   - NO usar `admin:org_hook` (demasiado permisivo)
+
+### Auditoría
+
+```powershell
+# Script para auditar uso de MCP GitHub
+# scripts/github/audit-mcp-usage.ps1
+
+# 1. Listar todos los commits hechos vía MCP (autor específico)
+# 2. Verificar PRs creadas automáticamente
+# 3. Reportar acciones de Copilot asignadas
+# 4. Alertar si uso excepcional (batch operations)
+```
+
+## Próximos Pasos
+
+1. **Configurar MCP GitHub Server localmente**
+   - Instalar servidor
+   - Configurar PAT token
+   - Verificar conectividad con `gh` CLI
+
+2. **Implementar scripts de automatización**
+   - `sync-repo.ps1` para mantener boost_sertxIA alineado
+   - `create-devlog.ps1` para documentación automática
+   - `manage-issues.ps1` para gestión inteligente
+
+3. **Integrar con workflows existentes**
+   - Añadir pasos en CI para devlog automático
+   - Setup de sync automation para PRs cross-repo
+   - Gestión de issues con Copilot
+
+4. **Documentar playbooks**
+   - Cómo crear PR programáticamente
+   - Cómo mergear cuando validaciones pasan
+   - Cómo sincronizar cambios a otros repos
+
+## Referencias
+
+- [GitHub MCP Server (Oficial)](https://github.com/github/github-mcp-server)
+- [MCP Specification](https://modelcontextprotocol.io/)
+- [GitHub REST API Documentation](https://docs.github.com/en/rest)
+- [GitHub CLI (gh) Documentation](https://cli.github.com/manual)
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [boost_sertxIA - GitHub Devlog Maintainer](https://github.com/Sertxito/boost_sertxIA/blob/main/.github/agents/github-devlog-maintainer.agent.md)
+
+## Estado
+
+- ✅ Documentación creada
+- ⏳ Configuración local de MCP Server
+- ⏳ Implementación de scripts de automatización
+- ⏳ Integración con CI/CD workflows
+- ⏳ Documentación de playbooks operacionales

package/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,51 @@
+---
+name: "🐛 Bug Report"
+about: Reporta un error o comportamiento inesperado
+title: "[BUG] "
+labels: ["bug", "triage"]
+---
+
+## Descripción del bug
+
+<!-- Describe el problema de forma clara y concisa -->
+
+## Reproducción
+
+Pasos para reproducir:
+1. ...
+2. ...
+3. ...
+
+## Comportamiento esperado
+
+<!-- Qué debería pasar -->
+
+## Comportamiento actual
+
+<!-- Qué sucede realmente -->
+
+## Contexto
+
+- **Entorno**: Windows / Linux / macOS
+- **Python**: (ej. 3.10, 3.11)
+- **Rama**: (ej. main, feature/xyz)
+- **Comando ejecutado**:
+  ```bash
+  # incluye el comando exacto que falla
+  ```
+
+## Output / Error
+
+```
+<!-- Incluye logs, stack traces, stdout/stderr -->
+```
+
+## Checklist de validación
+
+- [ ] He ejecutado `run-routing-evals.py` y falla reproduciblemente
+- [ ] He ejecutado `validate-context.ps1` y reporta el error
+- [ ] El error no es de configuración local (ej. .env faltante)
+
+## Solución propuesta
+
+<!-- Opcional: si tienes idea de la causa o solución, describe aquí -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,45 @@
+---
+name: "✨ Feature Request"
+about: Propón una nueva funcionalidad o mejora
+title: "[FEATURE] "
+labels: ["enhancement", "triage"]
+---
+
+## Descripción
+
+<!-- Explica la funcionalidad o mejora que propones -->
+
+## Motivación
+
+<!-- Por qué es necesaria? Qué problema resuelve? -->
+
+## Casos de uso
+
+<!-- Cómo usaría un usuario esta funcionalidad? -->
+
+## Alcance
+
+- [ ] Cambio en specs (`specs/*.spec.md`)
+- [ ] Nuevo script (`scripts/intake/` o similar)
+- [ ] Nuevo agente (`.github/agents/*.agent.md`)
+- [ ] Nuevo skill (`.github/skills/*/*.SKILL.md`)
+- [ ] Cambio en routing o políticas
+- [ ] Otro (describe):
+
+## Impacto estimado
+
+- [ ] Mínimo (docs, comentarios)
+- [ ] Bajo (nuevo script, sin cambios en arquitectura)
+- [ ] Medio (cambio en specs o routing)
+- [ ] Alto (cambio arquitectónico, impacta múltiples agentes)
+
+## Propuesta de validación
+
+<!-- Cómo sabríamos que la funcionalidad funciona? -->
+- [ ] Nuevo test/caso en `routing-eval-cases.json`
+- [ ] Script de validación en `scripts/intake/`
+- [ ] Spec actualizada con sección `## Validación mínima`
+
+## Contexto adicional
+
+<!-- Links, referencias, ejemplos de cómo debería funcionar -->

package/.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,18 @@
+---
+name: "❓ Question / Documentation"
+about: Pregunta sobre uso, documentación o decisiones de diseño
+title: "[QUESTION] "
+labels: ["documentation", "question"]
+---
+
+## Pregunta
+
+<!-- Qué querés saber? -->
+
+## Contexto
+
+<!-- Dónde encontraste la dificultad? Qué documentación consultaste? -->
+
+## Información esperada
+
+<!-- Qué tipo de respuesta te ayudaría? Ejemplo, referencia, explicación, etc. -->

package/.github/agents/backend.agent.md

@@ -0,0 +1,18 @@
+# backend
+
+## Purpose
+
+Modern development tasks on a single repository: bug fix, refactor, tests, and debugging.
+
+## Pipeline
+
+1. Memory-first selection (`repo-memory`, `routing-memory`, `code-memory`).
+2. Route to CodeGraph for structural retrieval.
+3. Apply Token Saver strict + Caveman full/lite.
+4. Execute coding flow and register feedback into AutoLearning.
+
+## Dependencies
+
+- Engine: CodeGraph
+- Skills/runtime: token-saver, caveman-mode, codebase-memory-mcp
+- Boost source expected via `repo-registry/repos.yml` (domain `dev`)

package/.github/agents/community-manager.agent.md

@@ -0,0 +1,18 @@
+# community-manager
+
+## Purpose
+
+Technical education, community posts, and storytelling grounded in repository knowledge.
+
+## Pipeline
+
+1. Memory-first selection (`repo-memory`, `routing-memory`, `knowledge-memory`).
+2. Route to Graphify for local context grounding.
+3. Apply Token Saver balanced + Caveman didactic-lite (unless concise mode requested).
+4. Produce audience-oriented output and register feedback into AutoLearning.
+
+## Dependencies
+
+- Engine: Graphify
+- Skills/runtime: token-saver, codebase-memory-mcp
+- Boost source expected via approved knowledge repos in `repo-registry/repos.yml`

package/.github/agents/dba.agent.md

@@ -0,0 +1,18 @@
+# dba
+
+## Purpose
+
+SQL/schema/procedure analysis and DBA-oriented technical diagnostics.
+
+## Pipeline
+
+1. Memory-first selection (`repo-memory`, `routing-memory`, `knowledge-memory`).
+2. Route to Graphify for technical knowledge retrieval.
+3. Apply Token Saver strict + Caveman lite/full.
+4. Return grounded technical answer and register feedback into AutoLearning.
+
+## Dependencies
+
+- Engine: Graphify
+- Skills/runtime: token-saver, codebase-memory-mcp
+- Boost source expected via `repo-registry/repos.yml` (domain `dba`)

package/.github/agents/frontend-agent.agent.md

@@ -0,0 +1,18 @@
+# frontend-agent
+
+## Purpose
+
+Frontend development tasks on a single repository: UI feature implementation, bug fixes, refactors, and test support.
+
+## Pipeline
+
+1. Memory-first selection (`repo-memory`, `routing-memory`, `code-memory`).
+2. Route to CodeGraph for structural retrieval in frontend code.
+3. Apply Token Saver strict + Caveman full/lite.
+4. Execute frontend coding flow and register feedback into AutoLearning.
+
+## Dependencies
+
+- Engine: CodeGraph
+- Skills/runtime: token-saver, caveman-mode, codebase-memory-mcp
+- Boost source expected via `repo-registry/repos.yml` (domain `frontend`)