refacil-sdd-ai 3.0.3 → 4.0.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.
- package/README.md +402 -392
- package/bin/cli.js +81 -1217
- package/lib/commands/bus.js +499 -0
- package/lib/commands/compact.js +92 -0
- package/lib/hooks.js +107 -0
- package/lib/ignore-files.js +88 -0
- package/lib/installer.js +265 -0
- package/package.json +6 -2
- package/refacil-bus-diagrams.md +314 -0
- package/skills/archive/SKILL.md +191 -167
- package/skills/guide/SKILL.md +4 -2
- package/skills/setup/SKILL.md +123 -91
- package/skills/update/SKILL.md +81 -0
- package/templates/methodology-guide.md +52 -45
package/README.md
CHANGED
|
@@ -1,392 +1,402 @@
|
|
|
1
|
-
# refacil-sdd-ai
|
|
2
|
-
|
|
3
|
-
Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
|
|
4
|
-
|
|
5
|
-
Instala **skills** y **sub-agentes** para **Claude Code** y **Cursor** que guian al desarrollador por un flujo estructurado de desarrollo usando **OpenSpec** como base de especificaciones, mas un **bus local** para que los agentes de distintos repos se comuniquen entre si.
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Requisitos
|
|
10
|
-
|
|
11
|
-
- **Node.js >= 20.19.0** (requerido por OpenSpec)
|
|
12
|
-
- **Claude Code >= 2.1.89** (requerido por el hook `compact-bash` para rewrite silencioso via `updatedInput`) o **Cursor**
|
|
13
|
-
|
|
14
|
-
`refacil-sdd-ai init` verifica la version de Claude Code y advierte si es inferior. Con version < 2.1.89 el resto de la metodologia funciona, pero `compact-bash` no tendra efecto.
|
|
15
|
-
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
## Instalacion
|
|
19
|
-
|
|
20
|
-
Recomendado: instalar globalmente una sola vez, y correr `init` por repo.
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
# 1. Global (una vez)
|
|
24
|
-
npm install -g refacil-sdd-ai
|
|
25
|
-
|
|
26
|
-
# 2. En la raiz del repo
|
|
27
|
-
refacil-sdd-ai init
|
|
28
|
-
# Copia skills a .claude/ y .cursor/, crea CLAUDE.md + .cursorrules, configura hooks
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
#
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
refacil-sdd-ai
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
| `refacil-sdd-ai
|
|
66
|
-
| `refacil-sdd-ai
|
|
67
|
-
| `refacil-sdd-ai
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
| `refacil-sdd-ai check-
|
|
75
|
-
| `refacil-sdd-ai
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
| `refacil-sdd-ai compact
|
|
83
|
-
| `refacil-sdd-ai compact
|
|
84
|
-
| `refacil-sdd-ai compact
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
| `refacil-sdd-ai bus
|
|
92
|
-
| `refacil-sdd-ai bus
|
|
93
|
-
| `refacil-sdd-ai bus
|
|
94
|
-
| `refacil-sdd-ai bus
|
|
95
|
-
| `refacil-sdd-ai bus
|
|
96
|
-
| `refacil-sdd-ai bus
|
|
97
|
-
| `refacil-sdd-ai bus
|
|
98
|
-
| `refacil-sdd-ai bus
|
|
99
|
-
| `refacil-sdd-ai bus
|
|
100
|
-
| `refacil-sdd-ai bus
|
|
101
|
-
| `refacil-sdd-ai bus
|
|
102
|
-
| `refacil-sdd-ai bus
|
|
103
|
-
| `refacil-sdd-ai bus
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
| `/refacil:
|
|
119
|
-
| `/refacil:
|
|
120
|
-
| `/refacil:
|
|
121
|
-
| `/refacil:
|
|
122
|
-
| `/refacil:
|
|
123
|
-
| `/refacil:
|
|
124
|
-
| `/refacil:
|
|
125
|
-
| `/refacil:
|
|
126
|
-
| `/refacil:
|
|
127
|
-
| `/refacil:
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
|
136
|
-
|
|
137
|
-
| `/refacil:
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
**
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
|
148
|
-
|
|
149
|
-
| `/refacil:
|
|
150
|
-
| `/refacil:
|
|
151
|
-
| `/refacil:
|
|
152
|
-
| `/refacil:
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
**
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
│
|
|
249
|
-
|
|
250
|
-
│
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
│
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
|
280
|
-
|
|
281
|
-
| `
|
|
282
|
-
| `
|
|
283
|
-
| `
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
|
293
|
-
|
|
294
|
-
| `
|
|
295
|
-
| `
|
|
296
|
-
| `
|
|
297
|
-
| `
|
|
298
|
-
| `
|
|
299
|
-
|
|
|
300
|
-
| `
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
.
|
|
374
|
-
|
|
375
|
-
.
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
|
|
392
|
-
|
|
1
|
+
# refacil-sdd-ai
|
|
2
|
+
|
|
3
|
+
Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
|
|
4
|
+
|
|
5
|
+
Instala **skills** y **sub-agentes** para **Claude Code** y **Cursor** que guian al desarrollador por un flujo estructurado de desarrollo usando **OpenSpec** como base de especificaciones, mas un **bus local** para que los agentes de distintos repos se comuniquen entre si.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Requisitos
|
|
10
|
+
|
|
11
|
+
- **Node.js >= 20.19.0** (requerido por OpenSpec)
|
|
12
|
+
- **Claude Code >= 2.1.89** (requerido por el hook `compact-bash` para rewrite silencioso via `updatedInput`) o **Cursor**
|
|
13
|
+
|
|
14
|
+
`refacil-sdd-ai init` verifica la version de Claude Code y advierte si es inferior. Con version < 2.1.89 el resto de la metodologia funciona, pero `compact-bash` no tendra efecto.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Instalacion
|
|
19
|
+
|
|
20
|
+
Recomendado: instalar globalmente una sola vez, y correr `init` por repo.
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# 1. Global (una vez)
|
|
24
|
+
npm install -g refacil-sdd-ai
|
|
25
|
+
|
|
26
|
+
# 2. En la raiz del repo
|
|
27
|
+
refacil-sdd-ai init
|
|
28
|
+
# Copia skills a .claude/ y .cursor/, crea CLAUDE.md + .cursorrules, configura hooks
|
|
29
|
+
# Crea/actualiza .claudeignore y .cursorignore con exclusiones base
|
|
30
|
+
|
|
31
|
+
# 3. Reiniciar sesion de Claude Code o Cursor
|
|
32
|
+
# (las skills nuevas no se detectan hasta reiniciar)
|
|
33
|
+
|
|
34
|
+
# 4. En el IDE
|
|
35
|
+
/refacil:setup
|
|
36
|
+
# Instala OpenSpec, inicializa openspec/ y genera AGENTS.md
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
### Actualizar
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
npm update -g refacil-sdd-ai
|
|
43
|
+
refacil-sdd-ai update # en cada repo donde se use
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
En Claude Code el hook `check-update` hace esto automaticamente al iniciar sesion. Si la nueva version incluye migraciones de estructura (ej. nuevo patron de documentacion), el hook informa al LLM y propone ejecutar `/refacil:update` — la skill detecta que aplica y omite lo que ya esta al dia.
|
|
47
|
+
|
|
48
|
+
### Desinstalar
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
refacil-sdd-ai clean # en el repo (elimina skills + hooks SDD-AI)
|
|
52
|
+
npm uninstall -g refacil-sdd-ai
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
> **Nota**: `openspec init` tambien instala sus comandos `opsx:*`. Coexisten sin conflicto con los `refacil:*`. Usar siempre `refacil:*` como interfaz principal.
|
|
56
|
+
|
|
57
|
+
---
|
|
58
|
+
|
|
59
|
+
## Comandos del CLI
|
|
60
|
+
|
|
61
|
+
### Gestion del paquete
|
|
62
|
+
|
|
63
|
+
| Comando | Descripcion |
|
|
64
|
+
|---|---|
|
|
65
|
+
| `refacil-sdd-ai init` | Instala skills y hooks en el repo actual |
|
|
66
|
+
| `refacil-sdd-ai update` | Re-copia skills y hooks a la ultima version |
|
|
67
|
+
| `refacil-sdd-ai clean` | Elimina skills y hooks SDD-AI del repo |
|
|
68
|
+
| `refacil-sdd-ai help` | Ver ayuda |
|
|
69
|
+
|
|
70
|
+
### Hooks internos (invocados automaticamente, no manual)
|
|
71
|
+
|
|
72
|
+
| Comando | Descripcion |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `refacil-sdd-ai check-update` | Verifica nueva version + sincroniza `compact-guidance` en AGENTS.md |
|
|
75
|
+
| `refacil-sdd-ai check-review` | Bloquea `git push` si falta `.review-passed` en algun cambio activo |
|
|
76
|
+
| `refacil-sdd-ai compact-bash` | Reescribe comandos Bash bare via `updatedInput` |
|
|
77
|
+
|
|
78
|
+
### Control del rewrite de comandos (`compact-bash`)
|
|
79
|
+
|
|
80
|
+
| Comando | Descripcion |
|
|
81
|
+
|---|---|
|
|
82
|
+
| `refacil-sdd-ai compact stats` | Estadisticas (hook + ya-compacto) + tokens y USD estimados |
|
|
83
|
+
| `refacil-sdd-ai compact enable` | Reactiva el rewrite |
|
|
84
|
+
| `refacil-sdd-ai compact disable` | Desactiva el rewrite sin desinstalar |
|
|
85
|
+
| `refacil-sdd-ai compact clear-log` | Limpia `~/.refacil-sdd-ai/compact.log` |
|
|
86
|
+
|
|
87
|
+
### Bus de agentes (`bus`)
|
|
88
|
+
|
|
89
|
+
| Comando | Descripcion |
|
|
90
|
+
|---|---|
|
|
91
|
+
| `refacil-sdd-ai bus start` | Arranca el broker local (auto-spawn detached) |
|
|
92
|
+
| `refacil-sdd-ai bus stop` | Detiene el broker |
|
|
93
|
+
| `refacil-sdd-ai bus status` | Muestra puerto, pid, uptime |
|
|
94
|
+
| `refacil-sdd-ai bus rooms` | Salas activas + miembros |
|
|
95
|
+
| `refacil-sdd-ai bus view` | Abre la UI web en el navegador |
|
|
96
|
+
| `refacil-sdd-ai bus watch <session> [--room <sala>]` | Panel en vivo en terminal (0 tokens) |
|
|
97
|
+
| `refacil-sdd-ai bus history [--n N] [--session <s>]` | Ultimos N mensajes |
|
|
98
|
+
| `refacil-sdd-ai bus join --room <sala> [--session <s>] [--intro "..."]` | Unirse a sala (las skills lo hacen) |
|
|
99
|
+
| `refacil-sdd-ai bus leave [--session <s>]` | Salir de la sala |
|
|
100
|
+
| `refacil-sdd-ai bus say --text "..." [--session <s>]` | Broadcast (las skills lo hacen) |
|
|
101
|
+
| `refacil-sdd-ai bus ask --to <name> --text "..." [--wait N]` | Pregunta dirigida (las skills lo hacen) |
|
|
102
|
+
| `refacil-sdd-ai bus reply --text "..." [--correlation <id>]` | Responder (las skills lo hacen) |
|
|
103
|
+
| `refacil-sdd-ai bus attend [--timeout N]` | Escucha preguntas dirigidas (las skills lo hacen) |
|
|
104
|
+
| `refacil-sdd-ai bus inbox [--session <s>]` | Ver mensajes nuevos |
|
|
105
|
+
|
|
106
|
+
> Los subcomandos `join/leave/say/ask/reply/attend/inbox` tambien existen como **skills** dentro del IDE (`/refacil:join`, etc.). En la mayoria de los casos conviene usar las skills; los comandos del CLI son para scripting o debugging.
|
|
107
|
+
|
|
108
|
+
---
|
|
109
|
+
|
|
110
|
+
## Skills disponibles en el IDE
|
|
111
|
+
|
|
112
|
+
Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
|
|
113
|
+
|
|
114
|
+
### Ciclo SDD
|
|
115
|
+
|
|
116
|
+
| Skill | Uso |
|
|
117
|
+
|---|---|
|
|
118
|
+
| `/refacil:setup` | Instalar OpenSpec + generar AGENTS.md |
|
|
119
|
+
| `/refacil:guide` | Guia interactiva sobre que comando usar |
|
|
120
|
+
| `/refacil:explore` | Explorar codebase sin modificar |
|
|
121
|
+
| `/refacil:propose` | Crear propuesta: proposal + specs + design + tasks |
|
|
122
|
+
| `/refacil:apply` | Implementar tasks del cambio |
|
|
123
|
+
| `/refacil:test` | Generar tests unitarios desde los artefactos |
|
|
124
|
+
| `/refacil:verify` | Validar implementacion vs specs (con autofix opcional) |
|
|
125
|
+
| `/refacil:review` | Checklist de calidad, emite `.review-passed` si aprueba |
|
|
126
|
+
| `/refacil:archive` | Archivar cambio completado + sincronizar specs (solicita links de Jira) |
|
|
127
|
+
| `/refacil:up-code` | Commit + push + PR (ejecuta review si falta) |
|
|
128
|
+
| `/refacil:bug` | Flujo completo de bugfix con tests de regresion |
|
|
129
|
+
| `/refacil:update` | Detectar y aplicar migraciones pendientes de la metodologia al repo actual |
|
|
130
|
+
|
|
131
|
+
### Sub-agentes automaticos (v3.0.0+)
|
|
132
|
+
|
|
133
|
+
Algunos skills delegan su trabajo pesado a **sub-agentes** que corren en contexto aislado (no saturan la sesion principal con lecturas masivas). Son invocados automaticamente por el skill correspondiente — no se llaman directo.
|
|
134
|
+
|
|
135
|
+
| Skill | Sub-agente | Rol |
|
|
136
|
+
|---|---|---|
|
|
137
|
+
| `/refacil:explore` | `refacil-investigator` | Lee codebase, enriquece con AGENTS.md, consulta bus cross-repo |
|
|
138
|
+
| `/refacil:verify` | `refacil-validator` | Corre tests + compara contra spec, retorna issues priorizados |
|
|
139
|
+
| `/refacil:review` | `refacil-auditor` | Evalua cambios contra el checklist de calidad |
|
|
140
|
+
|
|
141
|
+
**Propiedades comunes**: `readonly` (no pueden modificar archivos), system prompt especializado, guardrail de invocacion directa. El contrato con el skill wrapper es un bloque JSON fenced (`refacil-review-result`, `refacil-verify-result`).
|
|
142
|
+
|
|
143
|
+
**Dual-platform**: `.claude/agents/refacil-*.md` usa `tools:` (allowlist granular). `.cursor/agents/refacil-*.md` se genera automaticamente con `readonly: true` y `model: inherit`. El installer transforma el frontmatter.
|
|
144
|
+
|
|
145
|
+
### Bus de agentes
|
|
146
|
+
|
|
147
|
+
| Skill | Uso |
|
|
148
|
+
|---|---|
|
|
149
|
+
| `/refacil:join <sala>` | Unirse o crear sala |
|
|
150
|
+
| `/refacil:say "..."` | Broadcast |
|
|
151
|
+
| `/refacil:ask @nombre "..." [--wait N]` | Pregunta dirigida (bloquea con `--wait`) |
|
|
152
|
+
| `/refacil:reply "..."` | Responder ultima pregunta (autocompleta `correlationId`) |
|
|
153
|
+
| `/refacil:attend` | Modo escucha activa |
|
|
154
|
+
| `/refacil:inbox` | Mensajes nuevos desde la ultima lectura |
|
|
155
|
+
|
|
156
|
+
---
|
|
157
|
+
|
|
158
|
+
## Flujo recomendado
|
|
159
|
+
|
|
160
|
+
Regla rapida para elegir el comando de entrada:
|
|
161
|
+
|
|
162
|
+
- Entender el sistema sin tocar codigo -> `/refacil:explore`
|
|
163
|
+
- Feature nuevo o cambio de comportamiento -> `/refacil:propose`
|
|
164
|
+
- Bug funcional o error en produccion -> `/refacil:bug`
|
|
165
|
+
|
|
166
|
+
A partir de ahi, el ciclo completo es:
|
|
167
|
+
|
|
168
|
+
```
|
|
169
|
+
┌───────────────────────────┐
|
|
170
|
+
│ Necesidad de cambio │
|
|
171
|
+
└──────────────┬────────────┘
|
|
172
|
+
▼
|
|
173
|
+
┌─────────────────┐
|
|
174
|
+
│ ¿Tipo de tarea? │
|
|
175
|
+
└──┬───────┬──────┘
|
|
176
|
+
│ │
|
|
177
|
+
FEATURE│ │BUG
|
|
178
|
+
▼ ▼
|
|
179
|
+
/refacil: /refacil:
|
|
180
|
+
propose bug
|
|
181
|
+
(proposal + (fix + tests
|
|
182
|
+
specs + de regresion
|
|
183
|
+
design + + summary.md)
|
|
184
|
+
tasks) │
|
|
185
|
+
│ │
|
|
186
|
+
▼ │
|
|
187
|
+
/refacil: │
|
|
188
|
+
apply │
|
|
189
|
+
│ │
|
|
190
|
+
▼ │
|
|
191
|
+
/refacil: │
|
|
192
|
+
test │
|
|
193
|
+
│ │
|
|
194
|
+
▼ │
|
|
195
|
+
/refacil: │
|
|
196
|
+
verify │
|
|
197
|
+
(max 2 rondas │
|
|
198
|
+
autofix) │
|
|
199
|
+
│ │
|
|
200
|
+
└───┬───┘
|
|
201
|
+
▼
|
|
202
|
+
/refacil:review
|
|
203
|
+
(genera .review-passed)
|
|
204
|
+
▼
|
|
205
|
+
/refacil:archive
|
|
206
|
+
(feature: OpenSpec
|
|
207
|
+
bug: fix-*/spec.md +
|
|
208
|
+
review.yaml)
|
|
209
|
+
▼
|
|
210
|
+
/refacil:up-code
|
|
211
|
+
(verifica review +
|
|
212
|
+
commit + push + PR)
|
|
213
|
+
▼
|
|
214
|
+
PR creado
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Nota — dos capas de chequeo de review**:
|
|
218
|
+
- `/refacil:up-code` detecta `.review-passed` faltante y **ejecuta `/refacil:review` automaticamente** antes del push.
|
|
219
|
+
- El hook `check-review` tambien intercepta `git push` manuales y **bloquea** la operacion si falta. El hook no invoca skills — solo bloquea e instruye.
|
|
220
|
+
|
|
221
|
+
**Archive**:
|
|
222
|
+
- Para features/mejoras: OpenSpec mueve a `archive/` y extrae los campos del `.review-passed` a `review.yaml` dentro de cada spec afectado.
|
|
223
|
+
- Para bugs: archivado manual, crea `openspec/specs/fix-*/spec.md` en formato OpenSpec estandar + `review.yaml`.
|
|
224
|
+
- Una misma rama puede acumular multiples bugs, cada uno en su `fix-*/` independiente.
|
|
225
|
+
- `/refacil:archive` siempre solicita uno o varios **links de Jira** asociados al cambio antes de proceder. Los links se guardan en `review.yaml` bajo el campo `jiraTasks` (lista YAML). El campo es obligatorio — el archivado no avanza hasta que el usuario proporcione al menos un link.
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## Hooks automaticos
|
|
230
|
+
|
|
231
|
+
Se instalan en `.claude/settings.json` **y** `.cursor/settings.json` durante `init` / `update`. Aplican tanto a **Claude Code** como a **Cursor**.
|
|
232
|
+
|
|
233
|
+
| Hook | Evento | Que hace |
|
|
234
|
+
|---|---|---|
|
|
235
|
+
| `check-update` | `SessionStart` | Chequea nueva version en npm, la instala, y **sincroniza el bloque `compact-guidance`** en `AGENTS.md`. |
|
|
236
|
+
| `compact-bash` | `PreToolUse` (Bash) | Reescribe silenciosamente comandos Bash bare via `updatedInput`. Sin turnos extra, sin que el IDE vea el cambio. Requiere Claude Code >= 2.1.89. |
|
|
237
|
+
| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y bloquea si falta `.review-passed` en algun cambio activo. |
|
|
238
|
+
|
|
239
|
+
Los tres hooks se instalan en paralelo en `.claude/settings.json` (Claude Code) y `.cursor/settings.json` (Cursor) con la misma logica parametrica.
|
|
240
|
+
|
|
241
|
+
### Gate de review en el push
|
|
242
|
+
|
|
243
|
+
```
|
|
244
|
+
┌──────────────────────────────┐
|
|
245
|
+
│ Dev ejecuta /refacil:up-code │
|
|
246
|
+
│ o git push manual │
|
|
247
|
+
└──────────────┬───────────────┘
|
|
248
|
+
│
|
|
249
|
+
┌──────────────────┴──────────────────┐
|
|
250
|
+
│ Via /refacil:up-code │ git push directo
|
|
251
|
+
▼ ▼
|
|
252
|
+
┌─────────────────────┐ ┌───────────────────────┐
|
|
253
|
+
│ up-code detecta │ │ Hook check-review │
|
|
254
|
+
│ falta .review-passed│ │ (PreToolUse en Bash) │
|
|
255
|
+
│ INVOCA /refacil: │ │ Verifica .review- │
|
|
256
|
+
│ review │ │ passed en changes/* │
|
|
257
|
+
└─────────┬───────────┘ └──────────┬────────────┘
|
|
258
|
+
│ │
|
|
259
|
+
▼ ▼
|
|
260
|
+
┌──────────────┐ ┌─────────────────┐
|
|
261
|
+
│ ¿Review OK? │ │ ¿Falta alguno? │
|
|
262
|
+
└──┬────────┬──┘ └──┬───────────┬──┘
|
|
263
|
+
SI│ NO│ SI│ NO│
|
|
264
|
+
▼ ▼ ▼ ▼
|
|
265
|
+
push OK informa + block + allow
|
|
266
|
+
no pushea instruccion push
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
### Hook `compact-bash` — rewrite silencioso de comandos
|
|
270
|
+
|
|
271
|
+
Segunda capa de reduccion de tokens, **sin costo conversacional**. Claude emite un comando Bash; antes de ejecutarlo, el hook lo inspecciona, y si matchea una regla lo reescribe via `updatedInput`. Claude no ve el cambio.
|
|
272
|
+
|
|
273
|
+
**Detector de intencion**: si el comando ya tiene flags explicitos (`git log -p`, `jest --watch`, `docker logs --tail 50`), el hook **no interviene** — tu intencion manda.
|
|
274
|
+
|
|
275
|
+
**Escape**: prefija `COMPACT=0` al comando (`COMPACT=0 git log`).
|
|
276
|
+
|
|
277
|
+
**Reglas activas — git, tests, docker logs**:
|
|
278
|
+
|
|
279
|
+
| Bare | Reescrito a | Ahorro |
|
|
280
|
+
|---|---|---|
|
|
281
|
+
| `git log` | `git log --oneline -20` | ~85% |
|
|
282
|
+
| `git status` | `git status -s` | ~70% |
|
|
283
|
+
| `git diff` (sin args) | `git diff --stat` | ~80% |
|
|
284
|
+
| `git show` | `git show --stat` | ~70% |
|
|
285
|
+
| `docker logs <c>` | `docker logs --tail 100 <c>` | ~80% |
|
|
286
|
+
| `npm test` / `yarn test` / `pnpm test` | `… 2>&1 \| tail -80` | ~90% |
|
|
287
|
+
| `jest` | `jest --silent --reporters=summary` | ~85% |
|
|
288
|
+
| `pytest` | `pytest -q` | ~60% |
|
|
289
|
+
|
|
290
|
+
**Reglas activas — linters, type checkers, build, sistema**:
|
|
291
|
+
|
|
292
|
+
| Bare | Reescrito a | Ahorro |
|
|
293
|
+
|---|---|---|
|
|
294
|
+
| `eslint` | `eslint . --format compact --quiet` | ~70% |
|
|
295
|
+
| `eslint <path>` | `eslint <path> --format compact` | ~60% |
|
|
296
|
+
| `biome check` | `biome check --reporter=summary` | ~65% |
|
|
297
|
+
| `tsc` / `npx tsc …` | `… 2>&1 \| head -80` | variable |
|
|
298
|
+
| `prettier --check <p>` | `prettier --check <p> --loglevel warn` | ~50% |
|
|
299
|
+
| `npm audit` | `npm audit 2>&1 \| tail -10` | ~80% |
|
|
300
|
+
| `npm ls` | `npm ls --depth=0` | ~90% |
|
|
301
|
+
| `cargo build / test / check` | `… --quiet` | ~50% |
|
|
302
|
+
| `go test …` (sin flags) | `… 2>&1 \| tail -80` | ~70% |
|
|
303
|
+
| `mvn test` | `mvn test -q` | ~60% |
|
|
304
|
+
| `./gradlew test` / `gradle test` | `… -q` | ~60% |
|
|
305
|
+
| `ps aux` | `ps -eo pid,pcpu,pmem,comm \| head -30` | ~80% |
|
|
306
|
+
|
|
307
|
+
**Telemetria**: cada rewrite genera una linea JSON en `~/.refacil-sdd-ai/compact.log` (local, nada viaja fuera). `compact stats` calcula ahorro en tokens y USD estimado (a $3/MTok input de Sonnet, conservador).
|
|
308
|
+
|
|
309
|
+
### Bloque `compact-guidance` en AGENTS.md
|
|
310
|
+
|
|
311
|
+
La metodologia SDD-AI genera mucho contexto (artefactos, specs, prompts). Para compensar, el paquete mantiene un bloque en `AGENTS.md` que instruye a la IA a pedir salidas compactas (Read con offset/limit, `git log --oneline`, tests solo con failures, etc.).
|
|
312
|
+
|
|
313
|
+
- Delimitado por `<!-- refacil-sdd-ai:compact-guidance:start -->` y `...:end -->`
|
|
314
|
+
- Fuente de verdad: `templates/compact-guidance.md`
|
|
315
|
+
- Sincroniza en: `init`, `update`, y hook `check-update` (cada SessionStart)
|
|
316
|
+
- Si `AGENTS.md` no existe, no se crea a espaldas del usuario
|
|
317
|
+
|
|
318
|
+
> **No editar manualmente** entre los marcadores. Se sobrescribe en la proxima sesion.
|
|
319
|
+
|
|
320
|
+
---
|
|
321
|
+
|
|
322
|
+
## Reglas metodologicas transversales
|
|
323
|
+
|
|
324
|
+
Definidas en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
|
|
325
|
+
|
|
326
|
+
- **Estados del flujo**: `READY_FOR_APPLY` / `VERIFY` / `REVIEW` / `ARCHIVE` / `MERGE` — cada transicion valida prerequisitos.
|
|
327
|
+
- **Politica de ramas**: toda rama nueva (`feature/*`, `fix/*`, etc.) se crea desde `develop`/`dev` actualizado. Integracion a ramas protegidas (`testing`, `develop`, `dev`, `main`, `master`, `qa`) siempre por PR. **Nunca** commits directos a `master`/`main`. Excepcion unica: repos sin `develop`/`dev`, donde se permite usar temporalmente `main` o `master` como base.
|
|
328
|
+
- **Tests multi-stack**: se detecta el comando real (no hardcodea `npm test`).
|
|
329
|
+
- **`AGENTS.md` por perfil** (`openspec` vs `agents`): la metodologia respeta ambos.
|
|
330
|
+
- **Modo de salida**: conciso por defecto, detallado bajo demanda.
|
|
331
|
+
|
|
332
|
+
---
|
|
333
|
+
|
|
334
|
+
## refacil-bus — chat room entre agentes
|
|
335
|
+
|
|
336
|
+
Bus local (WebSocket sobre `127.0.0.1`) para que los agentes de distintos repos se comuniquen por texto plano. **No comparte archivos, contexto ni tokens entre repos** — cada agente responde desde su propio codigo.
|
|
337
|
+
|
|
338
|
+
**Caso de uso principal**: un dev con varias ventanas de IDE abiertas (una por repo). Antes del bus, el dev hacia de transcriptor entre sus propios agentes. Con el bus, los agentes se hablan solos.
|
|
339
|
+
|
|
340
|
+
**Propiedades**:
|
|
341
|
+
|
|
342
|
+
- 100% local: nada sale de `127.0.0.1`. Sin cuentas, sin servicio compartido.
|
|
343
|
+
- Zero config: el broker se auto-arranca la primera vez que una skill lo necesita (`127.0.0.1:7821`, fallback 7822/7823).
|
|
344
|
+
- ~40 MB RAM, 0% CPU idle. Persistencia: `~/.refacil-sdd-ai/bus/<sala>/inbox.jsonl` (rotacion 7 dias).
|
|
345
|
+
- Mismas skills en Claude Code y Cursor.
|
|
346
|
+
|
|
347
|
+
**Arranque rapido**:
|
|
348
|
+
|
|
349
|
+
```bash
|
|
350
|
+
# En cada repo, una vez
|
|
351
|
+
/refacil:join refacil-main
|
|
352
|
+
# La primera vez el LLM escribe un bloque de presentacion en AGENTS.md
|
|
353
|
+
```
|
|
354
|
+
|
|
355
|
+
**Patron optimo**: antes de arrancar una tarea que puede requerir consultar otro repo, ir a la ventana del otro repo y decir *"atiende el bus"*. Eso lo pone en `/refacil:attend` y la conversacion entre agentes ocurre en background sin que el dev cambie de ventana.
|
|
356
|
+
|
|
357
|
+
**Observador puro** (0 tokens): `refacil-sdd-ai bus watch <session>` o `refacil-sdd-ai bus view` para la UI web.
|
|
358
|
+
|
|
359
|
+
> **Diagramas, escenarios y pitch**: ver [`refacil-bus-diagrams.md`](./refacil-bus-diagrams.md) — incluye arquitectura, flujo con attend, flujo sin attend, tabla comparativa de impacto y guia de decision visual (Mermaid).
|
|
360
|
+
>
|
|
361
|
+
|
|
362
|
+
### Limitaciones conocidas
|
|
363
|
+
|
|
364
|
+
- Mientras `/refacil:attend` esta activo, la sesion del IDE queda ocupada (abortar con ESC). Mitigacion: segunda ventana del mismo repo dedicada a atender.
|
|
365
|
+
- El LLM no recibe pushes externos: la automatizacion completa requiere que el receptor este en `attend`, o que el dev le pida `/refacil:inbox` despues.
|
|
366
|
+
- Sin autenticacion: cualquier proceso local puede conectar al broker (por diseño, solo loopback y bajo demanda del dev).
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## Que se instala en tu repo
|
|
371
|
+
|
|
372
|
+
```
|
|
373
|
+
.claude/skills/refacil-*/ # Skills Claude Code (incluye refacil-prereqs con OPENSPEC-DELTAS.md)
|
|
374
|
+
.claude/agents/refacil-*.md # Sub-agentes (auditor, investigator, validator)
|
|
375
|
+
.claude/settings.json # Hooks: check-update + check-review + compact-bash
|
|
376
|
+
.cursor/skills/refacil-*/ # Skills Cursor (equivalente)
|
|
377
|
+
.cursor/agents/refacil-*.md # Sub-agentes Cursor (readonly + model:inherit auto-generados)
|
|
378
|
+
.cursor/settings.json # Hooks: check-update + check-review + compact-bash (mirror de .claude/)
|
|
379
|
+
CLAUDE.md # Indice minimo → apunta a AGENTS.md
|
|
380
|
+
.cursorrules # Idem en formato Cursor
|
|
381
|
+
.claudeignore # Exclusiones base (node_modules, dist, .env, *.key, etc.)
|
|
382
|
+
.cursorignore # Idem — mismo contenido que .claudeignore
|
|
383
|
+
AGENTS.md # Indice del proyecto → generado por /refacil:setup
|
|
384
|
+
# Apunta a .agents/ + incluye bloques auto-gestionados
|
|
385
|
+
# (compact-guidance y bus presentation)
|
|
386
|
+
.agents/ # Detalle del proyecto por area (generado por /refacil:setup)
|
|
387
|
+
# summary.md, architecture.md, stack.md, testing.md, commands.md...
|
|
388
|
+
openspec/ # Generado por /refacil:setup via OpenSpec
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
---
|
|
392
|
+
|
|
393
|
+
## Tecnologias
|
|
394
|
+
|
|
395
|
+
- [OpenSpec](https://github.com/Fission-AI/OpenSpec) — framework de especificaciones
|
|
396
|
+
- [AGENTS.md](https://agents.md/) — estandar universal de instrucciones para IA
|
|
397
|
+
- [Claude Code](https://claude.ai/code) — CLI de Anthropic
|
|
398
|
+
- [Cursor](https://cursor.sh) — IDE con IA
|
|
399
|
+
|
|
400
|
+
## Licencia
|
|
401
|
+
|
|
402
|
+
MIT
|