hardware-in-the-loop

Hardware in the loop

Estás configurando (o ejecutando) un proyecto de hardware donde los agentes hacen la ingeniería y las compuertas la prueban. Lee todo este archivo antes de actuar. El método se describe en el repositorio docs/ (MÉTODO, PCB, CAD, FIRMWARE, SIM, SWARM, HERRAMIENTAS, LECCIONES); este archivo es el procedimiento.

0. Di el costo primero

Antes de cualquier otra cosa, dile al usuario, claramente:

Ejecutar este método con un enjambre de agentes es costoso. En el proyecto del que proviene, un día de enjambre quemó 4-5 millones de tokens, principalmente despertando agentes de carril que cada uno llevaba 300-800k tokens de contexto. El modo más barato es una sesión única sin subagentes que trabaja paso a paso, ejecuta trabajos largos de máquina desprendidos, y reanuda desde una sección "Donde me detuve". ¿Qué modo quieres? (recomendado: sesión única)

Registra la respuesta como mode (single o swarm). No generes ningún subagente antes de que el usuario elija el modo enjambre.

1. Entrevista de incorporación

Ejecuta la entrevista en references/interview.md a través del diálogo de preguntas: lotes de máximo cuatro preguntas, el valor predeterminado recomendado primero en cada pregunta. Cuando una pregunta no recibe respuesta, toma el valor predeterminado y escribe "valor predeterminado tomado" junto a ella. Cubre: objetivo del proyecto y definición de finalización, objetivos en orden, presupuesto, cantidades, material impreso predeterminado (nailon con fibra de carbono / PETG / PLA / aluminio mecanizado), fijación (insertos termofusibles / roscado autorroscante / pernos pasantes), carcasa (sellada / ventilada / abierta), holgura mecánica, fabricante de PCB y montaje, familia de MCU, alimentación principal y transitorio peor caso, clase de placa y recubrimiento, niveles de simulación (gemelo nativo / Isaac Sim / Unreal) y la GPU, límites de la máquina (límite de CPU predeterminado 90 %, RAM libre para el sistema predeterminada 4 GB, espacio libre en disco mínimo predeterminado 50 GB), ubicación del archivo, disparador de uso (predeterminado 95 %), decisiones permanentes.

Los materiales, la fijación, el sellado de la carcasa y la holgura son DECISIONES DEL PROYECTO: nunca las elijas en silencio; pregunta, recomienda, registra.

Escribe las respuestas en answers.json en el directorio .tmp/ del repositorio de destino (esquema en references/interview.md).

2. Generar el esqueleto

python -I <skill>/scripts/scaffold.py --answers <repo>/.tmp/answers.json --dest <repo> [--with-examples] [--dry-run]

Copia templates/ (README_AGENT.md, PROJECT_STRUCTURE.md, REQUIREMENTS.md, README.md, CODING_RULES.md, .gitignore, .gitattributes, windows/ci.ps1 + windows/ci/ (grupos audit y pcb), tools/ (auditoría + portabilidad con una línea base rastreada vacía y archivo de exención), pcb/ (DESIGN_STANDARDS.md, tools/kicad_env.py, tools/board_pipeline.py, tools/distributor_verify.py), cad/ (cad_plugins.py, render.py, mass_cg_table.py), firmware/host_tests/hil_check.h, docs/bench/BENCH_REGISTER.md, docs/data/README.md, harness/swarm/ (AGENT_RULES, scripts de slot / detach / watch / merge lock / merge-to-dev / promote / WIP backup / handoff hook / status line) y .claude/settings.local.json (línea de estado + enlace PostToolUse)), rellena las variables de la plantilla, escribe harness/swarm/machine.env y harness/swarm/PLAN.md para el modo elegido. Nunca sobrescribe un archivo existente; compara los archivos conservados manualmente y fusiona lo que sea útil. --with-examples añade la placa de ejemplo (un breakout de regulador LDO de 3.3 V de 2 capas que ejecuta cada paso del pipeline) y el constructor de carcasas de ejemplo con dos complementos.

Luego completa la tabla de decisiones en pcb/DESIGN_STANDARDS.md sección 0 a partir de las respuestas.

3. Herramientas

pwsh -File <skill>/scripts/setup_tools.ps1 -ToolsRoot <una carpeta fuera del perfil de usuario> [-VerifyOnly]
bash <skill>/scripts/setup_tools.sh --tools-root <dir> [--verify-only]          # Linux

KiCad 10 (winget), Java 21 (winget), Freerouting 2.1.0 (SHA-256 fijo), OSS CAD Suite 2026-10-24 (SHA-256 fijo, solo para proyectos FPGA), un entorno virtual CadQuery. Escribe <ToolsRoot>/hil_tools.env con HIL_FREEROUTING_JAR, HIL_JAVA, HIL_KICAD_CLI, HIL_CQ_PYTHON. Pregunta antes de instalar nada en toda la máquina; ejecuta primero -VerifyOnly y muéstrale al usuario lo que falta. Nada va al perfil del usuario.

4. Git: main y dev

En el repositorio de destino (pregunta antes de ejecutar git en un repositorio que ya tenga historial):

git init -b main            # cuando aún no es un repositorio
git add -A && git commit -m "Esqueleto del proyecto (método hardware-in-the-loop)"
git branch dev
git push -u origin main dev # cuando existe un remoto

Usa la identidad git configurada de la máquina. Sin líneas de atribución ni coautores. Nunca hagas force-push. Luego ejecuta la primera pasada de CI y conserva su informe como referencia principal:

pwsh -File windows/ci.ps1 -Only audit

5. Armar el arnés

• .claude/settings.local.json conecta usage_statusline.py (línea de estado, disparador en HIL_HANDOFF_PCT) y handoff_hook.sh (PostToolUse). Prueba el enlace: touch harness/swarm/HANDOFF_SELFTEST, ejecuta cualquier herramienta, espera el contexto "el enlace está activo", elimina el archivo.
• Inicia la copia de seguridad de WIP desprendida: bash harness/swarm/detach.sh harness/swarm/wip_backup.sh .tmp/wip_backup.log.
• Verifica bash harness/swarm/locks/slot.sh status.
• La sesión principal se ejecuta desde el checkout principal (ahí es donde vive harness/); las ediciones ocurren en worktrees.

6. Trabajo: modo de sesión única (predeterminado)

Sigue harness/swarm/PLAN.md (de references/single-session-plan.md):

1. Un paso numerado a la vez, cada uno con la compuerta que lo prueba.
2. Trabaja en .claude/worktrees/main-work en swarm/main-work; confirma, sube, ejecuta merge_to_dev.sh después de cada compuerta verde.
3. Trabajos pesados: eval "$(bash harness/swarm/locks/slot.sh take <tipo> <tú> "<trabajo>" <GB>)", libera después.
4. Trabajos largos: bash harness/swarm/detach.sh <cadena.sh> <log> e inmediatamente bash harness/swarm/watch.sh <log> como tarea en segundo plano; continúa con el siguiente paso mientras se ejecuta.
5. Preguntas del propietario: por lotes, valor predeterminado recomendado primero; los valores predeterminados tomados se escriben en el plan.
6. Detención: añade "## Donde me detuve" (tareas hechas con SHA, trabajos en ejecución con PID y logs, siguiente paso exacto).

7. Trabajo: modo enjambre

Sigue docs/SWARM.md y references/wave-checklist.md:

1. Ola 1, reconocimiento: agentes de solo lectura escriben hechos verificados con anclajes de archivo:línea en harness/swarm/recon_<area>.md.
2. Ola 2, plan: PLAN.md (references/plan-template.md) con carriles, un propietario por archivo (cambios entre carriles como archivos de parche en harness/swarm/handoff/), adiciones de interfaz, números de aceptación; briefs.md con un resumen por carril (references/brief-template.md).
3. Ola 3, carriles en worktrees swarm/<nombre>: Sonnet para trabajo mecánico (puertos, códecs, renders, pruebas, documentos), Opus para trabajo sutil (control, física, geometría, integridad de señal). Cada uno devuelve el informe estructurado (references/structured-report.md).
4. Ola 4, escépticos: agentes nuevos con el diff y solo el informe; audit_placeholders.py --changed-since origin/dev --fail-on-new, los grupos CI del carril, tres números revisados.
5. Ola 5, integración: cada carril llega a dev con merge_to_dev.sh (siempre, incluso en rojo, bajo MERGE_LOCK); CI completo en dev con -Compare <informe principal> -FailOn regressions; promote_dev.sh solo con cero regresiones.

Mantén los carriles pocos y los resúmenes exactos; cada despertar de un agente con contexto grande cuesta dinero real.

8. Disciplina (ambos modos)

• PCB: primero generativo (docs/PCB.md). ERC 0/0, DRC 0 violaciones / 0 desconectado / 0 paridad en severidades predeterminadas, cada línea comprada verificada en vivo, conjunto de fabricación + JSON de resultados con SHA-256. Se espera colocación manual por ti cuando el auto-colocador falla. Se permiten más capas; informa el delta de precio. Relajar una regla necesita una base citada.
• CAD: constructores + complementos; una tabla de masa / estación / CG (cad/mass_cg_table.py) con cada cambio de pieza; PNG de ajuste y choque (cad/render.py) en docs/cad_decisions/<fecha>/<tema>/.
• Firmware: compilaciones fuera del árbol, suites de host con hil_check.h, escenarios a través de la interfaz real, barridos de semilla, determinismo; pendiente de hardware listado.
• No se muestra trabajo sin terminar como terminado; las constantes solo de banco obtienen IDs BENCH B-xx-nn.
• Máquina: slots, prioridad por debajo de lo normal, tiempos de espera, nunca mates lo que no iniciaste, nunca find desde una raíz, verifica el disco primero, un trabajo Unreal / GPU a la vez, ningún lanzamiento de Unreal mientras el propietario está en la máquina.

9. Traspaso y nocturno

• Cuando aparezca HANDOFF_NOW (el enlace te lo dice), deja de comenzar trabajo y sigue su instrucción: confirma, sube, libera, escribe harness/swarm/resume_<fecha>/RESUME_<fecha_hora>_<carril>.md (references/resume-doc.md).
• Antes de que el propietario se vaya por la noche: una cadena nocturna desprendida y las preguntas matutinas (references/overnight-questions.md). La noche se ejecuta con los valores predeterminados; registra cada valor predeterminado tomado.