feat: add built-in playbooks for various stacks and enhance skill management

- Introduced built-in playbooks for Node.js, Python, React, and Spring Boot to streamline common tasks and improve user guidance.
- Enhanced the skill management system by allowing the extension of skills from built-in playbooks based on the active focus.
- Added documentation for creating new skills, hooks, tools, and modifying the harness to improve developer experience.
- Implemented a new focus pack addition process to support new stacks and languages.

Author: davidpp09

skills/agregar-focus-pack.md

@@ -0,0 +1,21 @@
+---
+name: agregar un focus pack de un stack nuevo
+focus: dpx
+cuando: "USAR cuando: agregar soporte para un stack/lenguaje nuevo (un focus pack: Go, Kotlin, Vue, etc.). NO usar para skills sueltos ni para tocar un pack que ya existe."
+---
+Un focus pack es el conocimiento de dominio que se inyecta al system prompt según
+el stack. Para añadir uno (p.ej. `go`):
+
+1. **Archivo** `src/focus/go.rs` con `pub const SKILLS: &str = "..."` — el dominio.
+   Incluye SIEMPRE un bloque de VERSIONES ACTUALES (autoritativo, junio 2026) que
+   gane sobre la memoria del modelo; no inventes números de versión.
+2. **Declara el módulo**: `mod go;` en `src/focus/mod.rs` (junto a los otros).
+3. **Catálogo**: añade su `Focus { id, name, tagline }` en `catalog()` (el `id` es
+   lo que el usuario elige, p.ej. `"go"`).
+4. **Inyección**: añade el caso a `domain_skills()` (`"go" => Some(go::SKILLS)`).
+5. **Detección** (opcional): enséñale a `fs::detect_stack` a reconocer el stack por
+   sus archivos raíz (p.ej. `go.mod`).
+6. **Built-in playbooks** (opcional pero recomendado): añade `pub const PLAYBOOKS`
+   al pack y su caso en `focus::builtin_playbooks` (ver skill "crear un skill").
+7. **Verifica** clippy estricto + tests; reinstala con `/actualizar` (el prompt se
+   compila en el binario).

skills/agregar-hook.md

@@ -0,0 +1,18 @@
+---
+name: agregar un evento de hook del ciclo de vida
+focus: dpx
+cuando: "USAR cuando: agregar un hook o evento del ciclo de vida (OnSessionStart, PreToolUse y similares) que dispare comandos del usuario. NO usar para tools del agente ni comandos del REPL."
+---
+Los hooks viven en `src/cli/hooks.rs` y se configuran en `.dpx/hooks.toml`. Para
+añadir un evento nuevo:
+
+1. **Variante del enum**: añade el caso a `enum HookEvent` en `cli/hooks.rs`.
+2. **Mapeo string ↔ enum**: añádelo en `HookEvent::parse` (string → variante) y en
+   la conversión inversa (variante → string). Deben coincidir EXACTO con el valor
+   que el usuario escribe en `hooks.toml`.
+3. **Disparo**: llama a `run_hooks(&hooks, &HookEvent::TuEvento, ...)` en el punto
+   del ciclo de vida donde debe dispararse (mira cómo se dispara `OnSessionStart`
+   al arrancar la sesión en `src/cli/chat.rs`).
+4. **Doc**: actualiza el comentario de cabecera de `hooks.rs` (lista de eventos) y
+   el README si menciona los hooks.
+5. **Test** de `parse`/round-trip del nuevo evento + clippy estricto + tests.

skills/agregar-tool.md

@@ -0,0 +1,20 @@
+---
+name: agregar una tool/acción del agente
+focus: dpx
+cuando: "USAR cuando: agregar una acción o tool nueva que dpx pueda emitir (un bloque dpx:algo que lee o muta el repo). NO usar para comandos del REPL (/x) ni paneles."
+---
+Las acciones de dpx son bloques con marcador (`dpx:write path=`, `dpx:read path=`,
+`dpx:run`, `dpx:edit`, `dpx:delete`, `dpx:search`). Para añadir una:
+
+1. **Parser** en `src/fs/mod.rs`: una función `parse_<x>_marker`/`is_<x>_fence`
+   estilo las existentes (`parse_path_marker`, `is_run_fence`).
+2. **Guard de stripping**: añade tu marcador a la lista de `on_fence`/`on_next` en
+   `fs/mod.rs` (la que limpia los bloques de acción del texto visible) — si no, tu
+   bloque se imprime crudo.
+3. **Frontera lectura/mutación** (CRÍTICO): si la tool LEE, va libre. Si MUTA
+   (write/edit/delete/run), cabléala por la puerta de confirmación en
+   `src/cli/chat.rs` (`process_writes`/`process_edits`/`process_deletes`/`confirm_run`)
+   y respeta los guards (shrink, big-rewrite, sandbox). NUNCA un atajo que mute en silencio.
+4. **Doctrina**: documenta el marcador en el prompt de herramientas (`SHARED_TOOLS`
+   en `src/focus/mod.rs`) para que dpx sepa que existe.
+5. **Test** del parser (camino feliz + borde) y verifica con clippy estricto + tests.

skills/crear-skill.md

@@ -0,0 +1,35 @@
+---
+name: crear un skill / playbook para dpx
+focus: dpx
+cuando: "USAR cuando: crear, escribir o agregar un skill o playbook nuevo (curado o built-in de un stack: React, Python, Node, etc.), o cuando falte un playbook para una tarea que se repite."
+---
+Un skill es un PLAYBOOK A→B: le dice a dpx los pasos exactos de una tarea que se
+repite, para que no explore a ciegas ni dé algo genérico. Hay dos tipos:
+
+## A) Curado local (`skills/*.md`) — para ESTE repo
+Crea `skills/<nombre-kebab>.md` con frontmatter + cuerpo:
+```
+---
+name: <título corto y reconocible>
+focus: <id del stack o "dpx">
+cuando: "USAR cuando: <frases gatillo concretas>. NO usar para <contraejemplo>."
+---
+1. <paso A→B con la RUTA/función real>
+2. ...
+```
+
+## B) Built-in por stack (viene en dpx, para los USUARIOS)
+Añade una tupla al `pub const PLAYBOOKS` del focus pack (p.ej. `src/focus/react.rs`):
+`("nombre", "USAR cuando: …", "1. paso\n2. paso")`. Si el pack aún no tiene
+`PLAYBOOKS`, créalo (copia la forma del de `spring_boot.rs`) y añade su caso a
+`focus::builtin_playbooks` en `src/focus/mod.rs`. Reinstala para que tome efecto.
+
+## Reglas de un BUEN skill (esto es lo que evita lo genérico)
+- El `cuando` ES el gatillo: ponlo INSISTENTE, con frases y palabras reales que el
+  usuario diría (dpx tiende a sub-disparar los skills). Incluye un "NO usar para…".
+- Cuerpo CORTO y ESPECÍFICO: rutas, funciones, anotaciones, comandos REALES del
+  stack — nada de "crea una clase y añade lógica". Si no es específico, no sirve.
+- **Investiga antes de escribir** un stack que no domines: confirma las VERSIONES y
+  convenciones ACTUALES (busca en la web si hace falta; alinéate con el bloque de
+  versiones del focus pack). NUNCA inventes versiones ni APIs.
+- Un solo playbook por tarea repetible; pasos numerados que terminen en "verifica".

skills/escribir-tests-dpx.md

@@ -0,0 +1,22 @@
+---
+name: escribir tests en el repo de dpx
+focus: dpx
+cuando: "USAR cuando: escribir o arreglar un test de dpx, testear el loop del chat, mockear el modelo, o probar estado global (atómicos)."
+---
+Convenciones de testabilidad de dpx que DEBES respetar (romperlas hace tests
+frágiles o imposibles):
+
+1. **Costura del loop**: `run_turn` toma `&impl TurnBrain` (no `&Mentor`) y
+   `ask: &mut dyn FnMut(&str) -> Option<String>` (no el editor directo). En los
+   tests usa `FakeMentor` para guionar las `ChatReply` y un `ask` que da respuestas
+   fijas. Si cambias la firma del loop, MANTÉN esta costura.
+2. **Estado global = atómicos** (`ui::CANCEL`, `BUDGET`, el ledger de `token.rs`, el
+   `State` de `checkpoint.rs`): NUNCA los toques desde un test (carreras entre
+   tests). Prueba la lógica en una INSTANCIA LOCAL — copia el patrón de los tests de
+   `token.rs`/`checkpoint.rs`.
+3. **Cada lógica nueva lleva test** en su mismo módulo: camino feliz + un borde.
+   Funciones de parsing/formato son las más fáciles y valiosas de cubrir.
+4. **Verifica de verdad**: `cargo clippy --all-targets -- -D warnings` Y
+   `cargo test`. clippy/test NO cazan bugs visuales — razona la salida real.
+5. Tests temporales que crean archivos: usa rutas en `std::env::temp_dir()` con el
+   pid, y límpialas al final.

skills/modificar-harness.md

@@ -0,0 +1,21 @@
+---
+name: modificar el harness (doctrina/prompt de dpx)
+focus: dpx
+cuando: "USAR cuando: agregar o cambiar una regla, lección o doctrina del comportamiento de dpx (el system prompt / focus pack), o corregir una falla recurrente del agente."
+---
+El "harness" es lo que define cómo se comporta dpx. Va compilado en el binario, así
+que un cambio NO surte efecto hasta reinstalar.
+
+1. **¿Dónde va la regla?**
+   - Doctrina GENERAL (aplica a todos los stacks): `src/focus/mod.rs` (las secciones
+     de método: economía de rondas, cambio mínimo, errores recurrentes…).
+   - Lección ESPECÍFICA de trabajar sobre dpx: `src/focus/dpx.rs`.
+   - Conocimiento de un stack: el focus pack correspondiente (`spring_boot.rs`, etc.).
+2. **Sé concreto y corto**: una regla imperativa con el porqué y el síntoma real que
+   evita ("pasó de verdad: …"). Las reglas vagas se ignoran.
+3. **No dupliques**: busca si ya existe una regla parecida y refínala en vez de
+   añadir una quinta que diga lo mismo.
+4. **Reinstala**: `cargo install --path . --force` (o el usuario corre `/actualizar`).
+   OJO: falla si hay un dpx corriendo (binario en uso, os error 5 en Windows).
+5. **Valida** con el banco de pruebas (`eval/run-eval.sh`): corre la tarea que picaba
+   la falla y confirma que ahora la caza.

src/agent_skill.rs

@@ -36,8 +36,23 @@ pub struct AgentSkill {
     pub vector: Vec<f32>,
 }
 
-/// Catálogo de skills curados cargado de `skills/*.md`. De solo lectura: no se
-/// auto-persiste nada (los `.md` se editan a mano).
+impl AgentSkill {
+    /// Crea un skill EMPOTRADO (built-in) desde literales de un focus pack. Estos
+    /// vienen DENTRO de dpx (por stack), así un usuario obtiene playbooks expertos
+    /// sin escribir nada. El vector se llena perezosamente, igual que los curados.
+    pub fn builtin(name: &str, when: &str, body: &str, focus: &str) -> Self {
+        Self {
+            name: name.to_string(),
+            body: body.to_string(),
+            focus: focus.to_string(),
+            when: when.to_string(),
+            vector: Vec::new(),
+        }
+    }
+}
+
+/// Catálogo de skills cargado de `skills/*.md` (curados) + los empotrados del
+/// stack activo. De solo lectura: no se auto-persiste nada.
 pub struct SkillBook {
     skills: Vec<AgentSkill>,
 }
@@ -64,6 +79,16 @@ impl SkillBook {
         self.skills.iter().collect()
     }
 
+    /// Añade skills (p.ej. los empotrados del focus activo). No duplica por nombre
+    /// — un skill curado de `skills/` con el mismo nombre gana sobre el built-in.
+    pub fn extend(&mut self, more: Vec<AgentSkill>) {
+        for s in more {
+            if !self.skills.iter().any(|e| e.name == s.name) {
+                self.skills.push(s);
+            }
+        }
+    }
+
     /// Embebe (vectoriza) los skills que aún no tienen vector, usando `embed`.
     /// Se llama perezosamente la primera vez que se busca, cuando el motor de
     /// embeddings ya está cargado — así no encarecemos el arranque.
@@ -204,6 +229,21 @@ mod tests {
         assert_eq!(hits[0].name, "endpoint");
     }
 
+    #[test]
+    fn extend_no_duplica_y_el_curado_gana() {
+        // Un curado de skills/ con el mismo nombre debe ganar sobre el built-in.
+        let mut book = SkillBook {
+            skills: vec![AgentSkill::builtin("crear endpoint", "w", "curado", "spring-boot")],
+        };
+        book.extend(vec![
+            AgentSkill::builtin("crear endpoint", "w", "builtin", "spring-boot"), // mismo nombre → ignorado
+            AgentSkill::builtin("otro", "w", "nuevo", "spring-boot"),             // nombre nuevo → entra
+        ]);
+        assert_eq!(book.len(), 2, "no duplica por nombre");
+        let endpoint = book.ranked().into_iter().find(|s| s.name == "crear endpoint").unwrap();
+        assert_eq!(endpoint.body, "curado", "el primero (curado) gana");
+    }
+
     #[test]
     fn embed_pending_llena_solo_los_vacios() {
         let mut book = SkillBook { skills: Vec::new() };

src/cli/chat.rs

@@ -152,9 +152,17 @@ pub async fn run(
     let mut mem_store = crate::memory::MemoryStore::load(store.dpx_dir());
     let mut embedder: Option<crate::memory::Embedder> = None;
 
-    // Skills CURADOS del proyecto (playbooks `skills/*.md`). Como la memoria, se
-    // cargan barato (solo leer los .md); el embedder solo si de verdad se usan.
+    // Skills del proyecto: CURADOS (`skills/*.md`, locales) + EMPOTRADOS del stack
+    // activo (vienen en dpx). Carga barata; el embedder solo si de verdad se usan.
     let mut skillbook = crate::agent_skill::SkillBook::from_dir(&cwd.join("skills"));
+    skillbook.extend(
+        crate::focus::builtin_playbooks(focus_id.as_deref())
+            .iter()
+            .map(|(n, w, b)| {
+                crate::agent_skill::AgentSkill::builtin(n, w, b, focus_id.as_deref().unwrap_or(""))
+            })
+            .collect(),
+    );
 
     loop {
         // De vuelta en el prompt: la pestaña muestra dpx en reposo.

src/focus/mod.rs

@@ -191,6 +191,20 @@ fn domain_skills(focus_id: &str) -> Option<&'static str> {
     }
 }
 
+/// Playbooks EMPOTRADOS (built-in) del stack activo: `(nombre, cuándo, pasos)`.
+/// Vienen DENTRO de dpx, así un usuario obtiene playbooks A→B expertos sin
+/// escribir skills. Se cargan junto a los curados de `skills/` (el CLI los
+/// recupera por similitud antes del turno). Vacío = sin playbooks para ese stack.
+pub fn builtin_playbooks(focus_id: Option<&str>) -> &'static [(&'static str, &'static str, &'static str)] {
+    match focus_id {
+        Some("spring-boot") => spring_boot::PLAYBOOKS,
+        Some("react") => react::PLAYBOOKS,
+        Some("node") => node::PLAYBOOKS,
+        Some("python") => python::PLAYBOOKS,
+        _ => &[],
+    }
+}
+
 /// Devuelve el nombre legible de un focus pack (para banners).
 /// `None` = mentor general, sin enfoque de stack.
 pub fn display_name(focus_id: Option<&str>) -> &str {