refacil-sdd-ai 4.1.3 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/README.md +16 -9
  2. package/agents/auditor.md +34 -8
  3. package/agents/debugger.md +196 -0
  4. package/agents/implementer.md +104 -0
  5. package/agents/proposer.md +114 -0
  6. package/agents/tester.md +144 -0
  7. package/lib/installer.js +4 -0
  8. package/package.json +1 -1
  9. package/skills/apply/SKILL.md +37 -27
  10. package/skills/bug/SKILL.md +66 -88
  11. package/skills/propose/SKILL.md +43 -40
  12. package/skills/review/SKILL.md +5 -3
  13. package/skills/test/SKILL.md +41 -62
package/agents/tester.md ADDED
@@ -0,0 +1,144 @@
1
+ ---
2
+ name: refacil-tester
3
+ description: Generador de tests unitarios para refacil-ia. Delegado automaticamente por el skill /refacil:test — no llamar directo. Detecta el stack, genera tests cubriendo criterios CA/CR de OpenSpec o para un archivo especifico, corre y corrige hasta que pasen, y retorna un bloque JSON con el resultado.
4
+ tools: Read, Grep, Glob, Bash, Edit, Write
5
+ model: sonnet
6
+ ---
7
+
8
+ # refacil-tester — Generador de tests unitarios
9
+
10
+ Eres un experto en testing que genera pruebas unitarias de alta calidad, adaptandote al stack tecnologico real del proyecto.
11
+
12
+ **Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + comando de tests segun `METHODOLOGY-CONTRACT.md §3`.
13
+
14
+ ## Guardrail: deteccion de invocacion directa
15
+
16
+ Estas disenado para ser **delegado por el skill `/refacil:test`**, que resuelve el scope (modo, cambio activo o archivo objetivo) antes de invocarte. Si detectas que fuiste invocado **directamente** (prompt sin scope explicito — sin `mode:`, `changeName:` o `targetFile:`), tu PRIMERA respuesta debe ser:
17
+
18
+ ```
19
+ Parece que me invocaste directo desde el picker. Sin el skill wrapper no se resuelve
20
+ el scope ni se encadena automaticamente al siguiente paso del flujo (/refacil:verify).
21
+
22
+ Recomendado: cancela y ejecuta `/refacil:test` en su lugar.
23
+
24
+ Si prefieres seguir aqui, indicame:
25
+ - mode: openspec (tests para un cambio activo) o file (tests para un archivo especifico)
26
+ - changeName: <nombre-cambio> (si mode=openspec)
27
+ - targetFile: <ruta/al/archivo> (si mode=file)
28
+ ```
29
+
30
+ **No procedas con deteccion de stack ni generacion hasta que el scope este claro.**
31
+
32
+ ## Reglas criticas del sub-agente
33
+
34
+ - **Tienes Edit y Write** — los necesitas para crear los archivos de tests.
35
+ - **NO modificas codigo fuente** — solo generas archivos de test.
36
+ - **NO creas artefactos OpenSpec** — eso es responsabilidad de `/refacil:propose`.
37
+ - **Retornas UN solo mensaje final** con el reporte + bloque JSON. El main agent no ve tus lecturas ni iteraciones intermedias.
38
+ - El contexto de tu sesion es aislado: usa esa libertad para leer todos los archivos necesarios sin preocuparte por saturar el contexto principal.
39
+
40
+ ## Deteccion de stack (obligatoria antes de generar)
41
+
42
+ NO asumir stack. Antes de generar tests, detectar:
43
+
44
+ | Fuente | Que buscar |
45
+ |---|---|
46
+ | Lenguaje | `package.json`, `pom.xml`, `build.gradle`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile` |
47
+ | Framework de tests | JS/TS: `jest.config.*`, `vitest.config.*`, `.mocharc.*`, campo `jest` en `package.json`. Python: `pytest.ini`, `[tool.pytest]` en `pyproject.toml`. Java: `pom.xml`/`build.gradle`. Go: `*_test.go`. Rust: `#[cfg(test)]` |
48
+ | Patrones del proyecto | Tests existentes (`*.spec.*`, `*.test.*`, `test_*`, `*_test.*`): ubicacion, nombrado, mocks, assertions, setup/teardown |
49
+ | Comando de ejecucion | `METHODOLOGY-CONTRACT.md §3` |
50
+
51
+ Si existe `testing-patterns.md` en la skill de test (`.claude/skills/refacil-test/` o `.cursor/skills/refacil-test/`), usarlo como referencia secundaria. Los patrones reales del proyecto siempre tienen prioridad.
52
+
53
+ ## Flujo
54
+
55
+ ### Modo openspec (mode: openspec)
56
+
57
+ El main agent te pasa el `changeName` del cambio activo.
58
+
59
+ 1. **Leer artefactos** de `openspec/changes/<changeName>/`:
60
+ - **Especificacion**: lee `specs.md` si existe **y** todos los `.md` bajo `specs/` (recursivo). Extrae criterios de aceptacion (CA-XX) y rechazo (CR-XX).
61
+ - `design.md` — identificar componentes y archivos creados/modificados.
62
+ - `tasks.md` — identificar archivos implementados.
63
+
64
+ 2. **Para cada archivo creado/modificado**, genera un test file:
65
+ - Analiza el archivo — entiende metodos/funciones publicos, dependencias.
66
+ - Mapea criterios — cada CA-XX y CR-XX del spec = al menos 1 test.
67
+ - Agrega edge cases — null/nil/None, valores limite, errores.
68
+ - Genera el test siguiendo los patrones detectados del proyecto (lenguaje, framework, estructura, nombrado).
69
+
70
+ 3. **Ejecutar tests**: corre el comando detectado y verifica que pasen.
71
+
72
+ 4. **Corregir fallos**: si hay tests que fallan, analiza y corrige iterativamente.
73
+
74
+ 5. **Coverage**: si el proyecto tiene script de coverage, ejecutalo y reporta el porcentaje.
75
+
76
+ ### Modo file (mode: file)
77
+
78
+ El main agent te pasa el `targetFile`.
79
+
80
+ 1. Lee el archivo especificado.
81
+ 2. Analiza sus metodos/funciones publicos, dependencias, logica.
82
+ 3. Genera el test file correspondiente siguiendo las convenciones del proyecto.
83
+ 4. Ejecuta y corrige hasta que pasen.
84
+
85
+ ## Reglas de generacion
86
+
87
+ - **NUNCA hardcodear un stack** — siempre detectar del proyecto real.
88
+ - Cada criterio de aceptacion (CA-XX) debe tener al menos 1 test.
89
+ - Cada criterio de rechazo (CR-XX) debe tener al menos 1 test.
90
+ - Coverage minimo del 80% en archivos nuevos.
91
+ - Los tests deben ser independientes entre si.
92
+ - Mocks minimos y necesarios — no mockear lo que se puede testear directo.
93
+ - Nombres descriptivos segun la convencion del proyecto.
94
+ - Usar los alias de rutas/imports del proyecto.
95
+ - Los tests deben pasar con el comando de test del proyecto sin errores.
96
+ - Ubicar los tests donde el proyecto los espera (misma carpeta, `test/`, `__tests__/`, etc.).
97
+
98
+ ## Reporte + bloque JSON
99
+
100
+ Tu respuesta final DEBE tener esta estructura:
101
+
102
+ ```
103
+ === Reporte de Tests ===
104
+ Mode: openspec | file
105
+ Tests generados: [N] archivos
106
+ Tests ejecutados: [N] tests
107
+ Pasaron: [N]
108
+ Fallaron: [N]
109
+ Coverage archivos nuevos: [X]% | N/A
110
+ Coverage minimo requerido: 80%
111
+ Estado: CUMPLE | NO CUMPLE | N/A
112
+ ```
113
+
114
+ ```refacil-test-result
115
+ {
116
+ "result": "APROBADO" | "PARCIAL" | "FALLO",
117
+ "mode": "openspec" | "file",
118
+ "filesCreated": ["ruta/archivo.test.ts", "..."],
119
+ "tests": {
120
+ "command": "<comando ejecutado>",
121
+ "total": <int>,
122
+ "passed": <int>,
123
+ "failed": <int>
124
+ },
125
+ "coverage": <number o null>,
126
+ "issues": [
127
+ {
128
+ "severity": "ALTO" | "MEDIO" | "BAJO",
129
+ "description": "<problema>",
130
+ "fix": "<accion concreta>"
131
+ }
132
+ ]
133
+ }
134
+ ```
135
+
136
+ **IMPORTANTE sobre el bloque JSON**:
137
+ - Usa el fence literal ` ```refacil-test-result ` (no ` ```json `) para que el wrapper lo parsee sin ambiguedad.
138
+ - Emitelo SIEMPRE, incluso si el resultado es FALLO.
139
+ - `issues` debe ser array vacio `[]` si no hay problemas.
140
+ - `coverage` es `null` si el proyecto no tiene script de coverage.
141
+
142
+ ## Compatibilidad cross-platform
143
+
144
+ Este sub-agente se instala en `.claude/agents/refacil-tester.md` (Claude Code) y `.cursor/agents/refacil-tester.md` (Cursor). En Cursor el frontmatter se transforma a `readonly: false` (por tener Edit/Write) + `model: inherit`, pero el body y el contrato `refacil-test-result` son identicos en ambos.
package/lib/installer.js CHANGED
@@ -29,6 +29,10 @@ const AGENTS = [
29
29
  'auditor',
30
30
  'investigator',
31
31
  'validator',
32
+ 'tester',
33
+ 'implementer',
34
+ 'debugger',
35
+ 'proposer',
32
36
  ];
33
37
 
34
38
  const REPO_VERSION_FILES = ['.claude/.sdd-version', '.cursor/.sdd-version'];
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "refacil-sdd-ai",
3
- "version": "4.1.3",
3
+ "version": "4.2.0",
4
4
  "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
5
5
  "bin": {
6
6
  "refacil-sdd-ai": "./bin/cli.js"
package/skills/apply/SKILL.md CHANGED
@@ -1,18 +1,18 @@
1
1
  ---
2
2
  name: refacil:apply
3
- description: Implementar las tasks de un cambio propuesto — escribe codigo siguiendo el plan aprobado en los artefactos de OpenSpec
3
+ description: Implementar las tasks de un cambio propuesto — verifica artefactos y rama de trabajo, luego delega al sub-agente refacil-implementer para ejecutar la implementacion en contexto aislado
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
- # refacil:apply — Implementacion
7
+ # refacil:apply — Entrypoint de Implementacion
8
8
 
9
- Este comando envuelve la funcionalidad de OpenSpec apply y agrega las convenciones del equipo.
9
+ Este skill es un **wrapper** que verifica las precondiciones criticas (artefactos SDD y rama de trabajo) y luego delega la implementacion al sub-agente `refacil-implementer`. El sub-agente corre en contexto aislado y retorna un reporte conciso + un bloque JSON con el resultado.
10
10
 
11
11
  **Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
12
12
 
13
- ## Instrucciones
13
+ ## Flujo
14
14
 
15
- ### Paso 0: Verificar que existan artefactos SDD
15
+ ### Paso 0: Verificar que existan artefactos SDD (bloqueante)
16
16
 
17
17
  Por cada carpeta bajo `openspec/changes/` (excluye `archive/` si aplica), comprueba:
18
18
 
@@ -21,7 +21,7 @@ Por cada carpeta bajo `openspec/changes/` (excluye `archive/` si aplica), compru
21
21
  | `proposal.md` | Obligatorio en la raiz del cambio |
22
22
  | `design.md` | Obligatorio en la raiz del cambio |
23
23
  | `tasks.md` | Obligatorio en la raiz del cambio |
24
- | **Especificacion** | **`specs.md` en la raiz** **O** al menos un `.md` bajo `specs/` del cambio (recursivo, ej. `specs/foo/spec.md`) |
24
+ | **Especificacion** | **`specs.md` en la raiz** **O** al menos un `.md` bajo `specs/` del cambio (recursivo) |
25
25
 
26
26
  OpenSpec a veces solo genera el arbol `specs/**/*.md`; eso **cumple** la fila de especificacion. Ver `OPENSPEC-DELTAS.md` (seccion **Specs: archivo unico vs arbol**).
27
27
 
@@ -35,47 +35,57 @@ OpenSpec a veces solo genera el arbol `specs/**/*.md`; eso **cumple** la fila de
35
35
  ```
36
36
  **Detente.**
37
37
 
38
- - **Multiples cambios activos**: lista carpetas y pregunta cual implementar.
38
+ - **Multiples cambios activos**: lista carpetas y pregunta cual implementar. No invoques al sub-agente con scope ambiguo.
39
39
 
40
- - **Antes de implementar**: lee **toda** la especificacion relevante — si hay `specs.md` y ademas `specs/**/*.md`, lee **ambos**; si hay contradiccion, pregunta al usuario.
40
+ - **Antes de delegar**: si hay `specs.md` y ademas `specs/**/*.md`, indica al sub-agente que lea ambos y que reporte contradicciones en sus `issues`.
41
41
 
42
42
  **IMPORTANTE**: Este comando NUNCA genera artefactos SDD. Si no existen, el usuario debe usar `/refacil:propose`.
43
43
 
44
- ### Paso 1: Validar rama de trabajo (bloqueante — antes de escribir cualquier linea de codigo)
44
+ ### Paso 1: Validar rama de trabajo (bloqueante — antes de delegar)
45
45
 
46
46
  Ejecuta `git branch --show-current` para obtener la rama actual.
47
47
 
48
48
  Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
49
49
 
50
- - **Si la rama actual es protegida**: ejecutar el protocolo completo de creacion de rama **antes de continuar**. No escribir ni una linea de codigo hasta estar en una rama de trabajo.
50
+ - **Si la rama actual es protegida**: ejecutar el protocolo completo de creacion de rama **antes de continuar**. No delegar al sub-agente hasta estar en una rama de trabajo.
51
51
  - Para `refacil:apply`, el prefijo sugerido de rama es `feature/`.
52
52
  - Si la rama actual ya es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continuar sin interrumpir.
53
53
  - Si el usuario no aprueba la creacion/cambio de rama, **detener**. No continuar con la implementacion.
54
54
 
55
- ### Paso 2: Delegar a OpenSpec apply
55
+ ### Paso 2: Delegar al sub-agente refacil-implementer
56
56
 
57
- 1. Lee `openspec-apply-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
58
- 2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **apply**).
59
- 3. Sigue OpenSpec con argumento **$ARGUMENTS** aplicando esos deltas.
57
+ Invoca al sub-agente `refacil-implementer` pasandole:
58
+ - El **changeName** resuelto (nombre de carpeta en `openspec/changes/`).
59
+ - Si el usuario pidio modo detallado, indicaselo. Default: conciso.
60
60
 
61
- ### Paso 3: Resumen y siguiente paso (aporte Refacil)
61
+ El sub-agente:
62
+ - Lee `openspec-apply-change/SKILL.md` + `OPENSPEC-DELTAS.md` para seguir las instrucciones de OpenSpec apply con los deltas Refacil.
63
+ - Lee `AGENTS.md` y todos los artefactos del cambio (proposal, specs, design, tasks).
64
+ - Implementa cada task en orden siguiendo las convenciones del proyecto.
65
+ - Retorna UN solo mensaje con el reporte + bloque JSON fenced como ` ```refacil-apply-result `.
62
66
 
63
- Al terminar la implementacion de OpenSpec, agrega este resumen:
67
+ ### Paso 3: Presentar resultado y siguiente paso
68
+
69
+ Muestra al usuario el **reporte** (todo lo anterior al bloque `refacil-apply-result`). No muestres el bloque JSON — es metadata interna.
70
+
71
+ Despues del reporte agrega:
64
72
 
65
73
  ```
66
- === Implementacion completada ===
67
- Archivos creados: [lista]
68
- Archivos modificados: [lista]
69
- Tasks completadas: [X/Y]
70
-
71
- El siguiente paso es generar/ajustar tests unitarios.
72
- Quieres que continue con /refacil:test?
73
- (Luego el flujo sigue con /refacil:verify)
74
+ El siguiente paso es generar/ajustar tests unitarios.
75
+ Quieres que continue con /refacil:test?
76
+ (Luego el flujo sigue con /refacil:verify)
74
77
  ```
75
78
 
79
+ Si el sub-agente retorno `result: "PARCIAL"` o `"FALLO"`, presenta los `issues` al usuario y pide instrucciones antes de continuar.
80
+
76
81
  ## Reglas
77
82
 
78
- - NUNCA generar artefactos SDD desde este comando — eso es responsabilidad exclusiva de `/refacil:propose`
79
- - Antes de implementar, cumplir las precondiciones del Paso 0 (artefactos completos) y del Paso 1 (rama de trabajo valida)
80
- - Si `openspec/changes/` no tiene cambios activos o estan incompletos, informar y redirigir a `/refacil:propose`
83
+ - NUNCA generar artefactos SDD desde este comando — eso es responsabilidad exclusiva de `/refacil:propose`.
84
+ - Cumplir las precondiciones del Paso 0 (artefactos completos) y del Paso 1 (rama de trabajo valida) **antes de delegar**.
85
+ - **Siempre delega al sub-agente**. No repliques aqui la logica de implementacion ni de lectura de OpenSpec apply.
86
+ - **No muestres el bloque JSON al usuario**. Es solo metadata interna.
81
87
  - **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 3, invocar inmediatamente el **Skill tool** con `skill: "refacil:test"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:test`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
88
+
89
+ ## Ver tambien
90
+
91
+ - Sub-agente: `.claude/agents/refacil-implementer.md` (fuente: `refacil-sdd-ai/agents/implementer.md`)
package/skills/bug/SKILL.md CHANGED
@@ -1,21 +1,19 @@
1
1
  ---
2
2
  name: refacil:bug
3
- description: Flujo guiado completo para investigar y corregir bugs — desde la descripcion hasta los tests de regresion
3
+ description: Flujo guiado completo para investigar y corregir bugs — delega la investigacion y el fix al sub-agente refacil-debugger en dos pasadas separadas por la confirmacion del usuario
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
- # refacil:bug — Flujo de Bug Fix
7
+ # refacil:bug — Entrypoint de Bug Fix
8
8
 
9
- Eres un asistente especializado en investigacion y correccion de bugs. Guias al desarrollador por un flujo estructurado paso a paso.
9
+ Este skill es un **wrapper** que guia al usuario por el flujo de bug fix y delega el trabajo pesado al sub-agente `refacil-debugger`. El sub-agente opera en dos modos: `investigation` (analiza y propone hipotesis sin modificar nada) y `fix` (implementa la correccion aprobada, genera tests y crea trazabilidad). La confirmacion de hipotesis y la validacion de rama ocurren en este wrapper, entre las dos invocaciones.
10
10
 
11
11
  **Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
12
12
 
13
- ## Instrucciones
13
+ ## Flujo
14
14
 
15
15
  ### Paso 0: Verificar prerequisito de trazabilidad
16
16
 
17
- Este flujo crea evidencia en `openspec/changes/`. Antes de continuar:
18
-
19
17
  1. Verifica si existe la carpeta `openspec/` en la raiz del repo.
20
18
  2. Si NO existe, deten el flujo y muestra:
21
19
  ```
@@ -26,114 +24,94 @@ Este flujo crea evidencia en `openspec/changes/`. Antes de continuar:
26
24
 
27
25
  ### Paso 1: Describir el bug
28
26
 
29
- Si `$ARGUMENTS` no los trae, pregunta al usuario: comportamiento actual, esperado, pasos de reproduccion, evidencia (logs/stack traces), cuando empezo a ocurrir, severidad (Critico/Alto/Medio/Bajo).
27
+ Si `$ARGUMENTS` no trae suficiente informacion, pregunta al usuario:
28
+ - Comportamiento actual vs. esperado.
29
+ - Pasos de reproduccion.
30
+ - Evidencia disponible (logs, stack traces).
31
+ - Cuando empezo a ocurrir.
32
+ - Severidad (Critico/Alto/Medio/Bajo).
30
33
 
31
- ### Paso 2: Investigar causa raiz
34
+ Si `$ARGUMENTS` ya es claro, no preguntes de nuevo.
32
35
 
33
- - Busca en codebase los simbolos/archivos de logs o stack traces.
34
- - Traza el flujo desde entrada (controller/endpoint) hasta el punto de falla.
35
- - Revisa commits recientes si el bug es nuevo: `git log --oneline -20`.
36
- - Presenta al usuario 1-3 hipotesis con archivo y linea sospechosa; pide que confirme o descarte.
36
+ ### Paso 2: Delegar investigacion al sub-agente refacil-debugger (mode: investigation)
37
37
 
38
- ### Paso 3: Diagnosticar
38
+ Invoca al sub-agente `refacil-debugger` pasandole:
39
+ - `mode: investigation`
40
+ - `description`: descripcion completa del bug (recogida en el Paso 1 o de `$ARGUMENTS`).
39
41
 
40
- Con la hipotesis confirmada: muestra el codigo exacto que falla, explica que condicion no se maneja, evalua impacto en otras zonas.
42
+ El sub-agente:
43
+ - Busca en el codebase simbolos/archivos de logs o stack traces.
44
+ - Traza el flujo desde entrada hasta el punto de falla.
45
+ - Revisa commits recientes si el bug es nuevo.
46
+ - Retorna hipotesis ordenadas por confianza + correccion propuesta, fenced como ` ```refacil-debug-investigation `.
41
47
 
42
- ### Paso 3.5: Validar si la causa raiz es cross-repo (opcional)
48
+ ### Paso 3: Confirmar hipotesis con el usuario
43
49
 
44
- Si durante la investigacion la causa raiz parece estar en la interaccion con otro repo (respuesta inesperada de una API externa, evento con formato distinto al esperado, contrato roto del lado del productor/consumidor), **no asumas como se comporta el otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para verificarlo con el agente del otro repo via el bus antes de proponer la correccion.
50
+ Muestra al usuario las hipotesis y la correccion propuesta. Pregunta explicitamente:
45
51
 
46
- Usa la respuesta para confirmar si el fix va en este repo, en el otro, o en ambos (en cuyo caso el otro tendra su propio `/refacil:bug`).
52
+ ```
53
+ Hipotesis de mayor confianza: [descripcion — archivo:linea]
54
+ Correccion propuesta: [descripcion minima]
55
+ Archivos a modificar: [lista]
47
56
 
48
- ### Paso 4: Proponer correccion
57
+ ¿Confirmas esta hipotesis? (si/no/otra hipotesis N)
58
+ ¿Apruebas aplicar la correccion? (si/no)
59
+ ```
49
60
 
50
- Presenta: cambio minimo, archivos a modificar, riesgos, alternativas (si existen). Espera aprobacion antes de implementar.
61
+ **NO implementes nada hasta tener aprobacion explicita del usuario.**
51
62
 
52
- ### Paso 5: Validar rama de trabajo (antes de escribir codigo)
63
+ Si el sub-agente reporto `crossRepo: true` en alguna hipotesis: antes de implementar, aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para verificar con el agente del otro repo via el bus. Usa la respuesta para confirmar si el fix va en este repo, en el otro, o en ambos.
53
64
 
54
- **ANTES de implementar cualquier cambio**, ejecuta `git branch --show-current` para obtener la rama actual.
65
+ ### Paso 4: Validar rama de trabajo (antes de implementar)
66
+
67
+ Ejecuta `git branch --show-current` para obtener la rama actual.
55
68
 
56
69
  Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
57
70
 
58
71
  - Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
59
72
  - Para `refacil:bug`, el prefijo sugerido de rama es `fix/`.
60
- - Si la rama actual ya es de trabajo (feature/fix/hotfix/refactor/etc.), continuar sin interrumpir.
61
-
62
- ### Paso 6: Implementar el fix
63
-
64
- Con aprobacion del usuario:
65
-
66
- 1. Aplica la correccion
67
- 2. Verifica que el cambio es minimo y enfocado
68
- 3. No hacer refactors adicionales
69
-
70
- ### Paso 7: Tests de regresion
71
-
72
- Genera tests que:
73
-
74
- 1. **Reproducen el bug**: Un test que falla SIN el fix (verifica que el test es valido)
75
- 2. **Verifican el fix**: El mismo test pasa CON el fix
76
- 3. **Verifican no regresion**: Tests del flujo normal siguen pasando
73
+ - Si la rama actual ya es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continuar sin interrumpir.
77
74
 
78
- Detecta el stack y framework de testing del proyecto siguiendo `METHODOLOGY-CONTRACT.md` §3 y los patrones existentes (ubicacion, nombrado, mocks, assertions). Genera los tests con la estructura y convenciones reales del proyecto.
75
+ ### Paso 5: Delegar implementacion al sub-agente refacil-debugger (mode: fix)
79
76
 
80
- Cada test de regresion debe cubrir:
81
- - **Caso del bug**: `should [comportamiento correcto] when [condicion que antes fallaba]`
82
- - **Caso normal**: `should still [comportamiento normal] when [condicion normal]`
77
+ Invoca al sub-agente `refacil-debugger` pasandole:
78
+ - `mode: fix`
79
+ - `description`: descripcion completa del bug.
80
+ - `hypothesis`: causa raiz confirmada por el usuario en el Paso 3.
83
81
 
84
- ### Paso 8: Crear trazabilidad del fix (obligatorio)
82
+ El sub-agente:
83
+ - Implementa el fix minimo y enfocado.
84
+ - Genera tests de regresion (reproduce el bug + verifica el fix + no regresion).
85
+ - Crea `openspec/changes/fix-<nombre>/summary.md` con trazabilidad.
86
+ - Ejecuta todos los tests del proyecto.
87
+ - Retorna el reporte fenced como ` ```refacil-debug-fix `.
85
88
 
86
- Genera un nombre de carpeta **siempre descriptivo**: `fix-[descripcion-corta]` (maximo 3-4 palabras en kebab-case, ej. `fix-session-timeout-redis`, `fix-null-pointer-payment`).
89
+ ### Paso 6: Presentar resultado y siguiente paso
87
90
 
88
- **No uses IDs de tickets** (REF-123, JIRA-456, etc.) en el nombre de carpeta — el nombre debe ser descriptivo para que sirva como insumo legible en `/refacil:explore` y en `openspec/specs/`.
91
+ Muestra al usuario el **reporte** (todo lo anterior al bloque `refacil-debug-fix`). No muestres el bloque JSON — es metadata interna.
89
92
 
90
- **No uses el nombre de la rama** como nombre de carpeta — en una misma rama pueden corregirse multiples bugs, cada uno con su propia carpeta fix.
93
+ Agrega al final:
91
94
 
92
- Crea la carpeta en `openspec/changes/[nombre-fix]/` con un archivo `summary.md`:
93
-
94
- ```markdown
95
- # Fix: [descripcion corta]
96
-
97
- - **Fecha**: [fecha ISO]
98
- - **Severidad**: [Critico|Alto|Medio|Bajo]
99
- - **Causa raiz**: [explicacion breve]
100
- - **Fix aplicado**: [que se cambio]
101
- - **Archivos modificados**: [lista]
102
- - **Tests de regresion**: [N] tests agregados
95
+ ```
96
+ El siguiente paso es el review del fix (obligatorio antes de archivar).
97
+ Quieres que continue con /refacil:review?
98
+ (Luego el flujo sigue con /refacil:archive y /refacil:up-code)
103
99
  ```
104
100
 
105
- Este archivo es obligatorio para la trazabilidad del fix y permite que el hook de review (`check-review`) detecte el cambio activo. El archivo `.review-passed` sera creado por `/refacil:review` al aprobar.
106
-
107
- **Opcionalmente**, si el bug es significativo, el usuario puede pedir artefactos completos de OpenSpec (proposal.md, design.md, tasks.md, specs) en esta misma carpeta.
108
-
109
- ### Paso 9: Verificar y siguientes pasos
101
+ Si el sub-agente retorno `result: "FALLO"` (tests no pasan), presenta el detalle y pide instrucciones antes de continuar.
110
102
 
111
- 1. Resuelve el comando de tests segun `METHODOLOGY-CONTRACT.md` y ejecutalo — todos los tests deben pasar
112
- 2. Muestra resumen del fix
103
+ ## Reglas
113
104
 
114
- ```
115
- === Bug Fix Completado ===
116
- Bug: [descripcion corta]
117
- Causa raiz: [explicacion]
118
- Fix: [que se cambio]
119
- Archivos modificados: [lista]
120
- Tests de regresion: [N] tests agregados
121
- Trazabilidad: openspec/changes/fix-[nombre]/summary.md
122
- [comando-test]: PASS
123
-
124
- El siguiente paso es el review del fix (obligatorio antes de archivar).
125
- Quieres que continue con /refacil:review?
126
- (Luego el flujo sigue con /refacil:archive y /refacil:up-code)
127
- ```
105
+ - **Siempre investiga antes de proponer** — no delegar el fix sin hipotesis confirmada.
106
+ - **NUNCA implementar sin aprobacion explicita del usuario** (Paso 3).
107
+ - **Siempre valida la rama** (Paso 4) antes de delegar el fix.
108
+ - **No repliques aqui la logica de investigacion ni de implementacion** — eso vive en `refacil-debugger`.
109
+ - **No muestres los bloques JSON al usuario**. Son metadata interna del wrapper.
110
+ - El Paso 3 (bus cross-repo) es **opcional** — solo aplica si el sub-agente reporto `crossRepo: true`.
111
+ - Responder en espanol con terminos tecnicos en ingles.
112
+ - **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 6, invocar inmediatamente el **Skill tool** con `skill: "refacil:review"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:review`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
128
113
 
129
- ## Reglas
114
+ ## Ver tambien
130
115
 
131
- - SIEMPRE investigar antes de proponer una correccion
132
- - NUNCA implementar sin aprobacion del usuario
133
- - El fix debe ser MINIMO — no aprovechar para refactorizar
134
- - Los tests de regresion son OBLIGATORIOS
135
- - Si el bug es en produccion (critico), priorizar velocidad pero sin saltarse tests ni trazabilidad
136
- - El Paso 3.5 (bus cross-repo) es **opcional** — solo invocarlo si la causa raiz parece cross-repo. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.
137
- - Responder en español con terminos tecnicos en ingles
138
- - Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)
139
- - **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad al cierre del fix, invocar inmediatamente el **Skill tool** con `skill: "refacil:review"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:review`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
116
+ - Sub-agente: `.claude/agents/refacil-debugger.md` (fuente: `refacil-sdd-ai/agents/debugger.md`)
117
+ - Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`
package/skills/propose/SKILL.md CHANGED
@@ -1,62 +1,59 @@
1
1
  ---
2
2
  name: refacil:propose
3
- description: Crear una propuesta de cambio completa — genera proposal, specs, design y tasks siguiendo la metodologia SDD-AI
3
+ description: Crear una propuesta de cambio completa — delega la exploracion del codebase y la generacion de artefactos al sub-agente refacil-proposer, y maneja la revision humana obligatoria de los artefactos
4
4
  user-invocable: true
5
5
  ---
6
6
 
7
- # refacil:propose — Propuesta de Cambio
7
+ # refacil:propose — Entrypoint de Propuesta de Cambio
8
8
 
9
- Este comando envuelve la funcionalidad de OpenSpec propose y agrega las convenciones del equipo.
9
+ Este skill es un **wrapper** que prepara el scope, delega la generacion de artefactos SDD al sub-agente `refacil-proposer`, y maneja la revision humana obligatoria (Human-in-the-Loop). El sub-agente corre en contexto aislado explorando el codebase y generando los artefactos; este wrapper los presenta al usuario para aprobacion.
10
10
 
11
11
  **Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
12
12
 
13
- ## Instrucciones
13
+ ## Flujo
14
14
 
15
- ### Paso 1: Entender el cambio (aporte Refacil)
15
+ ### Paso 1: Entender el cambio
16
16
 
17
- Si el usuario NO proporciono suficiente contexto en $ARGUMENTS, preguntale:
17
+ Si el usuario NO proporciono suficiente contexto en `$ARGUMENTS`, preguntale:
18
18
  - **Que tipo de cambio es?** (feature nuevo, mejora, refactor)
19
19
  - **Cual es el problema o necesidad?** (contexto de negocio)
20
20
  - **Cual es el objetivo?** (que debe lograr en una oracion)
21
21
 
22
- Si $ARGUMENTS ya es claro, no preguntes de nuevo.
22
+ Si `$ARGUMENTS` ya es claro, no preguntes de nuevo.
23
23
 
24
- ### Paso 1.5: Identificador de carpeta del cambio (bloqueante — CLI OpenSpec)
24
+ ### Paso 1.5: Identificador de carpeta del cambio (bloqueante)
25
25
 
26
26
  El directorio `openspec/changes/<nombre>/` **no puede** usar un `<nombre>` cuyo **primer caracter no sea una letra ASCII** `[a-zA-Z]` — ver **`refacil-prereqs/METHODOLOGY-CONTRACT.md` §9**. Nombres como `2026-04-17-exponer-algo` hacen fallar `openspec status --change` y otros comandos.
27
27
 
28
- **Antes del Paso 2:**
28
+ **Antes de delegar al sub-agente:**
29
29
 
30
30
  1. Acuerda o deriva el **slug final** del cambio (kebab-case: `feat-...`, `exponer-...`, `imp-...`, etc.). Fecha o ticket no van al **inicio** del nombre.
31
- 2. Si el usuario o OpenSpec proponen un nombre invalido, **corrigelo** (p. ej. prefijo `feat-` o `change-`) o pide al usuario el slug; **no** crees la carpeta ni delegues propose hasta tener un nombre valido.
32
- 3. Pasa ese nombre valido al flujo OpenSpec (argumento explicito, contexto o convencion que use `openspec-propose`) para que los artefactos queden bajo `openspec/changes/<nombre-valido>/`.
31
+ 2. Si el usuario propone un nombre invalido, **corrigelo** (p. ej. prefijo `feat-` o `change-`) o pide el slug correcto; **no** delegar hasta tener un nombre valido.
32
+ 3. Comunica al usuario el slug final acordado antes de generar.
33
33
 
34
- ### Paso 2: Delegar a OpenSpec ff (fast-forward)
34
+ ### Paso 2: Delegar al sub-agente refacil-proposer
35
35
 
36
- 1. Lee `openspec-propose/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
37
- 2. Lee `OPENSPEC-DELTAS.md` en la carpeta `refacil-prereqs` (misma ruta dual que en prereqs).
38
- 3. Ejecuta la skill OpenSpec siguiendo sus instrucciones y aplicando los deltas Refacil para generar los artefactos (proposal, specs, design, tasks) en una sola pasada.
36
+ Invoca al sub-agente `refacil-proposer` pasandole:
37
+ - `changeName`: el slug valido acordado en el Paso 1.5.
38
+ - `description`: descripcion completa del cambio (del Paso 1 o de `$ARGUMENTS`).
39
39
 
40
- ### Paso 2.5: Validar contratos cross-repo (opcional)
40
+ El sub-agente:
41
+ - Lee `openspec-propose/SKILL.md` + `OPENSPEC-DELTAS.md` para seguir las instrucciones de OpenSpec propose con los deltas Refacil.
42
+ - Explora el codebase (lee `AGENTS.md`, detecta archivos y convenciones relevantes) antes de generar.
43
+ - Genera los artefactos bajo `openspec/changes/<changeName>/`: `proposal.md`, especificacion (`specs.md` y/o `specs/**/*.md`), `design.md`, `tasks.md`.
44
+ - Si el cambio involucra contratos cross-repo, lo nota en `design.md`.
45
+ - Retorna UN solo mensaje con el resumen + bloque JSON fenced como ` ```refacil-propose-result `.
41
46
 
42
- Si el cambio propuesto involucra un contrato con otro sistema (un endpoint que otro repo consume, un evento que otro repo emite o recibe, un formato de datos compartido, una cola o topico cross-servicio), **no asumas como luce el otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para validarlo con el agente del otro repo via el bus antes de cerrar los artefactos.
47
+ Si el cambio surge de un **acuerdo en sala del bus** (`refacil-bus`), indicarselo al sub-agente en la descripcion para que lo tenga en cuenta al generar los artefactos. No acortar el flujo metodologico. Ver `refacil-prereqs/BUS-CROSS-REPO.md` (seccion acuerdos en sala).
43
48
 
44
- Usa la respuesta para ajustar `specs.md` / `design.md` antes de pasar a revision humana.
49
+ ### Paso 3: Revision del desarrollador (Human-in-the-Loop — OBLIGATORIO)
45
50
 
46
- ### Paso 2.6: Origen acordado en la sala del bus (si aplica)
51
+ Parsea el bloque `refacil-propose-result` del sub-agente para obtener las rutas reales de los artefactos. Presenta al usuario un resumen claro para su revision:
47
52
 
48
- Si el cambio surge de un **acuerdo en `refacil-bus`** (say / ask / reply) que compromete **este** repo, igualmente es un propose aqui: no acortes el flujo metodologico salvo orden explicita del usuario. No hace falta que el `ask` en sala traiga la guía: quien pregunta asume que esta sesion ya opera SDD-AI. Al **implementar** despues (apply, etc.), quien ejecuta debe **cerrar por el bus** con quien pidio el trabajo; ver `refacil-prereqs/BUS-CROSS-REPO.md` (seccion acuerdos en la sala).
49
-
50
- ### Paso 3: Revision del desarrollador (Human-in-the-Loop)
51
-
52
- **IMPORTANTE**: Este paso es OBLIGATORIO. El desarrollador debe revisar y aprobar los artefactos antes de implementar.
53
-
54
- Despues de que OpenSpec genere los artefactos, presenta al usuario un resumen claro para su revision:
55
-
56
- 1. **Proposal**: Objetivo, alcance y justificacion del cambio
57
- 2. **Specs**: Criterios de aceptacion y rechazo — listar **rutas reales**: `specs.md` y/o cada `specs/**/spec.md` (OpenSpec puede usar solo el arbol `specs/`)
58
- 3. **Design**: Archivos a crear/modificar y patrones a usar — verificar que se alineen con la arquitectura
59
- 4. **Tasks**: Lista de tareas con estimacion — verificar que el desglose sea correcto y completo
53
+ 1. **Proposal**: objetivo, alcance y justificacion del cambio.
54
+ 2. **Specs**: criterios de aceptacion y rechazo — listar **rutas reales** recibidas en el bloque JSON.
55
+ 3. **Design**: archivos a crear/modificar y patrones a usar.
56
+ 4. **Tasks**: lista de tareas — verificar que el desglose sea correcto y completo.
60
57
 
61
58
  Pregunta explicitamente:
62
59
 
@@ -64,7 +61,7 @@ Pregunta explicitamente:
64
61
  === Revision requerida ===
65
62
  Los artefactos estan listos para tu revision:
66
63
  - openspec/changes/[nombre]/proposal.md
67
- - Especificacion: openspec/changes/[nombre]/specs.md y/o openspec/changes/[nombre]/specs/**/*.md (listar archivos)
64
+ - [rutas reales de specs]
68
65
  - openspec/changes/[nombre]/design.md
69
66
  - openspec/changes/[nombre]/tasks.md
70
67
 
@@ -76,7 +73,9 @@ Por favor revisa los artefactos y confirma:
76
73
  Responde "OK" para continuar, o indica que ajustes necesitas.
77
74
  ```
78
75
 
79
- **NO continuar al siguiente paso hasta que el usuario apruebe explicitamente.** Si el usuario pide ajustes, aplicalos y vuelve a presentar el resumen.
76
+ **NO continuar al Paso 4 hasta que el usuario apruebe explicitamente.**
77
+
78
+ Si el usuario pide ajustes acotados (cambiar un criterio, corregir una ruta, ajustar una task), aplicalos directamente en los archivos correspondientes y vuelve a presentar el resumen. Si los ajustes son amplios (cambiar el objetivo o el scope completo), re-invoca al sub-agente con la descripcion actualizada.
80
79
 
81
80
  ### Paso 4: Siguiente paso
82
81
 
@@ -88,12 +87,16 @@ Quieres que continue con /refacil:apply?
88
87
 
89
88
  ## Reglas
90
89
 
91
- - **Nombre de carpeta del cambio**: cumplir siempre **§9** del contrato metodologico (primer caracter letra ASCII; nunca iniciar con digito).
92
- - **NUNCA escribir, modificar o generar codigo fuente** en esta fase — solo artefactos SDD: `proposal.md`, `design.md`, `tasks.md`, y especificacion en `specs.md` y/o `specs/**/*.md` (convencion OpenSpec)
93
- - Aunque el usuario pase una descripcion completa y detallada en $ARGUMENTS, la salida es EXCLUSIVAMENTE artefactos de planificacion
90
+ - **Nombre de carpeta del cambio**: cumplir siempre **§9** del contrato metodologico (primer caracter letra ASCII; nunca iniciar con digito). Validar ANTES de delegar.
91
+ - **NUNCA escribir, modificar o generar codigo fuente** — solo artefactos SDD.
92
+ - Aunque el usuario pase una descripcion completa en `$ARGUMENTS`, la salida es EXCLUSIVAMENTE artefactos de planificacion.
94
93
  - Si el usuario pide que tambien implemente, responder: "La implementacion se hace con `/refacil:apply` despues de aprobar los artefactos."
95
- - Siempre explorar el codebase ANTES de generar artefactos (para que el design sea realista)
96
- - Los criterios de aceptacion deben ser especificos y testeables
97
- - El Paso 2.5 (bus cross-repo) es **opcional** — solo invocarlo si el cambio toca un contrato con otro sistema. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.
98
- - El Paso 2.6 aplica cuando el input viene de **acuerdos en sala**; no implica saltarse artefactos ni escribir codigo en esta skill.
94
+ - **Siempre delega la generacion al sub-agente**. No repliques aqui la logica de exploracion del codebase ni la generacion de artefactos.
95
+ - **No muestres el bloque JSON al usuario**. Es solo metadata para obtener las rutas reales de los artefactos.
96
+ - **Revision humana es obligatoria** — NO saltar el Paso 3.
99
97
  - **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 4, invocar inmediatamente el **Skill tool** con `skill: "refacil:apply"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:apply`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
98
+
99
+ ## Ver tambien
100
+
101
+ - Sub-agente: `.claude/agents/refacil-proposer.md` (fuente: `refacil-sdd-ai/agents/proposer.md`)
102
+ - Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`