lacasoft · Oct 26, 2026 · Oct 26, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,18 @@ Formato basado en [Keep a Changelog](https://keepachangelog.com/) y [SemVer](htt
 
 ## [No publicado]
 
+## [3.2.0] - 2026-10-27
+
+### Added
+- **Ciclos de trabajo con verificador (loop engineering): skill `/loop-task` y helper `loop.cjs`.** Para tareas largas con un final comprobable, en vez de pedirle cada paso a Claude se define un ciclo: objetivo, verificador, tope de turnos y revisión independiente. Es la práctica que Addy Osmani llamó *loop engineering*, hecha con piezas nativas de Claude Code (hook `Stop`, subagentes, worktrees), sin nada de terceros.
+  - **Verificador determinista**: al final de cada turno, el hook `Stop` corre el comando del ciclo. Si falla, bloquea el cierre y le devuelve el error a Claude; Claude no decide cuándo terminó.
+  - **Solo comandos de verificación**: como el hook corre fuera de los permisos de Claude Code, el verificador solo admite test, lint, typecheck o build del proyecto encadenados con `&&` (sin `;`, `|`, redirecciones ni subshells).
+  - **Sin trampas**: el contrato vive en `.claude/loop/state.json`, que solo escribe el helper (Claude Code protege `.claude/` y los hooks `pre-edit`/`pre-bash` del kit también); si cambia el script de `package.json` que usa el verificador, la puerta lo rechaza.
+  - **Línea base**: si el verificador ya pasa antes de empezar, el ciclo no arranca (`--allow-passing` para refactors que deben mantenerse en verde).
+  - **Quien hace no aprueba**: en verde, el ciclo exige pasar el agente `reviewer` por el diff y escribir un "Resumen para la persona" en `.loop/PROGRESS.md` antes de cerrar.
+  - **Tope y aislamiento**: 10 turnos por defecto (máximo 50) y solo en una rama o worktree propio, nunca en `main`/`master`/`develop`. El ciclo no hace commit, push ni merge.
+  - La skill explica cuándo **no** usar un ciclo y cómo combinarlo con `/goal` cuando el final requiere juicio. 32 tests nuevos (144 en total).
+
 ## [3.1.0] - 2026-10-26
 
 ### Added

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -85,7 +85,7 @@ Borra el archivo de `shared/.claude/` sin más: en `--update`, el instalador ret
 
 - SemVer en `package.json` + entrada en `CHANGELOG.md`.
 - Como se distribuye por `npx github:`, los proyectos toman la rama por defecto: **`master` siempre debe estar verde** (CI en cada PR). Usa ramas `feat/…`, `fix/…` y PRs.
-- Para fijar versiones en un proyecto concreto: `npx github:lacasoft/dev-starter-kit#v3.1.0`.
+- Para fijar versiones en un proyecto concreto: `npx github:lacasoft/dev-starter-kit#v3.2.0`.
 
 ## Probar localmente
 

diff --git a/README.md b/README.md
@@ -14,9 +14,9 @@ Configuración `.claude` unificada para backend, frontend, mobile y blockchain.
 │   ├── CLAUDE.base.md          # baseline universal (comportamiento, agentes, memoria, seguridad, calidad)
 │   ├── settings.json           # hooks + permisos + statusLine
 │   ├── agents/                 # 14 agentes (5 core + 9 especialistas) — ver "Agentes incluidos"
-│   ├── skills/                 # 18 skills (flujo + contexto + ingeniería + seguridad) — ver "Skills incluidas"
+│   ├── skills/                 # 19 skills (flujo + contexto + ingeniería + seguridad) — ver "Skills incluidas"
 │   ├── commands/               # /swarm, /kit:status
-│   ├── helpers/                # hook-handler, statusline
+│   ├── helpers/                # hook-handler, loop, statusline
 │   └── templates/              # PROJECT.template.md (definición del proyecto)
 ├── stacks/                     # OVERLAYS: 13 stacks seleccionables + un `_common` por categoría
 │   ├── backend/{_common,nestjs,express,fastapi,django,php,spring,dotnet}
@@ -34,7 +34,7 @@ Dentro de **cualquier proyecto** (nuevo o heredado), sin clonar nada:
 ```bash
 npx -y github:lacasoft/dev-starter-kit              # interactivo
 npx -y github:lacasoft/dev-starter-kit --yes --all  # desatendido (todo)
-npx -y github:lacasoft/dev-starter-kit#v3.1.0       # fijar una versión (recomendado)
+npx -y github:lacasoft/dev-starter-kit#v3.2.0       # fijar una versión (recomendado)
 ```
 
 Toma siempre la última versión de `master` (o el tag indicado). Repo **público (MIT)**.
@@ -121,7 +121,7 @@ Además, el kit instala por stack agentes/skills externos curados (`frontend-dev
 
 ## Skills incluidas (capa base)
 
-**Flujo de trabajo**: `tdd` · `diagnose` · `grill-me` · `handoff` · `swarm-orchestration` · `verification` · `code-review-response` · `git-worktrees`
+**Flujo de trabajo**: `tdd` · `diagnose` · `grill-me` · `handoff` · `swarm-orchestration` · `verification` · `code-review-response` · `git-worktrees` · `loop-task`
 **Contexto y memoria**: `project-context` (rellena `CLAUDE.project.md` a partir del repo real) · `adr` (registro de decisiones en `docs/adr/`)
 **Ingeniería/entrega**: `ci-cd` · `performance-profiling` · `migration` · `monorepo` · `release` · `ship-gate` · `iac`
 **Seguridad**: `owasp-review` (revisión contra OWASP Top 10:2025, ASVS 5.0 y CWE; LLM y agentes 2026)
@@ -234,6 +234,31 @@ Las listas completas, qué buscar en cada categoría y las fuentes están en
 `shared/.claude/skills/owasp-review/referencia.md`. Cuando un estándar publique edición nueva, se
 actualiza ahí y en esta tabla.
 
+## Ciclos de trabajo con verificador (loop engineering)
+
+Para tareas largas con un final comprobable (implementar un plan hasta que pasen sus tests, migrar
+un módulo hasta que compile, vaciar una lista de errores de lint), en vez de pedirle cada paso a
+Claude diseñas el **ciclo** que trabaja solo. Es la práctica que Addy Osmani llamó
+[*loop engineering*](https://addyosmani.com/blog/loop-engineering/), implementada con piezas
+nativas de Claude Code: un hook `Stop`, subagentes y worktrees. No se instala nada de terceros.
+
+```bash
+git switch -c feat/migracion-billing        # nunca en la rama principal
+> /loop-task migrar src/billing al API v2 — verificador: npm run typecheck && npm test — tope: 15 turnos
+```
+
+| Pieza | Qué hace |
+| --- | --- |
+| **Verificador determinista** | Al final de cada turno, el hook `Stop` corre tu comando. Si falla, Claude sigue con el error a la vista; Claude no decide cuándo terminó. |
+| **Solo comandos de verificación** | El verificador solo admite test, lint, typecheck o build del proyecto encadenados con `&&`: el hook no ejecuta shell arbitrario. |
+| **No se puede hacer trampa** | El estado del ciclo no se edita (hooks `pre-edit` y `pre-bash`), y si cambia el script de `package.json` que usa el verificador, la puerta lo rechaza. |
+| **Línea base** | Si el verificador ya pasa antes de empezar, el ciclo no arranca: no mide lo que quieres lograr. |
+| **Quien hace no aprueba** | En verde, el ciclo exige pasar el agente `reviewer` por el diff y un *Resumen para la persona* antes de cerrar. |
+| **Tope** | 10 turnos por defecto (máximo 50). Al agotarse, se detiene y deja el informe en `.loop/PROGRESS.md`. |
+
+El ciclo no hace commit, push ni merge: el resultado se revisa como cualquier PR. Para finales que
+requieren juicio y no un comando, la skill explica cómo combinarlo con `/goal` de Claude Code.
+
 ## Orquestación multiagente (nativa)
 
 Todo con herramientas de Claude Code: el tool `Agent` para lanzar subagentes en paralelo, los
@@ -336,7 +361,7 @@ recibir la copia vieja. La solución buena es la misma que exige la baseline §6
 versión** — y de paso hace la instalación reproducible:
 
 ```bash
-npx -y github:lacasoft/dev-starter-kit#v3.1.0 --update --yes    # por tag
+npx -y github:lacasoft/dev-starter-kit#v3.2.0 --update --yes    # por tag
 npx -y github:lacasoft/dev-starter-kit#<commit> --update --yes  # por commit (el SHA del tag)
 ```
 
@@ -357,4 +382,4 @@ Repo **público (MIT)** distribuido por `npx github:` → la rama **`master` deb
   (dry-run) y en un monorepo multi-stack, en cada PR. La lista sale de `scripts/stacks.cjs`, que la deriva de `install.js`.
 - **Cómo añadir** agentes, skills, stacks o externos: ver [CONTRIBUTING.md](CONTRIBUTING.md).
 - **Versionado**: SemVer en `package.json` + `CHANGELOG.md`, con tag anotado por versión
-  (`v3.1.0`). Instala siempre pineando (`#v3.1.0`): es reproducible y evita la cache de npx.
+  (`v3.2.0`). Instala siempre pineando (`#v3.2.0`): es reproducible y evita la cache de npx.
diff --git a/install.js b/install.js
@@ -456,7 +456,7 @@ function stackRules(stacks) {
 // env, y el `claude-flow init` que traía sus propios hooks) y ya no lo integra; dejarlo haría que
 // cada sesión siguiera llamando a un runtime que nadie mantiene. Lo retirado se informa.
 const isKitHook = (g) =>
-  Array.isArray(g && g.hooks) && g.hooks.length > 0 && g.hooks.every((h) => /hook-handler\.cjs|auto-memory-hook\.mjs/.test((h && h.command) || ""));
+  Array.isArray(g && g.hooks) && g.hooks.length > 0 && g.hooks.every((h) => /hook-handler\.cjs|auto-memory-hook\.mjs|loop\.cjs/.test((h && h.command) || ""));
 const RUFLO = /claude[-_]?flow|ruflo|ruv-swarm|flow-nexus/i;
 // Permisos que versiones anteriores del kit escribían y que ya no se usan. La unión de permisos
 // los arrastraría para siempre. Read(./.env.*) bloqueaba también .env.example: lo sustituyen
@@ -648,7 +648,8 @@ function rufloLeftovers(kitFiles = {}) {
 // La memoria de agente con scope `project` (.claude/agent-memory/) se versiona a propósito: es
 // conocimiento del equipo. La `local` y CLAUDE.local.md son personales. .claude/memory/ es de la
 // memoria propia que tuvo el kit hasta la 2.x: se sigue ignorando para no versionar restos.
-const GITIGNORE = [".claude/memory/", ".claude/agent-memory-local/", "CLAUDE.local.md", ".claude.backup.*", ".env", ".env.*"];
+// Ciclo en curso (skill loop-task): .claude/loop/ es el contrato y .loop/ el progreso. De trabajo, no de equipo.
+const GITIGNORE = [".claude/memory/", ".claude/agent-memory-local/", ".claude/loop/", ".loop/", "CLAUDE.local.md", ".claude.backup.*", ".env", ".env.*"];
 // Los archivos de ejemplo de env van versionados (la baseline los exige), pero ".env.*" los
 // captura. Git aplica la última regla que casa, así que las negaciones van SIEMPRE después.
 const GITIGNORE_KEEP = ["!.env.example", "!.env.sample", "!.env.template"];

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@lacasoft/dev-starter-kit",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "private": true,
   "description": "Base .claude coherente (agentes, skills, helpers, orquestación multiagente nativa) instalable en cualquier proyecto lacasoft (backend/frontend/mobile/blockchain).",
   "bin": {

diff --git a/shared/.claude/CLAUDE.base.md b/shared/.claude/CLAUDE.base.md
@@ -59,6 +59,7 @@ La orquestación multiagente usa solo herramientas nativas (tool `Agent`, agente
 - **Protocolo por tarea**: (1) recuperar contexto (CLAUDE.project.md, ADRs, memoria) → (2) planificar →
   (3) ejecutar en paralelo lo independiente → (4) verificar → (5) guardar lo duradero donde corresponde (ver §3.1).
 - Tras lanzar trabajo en background o subagentes: **STOP**. No hagas polling; espera el resultado.
+- **Tareas largas con final verificable** (un plan, una migración, una tanda de tests rotos): ciclo con verificador determinista, tope de turnos y revisión independiente (skill `loop-task`), en una rama propia.
 
 ### 3.1 Memoria y contexto del proyecto
 

diff --git a/shared/.claude/helpers/hook-handler.cjs b/shared/.claude/helpers/hook-handler.cjs
@@ -129,6 +129,7 @@ const BASH_DENY = [
   [new RegExp(`${C}(?:rm|mv|chown|chmod)\\s[^\\n;]*\\s/(?:etc|usr|bin|sbin|boot|lib|var|System)(?:/|\\s|$)`), "modifica rutas críticas del sistema"],
   [/\b(?:cat|cp|scp|tar|curl|base64)\b[^\n;]*(?:~|\$HOME)\/\.(?:ssh|aws|gnupg)\b/, "lee o copia credenciales del usuario (~/.ssh, ~/.aws, ~/.gnupg)"],
   [/\bgit\s+(?:commit|push)\b[^\n;]*--no-verify\b/, "salta los hooks de calidad y el escáner de secretos (--no-verify)"],
+  [/^(?!\s*node\s+\.claude\/helpers\/loop\.cjs\b).*\.claude\/loop\/state\.json/, "toca el estado del ciclo (.claude/loop/state.json), que solo escribe loop.cjs: el verificador no se negocia; usa loop.cjs status o stop"],
 ];
 
 // Paquetes que un comando de instalación añadiría. null = no es una instalación;
@@ -266,6 +267,9 @@ switch (action) {
         `Posible secreto (${hit}) en el contenido a escribir${file ? ` en ${file}` : ""}. No hardcodees secretos: usa variables de entorno / secret manager. Si es un placeholder/ejemplo, hazlo evidente (p.ej. prefijo your_/example_).`
       );
     }
+    if (/(^|\/)\.claude\/loop\/state\.json$/.test(file)) {
+      denyPreTool("El estado del ciclo (.claude/loop/state.json) solo lo escribe loop.cjs: ni el verificador ni el contador de turnos se editan a mano. Usa `node .claude/helpers/loop.cjs status` o `stop`.");
+    }
     if (/(^|\/)\.env(\.|$)/.test(file)) {
       addContext(`Editando un archivo de entorno (${file}): no versiones secretos reales; usa .env.example con placeholders.`);
     }