@tacuchi/agent-workflow-cli 12.10.0 → 13.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/dist/domain/skills.d.ts +8 -1
- package/dist/domain/skills.d.ts.map +1 -1
- package/dist/domain/skills.js +7 -6
- package/dist/domain/skills.js.map +1 -1
- package/package.json +1 -1
- package/skills/w/SKILL.md +4 -6
- package/skills/w/exports/README.md +5 -5
- package/skills/w/exports/export-manuals/SKILL.md +8 -8
- package/skills/w/exports/export-reports/SKILL.md +7 -7
- package/skills/w/harness/SKILL.md +1 -1
- package/skills/w/loops/README.md +3 -4
- package/skills/w/loops/plan-exec-loop/SKILL.md +4 -2
- package/skills/w/loops/quick-loop/SKILL.md +3 -1
- package/skills/w/loops/spec-refine-loop/SKILL.md +3 -1
- package/skills/w/roles/README.md +16 -23
- package/skills/w/roles/tools/SKILL.md +2 -2
- package/skills/w/roles/coding-standards/SKILL.md +0 -82
- package/skills/w/roles/testing/SKILL.md +0 -180
- package/skills/w/roles/writing/SKILL.md +0 -90
package/dist/domain/skills.d.ts
CHANGED
|
@@ -4,8 +4,15 @@
|
|
|
4
4
|
* A loop composes a CAPABILITY by its role (e.g. "ui-design"), not a concrete
|
|
5
5
|
* skill. The role → skill binding is resolved from `skills.toml`
|
|
6
6
|
* (cascade: built-in default → global → workspace). See skills-resolver-service.
|
|
7
|
+
*
|
|
8
|
+
* Only WORKFLOW-SPECIFIC capabilities are roles here. Generic, stack-agnostic
|
|
9
|
+
* conventions (coding standards, testing strategy, technical writing) are NOT
|
|
10
|
+
* roles: they live as standalone skills the host auto-discovers by `description`
|
|
11
|
+
* and applies whenever relevant. The workflow stays indifferent — it never reads
|
|
12
|
+
* or binds a specific convention skill; the host surfaces any useful one that is
|
|
13
|
+
* installed (e.g. from the `dev-conventions` marketplace plugin, or anywhere).
|
|
7
14
|
*/
|
|
8
|
-
export declare const SKILL_ROLES: readonly ["ui-design", "sql", "git", "
|
|
15
|
+
export declare const SKILL_ROLES: readonly ["ui-design", "sql", "git", "research", "tools", "diagrams", "overview"];
|
|
9
16
|
export type SkillRole = (typeof SKILL_ROLES)[number];
|
|
10
17
|
/** Built-in default skill name for each capability role. */
|
|
11
18
|
export declare const BUILTIN_DEFAULT_SKILLS: Record<SkillRole, string>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/domain/skills.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/domain/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,mFAQd,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,4DAA4D;AAC5D,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAQ5D,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEpE,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,uEAAuE;IACvE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;AAI9D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D"}
|
package/dist/domain/skills.js
CHANGED
|
@@ -4,15 +4,19 @@
|
|
|
4
4
|
* A loop composes a CAPABILITY by its role (e.g. "ui-design"), not a concrete
|
|
5
5
|
* skill. The role → skill binding is resolved from `skills.toml`
|
|
6
6
|
* (cascade: built-in default → global → workspace). See skills-resolver-service.
|
|
7
|
+
*
|
|
8
|
+
* Only WORKFLOW-SPECIFIC capabilities are roles here. Generic, stack-agnostic
|
|
9
|
+
* conventions (coding standards, testing strategy, technical writing) are NOT
|
|
10
|
+
* roles: they live as standalone skills the host auto-discovers by `description`
|
|
11
|
+
* and applies whenever relevant. The workflow stays indifferent — it never reads
|
|
12
|
+
* or binds a specific convention skill; the host surfaces any useful one that is
|
|
13
|
+
* installed (e.g. from the `dev-conventions` marketplace plugin, or anywhere).
|
|
7
14
|
*/
|
|
8
15
|
export const SKILL_ROLES = [
|
|
9
16
|
"ui-design",
|
|
10
17
|
"sql",
|
|
11
18
|
"git",
|
|
12
|
-
"coding-standards",
|
|
13
|
-
"writing",
|
|
14
19
|
"research",
|
|
15
|
-
"testing",
|
|
16
20
|
"tools",
|
|
17
21
|
"diagrams",
|
|
18
22
|
"overview",
|
|
@@ -22,10 +26,7 @@ export const BUILTIN_DEFAULT_SKILLS = {
|
|
|
22
26
|
"ui-design": "ui-spec",
|
|
23
27
|
sql: "sql",
|
|
24
28
|
git: "git",
|
|
25
|
-
"coding-standards": "coding-standards",
|
|
26
|
-
writing: "writing",
|
|
27
29
|
research: "research",
|
|
28
|
-
testing: "testing",
|
|
29
30
|
tools: "tools",
|
|
30
31
|
diagrams: "diagrams",
|
|
31
32
|
overview: "workflow",
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/domain/skills.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../src/domain/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,WAAW;IACX,KAAK;IACL,KAAK;IACL,UAAU;IACV,OAAO;IACP,UAAU;IACV,UAAU;CACF,CAAC;AAIX,4DAA4D;AAC5D,MAAM,CAAC,MAAM,sBAAsB,GAA8B;IAC/D,WAAW,EAAE,SAAS;IACtB,GAAG,EAAE,KAAK;IACV,GAAG,EAAE,KAAK;IACV,QAAQ,EAAE,UAAU;IACpB,KAAK,EAAE,OAAO;IACd,QAAQ,EAAE,UAAU;IACpB,QAAQ,EAAE,UAAU;CACrB,CAAC;AAcF,MAAM,QAAQ,GAAwB,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;AAE3D,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC7B,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tacuchi/agent-workflow-cli",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "13.0.0",
|
|
4
4
|
"description": "Agnostic runtime CLI for AI development workflows — a stages + loops + artifacts harness. Bundles the universal `w` skill set under `skills/w/` (slash commands `/w:*`: spec-new/spec-refine, plan-new/plan-exec, quick, workspace-init, export-*); `self install --target <host>` copies SKILL + commands + hooks into the host. Pluggable capability skills via `.workflow/skills.toml`. Multi-empresa parametrization via `profile.json` cascade. Namespace auto-detected from any `.<ns>/sessions/` dir in CWD; default `workflow`.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
package/skills/w/SKILL.md
CHANGED
|
@@ -133,9 +133,8 @@ Un loop **no** compone una skill concreta; compone una **capacidad por su rol**
|
|
|
133
133
|
ui-design = "ui-spec" # built-in default
|
|
134
134
|
sql = "sql"
|
|
135
135
|
git = "git"
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
testing = "off" # capacidad desactivada
|
|
136
|
+
research = "research"
|
|
137
|
+
# diagrams = "off" # ← capacidad desactivada
|
|
139
138
|
# ui-design = "acme/figma-spec" # ← skill de tercero (vía skills.sh)
|
|
140
139
|
```
|
|
141
140
|
|
|
@@ -148,14 +147,13 @@ Catálogo de roles y su default:
|
|
|
148
147
|
| `ui-design` | `ui-spec` | must | `spec-refine-loop` (UI) |
|
|
149
148
|
| `sql` | `sql` | must | research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
|
|
150
149
|
| `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
|
|
151
|
-
| `coding-standards` | `coding-standards` | must | `plan-exec-loop` · `quick-loop` |
|
|
152
|
-
| `writing` | `writing` | must | todos los loops · `export-manuals`/`export-reports` |
|
|
153
150
|
| `research` | `research` | should | todos los loops (capacidad inline) |
|
|
154
|
-
| `testing` | `testing` | should | `plan-exec-loop` · `quick-loop` |
|
|
155
151
|
| `tools` | `tools` | should | `plan-exec-loop` |
|
|
156
152
|
| `diagrams` | `diagrams` | should | `export-diagrams` |
|
|
157
153
|
| `overview` | `workflow` | should | cualquiera (orientación) |
|
|
158
154
|
|
|
155
|
+
> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
|
|
156
|
+
|
|
159
157
|
El **chasis del loop** NO se bindea: **es** el loop, no es enchufable.
|
|
160
158
|
|
|
161
159
|
### Harness (agnóstico al arnés)
|
|
@@ -25,11 +25,11 @@
|
|
|
25
25
|
| Export | Composes | Reads (artifacts / sessions + corpus) | Writes (its ONLY category) |
|
|
26
26
|
|---|---|---|---|
|
|
27
27
|
| [`export-scripts`](export-scripts/SKILL.md) | `sql` | type-B `SCRIPTS.sql` (DDL/DML migrations) across N sessions + standalone `docs/scripts/*.sql` | `docs/scripts/NNN-export-scripts-<date>/` (numbered forwards + `00-ROLLBACK.sql`) |
|
|
28
|
-
| [`export-manuals`](export-manuals/SKILL.md) |
|
|
28
|
+
| [`export-manuals`](export-manuals/SKILL.md) | — (prosa: convenciones ambientes) | sessions + `DECISION` + plan-doc (`Solution`, `Final behavior`, `Validations`) + touched code | `docs/manuals/` |
|
|
29
29
|
| [`export-diagrams`](export-diagrams/SKILL.md) | `diagrams` | source code of the sources + plan-doc (`AS-IS` / `TO-BE`, `Impacted`) | `docs/diagrams/` (C4 / mermaid) |
|
|
30
|
-
| [`export-reports`](export-reports/SKILL.md) |
|
|
30
|
+
| [`export-reports`](export-reports/SKILL.md) | — (prosa: convenciones ambientes) | corpus of sessions (spec, `CONCLUSIONS`, `DECISION`) + plan-doc state + `docs/` | `docs/reports/` (executive / functional report) |
|
|
31
31
|
|
|
32
|
-
> **Composition over ownership:** an export does **not** own its authoring logic — it **composes a capability role** from [`../roles/`](../roles/) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-
|
|
32
|
+
> **Composition over ownership:** an export that owns a derived artifact does **not** own its authoring logic — it **composes a capability role** from [`../roles/`](../roles/) (resolved through `.workflow/skills.toml`): `export-scripts` composes `sql`; `export-diagrams` composes `diagrams`. Swapping the implementation is a one-line config change; it never touches the export. `export-manuals` and `export-reports` produce **prose**, which follows **ambient writing conventions** (the host auto-applies an installed writing skill if present) — they do **not** compose or bind a `writing` role.
|
|
33
33
|
|
|
34
34
|
## Common properties
|
|
35
35
|
|
|
@@ -83,6 +83,6 @@ Exports read the corpus through the CLI — **never hard-coded paths**:
|
|
|
83
83
|
| Export | File | Category | Composes |
|
|
84
84
|
|---|---|---|---|
|
|
85
85
|
| `export-scripts` | [`export-scripts/SKILL.md`](export-scripts/SKILL.md) | `docs/scripts` | `sql` |
|
|
86
|
-
| `export-manuals` | [`export-manuals/SKILL.md`](export-manuals/SKILL.md) | `docs/manuals` |
|
|
86
|
+
| `export-manuals` | [`export-manuals/SKILL.md`](export-manuals/SKILL.md) | `docs/manuals` | — (prosa: convenciones ambientes) |
|
|
87
87
|
| `export-diagrams` | [`export-diagrams/SKILL.md`](export-diagrams/SKILL.md) | `docs/diagrams` | `diagrams` |
|
|
88
|
-
| `export-reports` | [`export-reports/SKILL.md`](export-reports/SKILL.md) | `docs/reports` |
|
|
88
|
+
| `export-reports` | [`export-reports/SKILL.md`](export-reports/SKILL.md) | `docs/reports` | — (prosa: convenciones ambientes) |
|
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: export-manuals
|
|
3
|
-
description: "Sintetiza manuales técnicos del workspace en `docs/manuals/` consolidando N sesiones (`exec`/`quick`) + `docs/`. Lee de cada sesión el `DECISION` y el plan-doc (`Solution`, `Final behavior`, `Validations`) + el código tocado en las fuentes (cómo opera/funciona lo construido). Dos modos: `complement` (default, sobrescribe `INDEX.md` apuntando a los manuales detectados) y `regenerate` (produce dossier `NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema). Audiencia: operadores / soporte / onboarding. Read-only/reporte: no commitea ni muta sesiones.
|
|
3
|
+
description: "Sintetiza manuales técnicos del workspace en `docs/manuals/` consolidando N sesiones (`exec`/`quick`) + `docs/`. Lee de cada sesión el `DECISION` y el plan-doc (`Solution`, `Final behavior`, `Validations`) + el código tocado en las fuentes (cómo opera/funciona lo construido). Dos modos: `complement` (default, sobrescribe `INDEX.md` apuntando a los manuales detectados) y `regenerate` (produce dossier `NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema). Audiencia: operadores / soporte / onboarding. Read-only/reporte: no commitea ni muta sesiones. La prosa sigue las convenciones de redacción ambientes (el host auto-aplica una skill de writing instalada si está presente). Úsalo para 'manual operativo', 'cómo funciona lo entregado', 'paquete de onboarding técnico', 'índice de manuales'. Invocado por el usuario vía `/w:export-manuals`."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# export-manuals — Manuales técnicos desde sesiones + `docs/`
|
|
7
7
|
|
|
8
8
|
Genera o refresca manuales de **operación / cómo-funciona / onboarding** en `docs/manuals/`, consolidando lo entregado en N sesiones + el corpus `docs/`. **Read-only / reporte** — no commitea, no muta sesiones ni el código.
|
|
9
9
|
|
|
10
|
-
> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-tech-manuals` (modos complementar/regenerar, `INDEX.md`, dossier por tema), modernizado: `docs/manuals` en inglés, sin modos project/hub, y la prosa
|
|
10
|
+
> Familia `export-*` (la única vía artefacto→`docs/`). Recicla el espíritu del viejo `export-tech-manuals` (modos complementar/regenerar, `INDEX.md`, dossier por tema), modernizado: `docs/manuals` en inglés, sin modos project/hub, y la prosa sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol propio. Diseño: `docs/referencias/workflow-exports/export-manuals.md`.
|
|
11
11
|
|
|
12
12
|
## Category
|
|
13
13
|
|
|
14
14
|
`docs/manuals` — **única** carpeta `docs/` que este export escribe.
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Writing (convención ambiente, no rol)
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
La redacción del manual sigue las convenciones de redacción **ambientes**: el host auto-aplica una skill de writing instalada (si está presente) por su `description` — frases cortas, listas sobre prosa, sin relleno, léxico técnico para la audiencia operador/soporte. Este export **no** compone un rol `writing` ni lo bindea; es **indiferente** a qué skill de redacción exista. Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el export **no depende** de él.
|
|
19
19
|
|
|
20
20
|
## When to use
|
|
21
21
|
|
|
@@ -30,7 +30,7 @@ Capacidad **`writing`** (built-in default `writing`), resuelta vía `.workflow/s
|
|
|
30
30
|
2. Inspecciona el código tocado en las fuentes (cómo opera/funciona lo construido) — solo lectura.
|
|
31
31
|
3. Detecta temas (declarados en el OBJECTIVE/`SESSION`, o inferidos por keywords operativos).
|
|
32
32
|
4. Resuelve el modo (`complement` o `regenerate`).
|
|
33
|
-
5. Sintetiza el contenido aplicando
|
|
33
|
+
5. Sintetiza el contenido aplicando las convenciones de redacción ambientes (host).
|
|
34
34
|
6. Escribe: `complement` → sobrescribe `docs/manuals/INDEX.md`; `regenerate` → dossier `docs/manuals/NNN-export-manuals-YYYY-MM-DD/` con 1 manual por tema.
|
|
35
35
|
|
|
36
36
|
## What it does NOT do
|
|
@@ -99,11 +99,11 @@ Listar `docs/manuals/*.md` (excluyendo `INDEX.md` y subdirectorios `NNN-export-m
|
|
|
99
99
|
|
|
100
100
|
Por cada sesión del corpus filtrado (`aw session-artifacts --code <NNN>`): leer `DECISION` + plan-doc (`Solution`/`Final behavior`/`Validations`) + el código tocado. Tema **primario**: sección de temas en el OBJECTIVE/`SESSION`. **Secundario**: inferencia por keywords operativos ("configurar", "instalar", "paso a paso", "cómo …"). Filtrar por `--topics` si está presente. Listar (slug, confidence, sesiones de origen).
|
|
101
101
|
|
|
102
|
-
### Paso 4 — Sintetizar (
|
|
102
|
+
### Paso 4 — Sintetizar (prosa: convenciones ambientes)
|
|
103
103
|
|
|
104
104
|
**Modo `complement`** — un `INDEX.md`: cabecera + count de manuales + tabla (Tema · Slug · Manual presente/`[pendiente]` · Sesiones de origen) + "Próximos pasos" si hay temas pendientes.
|
|
105
105
|
|
|
106
|
-
**Modo `regenerate`** — 1 `.md` por tema en el dossier, cada uno con: Propósito · Pre-requisitos · Pasos numerados (cómo operar) · Comportamiento final (del plan-doc) · Validación post-uso · Decisiones relevantes (`DECISION`) · Troubleshooting · Referencias. Cada manual debe permitir al operador completar la tarea **sin** invocar al equipo de desarrollo. Más un `README.md` del dossier con el índice. La redacción
|
|
106
|
+
**Modo `regenerate`** — 1 `.md` por tema en el dossier, cada uno con: Propósito · Pre-requisitos · Pasos numerados (cómo operar) · Comportamiento final (del plan-doc) · Validación post-uso · Decisiones relevantes (`DECISION`) · Troubleshooting · Referencias. Cada manual debe permitir al operador completar la tarea **sin** invocar al equipo de desarrollo. Más un `README.md` del dossier con el índice. La redacción sigue las convenciones de redacción ambientes (host).
|
|
107
107
|
|
|
108
108
|
### Paso 5 — Escribir o reportar
|
|
109
109
|
|
|
@@ -122,6 +122,6 @@ Si `--dry-run`: imprimir el reporte; no escribir. Si no: `complement` → `Write
|
|
|
122
122
|
## Resources
|
|
123
123
|
|
|
124
124
|
- Design: `docs/referencias/workflow-exports/export-manuals.md` · familia: [`../README.md`](../README.md).
|
|
125
|
-
-
|
|
125
|
+
- Redacción: convención **ambiente** (no rol) — el host auto-aplica una skill de writing instalada si está presente.
|
|
126
126
|
- Artefactos fuente: `DECISION` + plan-doc (ver `docs/referencias/workflow-artifacts/artifacts-exec/` y `docs/specs`/`docs/plans`).
|
|
127
127
|
- Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md) · [`../export-reports/SKILL.md`](../export-reports/SKILL.md).
|
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: export-reports
|
|
3
|
-
description: "Consolida N sesiones del workspace en un informe ejecutivo/funcional bajo `docs/reports/NNN-<slug>-YYYY-MM-DD.md`. Lee el corpus: el spec (`docs/specs`), `CONCLUSIONS` (research), `DECISION`, el estado del plan-doc + el resto de `docs/` para contexto. Sintetiza: qué se hizo, decisiones clave, resultados/conclusiones, pendientes/roadmap — con dedup de recomendaciones cross-session. Audiencia ajustable vía `--audience` (gerencia ≈ corto; tecnica ≈ detallado). Funde el espíritu de los viejos export-report (ejecutivo) y export-conclusions (dedup de R-items) en una sola salida a `docs/reports`. Read-only/reporte: no commitea ni muta sesiones.
|
|
3
|
+
description: "Consolida N sesiones del workspace en un informe ejecutivo/funcional bajo `docs/reports/NNN-<slug>-YYYY-MM-DD.md`. Lee el corpus: el spec (`docs/specs`), `CONCLUSIONS` (research), `DECISION`, el estado del plan-doc + el resto de `docs/` para contexto. Sintetiza: qué se hizo, decisiones clave, resultados/conclusiones, pendientes/roadmap — con dedup de recomendaciones cross-session. Audiencia ajustable vía `--audience` (gerencia ≈ corto; tecnica ≈ detallado). Funde el espíritu de los viejos export-report (ejecutivo) y export-conclusions (dedup de R-items) en una sola salida a `docs/reports`. Read-only/reporte: no commitea ni muta sesiones. La prosa sigue las convenciones de redacción ambientes (el host auto-aplica una skill de writing instalada si está presente). Úsalo para 'informe ejecutivo', 'qué se hizo este trimestre para gerencia', 'brief con recomendaciones consolidadas'. Invocado por el usuario vía `/w:export-reports`."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# export-reports — Informe ejecutivo/funcional desde el corpus de sesiones + `docs/`
|
|
7
7
|
|
|
8
8
|
Genera un único `.md` que consolida N sesiones del workspace en un informe **ejecutivo/funcional**: qué se hizo, decisiones clave, resultados/conclusiones y pendientes/roadmap. **Read-only / reporte** — no commitea, no muta sesiones ni el corpus.
|
|
9
9
|
|
|
10
|
-
> Familia `export-*` (la única vía artefacto→`docs/`). **Funde** el espíritu de dos viejos exports en una sola salida a `docs/reports`: `export-report` (informe ejecutivo con tabla de componentes + diagrama de flujo) y `export-conclusions` (dedup de R-items cross-session). Modernizado: `docs/reports` en inglés, sin modos project/hub, y la prosa
|
|
10
|
+
> Familia `export-*` (la única vía artefacto→`docs/`). **Funde** el espíritu de dos viejos exports en una sola salida a `docs/reports`: `export-report` (informe ejecutivo con tabla de componentes + diagrama de flujo) y `export-conclusions` (dedup de R-items cross-session). Modernizado: `docs/reports` en inglés, sin modos project/hub, y la prosa sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol propio. Diseño: `docs/referencias/workflow-exports/export-reports.md`.
|
|
11
11
|
|
|
12
12
|
## Category
|
|
13
13
|
|
|
14
14
|
`docs/reports` — **única** carpeta `docs/` que este export escribe.
|
|
15
15
|
|
|
16
|
-
##
|
|
16
|
+
## Writing (convención ambiente, no rol)
|
|
17
17
|
|
|
18
|
-
|
|
18
|
+
La redacción del informe sigue las convenciones de redacción **ambientes**: el host auto-aplica una skill de writing instalada (si está presente) por su `description` — traducción técnico→ejecutiva, cota de longitud por audiencia, frases cortas, listas sobre prosa, sin relleno. Este export **no** compone un rol `writing` ni lo bindea; es **indiferente** a qué skill de redacción exista. Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el export **no depende** de él.
|
|
19
19
|
|
|
20
20
|
## When to use
|
|
21
21
|
|
|
@@ -91,9 +91,9 @@ Por sesión filtrada (`aw session-artifacts --code <NNN>`): el spec referido (qu
|
|
|
91
91
|
|
|
92
92
|
Extraer los R-items de `CONCLUSIONS`/`DECISION` (pendientes, diferidos, "próximos pasos"). Agrupar por slug; merge de duplicados anotando `origins[]`; si dos R-items del mismo slug se contradicen, marcarlos como conflicto para resolución explícita. **No** deduplicar los C-items (son específicos de cada análisis: se preservan con trazabilidad).
|
|
93
93
|
|
|
94
|
-
### Paso 4 — Sintetizar (
|
|
94
|
+
### Paso 4 — Sintetizar (prosa: convenciones ambientes)
|
|
95
95
|
|
|
96
|
-
Render aplicando
|
|
96
|
+
Render aplicando las convenciones de redacción ambientes (host): Resumen ejecutivo · Qué se hizo (agrupado por capacidad de negocio, **no** por sesión) · Componentes impactados (tabla) · Decisiones clave · Resultados/conclusiones · Pendientes/Roadmap (solo si hay R-items). Traducción técnico→ejecutiva y cota de longitud por `--audience`. Opcional: un `flowchart LR` simple de síntesis (con link `mermaid.ink`); el diagrama técnico detallado es de `export-diagrams`.
|
|
97
97
|
|
|
98
98
|
### Paso 5 — Escribir o reportar
|
|
99
99
|
|
|
@@ -110,6 +110,6 @@ Idempotente funcional: cada invocación toma el siguiente `NNN`; no sobrescribe
|
|
|
110
110
|
## Resources
|
|
111
111
|
|
|
112
112
|
- Design: `docs/referencias/workflow-exports/export-reports.md` · familia: [`../README.md`](../README.md).
|
|
113
|
-
-
|
|
113
|
+
- Redacción: convención **ambiente** (no rol) — el host auto-aplica una skill de writing instalada si está presente.
|
|
114
114
|
- Insumos: spec (`docs/specs`), `CONCLUSIONS`/`DECISION` (ver `docs/referencias/workflow-artifacts/`), plan-doc (`docs/plans`).
|
|
115
115
|
- Siblings: [`../export-scripts/SKILL.md`](../export-scripts/SKILL.md) · [`../export-manuals/SKILL.md`](../export-manuals/SKILL.md) · [`../export-diagrams/SKILL.md`](../export-diagrams/SKILL.md).
|
|
@@ -63,7 +63,7 @@ Mecanismo concreto por arnés (jun-2026; `~` parcial · `?` sin confirmar).
|
|
|
63
63
|
|
|
64
64
|
"Aprovechar las skills que el arnés tenga instaladas" se resuelve por el **mismo binding** de `.workflow/skills.toml`: un rol puede apuntar a una skill **instalada en el host** (de tercero, vía skills.sh) en vez del built-in. Regla:
|
|
65
65
|
|
|
66
|
-
- Si el host tiene una skill **mejor** para un rol (ej. un generador de diagramas superior para `diagrams`, un
|
|
66
|
+
- Si el host tiene una skill **mejor** para un rol (ej. un generador de diagramas superior para `diagrams`, o un investigador especializado para `research`), se la **bindea** en `.workflow/skills.toml` y el loop la compone sin cambios.
|
|
67
67
|
- El built-in default es el **piso**, no el techo: garantiza que el rol funcione en cualquier host; el binding lo **enriquece** donde el host puede más.
|
|
68
68
|
|
|
69
69
|
## Convención para el resto del corpus
|
package/skills/w/loops/README.md
CHANGED
|
@@ -92,7 +92,7 @@ spec-refine-loop ── CHASIS (patrón de referencia: objetivo persistente + v
|
|
|
92
92
|
hereda git/BD/no-export de plan-exec
|
|
93
93
|
```
|
|
94
94
|
|
|
95
|
-
El chasis **no es una capacidad bindeable**: *es* `spec-refine-loop` y los demás loops lo heredan. Lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`, `
|
|
95
|
+
El chasis **no es una capacidad bindeable**: *es* `spec-refine-loop` y los demás loops lo heredan. Lo enchufable son las **capacidades** que un loop compone (ej. `ui-design`, `sql`, `git`, `tools`), resueltas por `.workflow/skills.toml`.
|
|
96
96
|
|
|
97
97
|
## Composed capabilities (roles)
|
|
98
98
|
|
|
@@ -103,13 +103,12 @@ Los loops componen **capacidades por su rol**, no skills concretas; la skill que
|
|
|
103
103
|
| `ui-design` | `ui-spec` | `spec-refine-loop` (cuando hay UI) |
|
|
104
104
|
| `sql` | `sql` | research · `plan-exec-loop` · `quick-loop` |
|
|
105
105
|
| `git` | `git` | `plan-exec-loop` · `quick-loop` |
|
|
106
|
-
| `coding-standards` | `coding-standards` | `plan-exec-loop` · `quick-loop` |
|
|
107
|
-
| `writing` | `writing` | todos los loops |
|
|
108
106
|
| `research` | `research` | todos los loops (research inline) |
|
|
109
|
-
| `testing` | `testing` | `plan-exec-loop` · `quick-loop` |
|
|
110
107
|
| `tools` | `tools` | `plan-exec-loop` |
|
|
111
108
|
| `overview` | `workflow` | cualquiera (orientación) |
|
|
112
109
|
|
|
110
|
+
> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
|
|
111
|
+
|
|
113
112
|
`off` en config → capacidad desactivada: el loop sigue sin ella; si era necesaria, lo dice o pregunta al humano.
|
|
114
113
|
|
|
115
114
|
## Index
|
|
@@ -14,7 +14,7 @@ description: >-
|
|
|
14
14
|
se ejecuta); validación por fase y final (lo dependiente de migración no
|
|
15
15
|
aplicada se difiere como handoff a DBA); y SIN auto-export (escribe solo
|
|
16
16
|
docs/plans + docs/tools; el resto queda como artefacto de session para
|
|
17
|
-
export-*). Compone git,
|
|
17
|
+
export-*). Compone git, tools y sql. Lo arranca
|
|
18
18
|
/w:plan-exec y es reanudable. Invocar para implementar un plan ya generado.
|
|
19
19
|
---
|
|
20
20
|
|
|
@@ -55,7 +55,9 @@ Del chasis [`spec-refine-loop`](../spec-refine-loop/SKILL.md), sin cambios:
|
|
|
55
55
|
|
|
56
56
|
## Composes
|
|
57
57
|
|
|
58
|
-
`git` (rama segura + commits propuestos) · `
|
|
58
|
+
`git` (rama segura + commits propuestos) · `tools` (herramientas reusables → `docs/tools`) · `sql` (regla BD). Todas resueltas por `.workflow/skills.toml`; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta.
|
|
59
|
+
|
|
60
|
+
> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
|
|
59
61
|
|
|
60
62
|
## Internal sessions (managed)
|
|
61
63
|
|
|
@@ -48,7 +48,9 @@ QUICK
|
|
|
48
48
|
|
|
49
49
|
## Composes
|
|
50
50
|
|
|
51
|
-
`git` · `
|
|
51
|
+
`git` · `sql` (regla BD) · `research` (inline). Resueltas por `.workflow/skills.toml`.
|
|
52
|
+
|
|
53
|
+
> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
|
|
52
54
|
|
|
53
55
|
## Delta QUICK — minimal ceremony
|
|
54
56
|
|
|
@@ -114,7 +114,9 @@ El **CLI es dueño del número**: `aw session-create` antepone un `NNN` **global
|
|
|
114
114
|
|
|
115
115
|
El gap **UI sin especificar** (cuando el requerimiento involucra UI; ver *Gap taxonomy*) se resuelve **componiendo** la capacidad **`ui-design`** (default built-in `ui-spec`; rebindeable vía `.workflow/skills.toml`): autora el UI spec nativamente (estructura, vocabulario, formato Markdown). Es un tercer modo de resolución de gap (junto a *research* y *humano*): el loop aporta la iteración/Q&A que el viejo servicio no tenía (design-system, tema, variantes, desambiguación) **vía la misma structured-choice**, y lo integra como sección `## UI spec` del spec.
|
|
116
116
|
|
|
117
|
-
Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research)
|
|
117
|
+
Otras capacidades transversales que el chasis usa siempre: `research` (research **inline**, ver abajo), `sql` (regla BD en research). Todas se resuelven por config; `off` → el loop sigue sin la capacidad y, si era necesaria, lo dice o pregunta. La **prosa del spec** sigue las convenciones de redacción **ambientes** (el host auto-aplica una skill de writing instalada si está presente), no un rol compuesto.
|
|
118
|
+
|
|
119
|
+
> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
|
|
118
120
|
|
|
119
121
|
## Deliverable schema (el spec, editado in place)
|
|
120
122
|
|
package/skills/w/roles/README.md
CHANGED
|
@@ -8,17 +8,14 @@
|
|
|
8
8
|
|
|
9
9
|
## Capability catalog
|
|
10
10
|
|
|
11
|
-
All
|
|
11
|
+
All 7 roles, their built-in defaults, their tier, and which loops/exports compose them:
|
|
12
12
|
|
|
13
13
|
| Role | Default built-in | Tier | Composed by |
|
|
14
14
|
|---|---|---|---|
|
|
15
15
|
| `ui-design` | [`ui-spec`](ui-spec/SKILL.md) | must | `spec-refine-loop` (when requirement involves UI) |
|
|
16
16
|
| `sql` | `sql` | must | inline research · `plan-exec-loop` · `quick-loop` · `export-scripts` |
|
|
17
17
|
| `git` | `git` | must | `plan-exec-loop` · `quick-loop` |
|
|
18
|
-
| `coding-standards` | `coding-standards` | must | `plan-exec-loop` · `quick-loop` |
|
|
19
|
-
| `writing` | `writing` | must | all loops · `export-manuals` · `export-reports` |
|
|
20
18
|
| `research` | [`research`](research/SKILL.md) | should | all loops (on-demand investigation) |
|
|
21
|
-
| `testing` | [`testing`](testing/SKILL.md) | should | `plan-exec-loop` · `quick-loop` |
|
|
22
19
|
| `tools` | [`tools`](tools/SKILL.md) | should | `plan-exec-loop` |
|
|
23
20
|
| `diagrams` | [`diagrams`](diagrams/SKILL.md) | should | `export-diagrams` |
|
|
24
21
|
| `overview` | `workflow` | should | any loop (orientation about the workflow itself) |
|
|
@@ -27,6 +24,8 @@ All 10 roles, their built-in defaults, their tier, and which loops/exports compo
|
|
|
27
24
|
- `must` — core to almost every session; built-in always active unless explicitly `off`.
|
|
28
25
|
- `should` — loaded on-demand; active by default but lower priority to override.
|
|
29
26
|
|
|
27
|
+
> **Convenciones ambientes (no roles).** Los estándares de código, testing y redacción **no son roles** del workflow ni se bindean: son **skills standalone que el host auto-descubre por su `description`** y aplica cuando son relevantes. El workflow es **indiferente** (no las lee ni las busca). Una familia útil vive en el plugin `dev-conventions` del marketplace, pero el workflow **no depende** de él.
|
|
28
|
+
|
|
30
29
|
---
|
|
31
30
|
|
|
32
31
|
## Binding cascade
|
|
@@ -59,18 +58,15 @@ built-in default
|
|
|
59
58
|
# ui-design = "ui-spec"
|
|
60
59
|
# sql = "sql"
|
|
61
60
|
# git = "git"
|
|
62
|
-
# coding-standards = "coding-standards"
|
|
63
|
-
# writing = "writing"
|
|
64
61
|
# research = "research"
|
|
65
|
-
# testing = "testing"
|
|
66
62
|
# tools = "tools"
|
|
67
63
|
# diagrams = "diagrams"
|
|
68
64
|
# overview = "workflow"
|
|
69
65
|
|
|
70
66
|
# Override examples:
|
|
71
|
-
testing = "off" # disable testing capability
|
|
72
67
|
ui-design = "acme/figma-spec" # third-party skill installed via skills.sh
|
|
73
68
|
diagrams = "mermaid-only" # custom built installed locally
|
|
69
|
+
sql = "off" # disable the sql capability
|
|
74
70
|
```
|
|
75
71
|
|
|
76
72
|
### Override: point to a third-party skill
|
|
@@ -86,10 +82,10 @@ ui-design = "acme/figma-spec"
|
|
|
86
82
|
|
|
87
83
|
```toml
|
|
88
84
|
[skills]
|
|
89
|
-
|
|
85
|
+
sql = "off"
|
|
90
86
|
```
|
|
91
87
|
|
|
92
|
-
The loop that composes `
|
|
88
|
+
The loop that composes `sql` will skip it. If the task required the capability and the role is `off`, the loop should inform the human and ask how to proceed.
|
|
93
89
|
|
|
94
90
|
### Override: use a different built-in
|
|
95
91
|
|
|
@@ -113,18 +109,15 @@ Lists the resolved binding for every role in the current workspace, showing whic
|
|
|
113
109
|
Example output:
|
|
114
110
|
|
|
115
111
|
```
|
|
116
|
-
Role Resolved skill
|
|
117
|
-
-----------------
|
|
118
|
-
ui-design ui-spec
|
|
119
|
-
sql sql
|
|
120
|
-
git git
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
tools tools built-in
|
|
126
|
-
diagrams mermaid-only global (~/.workflow/skills.toml)
|
|
127
|
-
overview workflow built-in
|
|
112
|
+
Role Resolved skill Source
|
|
113
|
+
----------------- ----------------------- -----------
|
|
114
|
+
ui-design ui-spec built-in
|
|
115
|
+
sql sql built-in
|
|
116
|
+
git git built-in
|
|
117
|
+
research research built-in
|
|
118
|
+
tools tools built-in
|
|
119
|
+
diagrams mermaid-only global (~/.workflow/skills.toml)
|
|
120
|
+
overview workflow built-in
|
|
128
121
|
```
|
|
129
122
|
|
|
130
123
|
---
|
|
@@ -142,7 +135,7 @@ Each `SKILL.md` follows this schema:
|
|
|
142
135
|
|
|
143
136
|
| Section | Content |
|
|
144
137
|
|---|---|
|
|
145
|
-
| Frontmatter `name:` | kebab-case; MUST equal the binding name (`research`, `
|
|
138
|
+
| Frontmatter `name:` | kebab-case; MUST equal the binding name (`research`, `tools`, etc.) |
|
|
146
139
|
| Frontmatter `description:` | rich description: what + when; drives automatic selection |
|
|
147
140
|
| `## Role` | which capability role this implements (its skills.toml slot) |
|
|
148
141
|
| `## Purpose` | what it does |
|
|
@@ -21,7 +21,7 @@ Dar al `plan-exec-loop` la capacidad de crear herramientas y utilidades auxiliar
|
|
|
21
21
|
|
|
22
22
|
| Tipo | Rol | ¿Quién lo maneja? |
|
|
23
23
|
|---|---|---|
|
|
24
|
-
| Código de producto (services, controllers, components) | cambio en el repo fuente | `plan-exec-loop`
|
|
24
|
+
| Código de producto (services, controllers, components) | cambio en el repo fuente | `plan-exec-loop` (estilo: convenciones ambientes del host) |
|
|
25
25
|
| Tool / utilidad auxiliar creada por el plan | herramienta de soporte | esta skill (`tools`) |
|
|
26
26
|
| Script SQL de migración | dato persistente | `sql` + `export-scripts` |
|
|
27
27
|
|
|
@@ -120,7 +120,7 @@ Si la tool genera o manipula SQL:
|
|
|
120
120
|
|
|
121
121
|
### Code quality baseline
|
|
122
122
|
|
|
123
|
-
Al autorar el código de la tool,
|
|
123
|
+
Al autorar el código de la tool, seguir las convenciones de código **ambientes** del host (auto-descubiertas por su `description`; no es un rol del workflow ni se bindea). Si no hay una skill de estándares aplicable, usar los estándares del lenguaje detectado:
|
|
124
124
|
- **Shell**: shellcheck-compatible, variables entre comillas, `set -euo pipefail`.
|
|
125
125
|
- **Node/TS**: tipado explícito, sin `any` salvo justificación, error handling explícito.
|
|
126
126
|
- **Python**: type hints, docstring en funciones públicas, manejo de excepciones específico.
|
|
@@ -1,82 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: coding-standards
|
|
3
|
-
description: >-
|
|
4
|
-
Coding standards capability — built-in default for the `coding-standards` role.
|
|
5
|
-
Stack-agnostic principles (SOLID, fail-fast, descriptive names, small methods,
|
|
6
|
-
reuse over duplication) plus per-stack conventions (Java/Spring, Angular/TypeScript,
|
|
7
|
-
Node), security (no secrets in code or logs, parametrized SQL, DB read-only via MCP),
|
|
8
|
-
HTTP error handling (never silence errors), logging levels, and FE-BE integration
|
|
9
|
-
rules (unified sparse DTO, PATCH for edit, no hidden fallbacks). Use when a loop
|
|
10
|
-
implements, reviews or refactors code.
|
|
11
|
-
---
|
|
12
|
-
|
|
13
|
-
# coding-standards — Coding standards capability
|
|
14
|
-
|
|
15
|
-
## Role
|
|
16
|
-
|
|
17
|
-
`coding-standards` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`).
|
|
18
|
-
|
|
19
|
-
## Purpose
|
|
20
|
-
|
|
21
|
-
Aportar los estándares de código que la IA aplica al **implementar, revisar o refactorizar**. Read-only por diseño: carga reglas, no edita ni ejecuta nada por sí misma — el loop consumidor materializa el código.
|
|
22
|
-
|
|
23
|
-
## Composed by
|
|
24
|
-
|
|
25
|
-
- **`plan-exec-loop`** — al implementar/refactorizar las tasks del plan.
|
|
26
|
-
- **`quick-loop`** — al implementar el atajo liviano.
|
|
27
|
-
|
|
28
|
-
## Knowledge
|
|
29
|
-
|
|
30
|
-
### Principios generales
|
|
31
|
-
|
|
32
|
-
- **SOLID** — Single Responsibility, Open/Closed, Liskov, Interface Segregation, Dependency Inversion.
|
|
33
|
-
- **Fail fast** — validar y retornar al inicio del método (early returns, evitar nesting).
|
|
34
|
-
- **Nombres descriptivos** — el código habla por sí mismo; comentarios solo para el "por qué".
|
|
35
|
-
- **Métodos pequeños** — una sola responsabilidad por función.
|
|
36
|
-
- **Composición sobre herencia**.
|
|
37
|
-
- **Reutilización antes que duplicación (DRY)** — antes de crear componente/función/clase, revisar si ya existe en `shared/` (frontend) o `common/`/`util/` (backend). Si un patrón aparece 2-3 veces, proponer extracción.
|
|
38
|
-
|
|
39
|
-
### Estándares por stack
|
|
40
|
-
|
|
41
|
-
- **Java / Spring Boot**: Constructor Injection (sin Field Injection), `@Transactional(readOnly=true)` para lecturas, Java records para DTOs Request/Response, Jakarta Validation para inputs.
|
|
42
|
-
- **Angular / TypeScript**: constructor injection, `async` pipe en templates, evitar `any`, FormBuilder reactivo sobre `ngModel` directo, arquitectura `@data`/`@presentation`, normalización de tipos.
|
|
43
|
-
- **Node / otros**: mismos principios generales; aplicar las convenciones idiomáticas del proyecto detectado.
|
|
44
|
-
|
|
45
|
-
### Integración FE-BE (cuando el cambio cruza frontend y backend)
|
|
46
|
-
|
|
47
|
-
- **R1 — Sparse DTO unificado**: mismo DTO `<Feature>SaveRequest` para create + edit, todos los campos nullable. `null` = "no tocar".
|
|
48
|
-
- **R2 — PATCH para edit**: `@PatchMapping` en BE, `http.patch()` en FE. POST solo para create. PUT solo si replace total justificado.
|
|
49
|
-
- **R3 — FE envía solo cambios**: payload diff entre `formValue` y entidad original.
|
|
50
|
-
- **R4 — Sin fallbacks que oculten errores**: prohibido `catchError(() => of([]))` en FE; prohibido try/catch con fallback al método legacy en BE durante migraciones. Usar feature flags explícitas para rollout gradual.
|
|
51
|
-
- **R5 — Validación BE con Bean Validation + groups**: `@NotNull(groups = OnCreate.class)` para distinguir reglas POST vs PATCH cuando comparten DTO.
|
|
52
|
-
- **R6 — DB stub-first**: funciones/SP nuevas arrancan devolviendo mock (`RETURN '[]'::jsonb`); implementación real en una fase posterior.
|
|
53
|
-
|
|
54
|
-
### Seguridad
|
|
55
|
-
|
|
56
|
-
- **Nunca** exponer secrets, API keys ni credenciales en código.
|
|
57
|
-
- **Nunca** logear datos sensibles (contraseñas, tokens, datos personales).
|
|
58
|
-
- **Siempre** parametrizar queries SQL (nunca concatenar strings).
|
|
59
|
-
- **BD vía MCP es READONLY**. Modificaciones a BD solo como scripts SQL versionados (ver rol `sql`); las aplica el **usuario**, nunca la IA — ni por MCP, ni `Bash`, ni `psql`, ni driver. (Invariante 4.)
|
|
60
|
-
|
|
61
|
-
### Manejo de errores HTTP
|
|
62
|
-
|
|
63
|
-
- **Nunca** silenciar errores HTTP con `catchError(() => of([]))` ni equivalentes. Los errores del backend se propagan al usuario (toast/mensaje) para detectar regresiones en guardado/sincronización/creación. Para reintentos usar operadores explícitos (`retry`, `retryWhen`), no silenciar.
|
|
64
|
-
|
|
65
|
-
### Logging
|
|
66
|
-
|
|
67
|
-
- `ERROR` — fallos que requieren atención inmediata.
|
|
68
|
-
- `WARN` — situaciones inesperadas pero manejadas.
|
|
69
|
-
- `INFO` — eventos de negocio relevantes (inicio/fin de procesos).
|
|
70
|
-
- `DEBUG` — detalle técnico para diagnóstico.
|
|
71
|
-
|
|
72
|
-
### Convenciones de BD (nomenclatura)
|
|
73
|
-
|
|
74
|
-
Esquemas `esq_`, tablas `tb_`, sequences `seq_`, funciones `fn_`/procedimientos `sp_`, patrón maestra-detalle, auditoría en `esq_audit`. Para autoría de scripts SQL (estilo, header, categorías, rollback) usar el rol **`sql`**.
|
|
75
|
-
|
|
76
|
-
## Output
|
|
77
|
-
|
|
78
|
-
Ninguno propio. La skill aporta reglas; el código lo escribe el loop. Cuando el cambio toca BD, delega la autoría de scripts al rol `sql`. Nunca exporta a `docs/` (invariante 1).
|
|
79
|
-
|
|
80
|
-
## Source
|
|
81
|
-
|
|
82
|
-
Reciclada de `standards/coding-standards/` (SKILL.md + references Java/Spring, Angular/TypeScript, fe-be-integration, database-conventions, frontend-structure, project-structure). Los principios UX de mantenimientos CRUD (formularios, listados, modales) viven en el rol `ui-spec`/`ui-design`; la autoría de scripts SQL en el rol `sql`. Se descarta la dependencia de `profile.json` y de comandos CLI de la doctrina vieja.
|
|
@@ -1,180 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: testing
|
|
3
|
-
description: >
|
|
4
|
-
Estrategia y ejecución de pruebas: selecciona niveles (unit / integration / e2e),
|
|
5
|
-
resuelve comandos por stack detectado, guía la convención de nombres y estructura de tests.
|
|
6
|
-
Pregunta al humano antes de ejecutar; nunca lanza el test runner sin confirmación explícita.
|
|
7
|
-
Compuesta por plan-exec-loop y quick-loop durante la fase de validación de cambios.
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
# testing — Test strategy and execution capability
|
|
11
|
-
|
|
12
|
-
## Role
|
|
13
|
-
|
|
14
|
-
`testing` — implementación built-in por defecto. Rebindeable a otra skill (de tercero o `off`) en `.workflow/skills.toml`.
|
|
15
|
-
|
|
16
|
-
## Purpose
|
|
17
|
-
|
|
18
|
-
Dar a los loops la capacidad de razonar sobre tests: qué nivel aplicar, con qué comando, con qué convención. **No ejecuta tests de forma autónoma** — primero pregunta al humano si quiere que el loop los corra, o si los correrá manualmente, o si no hacen falta en esta sesión.
|
|
19
|
-
|
|
20
|
-
## Composed by
|
|
21
|
-
|
|
22
|
-
| Loop | Cuándo la compone |
|
|
23
|
-
|---|---|
|
|
24
|
-
| `plan-exec-loop` | durante validation de cada task ejecutada |
|
|
25
|
-
| `quick-loop` | cuando el cambio quick requiere verificación |
|
|
26
|
-
|
|
27
|
-
## Knowledge
|
|
28
|
-
|
|
29
|
-
### Execution rule
|
|
30
|
-
|
|
31
|
-
Por defecto, **no ejecutar pruebas automáticamente**. Antes de correr cualquier test runner, preguntar al humano vía *structured-choice* (capacidad del arnés — ver `../../harness/SKILL.md`). En **Claude Code** es `AskUserQuestion` (máx 4 preguntas/llamada → **≤3 preguntas de contenido + 1 control `flow`**); en un arnés sin elección estructurada, degrada a **markdown numerado**.
|
|
32
|
-
|
|
33
|
-
```
|
|
34
|
-
structured-choice:
|
|
35
|
-
"¿Correr los tests?"
|
|
36
|
-
[a] Sí, el loop los ejecuta
|
|
37
|
-
[b] Los corro yo manualmente
|
|
38
|
-
[c] No hace falta en esta sesión
|
|
39
|
-
```
|
|
40
|
-
|
|
41
|
-
Solo saltear la pregunta si el workspace declara `Validation mode: auto` en `.workflow/config.toml`.
|
|
42
|
-
|
|
43
|
-
### Test levels
|
|
44
|
-
|
|
45
|
-
Tres niveles universales (adaptados al stack detectado):
|
|
46
|
-
|
|
47
|
-
| Nivel | Alcance | Cuándo usarlo |
|
|
48
|
-
|---|---|---|
|
|
49
|
-
| **a) Unit** | Lógica aislada (servicios, utils, mappers) | Fix puntual, lógica sin dependencias externas |
|
|
50
|
-
| **b) Integration** | Unit + capa de API/controladores | Endpoint nuevo o modificado |
|
|
51
|
-
| **c) Full** | Integration + contexto completo + e2e | Feature completa, flujo crítico, integración entre capas |
|
|
52
|
-
|
|
53
|
-
### Stack resolution
|
|
54
|
-
|
|
55
|
-
El stack se detecta por archivos de manifest presentes en el workspace. Precedencia: si el bloque `WORKSPACE → Stack` declara override de build/wrapper, usarlo.
|
|
56
|
-
|
|
57
|
-
#### Spring Boot (Maven)
|
|
58
|
-
|
|
59
|
-
| Nivel | Framework | Comando |
|
|
60
|
-
|---|---|---|
|
|
61
|
-
| a) Unit | JUnit 5 + Mockito | `./mvnw test -Dtest=ClaseTest` |
|
|
62
|
-
| b) Integration | + MockMvc | `./mvnw test` |
|
|
63
|
-
| c) Full | + @SpringBootTest | `./mvnw verify` |
|
|
64
|
-
|
|
65
|
-
> Windows: `mvnw.cmd` en lugar de `./mvnw`.
|
|
66
|
-
|
|
67
|
-
#### Spring Boot (Gradle)
|
|
68
|
-
|
|
69
|
-
| Nivel | Comando |
|
|
70
|
-
|---|---|
|
|
71
|
-
| a) Unit | `./gradlew test --tests ClaseTest` |
|
|
72
|
-
| b) Integration | `./gradlew test` |
|
|
73
|
-
| c) Full | `./gradlew integrationTest` (o `check`) |
|
|
74
|
-
|
|
75
|
-
#### Angular
|
|
76
|
-
|
|
77
|
-
| Nivel | Framework | Comando |
|
|
78
|
-
|---|---|---|
|
|
79
|
-
| a) Unit | Jasmine + Karma (o Jest) | `ng test --watch=false` |
|
|
80
|
-
| b) Integration | + TestBed + ComponentFixture | `ng test --watch=false` |
|
|
81
|
-
| c) Full | + Cypress/Playwright si configurado | `npm run e2e` |
|
|
82
|
-
|
|
83
|
-
#### Node / TypeScript genérico
|
|
84
|
-
|
|
85
|
-
| Nivel | Comando |
|
|
86
|
-
|---|---|
|
|
87
|
-
| a) Unit | `npm test` (script `test` en `package.json`) |
|
|
88
|
-
| b) Integration | `npm test` con suites de integración |
|
|
89
|
-
| c) Full | `npm run test:e2e` o según config |
|
|
90
|
-
|
|
91
|
-
#### Resolución automática
|
|
92
|
-
|
|
93
|
-
1. `mvnw` / `mvnw.cmd` → Maven wrapper.
|
|
94
|
-
2. `gradlew` → Gradle wrapper.
|
|
95
|
-
3. `angular.json` → `ng test`.
|
|
96
|
-
4. `package.json` con script `test` → `npm test`.
|
|
97
|
-
5. Si hay override en `WORKSPACE → Stack` → usarlo.
|
|
98
|
-
|
|
99
|
-
### Naming conventions
|
|
100
|
-
|
|
101
|
-
**Java:** clase `[Objetivo]Test.java`, método `[metodo]_[escenario]_[resultado]`. Estructura Arrange-Act-Assert.
|
|
102
|
-
|
|
103
|
-
```java
|
|
104
|
-
@Test
|
|
105
|
-
void enviar_conEmailValido_retornaExito() {
|
|
106
|
-
// Arrange
|
|
107
|
-
var request = new NotificacionRequest("user@example.com", "Asunto", "template", Map.of());
|
|
108
|
-
when(emailProvider.send(any())).thenReturn(true);
|
|
109
|
-
// Act
|
|
110
|
-
var resultado = service.enviar(request);
|
|
111
|
-
// Assert
|
|
112
|
-
assertThat(resultado).isTrue();
|
|
113
|
-
}
|
|
114
|
-
```
|
|
115
|
-
|
|
116
|
-
**Angular / TypeScript:** archivo `[nombre].spec.ts`, bloques `describe` / `it`. Usar `TestBed` para componentes.
|
|
117
|
-
|
|
118
|
-
```typescript
|
|
119
|
-
describe('AuthService', () => {
|
|
120
|
-
it('should return token on login', () => {
|
|
121
|
-
// ...
|
|
122
|
-
});
|
|
123
|
-
});
|
|
124
|
-
```
|
|
125
|
-
|
|
126
|
-
### Level selection prompt (to show the human)
|
|
127
|
-
|
|
128
|
-
Adaptar al stack resuelto. Ejemplo para Spring Boot:
|
|
129
|
-
|
|
130
|
-
```
|
|
131
|
-
¿Qué nivel de pruebas aplicamos?
|
|
132
|
-
a) Unitarios — JUnit 5 + Mockito (rápido, aislado)
|
|
133
|
-
b) Integración — + MockMvc controllers
|
|
134
|
-
c) Completo — + @SpringBootTest (contexto Spring completo)
|
|
135
|
-
```
|
|
136
|
-
|
|
137
|
-
El humano puede cambiar de nivel en cualquier momento o decidir no ejecutar desde el loop.
|
|
138
|
-
|
|
139
|
-
### Execution and logging
|
|
140
|
-
|
|
141
|
-
1. Confirmar que el humano quiere ejecución desde el loop (ver "Execution rule").
|
|
142
|
-
2. Ejecutar el comando resuelto según stack y nivel.
|
|
143
|
-
3. Registrar resultado en `TEST_LOG.md` **solo si** el humano pidió registro formal o la ejecución fue desde el loop.
|
|
144
|
-
4. Si el humano ya validó manualmente, no repetir; anotar una línea breve si aporta trazabilidad.
|
|
145
|
-
5. Si hay fallos y el humano quiere continuar: corregir y re-ejecutar.
|
|
146
|
-
|
|
147
|
-
### TestBuilder pattern (Java)
|
|
148
|
-
|
|
149
|
-
Para construir fixtures reutilizables sin acoplar los tests al constructor de producción:
|
|
150
|
-
|
|
151
|
-
```java
|
|
152
|
-
public class NotificacionTestBuilder {
|
|
153
|
-
private String destinatario = "test@example.com";
|
|
154
|
-
private String estado = "PENDIENTE";
|
|
155
|
-
|
|
156
|
-
public static NotificacionTestBuilder builder() { return new NotificacionTestBuilder(); }
|
|
157
|
-
|
|
158
|
-
public NotificacionTestBuilder destinatario(String val) { this.destinatario = val; return this; }
|
|
159
|
-
public NotificacionTestBuilder estado(String val) { this.estado = val; return this; }
|
|
160
|
-
|
|
161
|
-
public Notificacion build() {
|
|
162
|
-
var e = new Notificacion();
|
|
163
|
-
e.setDestinatario(destinatario);
|
|
164
|
-
e.setEstado(estado);
|
|
165
|
-
return e;
|
|
166
|
-
}
|
|
167
|
-
}
|
|
168
|
-
```
|
|
169
|
-
|
|
170
|
-
## Output
|
|
171
|
-
|
|
172
|
-
No produce artefactos de forma autónoma. Cuando el humano confirma ejecución:
|
|
173
|
-
- Corre el comando resuelto y reporta el resultado inline.
|
|
174
|
-
- Escribe `TEST_LOG.md` en la sesión activa solo si fue pedido explícitamente.
|
|
175
|
-
|
|
176
|
-
No gradua a `docs/` (invariant #1).
|
|
177
|
-
|
|
178
|
-
## Source
|
|
179
|
-
|
|
180
|
-
Reciclado de `agent-workflow/standards/testing-strategy/` del bundle viejo (v0.1.0). Se conserva: los tres niveles (a/b/c), la regla de confirmación antes de ejecutar, la resolución de stack por manifest, los naming conventions, la tabla de comandos por framework. Se descarta: la referencia al bloque `AW-PROJECT → Stack` (reemplazado por `WORKSPACE → Stack`), el `TEST_LOG.md` obligatorio, el sandbox-readonly-rules legacy, referencias a `plan mode` del sistema anterior.
|
|
@@ -1,90 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: writing
|
|
3
|
-
description: >-
|
|
4
|
-
Clear technical writing capability — built-in default for the `writing` role. Rules
|
|
5
|
-
for any prose the AI produces in agent-workflow context: spec/plan/session artifacts,
|
|
6
|
-
commit messages, PR descriptions, export deliverables (manuals/reports). Short
|
|
7
|
-
sentences, lists over prose, one idea per line, "what + why" on one line, no jargon,
|
|
8
|
-
no filler. Use across all loops and in export-manuals / export-reports.
|
|
9
|
-
---
|
|
10
|
-
|
|
11
|
-
# writing — Clear technical writing
|
|
12
|
-
|
|
13
|
-
## Role
|
|
14
|
-
|
|
15
|
-
`writing` — built-in default. Rebindable in `.workflow/skills.toml` (third-party skill or `off`). The most broadly composed role.
|
|
16
|
-
|
|
17
|
-
## Purpose
|
|
18
|
-
|
|
19
|
-
Reglas de estilo y formato para **toda la prosa** que la IA produce en contexto agent-workflow. Read-only por diseño: carga reglas; el `.md` lo materializa el consumidor (loop o export).
|
|
20
|
-
|
|
21
|
-
## Composed by
|
|
22
|
-
|
|
23
|
-
- **Todos los loops** — al escribir specs, planes, artefactos de sesión, mensajes de commit, descripciones de PR.
|
|
24
|
-
- **`export-manuals`** — al redactar manuales técnicos (`docs/manuals`).
|
|
25
|
-
- **`export-reports`** — al redactar informes ejecutivos (`docs/reports`).
|
|
26
|
-
|
|
27
|
-
(También aplica a respuestas en chat sobre temas agent-workflow.)
|
|
28
|
-
|
|
29
|
-
## Knowledge
|
|
30
|
-
|
|
31
|
-
### Las 6 reglas
|
|
32
|
-
|
|
33
|
-
1. **Frases cortas**: máximo ~15 palabras. Si pasa de 20, partir en dos.
|
|
34
|
-
2. **Listas sobre prosa**: 3+ ideas paralelas van en bullets. Prosa solo para narrar.
|
|
35
|
-
3. **Una idea por línea**: si el bullet usa "y" o ";" para meter una segunda idea, separar.
|
|
36
|
-
4. **"Qué + por qué" en una línea**: formato `<qué>: <por qué corto>`. Sin párrafo aparte para el "por qué".
|
|
37
|
-
5. **Sin jerga ni abreviaturas raras**: palabras comunes. Términos técnicos (MCP, C4) OK; abreviaturas inventadas (ej. "TLDR del CTX") no.
|
|
38
|
-
6. **Sin relleno**: borrar "es importante notar que…", "cabe destacar…", "como se mencionó…", "en conclusión…". La idea va directo.
|
|
39
|
-
|
|
40
|
-
### Palabras a evitar / preferir
|
|
41
|
-
|
|
42
|
-
| Evitar | Preferir |
|
|
43
|
-
|---|---|
|
|
44
|
-
| "es importante notar que" / "cabe destacar" | (borrar, empezar con la idea) |
|
|
45
|
-
| "en otras palabras" / "asimismo" | (borrar) / "también" |
|
|
46
|
-
| "se procede a" / "llevar a cabo" | verbo directo / "hacer" |
|
|
47
|
-
| "implementar la funcionalidad de X" | "implementar X" |
|
|
48
|
-
| "realizar la validación de" | "validar" |
|
|
49
|
-
| "a los efectos de" / "en el marco de" | "para" / "en" |
|
|
50
|
-
| "no obstante" / "previamente mencionado" | "pero" / "antes" |
|
|
51
|
-
| "TLDR", "FYI", "WIP" | escribir la palabra completa |
|
|
52
|
-
|
|
53
|
-
### Ejemplo antes / después
|
|
54
|
-
|
|
55
|
-
Antes:
|
|
56
|
-
> Es importante notar que cada llamada implica un round-trip al servidor MCP además del consumo de tokens correspondiente al JSON de respuesta.
|
|
57
|
-
|
|
58
|
-
Después (-50%):
|
|
59
|
-
> Cada llamada MCP cuesta un round-trip y los tokens del JSON.
|
|
60
|
-
|
|
61
|
-
Decisión densa, antes:
|
|
62
|
-
> Se decidió, luego de analizar las alternativas, implementar la validación de roles solo en el frontend, dado que el backend no requiere la lógica y evita duplicar la regla.
|
|
63
|
-
|
|
64
|
-
Después:
|
|
65
|
-
> **Decisión**: validar permisos solo en el frontend.
|
|
66
|
-
> **Por qué**: el backend no necesita la lógica; evita duplicar la regla.
|
|
67
|
-
|
|
68
|
-
### Cuándo SÍ se permite prosa larga
|
|
69
|
-
|
|
70
|
-
- Resúmenes ejecutivos donde la decisión necesita 4-6 oraciones para sostenerse.
|
|
71
|
-
- Cadena causal de un incidente (causa raíz puede requerir un párrafo).
|
|
72
|
-
- Tradeoffs de UX que necesitan explicación.
|
|
73
|
-
|
|
74
|
-
Aún ahí: oraciones simples encadenadas, no oraciones largas.
|
|
75
|
-
|
|
76
|
-
### Aplicación a los documentos del modelo nuevo
|
|
77
|
-
|
|
78
|
-
- **spec** (`docs/specs`): brief y criterios de aceptación claros; la sección `## UI spec` la formatea el rol `ui-design`.
|
|
79
|
-
- **plan** (`docs/plans`): resumen + fases + tasks con dependencias; tasks sin código inline (el código va en evidencia y se referencia).
|
|
80
|
-
- **decisiones**: `**Decisión**:` + `**Por qué**:`, 3-6 líneas; si es obvia, no se registra.
|
|
81
|
-
- **commit messages / PR**: mismas reglas (frases cortas, sin jerga, sin relleno). Formato canónico del mensaje en el rol `git`.
|
|
82
|
-
- **export manuals/reports**: audiencia operadores/gerencia; bullets sobre prosa, sin relleno corporativo.
|
|
83
|
-
|
|
84
|
-
## Output
|
|
85
|
-
|
|
86
|
-
Ninguno propio. La skill aporta reglas; el `.md` lo escribe el consumidor (loop o export). Cuando escribe a `docs/`, lo hace solo el export que la compone (invariante 1) y solo en su carpeta (invariante 2).
|
|
87
|
-
|
|
88
|
-
## Source
|
|
89
|
-
|
|
90
|
-
Reciclada de `standards/redaccion-simple/` (las 6 reglas, tabla evitar/preferir, ejemplos, cuándo permitir prosa larga). Se descarta el catálogo de estructuras por artefacto del modelo viejo (OBJETIVO/DECISIONES/etc.); los documentos del modelo nuevo son spec/plan + artefactos de sesión, y su estructura la definen los loops y exports.
|