@trycore/spec-build-harness 0.1.0

package/METODOLOGIA.md

@@ -0,0 +1,360 @@
+# METODOLOGIA.md — Arnés de construcción Trycore (`@trycore/spec-build-harness`)
+
+> **Fuente de verdad metodológica.** Este documento es la metodología canónica del arnés de
+> construcción. Si una skill, un agente, una reference o un hook contradice lo escrito aquí, **gana
+> la metodología**. (Es la misma regla dura que fija el bloque `<!-- BEGIN trycore-build-harness -->`
+> del `CLAUDE.md` del consumidor.)
+>
+> El arnés es **agnóstico al proyecto**: el core no asume dominio, stack ni framework. Lo que es
+> específico del consumidor (stack, PII, capa de servicios externos, capa de decisión determinista,
+> secretos, decisiones de alto impacto) se inyecta vía `/build:onboard` y `stack-allowlist.json`. El
+> ejemplo de referencia vive aparte en `docs/examples/reference/` y no forma parte del core.
+
+---
+
+## 0. Qué es y dónde encaja
+
+`@trycore/spec-build-harness` (CLI `trycore-build`, plugin `trycore-spec-build-harness`, marketplace
+`trycore-build`) es el **compañero de construcción** de `@trycore/spec-product-flow` (la vertical de
+discovery). El flujo completo de extremo a extremo es:
+
+```
+DISCOVERY  (@trycore/spec-product-flow)        CONSTRUCCIÓN  (@trycore/spec-build-harness)
+PRD → User Story Map → Backlog → Historias  →  por épica: DoR → change → TDD → smoke → api/data → DoD → PR
+      (AC G/W/T) → Priorización → Flows           por release: Release Gate (seguridad/diseño/UX/coherencia/arquitectura/integración)
+```
+
+Ambos paquetes **coexisten en el mismo `.claude/` sin colisión**, con namespaces disjuntos:
+
+| Eje | Discovery (`spec-product-flow`) | Construcción (`spec-build-harness`) |
+|---|---|---|
+| Comandos | `trycore/` (`/trycore:*`) | `opsx/` + `build/` (`/opsx:*`, `/build:onboard`) |
+| Sentinela de versión | `.trycore-version` | `.build-harness-version` |
+| Bloque en `CLAUDE.md` | `<!-- BEGIN trycore-vertical -->` | `<!-- BEGIN trycore-build-harness -->` |
+
+El puente entre los dos mundos es la **trazabilidad**: la construcción consume los artefactos de
+`docs/` (épicas, HU con AC en Given/When/Then, líneas de release del Story Map) y los enlaza a los
+OpenSpec changes en `openspec/`.
+
+---
+
+## 1. El modelo de dos loops (y por qué)
+
+El arnés organiza el trabajo en **dos loops anidados** con costos deliberadamente distintos:
+
+| | **Inner loop** | **Outer loop** |
+|---|---|---|
+| Skill | `building-a-slice` | `releasing-a-version` |
+| Unidad | una **épica** (`EP-XXX`) | una **línea de release** del Story Map |
+| Cadencia | muchas veces (una por épica) | pocas veces (una por release) |
+| Costo | barato y rápido (objetivo ≤ ~20 min/épica) | pesado (subagentes profundos sobre el diff acumulado) |
+| Qué hace | DoR → change → TDD → smoke → api/data → DoD → PR+archive | gates de seguridad, diseño, UX, coherencia triple, arquitectura, integración |
+| Estado | `active_slice` + `history[]` | `releases[]` |
+
+**Por qué partirlo así.** Las revisiones profundas (seguridad, diseño/smell, UX/Krug, coherencia
+triple AC↔change↔código, arquitectura, integración con dependencias reales) son caras en contexto y
+en tiempo. Si se corrieran **por épica**, su costo sería `O(épicas)` y el inner loop dejaría de ser
+rápido. Al moverlas al **Release Gate** —una sola pasada sobre el diff acumulado de todas las épicas
+de la release— el costo de los agentes pesados pasa a `O(releases)`. El inner loop queda libre para
+ser veloz: solo cierra gates baratos y mantiene el producto caminando.
+
+**Regla de no duplicación.** El outer loop **no** repite el inner loop: no hace TDD ni cierra gates
+por slice. Y el inner loop **no** dispara reviewers pesados. Cada gate vive en exactamente un loop.
+
+---
+
+## 2. La regla del "esqueleto que camina"
+
+El arnés prohíbe construir capas horizontales aisladas que "se juntan al final" (el anti-patrón que
+hace que todos los gates por-slice estén en verde y el producto aun así no funcione de punta a
+punta). En su lugar:
+
+- El **primer slice** de una release construye el **journey completo más delgado posible**: de la
+  primera a la última actividad del *backbone* del Story Map, aunque cada paso sea un *stub*.
+- **Cada épica posterior engorda un paso** de ese esqueleto y debe mantener el `journey_smoke`
+  **verde**. El esqueleto que camina nunca deja de caminar.
+- El gate `journey_smoke` (inner loop) recorre el *backbone-hasta-aquí* end-to-end en cada épica; el
+  gate `integration` (outer loop) recorre el journey completo de la release con **dependencias
+  reales**, no stubs.
+
+Consecuencia operativa: **la unidad de construcción es la épica, no la HU suelta**. Un slice = una
+épica = un OpenSpec change = una rama = un PR. Las HU que cubre la épica son su *alcance interno* y
+se listan en `active_slice.hus[]`. Construir por HU individual es sobre-ingeniería.
+
+---
+
+## 3. Pipeline del inner loop, fase por fase (con sus gates)
+
+Lo conduce la skill `building-a-slice` (opcionalmente vía el agente `build-orchestrator`). Es
+**secuencial** (un slice activo a la vez), con **divulgación progresiva** (cada fase carga solo su
+reference). Un gate no se salta.
+
+| # | Fase (`phase`) | Acción | Delega en | Gate que cierra | Reference |
+|---|---|---|---|---|---|
+| 1 | `dor` | Validar Definition of Ready de la épica y sus HU | `dor-dod-gatekeeper` | `dor` | `dor.md` |
+| 2 | `change` | `opsx:new` + bloque `## Trazabilidad`; validar enlace (barato) | `opsx:new`, `change-epic-coherence` | `coherence_link` | `link-change-epic.md` |
+| 3 | `red`→`green`→`refactor` | TDD por cada escenario AC (G/W/T) de cada HU | `superpowers:test-driven-development` | `tdd` | — |
+| 4 | `smoke` | Recorrer el journey-hasta-aquí end-to-end | skill `verify`/`run` (+ MCP chrome-devtools) | `journey_smoke` | `mcp-map.md` |
+| 5 | `api`/`data` | Contratos de endpoints + invariantes de datos (si aplican) | `api-contract-tester`, `data-consistency-checker` | `api`, `data` | `newman-tests.md`, `data-consistency.md` |
+| 6 | `dod` | Definition of Done reducido (lee los gates del estado) | `dor-dod-gatekeeper` | `dod` | `dod.md` |
+| 7 | `pr` | Abrir PR + **archivar el change en el mismo PR** | `opsx:archive`, `opsx:sync` | — | `gitflow.md` |
+| 8 | (decisión) | ¿Correr el Release Gate ahora? (default computado, decide el humano) | usuario | — | §4 |
+
+### 3.1 Definition of Ready (gate `dor`)
+
+Una épica **no entra a construcción** hasta cumplir todo (lo valida `dor-dod-gatekeeper`):
+
+- Épica `EP-XXX` existe en `docs/03-backlog/epicas.md` con trazabilidad a objetivos del PRD.
+- La épica tiene ≥1 HU; todas las que entran se listan en `hus[]`.
+- Frontmatter completo en cada `docs/04-historias/HU-XXX.md` (`id, titulo, epica, prioridad,
+  complejidad, estado`) con `estado: lista`.
+- AC en Given/When/Then por HU: 3–5 escenarios con happy + error + edge.
+- Cada HU pasa los 6 criterios **INVEST**.
+- Dependencias resueltas (las épicas/HU de las que depende están en `history[]` o no bloquean).
+- Cabe en el stack del PRD (no requiere tecnología fuera de `stack-allowlist.json`).
+- Datos de prueba disponibles o identificables (fixtures sintéticos del dominio).
+
+Si todo ✓ → se abre `active_slice` con `phase: dor`, `gates.dor: true` y el resto en `false`
+(`ux`/`api` en `null` si la épica no toca UI/endpoints). Si algo ✗ → no se abre el slice; se reporta
+qué falta y se vuelve a discovery.
+
+### 3.2 Definition of Done reducido (gate `dod`)
+
+El slice **no se archiva ni se mergea** hasta cumplir todo. Es el DoD **reducido** del inner loop;
+las revisiones pesadas **no** se piden aquí (van al Release Gate):
+
+- `tdd` — cada escenario AC de cada HU tiene test; ciclo red→green→refactor completo; suite verde.
+- `journey_smoke` — la app arranca y el backbone-hasta-aquí se recorre end-to-end sin romperse.
+- `coherence_link` — `change-epic-coherence` confirma el enlace change↔épica (chequeo **barato**;
+  la trazabilidad triple completa va al Release Gate).
+- `data` — invariantes de datos validadas (si el slice toca datos).
+- `api` — Newman 100% verde (o `null` si el slice no tiene endpoints).
+- OpenSpec: todas las tasks `[x]`; el archive del change va **en el mismo PR**.
+- Back-reference del change añadida en la épica y en cada HU de `hus[]`.
+- Hooks verdes (automáticos, **no** son gates de agente): `lint-typecheck.sh`, `stack-guard.sh`,
+  `gitflow-guard.sh`.
+
+Lo que **no** se valida aquí y sube al Release Gate: `security`, `smell`, `ux`, `coherence`
+(triple completa) y `stack_arch` (arquitectura). Las **dependencias** sí se vigilan por slice, pero
+vía el hook `stack-guard.sh` en tiempo real, no vía subagente.
+
+### 3.3 Gates por slice y su naturaleza N/A
+
+- `ux` y `api` admiten `null` cuando el slice no tiene UI o endpoints. `null` ≠ abierto: **no
+  bloquea** el DoD.
+- En `harness_phase: authoring` (sin `package.json`) se puede hacer `dor` + `change`, pero los gates
+  de código (`tdd`, `journey_smoke`, `api`, `data`) **no se cierran** hasta scaffoldear.
+
+---
+
+## 4. Decisión de Release Gate (fase 8 del inner loop)
+
+Tras archivar la épica, `building-a-slice` **pregunta al humano** si correr el Release Gate, con un
+**default calculado** desde las líneas de release del Story Map (`docs/02-user-story-map/`):
+
+- Si la épica **cierra una línea de release** (todas las épicas de esa línea ya están en
+  `history[]`) → default **"Sí, correr `releasing-a-version` ahora"**.
+- Si no la cierra → default **"Continuar a la siguiente épica"**. *Nudge*: si hay **≥ 2 épicas**
+  archivadas desde el último entry de `releases[]`, se recomienda correrlo igual.
+
+El humano siempre puede sobreescribir el default. Si acepta, se invoca `releasing-a-version` sobre la
+release correspondiente.
+
+---
+
+## 5. Los gates del Release Gate (outer loop)
+
+Lo conduce la skill `releasing-a-version`. Una **release** es una línea de release del Story Map
+(p.ej. `R1-mvp` = un conjunto de épicas). El alcance es el **diff acumulado** de todas sus épicas:
+desde el merge anterior a la primera épica de la release hasta `main`. Los subagentes se disparan **en
+paralelo** y devuelven síntesis (protegen el contexto). Resultado en `releases[]`.
+
+| Gate | Qué se exige | Delega en |
+|---|---|---|
+| `security` | Sin hallazgos CRÍTICO/ALTO; claves de servicios externos solo server-side; PII/datos regulados (según el PRD) no persistidos crudos; salida de servicios externos/IA tratada como input no confiable y validada contra esquema | `security-reviewer` |
+| `smell` | 4 reglas de Beck + code smells sin bloqueantes sobre el diff acumulado | `simple-design-reviewer` |
+| `ux` | Krug + Lighthouse sobre la UI ensamblada de la release (o `null` si sin UI) | `ux-krug-reviewer` |
+| `coherence` | Trazabilidad triple AC↔change↔código de **todas** las HU de **todas** las épicas de la release, sin huérfanos | `coherence-three-way` (opus) |
+| `stack_arch` | Arquitectura del PRD: capa de servicios externos/IA en la frontera declarada server-side (no decide); capa de decisión determinista del dominio sin IA; sin claves en cliente | `stack-guardian` |
+| `integration` | El **journey completo** de la release se recorre end-to-end con **dependencias reales** del proyecto, **no stubs** | skill `verify`/`run` (+ MCP chrome-devtools) |
+
+**Protocolo de la release:**
+
+1. Identificar la release y sus épicas (cruzar con `docs/02-user-story-map/`).
+2. Crear/actualizar la entrada en `releases[]` con `status: pending`.
+3. Disparar los subagentes en paralelo sobre el diff acumulado.
+4. Correr el gate `integration` con deps reales.
+5. Todos los gates ✓ (o `null` cuando N/A) → `status: passed`, escribir `gates` y `updated_by:
+   releasing-a-version`. Algo ✗ → `status: failed` con los hallazgos bloqueantes; el humano los
+   corrige como un slice normal (fix en `building-a-slice`) y se **re-corre** el Release Gate.
+
+> **`integration` es el gate no negociable del arnés.** Es el que faltaba en la era previa: todos los
+> gates por-slice estaban en verde y aun así el producto "no caminaba" de punta a punta. Sin
+> `integration` con dependencias reales **no hay release**. No se acepta con todo stubbeado.
+
+---
+
+## 6. Contrato de trazabilidad change ↔ épica
+
+Cada OpenSpec change corresponde a **exactamente una épica** (la unidad de construcción) y declara
+las HU que cubre. El enlace vive en el **cuerpo markdown** del `openspec/changes/<name>/proposal.md`,
+en una sección al final:
+
+```markdown
+## Trazabilidad
+- Épica: EP-003
+- Historias: HU-010, HU-011, HU-012
+- Discovery: docs/03-backlog/epicas.md#ep-003
+```
+
+**Regla dura: el enlace va en el cuerpo markdown, NUNCA en frontmatter YAML.** OpenSpec valida la
+estructura del change con `openspec validate --strict` y un frontmatter ajeno la rompe. El bloque
+markdown es seguro.
+
+Reglas del contrato (las verifica `change-epic-coherence`, gate `coherence_link`):
+
+1. **Una épica por change.** Un change no cruza épicas; si necesitas dos épicas, son dos slices.
+2. **Las HU de esa épica** que entran en alcance: la lista de `Historias:` debe **igualar** a
+   `hus[]`; cada `HU-XXX` debe existir y su `epica:` coincidir con la EP.
+3. **Nombre del change** en kebab-case basado en la épica (p.ej. `ep-003-pricing-engine`).
+4. **Back-reference bidireccional**: al archivar, se añade `> OpenSpec change: ep-003-pricing-engine`
+   en la épica (`docs/03-backlog/epicas.md`) y en cada HU de `hus[]`. Esto cierra el enlace
+   Trycore↔OpenSpec en ambos sentidos.
+
+Validación: `openspec validate "<name>" --type change --strict --json`.
+
+---
+
+## 7. Protocolo de `build-state.json`
+
+`.claude/state/build-state.json` es la **única fuente de verdad** y el medio por el que los agentes
+se sincronizan en modo **secuencial**. Cada gate del pipeline transiciona el estado; el siguiente
+agente lo lee antes de actuar. Estructura: `version`, `harness_phase`, `active_slice`, `history[]`,
+`releases[]` (esquema en `state/build-state.schema.json`, draft 2020-12).
+
+**Reglas del protocolo:**
+
+1. **Leer antes de actuar.** Todo agente lee `active_slice` y `gates` antes de trabajar. Si
+   `active_slice` es `null`, no hay slice → **solo `dor-dod-gatekeeper`** puede abrir uno.
+2. **Una transición = una escritura.** Quien completa una fase actualiza `phase`, su gate,
+   `updated_at` (ISO 8601 UTC) y `updated_by` (su nombre). No toca otros campos. Patrón
+   lee-modifica-escribe con `python3`.
+3. **Gates monótonos hacia adelante.** Un gate solo pasa de `false`→`true` cuando su agente lo
+   aprueba. Si una revisión posterior falla, **se vuelve a `false` y `phase` retrocede** (el retroceso
+   está permitido y es la forma de manejar fallos tardíos).
+4. **`null` para N/A.** `ux`/`api` son `null` cuando el slice no tiene UI/endpoints; no cuentan como
+   abiertos para el DoD.
+5. **Archivar.** Al completar `opsx:archive`, mover `active_slice` a `history[]` con
+   `phase: "archived"` y dejar `active_slice: null`.
+6. **Validar tras escribir** contra el schema (con `jsonschema`/`python3`).
+
+**Quién escribe qué:**
+
+| Campo / gate | Lo escribe | Cadencia |
+|---|---|---|
+| `active_slice` (alta) · `gates.dor` · `gates.dod` | `dor-dod-gatekeeper` | slice |
+| `gates.coherence_link` | `change-epic-coherence` | slice |
+| `gates.tdd` | flujo `superpowers:test-driven-development` (vía `build-orchestrator`) | slice |
+| `gates.journey_smoke` · `phase` (transiciones) · `history[]` | `build-orchestrator` | slice |
+| `gates.api` | `api-contract-tester` | slice |
+| `gates.data` | `data-consistency-checker` | slice |
+| `releases[]` (security, smell, ux, coherence, stack_arch, integration, status) | `releasing-a-version` (delega en los reviewers) | release |
+| `harness_phase` | `load-build-state.sh` (SessionStart) | — |
+
+**Régimen de fases (`harness_phase`):** arranca en `authoring`; `load-build-state.sh` lo cambia a
+`active` al detectar `package.json` en la raíz. En `authoring`, los hooks de código están armados
+pero inertes (`[ -f package.json ] || exit 0`) y empiezan a disparar solos al aparecer el scaffold,
+sin intervención manual.
+
+**Ciclo de fases del inner loop:**
+
+```
+dor → change → red → green → refactor → smoke → api → data → dod → pr → archived
+```
+
+**Versionado del estado.** `build-state.json` se siembra **vacío** y **nunca se sobreescribe** (está
+en `.gitignore`: es working state). El **schema** y el **README** sí se versionan. El
+`stack-allowlist.json` es artefacto del consumidor (lo siembra el CLI, lo puebla `/build:onboard`).
+`uninstall` preserva `state/` y `config/`.
+
+---
+
+## 8. GitHub Flow estricto
+
+Modelo de ramas **GitHub Flow** (no GitFlow clásico): **`main` siempre desplegable**, **sin
+`develop` ni `release/*`**. Una sola línea estable + ramas cortas + integración solo por Pull
+Request con checks verdes. Lo hace cumplir de forma determinista el hook `gitflow-guard.sh`.
+
+Ciclo por slice:
+
+```bash
+git switch main && git pull --ff-only
+git switch -c feature/<slug>          # rama tipada: feature/* | fix/* | chore/*
+# ... TDD + gates (estado en build-state.json) ...
+git add -A && git commit -m "feat: <mensaje>"   # commit en la rama (nunca en main)
+git push -u origin feature/<slug>               # push de la rama (nunca a main)
+gh pr create --base main --head feature/<slug> --fill   # integración por PR
+```
+
+Convenciones:
+
+- **Una rama por épica** (= un slice): `feature/ep-003-pricing-engine`. Tipos: `feature/*` (valor
+  nuevo), `fix/*` (corrección), `chore/*` (infra/docs).
+- **Conventional Commits** (`feat:`, `fix:`, `test:`, `refactor:`, `chore:`, `docs:`).
+- **PR**: enlaza la épica, sus HU (`hus[]`) y el OpenSpec change; checks (lint, types, tests, Newman)
+  en verde antes de merge; squash recomendado; el archive del change va **en el mismo PR**.
+
+`gitflow-guard.sh` bloquea: `git commit` en `main`/`master`, `git commit` desde rama no tipada, y
+`git push` apuntando a `main`/`master`.
+
+---
+
+## 9. Integración con OpenSpec y con la discovery
+
+### 9.1 OpenSpec — el motor de cambios
+
+El arnés **no reimplementa** la gestión de specs: la delega en **OpenSpec** (requisito duro;
+instalar con `npm i -g @fission-ai/openspec`). Los comandos `/opsx:*` y las skills `openspec-*` son
+adaptadores delgados sobre OpenSpec; la skill `building-a-slice` los **secuencia**, no los duplica.
+
+- Fase `change` del inner loop → `opsx:new` crea el change y se le añade el bloque `## Trazabilidad`.
+- Fase `pr` → `opsx:archive` archiva el change (en el mismo PR) y `opsx:sync` reconcilia los specs.
+- Validación con `openspec validate --strict`; por eso la trazabilidad va en markdown, no en
+  frontmatter (§6).
+
+### 9.2 Discovery — el contrato con `@trycore/spec-product-flow`
+
+La construcción **consume** los artefactos de discovery y los trata como entrada de solo lectura:
+
+| Artefacto de discovery | Uso en construcción |
+|---|---|
+| `docs/03-backlog/epicas.md` (`EP-XXX`) | Unidad de construcción del slice; trazabilidad del change |
+| `docs/04-historias/HU-XXX.md` (AC en G/W/T, INVEST, `estado: lista`) | Alcance interno del change (`hus[]`); base de los tests TDD |
+| `docs/02-user-story-map/` (backbone + líneas de release) | Esqueleto que camina (§2); definición de release y default del Release Gate (§4) |
+| PRD §7 / `stack-allowlist.json#source` | Stack permitido; arquitectura auditada en `stack_arch` |
+
+El arnés **no escribe** en `docs/`; cuando una HU no cumple DoR, devuelve el trabajo a discovery
+(`/trycore:*`). El único contacto de escritura cruzada es la **back-reference** del change en la
+épica y las HU al archivar (§6.4).
+
+---
+
+## 10. Reglas duras (resumen)
+
+1. La **épica** es la unidad de construcción: un slice = una épica = un change = una rama = un PR.
+   Las HU son alcance interno (`hus[]`).
+2. El **esqueleto que camina** nunca deja de caminar: nada de capas horizontales que se juntan al
+   final; `journey_smoke` verde en cada épica.
+3. **Dos loops sin duplicación**: gates baratos por épica (inner), gates pesados una vez por release
+   (outer). Ningún gate vive en ambos.
+4. La trazabilidad change↔épica va en el **cuerpo markdown** de `proposal.md` (`## Trazabilidad`),
+   **nunca** en frontmatter YAML.
+5. `build-state.json`: leer antes de actuar; **una transición = una escritura**; gates **monótonos**
+   (retroceso solo ante fallo); solo `dor-dod-gatekeeper` abre un slice cuando no hay activo.
+6. **GitHub Flow estricto**: `main` desplegable, integración solo por PR; `gitflow-guard.sh` bloquea
+   commits/push directos.
+7. **`integration` con dependencias reales es obligatorio** para cerrar una release; sin él no hay
+   release.
+8. El core es **agnóstico**: lo específico del dominio se inyecta vía `/build:onboard` y
+   `stack-allowlist.json`; el ejemplo de referencia vive en `docs/examples/reference/`.
+9. Si una skill, agente o reference contradice este documento, **gana la metodología**.

package/README.md

@@ -0,0 +1,130 @@
+# @trycore/spec-build-harness
+
+Arnés agéntico de **construcción** de Trycore para Claude Code: el compañero de `@trycore/spec-product-flow`. Donde la vertical de producto cierra el discovery (`PRD → backlog priorizado`), este arnés toma ese backlog y lo lleva a código mergeado con calidad gobernada. La narrativa completa es **Discovery → Construcción**:
+
+```
+Discovery (@trycore/spec-product-flow)      Construcción (este arnés)
+PRD → User Story Map → Backlog        →      slice por épica (TDD + gates) → release gate
+```
+
+Ambos paquetes coexisten en el mismo `.claude/` sin colisión: namespaces disjuntos (`trycore/` vs `build/` + `opsx/`), archivos de versión separados (`.trycore-version` vs `.build-harness-version`) y bloques distintos en `CLAUDE.md` (`<!-- BEGIN trycore-vertical -->` vs `<!-- BEGIN trycore-build-harness -->`). El núcleo es **100% agnóstico al proyecto**.
+
+## Cómo se usa (rápido)
+
+```bash
+# 0) Requisito: OpenSpec (lo usan los comandos /opsx:* y las skills openspec-*)
+npm install -g @fission-ai/openspec
+
+# 1) Instalar el CLI global (una vez por máquina)
+npm install -g @trycore/spec-build-harness
+
+# 2) Instalar el arnés en un proyecto cliente (idempotente; siembra estado y allowlist)
+cd /ruta/al/proyecto-cliente
+trycore-build init
+
+# 3) Abrir Claude Code y parametrizar (lee el PRD, resuelve los {{placeholders}})
+/build:onboard
+```
+
+`trycore-build init` captura el **stack mecánico** (lenguaje/deps, package manager, runtime, ruta del PRD) por flags o por prompt TTY, y siembra los archivos. Luego `/build:onboard` —ejecutado por Claude— lee el PRD, pregunta por PII / capa-IA / capa-determinista / secretos / decisiones de alto impacto vía `AskUserQuestion`, resuelve los `{{placeholders}}` del bloque `CLAUDE.md` y escribe la auto-memory. Es un onboarding en **dos capas** porque un binario Node no puede escribir la auto-memory de Claude.
+
+### Alternativa: instalar como plugin nativo de Claude Code (sin npm)
+
+```bash
+/plugin marketplace add trycore-co/trycore-spec-build-harness
+/plugin install trycore-spec-build-harness@trycore-build
+```
+
+> **Caveat de canales (importante).** El canal **npm CLI es el canónico**: instala los comandos en `.claude/commands/{opsx,build}/`, que namespacean por subcarpeta → `/opsx:*` y `/build:onboard`, y referencia los agentes por su nombre. El canal **plugin** namespacea los componentes bajo el **nombre del plugin** (→ `/trycore-spec-build-harness:*`) por diseño de Claude Code; se ofrece como conveniencia a nivel usuario, pero las cross-references internas (skills que invocan `/opsx:*`, agentes por nombre) están escritas para el canal CLI. **Para operar dentro de un proyecto, usa el CLI.** Los hooks son una única cadena autorresolutiva idéntica en ambos canales (`"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/<script>.sh"`); si se instalan los dos, Claude Code deduplica y el hook dispara una sola vez.
+
+### Comandos del CLI `trycore-build`
+
+| Comando | Para qué |
+|---|---|
+| `trycore-build init` | Instala el arnés en el proyecto (idempotente). Siembra estado, schema, allowlist y bloque `CLAUDE.md`. |
+| `trycore-build update` | Refresca assets y schema tras `npm update -g`. No pisa estado ni allowlist. |
+| `trycore-build status` | Muestra el estado de la instalación y la fase activa del arnés. |
+| `trycore-build uninstall` | Quita el arnés. **Preserva** `.claude/state/` y `.claude/config/`. |
+| `trycore-build doctor` | Verifica requisitos externos (`openspec`/`python3`/`git`), hooks ejecutables y canales. |
+
+Flags de `init`: `--copy` (copiar en vez de symlinkear), `--yes` (no interactivo), `--skip-doctor`, `--force-init`, `--stack <deps>`, `--pkg-manager <pm>`, `--runtime <semver>`, `--prd-path <path>`.
+
+## Los dos loops
+
+El arnés modela la construcción como dos ciclos anidados, cada uno con su skill maestra:
+
+### Inner loop — `building-a-slice` (una vez por épica `EP-XXX`)
+
+```
+DoR → OpenSpec change → TDD → journey-smoke → api/data → DoD → PR + archive
+```
+
+Por cada épica del backlog: se valida el **Definition of Ready**, se abre un *change* en OpenSpec, se desarrolla con **TDD**, se corre el smoke del journey, se verifican contratos de API y consistencia de datos, se valida el **Definition of Done** y se cierra con PR + archivado del change.
+
+### Outer loop — `releasing-a-version` (una vez por release)
+
+Gate de release que corre **una sola vez por versión** sobre el conjunto de slices acumulados: seguridad, diseño, UX, coherencia triple (spec ↔ código ↔ tests), arquitectura e integración.
+
+## Slash commands
+
+| Command | Propósito |
+|---|---|
+| `/build:onboard` | Onboarding capa 2: lee el PRD, pregunta por PII/IA/determinismo/secretos, resuelve `{{placeholders}}` y escribe la auto-memory. |
+| `/opsx:explore` | Explora el dominio / specs antes de abrir un change. |
+| `/opsx:new` | Crea un nuevo OpenSpec change. |
+| `/opsx:continue` | Retoma un change en curso. |
+| `/opsx:apply` | Aplica los cambios propuestos del change. |
+| `/opsx:verify` | Verifica el change contra sus specs. |
+| `/opsx:archive` | Archiva un change completado. |
+| `/opsx:bulk-archive` | Archiva varios changes en lote. |
+| `/opsx:ff` | Fast-forward de un change. |
+| `/opsx:onboard` | Onboarding de OpenSpec en el repo. |
+| `/opsx:sync` | Sincroniza specs ↔ estado del proyecto. |
+
+## Arquitectura
+
+```
+trycore-spec-build-harness/
+├── METODOLOGIA.md             ← fuente de verdad metodológica (gana ante cualquier skill)
+├── GOVERNANCE.md              ← gobernanza del paquete + cadencia de auditoría
+├── .claude-plugin/            ← manifiesto del plugin nativo (canal de conveniencia)
+├── agents/build/              ← 10 agentes revisores (segunda opinión, contexto limpio)
+├── commands/
+│   ├── opsx/                  ← 10 comandos /opsx:* (ciclo OpenSpec)
+│   └── build/                 ← /build:onboard
+├── skills/                    ← 12 skills (building-a-slice, releasing-a-version, 10 openspec-*)
+├── hooks/build/               ← 6 hooks bash (gate-check, gitflow-guard, stack-guard, …)
+├── state/                     ← máquina de estado: build-state.json + schema + README
+├── config/                    ← stack-allowlist.template.json (artefacto del consumidor)
+├── src/ + dist/               ← CLI trycore-build (init/update/status/uninstall/doctor)
+├── scripts/                   ← installer + guardias (check-version-sync/agnostic/state-clean)
+└── docs/examples/reference/   ← ejemplo de referencia (fuera del core, excluido de check-agnostic)
+```
+
+Los **10 agentes** en `agents/build/` son: `build-orchestrator`, `dor-dod-gatekeeper`, `security-reviewer`, `simple-design-reviewer`, `ux-krug-reviewer`, `coherence-three-way` (opus), `stack-guardian`, `api-contract-tester`, `data-consistency-checker` y `change-epic-coherence`.
+
+**Estado.** `state/build-state.json` se siembra **vacío** y nunca se sobreescribe (va al `.gitignore`); el schema y el README sí se versionan. `config/stack-allowlist.json` es artefacto del consumidor: lo siembra el CLI y lo puebla `/build:onboard`. `uninstall` preserva `state/` y `config/`.
+
+## Requisitos
+
+`init` y `doctor` **fallan** si falta cualquiera de estos:
+
+| Requisito | Por qué | Instalación |
+|---|---|---|
+| **openspec** | Lo usan los comandos `/opsx:*` y las skills `openspec-*`. | `npm i -g @fission-ai/openspec` |
+| **python3** | Los hooks parsean JSON con `python3`. | Según el sistema operativo |
+| **git** | Flujo de ramas / PRs / archivado de changes. | Según el sistema operativo |
+
+Runtime Node `>=18.0.0`.
+
+## Agnóstico al proyecto
+
+El core no menciona ningún dominio de cliente. Toda parametrización entra por el bloque `CLAUDE.md` (`<!-- BEGIN trycore-build-harness -->`), la auto-memory que escribe `/build:onboard` y las preguntas en runtime. El **ejemplo de referencia** vive en `docs/examples/reference/` —fuera del core y **excluido de `check-agnostic`**— para que nunca contamine los assets distribuibles. Las guardias de `prepublishOnly` lo blindan: `check-version-sync` + `check-agnostic` + `check-state-clean`.
+
+## Roadmap
+
+- ✅ **v0.1.0 (actual)** — arnés de dos loops (`building-a-slice` + `releasing-a-version`), 10 agentes, comandos `/opsx:*` + `/build:onboard`, 12 skills, 6 hooks, máquina de estado `build-state.json`, allowlist de stack, CLI `trycore-build` (init/update/status/uninstall/doctor) y plugin nativo. Compañero de `@trycore/spec-product-flow`.
+
+## Licencia
+
+Uso interno de Trycore.

package/VERSION

@@ -0,0 +1 @@
+0.1.0

package/agents/build/api-contract-tester.md

@@ -0,0 +1,32 @@
+---
+name: api-contract-tester
+description: Ejecuta pruebas de contrato de los endpoints (Route Handlers de Next.js) con Newman sobre una colección Postman. Aplica solo a slices con endpoints. Úsalo en la fase api. Requiere código + servidor levantable.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+Eres el **tester de contratos de API** del arnés de construcción. Si el slice no expone endpoints, devuelve
+"N/A" → `gates.api: null`. Referencia: `.claude/skills/building-a-slice/references/newman-tests.md`.
+
+## Procedimiento
+1. **Identifica endpoints** del slice (Route Handlers en `app/api/**/route.ts` o Server Actions).
+2. **Localiza/crea la colección** Postman en `tests/postman/<slice>.postman_collection.json` y su
+   `environment.json`. Cada request debe cubrir, alineado con los AC (G/W/T) de las HU de la épica:
+   - **happy path** (entrada válida → status + shape esperados),
+   - **error** (entrada inválida → 4xx con mensaje útil, sin filtrar datos sensibles / PII regulados que el consumidor declara en el bloque de dominio de su CLAUDE.md o su PRD),
+   - **edge** (límites: input faltante, respuesta parcial de un servicio externo, etc.).
+   Las aserciones validan **status, esquema (zod/JSON) y campos clave**, no solo el código HTTP.
+3. **Levanta la app** si hace falta (`npm run dev`/`build && start`) en background y espera readiness.
+4. **Ejecuta Newman**:
+   ```bash
+   npx --yes newman run tests/postman/<slice>.postman_collection.json \
+     -e tests/postman/environment.json --reporters cli,json \
+     --reporter-json-export .claude/state/newman-<slice>.json
+   ```
+5. **Interpreta**: reporta requests/assertions pasados/fallidos y la causa de cada fallo.
+
+## Salida
+- Resumen de ejecución (totales, fallos con request + aserción).
+- Veredicto: 100% verde → propón `gates.api: true`; fallos → `false` con el detalle; sin endpoints → `null`.
+
+No edites código de producto: si faltan casos, propón los requests a añadir. Devuelve al `build-orchestrator`.

package/agents/build/build-orchestrator.md

@@ -0,0 +1,50 @@
+---
+name: build-orchestrator
+description: Orquesta el pipeline secuencial de construcción de un slice (épica EP-XXX) del arnés de construcción. Lee y escribe .claude/state/build-state.json, transiciona las fases y delega en los gates, en los skills opsx:* (motor de changes) y en superpowers:test-driven-development (motor TDD). Úsalo cuando el usuario quiera construir, continuar o avanzar una épica EP-XXX (las HU que cubre son su alcance interno).
+tools: Read, Grep, Glob, Bash, Edit, Write
+model: sonnet
+---
+
+Eres el **orquestador de construcción** del arnés de construcción. NO escribes código de producto tú mismo:
+diriges el pipeline secuencial, mantienes el estado y delegas en agentes y skills.
+
+## Fuente de verdad
+`.claude/state/build-state.json` (valida contra `.claude/state/build-state.schema.json`).
+Protocolo en `.claude/state/README.md`. **Sólo un slice activo a la vez** (modelo secuencial).
+La **unidad de construcción es la épica** (`active_slice.epica`); las HU que cubre el change van en
+`active_slice.hus[]`. Un slice = una épica = un change = una rama = un PR.
+
+## Pipeline — inner loop (orden estricto, rápido, SIN subagentes pesados)
+```
+1. dor      → delega en dor-dod-gatekeeper (abre el slice si pasa)
+2. change   → opsx:new + bloque ## Trazabilidad → delega en change-epic-coherence (gate coherence_link, barato)
+3. tdd      → conduce superpowers:test-driven-development (red→green→refactor)
+4. smoke    → recorre el journey-hasta-aquí end-to-end con la skill verify/run (+ chrome-devtools) → gate journey_smoke
+5. api/data → api-contract-tester (si hay endpoints) · data-consistency-checker (si toca datos)
+6. dod      → dor-dod-gatekeeper (cierre por slice, DoD reducido)
+7. pr       → abre PR y archiva el change EN EL MISMO PR (opsx:archive + opsx:sync); back-ref en épica y HU
+8. release? → tras archivar, devuelve a la skill building-a-slice para preguntar el Release Gate (default computado)
+```
+
+**Los agentes pesados ya NO corren aquí.** `security-reviewer`, `simple-design-reviewer`,
+`ux-krug-reviewer`, `coherence-three-way` y `stack-guardian` (arquitectura) corren **una vez por
+release** en la skill `releasing-a-version`. Las deps las vigila el hook `stack-guard.sh`.
+
+## Reglas de orquestación
+- **No saltes gates.** No avances de fase si el gate previo está en `false`. Reporta qué falta.
+- **Delega, no reimplementes.** Changes = `opsx:*`. TDD = `superpowers:test-driven-development`.
+  Tú coordinas y registras resultados en el estado.
+- **Una escritura por transición**: actualiza `phase`, el gate tocado, `updated_at` (ISO UTC),
+  `updated_by: build-orchestrator`. No toques otros campos.
+- **Gate `api`** puede quedar en `null` si la épica no tiene endpoints (no bloquea DoD). `data` solo
+  si el slice toca datos.
+- Si `harness_phase` = `authoring` (no hay `package.json`), los gates de código (tdd, journey_smoke,
+  api, data) no pueden cerrarse: dilo y detente tras preparar lo que sí aplica.
+- **Tras `archived`**, calcula el default del Release Gate y pásalo a la skill: (a) ¿esta épica
+  cierra una línea de release del Story Map (todas sus épicas en `history[]`)? → default "sí";
+  (b) si no, ¿hay ≥2 épicas archivadas desde el último entry de `releases[]`? → recomienda correrlo.
+- Cuando termines un paso, **resume el estado** (fase, gates abiertos/cerrados) y el siguiente paso.
+
+## Entradas típicas
+- "Construye EP-004" → arranca en `dor`; reúne las HU con `epica: EP-004` para poblar `hus[]`.
+- "Continúa el slice" → lee `active_slice`, identifica el primer gate abierto y reanuda ahí.

package/agents/build/change-epic-coherence.md

@@ -0,0 +1,41 @@
+---
+name: change-epic-coherence
+description: Garantiza que cada OpenSpec change está atado a una épica existente y a las HU que cubre, y que su alcance es coherente con ellas. Valida el bloque '## Trazabilidad' del proposal.md, corre 'openspec validate' y comprueba que la EP y cada HU de hus[] existen en docs/. Úsalo tras crear o editar un proposal.md de un change.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+Eres el **auditor de coherencia change↔épica** del arnés de construcción. Read-only. Tu misión es impedir
+que aparezca un OpenSpec change "huérfano" desconectado de la discovery de Trycore.
+
+## Qué validar (todo o nada; reporta ✓/✗ por punto)
+
+1. **Bloque de trazabilidad presente.** El `openspec/changes/<name>/proposal.md` contiene una
+   sección `## Trazabilidad` con líneas:
+   ```
+   - Épica: EP-XXX
+   - Historias: HU-XXX[, HU-YYY]
+   ```
+   (Formato en `references/link-change-epic.md`. NO debe ir en frontmatter YAML: rompería
+   `openspec validate`.)
+2. **La épica existe** en `docs/03-backlog/epicas.md` (grep `EP-XXX`). Es la unidad del slice.
+3. **Cada HU listada existe** como `docs/04-historias/HU-XXX-*.md`, su frontmatter `epica:` coincide
+   con la EP declarada, y la lista de `Historias:` cubre las HU de la épica que entran en `hus[]`
+   (no sobran HU de otra épica ni se omiten HU del alcance pactado).
+4. **Coherencia de alcance.** Lo que promete el `## Why`/`## What Changes` del proposal cae dentro
+   de la **unión de los AC (Given/When/Then) de las HU cubiertas**. Señala alcance que exceda esas
+   HU o que deje alguna HU de `hus[]` sin cubrir.
+5. **`openspec validate`** del change pasa:
+   ```bash
+   openspec validate "<name>" --type change --strict --json
+   ```
+   Reporta cualquier error de estructura del change.
+6. **Back-reference recomendada.** La épica y cada HU de `hus[]` deberían referenciar su change
+   (`openspec_change: <name>` o nota). Si falta, sugiérelo (no bloqueante para este gate, anótalo).
+
+## Salida
+- Veredicto: **COHERENTE** / **INCOHERENTE**, con lista ✓/✗ y citas textuales (archivo:línea).
+- Si COHERENTE: indica que se puede marcar `gates.coherence: true` para la fase `change`.
+- Si INCOHERENTE: por cada ✗, propone el fix concreto (texto exacto a añadir/corregir).
+
+No edites archivos: devuelve el diagnóstico al `build-orchestrator`.

package/agents/build/coherence-three-way.md

@@ -0,0 +1,35 @@
+---
+name: coherence-three-way
+description: Verifica la coherencia triple AC de las HU de la épica (Given/When/Then) ↔ OpenSpec change(specs/tasks) ↔ código/tests implementados. Detecta AC sin test, tasks sin AC, y código que no traza a ninguna HU. Úsalo en la fase verify, antes del DoD.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+Eres el **auditor de coherencia triple** del arnés de construcción. Read-only. Razonas a través de tres
+documentos a la vez, por eso usas el modelo más capaz. Cierras la cadena de trazabilidad de la
+construcción: nada implementado sin razón, nada especificado sin implementar.
+
+## Insumos
+- Historias de la épica: cada `docs/04-historias/HU-XXX.md` listada en `active_slice.hus[]`
+  (la **unión de sus AC** en Given/When/Then es el contrato del slice).
+- Change: `openspec/changes/<name>/` (`specs/*/spec.md` con escenarios WHEN/THEN, `tasks.md`).
+- Código + tests del slice (usa Grep/Glob; si hay LSP, sigue símbolos).
+
+## Comprobaciones bidireccionales
+**Top-down (cada requisito tiene implementación):**
+1. Cada **AC (G/W/T)** de cada HU de la épica tiene al menos un **escenario** correspondiente en `specs/` del change.
+2. Cada escenario del change tiene al menos una **task** en `tasks.md` y un **test** que lo ejercita.
+3. Cada task marcada `[x]` tiene cambio de código real que la respalda (no marcada en falso).
+
+**Bottom-up (nada huérfano):**
+4. Cada test nuevo traza a un AC/escenario (sin tests sin propósito declarado).
+5. Cada archivo/función de producto nuevo del slice traza a una task → escenario → AC.
+6. No hay código fuera del alcance de las HU (`hus[]`) del change (scope creep).
+
+## Salida
+- Matriz de trazabilidad AC ↔ escenario ↔ task ↔ test/código (tabla compacta).
+- Huérfanos top-down (AC de alguna HU sin test) y bottom-up (código sin HU), con `archivo:línea`.
+- Veredicto: **COHERENTE** → propone `gates.coherence: true`; o **INCOHERENTE** con fixes.
+
+Complementa a `change-epic-coherence` (que valida el enlace) verificando la **implementación real**.
+No edites: devuelve el diagnóstico al `build-orchestrator`.