@cristiancorreau/forge 3.1.0 → 3.2.1

package/assets/core/skills/laravel-verify/SKILL.md

@@ -0,0 +1,462 @@
+# Skill: laravel-verify
+
+Loop de verificación reproducible para Laravel antes de commit/PR: formato (Pint),
+análisis estático (Larastan/PHPStan), tests con coverage (Pest), audit de dependencias
+y checks de configuración. Devuelve **PASA / FALLA** con acciones concretas.
+
+Triggers: /laravel-verify, "verificar antes de commit", "loop de verificación laravel",
+"chequeo previo a PR", "pint phpstan pest", "está listo para mergear", "correr el quality gate".
+
+---
+
+## Cuándo usar este skill
+
+- Antes de cada `git commit` o de abrir un PR en un proyecto Laravel.
+- Como gate de CI (GitHub Actions) en `pull_request` y `push`.
+- Como hook de pre-commit local para evitar romper `main`.
+- Cuando el `forge-quality-reviewer` pide la corrida completa de verificación.
+
+Requisitos del proyecto (Laravel / PHP 8.3+):
+
+```bash
+composer require --dev laravel/pint larastan/larastan pestphp/pest \
+  pestphp/pest-plugin-laravel
+```
+
+Coverage de Pest necesita `xdebug` (modo `coverage`) o `pcov`. En CI usa `pcov` por
+velocidad. El orden del loop es **rápido → costoso**: primero falla lo barato (Pint),
+después lo caro (Pest), para acortar el ciclo de feedback.
+
+---
+
+## El loop, de un vistazo
+
+| # | Paso | Comando | Falla si… |
+|---|------|---------|-----------|
+| 1 | Formato | `./vendor/bin/pint --test` | hay archivos sin formatear |
+| 2 | Estático | `./vendor/bin/phpstan analyse` | hay errores fuera del baseline |
+| 3 | Tests + coverage | `./vendor/bin/pest --coverage --min=80` | falla un test o coverage < 80% |
+| 4 | Dependencias | `composer audit` | hay CVE en dependencias |
+| 5 | Config | `php artisan about` + asserts | `APP_DEBUG=true` o `APP_ENV` mal seteado |
+
+Regla de oro: **no se hace commit con ningún paso en rojo.** Cada paso de abajo trae el
+comando exacto, qué mirar y la acción concreta para arreglarlo.
+
+---
+
+## Paso 1 — Pint (formato de código)
+
+Pint es el formateador oficial (envoltorio sobre PHP-CS-Fixer). En el loop se corre en
+modo `--test` (no modifica nada, solo reporta). El autofix queda explícito.
+
+```bash
+# Verifica sin modificar — esto es lo que corre el gate
+./vendor/bin/pint --test
+
+# Solo archivos con cambios (git working tree) — ideal para pre-commit, mucho más rápido
+./vendor/bin/pint --test --dirty
+```
+
+**Acción si FALLA:** corre el autofix y vuelve a verificar.
+
+```bash
+./vendor/bin/pint --dirty   # formatea solo lo modificado
+./vendor/bin/pint           # formatea todo el proyecto
+./vendor/bin/pint --test    # confirma que ya pasa
+```
+
+Define el preset en `pint.json` en la raíz del proyecto (recomendado: `laravel`):
+
+```json
+{
+    "preset": "laravel",
+    "rules": {
+        "declare_strict_types": true,
+        "ordered_imports": { "sort_algorithm": "alpha" },
+        "no_unused_imports": true
+    },
+    "exclude": ["bootstrap/cache", "storage"]
+}
+```
+
+En CI puedes emitir un reporte parseable con `--format=checkstyle --report=pint-report.xml`
+(útil con `cs2pr` para anotar el PR); localmente deja el output por defecto, que lista cada
+archivo con su diff.
+
+---
+
+## Paso 2 — Larastan / PHPStan (análisis estático)
+
+Larastan extiende PHPStan con reglas conscientes de Laravel (entiende `Model::find()`,
+facades, relaciones Eloquent, etc.). Se instala como extensión y PHPStan la autodescubre.
+
+`phpstan.neon` en la raíz:
+
+```neon
+includes:
+    - vendor/larastan/larastan/extension.neon
+    - phpstan-baseline.neon
+
+parameters:
+    level: 6
+    paths:
+        - app/
+        - bootstrap/app.php
+        - config/
+        - database/
+        - routes/
+    # Regla de Larastan que valida nombres de propiedades de modelo en argumentos tipados.
+    checkModelProperties: true
+    # PHPStan 2.x (que usa Larastan 3) ya NO tiene checkMissingIterableValueType.
+    # Para tolerar arrays sin value-type se ignora por identificador de error:
+    ignoreErrors:
+        - identifier: missingType.iterableValue
+```
+
+Corrida del gate:
+
+```bash
+./vendor/bin/phpstan analyse                 # usa phpstan.neon
+./vendor/bin/phpstan analyse --memory-limit=2G
+```
+
+### Subida gradual de nivel (0 → 10)
+
+No subas a nivel 9 de golpe en un código existente: te llenas de errores. Estrategia:
+
+```bash
+# Empieza donde el proyecto esté limpio (típico: 5 o 6 en código Laravel maduro)
+./vendor/bin/phpstan analyse --level=6
+
+# Cuando level N pasa sin errores, sube a N+1 y arregla lo nuevo:
+./vendor/bin/phpstan analyse --level=7
+```
+
+Metas razonables en Laravel: **level 6** como mínimo de merge, **level 8** como objetivo
+del proyecto. Niveles 9–10 (chequeo estricto de `mixed`/null) solo si el equipo se compromete.
+
+### Baseline — congelar la deuda existente
+
+El baseline registra los errores actuales para que el gate solo falle ante errores **nuevos**.
+Es la herramienta que permite subir de nivel sin bloquear el desarrollo.
+
+```bash
+# Genera/regenera el baseline con los errores actuales del nivel configurado
+./vendor/bin/phpstan analyse --generate-baseline
+```
+
+Esto crea `phpstan-baseline.neon` (ya incluido en `phpstan.neon` arriba). Reglas:
+
+- **Regenera el baseline solo cuando bajas deuda**, nunca para silenciar un error nuevo
+  que acabas de introducir — ese hay que arreglarlo.
+- Haz commit del baseline. Forma parte del contrato del repo.
+- Revisa el diff del baseline en cada PR: si **crece**, alguien metió deuda; si **encoge**,
+  se pagó deuda (bien).
+
+**Acción si FALLA:** lee el error, corrige el tipo/lógica. Si es un falso positivo legítimo
+(p. ej. un magic method de un paquete), usa `@phpstan-ignore-next-line` con comentario del
+porqué, o ignora ese identificador de error en `phpstan.neon` — pero esto es la excepción,
+no el patrón.
+
+> Las versiones recientes de Laravel usan estructura slim (sin `app/Http/Kernel.php` ni
+> `app/Console/Kernel.php`); verifica leyendo `bootstrap/app.php`, donde vive la config de
+> middleware (`->withMiddleware(...)`). Incluye `bootstrap/app.php` en `paths` por eso.
+> **No** referencies los Kernel legacy si tu proyecto ya usa la estructura slim.
+
+---
+
+## Paso 3 — Pest con coverage mínimo
+
+Pest 3 es el runner de tests. El gate exige un piso de coverage del 80%.
+
+```bash
+# Tests + coverage con piso del 80% — falla si baja
+./vendor/bin/pest --coverage --min=80
+
+# En paralelo (más rápido en CI con varios cores)
+./vendor/bin/pest --parallel --coverage --min=80
+
+# Solo lo afectado durante desarrollo (no en el gate final)
+./vendor/bin/pest --dirty
+./vendor/bin/pest --filter="UserTest"
+```
+
+Habilita el driver de coverage. En CI con `pcov`:
+
+```bash
+php -d pcov.enabled=1 ./vendor/bin/pest --coverage --min=80
+```
+
+Configura el filtro de coverage en `phpunit.xml` (así el `--min` y el reporte miden solo el
+código de la app, no vendor ni config):
+
+```xml
+<source>
+    <include>
+        <directory>app</directory>
+    </include>
+    <exclude>
+        <directory>app/Console</directory>
+    </exclude>
+</source>
+```
+
+Ejemplo de test Pest 3 sobre una API Resource de Laravel (`toResource()` + JSON:API). El
+método `toResource()` de auto-discovery existe en las versiones recientes; verifica que esté
+disponible en tu versión instalada:
+
+```php
+<?php
+
+use App\Models\Post;
+
+it('serializa el post via auto-discovery de resource', function () {
+    $post = Post::factory()->create(['title' => 'Hola']);
+
+    // toResource() autodescubre App\Http\Resources\PostResource en Laravel reciente
+    $payload = $post->toResource()->toArray(request());
+
+    expect($payload['title'])->toBe('Hola');
+});
+
+it('lista posts sin lazy loading', function () {
+    Post::factory()->count(3)->for(\App\Models\User::factory(), 'author')->create();
+
+    // preventLazyLoading activo en testing: si la relación no está eager-loaded, lanza
+    $this->getJson('/api/posts?include=author')
+        ->assertOk()
+        ->assertJsonCount(3, 'data');
+});
+```
+
+**Acción si FALLA:**
+
+- *Test roto:* lee el assert, corrige el código (no el test, salvo que el test esté mal).
+- *Coverage < 80%:* identifica qué falta cubrir y agrega tests sobre el código nuevo.
+
+  ```bash
+  # Reporte HTML para ver línea por línea qué quedó sin cubrir
+  ./vendor/bin/pest --coverage --coverage-html=coverage-report
+  ```
+
+  Sube el coverage cubriendo el **código que tocaste** en este cambio — no inflando con
+  tests triviales de getters. El piso es un guardrail, no una meta a gamear.
+
+---
+
+## Paso 4 — composer audit (vulnerabilidades en dependencias)
+
+```bash
+composer audit                       # falla con exit code ≠ 0 si hay CVE
+composer audit --format=json         # output parseable para CI
+composer audit --no-dev              # solo dependencias de producción
+```
+
+**Acción si FALLA:**
+
+```bash
+composer why vulnerable/package      # ver quién la trae
+composer update vulnerable/package   # subir a versión parcheada
+composer update vulnerable/package --with-dependencies
+```
+
+Si no hay parche disponible aún y el riesgo es aceptable para esta entrega, documenta la
+excepción en el PR (paquete, CVE, por qué se acepta, fecha de revisión) — no la silencies
+sin dejar registro. El audit corre también en CI: una dependencia nueva con CVE bloquea el
+merge.
+
+---
+
+## Paso 5 — Checks de configuración (`php artisan about` + asserts)
+
+`php artisan about` resume el estado del entorno. El gate verifica que la config sea sana
+**antes** de mergear, para que no se filtre `APP_DEBUG=true` a producción.
+
+```bash
+php artisan about                            # resumen completo legible
+php artisan about --only=environment         # solo el bloque de entorno
+php artisan about --json                      # output parseable para asserts en CI
+```
+
+Asserts concretos del gate (fallan el loop si no se cumplen):
+
+```bash
+# APP_DEBUG debe estar en false fuera de local (config cacheada o env real)
+php artisan tinker --execute="exit(config('app.debug') === false ? 0 : 1);" \
+  || { echo 'FALLA: APP_DEBUG=true'; exit 1; }
+
+# APP_KEY debe existir
+php artisan tinker --execute="exit(config('app.key') ? 0 : 1);" \
+  || { echo 'FALLA: APP_KEY vacía — corre php artisan key:generate'; exit 1; }
+```
+
+Checks adicionales útiles antes de PR:
+
+```bash
+php artisan config:clear     # evita asserts contra config cacheada vieja
+php artisan route:list        # confirma que las rutas registran sin error
+php artisan migrate:status    # no quedan migraciones pendientes sin aplicar en test
+```
+
+**Acción si FALLA:** ajusta `.env` / `.env.example`, corre `php artisan key:generate` si
+falta la key, y confirma que `APP_ENV` y `APP_DEBUG` correspondan al entorno
+(`local` → debug ok; `production`/`staging` → `APP_DEBUG=false`).
+
+---
+
+## Salida del loop — formato PASA / FALLA
+
+El skill termina con un veredicto único y accionable. Plantilla de reporte:
+
+```
+laravel-verify — VEREDICTO: FALLA
+
+  [✓] Pint            — formato OK
+  [✗] PHPStan (lvl 6) — 2 errores nuevos (fuera de baseline)
+  [✓] Pest            — 84 passed, coverage 86% (min 80%)
+  [✓] composer audit  — sin CVE
+  [✓] Config          — APP_DEBUG=false, APP_KEY presente
+
+  ACCIONES:
+   1. app/Http/Controllers/PostController.php:42 — método undefined en relación.
+      → Eager-load `author` o corrige el tipo del retorno.
+   2. app/Models/Post.php:18 — cast legacy detectado.
+      → Migra de `protected $casts` a `protected function casts(): array`.
+
+  No hacer commit hasta que todos los pasos estén en verde.
+```
+
+Si todos pasan: `VEREDICTO: PASA — listo para commit/PR.`
+
+---
+
+## Cableado en CI — GitHub Actions
+
+`.github/workflows/verify.yml`:
+
+```yaml
+name: laravel-verify
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: '8.3'
+          coverage: pcov
+          tools: composer:v2
+
+      - name: Install dependencies
+        run: composer install --prefer-dist --no-interaction --no-progress
+
+      - name: Prepare environment
+        run: |
+          cp .env.example .env
+          php artisan key:generate
+
+      # Paso 1 — Pint
+      - name: Pint (formato)
+        run: ./vendor/bin/pint --test
+
+      # Paso 2 — PHPStan / Larastan
+      - name: PHPStan (estático)
+        run: ./vendor/bin/phpstan analyse --no-progress --memory-limit=2G
+
+      # Paso 3 — Pest + coverage
+      - name: Pest (tests + coverage)
+        run: ./vendor/bin/pest --parallel --coverage --min=80
+
+      # Paso 4 — Dependencias
+      - name: composer audit
+        run: composer audit
+
+      # Paso 5 — Config
+      - name: Config checks
+        run: |
+          php artisan about --only=environment
+          php artisan tinker --execute="exit(config('app.debug') === false ? 0 : 1);"
+```
+
+Notas:
+
+- `pcov` es más rápido que Xdebug para coverage en CI.
+- Cada paso es un step independiente: el log de Actions muestra exactamente cuál falló.
+- Si necesitas base de datos para Pest, agrega un servicio `postgres`. Las versiones recientes
+  de Laravel con pgvector usan `Schema::ensureVectorExtensionExists()`; usa la imagen
+  `pgvector/pgvector` y verifica que el helper esté disponible en tu versión instalada.
+
+---
+
+## Cableado como pre-commit (local)
+
+Engancha el loop al hook de Git para que falle **antes** de crear el commit. Usa `--dirty`
+en Pint y Pest para que sea rápido sobre solo lo modificado.
+
+`.git/hooks/pre-commit` (o gestiónalo con un gestor de hooks versionado):
+
+```bash
+#!/usr/bin/env bash
+set -e
+
+echo "→ Pint (dirty)..."
+./vendor/bin/pint --test --dirty
+
+echo "→ PHPStan..."
+./vendor/bin/phpstan analyse --no-progress
+
+echo "→ Pest (dirty)..."
+./vendor/bin/pest --dirty
+
+echo "✓ laravel-verify OK — commit permitido."
+```
+
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+Recomendación: el pre-commit corre el subconjunto rápido (`--dirty`, sin `composer audit`
+ni coverage completo) para no entorpecer el flujo; el gate **completo** (coverage 80%,
+audit, config checks) corre en CI. Así local es ágil y CI es la autoridad final.
+
+Para versionar el hook en el repo (sin depender del `.git/hooks` de cada quien), usa un
+gestor de hooks como `captainhook/captainhook`:
+
+```bash
+composer require --dev captainhook/captainhook   # hooks versionados en captainhook.json
+```
+
+---
+
+## Qué NO hacer
+
+- **No** silencies un error nuevo de PHPStan regenerando el baseline — el baseline solo
+  congela deuda **vieja**; lo nuevo se arregla.
+- **No** bajes `--min=80` para que pase el coverage — cubre el código que escribiste.
+- **No** referencies `app/Http/Kernel.php` ni `app/Console/Kernel.php` si tu proyecto usa la
+  estructura slim de Laravel: ahí no existen. La config de middleware vive en
+  `bootstrap/app.php`; verifica leyendo ese archivo.
+- **No** uses `protected $casts` ni pares `getXAttribute()/setXAttribute()` — PHPStan +
+  el preset de Pint te lo van a marcar; usa `casts(): array` y `Attribute::make()`.
+- **No** uses `checkMissingIterableValueType` en `phpstan.neon`: lo removió PHPStan 2.x.
+  Ignora ese caso por identificador (`missingType.iterableValue`) si hace falta.
+- **No** hagas commit con `APP_DEBUG=true` apuntando a entornos no-locales.
+- **No** dejes `composer audit` en rojo sin un motivo documentado en el PR.
+
+---
+
+## Relación con otros skills
+
+- `new-feature` invoca este skill como gate final antes de cerrar la feature.
+- El `forge-quality-reviewer` lo corre como parte de su review de PR.
+- Es complementario a `laravel-security`: este verifica calidad/regresión, aquel verifica
+  seguridad de endpoints. Corre ambos antes de mergear rutas protegidas.
+- No depende de otros skills para ejecutarse (es standalone).

package/assets/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "forge",
-  "version": "3.1.0",
+  "version": "3.2.1",
   "description": "Agentic development framework for Claude Code, OpenCode, Codex and Kiro",
   "license": "Apache-2.0",
   "repository": "https://github.com/cristiancorreau/forge",
@@ -133,7 +133,7 @@
     {
       "id": "laravel",
       "stack": "Laravel + PHP",
-      "agents": ["api-engineer", "fullstack-engineer", "migration-specialist"]
+      "agents": ["api-engineer", "fullstack-engineer", "migration-specialist", "laravel-specialist", "laravel-test-engineer"]
     },
     {
       "id": "nestjs",
@@ -197,6 +197,31 @@
       "dir": "core/skills/db-migrate",
       "description": "Database migration orchestration"
     },
+    {
+      "id": "laravel-eloquent",
+      "dir": "core/skills/laravel-eloquent",
+      "description": "Eloquent (Laravel 13): relationships, eager loading, N+1, casts, scopes, pgvector"
+    },
+    {
+      "id": "laravel-mcp",
+      "dir": "core/skills/laravel-mcp",
+      "description": "Laravel 13 agents/MCP: Boost, laravel/mcp servers, AI SDK, embeddings/pgvector"
+    },
+    {
+      "id": "laravel-pest",
+      "dir": "core/skills/laravel-pest",
+      "description": "TDD with Pest 3 (and PHPUnit): factories, fakes, HTTP tests, coverage"
+    },
+    {
+      "id": "laravel-security",
+      "dir": "core/skills/laravel-security",
+      "description": "Laravel security: auth, policies, Form Requests, CSRF, rate limiting, secure deploy"
+    },
+    {
+      "id": "laravel-verify",
+      "dir": "core/skills/laravel-verify",
+      "description": "Laravel verification loop: Pint, Larastan/PHPStan, Pest coverage, composer audit"
+    },
     {
       "id": "local2prod",
       "dir": "core/skills/local2prod",

package/assets/profiles/astro/agents/frontend-engineer.md

@@ -14,6 +14,8 @@ Construís sitios web con Astro: desde sitios estáticos puros hasta apps con SS
 usando islands architecture. Tu scope es `src/` y `public/`. No tocás infraestructura
 ni backend fuera de las integraciones de Astro.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`package.json`/`package-lock.json`, `astro.config.*`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas en `src/`, archivos de configuración/bootstrap como `astro.config.mjs`, paquetes presentes como `astro` e integraciones, y sus versiones). Consulta la documentación oficial de tu versión instalada (deriva la URL del major detectado) y el CHANGELOG/UPGRADE del paquete antes de afirmar capacidades específicas de versión (adaptadores, Content Layer, directivas de islands, helpers de imágenes).
+
 ## Stack
 
 - **Framework:** Astro (última versión estable)

package/assets/profiles/django/agents/api-engineer.md

@@ -12,6 +12,8 @@ last_verified: "2026-06"
 
 Implementás el backend del proyecto. Tu scope es `apps/` y `config/` (estructura Two Scoops of Django). Leé el `CLAUDE.md` del proyecto antes de empezar.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`pyproject.toml` / `requirements.txt`, y el `manage.py`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas como `config/settings/`, archivos de configuración/bootstrap como `manage.py`, `asgi.py`/`wsgi.py`, paquetes presentes y sus versiones — Django, DRF, Django Ninja, Celery). Consulta la documentación oficial de tu versión instalada (deriva la URL del major detectado, p. ej. `https://docs.djangoproject.com/en/<major.minor>/`) y el CHANGELOG/UPGRADE del paquete (release notes de Django y de DRF/Ninja) antes de afirmar capacidades específicas de versión.
+
 ## Stack
 
 - **Runtime:** Python 3.11+

package/assets/profiles/expo/agents/mobile-engineer.md

@@ -14,6 +14,8 @@ Construís la app o SDK móvil del proyecto. Tu scope es el directorio móvil de
 `CLAUDE.md` del proyecto (típicamente `packages/mobile/` o `apps/mobile/`).
 Leé ese archivo antes de empezar.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`package.json`/`package-lock.json` y `app.json`/`app.config.*`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de configuración/bootstrap como `app.json`/`app.config.ts`, paquetes presentes y sus versiones —Expo SDK, `react-native`, `expo-router`—). Consulta la documentación oficial de tu versión instalada (deriva la URL del major detectado) y el CHANGELOG/UPGRADE del paquete antes de afirmar capacidades específicas de versión.
+
 ## Stack
 
 - **Framework:** Expo SDK (versión definida en el `CLAUDE.md` del proyecto).

package/assets/profiles/express/agents/api-engineer.md

@@ -13,6 +13,8 @@ last_verified: "2026-06"
 Implementás el backend del proyecto. Tu scope es el directorio de API definido en el `CLAUDE.md`
 del proyecto (típicamente `src/` o `packages/api/`). Leé ese archivo antes de empezar.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`package.json` / `package-lock.json`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de configuración/bootstrap como `tsconfig.json` o el entrypoint del servidor, paquetes presentes en `node_modules` y sus versiones). Consulta la documentación oficial de tu versión instalada de Express, Node.js y el ORM (deriva la URL del major detectado) y el CHANGELOG/UPGRADE del paquete antes de afirmar capacidades específicas de versión.
+
 ## Stack
 
 - **Runtime:** Node.js 20 LTS (o Bun si el proyecto lo especifica).

package/assets/profiles/fastapi/agents/api-engineer.md

@@ -13,6 +13,8 @@ last_verified: "2026-06"
 Implementás el backend del proyecto. Tu scope es el directorio de API definido en el `CLAUDE.md`
 del proyecto (típicamente `app/` o `src/`). Leé ese archivo antes de empezar.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`pyproject.toml` o `requirements.txt`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de configuración/bootstrap como `app/main.py` y `alembic.ini`, paquetes presentes y sus versiones en el entorno o el lockfile). Consulta la documentación oficial de tu versión instalada de FastAPI, SQLAlchemy y Pydantic (deriva la URL del major detectado) y el CHANGELOG/UPGRADE de cada paquete antes de afirmar capacidades específicas de versión.
+
 ## Stack
 
 - **Runtime:** Python 3.11+.

package/assets/profiles/flask/agents/api-engineer.md

@@ -14,6 +14,8 @@ Implementás el backend del proyecto con Flask. Tu scope es el paquete de la apl
 (típicamente `app/` o `src/`) definido en el `CLAUDE.md` del proyecto. Leé ese archivo
 antes de empezar.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`pyproject.toml` / `requirements.txt`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de configuración/bootstrap como `create_app()` y `config.py`, paquetes presentes y sus versiones vía `pip show flask` / `pip freeze`). Consulta la documentación oficial de tu versión instalada (deriva la URL del major detectado) y el CHANGELOG/UPGRADE del paquete antes de afirmar capacidades específicas de versión.
+
 ## Stack
 
 - **Runtime:** Python 3.11+.

package/assets/profiles/flutter/agents/mobile-engineer.md

@@ -1,6 +1,6 @@
 ---
 name: mobile-engineer
-description: "Construye la app móvil del proyecto. Flutter 3 + Dart 3 + Riverpod + go_router. Scope: el directorio lib/ del paquete móvil."
+description: "Construye la app móvil del proyecto. Flutter + Dart 3 + Riverpod + go_router. Scope: el directorio lib/ del paquete móvil."
 model: sonnet
 tools: Read, Grep, Glob, Bash, Edit, Write
 tier: 2
@@ -10,19 +10,21 @@ last_verified: "2026-06"
 
 # Mobile Engineer — Flutter
 
-Construís la app móvil del proyecto con Flutter. Tu scope es el directorio `lib/` del
-paquete móvil (y su `test/`), definido en el `CLAUDE.md` del proyecto. Leé ese archivo
+Construyes la app móvil del proyecto con Flutter. Tu scope es el directorio `lib/` del
+paquete móvil (y su `test/`), definido en el `CLAUDE.md` del proyecto. Lee ese archivo
 antes de empezar para confirmar el approach de state management y de navegación que usa
 el proyecto.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`pubspec.yaml`/`pubspec.lock`, y en su caso `android/build.gradle` o `ios/Podfile`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de bootstrap, paquetes presentes y sus versiones).
+
 ## Stack
 
-- **Framework:** Flutter 3 (canal stable). **Lenguaje:** Dart 3 con null-safety y sound types.
-- **State management:** Riverpod por defecto (`@riverpod` + code-gen). Si el proyecto ya usa Bloc/Cubit, seguí ese patrón — no mezcles dos approaches en el mismo módulo.
+- **Framework:** Flutter (canal stable). **Lenguaje:** Dart 3 con null-safety y sound types.
+- **State management:** Riverpod por defecto (`@riverpod` + code-gen). Si el proyecto ya usa Bloc/Cubit, sigue ese patrón — no mezcles dos approaches en el mismo módulo.
 - **Navegación:** `go_router` (rutas declarativas, deep links). NO usar `Navigator.push` imperativo disperso por la app.
 - **Networking:** `dio` o `http` con un cliente centralizado y manejo de errores tipado. Modelos con `freezed` + `json_serializable`.
 - **Storage seguro:** `flutter_secure_store` (Keychain en iOS, EncryptedSharedPreferences en Android) para tokens/PII. `shared_preferences` solo para datos no sensibles.
-- **Dependencias:** `pub` (`pubspec.yaml`). Fijar versiones; correr `flutter pub get` tras editar.
+- **Dependencias:** `pub` (`pubspec.yaml`). Fija versiones; corre `flutter pub get` tras editar.
 - **Tests:** `flutter test` (widget + unit), `mocktail` para mocks. `integration_test` para flujos E2E.
 - **Lint:** `flutter analyze` con `flutter_lints` (o `very_good_analysis`) en `analysis_options.yaml`.
 
@@ -84,13 +86,13 @@ flutter build apk    # / ios / appbundle # build de release
 ## No hagas
 
 - No mezcles dos soluciones de state management en el mismo proyecto.
-- No uses `setState` para estado compartido entre pantallas — usá el provider/bloc del proyecto.
+- No uses `setState` para estado compartido entre pantallas — usa el provider/bloc del proyecto.
 - No hagas networking ni I/O dentro de `build()`.
-- No uses `dynamic` ni `as` casts sin verificación; mantené el tipado estricto.
-- No commitees archivos generados a mano — regenerá con `build_runner`.
+- No uses `dynamic` ni `as` casts sin verificación; mantén el tipado estricto.
+- No commitees archivos generados a mano — regenera con `build_runner`.
 - No toques `pubspec.yaml`, `android/`, `ios/` ni la firma de la app sin instrucción del orchestrator.
 - No guardes tokens en `shared_preferences` ni los loguees.
-- No implementes sin spec aprobada — pedí al orchestrator que la cree primero.
+- No implementes sin spec aprobada — pide al orchestrator que la cree primero.
 
 ## Forge v2
 

package/assets/profiles/go-gin/agents/api-engineer.md

@@ -13,6 +13,8 @@ last_verified: "2026-06"
 Implementás el backend del proyecto en Go. Tu scope es `internal/` y `cmd/`. Leé el
 `CLAUDE.md` del proyecto antes de empezar.
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`go.mod` / `go.sum`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de configuración/bootstrap como `cmd/api/main.go`, la directiva `go` y los módulos presentes con sus versiones — por ejemplo `github.com/gin-gonic/gin`, `github.com/golang-jwt/jwt`). Consulta la documentación oficial de tu versión instalada (deriva la URL del major detectado, p. ej. `pkg.go.dev/github.com/gin-gonic/gin@<versión>`) y el CHANGELOG/UPGRADE del paquete antes de afirmar capacidades específicas de versión.
+
 ## Stack
 
 - **Lenguaje:** Go 1.21+
@@ -96,4 +98,4 @@ sqlc generate
 - No uses `init()` para lógica de negocio — solo para registro de drivers.
 - No retornes errores de base de datos directos al cliente — mapearlos a errores de dominio.
 - No toques archivos fuera de `internal/` y `cmd/`.
-- No implementes sin spec aprobada.
+- No implementes sin spec aprobada.

package/assets/profiles/hono-drizzle/agents/api-engineer.md

@@ -15,6 +15,8 @@ del proyecto (típicamente `packages/api/` o `src/api/`). Leé ese archivo antes
 
 ## Stack
 
+> **No asumas una versión mayor.** Antes de escribir código, lee el manifiesto del proyecto (`package.json` / `package-lock.json`) y contrasta los patrones que vas a usar contra el código realmente instalado (estructura de carpetas, archivos de configuración/bootstrap como `drizzle.config.ts` y el entrypoint de Hono, paquetes presentes y sus versiones de `hono`, `drizzle-orm`, `drizzle-kit` y `zod`). Consulta la documentación oficial de tu versión instalada (deriva la URL del major detectado) y el CHANGELOG/UPGRADE del paquete antes de afirmar capacidades específicas de versión.
+
 - **Runtime:** Bun en dev, Node 22 LTS en prod (el código debe correr en ambos).
 - **Framework HTTP:** Hono.
 - **ORM:** Drizzle. NO usar Prisma, TypeORM ni query builders ad-hoc.