javi-forge 1.2.0 → 1.4.0

package/ai-config/hooks/commit-guard.md

@@ -1,90 +0,0 @@
----
-name: commit-guard
-description: Valida que los mensajes de commit sigan el formato Conventional Commits antes de ejecutar git commit. Trigger: PreToolUse Bash
-event: PreToolUse
-tools:
-  - Bash
-match_pattern: "git commit"
-action: warn
-metadata:
-  author: project-starter-framework
-  version: "1.0"
----
-
-# Commit Guard Hook
-
-> Valida el formato Conventional Commits antes de ejecutar `git commit`.
-
-## Propósito
-
-Garantizar que todos los commits sigan el estándar Conventional Commits (`feat`, `fix`, `refactor`, etc.) para mantener un historial limpio y semver automático.
-
-## Formato Válido
-
-```
-type(scope): descripción en imperativo
-
-[cuerpo opcional]
-
-[footer opcional]
-```
-
-### Tipos Permitidos
-
-| Tipo | Cuándo usarlo |
-|------|---------------|
-| `feat` | Nueva funcionalidad |
-| `fix` | Corrección de bug |
-| `refactor` | Reestructuración sin cambio de comportamiento |
-| `docs` | Solo documentación |
-| `test` | Añadir o actualizar tests |
-| `chore` | Build, CI, dependencias |
-| `perf` | Mejora de performance |
-| `style` | Formato, espacios (sin cambio lógico) |
-| `ci` | Cambios en CI/CD |
-| `revert` | Revertir commit anterior |
-
-## Comportamiento
-
-1. **Intercepta** comandos que contienen `git commit`
-2. **Extrae** el mensaje de commit (`-m "..."`)
-3. **Valida** contra el patrón `^(feat|fix|refactor|docs|test|chore|perf|style|ci|revert)(\(.+\))?: .{1,72}$`
-4. **Alerta** si no cumple, muestra ejemplo correcto
-5. **Permite** continuar (es warning, no block)
-
-## Implementación Claude Code
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [{ "type": "command", "command": "echo \"$TOOL_INPUT\" | grep -q 'git commit' && echo \"$TOOL_INPUT\" | grep -oP '(?<=-m \")[^\"]+' | grep -qP '^(feat|fix|refactor|docs|test|chore|perf|style|ci|revert)(\\(.+\\))?: .{1,72}$' || (echo 'WARN: Mensaje no sigue Conventional Commits. Ejemplo: feat(auth): add login endpoint' && exit 0)" }]
-      }
-    ]
-  }
-}
-```
-
-## Ejemplos
-
-### ✅ Válidos
-```
-feat(auth): add JWT refresh token endpoint
-fix(api): handle null response from external service
-refactor(db): extract query builder into separate module
-docs: update README with new setup instructions
-```
-
-### ❌ Inválidos
-```
-"fixed stuff"
-"WIP"
-"update"
-"Added new feature for the user authentication system"
-```
-
-## Notas
-
-No bloquea el commit — es un recordatorio. Para enforcement estricto cambiar `action: warn` a `action: block`.

package/ai-config/hooks/context-loader.md

@@ -1,73 +0,0 @@
----
-name: context-loader
-description: Al iniciar sesión, carga el estado del proyecto (git, TODOs pendientes, últimos cambios). Trigger: SessionStart
-event: SessionStart
-action: execute
-metadata:
-  author: project-starter-framework
-  version: "1.0"
----
-
-# Context Loader Hook
-
-> Carga contexto del proyecto automáticamente al iniciar cada sesión AI.
-
-## Propósito
-
-Proporcionar contexto inmediato al AI sobre el estado actual del proyecto sin necesidad de preguntarlo manualmente cada vez.
-
-## Información Cargada
-
-### Estado Git
-- Branch actual y commits recientes (`git log --oneline -5`)
-- Cambios sin commitear (`git status --short`)
-- Archivos modificados recientemente
-
-### TODOs y Tasks
-- Busca archivos `TODO.md`, `TASKS.md`, `.todo`
-- Extrae líneas con `TODO:`, `FIXME:`, `HACK:` del código
-
-### Config del Proyecto
-- `package.json` → nombre, versión, scripts principales
-- Lenguaje/runtime detectado (Go, Python, Node, Rust, Java)
-- Stack inferido de archivos presentes
-
-## Comportamiento
-
-1. **Ejecuta** al inicio de cada sesión Claude Code
-2. **Recopila** información de estado en menos de 2 segundos
-3. **Inyecta** un resumen compacto al contexto inicial
-4. **No bloquea** ni modifica archivos
-
-## Implementación Claude Code
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "hooks": [{ "type": "command", "command": "echo '=== PROJECT CONTEXT ===' && git branch --show-current 2>/dev/null && git log --oneline -3 2>/dev/null && echo '--- Status ---' && git status --short 2>/dev/null | head -10 && echo '--- Recent TODOs ---' && grep -r 'TODO:\\|FIXME:' --include='*.go' --include='*.ts' --include='*.py' -l 2>/dev/null | head -5 && echo '=== END CONTEXT ===' || true" }]
-      }
-    ]
-  }
-}
-```
-
-## Configuración
-
-Puedes personalizar qué información se carga editando el comando según el stack del proyecto:
-
-```bash
-# Para proyectos Go
-grep -r 'TODO:\|FIXME:' --include='*.go' .
-
-# Para proyectos TypeScript/Node
-cat package.json | jq '{name,version,scripts}' 2>/dev/null
-
-# Para proyectos Python
-cat pyproject.toml 2>/dev/null | head -20
-```
-
-## Notas
-
-Este hook es read-only — nunca modifica archivos. El overhead es mínimo (< 500ms en proyectos normales).

package/ai-config/hooks/improve-prompt.md

@@ -1,91 +0,0 @@
----
-name: improve-prompt
-description: Intercepts vague user prompts and asks clarifying questions before execution. Bypass with *, /, #, or ! prefix.
-event: UserPromptSubmit
-action: execute
-metadata:
-  author: project-starter-framework
-  version: "1.0"
-  updated: "2026-02"
----
-
-# Improve Prompt Hook
-
-> Intercepts short or vague prompts and asks targeted clarifying questions to improve output quality.
-
-## Purpose
-
-Prevent low-quality AI responses caused by under-specified prompts. When a prompt is vague (< 15 words, no clear action verb), the hook pauses and asks up to 3 clarifying questions before proceeding.
-
-## Bypass Prefixes
-
-Prefix your prompt with any of the following to skip interception and pass through immediately:
-
-| Prefix | Meaning |
-|--------|---------|
-| `*` | Force execute as-is |
-| `/` | Slash command — pass through |
-| `#` | Comment / meta instruction |
-| `!` | Override / urgent |
-
-**Example**: `* just do it` → skips all checks.
-
-## Vagueness Detection
-
-A prompt is considered vague when **both** conditions are true:
-1. Word count < 15
-2. No clear action verb detected (e.g., `create`, `fix`, `refactor`, `add`, `remove`, `update`, `write`, `build`, `test`, `explain`, `analyze`, `generate`)
-
-## Clarifying Questions (up to 3)
-
-Based on what's missing, the hook asks from:
-
-1. **Output**: What is the expected output or deliverable?
-2. **Constraints**: What constraints or requirements apply (language, framework, style)?
-3. **Context**: What already exists that I should be aware of?
-
-## Companion Skill
-
-See `.ai-config/skills/prompt-improver/SKILL.md` for the full 4-phase logic used to enrich prompts before execution.
-
-## Implementation (Claude Code JSON)
-
-```json
-{
-  "hooks": {
-    "UserPromptSubmit": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"\nimport sys, os\nprompt = os.environ.get('CLAUDE_USER_PROMPT', '')\nbypass = ['*', '/', '#', '!']\nif any(prompt.strip().startswith(p) for p in bypass):\n    sys.exit(0)\nwords = prompt.strip().split()\naction_verbs = ['create','fix','refactor','add','remove','update','write','build','test','explain','analyze','generate','implement','debug','review','migrate','deploy','configure','setup','delete','rename','move','convert','optimize','document']\nhas_verb = any(v in prompt.lower() for v in action_verbs)\nif len(words) < 15 and not has_verb:\n    print('PROMPT IMPROVEMENT NEEDED')\n    print('Your prompt appears vague. Please answer up to 3 questions:')\n    print('  1. What is the expected output or deliverable?')\n    print('  2. What constraints apply (language, framework, style)?')\n    print('  3. What already exists that I should be aware of?')\n    print('Tip: Prefix with * to skip this check (e.g. \\\"* just do it\\\")')\n    sys.exit(1)\nsys.exit(0)\n\""
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Examples
-
-### ✅ Passes Through
-```
-* fix it quickly
-/commit
-# note: use typescript
-! urgent: rollback last change
-create a REST endpoint for user authentication using FastAPI with JWT
-```
-
-### 🛑 Intercepted (vague)
-```
-fix the bug
-make it better
-add feature
-help
-```
-
-## Notes
-
-This hook complements the `prompt-improver` skill. For prompts that pass through but still need enrichment, the skill applies the full 4-phase Analyze → Research → Question → Execute flow.

package/ai-config/hooks/learning-log.md

@@ -1,72 +0,0 @@
----
-name: learning-log
-description: Al finalizar sesión, guarda un resumen de lo aprendido y los commits realizados. Trigger: SessionEnd
-event: SessionEnd
-action: execute
-metadata:
-  author: project-starter-framework
-  version: "1.0"
----
-
-# Learning Log Hook
-
-> Registra automáticamente los aprendizajes y cambios de cada sesión AI.
-
-## Propósito
-
-Crear un historial de sesiones que documente decisiones técnicas, problemas encontrados y soluciones aplicadas — útil para onboarding, debugging futuro y mejora continua.
-
-## Información Registrada
-
-### Por Sesión
-- Fecha y hora de la sesión
-- Branch y commits realizados durante la sesión
-- Archivos modificados (lista compacta)
-- Resumen de cambios (del último commit message)
-
-### Formato de Log
-
-```markdown
-## 2026-02-25 — feat(auth): add refresh tokens
-
-**Branch:** feature/t-42-refresh-tokens
-**Commits:** 3
-**Files changed:** src/auth/token.go, src/auth/refresh.go, tests/auth_test.go
-
-**Notes:** Implemented JWT refresh token flow with Redis-backed token rotation.
-Issues: Had to handle concurrent refresh requests with mutex.
-```
-
-## Comportamiento
-
-1. **Ejecuta** al cerrar cada sesión Claude Code
-2. **Recopila** commits realizados desde inicio de sesión
-3. **Escribe** entrada al log `.ai-session-log.md` (gitignored)
-4. **Rota** el log cuando supera 1000 líneas
-
-## Implementación Claude Code
-
-```json
-{
-  "hooks": {
-    "SessionEnd": [
-      {
-        "hooks": [{ "type": "command", "command": "LOG='.ai-session-log.md'; DATE=$(date '+%Y-%m-%d %H:%M'); BRANCH=$(git branch --show-current 2>/dev/null); COMMITS=$(git log --oneline --since='8 hours ago' 2>/dev/null | head -5); echo \"\\n## $DATE — $BRANCH\\n\\n$COMMITS\" >> $LOG 2>/dev/null || true" }]
-      }
-    ]
-  }
-}
-```
-
-## Configuración del .gitignore
-
-Agregar al `.gitignore` del proyecto:
-```
-.ai-session-log.md
-```
-
-O committear el log si se quiere historial compartido con el equipo.
-
-## Notas
-
-El log es local por defecto. Para compartir con el equipo, quitar de `.gitignore` y commitear periódicamente con `chore: update AI session log`.

package/ai-config/hooks/model-router.md

@@ -1,86 +0,0 @@
----
-name: model-router
-description: Detects task complexity from prompt keywords and recommends the appropriate Claude model. Logs a recommendation comment without blocking execution.
-event: UserPromptSubmit
-action: log
-
-metadata:
-  author: project-starter-framework
-  version: "1.0"
-  updated: "2026-02"
----
-
-# Model Router Hook
-
-> Recommends the optimal Claude model based on task complexity keywords. Non-blocking — documents the recommendation as a comment.
-
-## Purpose
-
-Help developers choose the right model for cost and quality efficiency. Complex reasoning
-tasks benefit from Opus; routine edits benefit from Haiku; most work is Sonnet territory.
-
-## Evento
-
-- **Trigger:** UserPromptSubmit (or SessionStart)
-- **Action:** log (recommendation only — does not force model selection)
-- **Condition:** Every prompt is evaluated; only logs when a non-default model is recommended
-
-## Model Routing Table
-
-| Keywords in Prompt | Recommended Model | Reason |
-|-------------------|-------------------|--------|
-| `architect`, `system design`, `design pattern`, `scalability`, `microservice`, `distributed`, `trade-off`, `ADR` | `claude-opus-4-5` | Complex multi-step reasoning required |
-| `security audit`, `threat model`, `CVE`, `OWASP`, `pentest`, `cryptography` | `claude-opus-4-5` | Security analysis needs deep reasoning |
-| `performance profile`, `memory leak`, `flame graph`, `bottleneck analysis` | `claude-opus-4-5` | Diagnostic reasoning over complex systems |
-| `quick fix`, `typo`, `rename`, `lint`, `format`, `simple`, `one-liner`, `obvious` | `claude-haiku-4-5` | Fast and cost-effective for trivial tasks |
-| `add comment`, `update README`, `fix spacing`, `bump version` | `claude-haiku-4-5` | Lightweight documentation/formatting tasks |
-| *(default — everything else)* | `claude-sonnet-4-5` | Balanced capability and cost |
-
-## Lógica
-
-```
-SI prompt matches opus keywords
-ENTONCES log "💡 Model recommendation: claude-opus-4-5 (complex reasoning detected)"
-SINO SI prompt matches haiku keywords
-ENTONCES log "💡 Model recommendation: claude-haiku-4-5 (simple task detected)"
-SINO log nothing (sonnet is default, no recommendation needed)
-```
-
-## Implementación
-
-### Para Claude Code
-
-```json
-{
-  "hooks": {
-    "UserPromptSubmit": [
-      {
-        "matcher": ".*",
-        "command": "bash .ai-config/scripts/model-router.sh \"$CLAUDE_USER_PROMPT\""
-      }
-    ]
-  }
-}
-```
-
-### Script: .ai-config/scripts/model-router.sh
-
-```bash
-#!/bin/bash
-PROMPT="$1"
-OPUS_PATTERN="architect|system design|design pattern|scalability|microservice|distributed|trade.off|ADR|security audit|threat model|CVE|OWASP|pentest|cryptography|performance profile|memory leak|flame graph|bottleneck analysis"
-HAIKU_PATTERN="quick fix|typo|rename|lint|format|simple|one.liner|obvious|add comment|update README|fix spacing|bump version"
-
-if echo "$PROMPT" | grep -qiE "$OPUS_PATTERN"; then
-  echo "💡 Model recommendation: claude-opus-4-5 — complex reasoning detected in prompt"
-elif echo "$PROMPT" | grep -qiE "$HAIKU_PATTERN"; then
-  echo "💡 Model recommendation: claude-haiku-4-5 — simple task detected, consider switching for cost savings"
-fi
-# Default (sonnet): no output needed
-```
-
-## Notes
-
-- This hook is **advisory only** — it does not change the active model
-- To actually switch models, use the `/model` command or configure in `CLAUDE.md`
-- Tune the keyword patterns for your team's vocabulary

package/ai-config/hooks/secret-scanner.md

@@ -1,64 +0,0 @@
----
-name: secret-scanner
-description: Escanea archivos antes de escribir/editar para detectar secrets y credenciales. Trigger: PreToolUse Write/Edit
-event: PreToolUse
-tools:
-  - Write
-  - Edit
-action: warn
-metadata:
-  author: project-starter-framework
-  version: "1.0"
----
-
-# Secret Scanner Hook
-
-> Detecta secrets, tokens y credenciales antes de escribir archivos.
-
-## Propósito
-
-Prevenir que API keys, tokens, passwords y otras credenciales sean escritas en archivos del proyecto o commits.
-
-## Patrones Detectados
-
-| Patrón | Ejemplo |
-|--------|---------|
-| AWS keys | `AKIA[0-9A-Z]{16}` |
-| Private keys | `-----BEGIN (RSA\|EC\|DSA) PRIVATE KEY-----` |
-| Tokens Bearer | `Bearer [a-zA-Z0-9_-]{20,}` |
-| GitHub PAT | `ghp_[a-zA-Z0-9]{36}` |
-| Generic secret | `(secret\|password\|passwd\|pwd)\s*=\s*[^\s]{8,}` |
-| API Key pattern | `api[_-]?key\s*=\s*[^\s]{8,}` |
-| .env secrets | Variables en archivos `.env` con valores reales |
-
-## Comportamiento
-
-1. **Analiza** el contenido antes de escribir
-2. **Detecta** patrones de secrets conocidos
-3. **Alerta** al usuario con la línea problemática
-4. **Sugiere** usar variables de entorno o `.env.example` en su lugar
-
-## Implementación Claude Code
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write",
-        "hooks": [{ "type": "command", "command": "echo \"$TOOL_INPUT\" | python3 -c \"import sys,re; content=sys.stdin.read(); patterns=[r'AKIA[0-9A-Z]{16}', r'-----BEGIN.*(RSA|EC).PRIVATE', r'ghp_[a-zA-Z0-9]{36}', r'(?i)(password|secret|api_?key)\\s*=\\s*[\\S]{8,}']; found=[p for p in patterns if re.search(p,content)]; print('SECRET DETECTED: '+str(found)) if found else None; sys.exit(1 if found else 0)\"" }]
-      }
-    ]
-  }
-}
-```
-
-## Excepciones Legítimas
-
-- Archivos `.env.example` con valores placeholder (`YOUR_KEY_HERE`)
-- Archivos de test con datos ficticios (`fake-secret-for-testing`)
-- Documentación que explica el formato (sin valores reales)
-
-## Notas
-
-Complementa al hook `block-dangerous-commands`. Para secrets reales usar siempre variables de entorno.

package/ai-config/hooks/skill-validator.md

@@ -1,102 +0,0 @@
----
-name: skill-validator
-description: Validates new SKILL.md files being written to ensure they follow the required format and conventions.
-event: PreToolUse
-tools:
-  - Write
-  - Edit
-match_pattern: ".ai-config/skills/.*/SKILL\\.md"
-action: warn
-metadata:
-  author: project-starter-framework
-  version: "1.0"
-  updated: "2026-02"
----
-
-# Skill Validator Hook
-
-> Validates SKILL.md files before they are written to ensure they meet required format standards.
-
-## Purpose
-
-Prevent malformed or incomplete skill files from being saved. Catches common issues like missing required fields, absolute paths, wildcard tool usage, and missing trigger keywords.
-
-## Checks Performed
-
-| Check | Rule |
-|-------|------|
-| `name` field | Must be present in frontmatter |
-| `description` field | Must contain trigger keywords (e.g., `Trigger:`) |
-| `tags` field | Must be present and non-empty |
-| Absolute paths | No `/Users/` or `/home/` paths in content |
-| Wildcard tools | Tools list must not contain `"*"` |
-
-## Behavior
-
-1. **Intercepts** Write/Edit operations targeting `SKILL.md` files under `.ai-config/skills/`
-2. **Reads** the content being written
-3. **Validates** each rule above
-4. **Warns** with specific failure reasons if any check fails
-5. **Allows** the write to proceed (action: warn, not block)
-
-## Implementation (Claude Code JSON)
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"\nimport sys, os, json, re\ntool_input = os.environ.get('TOOL_INPUT', '{}')\ntry:\n    data = json.loads(tool_input)\nexcept Exception:\n    sys.exit(0)\nfile_path = data.get('file_path', data.get('path', ''))\nif not re.search(r'\\.ai-config/skills/.+/SKILL\\.md', file_path):\n    sys.exit(0)\ncontent = data.get('content', '')\nwarnings = []\nif not re.search(r'^name:\\s*.+', content, re.MULTILINE):\n    warnings.append('MISSING: name field in frontmatter')\nif not re.search(r'Trigger:', content):\n    warnings.append('MISSING: Trigger keywords in description field')\nif not re.search(r'^tags:', content, re.MULTILINE):\n    warnings.append('MISSING: tags field in frontmatter')\nif re.search(r'/Users/|/home/', content):\n    warnings.append('INVALID: Absolute path detected (/Users/ or /home/). Use relative paths.')\nif re.search(r'tools:\\s*\\[\\s*\\\"\\*\\\"', content) or re.search(r\"tools:\\s*\\[\\s*'\\*'\", content):\n    warnings.append('INVALID: Wildcard tool [\\\"*\\\"] is not allowed. List specific tools.')\nif warnings:\n    print('SKILL VALIDATION WARNINGS:')\n    for w in warnings:\n        print('  - ' + w)\n    print('Fix these issues to ensure the skill works correctly.')\nsys.exit(0)\n\""
-          }
-        ]
-      },
-      {
-        "matcher": "Edit",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"\nimport sys, os, json, re\ntool_input = os.environ.get('TOOL_INPUT', '{}')\ntry:\n    data = json.loads(tool_input)\nexcept Exception:\n    sys.exit(0)\nfile_path = data.get('file_path', data.get('path', ''))\nif not re.search(r'\\.ai-config/skills/.+/SKILL\\.md', file_path):\n    sys.exit(0)\nnew_content = data.get('new_str', data.get('new_content', ''))\nif not new_content:\n    sys.exit(0)\nwarnings = []\nif re.search(r'/Users/|/home/', new_content):\n    warnings.append('INVALID: Absolute path detected (/Users/ or /home/). Use relative paths.')\nif re.search(r'tools:\\s*\\[\\s*\\\"\\*\\\"', new_content) or re.search(r\"tools:\\s*\\[\\s*'\\*'\", new_content):\n    warnings.append('INVALID: Wildcard tool [\\\"*\\\"] is not allowed. List specific tools.')\nif warnings:\n    print('SKILL VALIDATION WARNINGS (Edit):')\n    for w in warnings:\n        print('  - ' + w)\nsys.exit(0)\n\""
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-## Examples
-
-### ✅ Valid SKILL.md
-```yaml
----
-name: my-skill
-description: >
-  Does something useful.
-  Trigger: keyword1, keyword2
-tools:
-  - Read
-  - Bash
-metadata:
-  tags: [tag1, tag2]
----
-```
-
-### ❌ Will Warn
-```yaml
----
-# Missing name field
-description: Does something.  # Missing Trigger:
-tools:
-  - "*"                        # Wildcard not allowed
----
-
-# Content with /Users/john/project/file.ts  ← absolute path
-```
-
-## Notes
-
-This hook validates Write and Edit operations. For a full skill authoring guide, see `.ai-config/skills/_TEMPLATE.md`.