sdd-es 2.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/.claude/settings.json +51 -0
- package/.claude-plugin/marketplace.json +31 -0
- package/.claude-plugin/plugin.json +97 -0
- package/README.md +332 -0
- package/agents/arquitecto.md +148 -0
- package/agents/asesor-datos.md +163 -0
- package/agents/critico.md +142 -0
- package/agents/desarrollador-backend.md +242 -0
- package/agents/desarrollador-frontend.md +120 -0
- package/agents/disenador-api.md +108 -0
- package/agents/documentador.md +177 -0
- package/agents/investigador.md +174 -0
- package/agents/operaciones.md +105 -0
- package/agents/revisor.md +153 -0
- package/agents/seguridad.md +216 -0
- package/agents/tester.md +286 -0
- package/claude-hooks/post-write-conventions.js +412 -0
- package/claude-hooks/pre-tool-guard.js +159 -0
- package/cli/index.js +401 -0
- package/commands/sdd.aclarar.md +200 -0
- package/commands/sdd.analizar.md +241 -0
- package/commands/sdd.ayuda.md +227 -0
- package/commands/sdd.canary.md +60 -0
- package/commands/sdd.checklist.md +174 -0
- package/commands/sdd.comprimir.md +166 -0
- package/commands/sdd.configurar.md +195 -0
- package/commands/sdd.constitucion.md +343 -0
- package/commands/sdd.crear-app.md +168 -0
- package/commands/sdd.crear-mcp.md +174 -0
- package/commands/sdd.descubrir.md +269 -0
- package/commands/sdd.desplegar.md +155 -0
- package/commands/sdd.especificar.md +302 -0
- package/commands/sdd.estado.md +124 -0
- package/commands/sdd.glosario.md +108 -0
- package/commands/sdd.implementar.md +377 -0
- package/commands/sdd.importar.md +91 -0
- package/commands/sdd.mapear.md +120 -0
- package/commands/sdd.md +119 -0
- package/commands/sdd.planificar.md +372 -0
- package/commands/sdd.qa.md +108 -0
- package/commands/sdd.release.md +253 -0
- package/commands/sdd.retro.md +82 -0
- package/commands/sdd.snapshot.md +122 -0
- package/commands/sdd.tareas.md +300 -0
- package/commands/sdd.verificar.md +239 -0
- package/configuracion-ejemplo/hooks-ejemplo/antes_cada_tarea.sh +18 -0
- package/configuracion-ejemplo/hooks-ejemplo/antes_implementar.sh +45 -0
- package/configuracion-ejemplo/hooks-ejemplo/despues_especificar.sh +14 -0
- package/configuracion-ejemplo/hooks-ejemplo/despues_implementar.sh +36 -0
- package/configuracion-ejemplo/hooks-ejemplo/despues_planificar.sh +19 -0
- package/configuracion-ejemplo/hooks-ejemplo/guardia-seguridad.sh +367 -0
- package/configuracion-ejemplo/sdd.config.yaml +310 -0
- package/docs/AGENTES.md +74 -0
- package/docs/COMPRESION.md +155 -0
- package/docs/EJEMPLO-PRACTICA.md +383 -0
- package/docs/EJEMPLOS.md +212 -0
- package/docs/FABRICA.md +185 -0
- package/docs/FILOSOFIA.md +61 -0
- package/docs/FLUJO.md +149 -0
- package/docs/INICIO-RAPIDO.md +116 -0
- package/docs/MAPAS.md +113 -0
- package/docs/MODELOS.md +103 -0
- package/docs/PERSONALIZACION.md +152 -0
- package/instalar.ps1 +39 -0
- package/instalar.sh +22 -0
- package/mcp-figma/README.md +158 -0
- package/mcp-figma/package.json +7 -0
- package/mcp-figma/src/component-generator.js +162 -0
- package/mcp-figma/src/design-system-analyzer.js +247 -0
- package/mcp-figma/src/figma-client.js +75 -0
- package/mcp-figma/src/index.js +114 -0
- package/mcp-figma/src/mcp.js +97 -0
- package/mcp-figma/src/style-mapper.js +85 -0
- package/package.json +50 -0
- package/plantillas/analisis.md +57 -0
- package/plantillas/checklist-especificacion.md +66 -0
- package/plantillas/constitucion.md +104 -0
- package/plantillas/decision-arquitectura.md +39 -0
- package/plantillas/dependencias-mapa.md +89 -0
- package/plantillas/especificacion.md +108 -0
- package/plantillas/estructura-mapa.md +40 -0
- package/plantillas/glosario.md +22 -0
- package/plantillas/index-especificaciones.md +15 -0
- package/plantillas/mcp-server.md +147 -0
- package/plantillas/plan.md +152 -0
- package/plantillas/simbolos-mapa.md +57 -0
- package/plantillas/snapshot.md +54 -0
- package/plantillas/tareas.md +72 -0
- package/presets/enterprise.yaml +69 -0
- package/presets/lean.yaml +63 -0
- package/presets/startup.yaml +67 -0
- package/skills/compresion-tokens.md +264 -0
- package/skills/constitucion-constraint.md +78 -0
- package/skills/deteccion-stack.md +175 -0
- package/skills/enrutador-agentes.md +69 -0
- package/skills/gestion-estado.md +114 -0
- package/skills/indexador.md +199 -0
- package/skills/modo-guiado/SKILL.md +78 -0
- package/skills/orquestacion-ptc/SKILL.md +96 -0
- package/skills/validacion-spec.md +52 -0
- package/skills/verificador-implementacion.md +71 -0
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Gestiona el estado persistente del flujo SDD entre sesiones. Lee y escribe estado.json y .estado-tareas.json. Permite reanudar exactamente donde se dejó.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Skill: Gestión de Estado
|
|
6
|
+
|
|
7
|
+
## Schemas
|
|
8
|
+
|
|
9
|
+
### Estado global (`.sdd/estado.json`)
|
|
10
|
+
|
|
11
|
+
```json
|
|
12
|
+
{
|
|
13
|
+
"version_plugin": "2.0.0",
|
|
14
|
+
"version_constitucion": "1.0.0",
|
|
15
|
+
"inicializado": true,
|
|
16
|
+
"fase_actual": "implementacion",
|
|
17
|
+
"stack_detectado": { ... },
|
|
18
|
+
"especificacion_activa": "2026-06-08-feature-x",
|
|
19
|
+
"plan_aprobado": true,
|
|
20
|
+
"tareas_generadas": true,
|
|
21
|
+
"historial": [
|
|
22
|
+
{
|
|
23
|
+
"fase": "constitucion",
|
|
24
|
+
"version": "1.0.0",
|
|
25
|
+
"fecha": "2026-06-01T10:00:00Z"
|
|
26
|
+
},
|
|
27
|
+
{
|
|
28
|
+
"fase": "especificacion",
|
|
29
|
+
"id": "2026-06-08-feature-x",
|
|
30
|
+
"fecha": "2026-06-08T14:30:00Z"
|
|
31
|
+
}
|
|
32
|
+
],
|
|
33
|
+
"fecha_inicio": "2026-06-01T10:00:00Z",
|
|
34
|
+
"ultima_actualizacion": "2026-06-08T15:00:00Z"
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Estado de tareas por spec (`.sdd/especificaciones/{ID}/.estado-tareas.json`)
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"spec_id": "2026-06-08-feature-x",
|
|
43
|
+
"total": 10,
|
|
44
|
+
"completadas": 6,
|
|
45
|
+
"en_progreso": "T007",
|
|
46
|
+
"bloqueadas": 0,
|
|
47
|
+
"tareas": {
|
|
48
|
+
"T001": {
|
|
49
|
+
"estado": "completada",
|
|
50
|
+
"agente": "arquitecto",
|
|
51
|
+
"modelo": "opus",
|
|
52
|
+
"depende_de": [],
|
|
53
|
+
"cubre_cas": ["CA-001-01"],
|
|
54
|
+
"archivos_modificados": ["src/types.ts"],
|
|
55
|
+
"fecha_inicio": "2026-06-08T14:35:00Z",
|
|
56
|
+
"fecha_fin": "2026-06-08T14:50:00Z"
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
"bloqueos": {},
|
|
60
|
+
"ultima_actualizacion": "2026-06-08T15:00:00Z"
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Operaciones
|
|
65
|
+
|
|
66
|
+
### leer_estado_global()
|
|
67
|
+
```bash
|
|
68
|
+
cat .sdd/estado.json 2>/dev/null || echo '{"inicializado": false}'
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
### actualizar_estado_global(patch)
|
|
72
|
+
Lee el estado actual, hace merge con el patch, escribe de vuelta. Siempre actualiza `ultima_actualizacion`.
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
# Pseudocódigo
|
|
76
|
+
ESTADO=$(cat .sdd/estado.json)
|
|
77
|
+
NUEVO=$(echo "$ESTADO" | jq '. * $patch | .ultima_actualizacion = now | tostring' --argjson patch "$PATCH")
|
|
78
|
+
echo "$NUEVO" > .sdd/estado.json
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### obtener_spec_activa()
|
|
82
|
+
```bash
|
|
83
|
+
grep -o '"especificacion_activa": "[^"]*"' .sdd/estado.json | cut -d'"' -f4
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### marcar_tarea(spec_id, tarea_id, estado, metadata)
|
|
87
|
+
Actualiza `.estado-tareas.json` y la barra de progreso en `tareas.md`.
|
|
88
|
+
|
|
89
|
+
### registrar_historial(fase, id, resultado)
|
|
90
|
+
Añade entrada al array `historial`.
|
|
91
|
+
|
|
92
|
+
## Reanudación entre sesiones
|
|
93
|
+
|
|
94
|
+
Cuando un comando SDD inicia con spec activa:
|
|
95
|
+
|
|
96
|
+
1. Lee estado global
|
|
97
|
+
2. Lee estado de tareas de la spec activa
|
|
98
|
+
3. Determina exactamente dónde quedó
|
|
99
|
+
4. Ofrece reanudar:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
🔄 Sesión anterior detectada.
|
|
103
|
+
Spec: {ID} (fase: implementacion)
|
|
104
|
+
Última tarea completada: T007
|
|
105
|
+
Tarea pendiente: T008
|
|
106
|
+
|
|
107
|
+
¿Continuar desde T008?
|
|
108
|
+
sí → /sdd.implementar continuar
|
|
109
|
+
no → /sdd.estado para ver detalle
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Concurrencia
|
|
113
|
+
|
|
114
|
+
El plugin asume **un único proceso/usuario** modificando el estado a la vez. Si necesitas multi-usuario, los hooks pueden agregar locking.
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Detecta lenguajes del proyecto y genera mapas estáticos (estructura, símbolos, dependencias) usando regex por lenguaje. Se invoca por /sdd.mapear.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Skill: Indexador de Proyecto
|
|
6
|
+
|
|
7
|
+
Analiza el código del proyecto sin dependencias externas (solo bash + grep + find) y genera 3 mapas estáticos en `.sdd/mapa/`.
|
|
8
|
+
|
|
9
|
+
## Proceso
|
|
10
|
+
|
|
11
|
+
### Paso 1: Detectar lenguajes
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
find . -type f -name "*.{ts,js,py,rs,go,java,cs,rb,php}" \
|
|
15
|
+
-not -path './.git/*' -not -path './node_modules/*' -not -path './.sdd/*' \
|
|
16
|
+
-not -path './dist/*' -not -path './build/*' \
|
|
17
|
+
| sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Resultado: lista de lenguajes presentes + frecuencia.
|
|
21
|
+
|
|
22
|
+
### Paso 2: Generar estructura.md
|
|
23
|
+
|
|
24
|
+
Árbol de directorios con descripciones por archivo.
|
|
25
|
+
|
|
26
|
+
Para cada archivo, extrae:
|
|
27
|
+
- Ruta
|
|
28
|
+
- 1 línea de descripción (automática o manual)
|
|
29
|
+
|
|
30
|
+
Descripción automática por lenguaje:
|
|
31
|
+
|
|
32
|
+
| Patrón de archivo | Descripción automática |
|
|
33
|
+
|------------------|------------------------|
|
|
34
|
+
| `*/service.ts` | Servicio: [nombre extraído] |
|
|
35
|
+
| `*/controller.ts` | HTTP: [métodos detectados] |
|
|
36
|
+
| `*/repo.ts`, `*/repository.ts` | Repositorio: acceso a BD |
|
|
37
|
+
| `*/types.ts`, `*.types.ts` | Tipos: [enums/interfaces detectados] |
|
|
38
|
+
| `*/index.ts` | Exporta símbolos públicos |
|
|
39
|
+
| `auth/` | Autenticación y autorización |
|
|
40
|
+
| `components/` | Componentes UI |
|
|
41
|
+
| `models/` | Modelos de datos |
|
|
42
|
+
| `utils/` | Utilidades y helpers |
|
|
43
|
+
| `tests/`, `__tests__/`, `spec/` | Tests y specs |
|
|
44
|
+
|
|
45
|
+
### Paso 3: Generar símbolos.md
|
|
46
|
+
|
|
47
|
+
Símbolos públicos (funciones, clases, tipos) por archivo.
|
|
48
|
+
|
|
49
|
+
Detección por lenguaje con regex:
|
|
50
|
+
|
|
51
|
+
**TypeScript/JavaScript**:
|
|
52
|
+
```regex
|
|
53
|
+
^export (function|class|const|type|interface|enum) (\w+)
|
|
54
|
+
→ extrae nombre + tipo
|
|
55
|
+
→ grep -nE '^export (function|const|class|type)' archivo.ts
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Python**:
|
|
59
|
+
```regex
|
|
60
|
+
^(def|class) (\w+)
|
|
61
|
+
→ funciones y clases en módulo principal
|
|
62
|
+
→ grep -nE '^(def|class) ' archivo.py
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Rust**:
|
|
66
|
+
```regex
|
|
67
|
+
^(pub fn|pub struct|pub enum|pub trait)
|
|
68
|
+
→ ítems públicos
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Go**:
|
|
72
|
+
```regex
|
|
73
|
+
^func ([A-Z]\w+)
|
|
74
|
+
→ funciones exportadas (mayúscula inicial)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Paso 4: Generar dependencias.md
|
|
78
|
+
|
|
79
|
+
Extrae imports/requires/use por archivo.
|
|
80
|
+
|
|
81
|
+
**TypeScript/JavaScript**:
|
|
82
|
+
```regex
|
|
83
|
+
^import .* from ['"]([^'"]+)['"]
|
|
84
|
+
^import .* require(['"]([^'"]+)['"])
|
|
85
|
+
→ extrae ruta del módulo
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
**Python**:
|
|
89
|
+
```regex
|
|
90
|
+
^import (\w+)
|
|
91
|
+
^from (\w+) import
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
**Rust**:
|
|
95
|
+
```regex
|
|
96
|
+
^use (crate::|super::|std::)?(\w+)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
Luego construye grafo:
|
|
100
|
+
- archivo.ts depende de: [lista de archivos/módulos importados]
|
|
101
|
+
- archivo.ts es usado por: [archivos que lo importan]
|
|
102
|
+
|
|
103
|
+
Detecta dependencias circulares (A → B → A).
|
|
104
|
+
|
|
105
|
+
### Paso 5: Guardar checksums
|
|
106
|
+
|
|
107
|
+
Para detección de cambios:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
md5sum archivo.ts > .sdd/mapa/.checksums
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Próxima ejecución compara:
|
|
114
|
+
```bash
|
|
115
|
+
md5sum -c .sdd/mapa/.checksums 2>/dev/null | grep FAILED
|
|
116
|
+
→ archivos modificados desde último mapeo
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Lógica de actualización
|
|
120
|
+
|
|
121
|
+
### Primera ejecución
|
|
122
|
+
- Re-indexa TODO el proyecto
|
|
123
|
+
- Genera los 3 mapas + `.checksums`
|
|
124
|
+
|
|
125
|
+
### Ejecuciones posteriores (sin `regenerar`)
|
|
126
|
+
|
|
127
|
+
1. Compara checksums: `md5sum -c`
|
|
128
|
+
2. Si hay archivos con FAILED: re-indexa solo esos
|
|
129
|
+
3. Si no hay cambios: "ya fresco"
|
|
130
|
+
4. Si hay archivos NUEVOS (no en checksums): indexa también
|
|
131
|
+
|
|
132
|
+
### Con `regenerar`
|
|
133
|
+
|
|
134
|
+
- Borra `.sdd/mapa/*` completamente
|
|
135
|
+
- Empieza de cero
|
|
136
|
+
- Re-indexa TODO
|
|
137
|
+
|
|
138
|
+
## Errores comunes y manejo
|
|
139
|
+
|
|
140
|
+
| Error | Mitigación |
|
|
141
|
+
|-------|-----------|
|
|
142
|
+
| Proyecto muy grande (>5000 archivos) | Capa un máximo de 2000, avisa al usuario |
|
|
143
|
+
| Archivo binario en src/ | Detecta por magic bytes, lo salta |
|
|
144
|
+
| Import dinámico (`require(variable)`) | Detecta patrón, marca como "???" |
|
|
145
|
+
| Ruta relativa confusa (`../../`) | Resuelve a path absoluto |
|
|
146
|
+
|
|
147
|
+
## Output de la skill
|
|
148
|
+
|
|
149
|
+
Tres archivos `.sdd/mapa/`:
|
|
150
|
+
|
|
151
|
+
```markdown
|
|
152
|
+
# estructura.md
|
|
153
|
+
src/
|
|
154
|
+
├── auth/
|
|
155
|
+
│ ├── login.service.ts — Servicio: autenticación local+JWT
|
|
156
|
+
│ ├── magic-link.service.ts — Servicio: magic links por email
|
|
157
|
+
│ └── ...
|
|
158
|
+
├── users/
|
|
159
|
+
│ └── ...
|
|
160
|
+
└── shared/
|
|
161
|
+
└── logger.ts — Utilidad: logger con contexto
|
|
162
|
+
|
|
163
|
+
# simbolos.md
|
|
164
|
+
## src/auth/login.service.ts
|
|
165
|
+
- autenticarUsuario(email, password): Promise<Session>
|
|
166
|
+
- cerrarSesion(sessionId): Promise<void>
|
|
167
|
+
- type AuthResult = { session, user }
|
|
168
|
+
|
|
169
|
+
## src/users/user.service.ts
|
|
170
|
+
- crearUsuario(datos): Promise<User>
|
|
171
|
+
- obtenerPorId(id): Promise<User>
|
|
172
|
+
- ...
|
|
173
|
+
|
|
174
|
+
# dependencias.md
|
|
175
|
+
auth/login.service.ts
|
|
176
|
+
↳ depende: users/user.repo.ts, shared/logger.ts, auth/session.repo.ts
|
|
177
|
+
↳ usado por: auth/auth.controller.ts
|
|
178
|
+
↳ importado por: [1 archivo]
|
|
179
|
+
|
|
180
|
+
users/user.service.ts
|
|
181
|
+
↳ depende: users/user.repo.ts, shared/logger.ts
|
|
182
|
+
↳ usado por: users/user.controller.ts, auth/login.service.ts
|
|
183
|
+
↳ importado por: [2 archivos]
|
|
184
|
+
|
|
185
|
+
Acoplamientos:
|
|
186
|
+
shared/logger.ts → 47 usos (alto, esperado)
|
|
187
|
+
errors.ts → 23 usos (medio)
|
|
188
|
+
|
|
189
|
+
Ciclos detectados: NINGUNO ✅
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
## Limitaciones honestas
|
|
193
|
+
|
|
194
|
+
- ❌ **Imports dinámicos no detectados**: `require(variable)` no se indexa
|
|
195
|
+
- ⚠️ **Descripciones manuales perdidas**: si habías editado `.md`, regenerar sobrescribe. Por eso existe `.original.md`
|
|
196
|
+
- ⚠️ **Lenguajes políglotas complejos**: monorepositorio con 5 lenguajes → cada uno con sus reglas
|
|
197
|
+
- ❌ **Análisis de tipos**: no sigue tipos a través de funciones, solo detecta firmas
|
|
198
|
+
|
|
199
|
+
Estos son trade-offs aceptables para una solución sin dependencias.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: modo-guiado
|
|
3
|
+
description: Conduce el flujo SDD-ES para personas que no programan (perfil guiado). Define cómo hablar sin jerga, cuándo confirmar antes de actuar, y cómo tomar las decisiones técnicas por el usuario sin bajar el rigor. Se activa cuando estado.json o sdd.config.yaml indican perfil "guiado".
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Skill: Modo Guiado (para no-programadores)
|
|
7
|
+
|
|
8
|
+
Esta skill cambia **cómo te comunicas**, no **qué tan bien construyes**. El producto generado mantiene los mismos estándares altos (tests, lint, sin secretos en el código, revisión independiente). Lo único que cambia es que el usuario no toma decisiones técnicas ni ve jerga.
|
|
9
|
+
|
|
10
|
+
## Cuándo se activa
|
|
11
|
+
|
|
12
|
+
- `estado.json` tiene `"perfil": "guiado"`, **o**
|
|
13
|
+
- `sdd.config.yaml` tiene `perfil: guiado`, **o**
|
|
14
|
+
- El usuario describe el producto por su función ("quiero una app que…") y no por su tecnología.
|
|
15
|
+
|
|
16
|
+
Comprobación rápida:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
grep -q '"perfil": *"guiado"' .sdd/estado.json 2>/dev/null && echo GUIADO
|
|
20
|
+
grep -q '^perfil: *guiado' .sdd/sdd.config.yaml 2>/dev/null && echo GUIADO
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## Reglas de comunicación (las 6 reglas)
|
|
24
|
+
|
|
25
|
+
1. **Sin jerga.** Nunca digas "endpoint", "schema", "ORM", "deploy", "lint", "CI". Di "dirección donde vive el dato", "estructura de la información", "guardar en disco", "publicar en internet", "revisión automática de calidad". Si un término técnico es inevitable, defínelo en la misma frase con una analogía.
|
|
26
|
+
|
|
27
|
+
2. **Confirma antes de actuar.** Antes de cada paso con consecuencias (crear archivos, instalar, publicar), explica en UNA frase qué vas a hacer y espera un "sí". Ejemplo: *"Voy a construir las pantallas y la lógica. ¿Arranco? (responde sí)"*.
|
|
28
|
+
|
|
29
|
+
3. **Nunca pidas que edite archivos a mano.** El usuario no abre el editor. Si algo necesita un valor (ej. una clave de un servicio), pídeselo en lenguaje natural y tú lo colocas donde va.
|
|
30
|
+
|
|
31
|
+
4. **Decide lo técnico por el usuario, y dilo.** Elige el stack, la arquitectura y las librerías. Comunica la decisión en una línea con el *porqué* en términos de beneficio, no de tecnología: *"Lo haré con una base de datos que vive en un solo archivo: así es fácil de respaldar y no necesitas instalar nada extra."*
|
|
32
|
+
|
|
33
|
+
5. **Una pregunta a la vez.** Nada de cuestionarios. Pregunta lo mínimo, sigue, y vuelve a preguntar solo si hace falta.
|
|
34
|
+
|
|
35
|
+
6. **Explica el resultado en términos de lo que el usuario puede hacer ahora.** Al terminar un paso: *"Ya puedes crear tareas y marcarlas como hechas. ¿Quieres que lo publiquemos en internet para usarlo desde el móvil?"* — no *"implementé el CRUD con 14 tests, cobertura 87%"*.
|
|
36
|
+
|
|
37
|
+
## Cómo traducir los pasos del flujo
|
|
38
|
+
|
|
39
|
+
| Paso técnico interno | Cómo lo nombras al usuario |
|
|
40
|
+
|----------------------|----------------------------|
|
|
41
|
+
| `/sdd.especificar` | "Voy a entender bien qué quieres" |
|
|
42
|
+
| `/sdd.aclarar` | "Tengo un par de dudas para no equivocarme" |
|
|
43
|
+
| `/sdd.planificar` | "Estoy decidiendo cómo construirlo" |
|
|
44
|
+
| `/sdd.tareas` | (no se menciona — es interno) |
|
|
45
|
+
| `/sdd.implementar` | "Lo estoy construyendo" |
|
|
46
|
+
| `/sdd.qa` + `/sdd.verificar` | "Estoy probando que todo funcione de verdad" |
|
|
47
|
+
| `/sdd.desplegar` | "Lo voy a publicar en internet" |
|
|
48
|
+
|
|
49
|
+
## Preguntas de aclaración sin jerga
|
|
50
|
+
|
|
51
|
+
Cuando `/sdd.aclarar` encuentre ambigüedades, reformúlalas en lenguaje cotidiano y con opciones concretas. En lugar de:
|
|
52
|
+
|
|
53
|
+
> ¿El campo `vence_en` usa formato ISO 8601 y zona horaria UTC?
|
|
54
|
+
|
|
55
|
+
di:
|
|
56
|
+
|
|
57
|
+
> ¿Las tareas tienen fecha límite?
|
|
58
|
+
> a) Sí, quiero ponerle una fecha a cada tarea
|
|
59
|
+
> b) No, solo saber si está hecha o no
|
|
60
|
+
|
|
61
|
+
## Lo que NO cambia (rigor intacto)
|
|
62
|
+
|
|
63
|
+
Aunque el usuario no lo vea, en modo guiado SIEMPRE:
|
|
64
|
+
|
|
65
|
+
- Se generan tests y deben pasar antes de decir "listo".
|
|
66
|
+
- Se aplican lint/formato y la revisión del agente `revisor`.
|
|
67
|
+
- Se respeta la constitución como restricción dura.
|
|
68
|
+
- No se imprimen ni hardcodean secretos.
|
|
69
|
+
- Se confirma antes de cualquier acción irreversible o hacia afuera (publicar, borrar).
|
|
70
|
+
|
|
71
|
+
Si una verificación falla, NO digas "el test X falló con assertion error". Di: *"Encontré un detalle que no funcionaba bien y lo estoy corrigiendo"* — y arréglalo antes de continuar.
|
|
72
|
+
|
|
73
|
+
## Cierre de cada interacción
|
|
74
|
+
|
|
75
|
+
Termina siempre ofreciendo el siguiente paso como una acción en lenguaje natural, no como un comando:
|
|
76
|
+
|
|
77
|
+
> ✅ Ya está. Tu lista de tareas funciona.
|
|
78
|
+
> ¿Quieres que **la publique en internet** para usarla desde cualquier lado? (responde *sí*)
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: orquestacion-ptc
|
|
3
|
+
description: Patrón Programmatic Tool Calling para despachar subagentes en paralelo y agregar solo resultados mínimos. Reduce ~85% de tokens en orquestación multi-agente. Aplica en /sdd.implementar y /sdd.analizar.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Skill: Orquestación PTC (Programmatic Tool Calling)
|
|
7
|
+
|
|
8
|
+
## ¿Qué es PTC?
|
|
9
|
+
|
|
10
|
+
En lugar de invocar subagentes uno a uno (secuencial, cada resultado en contexto completo), el orquestador **escribe un bloque de código** que despacha todos los agentes independientes en paralelo dentro de un sandbox de Claude Code, luego **agrega solo el resumen** — estado PASA/FALLA + diff mínimo — antes de devolver el control al modelo.
|
|
11
|
+
|
|
12
|
+
Resultado: −85% de tokens en orquestación con 3+ agentes independientes (referencia: PTC cookbook de Anthropic).
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## Cuándo aplicar PTC
|
|
17
|
+
|
|
18
|
+
### ✅ Aplica PTC cuando:
|
|
19
|
+
|
|
20
|
+
1. **Tareas independientes en paralelo** — múltiples tareas de `/sdd.implementar` sin dependencias entre sí (distintos archivos, distintas capas).
|
|
21
|
+
2. **Lotes de verificación** — `/sdd.analizar` corre 7 dimensiones de auditoría; las dimensiones son independientes entre sí.
|
|
22
|
+
3. **Revisión multi-agente** — invocar revisor + crítico + seguridad al mismo tiempo cuando sus entradas no cambian entre sí.
|
|
23
|
+
4. **Cualquier fan-out N≥3** donde los subagentes reciben el mismo contexto base y sus resultados se agregan.
|
|
24
|
+
|
|
25
|
+
### ❌ NO aplica PTC cuando:
|
|
26
|
+
|
|
27
|
+
1. **El siguiente paso depende del resultado del anterior** — ej. el agente arquitecto diseña, el backend implementa usando esa arquitectura. Secuencial obligatorio.
|
|
28
|
+
2. **Acciones irreversibles** — deploy, escritura en BD de producción, envío de notificaciones. Confirmación explícita primero; nunca paralelizar sin gate.
|
|
29
|
+
3. **El usuario debe revisar entre pasos** — si hay decisión humana en el medio, no hay PTC: es un punto de pausa.
|
|
30
|
+
4. **Solo 1 o 2 agentes** — el overhead de PTC supera el beneficio; invocar directo.
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Patrón de implementación
|
|
35
|
+
|
|
36
|
+
### Estructura del bloque PTC
|
|
37
|
+
|
|
38
|
+
```javascript
|
|
39
|
+
// Bloque PTC — orquestador despacha en paralelo
|
|
40
|
+
// Entrada: lista de tareas independientes con su agente asignado
|
|
41
|
+
// Salida: array [{id, estado, archivos_modificados, resumen_1_linea}]
|
|
42
|
+
|
|
43
|
+
const tareas = [
|
|
44
|
+
{ id: "T001", agente: "desarrollador-backend", contexto: "..." },
|
|
45
|
+
{ id: "T003", agente: "tester", contexto: "..." },
|
|
46
|
+
{ id: "T005", agente: "documentador", contexto: "..." }
|
|
47
|
+
];
|
|
48
|
+
|
|
49
|
+
// Despacho paralelo
|
|
50
|
+
const resultados = await Promise.all(
|
|
51
|
+
tareas.map(t => invocarAgente(t.agente, t.contexto))
|
|
52
|
+
);
|
|
53
|
+
|
|
54
|
+
// Agregación mínima — solo PASA/FALLA + archivos
|
|
55
|
+
return resultados.map((r, i) => ({
|
|
56
|
+
id: tareas[i].id,
|
|
57
|
+
estado: r.verificacion_ok ? "PASA" : "FALLA",
|
|
58
|
+
archivos: r.archivos_modificados,
|
|
59
|
+
resumen: r.primera_linea_resultado
|
|
60
|
+
}));
|
|
61
|
+
// El output completo de cada agente NO vuelve al modelo — solo el agregado
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### Cuándo incluir más contexto en el agregado
|
|
65
|
+
|
|
66
|
+
- Si `estado === "FALLA"`: incluir el mensaje de error completo (necesario para el retry).
|
|
67
|
+
- Si hay un hallazgo de seguridad: incluir extracto, no el análisis completo.
|
|
68
|
+
- Nunca incluir diffs completos de archivos en el agregado; solo lista de rutas modificadas.
|
|
69
|
+
|
|
70
|
+
---
|
|
71
|
+
|
|
72
|
+
## Fallback secuencial
|
|
73
|
+
|
|
74
|
+
Si el entorno no soporta ejecución de código programática (sandbox no disponible, Claude Code en modo lectura, política de permisos):
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
MODO_PTC_DISPONIBLE = false
|
|
78
|
+
→ ejecutar tareas en secuencia con el ciclo estándar del paso 4 de /sdd.implementar
|
|
79
|
+
→ notificar al usuario: "Ejecutando en modo secuencial (PTC no disponible en este entorno)"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
El fallback es transparente; el resultado final es idéntico, solo más lento y con más tokens.
|
|
83
|
+
|
|
84
|
+
---
|
|
85
|
+
|
|
86
|
+
## Cómo medirlo
|
|
87
|
+
|
|
88
|
+
Antes de PTC: observar tokens de entrada en la respuesta con `/sdd.estado` + `--verbose`.
|
|
89
|
+
Después de PTC: comparar para la misma spec con 3+ tareas independientes.
|
|
90
|
+
Ahorro esperado: −70 a −85% en tokens de entrada del orquestador.
|
|
91
|
+
|
|
92
|
+
---
|
|
93
|
+
|
|
94
|
+
## Referencia
|
|
95
|
+
|
|
96
|
+
Patrón documentado en: Anthropic Cookbook — "Programmatic Tool Calling" (parallel subagent dispatch + result aggregation).
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Valida silenciosamente que la spec activa cumple el mínimo de calidad antes de pasar a la siguiente fase. Se invoca internamente.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Skill: Validación de Spec
|
|
6
|
+
|
|
7
|
+
## Checks mínimos (bloquean si fallan)
|
|
8
|
+
|
|
9
|
+
1. **Objetivo presente**: Sección "Objetivo" no vacía
|
|
10
|
+
2. **Mínimo 1 CA**: Al menos 1 ítem en criterios de aceptación
|
|
11
|
+
3. **Mínimo 1 escenario**: Al menos 1 bloque Dado/Cuando/Entonces
|
|
12
|
+
4. **Sin críticos pendientes**: 0 marcadores `[NECESITA_ACLARACION]` en preguntas críticas
|
|
13
|
+
5. **Frontmatter válido**: YAML bien formado con `id`, `titulo`, `estado`
|
|
14
|
+
|
|
15
|
+
## Checks de calidad (warnings, no bloquean)
|
|
16
|
+
|
|
17
|
+
- CAs con palabras vagas ("rápido", "fácil", "bueno", "intuitivo")
|
|
18
|
+
- Escenarios de error ausentes
|
|
19
|
+
- Más de 5 preguntas abiertas sin resolver
|
|
20
|
+
- Sin sección "Fuera de Alcance"
|
|
21
|
+
- Sin métricas de éxito medibles
|
|
22
|
+
- Sin actores definidos
|
|
23
|
+
|
|
24
|
+
## Implementación (pseudocódigo)
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
SPEC_FILE=".sdd/especificaciones/$(spec_activa)/spec.md"
|
|
28
|
+
|
|
29
|
+
# Check 1: objetivo
|
|
30
|
+
grep -A2 "## 2. Objetivo" "$SPEC_FILE" | tail -1 | grep -q '\w' || echo "FALTA_OBJETIVO"
|
|
31
|
+
|
|
32
|
+
# Check 2: CAs
|
|
33
|
+
grep -c "CA-[0-9]" "$SPEC_FILE" | grep -qv '^0$' || echo "SIN_CAS"
|
|
34
|
+
|
|
35
|
+
# Check 3: escenarios
|
|
36
|
+
grep -c "**Dado**" "$SPEC_FILE" | grep -qv '^0$' || echo "SIN_ESCENARIOS"
|
|
37
|
+
|
|
38
|
+
# Check 4: marcadores críticos
|
|
39
|
+
N_CRITICOS=$(grep -c "\[NECESITA_ACLARACION\]" "$SPEC_FILE")
|
|
40
|
+
[ "$N_CRITICOS" -gt 0 ] && echo "$N_CRITICOS pendientes"
|
|
41
|
+
|
|
42
|
+
# Check 5: frontmatter
|
|
43
|
+
head -20 "$SPEC_FILE" | grep -q '^id:' || echo "FRONTMATTER_INCOMPLETO"
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## Output
|
|
47
|
+
|
|
48
|
+
Si pasa todos los críticos: continúa silenciosamente, no muestra nada.
|
|
49
|
+
|
|
50
|
+
Si falla algún crítico:
|
|
51
|
+
> ❌ La spec no está lista: [razón específica]
|
|
52
|
+
> Usa `/sdd.aclarar` o `/sdd.checklist`.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Verifica que el código implementado cumple los criterios de aceptación de la spec. Lee código y tests, no asume.
|
|
3
|
+
---
|
|
4
|
+
|
|
5
|
+
# Skill: Verificador de Implementación
|
|
6
|
+
|
|
7
|
+
Cruza el código generado contra los CAs de la spec, archivo por archivo.
|
|
8
|
+
|
|
9
|
+
## Proceso
|
|
10
|
+
|
|
11
|
+
### 1. Cargar contexto
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
SPEC_ID=$(spec_activa)
|
|
15
|
+
cat ".sdd/especificaciones/${SPEC_ID}/spec.md"
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
### 2. Extraer CAs
|
|
19
|
+
|
|
20
|
+
Lista todos los criterios de aceptación con su ID y descripción.
|
|
21
|
+
|
|
22
|
+
### 3. Por cada CA
|
|
23
|
+
|
|
24
|
+
#### 3a. Buscar implementación
|
|
25
|
+
```bash
|
|
26
|
+
# Identificar archivos/funciones que deberían implementar este CA
|
|
27
|
+
# Usar palabras clave del CA para búsqueda fuzzy
|
|
28
|
+
grep -rn "[palabras clave]" --include="*.{ext}" src/
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
#### 3b. Buscar test
|
|
32
|
+
```bash
|
|
33
|
+
# ¿Existe un test que verifique este CA específicamente?
|
|
34
|
+
grep -rn "[descripción del CA o CA-XXX-XX]" --include="*test*" --include="*spec*"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
#### 3c. Verificar manualmente
|
|
38
|
+
Lee el código encontrado y evalúa:
|
|
39
|
+
- ¿Implementa el comportamiento del CA?
|
|
40
|
+
- ¿Maneja los casos borde?
|
|
41
|
+
- ¿El test que lo cubre realmente valida lo que pide el CA?
|
|
42
|
+
|
|
43
|
+
#### 3d. Clasificar
|
|
44
|
+
- ✅ **Implementado y testeado**: hay código + test
|
|
45
|
+
- ⚠️ **Implementado sin test**: hay código pero no test específico
|
|
46
|
+
- ⚠️ **Implementado parcialmente**: cubre algunos casos pero no todos
|
|
47
|
+
- ❌ **No implementado**: no se encontró código que lo cubra
|
|
48
|
+
|
|
49
|
+
### 4. Verificar exclusiones
|
|
50
|
+
|
|
51
|
+
Para cada exclusión explícita de la spec:
|
|
52
|
+
- ¿Se respetó? (no se implementó funcionalidad fuera de scope)
|
|
53
|
+
|
|
54
|
+
### 5. Reporte
|
|
55
|
+
|
|
56
|
+
Genera tabla en `.sdd/especificaciones/{ID}/verificacion.md`:
|
|
57
|
+
|
|
58
|
+
```markdown
|
|
59
|
+
| CA | Descripción | Implementado | Testeado | Archivo | Test |
|
|
60
|
+
|----|-------------|--------------|----------|---------|------|
|
|
61
|
+
| CA-001-01 | [texto] | ✅ | ✅ | src/auth.ts:45 | tests/auth.test.ts:12 |
|
|
62
|
+
| CA-001-02 | [texto] | ⚠️ | ❌ | src/auth.ts:78 | — |
|
|
63
|
+
| CA-002-01 | [texto] | ❌ | — | — | — |
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Output
|
|
67
|
+
|
|
68
|
+
Veredicto:
|
|
69
|
+
- **APROBADA**: 100% CAs implementados + tests
|
|
70
|
+
- **APROBADA_CON_OBSERVACIONES**: ≥95% CAs cubiertos
|
|
71
|
+
- **RECHAZADA**: <95% o tests fallando
|