Uscha es spec-driven y agnóstico de herramienta, y arranca antes del spec. Este es el manual operativo para correrlo en Claude Code con el uscha-kit: cada jugada te dice cuándo se dispara, qué hacés, y qué lo verifica.
Uscha rechaza el supuesto de siempre: que ya sabés qué construir. La falla cara es un build confiado de la forma equivocada — por eso la primera jugada es siempre encontrar la forma, y cada jugada posterior avanza sobre evidencia capturada, frenando antes del merge.
Corré /uscha-discovery cuando tenés una idea pero no una forma; corré /uscha-adr-refine cuando la forma ya está y solo faltan los bordes. Ninguno escribe código — corren sobre Read, Write, Glob, Grep (discovery suma WebFetch).
Interrogá, no acuerdes. Un discovery donde el asistente estuvo de acuerdo con todo fracasó — un entrevistador complaciente hereda tus puntos ciegos y te los devuelve formateados como plan. Si no te está apretando, reiniciálo — la fricción es el entregable.
A medida que se asientan las decisiones, escribilas directo en el repo — no las acumules para el final. El build lee archivos, no el chat.
| CONTEXT.md | Glosario de dominio — mata el lenguaje difuso. |
| DOMAIN-MODEL.md | La forma aprobada: entidades + relaciones. |
| SPEC.md | Comportamiento, I/O, errores, aceptación, rollback. |
| docs/adr/*.md | Uno por decisión durable; ejecutable. |
| ACCEPTANCE.md | DoD como - [ ] — lo que mide readiness. |
| RISKS · HANDOFF | Riesgo residual; qué leer antes de codear. |
Los resets de contexto (sesión nueva, /clear, compactación) pierden el chat. Los sub-agentes (y el CI que tengas, si tenés) leen archivos. La verdad vive en archivos versionados.
Preguntá: ¿qué puede romper esto, y cuánto cuesta la rotura? La respuesta dimensiona el aparato. No arrastres toda la máquina detrás de un ajuste de config. Es una heurística de proceso: en el código/config del kit no existe el concepto de perfil, y ningún perfil selecciona gates automáticamente — los elegís vos.
| Perfil | Ejemplo | Gates mínimos |
|---|---|---|
| A · Bajo | UI menor / config | build + test relevante |
| B · Normal | feature local / bugfix | tests + estático + review |
| C · Crítico | pagos / seguridad | unit+integración+seguridad+rollback |
| D · Multi-sistema | API pública / eventos | contract tests + versionado |
| E · Legacy | refactor / migración | caracterización + no-regresión |
Perfil E → golden testing es obligatorio (ver jugada 08). Baselineá el comportamiento viejo antes de tocarlo.
Tres documentos, tres niveles de fuerza.
Si falta uno → es una línea del SPEC. El Implementation Plan hace ejecutable al ADR; el código enlaza de vuelta con // ADR: <slug>.
Un ADR elige; la CONSTITUTION prohíbe. Un ADR puede elegir Postgres vs Redis. Un ADR no puede elegir "guardar el secreto en texto plano" — la CONSTITUTION lo veta antes. El motor no lee CONSTITUTION.md solo: detectar la violación es deber del agente/humano, y el agente debe loguearla con flag-blocker --kind constitution. Una vez logueada, capea readiness ≤65 y bloquea la convergencia hasta el --resolve (humano). Los invariantes están mapeados a CWE.
El orquestador toma los ADR + ACCEPTANCE.md, construye, y corre un loop de review gateado por severidad que frena. Tres leyes: convergé, no persigas el cero · los tests son un guardarraíl, no el final · generar tests ≠ correrlos.
qa_ledger.py init; ADR + aceptación adentro. Sin aceptación → corré /uscha-adr-refine primero./uscha-sysdoc es reporte opcional (a pedido), no una fase obligatoria del pipeline.El loop Ralph Wiggum — el agente dispara el token de "listo" demasiado temprano. Lo cierran los gates objetivos más el humano en el merge — nunca una opinión, y el motor solo no lo cierra.
Si el que hace escribe su propio boletín, puede loguear exit_code: 0 sin haber corrido nada. Por eso el ledger parsea archivos reales — no transcribe afirmaciones.
# qa_ledger.py lee archivos, no al agente
coverage ← reporte de coverage (ej. jacoco.xml / lcov)
tests ← XML de resultados (ej. JUnit / surefire)
estático ← linters · type-checker · scanner de seguridad
LOC ← su propio conteo (stdlib)
gates ← veredictos persistidos con log-gate (pass|fail|not-run)
Ausente = sin evidencia, nunca "OK". Un reporte vacío-pero-presente acredita el fix; un reporte ausente significa que el gate no corrió. Una herramienta que no corrió jamás se inventa en verde.
El que hace ≠ el que chequea. El que hace no gradúa su propio trabajo — lo hace un checker de contexto fresco. (Evaluator-optimizer de Anthropic, dic 2024.)
Un gate que lee un hecho puede bloquear el trabajo. Un gate que conjetura sobre prosa solo puede susurrar. Rompé esto y los falsos positivos matan el gate — el dev lo apaga, y un gate muerto es peor que ninguno.
| Gate | Lee | |
|---|---|---|
| golden-diff | bytes vs .approved | BLOQUEA |
| pit-check | XML de mutación — tier programado/incremental, no del loop interno; si el reporte existe y falla, se persiste | BLOQUEA |
| gate-check | estructura del diff (tests borrados/deshabilitados · thresholds bajados · secretos agregados — 1.12.0) | BLOQUEA |
| static gate | 4 linters, normalizados | BLOQUEA |
| spec-check (estructura) | falta out-of-scope · aceptación ausente/vacía · cero AC-n trazables — hechos, exit 1 | BLOQUEA |
| phase --require pr-ready | estado DERIVADO del ledger; rama spike/* jamás pasa (1.18.0–1.19.0) | BLOQUEA |
| regression-check | cierre de findings sin test nuevo = NARRATED (1.16.0); --strict lo gatea | ACONSEJA |
| waste-check | clones Type-1/2 del diff vs el repo (reuse-first, 1.26.0) — la duplicación que simplicity-check no ve; flags con file:line a reusar; gatea solo con --gate o defaults.waste.gate | ACONSEJA |
| rubric-ingest | grade de la rúbrica (criterio cualitativo versionado, contrato JSON agnóstico, 1.23.0); gatea solo si el humano lo declara | ACONSEJA |
| spec-check (prosa) | heurística sobre prosa (vaguedad, EARS); --strict la gatea | ACONSEJA |
Un checker no correlacionado atrapó el 93.4% de lo que atraparon cuatro (Osmani). Apilá opiniones distintas, no cuatro linters parecidos. En /uscha-devloop el agente corre los gates de hecho inline (exit 0/1) y persiste cada veredicto con qa_ledger.py log-gate --kind golden-diff|gate-check|pit-check|simplicity|regression --verdict pass|fail|not-run: un fail bloquea la convergencia y capea readiness ≤65; un not-run queda registrado pero nunca es verde. El loop frena en el merge gate y revisa el humano — el kit no trae workflow de CI.
Todo lo demás lo authorea el agente. El golden es lo único que no puede authorear — y ese es el punto. Capturá lo que el código viejo realmente hace corriéndolo, congelálo como .approved aprobado por humano, y diffeá el código migrado contra eso.
golden-diff limpio, o no hay merge — exit 0 CLEAN · 1 DIVERGE · 2 NOT-RUN (cero fixtures = NOT-RUN, nunca CLEAN)..approved — un hook PreToolUse bloquea la escritura.*.approved.* binary al .gitattributes — si no, los fin-de-línea mienten.Si el agente authoreara el golden, codificaría el mismo entendimiento parcial que perdió la lógica. El golden es un chequeo sobre el agente, no uno que él mismo se otorga — que es precisamente por lo que existe.
El loop externo es un latido que dispara al interno con una cadencia. No lo construyas hasta que los cuatro sean verdad.
# latido envolviendo /uscha-devloop > /loop 0 3 * * * # cadencia nocturna /goal readiness ≥ 80 AND tests verdes AND 0 CRITICAL # checker de otra familia o al menos otro perfil (proceso, no código) > corré /uscha-devloop sobre <scope chequeable por máquina> stop = /goal cumplido (checker fresco) OR sin presupuesto on-done = draft PR · escalá toques a la CONSTITUTION humano = merge/deploy SIEMPRE con aprobación
Loop desatendido = superficie de ataque desatendida. SAST + secret-scan + dep-audit antes de cualquier PR; vetá el origen de cada skill antes de instalarla; logs no-verbosos; re-auditá permisos cada 30d, arrancá read-only; rotá la sesión antes de que se infle. Métrica: costo por cambio aceptado — por debajo del 50% de aceptación, el loop está perdiendo.
Regulado/fiscal, pagos y retail crítico están todos del lado "NO autonomizar". Gateado-por-diseño no es un hueco — es la decisión.
Arreglá primero. Pero la evidencia mínima (qué cambió, cómo revertir) + un SPEC/ADR retroactivo vencen dentro de 24h. Es una regla de proceso que el equipo se compromete a cumplir — no una feature del kit. Una válvula de escape diseñada mantiene honesto al método bajo presión; una improvisada lo destruye.
Claude Code + Python + git/gh + skills corren el método. Los pedazos específicos del stack (build tool, driver de base, linters) son el adaptador por-repo en cada CLAUDE.md — no el banco de trabajo.
# instalador nativo — sin Node, se autoactualiza curl -fsSL https://claude.ai/install.sh | bash # mac/linux/wsl irm https://claude.ai/install.ps1 | iex # windows cp -r uscha-kit/.claude/skills/* ~/.claude/skills/ scoop bucket add gentleman https://github.com/Gentleman-Programming/scoop-bucket scoop install gentle-ai # toolchain del autor — opcional, el kit no lo requiere claude --version && claude doctor
Clonarlo a un compañero no es un archivo — son 7 capas: config, plugins, skills, agents+commands, hooks, el CLI externo, y los servidores MCP (taxonomía del setup del autor — no viene en el kit; lo que el kit trae es Claude Code CLI, Python 3.8+, git, gh opcional, las skills copiadas a ~/.claude/skills y config + permisos por repo).
settings.json hardcodea C:\Users\…. El bootstrap que tokeniza el path al exportar y lo reescribe al importar es tooling del autor — no viene en el kit.| /uscha-discovery | interrogatorio idea→forma; propone entidades/endpoints. |
| /uscha-adr-refine | pulir los bordes de una decisión. |
| /uscha-devloop | plan → coverage → build → QA loop → integración. |
| /uscha-sysdoc | reporte opcional (a pedido) — deck de dos vistas desde el ledger. |
| doctor | diagnóstico de la instalación (flutter-doctor spirit): python/git, 9 skills, hook INV-GOLDEN-01, config/ACCEPTANCE/ledger, toolchains por type — exit 1 solo con errores (1.22.0). |
| qa_ledger init | arma el ledger desde uscha.config.json. |
| snapshot | coverage/tests/LOC (--phase pre|post). |
| check-coverage | exit 0 si ≥ umbral (gate de fase 1). |
| ingest-gate | parsea linters, normaliza severidad, diffea IDs. |
| converged | ciclo limpio + static gate limpio. |
| oscillation | repetición de huella período-2. |
| readiness | KPI 0–100 que reporta (siempre exit 0), con caps duros — no es un gate exit 0/1. Veredicto único (anti-ceremonia, 1.25.0): por default UNA pantalla — veredicto + una línea --- gates: colapsada; --verbose expande las dimensiones y el detalle por repo. |
| rebuild | completitud del spec: COVERS/PARTIAL/DIVERGE — exit 1 salvo COVERS. |
| golden-diff | bytes vs .approved — verdad de campo, aprobada por humano; exit 0 CLEAN · 1 DIVERGE · 2 NOT-RUN. |
| log-gate | persiste el veredicto de un gate de hecho (--kind golden-diff|gate-check|pit-check|simplicity|regression, --verdict pass|fail|not-run). |
| flag-blocker | loguea una violación (ej. --kind constitution): capea readiness ≤65 y bloquea convergencia hasta --resolve (que exige --escape-analysis: qué gate/test debió atraparla — 1.16.0). |
| resolve-escalation | resuelve una escalación; sin resolver, readiness queda capeado ≤75. |
| regression-check | Find Bugs Once (1.16.0): findings cerrados sin línea nueva de test = NARRATED (avisa; --strict gatea). |
| waste-check | reuse-first (1.26.0): clones Type-1/2 determinísticos del diff vs el repo — la duplicación que simplicity-check no ve; flags con file:line a reusar; advisory salvo --gate o defaults.waste.gate. |
| summary | métricas retrospectivas (--json lo consume /uscha-sysdoc); incluye el first-time yield (FTY, 1.27.0): % de repos que pasaron QA en el 1er ciclo — informativo, jamás gatea. |
| phase | estado del workflow DERIVADO del ledger (plan/build/qa/escalated/pr-ready), jamás declarado; --require pr-ready gatea el PR y veta ramas spike/* (1.18.0–1.19.0). |
| rubric-ingest | ingesta el JSON del grader de la rúbrica (evidence-or-nothing, score ponderado vs threshold); advisory por default, --gate o defaults.rubric.gate lo vuelve bloqueante (1.23.0). |
| init | comando del ledger. |
| log-step | registra un pase de una herramienta de QA. |
| escalate | registra una escalaci?n humana. |
| production-finding | registra o resuelve feedback de producci?n. |
| spec-doubt | registra o resuelve una duda de SPEC. |
| spec-change-request | registra o resuelve un pedido humano de cambio de SPEC/ADR. |
| execution-policy | imprime el ruteo de modelo/esfuerzo por fase. |
| dashboard | emite el contrato de datos de Mirador. |
| simplicity-check | eval?a minimalidad y complejidad del diff. |
| pit-check | eval?a efectividad de tests desde PIT. |
| gate-check | detecta debilitamiento de gates o secretos. |
| spec-check | valida estructura y trazabilidad de SPEC/ACCEPTANCE. |
Antes de editar cualquier .md trackeado (CLAUDE.md, docs de plan/delta, docs/adr), traé primero la versión actual del repo. Esos archivos cargan progreso vivo — nunca los regeneres de cero.