javi-forge 0.1.0

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

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

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

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

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

@@ -0,0 +1,102 @@
+---
+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`.

package/ai-config/hooks/task-artifact.md

@@ -0,0 +1,114 @@
+---
+name: task-artifact
+description: Creates a structured task directory with blank artifact files at session start. Directory is organized by domain, date, and task slug.
+event: SessionStart
+action: execute
+
+metadata:
+  author: project-starter-framework
+  version: "1.0"
+  updated: "2026-02"
+---
+
+# Task Artifact Hook
+
+> Scaffolds a task workspace directory at the start of each session.
+
+## Purpose
+
+Automatically creates a `tasks/<domain>/<YYYY-MM-DD>/<task-slug>/` directory structure
+with blank artifact files, so every session has a consistent place to capture research,
+plans, file changes, and verification steps.
+
+## Evento
+
+- **Trigger:** SessionStart
+- **Action:** execute
+- **Condition:** When a session begins with a clear task or feature in mind
+
+## Domain Detection
+
+The `<domain>` is inferred from keywords in the first user message:
+
+| Keywords | Domain |
+|----------|--------|
+| `git`, `commit`, `branch`, `merge`, `rebase` | `git` |
+| `test`, `spec`, `coverage`, `mock`, `TDD` | `testing` |
+| `feature`, `implement`, `build`, `create`, `add` | `development` |
+| `bug`, `fix`, `error`, `broken`, `debug` | `bugfix` |
+| `refactor`, `clean`, `extract`, `simplify` | `refactoring` |
+| `deploy`, `CI`, `pipeline`, `docker`, `k8s` | `devops` |
+| `security`, `vulnerability`, `auth`, `CVE` | `security` |
+| `docs`, `README`, `documentation`, `guide` | `docs` |
+| *(default)* | `general` |
+
+## Directory Structure Created
+
+```
+tasks/
+└── <domain>/
+    └── <YYYY-MM-DD>/
+        └── <task-slug>/
+            ├── research.md
+            ├── plan.md
+            ├── files-edited.md
+            └── verification.md
+```
+
+## Lógica
+
+```
+SI first message contains task keywords
+ENTONCES infer domain and task-slug from message
+  CREATE tasks/<domain>/<YYYY-MM-DD>/<task-slug>/
+  CREATE research.md with ## Research header
+  CREATE plan.md with ## Plan header
+  CREATE files-edited.md with ## Files Changed header
+  CREATE verification.md with checklist
+SINO skip (no task directory needed for questions/exploration)
+```
+
+## Implementación
+
+### Para Claude Code
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": ".*",
+        "command": "bash .ai-config/scripts/task-artifact.sh \"$CLAUDE_SESSION_FIRST_MESSAGE\""
+      }
+    ]
+  }
+}
+```
+
+### Script: .ai-config/scripts/task-artifact.sh
+
+```bash
+#!/bin/bash
+# Usage: task-artifact.sh "<first message>"
+DOMAIN=$(echo "$1" | grep -qiE "git|commit|branch|merge" && echo "git" || \
+         echo "$1" | grep -qiE "test|spec|coverage|mock|TDD" && echo "testing" || \
+         echo "$1" | grep -qiE "bug|fix|error|broken|debug" && echo "bugfix" || \
+         echo "$1" | grep -qiE "refactor|clean|extract" && echo "refactoring" || \
+         echo "$1" | grep -qiE "deploy|CI|pipeline|docker" && echo "devops" || \
+         echo "development")
+
+DATE=$(date +%Y-%m-%d)
+SLUG=$(echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | cut -c1-40)
+DIR="tasks/$DOMAIN/$DATE/$SLUG"
+
+mkdir -p "$DIR"
+echo -e "## Research\n\n_Add findings here_" > "$DIR/research.md"
+echo -e "## Plan\n\n_Add steps here_" > "$DIR/plan.md"
+echo -e "## Files Changed\n\n_Auto-populated_" > "$DIR/files-edited.md"
+echo -e "## Verification Checklist\n\n- [ ] Tests pass\n- [ ] No regressions\n- [ ] Docs updated" > "$DIR/verification.md"
+echo "📁 Task workspace: $DIR"
+```
+
+## Template Files
+
+See `tasks/_TEMPLATE/` for the canonical blank file templates.

package/ai-config/hooks/validate-workflow.md

@@ -0,0 +1,100 @@
+---
+name: validate-workflow
+description: Validates GitHub Actions workflow YAML files after writing or editing. Checks syntax and required keys.
+event: PostToolUse
+tools:
+  - Write
+  - Edit
+match_pattern: "\\.github/workflows/.*\\.yml"
+action: execute
+metadata:
+  author: project-starter-framework
+  version: "1.0"
+  updated: "2026-02"
+---
+
+# Validate Workflow Hook
+
+> Automatically validates GitHub Actions workflow files after every write or edit.
+
+## Purpose
+
+Catch YAML syntax errors and missing required keys in workflow files immediately after saving, before a broken workflow gets pushed to the repository.
+
+## Checks Performed
+
+| Check | Rule |
+|-------|------|
+| YAML syntax | Valid YAML parseable by Python's `yaml.safe_load` |
+| `on:` trigger | Workflow must define at least one trigger |
+| `jobs:` key | Workflow must define at least one job |
+
+## Behavior
+
+1. **Triggers** after Write or Edit on any `.github/workflows/*.yml` file
+2. **Validates** YAML syntax using `python3 -c "import yaml,sys; yaml.safe_load(open('$FILE'))"`
+3. **Checks** for `on:` and `jobs:` keys
+4. **Reports** any issues with line number if available
+5. **Suggests** local testing tools if validation passes
+
+## Local Testing Suggestion
+
+If validation passes, the hook suggests running the workflow locally:
+
+- **act** — [github.com/nektos/act](https://github.com/nektos/act): `act push --container-architecture linux/amd64`
+- **wrkflw** — lightweight alternative: `wrkflw run`
+
+## Implementation (Claude Code JSON)
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"\nimport sys, os, json\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', ''))\nimport re\nif not re.search(r'\\.github/workflows/.*\\.yml$', file_path):\n    sys.exit(0)\nimport yaml\ntry:\n    with open(file_path) as f:\n        content = yaml.safe_load(f)\nexcept yaml.YAMLError as e:\n    print('WORKFLOW SYNTAX ERROR: ' + str(e))\n    sys.exit(1)\nexcept FileNotFoundError:\n    sys.exit(0)\nwarnings = []\nif not content:\n    warnings.append('Workflow file is empty')\nelse:\n    if 'on' not in content and True not in content:\n        warnings.append('Missing required key: on (trigger definition)')\n    if 'jobs' not in content:\n        warnings.append('Missing required key: jobs')\nif warnings:\n    print('WORKFLOW VALIDATION WARNINGS for ' + file_path + ':')\n    for w in warnings:\n        print('  - ' + w)\nelse:\n    print('Workflow YAML valid: ' + file_path)\n    print('Tip: Test locally with:')\n    print('  act push --container-architecture linux/amd64')\n    print('  # or: wrkflw run')\nsys.exit(0)\n\""
+          }
+        ]
+      },
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"\nimport sys, os, json\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', ''))\nimport re\nif not re.search(r'\\.github/workflows/.*\\.yml$', file_path):\n    sys.exit(0)\nimport yaml\ntry:\n    with open(file_path) as f:\n        content = yaml.safe_load(f)\nexcept yaml.YAMLError as e:\n    print('WORKFLOW SYNTAX ERROR: ' + str(e))\n    sys.exit(1)\nexcept FileNotFoundError:\n    sys.exit(0)\nwarnings = []\nif not content:\n    warnings.append('Workflow file is empty')\nelse:\n    if 'on' not in content and True not in content:\n        warnings.append('Missing required key: on (trigger definition)')\n    if 'jobs' not in content:\n        warnings.append('Missing required key: jobs')\nif warnings:\n    print('WORKFLOW VALIDATION WARNINGS for ' + file_path + ':')\n    for w in warnings:\n        print('  - ' + w)\nelse:\n    print('Workflow YAML valid: ' + file_path)\n    print('Tip: Test locally with: act push --container-architecture linux/amd64')\nsys.exit(0)\n\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Examples
+
+### ✅ Valid Workflow
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+```
+→ Output: `Workflow YAML valid: .github/workflows/ci.yml`
+
+### ❌ Invalid — Missing `jobs:`
+```yaml
+name: CI
+on: [push]
+# jobs: missing!
+```
+→ Output: `WORKFLOW VALIDATION WARNINGS: Missing required key: jobs`
+
+## Notes
+
+For local testing, install `act`: `brew install act` (macOS) or `apt install act` (Ubuntu via snap). See [nektos/act](https://github.com/nektos/act) for full docs.