@trycore/spec-build-harness 0.7.0 → 0.8.0

package/docs/commands.md

@@ -2,8 +2,8 @@
 
 Esta referencia cubre los **dos planos de operación** del arnés de construcción:
 
-1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.3.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
-2. Los **slash commands de Claude Code** (`/opsx:*` + `/build:onboard` + `/build:reflect`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
+1. El **CLI `trycore-build`** (binario Node, paquete `@trycore/spec-build-harness` v0.7.0) — instala, actualiza, diagnostica y desinstala el arnés en el proyecto consumidor. Captura el **stack mecánico**.
+2. Los **slash commands de Claude Code** (`/opsx:*` + los 7 `/build:*`: `onboard`, `reflect`, `slice`, `release`, `work`, `resume`, `front`) — operan el pipeline de dos loops, resuelven la parametrización **semántica** del dominio y capturan el conocimiento aprendido por slice.
 
 > **División de responsabilidades del onboarding (dos capas).** Un binario Node **no puede** escribir la auto-memory de Claude. Por eso `trycore-build init` siembra archivos y captura el stack mecánico (lenguaje/deps, package manager, runtime, ruta del PRD), y el slash command `/build:onboard` —ejecutado por Claude— lee el PRD, pregunta por PII / capa de servicios externos-IA / capa determinista / secretos / decisiones de alto impacto, resuelve los `{{placeholders}}` del bloque marcado de `CLAUDE.md` y escribe la auto-memory.
 
@@ -52,7 +52,7 @@ Solo `init` y `update` aceptan flags. `status`, `uninstall` y `doctor` toman ún
 
 ## 2. Slash commands de Claude Code
 
-El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → `/build:onboard` y `/build:reflect`.
+El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y `.claude/commands/build/` → los 7 `/build:*` (`onboard`, `reflect`, `slice`, `release`, `work`, `resume`, `front`).
 
 ### `/opsx:*` — pipeline OpenSpec
 
@@ -69,6 +69,24 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 | `/opsx:onboard` | Onboarding guiado: recorre un ciclo completo del workflow OpenSpec con narración (tutorial de aprendizaje). |
 | `/opsx:sync` | Sincroniza los delta specs de un cambio hacia los specs principales. |
 
+### `/build:slice` — entrada del inner loop
+
+| Slash command | Propósito |
+|---|---|
+| `/build:slice` | Punto de entrada del **inner loop** sobre una épica (`EP-XXX`). Adaptador delgado: **delega** en la skill `building-a-slice` (o en el agente `build-orchestrator` para épicas multicapa) y conduce el pipeline `DoR → change → TDD → smoke → api/data → DoD → PR + archive` respetando el **orden estricto de gates**. Exige `scaffold.confirmed: true` (y `design_source.confirmed: true` si hay UI) como precondición; el arnés **lo exige pero no lo genera**. **Un solo slice activo** (secuencial). No dispara los reviewers pesados (eso es del Release Gate). |
+
+### `/build:release` — entrada del outer loop (Release Gate)
+
+| Slash command | Propósito |
+|---|---|
+| `/build:release` | Punto de entrada del **outer loop**: corre el **Release Gate UNA vez** sobre el diff acumulado de una release (no por épica). Dispara **en paralelo** los 5 reviewers pesados (`security` → `security-reviewer`, `smell` → `simple-design-reviewer`, `ux` → `ux-krug-reviewer`, `coherence` → `coherence-three-way`, `stack_arch` → `stack-guardian`) y luego el gate `integration` **secuencial** con dependencias reales (no stubs). Escribe `releases[].gates.{security,smell,ux,coherence,stack_arch}` y `status` vía la skill `releasing-a-version` (única escritora de `releases[]`). Lo **sugiere** el hook `release-gate-nudge.sh` al cerrar sesión. No duplica el inner loop (ni TDD ni gates por slice). |
+
+### `/build:work` — router classify-and-act
+
+| Slash command | Propósito |
+|---|---|
+| `/build:work` | **Router puro** (classify-and-act): clasifica el trabajo entrante y **delega** en la skill correcta — `building-a-micro-change` (mantenimiento), `building-a-slice` (épica / capacidad nueva) o `releasing-a-version` (Release Gate) — codificando el *decision gate* del micro-change y el default del Release Gate. Es **ruteo, no política**: no ejecuta el pipeline, no escribe `build-state.json` ni crea ramas. Aplica los **límites duros** del micro-change (dependencia nueva, endpoint/API nuevo, o tocar lógica de dominio / invariantes de datos → escala a épica) y, **ante la duda, SIEMPRE épica**. |
+
 ### `/build:onboard` — parametrización del dominio
 
 | Slash command | Propósito |
@@ -81,6 +99,18 @@ El canal CLI namespacea por subcarpeta: `.claude/commands/opsx/` → `/opsx:*` y
 |---|---|
 | `/build:reflect` | Tras archivar un slice, detecta **convenciones aprendidas** / errores recurrentes (a partir del change, el diff y la sesión) y **propone** viñetas para el bloque `trycore-build-learnings` de `CLAUDE.md`; las aplica **solo tras tu aprobación** y estampa el slice como reflexionado (`reflected: true`). Lo **sugiere** el hook `reflect-nudge.sh` al cerrar sesión, pero puedes invocarlo cuando quieras. No toca el bloque de dominio ni sus `{{placeholders}}` (eso es de `/build:onboard`). |
 
+### `/build:resume` — rehidratación sin pérdida de contexto
+
+| Slash command | Propósito |
+|---|---|
+| `/build:resume` | Reconstruye el contexto de construcción **desde disco**, no desde la conversación: corre `reconcile-build-state.py`, lee `active_slice` (`gates`, `wiring_checklist`, `progress_log`, `session_continuity`, `parallel_front`) y determina la siguiente acción por prioridad (`resume_hint` → item `failing` de wiring → `sub_slices` pendiente → fase del pipeline). Es el punto de entrada tras un handoff automático del hook `context-monitor.sh` o tras cualquier reinicio de contexto. |
+
+### `/build:front` — front paralelo inter-épica
+
+| Slash command | Propósito |
+|---|---|
+| `/build:front` | Abre y coordina un **front paralelo** de épicas NO fundacionales y disjuntas en archivos, cada una en su propio worktree/rama/PR. Delega en la skill `managing-parallel-front`: verifica precondiciones (scaffold confirmado, sin épica foundational abierta), selecciona el conjunto disjunto (`scripts/lib/front-plan.py`) y mergea en orden con re-smoke. Úsalo solo con ≥2 épicas no fundacionales disjuntas listas; para una sola épica, usa `/build:slice`. |
+
 ---
 
 ## 3. Caveat de canales (CLI vs. plugin)
@@ -90,7 +120,7 @@ El arnés se distribuye por **dos canales** que coexisten, pero **namespacean di
 | Aspecto | Canal **CLI** (canónico) | Canal **Plugin** nativo |
 |---|---|---|
 | Instalación | `npm i -g @trycore/spec-build-harness` → `trycore-build init` | `/plugin marketplace add <repo-github>` → `/plugin install trycore-spec-build-harness@trycore-build` |
-| Namespace de comandos | Por subcarpeta: `/opsx:*`, `/build:onboard` y `/build:reflect` | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
+| Namespace de comandos | Por subcarpeta: `/opsx:*` y los 7 `/build:*` (`onboard`, `reflect`, `slice`, `release`, `work`, `resume`, `front`) | Por nombre del plugin: `/trycore-spec-build-harness:*` (por diseño de Claude Code) |
 | Referencia a agentes | Por su nombre (p. ej. `build-orchestrator`) | Bajo el nombre del plugin |
 | Cross-references internas | ✔ Escritas para este canal (skills invocan `/opsx:*`, agentes por nombre) | Pueden no resolver según están escritas |
 | Recomendación | **Usar este canal para operar un proyecto** | Conveniencia a nivel usuario |

package/docs/customization/mcp-extensions.md

@@ -78,14 +78,15 @@ cada uno por el que aplique a **tu** stack declarado en el PRD; ninguno es oblig
 | `ux` (release) | `ux-krug-reviewer` | Navegador headless con auditoría tipo Lighthouse | Accesibilidad / Best-Practices y snapshots de la UI ensamblada de la release. | Revisión heurística Krug sobre el código + capturas manuales. |
 | `api` (inner) | `api-contract-tester` | **Newman corre por CLI, no es MCP** | Contratos de endpoints sobre una colección de pruebas. | Es la vía por defecto: se ejecuta vía Bash, sin MCP. |
 | `data` (inner) | `data-consistency-checker` | MCP de base de datos (solo si tu slice usa esa BD) | Consultas de lectura / describe de tablas para validar invariantes y consistencia. | Validación por tests contra un almacén embebido o cliente del stack. |
-| `coherence` / diseño | `coherence-three-way`, `simple-design-reviewer`, `stack-guardian` | **LSP del lenguaje** (p. ej. LSP de TypeScript en stacks TS tipados) | Seguir definiciones/referencias con precisión de compilador: trazar símbolo→test, detectar duplicación y uso real. Mejor ROI que `grep` en código tipado. | Navegación con `grep`/`glob` + lectura dirigida. |
+| `coherence` / `smell` / `stack_arch` (release) | `coherence-three-way`, `simple-design-reviewer`, `stack-guardian` | **LSP del lenguaje** (p. ej. LSP de TypeScript en stacks TS tipados) | Seguir definiciones/referencias con precisión de compilador: trazar símbolo→test, detectar duplicación y uso real. Mejor ROI que `grep` en código tipado. | Navegación con `grep`/`glob` + lectura dirigida. |
 | perf (opcional, **fuera del DoD**) | — | MCP de pruebas de carga (p. ej. un MCP de k6) | Carga/latencia si una HU de la épica lo exige explícitamente. | Omitir; no es un gate del arnés. |
 
 Notas de coherencia con el arnés:
 
-- En el **inner loop** los gates pesados (`security`, `smell`, `ux`, coherencia triple completa,
-  arquitectura, integración con deps reales) **no** se cierran por épica: corren **una vez por
-  release** en `releasing-a-version`. Habilita los MCP de esas fases pensando en el outer loop.
+- En el **inner loop** los gates pesados (`security`, `smell`, `ux`, `coherence` —coherencia triple
+  completa, distinta del `coherence_link` barato del inner—, `stack_arch` —arquitectura— e
+  `integration` con deps reales) **no** se cierran por épica: corren **una vez por release** en
+  `releasing-a-version`. Habilita los MCP de esas fases pensando en el outer loop.
 - El gate `api` usa **Newman por CLI**: es un ejemplo de que la herramienta de un gate **no tiene por
   qué ser un MCP**. Lo importante es la evidencia (los contratos responden), no el canal.
 - **Excepción única — `fidelity` en slices con UI.** Es el **único** gate donde un MCP es **requerido**,

package/docs/decisiones/2026-07-03-gsd-vs-openspec-fork-vs-rama.md

@@ -0,0 +1,157 @@
+# Evaluación: ¿reemplazar el harness OpenSpec por GSD? ¿fork o rama?
+
+- **Fecha:** 2026-07-03
+- **Estado:** Decidido — ver **Actualización post-análisis de código** al final. Diseño en [`docs/superpowers/specs/2026-07-03-harness-context-engine-design.md`](../superpowers/specs/2026-07-03-harness-context-engine-design.md)
+- **Autor:** Jhonata.segura (asistido)
+- **Repo evaluado:** `@trycore/spec-build-harness` v0.7.1
+- **Candidato:** `open-gsd/gsd-core` (GSD — "Git. Ship. Done"), MIT
+- **Insumo relacionado:** `gsd-template.md` (PRD "Orquestador Semántico Determinista", análisis de 4 agentes)
+
+---
+
+## 1. Pregunta a resolver
+
+Dos preguntas, una depende de la otra:
+
+1. **¿Debemos reemplazar OpenSpec por GSD** como base del harness de construcción, motivado por que "los foros dicen que GSD es más nativo con Claude Code, usa mejor el contexto y es más eficiente"?
+2. **Si avanzamos, ¿fork de gsd-core o rama en este repo?**
+
+Este documento responde ambas con evidencia y deja una recomendación. No modifica arquitectura.
+
+---
+
+## 2. Punto de partida: qué es hoy el harness y qué papel juega OpenSpec
+
+`@trycore/spec-build-harness` no *es* OpenSpec: es un **arnés propio** que orquesta a Claude Code con arquitectura de **dos loops** (slice por épica con TDD + gates → release gate), **12 agentes de build** (coherence three-way, security-reviewer, wiring-adversarial-verifier, ux-krug, dor-dod-gatekeeper, stack-guardian, etc.), estado compartido, hooks y una **metodología documentada en español** (`METODOLOGIA.md`, `GOVERNANCE.md`). Es el compañero de `@trycore/spec-product-flow` (Discovery → Construcción).
+
+OpenSpec (`@fission-ai/openspec`) es **una pieza dentro**, no el todo. Aporta el **modelo de spec basado en cambios**: `changes/` (propuesta) → implementación → `archive` hacia `specs/`. Se expresa como:
+
+- **55 referencias** en el repo (`grep -ril openspec`).
+- Namespace `/opsx:*` — 10 comandos (`new`, `apply`, `archive`, `bulk-archive`, `continue`, `explore`, `ff`, `onboard`, `sync`, `verify`).
+- 8 skills `openspec-*` (todas con `Requires openspec CLI` y licencia MIT — son wrappers del CLI de OpenSpec).
+- Dependencia externa: `npm install -g @fission-ai/openspec`.
+
+**Conclusión de esta sección:** "reemplazar OpenSpec" ≠ "reemplazar el harness". OpenSpec es la **capa de gobernanza de spec** (propuesta de cambio → archivo). El valor diferencial de Trycore (dos loops, gates, agentes, metodología, coexistencia con product-flow) **no vive en OpenSpec**.
+
+---
+
+## 3. Qué es realmente GSD (verificado, no de oídas)
+
+GSD es un framework de **context-engineering + spec-driven** mucho **más grande y ambicioso** que nuestra capa OpenSpec:
+
+- **Loop de 5 fases:** Discuss → Plan → Execute → Verify → Ship, repetido por *milestones*.
+- **~55+ comandos** (`/gsd-*`): incluye planificación con convergencia cross-AI, ejecución en *waves* paralelas, *workstreams*, knowledge graph (`/gsd-graphify`), memory palace temporal (`/gsd-mempalace-*`), auditorías de milestone/UAT/seguridad, code-review, audit-fix, spikes, forensics, etc.
+- **Estado en archivos planos:** `STATE.md`, `CONTEXT.md`, `ROADMAP.md`, `.planning/` — con comandos de validación (`state validate`, `roadmap validate`).
+- **Multi-runtime:** Claude Code, Codex, Gemini CLI, Kimi, Copilot, Cursor, Windsurf… vía instalador (`npx @opengsd/gsd-core@latest`). **No se copian `agents/`/`commands/` a mano.**
+- **Licencia MIT.** Fork legalmente trivial.
+- **Escala/actividad:** ~48K estrellas; v1.34.2 el 2026-04-06; **1.693 commits en 47 releases** desde dic-2025. Es un proyecto que se mueve rápido.
+
+### 3.1 ¿Son ciertas las afirmaciones de los foros?
+
+| Afirmación de foro | Veredicto | Matiz |
+|---|---|---|
+| "Más nativo con Claude Code" | **Parcialmente cierto** | Nació Claude-Code-first y es lo más maduro ahí, pero hoy se posiciona **multi-runtime**. "Nativo" real = su patrón de *fresh-context subagents* encaja muy bien con el modelo de subagentes de Claude Code. |
+| "Usa mejor el contexto" | **Cierto en el patrón** | El núcleo — ejecutar research/plan/execute en **subagentes de contexto fresco (~200k)** manteniendo la sesión principal ligera — es una respuesta genuinamente buena al *context rot*. Es la idea que la comunidad realmente elogia. |
+| "Más eficiente" | **No demostrado como número** | El README no publica benchmarks de tokens. La eficiencia proviene del patrón, no de una métrica auditada. Ojo: fresh-context tiene su propio **"impuesto de arranque"** (reinyección) — es exactamente lo que critica tu PRD §2.2. |
+
+**Lo importante:** lo que los foros elogian de GSD es un **patrón de ejecución** (subagentes de contexto fresco + estado externalizado), *no* un motor de spec que haga a OpenSpec obsoleto. Ese patrón es **adoptable sin reemplazar OpenSpec**.
+
+---
+
+## 4. Solapamiento, brechas y choque de modelos
+
+| Capacidad | Harness actual | GSD | Lectura |
+|---|---|---|---|
+| Gobernanza de spec | OpenSpec `changes/ → specs/` (brownfield, delta por cambio) | `ROADMAP.md` + fases/milestones (`.planning/`) | **Modelos distintos.** OpenSpec = delta de cambio archivable; GSD = roadmap de fases. Migrar es re-conceptualizar, no un swap. |
+| Ejecución / context rot | Slices + orquestador propio | **Waves paralelas en subagentes frescos** | GSD es **más fuerte** aquí. Es la joya a mirar. |
+| Gates de calidad | 12 agentes Trycore + release gate | code-review, audit-fix, secure-phase, verify | **Solapan.** Adoptar GSD nos obliga a re-hospedar o botar nuestros agentes. |
+| TDD / Gitflow / release gate | **Explícito** (nuestro valor) | Ship/PR + verify; TDD/gitflow **no formalizados** | Perdemos rigor si migramos crudo. |
+| Metodología en español + product-flow | **Sí** (diferencial Trycore) | No existe | Se re-implementa igual, migremos o no. |
+| Extensibilidad | Nuestra, total | Vía instalador/capabilities/overlays; **no copiar archivos a mano** | Forkear = pelear contra su modelo de instalación. |
+
+**Choque clave:** OpenSpec gobierna **el cambio** (delta propuesto y archivado); GSD gobierna **el plan** (fases de un roadmap). No son intercambiables 1:1; "reemplazar" implicaría rehacer cómo pensamos la unidad de trabajo.
+
+---
+
+## 5. Riesgos de adoptar/forkear GSD
+
+1. **Gobernanza inestable (riesgo alto).** El proyecto original tuvo un incidente (meme-coin) y **el autor original ya no participa**. Hoy conviven `open-gsd/gsd-core`, `open-gsd/get-shit-done-redux` y otros forks. Atarnos a un upstream en plena reorganización de gobernanza es riesgo de cadena de suministro y de dirección.
+2. **Velocidad de upstream (riesgo de mantenimiento).** 47 releases / 1.693 commits en ~4 meses. Un **fork** nos obliga a un *sync* costoso y perpetuo, o a divergir y perder el motivo de forkear.
+3. **Superficie enorme.** ~55 comandos y subsistemas (knowledge graph, memory palace, cross-AI). Adoptarlo entero es asumir complejidad que **no pediste** (YAGNI) y que solapa lo nuestro.
+4. **Modelo de instalación cerrado.** "No copies `agents/`/`commands/`" → un fork/patch integrado con nuestro CLI (`trycore-build init`) va a contracorriente de su diseño.
+5. **Contradice tu propio PRD.** El consenso de los 4 agentes en `gsd-template.md` es explícito: *"El Orquestador… no reemplaza a GSD ni a Claude Code — se inserta entre ellos"*. Es decir, tu análisis ya descartó "reemplazar".
+
+---
+
+## 6. Opciones de estrategia de repositorio
+
+### Opción A — Rama en este repo (evolución in-place) ✅ recomendada para empezar
+Crear `spike/gsd-eval` (y luego `feature/…`) **en este mismo repo**. Adoptar **el patrón que sí vale de GSD** (ejecución en subagentes de contexto fresco / waves) dentro de nuestra arquitectura, **conservando** OpenSpec como gobernanza de cambio y nuestros gates.
+- **Pro:** control total, mantiene identidad Trycore y coexistencia con product-flow; reversible; publicable como v0.8/v1.0; cero riesgo de gobernanza externa.
+- **Contra:** reimplementamos el patrón (no heredamos el código de GSD).
+
+### Opción B — Fork de `gsd-core`
+Partir de su base MIT y montar gates/metodología encima.
+- **Pro:** heredamos madurez (waves, graph, memory palace).
+- **Contra:** **el más caro y arriesgado** — sync perpetuo con upstream velocísimo, gobernanza inestable, superficie que no queremos, choque con nuestro CLI e instalación. Botamos o duplicamos nuestros 12 agentes y los dos loops.
+
+### Opción C — GSD como dependencia (wrap, igual que hoy con OpenSpec)
+No forkear: invocar el CLI de GSD desde nuestro harness, como orquestamos OpenSpec hoy.
+- **Pro:** bajo mantenimiento; nos beneficiamos de upstream sin cargarlo.
+- **Contra:** dependemos de su CLI/estado; dos modelos de spec conviviendo (OpenSpec + GSD) puede confundir; seguimos expuestos a su gobernanza en runtime.
+
+### Opción D — Greenfield: el "Orquestador" del PRD (visión larga)
+Construir el plano de control determinista + datos semánticos (MCP a nivel símbolo + estado tipado) que describe `gsd-template.md`. GSD queda como capa metodológica, no como reemplazo.
+- **Pro:** ataca la métrica real (tokens/rework/first-time-pass) según tu propio análisis.
+- **Contra:** mayor esfuerzo; fuera del alcance de "una versión nueva del harness" ahora.
+
+---
+
+## 7. Recomendación
+
+**No forkear gsd-core y no arrancar OpenSpec a ciegas.** En concreto:
+
+1. **Reencuadrar el objetivo.** Lo que la comunidad elogia de GSD y lo que tú buscas ("mejor uso de contexto, más eficiente") es un **patrón de ejecución** (subagentes de contexto fresco + estado externalizado), **no** un motor de spec que reemplace a OpenSpec. Perseguir ese patrón ≠ reemplazar OpenSpec.
+2. **Opción A (rama en este repo) para un spike acotado.** Validar el patrón de contexto fresco dentro de nuestra arquitectura, midiendo contra un baseline. Reversible y publicable.
+3. **Descartar la Opción B (fork)** salvo que decidamos, con datos del spike, comprometer GSD como *motor* y aceptar el costo de mantenimiento/gobernanza. Hoy el riesgo de gobernanza (autor fuera, forks múltiples) lo hace desaconsejable.
+4. **Mantener la Opción D (orquestador del PRD) como norte de largo plazo**, no como esta release. Coincide con el consenso de tu propio PRD: *insertar entre*, no reemplazar.
+
+En una frase: **la próxima versión del harness debería robarle a GSD la *idea* (ejecución en contexto fresco), no el *repositorio*.**
+
+---
+
+## 8. Spike de validación propuesto (si se aprueba avanzar)
+
+Rama `spike/gsd-eval`, alcance de días, criterios de éxito medibles:
+
+1. **Baseline.** Correr un slice representativo con el harness actual; registrar tokens de entrada, nº de llamadas a herramientas, rework y first-time-pass.
+2. **Variante A (patrón GSD, sin GSD).** Reimplementar la ejecución del slice en **subagentes de contexto fresco** (ya tenemos `Agent`/waves nativos de Claude Code) manteniendo OpenSpec + gates. Medir lo mismo.
+3. **Variante B (GSD como dependencia, opcional).** Instalar `gsd-core` en un proyecto de prueba y comparar su Execute-phase contra nuestro slice, para calibrar cuánto valor real añade su motor vs. reimplementarlo.
+4. **Decisión.** Con las tres mediciones, elegir entre: (a) adoptar solo el patrón (Opción A), (b) wrap de GSD (Opción C), o (c) invertir en el orquestador (Opción D). Sólo entonces se justificaría —o no— un fork.
+
+**Criterio de descarte de fork:** si el spike no muestra ≥30% de mejora de tokens/rework atribuible al *código* de GSD (y no solo al patrón), no forkear.
+
+---
+
+## 9. Fuentes
+
+- [open-gsd/gsd-core (GitHub)](https://github.com/open-gsd/gsd-core)
+- [GSD hits 48K stars — Augment Code](https://www.augmentcode.com/learn/gsd-stars-spec-driven-dev-claude-code)
+- [The Anatomy of Claude Code Workflows (GSD deep dive) — codecentric](https://www.codecentric.de/en/knowledge-hub/blog/the-anatomy-of-claude-code-workflows-turning-slash-commands-into-an-ai-development-system)
+- [Superpowers, GSD, and gstack: what each constrains — Ewan Mak (Medium)](https://medium.com/@tentenco/superpowers-gsd-and-gstack-what-each-claude-code-framework-actually-constrains-12a1560960ad)
+- [GSD vs Spec Kit vs OpenSpec vs Taskmaster — Rick Hightower (Medium)](https://medium.com/@richardhightower/agentic-coding-gsd-vs-spec-kit-vs-openspec-vs-taskmaster-ai-where-sdd-tools-diverge-0414dcb97e46)
+- Interno: `gsd-template.md` (PRD "Orquestador Semántico Determinista"), `README.md`, `METODOLOGIA.md`, skills `openspec-*`.
+
+---
+
+## 10. Actualización post-análisis de código (2026-07-03)
+
+Se clonó `gsd-core` y se leyó su ingeniería real (5 exploradores, evidencia `file:line`). Confirma y **cierra** las decisiones:
+
+1. **NO forkear — confirmado con datos.** `git log --since=30d` = **861 commits**; sin campo `exports` (no es librería); artefactos compilados en `.gitignore`; instalador monolítico de **11.740 líneas**; 3 sistemas de toggles entrelazados. No hay costura estable para depender. Los patrones valiosos son portables (MIT) sin el motor.
+2. **El dolor real (reinicio manual) NO lo resuelve GSD tampoco:** GSD deja el `/clear` manual (filosofía #884). Su valor = **aviso temprano (hook a 35%/25%) + handoff sin pérdida**. Eso es lo adoptable, y es pequeño/portable.
+3. **Nuestro estado tipado ≥ el de GSD** (JSON schema vs Markdown+regex); GSD compensa con **derivación desde disco** — esa *idea* sí vale robarla.
+4. **Worktrees:** GSD paraleliza solo lo disjunto en archivos + seguro en el DAG, con serializador de solapes. Adoptamos el patrón a nivel **inter-épica** (no fundacionales, disjuntas).
+5. Lo *hypeado* (memory-palace, knowledge graph) es lo *menos* propio de GSD (MCP/Python externos). Descartado por ahora.
+
+**Veredicto final:** rama en este repo (`feature/gsd-context-engine`), robar patrones de contexto + estado-en-disco + worktrees inter-épica. Diseño detallado en el spec enlazado arriba.

package/docs/flujo-harness-funcional.md

@@ -0,0 +1,42 @@
+# Cómo trabaja el arnés — flujo funcional
+
+Vista única y sencilla del flujo de trabajo, para explicar a los devs **qué pasa con cada cambio**.
+(Versión detallada/técnica en [flujo-harness.md](./flujo-harness.md).)
+
+```mermaid
+flowchart TD
+    A([Llega un trabajo]) --> B{"¿Qué tipo de cambio es?"}
+
+    B -->|"Arreglo pequeño<br/>(typo, copy, config)"| C["Carril rápido:<br/>rama → cambio → PR"]
+    C --> Z([PR listo para mergear])
+
+    B -->|"Funcionalidad nueva<br/>(una épica)"| D{"¿Está lista para construir?<br/>historias claras, criterios definidos,<br/>base ya construida"}
+    D -->|"No"| E["Vuelve a discovery<br/>a completar la historia"]
+    D -->|"Sí"| F["Construir con pruebas<br/>(escribo el test, luego el código)"]
+
+    F --> G{"¿La app funciona<br/>de punta a punta?"}
+    G -->|"No"| F
+    G -->|"Sí"| H["Revisión final del cambio<br/>+ pantallas iguales al diseño (si hay UI)"]
+
+    H --> I["Abrir PR y dejar todo enlazado<br/>(historia ↔ cambio ↔ código)"]
+    I --> J{"¿Esta épica cierra<br/>una entrega/release?"}
+
+    J -->|"No, sigue otra épica"| A
+    J -->|"Sí"| K["Revisión profunda de la entrega:<br/>seguridad · calidad · UX ·<br/>coherencia · arquitectura"]
+
+    K --> L{"¿Todo el journey completo<br/>funciona con dependencias reales?"}
+    L -->|"No, hay hallazgos"| M["Corregir como un cambio normal"]
+    M --> K
+    L -->|"Sí"| N([Release lista ✅])
+
+    classDef q fill:#fff3cd,stroke:#d39e00,color:#000;
+    classDef ok fill:#d4edda,stroke:#155724,color:#000;
+    class B,D,G,J,L q;
+    class N,Z ok;
+```
+
+## La idea en una frase
+
+- **Cambios chicos** van por un carril rápido.
+- **Cada funcionalidad nueva** se construye completa, con pruebas, verificando que la app **funcione de punta a punta** antes de cerrarla.
+- **De vez en cuando** (al cerrar una entrega) se hace una **revisión profunda** de todo lo acumulado antes de liberar.

package/docs/flujo-harness.md

@@ -0,0 +1,192 @@
+# Flujo del arnés de construcción — `@trycore/spec-build-harness`
+
+Diagrama de flujo end-to-end del harness, modelado al estilo BPMN:
+
+- **◆ XOR** (rombo) = compuerta **exclusiva** (un solo camino).
+- **⬡ AND** (hexágono) = compuerta **paralela** (fork: todos los caminos; join: convergencia/barrera).
+- **▭ Tarea** con su **gate** entre `[ ]`.
+- Aristas punteadas `-.->` = retroceso (gate monótono que vuelve a `false`).
+
+Fuente de verdad: [METODOLOGIA.md](../METODOLOGIA.md). Si algo contradice ese documento, gana la metodología.
+
+---
+
+## 1. Vista global (router → inner loop → outer loop)
+
+```mermaid
+flowchart TD
+    START([Trabajo entrante]) --> PRE{{"⬡ Preflight<br/>¿instalado?"}}
+    PRE -->|NOT_INSTALLED| INIT[trycore-build init] --> ROUTER
+    PRE -->|ok| ROUTER
+
+    ROUTER[/"/build:work — Router (classify-and-act)<br/>solo ruteo: no toca estado ni ramas"/]
+    ROUTER --> GW1{"◆ XOR — Decision gate<br/>¿qué carril?"}
+
+    %% --- Rama 1: micro-change ---
+    GW1 -->|"mantenimiento<br/>sin capacidad nueva"| HARD{"◆ XOR — ¿cruza límite duro?<br/>dep nueva / API nueva / dominio·datos"}
+    HARD -->|"sí → escala"| INNER
+    HARD -->|no| MICRO["building-a-micro-change<br/>fix/* | chore/* → cambio → PR<br/>(sin abrir active_slice)"]
+    MICRO --> ENDM([PR mergeado])
+
+    %% --- Rama 2: épica / producto nuevo ---
+    GW1 -->|"capacidad nueva<br/>o límite duro"| INNER[["INNER LOOP<br/>building-a-slice<br/>(ver §2)"]]
+
+    %% --- Rama 3: release gate ---
+    GW1 -->|"cierra línea de release<br/>o ≥2 épicas archivadas"| OUTER[["OUTER LOOP<br/>releasing-a-version<br/>(ver §3)"]]
+
+    INNER --> DEC{"◆ XOR — fase 8<br/>¿correr Release Gate ahora?<br/>(default computado, decide humano)"}
+    DEC -->|"sí (cierra release<br/>o nudge ≥2)"| OUTER
+    DEC -->|no| NEXT([Siguiente épica]) -.-> INNER
+
+    OUTER --> OUTGW{"◆ XOR — ¿todos los gates ✓?"}
+    OUTGW -->|"passed"| REL([Release lista])
+    OUTGW -->|"failed (hallazgos)"| FIX["Fix como slice normal<br/>(building-a-slice)"] -.->|re-corre| OUTER
+
+    classDef xor fill:#fff3cd,stroke:#d39e00,color:#000;
+    classDef andg fill:#d1ecf1,stroke:#0c5460,color:#000;
+    classDef loop fill:#e2e3f3,stroke:#383d6b,color:#000;
+    class GW1,HARD,DEC,OUTGW xor;
+    class PRE andg;
+    class INNER,OUTER loop;
+```
+
+---
+
+## 2. Inner loop — `building-a-slice` (pipeline secuencial por épica)
+
+Precondición dura: **scaffold confirmado** (`scaffold.confirmed`) antes de abrir cualquier slice.
+Secuencial (un `active_slice` a la vez), divulgación progresiva, ningún gate se salta.
+
+```mermaid
+flowchart TD
+    S0([Épica EP-XXX entrante]) --> SCAF{"◆ XOR — gate proyecto<br/>scaffold.confirmed?"}
+    SCAF -->|"false"| STOPS["STOP — exige scaffold runnable<br/>(scaffold-guard.sh)"]
+    SCAF -->|"true"| F1
+
+    %% Fase 1: DoR
+    F1["F1 · dor — Definition of Ready<br/>delega: dor-dod-gatekeeper"]
+    F1 --> DORGW{"◆ XOR — ¿DoR ✓?<br/>épica+HU, AC G/W/T, INVEST,<br/>cimiento, tamaño, stack, fixtures"}
+    DORGW -->|"✗"| BACKDISC["Vuelve a discovery<br/>(/trycore:*) — no se abre slice"]
+    DORGW -->|"✓ [gate: dor]"| SIZE{"◆ XOR — gate tamaño<br/>>3 HU ó ≥3 capas?"}
+
+    SIZE -->|"sí"| SUB["Descompone en sub_slices[]<br/>se construyen de a uno<br/>(journey_smoke verde entre cada uno)"]
+    SIZE -->|"no (atómica)"| F2
+    SUB --> F2
+
+    %% Fase 2: change
+    F2["F2 · change — opsx:new + ## Trazabilidad<br/>delega: change-epic-coherence"]
+    F2 --> F2GW{"◆ XOR — ¿enlace change↔épica ✓?"}
+    F2GW -->|"✓ [gate: coherence_link]"| F3
+    F2GW -.->|"✗ retroceso"| F2
+
+    %% Fase 3: TDD
+    F3["F3 · red→green→refactor<br/>TDD por cada escenario AC de cada HU<br/>delega: superpowers:test-driven-development"]
+    F3 --> F3GW{"◆ XOR — ¿suite verde?"}
+    F3GW -.->|"✗ retroceso"| F3
+    F3GW -->|"✓ [gate: tdd]"| F4
+
+    %% Fase 4: smoke + fidelity (UI)
+    F4["F4 · smoke — journey-hasta-aquí end-to-end<br/>runner determinista fuera-de-chat (sesión virgen)"]
+    F4 --> UIGW{"◆ XOR — ¿la épica toca UI?"}
+    UIGW -->|"no"| F4OUT["fidelity = null"]
+    UIGW -->|"sí"| FID["Verificación visual real (MCP chrome-devtools)<br/>screenshot app vs prototipo<br/>delega: ux-fidelity-reviewer"]
+    FID --> FIDGW{"◆ XOR — ¿fidelidad ESTRICTA ✓?<br/>INCONCLUSO = false"}
+    FIDGW -.->|"✗ → false"| FID
+    FIDGW -->|"✓ [gate: fidelity]"| F4OUT
+    F4OUT -->|"[gate: journey_smoke]"| F5FORK
+
+    %% Fase 5: api / data en paralelo (condicional/null)
+    F5FORK{{"⬡ AND — fork (fase api/data)"}}
+    F5FORK --> APIB["api — contratos endpoints<br/>Newman 100% (delega: api-contract-tester)<br/>null si no hay endpoints"]
+    F5FORK --> DATAB["data — invariantes de datos<br/>(delega: data-consistency-checker)<br/>N/A si no toca datos"]
+    APIB --> F5JOIN
+    DATAB --> F5JOIN
+    F5JOIN{{"⬡ AND — join (convergencia)<br/>[gates: api, data]"}}
+
+    %% Fase 6: dod — adversarial THEN dod
+    F5JOIN --> WIRE["F6a · Verificación ADVERSARIAL independiente<br/>(subagente contexto virgen)<br/>asume slice incompleto e intenta refutarlo<br/>delega: wiring-adversarial-verifier"]
+    WIRE --> WIREGW{"◆ XOR — ¿wiring_checklist[] sin items failing?"}
+    WIREGW -.->|"✗ huecos (stub/ruta/AC sin test)"| F3
+    WIREGW -->|"✓ [gate: wiring_verified]"| DOD["F6b · DoD reducido<br/>delega: dor-dod-gatekeeper<br/>(piso declarativo, no el arreglo)"]
+    DOD --> DODGW{"◆ XOR — ¿DoD ✓?<br/>tdd·journey_smoke·coherence_link·<br/>data·api·fidelity·wiring_verified·hooks"}
+    DODGW -.->|"✗ retroceso"| F3
+    DODGW -->|"✓ [gate: dod]"| F7
+
+    %% Fase 7: PR + archive
+    F7["F7 · pr — abrir PR + archivar change EN EL MISMO PR<br/>opsx:archive + opsx:sync<br/>back-reference en épica y HU"]
+    F7 --> ARCH["active_slice → history[] (phase: archived)<br/>active_slice = null"]
+    ARCH --> F8([F8 · decisión Release Gate → §1])
+
+    classDef xor fill:#fff3cd,stroke:#d39e00,color:#000;
+    classDef andg fill:#d1ecf1,stroke:#0c5460,color:#000;
+    classDef stop fill:#f8d7da,stroke:#842029,color:#000;
+    class SCAF,DORGW,SIZE,F2GW,F3GW,UIGW,FIDGW,WIREGW,DODGW xor;
+    class F5FORK,F5JOIN andg;
+    class STOPS,BACKDISC stop;
+```
+
+> **Disciplina de horizonte largo:** cada iteración nace headless / contexto virgen y reconstruye estado
+> desde disco (`build-state.json` + git + logs). `wiring_checklist[]` (1 item por escenario AC y por punto
+> de integración entre capas) nace `failing` y solo pasa a `passing` **tras prueba real ejecutada**.
+> Mientras quede un item `failing`, el cableado NO está hecho.
+
+---
+
+## 3. Outer loop — `releasing-a-version` (Release Gate)
+
+Alcance = **diff acumulado** de todas las épicas de la release (merge anterior → `main`).
+Los reviewers se disparan **en paralelo** y devuelven síntesis (protegen el contexto).
+
+```mermaid
+flowchart TD
+    R0([Línea de release identificada]) --> R1["Crear/actualizar releases[] (status: pending)<br/>cruzar con docs/02-user-story-map/"]
+    R1 --> FORK{{"⬡ AND — fork (reviewers en paralelo<br/>sobre el diff acumulado)"}}
+
+    FORK --> SEC["security — sin CRÍTICO/ALTO;<br/>claves server-side; PII no cruda;<br/>salida IA = input no confiable<br/>(security-reviewer)"]
+    FORK --> SME["smell — 4 reglas de Beck<br/>+ code smells sin bloqueantes<br/>(simple-design-reviewer)"]
+    FORK --> UX["ux — Krug + Lighthouse<br/>(null si sin UI)<br/>(ux-krug-reviewer)"]
+    FORK --> COH["coherence — trazabilidad triple<br/>AC↔change↔código, sin huérfanos<br/>(coherence-three-way · opus)"]
+    FORK --> ARCH["stack_arch — arquitectura PRD:<br/>capa IA en frontera server-side;<br/>decisión determinista sin IA<br/>(stack-guardian)"]
+
+    SEC --> JOIN
+    SME --> JOIN
+    UX --> JOIN
+    COH --> JOIN
+    ARCH --> JOIN
+
+    JOIN{{"⬡ AND — join (convergencia de reviewers)"}}
+    JOIN --> INTEG["integration — journey COMPLETO end-to-end<br/>con DEPENDENCIAS REALES (no stubs)<br/>skill verify/run + MCP chrome-devtools"]
+
+    INTEG --> RGW{"◆ XOR — ¿todos los gates ✓ (o null N/A)?"}
+    RGW -->|"✓"| PASS["status: passed<br/>escribir gates + updated_by: releasing-a-version"]
+    RGW -->|"✗ hallazgos bloqueantes"| FAIL["status: failed"]
+    PASS --> RELOK([Release ✅])
+    FAIL --> FIXLOOP["Humano corrige como slice normal<br/>(building-a-slice)"]
+    FIXLOOP -.->|"re-corre Release Gate"| R1
+
+    classDef xor fill:#fff3cd,stroke:#d39e00,color:#000;
+    classDef andg fill:#d1ecf1,stroke:#0c5460,color:#000;
+    classDef gate fill:#d4edda,stroke:#155724,color:#000;
+    class RGW xor;
+    class FORK,JOIN andg;
+    class INTEG gate;
+```
+
+> **`integration` es el gate no negociable.** Sin journey completo con dependencias reales **no hay release**.
+> No se acepta con todo stubbeado.
+
+---
+
+## 4. Leyenda de loops y gates
+
+| | Inner loop | Outer loop |
+|---|---|---|
+| Skill | `building-a-slice` | `releasing-a-version` |
+| Unidad | una épica `EP-XXX` | una línea de release |
+| Cadencia | muchas (1 por épica) | pocas (1 por release) |
+| Costo | barato (≤ ~20 min/épica) | pesado (subagentes profundos) |
+| Gates | dor · coherence_link · tdd · journey_smoke · fidelity · api · data · wiring_verified · dod | security · smell · ux · coherence · stack_arch · integration |
+| Estado | `active_slice` + `history[]` | `releases[]` |
+
+**Regla de no duplicación:** cada gate vive en exactamente un loop. El outer no hace TDD ni gates por slice;
+el inner no dispara reviewers pesados.

package/docs/getting-started.md

@@ -16,9 +16,10 @@ trycore-build doctor     # verifica requisitos y hooks
 ```text
 # 3) En Claude Code (lo corre Claude, no la terminal)
 /build:onboard               # parametriza el dominio: lee tu PRD, resuelve los {{placeholders}}
-skill building-a-slice       # construye una épica: DoR → change → TDD → smoke → DoD → PR
+/build:slice                 # construye una épica: DoR → change → TDD → smoke → DoD → PR
 /build:reflect               # (opcional) captura aprendizajes del slice recién archivado
-skill releasing-a-version    # al cerrar una línea de release del Story Map
+/build:release               # al cerrar una línea de release del Story Map
+# /build:work                # (opcional) router: clasifica la tarea y la enruta (micro-change/slice/release)
 ```
 
 Eso es el ciclo completo. Lo de abajo explica cada paso.
@@ -47,7 +48,7 @@ npm i -g @fission-ai/openspec @trycore/spec-build-harness
 
 ## 2 · `trycore-build init` (terminal)
 
-Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **12 agentes**, **12 skills**, **10 comandos `/opsx:*`** + `/build:onboard` + `/build:reflect`, **9 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
+Desde la raíz de tu proyecto. Es **idempotente** (re-correrlo es seguro) y siembra: **12 agentes**, **13 skills** (`building-a-slice`, `building-a-micro-change`, `releasing-a-version` + 10 `openspec-*`), **10 comandos `/opsx:*`** + **5 comandos `/build:*`** (`onboard`, `slice`, `release`, `reflect`, `work`), **10 hooks**, el estado vacío `.claude/state/build-state.json` (gitignored, nunca se sobreescribe) y el bloque `<!-- BEGIN trycore-build-harness -->` en tu `CLAUDE.md` con `{{placeholders}}` sin resolver.
 
 ```bash
 trycore-build init
@@ -81,7 +82,7 @@ Si un punto no aplica, se registra como "no aplica" (no se deja como `{{...}}`).
 
 ## 4 · Construir un slice (Claude Code)
 
-**Un slice = una épica `EP-XXX` = un OpenSpec change = una rama = un PR.** Las HU de la épica son su alcance interno. Invoca `skill building-a-slice` (o pídelo en lenguaje natural: *"construye EP-001"*). Pipeline del **inner loop**:
+**Un slice = una épica `EP-XXX` = un OpenSpec change = una rama = un PR.** Las HU de la épica son su alcance interno. Invoca `/build:slice` —la entrada del **inner loop**— (o pídelo en lenguaje natural: *"construye EP-001"*; o deja que `/build:work` clasifique y enrute la tarea). Pipeline del **inner loop**:
 
 ```
 DoR → change (+ trazabilidad) → TDD → journey-smoke (+ fidelidad si hay UI) → api/data → DoD reducido → PR + archive
@@ -99,7 +100,7 @@ Lo que importa:
 
 ## 5 · Release Gate (Claude Code, por release)
 
-Al archivar una épica, la skill te **pregunta** si correr el Release Gate (default computado desde las líneas de release del Story Map). `skill releasing-a-version` corre las **revisiones pesadas una sola vez** sobre el diff acumulado:
+Al archivar una épica, la skill te **pregunta** si correr el Release Gate (default computado desde las líneas de release del Story Map; lo respalda el hook `release-gate-nudge`, que solo **sugiere** y nunca ejecuta trabajo pesado). `/build:release` (outer loop) corre las **revisiones pesadas una sola vez** sobre el diff acumulado:
 
 | Gate | Delega en |
 |---|---|