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/skills/archive/SKILL.md
CHANGED
|
@@ -1,167 +1,191 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: refacil:archive
|
|
3
|
-
description: Archivar un cambio completado — mueve artefactos a archive y sincroniza specs
|
|
4
|
-
user-invocable: true
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# refacil:archive — Archivar Cambio Completado
|
|
8
|
-
|
|
9
|
-
Este comando envuelve la funcionalidad de OpenSpec archive (que internamente llama a sync-specs) y agrega verificaciones previas del equipo.
|
|
10
|
-
|
|
11
|
-
**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
|
|
12
|
-
|
|
13
|
-
## Instrucciones
|
|
14
|
-
|
|
15
|
-
### Paso 1: Verificaciones previas (aporte Refacil)
|
|
16
|
-
|
|
17
|
-
Antes de archivar, verifica que el cambio esta realmente completo:
|
|
18
|
-
|
|
19
|
-
1. **Tasks completadas**: Busca el `tasks.md` del cambio y verifica que todas las tasks tienen checkbox marcado (`[x]`). Si hay tasks sin completar, informa al usuario y pregunta si quiere continuar de todas formas.
|
|
20
|
-
|
|
21
|
-
2. **Tests pasan**: Resuelve y ejecuta el comando de tests segun `refacil-prereqs/METHODOLOGY-CONTRACT.md`. Si hay tests que fallan, informa y pregunta si quiere continuar.
|
|
22
|
-
|
|
23
|
-
3. **Sin archivos pendientes**: Ejecuta `git status` y verifica si hay cambios sin commitear relacionados al feature. Si los hay, sugiere hacer commit antes de archivar.
|
|
24
|
-
|
|
25
|
-
4. **Review aprobado (bloqueante)**: Verifica que existe el archivo `.review-passed` en la carpeta del cambio (`openspec/changes/[nombre-cambio]/.review-passed`). Si NO existe, **detener el archivado** e informar al usuario:
|
|
26
|
-
```
|
|
27
|
-
No se puede archivar: el cambio no tiene review aprobado.
|
|
28
|
-
Ejecuta /refacil:review primero.
|
|
29
|
-
```
|
|
30
|
-
Esta verificacion es **obligatoria y bloqueante** — no se puede saltar.
|
|
31
|
-
|
|
32
|
-
Si alguna de las verificaciones 1-3 falla, informa al usuario pero permite que decida si continuar.
|
|
33
|
-
Si la verificacion 4 falla, el archivado no puede continuar.
|
|
34
|
-
|
|
35
|
-
### Paso
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
- **
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
-
|
|
125
|
-
- Si
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
1
|
+
---
|
|
2
|
+
name: refacil:archive
|
|
3
|
+
description: Archivar un cambio completado — mueve artefactos a archive y sincroniza specs
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# refacil:archive — Archivar Cambio Completado
|
|
8
|
+
|
|
9
|
+
Este comando envuelve la funcionalidad de OpenSpec archive (que internamente llama a sync-specs) y agrega verificaciones previas del equipo.
|
|
10
|
+
|
|
11
|
+
**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
|
|
12
|
+
|
|
13
|
+
## Instrucciones
|
|
14
|
+
|
|
15
|
+
### Paso 1: Verificaciones previas (aporte Refacil)
|
|
16
|
+
|
|
17
|
+
Antes de archivar, verifica que el cambio esta realmente completo:
|
|
18
|
+
|
|
19
|
+
1. **Tasks completadas**: Busca el `tasks.md` del cambio y verifica que todas las tasks tienen checkbox marcado (`[x]`). Si hay tasks sin completar, informa al usuario y pregunta si quiere continuar de todas formas.
|
|
20
|
+
|
|
21
|
+
2. **Tests pasan**: Resuelve y ejecuta el comando de tests segun `refacil-prereqs/METHODOLOGY-CONTRACT.md`. Si hay tests que fallan, informa y pregunta si quiere continuar.
|
|
22
|
+
|
|
23
|
+
3. **Sin archivos pendientes**: Ejecuta `git status` y verifica si hay cambios sin commitear relacionados al feature. Si los hay, sugiere hacer commit antes de archivar.
|
|
24
|
+
|
|
25
|
+
4. **Review aprobado (bloqueante)**: Verifica que existe el archivo `.review-passed` en la carpeta del cambio (`openspec/changes/[nombre-cambio]/.review-passed`). Si NO existe, **detener el archivado** e informar al usuario:
|
|
26
|
+
```
|
|
27
|
+
No se puede archivar: el cambio no tiene review aprobado.
|
|
28
|
+
Ejecuta /refacil:review primero.
|
|
29
|
+
```
|
|
30
|
+
Esta verificacion es **obligatoria y bloqueante** — no se puede saltar.
|
|
31
|
+
|
|
32
|
+
Si alguna de las verificaciones 1-3 falla, informa al usuario pero permite que decida si continuar.
|
|
33
|
+
Si la verificacion 4 falla, el archivado no puede continuar.
|
|
34
|
+
|
|
35
|
+
### Paso 1.5: Solicitar links de Jira (trazabilidad — obligatorio)
|
|
36
|
+
|
|
37
|
+
Antes de proceder al archivado, solicita al usuario los links de Jira asociados al cambio:
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
Link de Jira asociado a este cambio (si son varios, sepáralos con comas):
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
**Reglas:**
|
|
44
|
+
- El usuario puede ingresar uno o múltiples links separados por comas en un solo mensaje.
|
|
45
|
+
- Si el usuario no proporciona ningún link (responde vacío, "n", "no", "ninguno", Enter en blanco), **bloquear el archivado** y volver a solicitar:
|
|
46
|
+
```
|
|
47
|
+
No se puede archivar sin al menos un link de Jira.
|
|
48
|
+
Proporciona el link de la tarea que originó este cambio para continuar.
|
|
49
|
+
```
|
|
50
|
+
- Repetir hasta recibir al menos una URL válida.
|
|
51
|
+
- Guardar los links en `jiraTasks` para usarlos al escribir `review.yaml` en los pasos siguientes.
|
|
52
|
+
|
|
53
|
+
### Paso 2: Determinar tipo de cambio
|
|
54
|
+
|
|
55
|
+
Inspecciona la carpeta del cambio en `openspec/changes/`:
|
|
56
|
+
|
|
57
|
+
- **Es un bug fix** si el nombre de la carpeta empieza con `fix-` (creado por `refacil:bug`).
|
|
58
|
+
- **Es un cambio regular** en cualquier otro caso (creado por `refacil:propose`).
|
|
59
|
+
|
|
60
|
+
Segun el tipo, sigue el paso correspondiente:
|
|
61
|
+
|
|
62
|
+
### Paso 2A: Bug fix → Archivado manual (sin OpenSpec)
|
|
63
|
+
|
|
64
|
+
Los bug fixes solo contienen `summary.md` (y opcionalmente `.review-passed`), no tienen los artefactos completos que OpenSpec espera. Por eso se archivan **sin delegar a OpenSpec**.
|
|
65
|
+
|
|
66
|
+
1. **Mover a archive (operacion de move, no copy)**: traslada la carpeta completa del fix desde `openspec/changes/[nombre-fix]/` a `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/`. La carpeta de origen **debe quedar eliminada** al finalizar.
|
|
67
|
+
|
|
68
|
+
Orden de ejecucion recomendado (determinista y cross-platform):
|
|
69
|
+
1. Asegurar que existe el directorio `openspec/changes/archive/` (crearlo si no existe).
|
|
70
|
+
2. Preferir un **move atomico** con `git mv "openspec/changes/[nombre-fix]" "openspec/changes/archive/[fecha-ISO]-[nombre-fix]"` cuando el fix ya esta bajo control de git (mueve y stagea de una).
|
|
71
|
+
3. Si `git mv` no aplica (archivos no trackeados o error), usar en su lugar:
|
|
72
|
+
- Linux/macOS: `mv "openspec/changes/[nombre-fix]" "openspec/changes/archive/[fecha-ISO]-[nombre-fix]"`
|
|
73
|
+
- Windows (bash de Claude Code): el mismo `mv` funciona sobre rutas POSIX (`/c/Users/...`). **No usar `cp -r` sin el `rm -rf` posterior** — es la causa raiz tipica del bug en que la carpeta de origen sobrevive.
|
|
74
|
+
4. **Verificacion obligatoria post-move**: ejecutar una listado/test de existencia para confirmar que:
|
|
75
|
+
- `openspec/changes/[nombre-fix]/` **ya NO existe**.
|
|
76
|
+
- `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/` **SI existe** y contiene `summary.md` (+ `.review-passed` si lo habia).
|
|
77
|
+
5. Si la verificacion falla (la carpeta de origen sobrevivio), eliminarla explicitamente con `rm -rf "openspec/changes/[nombre-fix]"` y re-verificar. No continuar al paso 2 hasta que el estado sea consistente.
|
|
78
|
+
|
|
79
|
+
2. **Documentar en specs**: Lee el `summary.md` y el `.review-passed` del fix (desde la ruta **archivada** en `openspec/changes/archive/[fecha-ISO]-[nombre-fix]/`, ya no desde la ruta original), y crea un spec individual para el bug en `openspec/specs/[nombre-descriptivo]/spec.md`.
|
|
80
|
+
|
|
81
|
+
**Nombre de la carpeta en specs**: Usa una descripcion corta y clara del bug en kebab-case (ej. `fix-session-timeout-redis`, `fix-null-pointer-payment-callback`). **NO uses IDs de tickets** (REF-123, JIRA-456, etc.) — el nombre debe ser descriptivo para que `/refacil:explore` pueda encontrar y entender el fix sin contexto externo.
|
|
82
|
+
|
|
83
|
+
Contenido del `spec.md` (formato OpenSpec estandar):
|
|
84
|
+
```markdown
|
|
85
|
+
# [nombre-descriptivo] Specification
|
|
86
|
+
|
|
87
|
+
## Purpose
|
|
88
|
+
Corregir [descripcion clara del bug] para restaurar el comportamiento esperado sin introducir regresiones.
|
|
89
|
+
|
|
90
|
+
## Requirements
|
|
91
|
+
### Requirement: [comportamiento esperado principal]
|
|
92
|
+
El sistema SHALL [comportamiento correcto despues del fix].
|
|
93
|
+
|
|
94
|
+
#### Scenario: Bug corregido en condicion original
|
|
95
|
+
- **WHEN** [condicion que antes fallaba]
|
|
96
|
+
- **THEN** el sistema SHALL [resultado esperado]
|
|
97
|
+
|
|
98
|
+
#### Scenario: Flujo normal permanece estable
|
|
99
|
+
- **WHEN** [condicion normal]
|
|
100
|
+
- **THEN** el sistema SHALL [comportamiento normal sin regresion]
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
3. **Persistir metadata de review separada**: crea `openspec/specs/[nombre-descriptivo]/review.yaml` con los campos de `.review-passed` más los links de Jira del Paso 1.5:
|
|
104
|
+
```yaml
|
|
105
|
+
verdict: APROBADO|APROBADO CON OBSERVACIONES
|
|
106
|
+
date: 2026-04-10T00:00:00.000Z
|
|
107
|
+
changeName: fix-...
|
|
108
|
+
summary: "..."
|
|
109
|
+
failCount: 0
|
|
110
|
+
blockers: false
|
|
111
|
+
jiraTasks:
|
|
112
|
+
- https://tu-empresa.atlassian.net/browse/REF-123
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
4. Continua al **Paso 3**.
|
|
116
|
+
|
|
117
|
+
### Paso 2B: Cambio regular → Delegar a OpenSpec archive
|
|
118
|
+
|
|
119
|
+
1. Lee `openspec-archive-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
|
|
120
|
+
2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **archive**).
|
|
121
|
+
3. Sigue OpenSpec con argumento **$ARGUMENTS** (sync de specs segun deltas).
|
|
122
|
+
|
|
123
|
+
4. **Verificar sincronizacion**: Despues de que OpenSpec archive, verifica que `openspec/specs/` fue actualizada:
|
|
124
|
+
- Revisa si hay archivos nuevos o modificados en `openspec/specs/`
|
|
125
|
+
- Si la sincronizacion no ocurrio (OpenSpec la salto o fallo), ejecuta manualmente:
|
|
126
|
+
- Lee la especificacion del cambio archivado: `specs.md` si existe **y** todos los `.md` bajo `specs/` de esa carpeta (misma regla que `refacil:apply`)
|
|
127
|
+
- Busca el spec principal relevante en `openspec/specs/`
|
|
128
|
+
- Si existe, integra los cambios (ADDED → agregar, MODIFIED → actualizar, REMOVED → eliminar)
|
|
129
|
+
- Si NO existe, crea un spec principal nuevo con nombre descriptivo
|
|
130
|
+
|
|
131
|
+
5. **Persistir evidencia de review en specs (obligatorio)**:
|
|
132
|
+
- Lee `openspec/changes/[nombre-cambio]/.review-passed` **antes** de mover/archivar (o desde la ruta archivada si ya fue movido).
|
|
133
|
+
- Toma sus campos (`verdict`, `date`, `summary`, `failCount`, `blockers`, `changeName`).
|
|
134
|
+
- Crea/actualiza `review.yaml` en cada carpeta de spec afectada (`openspec/specs/<spec-name>/review.yaml`).
|
|
135
|
+
- Formato de `review.yaml` (incluye `jiraTasks` del Paso 1.5):
|
|
136
|
+
```yaml
|
|
137
|
+
verdict: APROBADO|APROBADO CON OBSERVACIONES
|
|
138
|
+
date: 2026-04-10T00:00:00.000Z
|
|
139
|
+
changeName: nombre-del-cambio
|
|
140
|
+
summary: "..."
|
|
141
|
+
failCount: 0
|
|
142
|
+
blockers: false
|
|
143
|
+
jiraTasks:
|
|
144
|
+
- https://tu-empresa.atlassian.net/browse/REF-123
|
|
145
|
+
- https://tu-empresa.atlassian.net/browse/REF-124
|
|
146
|
+
```
|
|
147
|
+
- Si el cambio sincroniza multiples specs, crea/actualiza `review.yaml` en cada una con los mismos `jiraTasks`.
|
|
148
|
+
- Si el `review.yaml` ya existe, agregar/actualizar solo `jiraTasks` sin eliminar los demás campos.
|
|
149
|
+
- Si no se puede determinar con precision los specs afectados, crea/actualiza `openspec/specs/review-metadata.yaml` con un registro por cambio.
|
|
150
|
+
|
|
151
|
+
6. Continua al **Paso 3**.
|
|
152
|
+
|
|
153
|
+
El objetivo es que `openspec/specs/` documente como funciona el sistema HOY.
|
|
154
|
+
|
|
155
|
+
### Paso 3: Confirmar
|
|
156
|
+
|
|
157
|
+
Antes de mostrar el resumen, ejecutar una **verificacion final de limpieza** (aplica tanto a bug fixes como a cambios regulares):
|
|
158
|
+
|
|
159
|
+
- `openspec/changes/[nombre-original]/` **NO debe existir** (solo la version archivada debe sobrevivir en `openspec/changes/archive/...`).
|
|
160
|
+
- Si la carpeta de origen sobrevivio por cualquier razon (fallo del move, OpenSpec dejo residuos, copia en vez de mover), eliminarla explicitamente con `rm -rf "openspec/changes/[nombre-original]"` antes de confirmar al usuario.
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
=== Cambio archivado ===
|
|
164
|
+
Cambio: [nombre]
|
|
165
|
+
Tipo: [Bug fix | Cambio regular]
|
|
166
|
+
Ubicacion: openspec/changes/archive/[fecha]-[nombre]/
|
|
167
|
+
Carpeta original eliminada: SI
|
|
168
|
+
Specs sincronizadas: SI
|
|
169
|
+
Tests: PASS
|
|
170
|
+
|
|
171
|
+
El cambio ha sido completado y archivado exitosamente.
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Paso 4: Recomendar subir codigo
|
|
175
|
+
|
|
176
|
+
Despues de confirmar el archivado, recomienda al usuario subir los cambios al remoto:
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
El siguiente paso es subir el cambio y crear el PR.
|
|
180
|
+
Quieres que continue con /refacil:up-code?
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
## Reglas
|
|
184
|
+
|
|
185
|
+
- Siempre verificar completitud antes de archivar
|
|
186
|
+
- **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:up-code"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:up-code`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
|
|
187
|
+
- La sincronizacion de specs es OBLIGATORIA en la metodologia Refacil
|
|
188
|
+
- La metadata de `.review-passed` debe persistirse separada en YAML (`review.yaml`) dentro de cada carpeta de spec
|
|
189
|
+
- No eliminar artefactos, solo moverlos a archive/ para trazabilidad
|
|
190
|
+
- **La carpeta original en `openspec/changes/[nombre]/` NO debe sobrevivir al archivado** — ni para bug fixes (Paso 2A) ni para cambios regulares (Paso 2B). Usar `git mv` o `mv` (no `cp -r`) y verificar explicitamente. Si queda residuo, borrarlo con `rm -rf` antes del Paso 3.
|
|
191
|
+
- Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)
|
package/skills/guide/SKILL.md
CHANGED
|
@@ -28,7 +28,8 @@ Eres un guia **breve**: eliges el siguiente comando; el detalle de cada flujo es
|
|
|
28
28
|
6. Review de calidad → `/refacil:review`
|
|
29
29
|
7. Subir codigo y crear PR → `/refacil:up-code`
|
|
30
30
|
8. Configurar repo → `refacil-sdd-ai init` (global + por repo) y `/refacil:setup`
|
|
31
|
-
9.
|
|
31
|
+
9. Migrar documentacion al patron actual → `/refacil:update`
|
|
32
|
+
10. Coordinar con otros repos (sin copy/paste manual) → ver bloque **Bus entre agentes** abajo
|
|
32
33
|
|
|
33
34
|
> **Nota**: `/refacil:up-code` verifica que el review este aprobado (`.review-passed`). Si falta y hay un solo cambio pendiente, lanza `/refacil:review` automaticamente (sin re-ejecutar si no hay cambios nuevos). Si hay multiples cambios sin review, pide seleccion explicita. Toda integracion a ramas protegidas (incluyendo `testing`) requiere PR. Nunca se hacen ajustes directos en `master` o `main`. La validacion de rama se hace en `/refacil:apply` o `/refacil:bug`, no en `up-code`.
|
|
34
35
|
|
|
@@ -67,7 +68,8 @@ Detalle completo en el README de refacil-sdd-ai (seccion `refacil-bus`).
|
|
|
67
68
|
- Opcion 6 (Review de calidad) → `skill: "refacil:review"`
|
|
68
69
|
- Opcion 7 (Subir codigo y crear PR) → `skill: "refacil:up-code"`
|
|
69
70
|
- Opcion 8 (Configurar repo) → `skill: "refacil:setup"`
|
|
70
|
-
- Opcion 9 (
|
|
71
|
+
- Opcion 9 (Migrar documentacion) → `skill: "refacil:update"`
|
|
72
|
+
- Opcion 10 (Bus entre agentes) → `skill: "refacil:join"` (u otra del grupo `refacil:say`/`refacil:ask`/`refacil:reply`/`refacil:attend`/`refacil:inbox` segun la intencion expresada).
|
|
71
73
|
- Si la intencion no mapea exactamente a una opcion, NO invocar — listar opciones numeradas y pedir seleccion explicita.
|
|
72
74
|
|
|
73
75
|
No describirlo en texto ni esperar que el usuario escriba el comando. (Ver `METHODOLOGY-CONTRACT.md §5`.)
|
package/skills/setup/SKILL.md
CHANGED
|
@@ -1,91 +1,123 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: refacil:setup
|
|
3
|
-
description: Verificar e instalar OpenSpec, generar AGENTS.md y configurar el repositorio para la metodologia SDD-AI
|
|
4
|
-
user-invocable: true
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# refacil:setup — Configuracion del Repositorio
|
|
8
|
-
|
|
9
|
-
Guia al desarrollador **paso a paso**. Tras cada paso, informa resultado; si falla, **detente** y da el error. Fallos de instalacion o PATH: ver [troubleshooting.md](troubleshooting.md) en esta skill (`refacil-setup`).
|
|
10
|
-
|
|
11
|
-
## Proceso
|
|
12
|
-
|
|
13
|
-
### Paso 1: Node.js
|
|
14
|
-
|
|
15
|
-
`node --version` >= 20.19.0. Si no: indicar requisito y detener.
|
|
16
|
-
|
|
17
|
-
### Paso 2: OpenSpec
|
|
18
|
-
|
|
19
|
-
`openspec --version 2>&1`. Si falla: ofrecer `npm install -g @fission-ai/openspec@latest`, re-verificar. Si sigue fallando: **troubleshooting.md**.
|
|
20
|
-
|
|
21
|
-
### Paso 3: Perfil OpenSpec
|
|
22
|
-
|
|
23
|
-
```bash
|
|
24
|
-
openspec config set profile custom
|
|
25
|
-
openspec config set workflows "explore,new,continue,apply,ff,sync,archive,bulk-archive,verify,onboard"
|
|
26
|
-
openspec config list
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Debe verse `profile: custom` y los 10 workflows.
|
|
30
|
-
|
|
31
|
-
### Paso 4: Init en el repo
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
openspec init --tools claude,cursor
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
`openspec init` instala `opsx:*` en `.claude/` y `.cursor/`; convive con `refacil:*` — el equipo usa **refacil:*** como interfaz principal.
|
|
38
|
-
|
|
39
|
-
### Paso 5: `openspec/config.yaml`
|
|
40
|
-
|
|
41
|
-
Si no existe, crear con `language: spanish` (y comentario de terminos tecnicos en ingles). Si existe, asegurar `language: spanish`.
|
|
42
|
-
|
|
43
|
-
### Paso 6: Generar `AGENTS.md`
|
|
44
|
-
|
|
45
|
-
Analiza el repo y genera
|
|
46
|
-
|
|
47
|
-
**6.1 Analisis** — Lee si existen: `package.json`, `tsconfig*.json`, `nest-cli.json`, `angular.json`, `README.md`, eslint, jest, `ls` raiz, Docker, `.env.example`.
|
|
48
|
-
|
|
49
|
-
**6.2
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
**6.
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
1
|
+
---
|
|
2
|
+
name: refacil:setup
|
|
3
|
+
description: Verificar e instalar OpenSpec, generar AGENTS.md y configurar el repositorio para la metodologia SDD-AI
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# refacil:setup — Configuracion del Repositorio
|
|
8
|
+
|
|
9
|
+
Guia al desarrollador **paso a paso**. Tras cada paso, informa resultado; si falla, **detente** y da el error. Fallos de instalacion o PATH: ver [troubleshooting.md](troubleshooting.md) en esta skill (`refacil-setup`).
|
|
10
|
+
|
|
11
|
+
## Proceso
|
|
12
|
+
|
|
13
|
+
### Paso 1: Node.js
|
|
14
|
+
|
|
15
|
+
`node --version` >= 20.19.0. Si no: indicar requisito y detener.
|
|
16
|
+
|
|
17
|
+
### Paso 2: OpenSpec
|
|
18
|
+
|
|
19
|
+
`openspec --version 2>&1`. Si falla: ofrecer `npm install -g @fission-ai/openspec@latest`, re-verificar. Si sigue fallando: **troubleshooting.md**.
|
|
20
|
+
|
|
21
|
+
### Paso 3: Perfil OpenSpec
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
openspec config set profile custom
|
|
25
|
+
openspec config set workflows "explore,new,continue,apply,ff,sync,archive,bulk-archive,verify,onboard"
|
|
26
|
+
openspec config list
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Debe verse `profile: custom` y los 10 workflows.
|
|
30
|
+
|
|
31
|
+
### Paso 4: Init en el repo
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
openspec init --tools claude,cursor
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
`openspec init` instala `opsx:*` en `.claude/` y `.cursor/`; convive con `refacil:*` — el equipo usa **refacil:*** como interfaz principal.
|
|
38
|
+
|
|
39
|
+
### Paso 5: `openspec/config.yaml`
|
|
40
|
+
|
|
41
|
+
Si no existe, crear con `language: spanish` (y comentario de terminos tecnicos en ingles). Si existe, asegurar `language: spanish`.
|
|
42
|
+
|
|
43
|
+
### Paso 6: Generar `.agents/` y `AGENTS.md`
|
|
44
|
+
|
|
45
|
+
Analiza el repo y genera la estructura de documentacion. Si ya existen, pregunta si regenerar.
|
|
46
|
+
|
|
47
|
+
**6.1 Analisis** — Lee si existen: `package.json`, `tsconfig*.json`, `nest-cli.json`, `angular.json`, `README.md`, eslint, jest, `ls` raiz, Docker, `.env.example`.
|
|
48
|
+
|
|
49
|
+
**6.2 Arquitectura obligatoria: carpeta `.agents/` + indice `AGENTS.md`**
|
|
50
|
+
|
|
51
|
+
Siempre genera esta estructura — nunca un archivo monolitico:
|
|
52
|
+
|
|
53
|
+
Crea la carpeta `.agents/` con un archivo `.md` por area tematica. Archivos tipicos (adaptar al proyecto real):
|
|
54
|
+
- `.agents/summary.md` — descripcion breve, tabla (lenguaje, framework, tests, package manager), scripts esenciales con una frase, reglas criticas condensadas (Siempre / Nunca / Preguntar, max 5 bullets cada bloque).
|
|
55
|
+
- `.agents/architecture.md` — modulos, servicios, flujos principales, patrones clave.
|
|
56
|
+
- `.agents/stack.md` — dependencias, variables de entorno, bases de datos, integraciones.
|
|
57
|
+
- `.agents/testing.md` — estrategia, comandos, convenciones, fixtures.
|
|
58
|
+
- `.agents/commands.md` — comandos de desarrollo, alias, scripts de CI/CD.
|
|
59
|
+
|
|
60
|
+
Un monorepo puede agregar `.agents/services.md`; una libreria puede combinar testing en stack. Adaptar segun el proyecto.
|
|
61
|
+
|
|
62
|
+
`AGENTS.md` es el **indice puro** — no contiene detalle de proyecto, solo:
|
|
63
|
+
1. Una linea de descripcion del proyecto.
|
|
64
|
+
2. Por cada archivo en `.agents/`: nombre del area + enlace relativo + cuando leer ese archivo (una frase).
|
|
65
|
+
3. Bloque `compact-guidance` (auto-gestionado por `refacil-sdd-ai`, no editar).
|
|
66
|
+
|
|
67
|
+
**6.3 Fallback** — Si el analisis falla: crear `.agents/summary.md` con resumen minimo + tabla refacil + TODOs, y `AGENTS.md` como indice apuntando a ese unico archivo.
|
|
68
|
+
|
|
69
|
+
**6.4** — Muestra el resultado al usuario; si aprueba, escribe los archivos.
|
|
70
|
+
|
|
71
|
+
**6.5 Bloque compact-guidance**:
|
|
72
|
+
- `refacil-sdd-ai` inyecta en `AGENTS.md` un bloque entre marcadores `compact-guidance` con reglas de salida compacta.
|
|
73
|
+
- Se sincroniza automaticamente en cada `SessionStart`. No editar el contenido entre marcadores.
|
|
74
|
+
|
|
75
|
+
### Paso 6b: Sobreescribir `CLAUDE.md` y `.cursorrules`
|
|
76
|
+
|
|
77
|
+
Siempre **sobreescribe** ambos archivos aunque ya existan — son indices delgados hacia `AGENTS.md`, no deben contener detalle de proyecto.
|
|
78
|
+
|
|
79
|
+
**`CLAUDE.md`** — indice minimo, sin contenido de proyecto:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
# CLAUDE.md
|
|
83
|
+
|
|
84
|
+
Contexto completo del proyecto: ver `AGENTS.md` (indice) y `.agents/` (detalle por area).
|
|
85
|
+
Si `AGENTS.md` no existe, ejecuta `/refacil:setup`.
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**`.cursorrules`** — contenido identico con header `# Cursor Rules`.
|
|
89
|
+
|
|
90
|
+
Todo el detalle de proyecto, stack, reglas y comandos `refacil:*` vive en `.agents/` y se indexa desde `AGENTS.md`. No duplicar nada en CLAUDE.md ni en .cursorrules.
|
|
91
|
+
|
|
92
|
+
### Paso 7: Archivos de exclusion de contexto
|
|
93
|
+
|
|
94
|
+
`refacil-sdd-ai init` crea o actualiza automaticamente `.claudeignore` y `.cursorignore` con entradas estandar (node_modules/, dist/, logs, binarios, secretos, etc.).
|
|
95
|
+
|
|
96
|
+
Si los archivos ya existen, solo se agregan las entradas faltantes — no se sobreescribe contenido personalizado.
|
|
97
|
+
|
|
98
|
+
Informa el resultado al usuario:
|
|
99
|
+
- **Creados**: ambos archivos fueron creados desde cero.
|
|
100
|
+
- **Actualizados**: se agregaron entradas faltantes.
|
|
101
|
+
- **Sin cambios**: ya tenian todas las entradas.
|
|
102
|
+
|
|
103
|
+
Si el usuario quiere personalizar exclusiones adicionales, puede editarlos directamente despues del setup.
|
|
104
|
+
|
|
105
|
+
### Paso 8: Verificar skills
|
|
106
|
+
|
|
107
|
+
- OpenSpec: 10 carpetas bajo `.claude/skills/` y `.cursor/skills/`: `openspec-apply-change`, `openspec-archive-change`, `openspec-bulk-archive-change`, `openspec-continue-change`, `openspec-explore`, `openspec-ff-change`, `openspec-new-change`, `openspec-onboard`, `openspec-sync-specs`, `openspec-verify-change`. Si falta alguna: sugerir `openspec init --tools claude,cursor` o `openspec config list`.
|
|
108
|
+
- Refacil: carpetas `refacil-*` en esas rutas. Si no: `refacil-sdd-ai init` + reiniciar sesion.
|
|
109
|
+
|
|
110
|
+
### Paso 9: Resumen final
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
=== refacil:setup completado ===
|
|
114
|
+
Node.js / OpenSpec / perfil / openspec/ / config / AGENTS.md / CLAUDE.md / .cursorrules / .claudeignore / .cursorignore / skills OK
|
|
115
|
+
|
|
116
|
+
Reiniciar sesion Claude Code o Cursor si es la primera instalacion de skills.
|
|
117
|
+
El siguiente paso es revisar el flujo disponible.
|
|
118
|
+
Quieres que continue con /refacil:guide?
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## Reglas
|
|
122
|
+
|
|
123
|
+
- **Continuidad del flujo**: si el usuario confirma afirmativamente ("si", "ok", "dale", "continua", etc.) la pregunta de continuidad del Paso 9, invocar inmediatamente el **Skill tool** con `skill: "refacil:guide"`. No describirlo en texto ni esperar que el usuario escriba `/refacil:guide`. (Ver `METHODOLOGY-CONTRACT.md §5`.)
|