@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)

# 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)

/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; reporta slices sin reflexionar y sugiere LSP en stacks tipados. |

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. Tras archivar, /build:reflect puede capturar las convenciones aprendidas del slice (ciclo autocorrectivo, opcional; lo sugiere el hook reflect-nudge.sh).

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. | | /build:reflect | Reflexión post-slice: tras archivar, propone convenciones aprendidas / errores recurrentes al bloque trycore-build-learnings de CLAUDE.md (tras tu aprobación) y marca el slice como reflexionado. | | /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/              ← 11 agentes revisores (segunda opinión, contexto limpio)
├── commands/
│   ├── opsx/                  ← 10 comandos /opsx:* (ciclo OpenSpec)
│   └── build/                 ← /build:onboard, /build:reflect
├── skills/                    ← 12 skills (building-a-slice, releasing-a-version, 10 openspec-*)
├── hooks/build/               ← 9 hooks bash (gate-check, reflect-nudge, scaffold-guard, 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 11 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, change-epic-coherence y ux-fidelity-reviewer.

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 — 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.
• ✅ v0.2.0 — scaffold como "Paso 1 fundamental": gate de proyecto scaffold.confirmed (confirmación explícita, no auto), Fase 0 en building-a-slice, criterio duro de DoR y hook scaffold-guard.sh. El arnés exige el scaffold pero no lo genera.
• ✅ v0.3.0 — ciclo autocorrectivo (hook reflect-nudge.sh + comando /build:reflect: propone convenciones aprendidas al bloque trycore-build-learnings de CLAUDE.md tras tu aprobación; campos reflected/reflected_at) y LSP opt-in (docs/customization/lsp-extensions.md + sugerencia en doctor para stacks tipados). Total: 8 hooks; comandos /opsx:* + /build:onboard + /build:reflect.
• ✅ v0.4.0 — carril building-a-micro-change (mantenimiento ligero sin slice) + DoR proporcional a la complejidad.
• ✅ v0.5.0 (actual) — seguro de fuente de diseño (design_source + design-source-guard.sh) + agente ux-fidelity-reviewer (gate fidelity, inner loop). Total: 11 agentes, 9 hooks.

Licencia

Uso interno de Trycore.