@trycore/spec-build-harness 0.1.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
+  "name": "trycore-build",
+  "description": "Marketplace del arnés de construcción de Trycore para Claude Code.",
+  "owner": {
+    "name": "Trycore",
+    "url": "https://trycore.co"
+  },
+  "plugins": [
+    {
+      "name": "trycore-spec-build-harness",
+      "displayName": "Trycore — Spec & Build Harness",
+      "source": "./",
+      "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
+      "author": { "name": "Trycore", "url": "https://trycore.co" },
+      "homepage": "https://github.com/trycore-co/trycore-spec-build-harness",
+      "license": "UNLICENSED",
+      "keywords": ["build-harness", "openspec", "tdd", "gitflow", "quality-gates", "release-gate", "two-loop", "trycore"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "trycore-spec-build-harness",
+  "displayName": "Trycore — Spec & Build Harness",
+  "version": "0.1.0",
+  "description": "Arnés de construcción de dos loops (slice por épica + release gate) para Claude Code, con gates de calidad, estado compartido y OpenSpec. Compañero de @trycore/spec-product-flow. Agnóstico al proyecto.",
+  "author": {
+    "name": "Trycore",
+    "url": "https://trycore.co"
+  },
+  "homepage": "https://github.com/trycore-co/trycore-spec-build-harness",
+  "repository": "https://github.com/trycore-co/trycore-spec-build-harness",
+  "license": "UNLICENSED",
+  "keywords": [
+    "build-harness",
+    "openspec",
+    "tdd",
+    "gitflow",
+    "quality-gates",
+    "release-gate",
+    "two-loop",
+    "trycore"
+  ],
+  "skills": "./skills/",
+  "commands": ["./commands/opsx/", "./commands/build/"],
+  "agents": "./agents/build/",
+  "hooks": "./hooks/build-harness.json"
+}

package/GOVERNANCE.md

@@ -0,0 +1,48 @@
+# Gobernanza del arnés de construcción `.claude`
+
+Versión: ver `.claude/.build-harness-version` (`1.0.0`). El arnés es **soporte cognitivo vivo**:
+evoluciona con el modelo y el proyecto. No es "instalar y olvidar".
+
+## Componentes y dueño
+| Capa | Artefactos | Ubicación |
+|---|---|---|
+| Contexto | sección Construcción de CLAUDE.md, `openspec/project.md` | raíz / `openspec/` |
+| Estado | `build-state.json` (+schema, README) | `.claude/state/` |
+| Agentes | 10 agentes de build | `.claude/agents/build/` |
+| Hooks | settings.json + 6 scripts | `.claude/settings.json`, `.claude/hooks/build/` |
+| Skill | `building-a-slice` + 10 references | `.claude/skills/building-a-slice/` |
+| Config | allowlist de stack | `.claude/config/stack-allowlist.json` |
+
+## Fases de activación (`harness_phase`)
+- **authoring** (actual): aún no hay `package.json`. Activos: `gitflow-guard`, `load-build-state`,
+  `coherence-flag`; agentes de coherencia/stack/DoR/DoD operan sobre texto. Los hooks de
+  lint/typecheck/stack(package.json)/tests están **armados** pero inertes (`[ -f package.json ] || exit 0`).
+- **active**: al aparecer `package.json`, `load-build-state.sh` cambia la fase y los hooks armados
+  empiezan a disparar solos. Sin intervención manual.
+
+## Cadencia de auditoría (cada 3–6 meses)
+1. **Poda de instrucciones**: borrar reglas que el modelo nuevo ya maneja de forma nativa
+   (las instrucciones obsoletas limitan a modelos más capaces). Revisar agentes y references.
+2. **Validación de herramientas**: ¿hay modos nativos (LSP, MCP nuevos) que vuelvan redundante un
+   hook o un agente? Si sí, retirarlo.
+3. **Allowlist vs PRD**: re-sincronizar `stack-allowlist.json` con la sección de requisitos técnicos del PRD del consumidor (ruta declarada en `stack-allowlist.json#source`) si el stack cambió.
+4. **Coherencia de convenciones**: que `build-state.schema.json`, los agentes y la skill sigan
+   alineados (mismos nombres de gate/fase).
+
+## DRI (Directly Responsible Individual)
+Un **Agent Manager** (rol híbrido PM + DevEx) centraliza qué funciona y evita la fragmentación de
+convenciones. Aprueba cambios al schema de estado, a la allowlist y a la política de gitflow.
+Cambios al arnés se hacen por PR (el arnés se gobierna a sí mismo bajo GitHub Flow).
+
+## Cambios al stack
+Editar `stack-allowlist.json` SOLO si la sección de requisitos técnicos del PRD del consumidor (ruta declarada en `stack-allowlist.json#source`) cambia. Dejar nota aquí:
+
+### Bitácora de excepciones de stack
+- _(vacío)_ — registrar fecha, dependencia, justificación y aprobador.
+
+## Extensiones futuras (no implementadas)
+- **Construcción en paralelo** de slices con `superpowers:using-git-worktrees` + orquestación
+  multi-worktree (hoy el modelo es **secuencial** por decisión de proyecto). El `build-state.json`
+  pasaría de un `active_slice` a un arreglo de slices con locking por archivo.
+- **Empaquetado como plugin** + marketplace interno para distribuir el arnés a otros proyectos.
+- **LSP TypeScript** integrado a los agentes de coherencia/diseño cuando exista código.

package/INSTALL.md

@@ -0,0 +1,295 @@
+# Guía de instalación — `@trycore/spec-build-harness`
+
+Arnés agéntico de **construcción** de Trycore para Claude Code: pipeline de **dos loops**
+(slice por épica + release gate) con gates de calidad, estado compartido y OpenSpec.
+Es el **compañero** de [`@trycore/spec-product-flow`](https://www.npmjs.com/package/@trycore/spec-product-flow):
+**Discovery** (PRD → backlog → historias) → **Construcción** (este arnés).
+
+| Dato | Valor |
+|---|---|
+| Paquete npm | `@trycore/spec-build-harness` |
+| CLI (bin) | `trycore-build` |
+| Plugin | `trycore-spec-build-harness` |
+| Marketplace | `trycore-build` |
+| Versión | `0.1.0` |
+
+Hay **dos canales** de instalación: el **CLI npm** (canónico, recomendado para operar en un
+proyecto) y el **plugin nativo** de Claude Code (conveniencia a nivel usuario). Lee el
+[caveat de canales](#5-alternativa-plugin-nativo-con-caveat-de-canales) antes de elegir.
+
+---
+
+## 1. Instalar el CLI global (npm)
+
+```bash
+npm install -g @trycore/spec-build-harness
+```
+
+Esto expone el binario `trycore-build`. Comprueba la versión:
+
+```bash
+trycore-build --version    # → 0.1.0
+trycore-build --help
+```
+
+Comandos disponibles: `init` · `update` · `status` · `uninstall` · `doctor`.
+
+> Requiere Node `>=18.0.0` (`engines` del paquete).
+
+---
+
+## 2. Requisitos duros (externos) y `trycore-build doctor`
+
+El CLI **no puede** instalar estos binarios externos, pero los necesita en runtime. **`init` y
+`doctor` fallan con exit 1 si falta alguno**:
+
+| Requisito | Por qué | Cómo instalarlo |
+|---|---|---|
+| **`openspec`** | Columna vertebral de `/opsx:*` y de las skills `openspec-*` | `npm i -g @fission-ai/openspec` |
+| **`python3`** | Los hooks de `.claude/hooks/build/` parsean el JSON de estado con `python3` | Vía el gestor de tu sistema (brew, apt, pyenv…) |
+| **`git`** | Los hooks y `gitflow-guard.sh` resuelven la raíz del repo con `git rev-parse` | Vía el gestor de tu sistema |
+
+Verifícalos **antes** de instalar en un proyecto:
+
+```bash
+trycore-build doctor
+```
+
+`doctor` reporta:
+
+- Requisitos externos (`git`, `python3`, `openspec`) con ✓ / ✗ FALTA.
+- Hooks instalados y si tienen **bit ejecutable** (si alguno no lo tiene, sugiere `init --copy` o `chmod +x`).
+- Detección de **doble canal**: si hay hooks del arnés en `settings.json` (canal CLI) y además
+  instalaste el plugin nativo, avisa que la cadena de comando es idéntica y Claude Code
+  **deduplica** (el hook dispara **una sola vez**) — no requiere acción.
+
+Si falta un requisito duro, `doctor` termina con exit 1.
+
+---
+
+## 3. Instalar en un proyecto cliente — `trycore-build init`
+
+Desde la raíz del proyecto consumidor:
+
+```bash
+cd /ruta/al/proyecto-cliente
+trycore-build init
+```
+
+`init` es **idempotente** (re-correr es seguro; respeta `.claude/`, `CLAUDE.md` y el estado
+vivo preexistentes). Detecta automáticamente si es una instalación nueva (`init`) o una
+actualización (`update`) según exista `.claude/.build-harness-version`.
+
+Qué hace `init`:
+
+1. **Verifica requisitos duros** (a menos que uses `--skip-doctor`).
+2. **Siembra los assets** en rutas nativas de Claude Code:
+   - `.claude/agents/build/` — 10 agentes.
+   - `.claude/commands/opsx/` (10 comandos `/opsx:*`) y `.claude/commands/build/` (`/build:onboard`).
+   - `.claude/skills/` — 12 skills (`building-a-slice`, `releasing-a-version`, `openspec-*`).
+   - `.claude/hooks/build/` — 6 hooks bash.
+3. **Siembra el estado**: `state/build-state.schema.json` y `state/README.md` se versionan;
+   `state/build-state.json` se siembra **vacío y nunca se sobrescribe** (va al `.gitignore`).
+4. **Siembra `config/stack-allowlist.json`** (artefacto del consumidor; lo puebla `/build:onboard`).
+5. **Mergea hooks + permisos mínimos** en `settings.json` (canal CLI).
+6. **Inserta el bloque marcado** `<!-- BEGIN trycore-build-harness ... -->` en `CLAUDE.md`
+   con `{{placeholders}}` **sin resolver** (los resuelve `/build:onboard`).
+7. **Actualiza `.gitignore`** para no commitear el estado vivo ni los symlinks que se rompen
+   en otra máquina.
+
+Al terminar imprime el siguiente paso: abrir Claude Code y ejecutar `/build:onboard`.
+
+### Flags de `init`
+
+| Flag | Para qué |
+|---|---|
+| `[directory]` | Directorio donde instalar (default `.`) |
+| `--copy` | **Copiar** archivos en vez de symlinkear (Windows sin admin, sandboxes, CI) |
+| `--force-init` | Fuerza modo `init` aunque ya exista instalación previa |
+| `--skip-doctor` | Omite la verificación de `openspec`/`python3`/`git` (no recomendado: fallarán en runtime) |
+| `--stack <deps>` | Dependencias permitidas, coma-separadas (no interactivo) |
+| `--pkg-manager <pm>` | Package manager: `npm` \| `pnpm` \| `yarn` |
+| `--runtime <semver>` | Semver del runtime (ej. `">=18.18"`) |
+| `--prd-path <path>` | Ruta#ancla del PRD técnico (fuente del allowlist) |
+| `--yes` | No interactivo: usa defaults para el stack (CI-safe) |
+
+### Modo `--copy` (Windows / sandbox)
+
+Por defecto `init` **symlinkea** los assets desde el paquete global. En Windows sin permisos
+de administrador, o en sandboxes/contenedores donde los symlinks no se preservan, usa:
+
+```bash
+trycore-build init --copy
+```
+
+Esto copia los archivos físicamente y, en hooks, **preserva el bit ejecutable** (`+x`). En modo
+`--copy` los assets **no** se añaden al `.gitignore` (no se rompen al clonar), así que el equipo
+puede commitearlos.
+
+### Modo no interactivo / CI
+
+El CLI captura el **stack mecánico** (lenguaje/deps, package manager, runtime, ruta del PRD).
+En interactivo lo pregunta por TTY; en CI usa flags + `--yes`:
+
+```bash
+trycore-build init --yes \
+  --stack "fastapi,pydantic,sqlalchemy" \
+  --pkg-manager npm \
+  --runtime ">=18.18" \
+  --prd-path "docs/01-prd/prd.md#requisitos-tecnicos"
+```
+
+Si el stack se captura de flags/defaults (no interactivo), `init` lo avisa y recuerda que
+puedes ajustar `.claude/config/stack-allowlist.json` o ejecutar `/build:onboard` después.
+
+---
+
+## 4. Parametrizar el dominio — `/build:onboard`
+
+El onboarding tiene **dos capas** por una razón técnica: **un binario Node no puede escribir la
+auto-memory de Claude**.
+
+| Capa | Quién | Qué captura |
+|---|---|---|
+| **(1) Stack mecánico** | `trycore-build init` (CLI) | Lenguaje/deps, package manager, runtime, ruta del PRD; siembra archivos y el bloque marcado de `CLAUDE.md` con `{{placeholders}}` |
+| **(2) Dominio semántico** | `/build:onboard` (Claude) | Lee el PRD, resuelve los placeholders y escribe la auto-memory |
+
+Tras `init`, abre Claude Code en el proyecto y ejecuta:
+
+```
+/build:onboard
+```
+
+`/build:onboard` lee el PRD técnico (y `openspec/project.md` si existe) y, vía `AskUserQuestion`
+(proponiendo un valor "(Recomendado)" por punto), confirma y resuelve **6 puntos de extensión**
+que leen los agentes de calidad (`security-reviewer`, `stack-guardian`, `data-consistency-checker`,
+`ux-krug-reviewer`, `simple-design-reviewer`):
+
+| Placeholder | Qué pregunta |
+|---|---|
+| `{{PRD_TECH_PATH}}` | Ruta#ancla de la sección de requisitos técnicos del PRD |
+| `{{EXTERNAL_SERVICE_LAYER}}` | Capa de servicios externos / IA y su frontera/aislamiento |
+| `{{DETERMINISTIC_LAYER}}` | Lógica que **no** puede delegarse a un servicio no determinista |
+| `{{SENSITIVE_DATA_CATEGORIES}}` | Categorías de datos sensibles / PII reguladas |
+| `{{SERVER_SIDE_SECRETS}}` | Secretos server-side que jamás van al cliente |
+| `{{HIGH_STAKES_DECISIONS}}` | Decisiones de alto impacto que exigen explicabilidad en la UI |
+
+Qué resuelve:
+
+- Reemplaza los `{{placeholders}}` **dentro del bloque marcado** de `CLAUDE.md` (no toca nada fuera de los markers).
+- (Opcional) Puebla `.claude/config/stack-allowlist.json` contrastando `package.json` contra el PRD.
+- Escribe **auto-memory** tipo `project` (`build_prd_tech_path.md`, `build_external_service_layer.md`,
+  `build_deterministic_layer.md`, `build_sensitive_data.md`, `build_server_side_secrets.md`,
+  `build_high_stakes_decisions.md`) y las registra en `MEMORY.md`.
+
+Si un punto no aplica, se registra explícitamente "no aplica" (no se deja como `{{...}}`).
+
+---
+
+## 5. Alternativa: plugin nativo (con caveat de canales)
+
+Como conveniencia a nivel usuario, el arnés también se instala como **plugin nativo** de Claude Code:
+
+```
+/plugin marketplace add <repo-github>
+/plugin install trycore-spec-build-harness@trycore-build
+```
+
+### ⚠ Caveat de canales (importante)
+
+- El **canal npm CLI es el CANÓNICO**. `trycore-build init` instala los comandos en
+  `.claude/commands/{opsx,build}/`, que namespacean **por subcarpeta** → `/opsx:*` y `/build:onboard`,
+  y los agentes se referencian por su **nombre** (`security-reviewer`, `stack-guardian`, …).
+- El **canal plugin nativo** namespacea **todos** los componentes bajo el **nombre del plugin**
+  (→ `/trycore-spec-build-harness:*`), por diseño de Claude Code.
+- Las **cross-references internas** del arnés (skills que invocan `/opsx:*`, agentes referenciados
+  por nombre) están escritas para el **canal CLI**.
+
+**Recomendación:** para **operar dentro de un proyecto**, usa el **CLI** (`trycore-build init`),
+porque garantiza que las invocaciones internas `/opsx:*` y por nombre de agente resuelvan tal cual
+están escritas. El plugin es útil para descubrir/probar los componentes a nivel usuario.
+
+### Hooks: una sola cadena autorresolutiva
+
+Ambos canales registran exactamente la **misma** cadena de comando en cada hook:
+
+```
+"${CLAUDE_PLUGIN_ROOT:-$CLAUDE_PROJECT_DIR/.claude}/hooks/build/<script>.sh"
+```
+
+Si instalas **ambos** canales, Claude Code **deduplica** por cadena idéntica y el hook dispara
+**una sola vez**. `trycore-build doctor` lo detecta y confirma que no requiere acción.
+
+---
+
+## 6. Coexistencia con `@trycore/spec-product-flow`
+
+Ambos paquetes coexisten en el mismo `.claude/` **sin colisión**, porque usan **namespaces disjuntos**:
+
+| | Discovery — `spec-product-flow` | Construcción — `spec-build-harness` |
+|---|---|---|
+| Comandos | `/trycore:*` | `/opsx:*` + `/build:onboard` |
+| Marca de versión | `.trycore-version` | `.build-harness-version` |
+| Bloque en `CLAUDE.md` | `<!-- BEGIN trycore-vertical -->` | `<!-- BEGIN trycore-build-harness -->` |
+
+Flujo conjunto: Discovery produce el PRD y el backlog → Construcción consume el PRD por épica
+(`EP-XXX`) en el inner loop y cierra cada release en el outer loop. La carpeta `.claude/skills/`
+es compartida: por eso `uninstall` quita **solo** las skills del arnés, no toda la carpeta.
+
+---
+
+## 7. Mantenimiento — `update` / `status` / `uninstall`
+
+### `trycore-build update`
+
+```bash
+trycore-build update [directory] [--copy] [--skip-doctor]
+```
+
+Refresca assets y schema tras actualizar el paquete npm (es `init` en modo `update`, no interactivo).
+**Nunca pisa** `build-state.json` ni `stack-allowlist.json` (estado y allowlist son del consumidor).
+
+> Flujo típico: `npm i -g @trycore/spec-build-harness@latest` y luego `trycore-build update` en cada proyecto.
+
+### `trycore-build status`
+
+```bash
+trycore-build status [directory]
+```
+
+Muestra: versión del paquete vs versión instalada (avisa si hay drift → `update`), conteo de
+componentes (agentes/comandos/skills/hooks), requisitos externos (`openspec`/`python3`), y el
+**estado del arnés** desde `build-state.json` (fase, slice activo, gates abiertos, historial, releases).
+
+### `trycore-build uninstall`
+
+```bash
+trycore-build uninstall [directory]
+```
+
+Quita **solo** lo que `init` puso: agentes, comandos `/opsx:*` y `/build:*`, hooks, skills del arnés,
+la marca de versión, los bloques marcados de `CLAUDE.md` y `.gitignore`, y los hooks/permisos en
+`settings.json` (por cadena exacta).
+
+**Preserva `.claude/state/` y `.claude/config/`** — el estado vivo y el `stack-allowlist.json` son
+del consumidor y no se borran.
+
+---
+
+## 8. Troubleshooting
+
+| Síntoma | Causa | Solución |
+|---|---|---|
+| Hooks **no ejecutables** (`✗` en `doctor`) | Symlinks o copia sin bit `+x` (Windows/sandbox) | `trycore-build init --copy` (preserva `+x`), o `chmod +x .claude/hooks/build/*.sh`; verifica con `trycore-build doctor` |
+| `init` **falla**: "Faltan requisitos externos" | Falta `openspec`, `python3` o `git` | Instala `openspec` con `npm i -g @fission-ai/openspec`; `python3`/`git` vía el gestor del sistema. Reintenta `init` (o `--skip-doctor` para forzar, sabiendo que fallarán en runtime) |
+| `/opsx:*` o skills `openspec-*` fallan en runtime | `openspec` ausente | `npm i -g @fission-ai/openspec`; confirma con `trycore-build doctor` |
+| `status` avisa "desincronizado" | Versión instalada ≠ versión del paquete | `trycore-build update` |
+| Symlinks rotos al clonar en otra máquina | Se commitearon symlinks absolutos al paquete global | Usa `--copy`, o respeta el `.gitignore` que añade `init` (no commitees los assets symlinkeados) |
+| `/build:onboard` dice "NOT_INSTALLED" | No existe `.claude/.build-harness-version` | Corre `trycore-build init` antes de `/build:onboard` |
+| `CLAUDE.md` sin bloque marcado tras instalar | Caso raro post-install | `trycore-build init` (o `update`) para re-insertar el bloque, luego `/build:onboard` |
+
+---
+
+> **Nota de gobierno:** `METODOLOGIA.md` es la fuente de verdad del arnés. Si una skill contradice
+> la metodología, **gana la metodología** (regla dura del bloque `CLAUDE.md`). El core es 100%
+> agnóstico al proyecto; el ejemplo de referencia vive en `docs/examples/reference/`.