javi-forge 0.1.0

package/ai-config/commands/git/changelog.md

@@ -0,0 +1,32 @@
+Generá un CHANGELOG desde los commits recientes siguiendo Keep a Changelog.
+
+## Pasos
+
+1. Corré `git log --oneline --no-merges $(git describe --tags --abbrev=0)..HEAD` para commits desde último tag.
+2. Si no hay tag: `git log --oneline --no-merges -30`
+3. Agrupá los commits por tipo (feat, fix, refactor, etc.)
+4. Generá la entrada de CHANGELOG en formato Keep a Changelog.
+
+## Formato
+
+```markdown
+## [Unreleased] — YYYY-MM-DD
+
+### Added
+- Nueva funcionalidad X (feat commits)
+
+### Fixed  
+- Corrección de Y (fix commits)
+
+### Changed
+- Cambio en Z (refactor commits)
+
+### Security
+- Parche de seguridad W (fix(security) commits)
+```
+
+## Reglas
+
+- Solo incluir commits visibles para usuarios (no `chore`, `style`, `ci` internos)
+- Agrupar múltiples commits relacionados en una sola entrada si tienen el mismo scope
+- Linkear issues cuando el commit los menciona (#123)

package/ai-config/commands/git/ci-local.md

@@ -0,0 +1,70 @@
+---
+name: ci-local
+description: Run CI pipeline locally before pushing
+category: git
+---
+
+# /ci-local
+
+Run your GitHub Actions CI pipeline locally before pushing, using `act` or `wrkflw`. Catches failures fast without burning CI minutes.
+
+## Usage
+
+`/ci-local [workflow-file]`
+
+- No argument: detects and runs the default push workflow
+- With file: runs the specified workflow (e.g., `/ci-local ci.yml`)
+
+## Steps
+
+1. **List available workflows**
+   ```bash
+   ls .github/workflows/
+   ```
+
+2. **Check for local CI tools**
+   ```bash
+   which act 2>/dev/null && echo "act found" || echo "act not found"
+   which wrkflw 2>/dev/null && echo "wrkflw found" || echo "wrkflw not found"
+   ```
+
+3. **Run with `act`** (if installed)
+   ```bash
+   act push --container-architecture linux/amd64
+   # or for a specific workflow:
+   act push -W .github/workflows/ci.yml --container-architecture linux/amd64
+   ```
+
+4. **Run with `wrkflw`** (if installed)
+   ```bash
+   wrkflw run
+   # or for a specific workflow:
+   wrkflw run .github/workflows/ci.yml
+   ```
+
+5. **If neither is installed** — install `act`:
+
+   **macOS (Homebrew)**
+   ```bash
+   brew install act
+   ```
+
+   **Linux (apt / snap)**
+   ```bash
+   snap install act
+   # or via script:
+   curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash
+   ```
+
+   See: https://github.com/nektos/act
+
+6. **Show pass/fail summary**
+   - ✅ All jobs green → safe to push
+   - ❌ Any job red → fix before pushing (`git push --no-verify` only in emergencies)
+
+## Notes
+
+- `act` requires Docker to be running
+- Use `--container-architecture linux/amd64` on Apple Silicon to avoid platform mismatches
+- First run downloads Docker images — subsequent runs are faster
+- Secrets: create `.secrets` file at repo root (`KEY=value`) and pass with `act --secret-file .secrets`

package/ai-config/commands/git/commit.md

@@ -0,0 +1,35 @@
+Analizá los cambios staged (`git diff --cached`) y generá un mensaje de commit siguiendo Conventional Commits.
+
+## Pasos
+
+1. Corré `git diff --cached --stat` para ver qué archivos cambiaron.
+2. Corré `git diff --cached` para leer los cambios reales.
+3. Determiná el tipo de commit:
+   - `feat` - nueva funcionalidad
+   - `fix` - corrección de bug
+   - `refactor` - reestructuración sin cambio de comportamiento
+   - `docs` - solo documentación
+   - `test` - agregar o actualizar tests
+   - `chore` - build, CI, dependencias
+   - `perf` - mejora de performance
+   - `style` - formateo, espacios
+4. Identificá el scope del módulo/directorio más afectado.
+5. Escribí una línea de subject concisa en imperativo (máx 72 chars).
+6. Si el cambio no es trivial, agregá un cuerpo explicando **por qué** se hizo el cambio.
+7. Presentá el mensaje de commit para aprobación antes de ejecutar.
+
+## Formato
+
+```
+type(scope): línea de subject en modo imperativo
+
+Cuerpo opcional explicando motivación y contexto.
+BREAKING CHANGE: descripción si aplica.
+```
+
+## Reglas
+
+- Subject: modo imperativo, sin punto final, máx 72 caracteres.
+- Cuerpo: wrap a 80 chars, línea en blanco entre subject y cuerpo.
+- Si hay múltiples cambios lógicos staged, sugerí dividir en commits separados.
+- Nunca incluir archivos generados, lock files o artefactos de build sin intención explícita.

package/ai-config/commands/git/fix-issue.md

@@ -0,0 +1,23 @@
+Implementá el fix para un issue específico siguiendo el flujo completo.
+
+## Pasos
+
+1. **Entender**: Leé el issue completamente. Reproducí el problema si es posible.
+2. **Branch**: Creá branch con convención `fix/t-{issue-number}-descripcion-corta`
+   ```bash
+   git checkout -b fix/t-42-null-pointer-in-auth
+   ```
+3. **Escribí el test**: Creá un test que falla reproduciendo el bug.
+4. **Implementá el fix**: Hacé el cambio mínimo necesario para pasar el test.
+5. **Verificá**: Corré todos los tests. Confirmá que no hay regresiones.
+6. **Commit**: Usá el formato `fix(scope): descripción concisa — closes #N`
+7. **PR**: Creá el PR linkeando el issue.
+
+## Checklist
+
+- [ ] Reproduje el bug localmente
+- [ ] Escribí test de regresión que falla antes del fix
+- [ ] El fix es el cambio mínimo necesario
+- [ ] Todos los tests pasan
+- [ ] El mensaje de commit linkea el issue
+- [ ] El PR describe la causa raíz del bug

package/ai-config/commands/git/pr-create.md

@@ -0,0 +1,42 @@
+Creá un Pull Request para el branch actual con descripción completa.
+
+## Pasos
+
+1. Verificá que todos los cambios estén committed: `git status`
+2. Determiná el branch base (normalmente `main` o `develop`)
+3. Corré `git log origin/main..HEAD --oneline` para ver los commits del PR
+4. Corré `git diff origin/main...HEAD --stat` para el resumen de cambios
+5. Generá la descripción usando el template
+
+## Template de PR
+
+```markdown
+## ¿Qué hace este PR?
+
+[Descripción concisa del cambio y su propósito]
+
+## ¿Por qué?
+
+[Contexto y motivación. Linkear el issue si existe: Closes #123]
+
+## Cambios principales
+
+- [ ] Cambio 1
+- [ ] Cambio 2
+
+## Testing
+
+- [ ] Tests unitarios pasan
+- [ ] Tests de integración pasan
+- [ ] Testeo manual completado
+
+## Screenshots / evidencia
+
+[Si aplica]
+```
+
+## Comando gh
+
+```bash
+gh pr create --title "type(scope): descripción" --body "$(cat pr-body.md)" --base main
+```

package/ai-config/commands/git/pr-review.md

@@ -0,0 +1,50 @@
+Revisá el PR actual con foco en correctitud, seguridad y mantenibilidad.
+
+## Pasos
+
+1. Corré `git diff main...HEAD` o `git diff origin/main...HEAD` para ver todos los cambios.
+2. Revisá el diff completo antes de comentar.
+3. Verificá cada uno de los checkpoints de la lista.
+4. Generá un reporte estructurado con hallazgos.
+
+## Checkpoints
+
+### Correctitud
+- [ ] La lógica es correcta para el caso happy path
+- [ ] Los edge cases están manejados (null, empty, overflow)
+- [ ] El error handling es apropiado y no silencia errores
+- [ ] Las condiciones de race condition están consideradas
+
+### Seguridad
+- [ ] No hay SQL injection posible
+- [ ] Input validation en límites del sistema
+- [ ] No hay secrets en el diff
+- [ ] Autenticación/autorización correcta
+
+### Tests
+- [ ] Los tests cubren el comportamiento cambiado
+- [ ] Hay tests para edge cases críticos
+- [ ] Los tests no son frágiles (no dependen de orden o timing)
+
+### Mantenibilidad
+- [ ] El código es legible sin comentarios explicativos
+- [ ] No hay duplicación innecesaria
+- [ ] Los nombres son descriptivos
+
+## Formato de Reporte
+
+```
+## Code Review
+
+### Blockers
+- [archivo:línea] descripción del problema
+
+### Suggestions
+- [archivo:línea] mejora sugerida
+
+### Questions
+- [archivo:línea] pregunta de clarificación
+
+### Positivos
+- Buen patrón en X
+```

package/ai-config/commands/git/worktree.md

@@ -0,0 +1,39 @@
+Gestioná Git worktrees para trabajar en múltiples branches en paralelo.
+
+## ¿Cuándo usar worktrees?
+
+- Necesitás hacer un hotfix urgente mientras trabajás en una feature
+- Querés revisar otro branch sin perder tu trabajo en progreso
+- Correr tests de dos versiones en paralelo
+
+## Comandos Principales
+
+```bash
+# Listar worktrees existentes
+git worktree list
+
+# Crear nuevo worktree para un branch existente
+git worktree add ../proyecto-hotfix hotfix/critical-bug
+
+# Crear nuevo worktree con nuevo branch
+git worktree add -b feature/nueva-feature ../proyecto-nueva main
+
+# Eliminar worktree cuando ya no se necesita
+git worktree remove ../proyecto-hotfix
+
+# Limpiar referencias de worktrees eliminados manualmente
+git worktree prune
+```
+
+## Flujo Recomendado
+
+1. Creá el worktree en un directorio hermano al proyecto principal
+2. Abrí el worktree en una terminal separada (o tab)
+3. Trabajá independientemente en cada directorio
+4. Al terminar: `git worktree remove` + merge/PR normal
+
+## Precauciones
+
+- No editéis el mismo archivo en dos worktrees simultáneamente
+- Cada worktree comparte el historial git pero tiene su propio working tree
+- Los stashes son compartidos entre worktrees del mismo repo

package/ai-config/commands/refactoring/cleanup.md

@@ -0,0 +1,24 @@
+Limpiá el código del archivo o módulo actual sin cambiar su comportamiento.
+
+## Qué Limpiar
+
+1. **Código comentado**: Eliminar código comentado que no se usa (está en git history)
+2. **Console.log / print debug**: Remover logging de debug temporal
+3. **Variables no usadas**: Identificar con linter e eliminar
+4. **Imports no usados**: Limpiar imports innecesarios
+5. **Lógica duplicada**: Extraer a función/método compartido
+6. **Magic numbers**: Reemplazar con constantes con nombre descriptivo
+7. **Comentarios obvios**: Eliminar comentarios que repiten lo que hace el código
+
+## Proceso
+
+1. Corré el linter para identificar issues automáticamente
+2. Revisá el archivo buscando los items de la lista
+3. Hacé los cambios en pequeños commits agrupados por tipo
+4. Corré los tests después de cada grupo de cambios
+5. Commit: `refactor(scope): clean up X`
+
+## Regla de Oro
+
+**Si el comportamiento cambia, no es cleanup — es un bug o una feature.**
+Corré los tests antes y después. Si fallan, revertí.

package/ai-config/commands/refactoring/dead-code.md

@@ -0,0 +1,40 @@
+Identificá y eliminá código muerto (código que nunca se ejecuta o no se usa).
+
+## Tipos de Código Muerto
+
+- Funciones/métodos nunca llamados
+- Variables declaradas pero nunca leídas
+- Branches de condicionales que nunca se ejecutan (unreachable code)
+- Imports que no se usan
+- Features flags siempre false/true
+- Código después de `return` / `throw`
+
+## Detección
+
+```bash
+# TypeScript/JavaScript
+npx ts-prune  # funciones no usadas
+npx knip      # exports no usados
+
+# Go
+go vet ./...
+
+# Python
+vulture . --min-confidence 80
+
+# General: buscar con grep
+grep -r "function\|def\|func " --include="*.ts" | grep -v test
+```
+
+## Proceso Seguro
+
+1. Identificá el código candidato a eliminar
+2. Buscá todos los usos en el codebase (grep exhaustivo)
+3. Verificá que no se usa vía reflection, dynamic imports o configuración externa
+4. Eliminá el código
+5. Corré el suite completo de tests
+6. Si pasan: commit `refactor: remove dead code in X`
+
+## Precaución
+
+Algunos "dead code" es intencional: hooks de lifecycle, handlers registrados dinámicamente, código de compatibility. Verificá antes de eliminar.

package/ai-config/commands/refactoring/extract.md

@@ -0,0 +1,31 @@
+Extraé lógica duplicada o compleja a funciones/módulos separados.
+
+## Cuándo Extraer
+
+- La misma lógica aparece en 2+ lugares (DRY)
+- Una función hace más de una cosa (SRP)
+- Una función supera ~30-40 líneas
+- Un bloque de código necesita un comentario para explicar qué hace
+
+## Proceso
+
+1. Identificá el bloque a extraer
+2. Determiná el nombre descriptivo (verbo + sustantivo: `calculateTotal`, `validateEmail`)
+3. Identificá los inputs (parámetros) y el output (valor de retorno)
+4. Creá la función en el lugar apropiado (mismo archivo, módulo utilitario, o clase)
+5. Reemplazá el bloque original con la llamada a la nueva función
+6. Corré los tests
+7. Repetí para cada ocurrencia duplicada
+
+## Nombres de Funciones
+
+- Debe describir QUÉ hace, no CÓMO lo hace
+- Verbo en imperativo: `get`, `calculate`, `validate`, `transform`, `parse`
+- Específico: `getUserById` > `getUser` > `get`
+- Sin abreviaturas oscuras
+
+## Commit
+
+```
+refactor(scope): extract X logic into Y function
+```

package/ai-config/commands/testing/e2e.md

@@ -0,0 +1,30 @@
+Escribí o corré tests end-to-end para verificar flujos completos del sistema.
+
+## Cuándo Usar E2E
+
+- Flujos críticos de negocio (checkout, login, registro)
+- Integraciones entre múltiples servicios
+- Regresiones de bugs reportados por usuarios
+- Smoke tests post-deploy
+
+## Pasos para Escribir E2E
+
+1. Identificá el flujo de usuario completo (inicio → fin)
+2. Listá los pasos exactos del usuario
+3. Definí los assertions en cada paso crítico
+4. Usá selectores robustos (data-testid preferido sobre CSS classes)
+5. Manejá estados asíncronos correctamente (waitFor, expect.poll)
+
+## Principios
+
+- **Independencia**: Cada test debe poder correr solo
+- **Idempotencia**: Limpiar estado antes/después del test
+- **Realismo**: Testear como el usuario real lo haría
+- **Determinismo**: Evitar flakiness con waits explícitos
+
+## Stack por Proyecto
+
+- **Web**: Playwright o Cypress
+- **Mobile**: Detox o Appium
+- **API**: Supertest o Rest Assured
+- **CLI**: expect o subprocess testing

package/ai-config/commands/testing/tdd.md

@@ -0,0 +1,36 @@
+Implementá una feature usando Test-Driven Development (TDD).
+
+## Ciclo Red-Green-Refactor
+
+1. **RED**: Escribí un test que falla para el comportamiento deseado
+2. **GREEN**: Escribí el código mínimo para que el test pase
+3. **REFACTOR**: Mejorá el código sin romper los tests
+
+## Pasos
+
+1. Definí el comportamiento esperado en lenguaje natural
+2. Escribí el test primero (debe fallar — confirmá que falla)
+3. Implementá solo lo necesario para pasar el test
+4. Corré el test (debe pasar)
+5. Refactorizá si hay duplicación u oportunidades de mejora
+6. Repetí para el siguiente comportamiento
+
+## Reglas TDD
+
+- **Un test a la vez**: Focus en un comportamiento específico
+- **Test mínimo**: El test más simple que falla
+- **Código mínimo**: Solo lo necesario para pasar, nada más
+- **No adelantarse**: No implementar funcionalidad sin test previo
+- **Refactor only on green**: Solo refactorizá cuando todos los tests pasan
+
+## Estructura de Tests
+
+```
+describe("Componente/Función", () => {
+  it("debe hacer X cuando Y", () => {
+    // Arrange
+    // Act  
+    // Assert
+  })
+})
+```

package/ai-config/commands/testing/test-coverage.md

@@ -0,0 +1,30 @@
+Analizá la cobertura de tests e identificá gaps críticos.
+
+## Pasos
+
+1. Corré el coverage report del proyecto:
+   - Go: `go test ./... -coverprofile=coverage.out && go tool cover -html=coverage.out`
+   - Node/TS: `npm run test:coverage` o `vitest --coverage`
+   - Python: `pytest --cov=src --cov-report=html`
+2. Identificá archivos con cobertura < 70%
+3. Revisá paths de código no cubiertos — enfocate en:
+   - Manejo de errores
+   - Edge cases (nil, empty, boundary values)
+   - Paths de autenticación/autorización
+4. Priorizá tests para código crítico primero
+
+## Métricas Objetivo
+
+| Tipo | Mínimo | Objetivo |
+|------|--------|----------|
+| Statements | 70% | 85% |
+| Branches | 60% | 80% |
+| Functions | 75% | 90% |
+| Lines | 70% | 85% |
+
+## Lo Que NO Necesita Tests
+
+- Getters/setters triviales sin lógica
+- Código generado automáticamente
+- Configuración estática (constantes)
+- Código de terceros

package/ai-config/commands/testing/test-fix.md

@@ -0,0 +1,24 @@
+Corregí tests que fallan sin romper la lógica de negocio.
+
+## Pasos
+
+1. Identificá todos los tests que fallan: `npm test 2>&1 | grep FAIL`
+2. Para cada test fallando:
+   a. Leé el mensaje de error completo
+   b. Determiná si falla por: bug en código, test desactualizado, o flakiness
+3. **Si es bug en código**: Seguí el flujo de fix-issue
+4. **Si el test está desactualizado**: Actualizá el test para reflejar el comportamiento correcto
+5. **Si es flakiness**: Identificá la causa (timing, orden, estado compartido) y eliminala
+
+## Nunca
+
+- No borres tests que fallan sin entender por qué fallan
+- No cambies assertions para que siempre pasen sin verificar que el comportamiento es correcto
+- No agregues `skip` o `xtest` sin documentar por qué y crear un issue
+
+## Diagnóstico de Flakiness
+
+```bash
+# Correr el test N veces para confirmar flakiness
+for i in {1..10}; do npm test -- --testNamePattern="nombre del test" 2>&1 | tail -1; done
+```

package/ai-config/commands/workflow/generate-agents-md.md

@@ -0,0 +1,85 @@
+---
+name: generate-agents-md
+description: Inspect project and auto-generate a cross-agent compatible AGENTS.md
+category: workflow
+---
+
+# /generate-agents-md
+
+Inspects the current project and generates a well-structured `AGENTS.md` compatible with all major AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, OpenCode).
+
+## Usage
+
+```
+/generate-agents-md
+```
+
+## Steps
+
+### 1. Detect Project Stack
+
+```bash
+# Package manager
+ls package.json pyproject.toml Cargo.toml go.mod pom.xml build.gradle 2>/dev/null
+
+# Test runner
+cat package.json | grep -E '"test"|"jest"|"vitest"' 2>/dev/null
+ls pytest.ini setup.cfg .pytest.ini 2>/dev/null
+
+# CI workflows
+ls .github/workflows/*.yml 2>/dev/null | head -5
+
+# PR title pattern from recent commits
+git log --oneline -10 2>/dev/null
+```
+
+### 2. Generate AGENTS.md Structure
+
+Output a file with these sections:
+
+```markdown
+# AGENTS.md
+
+> Cross-agent configuration for AI coding assistants.
+> Compatible with: Claude Code, OpenCode, Codex CLI, Gemini CLI, GitHub Copilot.
+
+## Dev Environment
+
+- **Language:** <detected>
+- **Package manager:** <detected>
+- **Node/Python/Go version:** <from .nvmrc / .python-version / go.mod>
+
+## Setup
+
+```bash
+<install command: npm install / pip install -r requirements.txt / go mod tidy>
+```
+
+## Testing
+
+```bash
+<test command: npm test / pytest / go test ./...>
+```
+
+## Key Conventions
+
+- <PR title format from git log, e.g., Conventional Commits>
+- <branch naming from git branch -r>
+- <code style: eslint/prettier/black/gofmt if config files found>
+
+## Important Files
+
+- `<main config file>` — <brief description>
+- `<main entry point>` — <brief description>
+
+## AI Agent Notes
+
+- Always run tests before marking a task complete
+- Never commit directly to main — use feature branches
+- Follow existing code style; check linter config before writing new code
+- For large changes, create a plan first with /workflows:plan
+```
+
+### 3. Save and Confirm
+
+Save to project root as `AGENTS.md` and report what was detected vs. what defaulted to assumptions.

package/ai-config/commands/workflow/planning.md

@@ -0,0 +1,47 @@
+Creá un plan estructurado antes de implementar una feature o cambio complejo.
+
+## Cuándo Planificar Primero
+
+- Feature nueva que toca múltiples archivos o servicios
+- Cambio que requiere migración de datos
+- Refactoring de componente crítico
+- Cualquier tarea > 2 horas estimadas
+
+## Template de Plan
+
+```markdown
+## Feature: [nombre]
+
+### Problema
+[Qué problema resuelve]
+
+### Solución Propuesta
+[Descripción técnica de la solución]
+
+### Archivos Afectados
+- `src/x.go` — añadir función Y
+- `tests/x_test.go` — tests para Y
+- `api/routes.go` — registrar nuevo endpoint
+
+### Orden de Implementación
+1. Paso 1 (independiente)
+2. Paso 2 (depende de 1)
+3. Paso 3
+
+### Riesgos
+- Riesgo A → Mitigación A
+- Riesgo B → Mitigación B
+
+### Criterios de Done
+- [ ] Feature funciona para casos normales
+- [ ] Edge cases cubiertos
+- [ ] Tests pasan
+- [ ] Documentación actualizada
+```
+
+## Principios
+
+- Planificá a nivel de archivos y funciones, no de líneas
+- Identificá dependencias entre pasos
+- Empezá por lo más incierto o riesgoso
+- Un plan es una guía, no un contrato — actualizarlo está bien