javi-forge 0.1.0

package/ai-config/commands/workflows/compound.md

@@ -0,0 +1,89 @@
+---
+name: compound
+description: Post-completion workflow — summarize what was learned, append to learnings.md, and suggest CLAUDE.md improvements. Triggered after significant task completion.
+category: workflows
+---
+
+# /workflows:compound
+
+Capture learnings after completing significant work and improve project AI configuration.
+
+## Usage
+
+```
+/workflows:compound [<feature-name>]
+```
+
+Run this after completing a feature, fixing a complex bug, or finishing a refactoring session.
+
+## What It Does
+
+1. **Summarizes the work**: What was built, changed, or discovered
+2. **Extracts learnings**: Patterns found, mistakes made, approaches that worked
+3. **Appends to learnings.md**: Persistent knowledge base at project root
+4. **Suggests CLAUDE.md improvements**: 1-3 specific, actionable improvements
+
+## PostToolUse Pattern
+
+This command is designed to trigger after significant task completion. Add to your workflow:
+```
+After every /workflows:work completion → run /workflows:compound
+After every major debugging session → run /workflows:compound
+After every architecture decision → run /workflows:compound
+```
+
+## Process
+
+```
+STEP 1: Review what was just completed
+         → Read tasks/<feature-name>/plan.md (if exists)
+         → Read tasks/<feature-name>/files-edited.md (if exists)
+         → Reflect on the conversation/session
+
+STEP 2: Synthesize learnings
+         → What patterns were discovered?
+         → What went wrong and how was it resolved?
+         → What would you do differently next time?
+         → What project-specific context would help future sessions?
+
+STEP 3: Append to learnings.md
+         → Create if it doesn't exist
+         → Add dated entry with feature name
+
+STEP 4: Suggest CLAUDE.md improvements
+         → Review current CLAUDE.md
+         → Propose 1-3 specific additions or changes
+```
+
+## learnings.md Format
+
+```markdown
+## YYYY-MM-DD — <feature-name or topic>
+
+### What Was Done
+[Brief summary of work completed]
+
+### Key Learnings
+- [Learning 1: specific and reusable]
+- [Learning 2: specific and reusable]
+
+### What Went Wrong
+- [Issue encountered and how it was resolved]
+
+### Patterns to Reuse
+- [Approach that worked well and should be applied again]
+```
+
+## CLAUDE.md Suggestion Format
+
+```
+Suggested CLAUDE.md improvements:
+
+1. **Add command to run tests**: `npm test` — discovered during this session that
+   tests need to be run with --watch=false in CI context
+
+2. **Document auth pattern**: Project uses custom JWT middleware — add to CLAUDE.md
+   so future sessions don't re-discover this
+
+3. **Note environment variables**: DATABASE_URL must be set — add to setup section
+```

package/ai-config/commands/workflows/plan.md

@@ -0,0 +1,77 @@
+---
+name: plan
+description: Decompose a feature into structured tasks with goal, acceptance criteria, estimates, risks, and dependencies. Saves to tasks/<feature-name>/plan.md
+category: workflows
+---
+
+# /workflows:plan
+
+Decompose a feature or task into a structured, actionable plan before writing any code.
+
+## Usage
+
+```
+/workflows:plan <feature-name>
+```
+
+## What It Does
+
+1. **Clarifies the goal**: What problem does this solve? What's the success state?
+2. **Defines acceptance criteria**: Concrete, testable conditions for "done"
+3. **Breaks down tasks**: Ordered list with time estimates and dependencies
+4. **Identifies risks**: What could go wrong and how to mitigate it
+5. **Saves the plan**: Writes to `tasks/<feature-name>/plan.md`
+
+## Process
+
+```
+STEP 1: Ask clarifying questions if the feature is ambiguous
+STEP 2: Draft the plan using the template below
+STEP 3: Save to tasks/<feature-name>/plan.md
+STEP 4: Confirm with user before starting implementation
+```
+
+## Plan Template
+
+```markdown
+# Plan: <feature-name>
+
+## Goal
+[One paragraph: what this feature does and why it matters]
+
+## Acceptance Criteria
+- [ ] [Testable condition 1]
+- [ ] [Testable condition 2]
+- [ ] [Testable condition 3]
+
+## Task List
+
+| # | Task | Estimate | Depends On | Status |
+|---|------|----------|------------|--------|
+| 1 | [Task description] | 30m | — | pending |
+| 2 | [Task description] | 1h | 1 | pending |
+| 3 | [Task description] | 45m | 2 | pending |
+
+## Risks
+
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk 1] | Low/Med/High | Low/Med/High | [How to handle it] |
+
+## Dependencies
+- External services: [list any]
+- Other features/branches: [list any]
+- Team: [list any people/approvals needed]
+
+## Notes
+[Anything else relevant to implementation]
+```
+
+## Output Location
+
+Plan is saved to: `tasks/<feature-name>/plan.md`
+
+If the directory doesn't exist, create it:
+```bash
+mkdir -p tasks/<feature-name>
+```

package/ai-config/commands/workflows/review.md

@@ -0,0 +1,78 @@
+---
+name: review
+description: Multi-perspective code review using code-reviewer and security-auditor agents on staged changes. Reads review policy before reviewing. Outputs inline comments with severity.
+category: workflows
+---
+
+# /workflows:review
+
+Run a multi-perspective review on staged changes before committing or opening a PR.
+
+## Usage
+
+```
+/workflows:review [--scope staged|branch|<file-path>]
+```
+
+## What It Does
+
+1. **Loads review policy**: Reads `.ai-config/prompts/review-policy.md` for project standards
+2. **Gathers changes**: Gets staged diff or branch diff depending on scope
+3. **Runs code-reviewer perspective**: Quality, SOLID, DRY, naming, test coverage
+4. **Runs security-auditor perspective**: OWASP, injection, auth/authz, secrets
+5. **Outputs consolidated report**: Inline comments grouped by file with severity
+
+## Process
+
+```
+STEP 1: Load .ai-config/prompts/review-policy.md (if exists)
+         → Use project-specific standards for what constitutes a violation
+
+STEP 2: Gather diff
+         git diff --staged                    # for staged changes
+         git diff main...HEAD                 # for branch changes
+
+STEP 3: Code Quality Review (code-reviewer agent)
+         → Check each changed file for quality issues
+
+STEP 4: Security Review (security-auditor agent)
+         → Check for vulnerabilities, secrets, auth issues
+
+STEP 5: Consolidate and output report
+```
+
+## Output Format
+
+### Per-file findings:
+
+```
+## src/path/to/file.ts
+
+🔴 [CRITICAL] line 42 — Hardcoded secret in source
+   Problem: API key visible in source code
+   Fix: Move to environment variable, add to .gitignore
+
+🟡 [WARNING] line 87 — Function violates Single Responsibility
+   Problem: processPayment() handles validation + DB + email
+   Fix: Extract into validatePayment(), savePayment(), notifyUser()
+
+🔵 [SUGGESTION] line 103 — Variable name is unclear
+   Problem: `d` is not descriptive
+   Fix: Rename to `durationMs` or `delaySeconds`
+```
+
+### Summary block:
+
+```
+## Review Summary
+Critical: N  |  Warnings: N  |  Suggestions: N
+Recommendation: ✅ APPROVE | ⚠️ APPROVE WITH NOTES | ❌ REQUEST CHANGES
+```
+
+## Severity Guide
+
+| Severity | Symbol | Meaning | Action |
+|----------|--------|---------|--------|
+| Critical | 🔴 | Bug, security, data loss | Must fix before merge |
+| Warning | 🟡 | Quality, SOLID, test gap | Should fix |
+| Suggestion | 🔵 | Style, naming, minor | Consider fixing |

package/ai-config/commands/workflows/work.md

@@ -0,0 +1,75 @@
+---
+name: work
+description: Execute the current plan by creating a git worktree, checking off tasks, and tracking files edited. Reads plan from tasks/<feature-name>/plan.md
+category: workflows
+---
+
+# /workflows:work
+
+Execute the plan for a feature, tracking progress and edited files as you go.
+
+## Usage
+
+```
+/workflows:work <feature-name>
+```
+
+## What It Does
+
+1. **Reads the plan**: Loads `tasks/<feature-name>/plan.md`
+2. **Creates git worktree**: Isolates work in a dedicated branch/worktree
+3. **Executes tasks in order**: Respects task dependencies from the plan
+4. **Tracks progress**: Checks off tasks as they complete
+5. **Records file changes**: Appends to `tasks/<feature-name>/files-edited.md`
+
+## Process
+
+```
+STEP 1: Read tasks/<feature-name>/plan.md
+         → If not found, prompt user to run /workflows:plan first
+
+STEP 2: Create git worktree
+         git worktree add ../worktrees/<feature-name> -b feature/<feature-name>
+
+STEP 3: For each task in the plan (in dependency order):
+         a. Mark task as "in-progress" in the plan
+         b. Implement the task
+         c. Run tests if applicable
+         d. Mark task as "done" ✅ in plan.md
+         e. Append edited files to files-edited.md
+
+STEP 4: When all tasks complete, summarize what was done
+```
+
+## files-edited.md Format
+
+```markdown
+## Files Changed — <feature-name>
+
+### <task-name>
+- `src/path/to/file.ts` — [what changed]
+- `tests/path/to/file.test.ts` — [what changed]
+
+### <next-task>
+- ...
+```
+
+## Git Worktree Commands
+
+```bash
+# Create worktree for the feature
+git worktree add ../worktrees/<feature-name> -b feature/<feature-name>
+
+# List active worktrees
+git worktree list
+
+# Remove worktree after merging
+git worktree remove ../worktrees/<feature-name>
+```
+
+## Rules
+
+- Do not skip tasks unless they're blocked (document why in the plan)
+- Commit after each logical unit of work: `git commit -m "feat: <task-name>"`
+- Update `tasks/<feature-name>/plan.md` task statuses in real time
+- If a task reveals new sub-tasks, add them to the plan before proceeding

package/ai-config/config.yaml

@@ -0,0 +1,18 @@
+# .ai-config/config.yaml
+# Declarative configuration for sync-ai-config.sh
+# Run: ./scripts/sync-ai-config.sh  (no args = reads this file)
+#
+# yaml-language-server: $schema=../schemas/ai-config.schema.json
+
+# Targets to sync when running without arguments
+targets:
+  - claude
+  - opencode
+  - cursor
+  - aider
+  - gemini
+
+# Sync options
+sync:
+  # Claude mode: 'overwrite' or 'merge' (merge appends/updates generated section)
+  claude_mode: overwrite

package/ai-config/hooks/_TEMPLATE.md

@@ -0,0 +1,96 @@
+---
+# =============================================================================
+# HOOK TEMPLATE
+# =============================================================================
+# Hooks se ejecutan en respuesta a eventos del AI CLI
+# =============================================================================
+
+name: mi-hook
+description: Descripción del hook
+
+# Evento que dispara el hook
+# Opciones: PreToolUse, PostToolUse, Stop, SessionStart, SessionEnd
+event: PreToolUse
+
+# Filtrar por herramientas específicas (opcional)
+# Si no se especifica, aplica a todas
+tools:
+  - Bash
+  - Write
+
+# Filtrar por patrón en el contenido (opcional)
+match_pattern: "rm -rf|drop table|delete from"
+
+# Acción: block | warn | log | execute
+action: block
+
+metadata:
+  author: tu-usuario
+  version: "1.0"
+---
+
+# [Nombre del Hook]
+
+> [Descripción de una línea]
+
+## Propósito
+
+[Qué hace este hook y por qué existe]
+
+## Evento
+
+- **Trigger:** [PreToolUse | PostToolUse | Stop | etc.]
+- **Herramientas:** [Lista de herramientas o "todas"]
+- **Condición:** [Cuándo se activa]
+
+## Lógica
+
+```
+SI [condición]
+ENTONCES [acción]
+SINO [alternativa]
+```
+
+## Implementación
+
+### Para Claude Code
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "command": "echo 'Validating...'"
+      }
+    ]
+  }
+}
+```
+
+### Para OpenCode
+
+```yaml
+hooks:
+  pre_tool_use:
+    - tool: Bash
+      action: validate
+```
+
+## Ejemplos
+
+### Ejemplo 1: Hook activa
+
+**Contexto:**
+```
+[Descripción del contexto]
+```
+
+**Resultado:**
+```
+[Qué hace el hook]
+```
+
+## Notas
+
+[Consideraciones adicionales]

package/ai-config/hooks/block-dangerous-commands.md

@@ -0,0 +1,75 @@
+---
+name: block-dangerous-commands
+description: Bloquea comandos peligrosos antes de ejecutar
+event: PreToolUse
+tools:
+  - Bash
+match_pattern: "rm -rf /|rm -rf ~|drop database|truncate table|:(){ :|:& };:|mkfs|dd if=|> /dev/sd|chmod -R 777 /|curl.*| bash|wget.*| sh"
+action: block
+metadata:
+  author: project-starter-framework
+  version: "1.0"
+---
+
+# Block Dangerous Commands Hook
+
+> Previene ejecución de comandos potencialmente destructivos.
+
+## Propósito
+
+Interceptar comandos de Bash que podrían causar daño irreversible al sistema o datos.
+
+## Comandos Bloqueados
+
+| Patrón | Riesgo |
+|--------|--------|
+| `rm -rf /` | Borrar sistema completo |
+| `rm -rf ~` | Borrar home directory |
+| `drop database` | Eliminar base de datos |
+| `truncate table` | Vaciar tablas |
+| `:(){ :|:& };:` | Fork bomb |
+| `mkfs` | Formatear disco |
+| `dd if=` | Escritura directa a disco |
+| `> /dev/sd*` | Sobrescribir disco |
+| `chmod -R 777 /` | Permisos inseguros |
+| `curl \| bash` | Ejecución remota |
+| `wget \| sh` | Ejecución remota |
+
+## Comportamiento
+
+1. **Detecta** comando peligroso en input de Bash
+2. **Bloquea** ejecución
+3. **Notifica** al usuario con explicación
+4. **Sugiere** alternativa segura si existe
+
+## Implementación Claude Code
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '$TOOL_INPUT' | grep -qE 'rm -rf /|rm -rf ~|drop database' && echo 'BLOCKED: Dangerous command detected' && exit 1 || exit 0"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Excepciones
+
+Si necesitás ejecutar un comando bloqueado legítimamente:
+
+1. Revisar el comando manualmente
+2. Usar `--no-verify` o equivalente
+3. Documentar la razón
+
+## Notas
+
+Este hook es una capa de seguridad adicional, no reemplaza el sentido común.

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

@@ -0,0 +1,90 @@
+---
+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

@@ -0,0 +1,73 @@
+---
+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).