siesa-agents 2.1.86 → 2.1.88
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.
|
@@ -1,143 +1,221 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sa-delivery-guides
|
|
3
|
-
description:
|
|
3
|
+
description: Consolidate the per-feature user-guide documents indexed in the mcp-siesa-docs MCP into ONE coherent, end-user friendly guide per project — a folder of linked Spanish markdown files with a central index. Use this skill when a delivery team member needs to turn the scattered per-feature user guides of a project into a single navigable end-user manual. Always trigger on /sa-delivery-guides. Also trigger when the user says "generar guía de entrega", "consolidar guías de usuario", "guía para el cliente", "documentación de entrega para [project]", "guía consolidada de usuario final", "guía para usuario final", or describes wanting to merge the indexed per-feature user guides into one coherent manual a non-technical client can read.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
# Delivery Agent Guides
|
|
6
|
+
# Delivery Agent Guides — Consolidador
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
Toma las guías de usuario **por feature** de un proyecto (que viven en el RAG y se consultan vía el MCP `mcp-siesa-docs`) y produce **una guía de usuario final consolidada y coherente**: una **carpeta con el nombre del proyecto** que contiene varios archivos Markdown enlazados entre sí y un `index.md` central que actúa como tabla de contenidos.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
El resultado **no** es un solo documento gigante ni una copia 1:1 de cada feature. Es un manual **sintetizado**: se agrupan features afines en capítulos temáticos, se unifican los conceptos repetidos (acceso, navegación, glosario, FAQ) y se redacta una narrativa continua en español, para usuario final no técnico.
|
|
11
|
+
|
|
12
|
+
**El MCP es la única fuente de contenido. No se escanea el sistema de archivos local.**
|
|
11
13
|
|
|
12
14
|
---
|
|
13
15
|
|
|
14
|
-
##
|
|
16
|
+
## Herramientas del MCP disponibles (úsalas tal cual)
|
|
17
|
+
|
|
18
|
+
El servidor `mcp-siesa-docs` expone **solo tres** herramientas. **No existe `get_document`** — no la llames.
|
|
19
|
+
|
|
20
|
+
- `list_collections()` → inventario de colecciones. La colección indexada es **`siesa-docs`** (el nombre `mcp-siesa-docs` es el del servidor, no el de la colección).
|
|
21
|
+
- `list_projects()` → proyectos indexados con banderas `has_user_guide`, `has_technical_knowledge` y `document_count`. **Esta es la fuente para saber qué proyectos tienen guías de usuario.**
|
|
22
|
+
- `search_docs({ query, top_k, filter })` → recuperación híbrida que devuelve **chunks** relevantes (máx. `top_k` = 50). `filter` es un diccionario opcional de pares string→string (p. ej. `{ "project": "<proyecto>" }`).
|
|
15
23
|
|
|
16
|
-
|
|
24
|
+
> ⚠️ Como no hay `get_document`, el contenido de cada guía se reconstruye **a partir de chunks** vía `search_docs`. Por eso se hacen varias búsquedas temáticas con `top_k` alto, en vez de una sola.
|
|
25
|
+
|
|
26
|
+
---
|
|
17
27
|
|
|
18
|
-
|
|
28
|
+
## Flujo
|
|
19
29
|
|
|
20
|
-
1
|
|
21
|
-
2. Call `search_docs("user guide proyectos disponibles")` to find projects whose indexed docs include a `user-guide` directory.
|
|
22
|
-
3. Build the candidate list: **only include projects that have at least one document in their `user-guide` directory**. Projects with only feature specs, épicas, stories, or architecture docs are excluded (Option A).
|
|
23
|
-
4. Present the list to the user:
|
|
24
|
-
```
|
|
25
|
-
Proyectos con guías de usuario disponibles:
|
|
26
|
-
[1] {project-name-1}
|
|
27
|
-
[2] {project-name-2}
|
|
28
|
-
...
|
|
30
|
+
### Paso 1: Descubrir proyectos con guías de usuario (automático)
|
|
29
31
|
|
|
30
|
-
|
|
31
|
-
```
|
|
32
|
-
5. The user replies with a number or project name.
|
|
32
|
+
Apenas se invoca la skill, sin preguntar primero:
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
1. **Saluda con un mensaje de bienvenida** antes de cualquier llamada técnica. Una sola frase cálida y no técnica, p. ej.:
|
|
35
|
+
> 👋 Bienvenido al generador de Guías de Usuario de Siesa. Voy a consultar los proyectos disponibles y te dejaré elegir uno para construir su manual de usuario final.
|
|
36
|
+
|
|
37
|
+
No narres las llamadas al MCP ("voy a cargar las herramientas", "llamando a list_collections…"). Mantén el tono de cara al usuario: limpio y orientado a negocio.
|
|
38
|
+
2. `list_collections()` para confirmar que **`siesa-docs`** está disponible.
|
|
39
|
+
3. `list_projects()` y filtra los que tengan **`has_user_guide: true`**.
|
|
40
|
+
4. Presenta los proyectos usando la herramienta **`AskUserQuestion`** (menú con selección por flechas, el usuario no escribe su opción):
|
|
41
|
+
- `header`: "Proyecto"
|
|
42
|
+
- `question`: "¿Para cuál proyecto quieres generar la guía consolidada de usuario final?"
|
|
43
|
+
- `options`: una por cada proyecto con `has_user_guide: true`. El `label` es **solo el nombre del proyecto** (sin conteos ni datos técnicos). El `description` puede ser una frase breve y no técnica (p. ej. "Guía de usuario final del sistema {proyecto}").
|
|
44
|
+
- `multiSelect`: false
|
|
45
|
+
- **Nunca** muestres el número de fragmentos ni `document_count` — es un dato técnico que no le interesa al usuario.
|
|
46
|
+
5. Toma la respuesta del menú como el proyecto seleccionado.
|
|
47
|
+
|
|
48
|
+
Si ninguno califica, dilo claramente ("No encontré proyectos con guías de usuario indexadas en el MCP") y detente (no presentes el menú).
|
|
35
49
|
|
|
36
50
|
---
|
|
37
51
|
|
|
38
|
-
###
|
|
52
|
+
### Paso 2: Mapear las guías por feature del proyecto
|
|
39
53
|
|
|
40
|
-
|
|
41
|
-
2. For each result, call `get_document(path)` to fetch the full content.
|
|
42
|
-
3. **Strict filter**: process only documents whose `path` is inside the project's `user-guide` directory. Ignore feature specs, épicas, stories, architecture, or any other technical doc, even if they show up in results.
|
|
54
|
+
Objetivo: saber qué features/áreas cubre el proyecto, recuperando los chunks de sus guías de usuario.
|
|
43
55
|
|
|
44
|
-
|
|
56
|
+
1. Lanza un barrido de `search_docs` con `filter: { "project": "<proyecto>" }` y `top_k: 50`. Usa varias consultas amplias en español para maximizar cobertura, por ejemplo:
|
|
57
|
+
- `"guía de usuario funcionalidades del sistema"`
|
|
58
|
+
- `"cómo se usa pasos flujos de trabajo"`
|
|
59
|
+
- `"preguntas frecuentes y solución de problemas"`
|
|
60
|
+
2. De los resultados, quédate **solo con chunks de guías de usuario** (su `path`/origen está bajo `user-guide/`). Ignora chunks de specs técnicas, arquitectura, stories o épicas aunque aparezcan.
|
|
61
|
+
3. Construye la lista de **features/áreas** detectadas (agrupa los chunks por su documento/feature de origen). Conserva los `path` de origen — los citarás al final.
|
|
62
|
+
|
|
63
|
+
Si el barrido devuelve muy pocos chunks, repite con consultas más específicas por nombre de feature detectado.
|
|
45
64
|
|
|
46
65
|
---
|
|
47
66
|
|
|
48
|
-
###
|
|
67
|
+
### Paso 3: Diseñar la estructura del manual (capítulos)
|
|
49
68
|
|
|
50
|
-
|
|
69
|
+
Aplica una arquitectura de información orientada a la **necesidad del usuario** (Diátaxis simplificado), no un archivo por feature suelto:
|
|
51
70
|
|
|
52
|
-
**
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
71
|
+
1. **Agrupa las features afines en capítulos temáticos.** Ejemplo (ilustrativo, depende del proyecto): "Suscripciones y planes", "Saldos y consumo", "Facturación y pagos", "Portal y notificaciones".
|
|
72
|
+
2. Define el conjunto de archivos a crear. Estructura recomendada (ajústala al tamaño real del proyecto):
|
|
73
|
+
- `index.md` — portada + tabla de contenidos enlazada
|
|
74
|
+
- `01-introduccion.md` — qué es el sistema y para qué sirve
|
|
75
|
+
- `02-primeros-pasos.md` — acceso, primer ingreso, navegación general
|
|
76
|
+
- `03-{area-1}.md`, `04-{area-2}.md`, … — un archivo por capítulo temático
|
|
77
|
+
- `NN-solucion-de-problemas.md`
|
|
78
|
+
- `NN-preguntas-frecuentes.md`
|
|
79
|
+
- `NN-glosario.md`
|
|
80
|
+
3. **Mantén la cantidad de archivos manejable**: agrupa, no generes un archivo por cada feature. Si dos features son pequeñas y relacionadas, van en el mismo capítulo.
|
|
81
|
+
4. Muestra al usuario el plan de capítulos propuesto **en una línea por archivo** y continúa (no requiere aprobación explícita salvo que el usuario quiera ajustar).
|
|
58
82
|
|
|
59
|
-
**
|
|
60
|
-
- Mermaid diagrams → rewrite as one or two plain sentences describing the flow. Never emit Mermaid syntax.
|
|
83
|
+
> ❌ **Nunca** generes un único archivo monolítico (`delivery-guide.md`) con todo el contenido. El entregable es **siempre** la carpeta con varios archivos enlazados. Un solo documento gigante es justo el comportamiento a evitar.
|
|
61
84
|
|
|
62
|
-
|
|
63
|
-
- `📸 [Screenshot: ...]` placeholders
|
|
64
|
-
- `[Source: FX Story Y.Z]` traceability references
|
|
65
|
-
- Screenshot index tables
|
|
66
|
-
- Implementation component names (ContactManager, EmptyState, ErrorPanel, etc.) — describe the behavior instead
|
|
67
|
-
- `*Generado: ...` footers
|
|
85
|
+
---
|
|
68
86
|
|
|
69
|
-
|
|
87
|
+
### Paso 4: Generar los archivos del manual
|
|
70
88
|
|
|
89
|
+
Para **cada capítulo temático**, antes de redactar, recupera su contenido con `search_docs` enfocado (consulta con el nombre del área/feature, `filter` del proyecto, `top_k` alto). Luego escribe el archivo `.md` en español, con contenido **coherente y sintetizado** (no copiado por feature).
|
|
90
|
+
|
|
91
|
+
**Contenido a conservar y reescribir en lenguaje sencillo:**
|
|
92
|
+
- Nombre y propósito de cada funcionalidad
|
|
93
|
+
- Flujos paso a paso
|
|
94
|
+
- Conceptos clave y definiciones (simplificadas)
|
|
95
|
+
- Solución de problemas y FAQ
|
|
96
|
+
- Advertencias (⚠️) — reformula sin detalle técnico; conserva la implicación práctica
|
|
97
|
+
|
|
98
|
+
**Contenido a transformar:**
|
|
99
|
+
- Diagramas Mermaid → reescríbelos como una o dos frases que describan el flujo. **Nunca emitas sintaxis Mermaid.**
|
|
100
|
+
|
|
101
|
+
**Contenido a omitir:**
|
|
102
|
+
- Placeholders `📸 [Screenshot: ...]`
|
|
103
|
+
- Referencias de trazabilidad `[Source: FX Story Y.Z]`
|
|
104
|
+
- Tablas de índice de capturas
|
|
105
|
+
- Nombres de componentes de implementación (ContactManager, EmptyState, ErrorPanel, etc.) — describe el comportamiento
|
|
106
|
+
- Pies `*Generado: ...`
|
|
107
|
+
|
|
108
|
+
**Coherencia entre archivos (clave de la consolidación):**
|
|
109
|
+
- Los conceptos y términos repetidos en varias features se explican **una sola vez** (en `01-introduccion.md` o en `glosario.md`) y los capítulos los referencian con un enlace relativo.
|
|
110
|
+
- El acceso/login/navegación va **una vez** en `02-primeros-pasos.md`, no en cada capítulo.
|
|
111
|
+
- FAQ y Solución de Problemas se **fusionan** de todas las features en sus archivos únicos, sin repetir preguntas.
|
|
112
|
+
- Cada archivo enlaza al anterior/siguiente y de vuelta al `index.md` con enlaces relativos Markdown.
|
|
113
|
+
|
|
114
|
+
**Plantilla de un archivo de capítulo:**
|
|
71
115
|
```markdown
|
|
72
116
|
---
|
|
73
|
-
project: {
|
|
117
|
+
project: {proyecto}
|
|
118
|
+
chapter: {nombre del capítulo}
|
|
74
119
|
generated_date: {YYYY-MM-DD}
|
|
120
|
+
audience: Usuario final no técnico
|
|
75
121
|
sources:
|
|
76
122
|
- {mcp-path-1}
|
|
77
123
|
- {mcp-path-2}
|
|
78
|
-
audience: Usuario final no técnico
|
|
79
124
|
---
|
|
80
125
|
|
|
81
|
-
|
|
126
|
+
[⬅️ Índice](index.md)
|
|
82
127
|
|
|
83
|
-
|
|
84
|
-
2-3 sentences. What the app does and who it is for. No technical terms.
|
|
128
|
+
# {Nombre del Capítulo}
|
|
85
129
|
|
|
86
|
-
##
|
|
87
|
-
What problems it solves, from the user's perspective.
|
|
88
|
-
|
|
89
|
-
---
|
|
90
|
-
|
|
91
|
-
## {Feature 1}
|
|
130
|
+
## {Funcionalidad 1}
|
|
92
131
|
|
|
93
132
|
### ¿Qué es?
|
|
94
|
-
|
|
133
|
+
Un párrafo. Descripción simple.
|
|
95
134
|
|
|
96
135
|
### ¿Para qué sirve?
|
|
97
|
-
|
|
136
|
+
El beneficio práctico para el usuario.
|
|
98
137
|
|
|
99
138
|
### ¿Cómo se usa?
|
|
100
|
-
|
|
101
|
-
|
|
139
|
+
Pasos numerados. Una acción clara por paso.
|
|
140
|
+
Incluye advertencias en línea (⚠️ ...) justo antes del paso que puede causar un problema.
|
|
102
141
|
|
|
103
|
-
|
|
142
|
+
## {Funcionalidad 2}
|
|
143
|
+
(misma estructura)
|
|
104
144
|
|
|
105
|
-
|
|
106
|
-
(
|
|
145
|
+
---
|
|
146
|
+
[⬅️ Anterior]({archivo-anterior}.md) · [Índice](index.md) · [Siguiente ➡️]({archivo-siguiente}.md)
|
|
147
|
+
```
|
|
107
148
|
|
|
149
|
+
**Plantilla de `index.md`:**
|
|
150
|
+
```markdown
|
|
151
|
+
---
|
|
152
|
+
project: {proyecto}
|
|
153
|
+
generated_date: {YYYY-MM-DD}
|
|
154
|
+
audience: Usuario final no técnico
|
|
155
|
+
type: indice-consolidado
|
|
156
|
+
sources:
|
|
157
|
+
- {mcp-path-1}
|
|
158
|
+
- {mcp-path-2}
|
|
108
159
|
---
|
|
109
160
|
|
|
110
|
-
|
|
111
|
-
Plain Q&A: "¿Qué hago si...? → ..."
|
|
161
|
+
# Guía de Usuario de {Proyecto}
|
|
112
162
|
|
|
113
|
-
|
|
114
|
-
|
|
163
|
+
Manual de usuario final. Esta guía reúne, de forma coherente, toda la documentación de uso del sistema.
|
|
164
|
+
|
|
165
|
+
## ¿Qué es {Proyecto}?
|
|
166
|
+
2-3 frases. Qué hace y para quién es. Sin términos técnicos.
|
|
167
|
+
|
|
168
|
+
## Contenido
|
|
169
|
+
|
|
170
|
+
1. [Introducción](01-introduccion.md)
|
|
171
|
+
2. [Primeros Pasos](02-primeros-pasos.md)
|
|
172
|
+
3. [{Capítulo temático 1}](03-{area-1}.md)
|
|
173
|
+
4. [{Capítulo temático 2}](04-{area-2}.md)
|
|
174
|
+
...
|
|
175
|
+
N. [Solución de Problemas](NN-solucion-de-problemas.md)
|
|
176
|
+
N. [Preguntas Frecuentes](NN-preguntas-frecuentes.md)
|
|
177
|
+
N. [Glosario](NN-glosario.md)
|
|
115
178
|
```
|
|
116
179
|
|
|
117
|
-
**
|
|
118
|
-
-
|
|
119
|
-
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
180
|
+
**Guías de redacción:**
|
|
181
|
+
- Lector cómodo con un smartphone pero sin formación en software.
|
|
182
|
+
- Voz activa, instrucciones directas: "Haz clic en...", "Escribe...", "Selecciona..."
|
|
183
|
+
- Frases cortas. Si una frase necesita una coma para explicar un concepto técnico, reescríbela.
|
|
184
|
+
- Si un concepto no aporta valor práctico al usuario final, elimínalo.
|
|
122
185
|
|
|
123
186
|
---
|
|
124
187
|
|
|
125
|
-
###
|
|
188
|
+
### Paso 5: Guardar y confirmar
|
|
126
189
|
|
|
127
|
-
|
|
190
|
+
Guarda todo en la carpeta del proyecto:
|
|
128
191
|
```
|
|
129
|
-
_bmad-output/documentation-artifacts/delivery-guides/{
|
|
192
|
+
_bmad-output/documentation-artifacts/delivery-guides/{proyecto}/
|
|
193
|
+
├── index.md
|
|
194
|
+
├── 01-introduccion.md
|
|
195
|
+
├── 02-primeros-pasos.md
|
|
196
|
+
├── 03-{area-1}.md
|
|
197
|
+
├── ...
|
|
198
|
+
├── NN-solucion-de-problemas.md
|
|
199
|
+
├── NN-preguntas-frecuentes.md
|
|
200
|
+
└── NN-glosario.md
|
|
130
201
|
```
|
|
131
202
|
|
|
132
|
-
|
|
203
|
+
Crea la carpeta si no existe.
|
|
133
204
|
|
|
134
|
-
|
|
205
|
+
Luego confirma:
|
|
135
206
|
```
|
|
136
|
-
Guía guardada en: _bmad-output/documentation-artifacts/delivery-guides/{
|
|
207
|
+
Guía consolidada guardada en: _bmad-output/documentation-artifacts/delivery-guides/{proyecto}/
|
|
208
|
+
|
|
209
|
+
Archivos generados:
|
|
210
|
+
- index.md
|
|
211
|
+
- 01-introduccion.md
|
|
212
|
+
- 02-primeros-pasos.md
|
|
213
|
+
- {capítulos...}
|
|
214
|
+
- NN-glosario.md
|
|
137
215
|
|
|
138
|
-
|
|
139
|
-
- {
|
|
140
|
-
- {
|
|
216
|
+
Capítulos / features incluidos:
|
|
217
|
+
- {capítulo 1}: {features que agrupa}
|
|
218
|
+
- {capítulo 2}: {features que agrupa}
|
|
141
219
|
|
|
142
220
|
Fuentes del MCP:
|
|
143
221
|
- {mcp-path-1}
|
|
@@ -146,17 +224,17 @@ Fuentes del MCP:
|
|
|
146
224
|
|
|
147
225
|
---
|
|
148
226
|
|
|
149
|
-
##
|
|
227
|
+
## Referencia de Transformación
|
|
150
228
|
|
|
151
|
-
|
|
|
229
|
+
| Elemento técnico | Tratamiento en la guía |
|
|
152
230
|
|---|---|
|
|
153
231
|
| `deep linking` / URL única por registro | "Cada registro tiene su propia dirección web que puedes guardar o compartir" |
|
|
154
|
-
| `ContactManager`, `EmptyState`, `ErrorPanel` |
|
|
155
|
-
| `NIT/RUC` |
|
|
156
|
-
| `Toast`
|
|
157
|
-
| Reintentar
|
|
232
|
+
| `ContactManager`, `EmptyState`, `ErrorPanel` | Quita el nombre; describe lo que el usuario ve |
|
|
233
|
+
| `NIT/RUC` | Consérvalo — explícalo una vez: "número de identificación tributaria (NIT/RUC)" |
|
|
234
|
+
| Notificación `Toast` | "mensaje de confirmación que aparece brevemente en pantalla" |
|
|
235
|
+
| Botón Reintentar ante error | "si aparece un error, haz clic en Reintentar" |
|
|
158
236
|
| Panel de dos columnas | "La pantalla se divide en dos partes: a la izquierda la lista, a la derecha el detalle" |
|
|
159
237
|
| Validación inline | "mensajes de error junto al campo que necesita corrección" |
|
|
160
|
-
|
|
|
161
|
-
| `[Source: FX Story Y.Z]` |
|
|
162
|
-
| `📸 [Screenshot: ...]` |
|
|
238
|
+
| Bloque de código Mermaid | Una o dos frases que describan el flujo |
|
|
239
|
+
| `[Source: FX Story Y.Z]` | Omitir |
|
|
240
|
+
| `📸 [Screenshot: ...]` | Omitir |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "siesa-agents",
|
|
3
|
-
"version": "2.1.
|
|
3
|
+
"version": "2.1.88",
|
|
4
4
|
"description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"bin": {
|
|
@@ -25,7 +25,9 @@
|
|
|
25
25
|
"vscode/**/*",
|
|
26
26
|
"github/**/*",
|
|
27
27
|
"!github/workflows/**",
|
|
28
|
+
"!.github/workflows/**",
|
|
28
29
|
"!github/CODEOWNERS",
|
|
30
|
+
"!.github/CODEOWNERS",
|
|
29
31
|
"claude/**/*",
|
|
30
32
|
"gemini/**/*",
|
|
31
33
|
"bin/**/*",
|