Agents Harness

Harness generico de .agents para arrancar el mismo workflow de agentes en todos los repositorios. Inspirado en los sistemas de .agents de Khatarsis (Vue 3, v3.3) y Alytos (Java/Spring, v1.0): mismo flujo conversacional, mismas compuertas de autorizacion y mismo ciclo de vida de planes en cada repo, sin reinventar el sistema por proyecto.

Que ofrece

• Unica fuente del workflow: Orquestador -> Enrichment -> Executor, identico en todos los repos.
• Compuertas explicitas: "enriquece el plan" (PENDING -> ENRICHED) y "ejecuta el plan" (READY -> EXECUTED). Ninguna frase ambigua ("continua", "procede", "investiga") autoriza transiciones.
• Ciclo de vida de planes: PENDING -> ENRICHED -> READY -> EXECUTED -> CLOSED, con plan MD persistido en .agents/plans/ para solicitudes amplias. Los planes son la memoria persistente del proyecto: nunca se eliminan y todo cambio se documenta en el plan antes de ejecutarse.
• Definition of Done: ningun plan pasa a CLOSED sin cumplir el DoD (verificacion, higiene, entrada de memoria) revisado por el rol Reviewer.
• Decisiones de arquitectura (ADR): registro permanente en .agents/decisions/, complementario a los planes.
• Skills resueltas por stack via autoskills: npx autoskills escanea el repo, detecta las tecnologias e instala las skills curadas del registro auditado en .agents/skills/.
• Reglas operativas genericas (Git, borrado, alcance, scripts, secretos) identicas en todos los repos.
• Separacion nucleo/stack: el workflow no cambia; cada repo solo adapta su perfil, standards y diseno.
• Instalacion y actualizacion por comando: setup.mjs integra el harness en cualquier proyecto y update trae los cambios del harness sin pisar adaptaciones locales ni planes.
• Compatibilidad multi-agente: la instalacion genera AGENTS.md, CLAUDE.md, .cursorrules y copilot-instructions.md en la raiz apuntando a .agents/.

Estructura

.agents/
|-- AGENTS.md                      # Indice central (perfil del proyecto + sistema)
|-- RULES.md                       # Reglas operativas genericas
|-- CODING_STANDARDS.md            # Convenciones de codigo (adaptar por repo)
|-- DESIGN.md                      # Arquitectura y diseno (adaptar por repo)
|-- WORKFLOW.md                    # Flujo vigente + compuertas + DoD + ciclo de planes
|-- PLANS.md                       # Ownership de planes (memoria persistente)
|-- manifest.json                  # Version y listas del harness (install/update)
|-- plans/                         # Planes del proyecto (memoria persistente)
|-- decisions/                     # Decisiones de arquitectura (ADR, permanentes)
|-- templates/                     # Plantillas: plan.md y adr.md
|-- orchestrator/instructions.md   # Rol del orquestador
|-- subagents/                     # Enrichment, Executor y Reviewer (DoD)
|-- skills/README.md               # Registro de skills + autoskills
`-- bootstrap/INSTALL.md           # Guia de instalacion y actualizacion
scripts/
|-- setup.mjs                      # Instala/actualiza el harness por comando (install/update, --from)
|-- verify.mjs                     # Health check del harness instalado
`-- install.sh                     # Wrapper de setup.mjs con fallback bash
AGENTS.md, CLAUDE.md, .cursorrules, .github/   # Capa de compatibilidad raiz (generada por la instalacion; presente aqui como ejemplo)
package.json                       # Paquete npm con binario: npx agents-setup-sorno

Uso rapido

Comando corto (npx/bunx)

El harness es un paquete npm con binario (agents-setup-sorno). Publicado:

npx agents-setup-sorno ../nombre-del-repo
bunx agents-setup-sorno ../nombre-del-repo

Antes de publicarlo, activarlo localmente con npm link (o bun link) desde este repo, y despues agents-setup-sorno <repo> funciona desde cualquier carpeta.

Instalar en cualquier proyecto (sin copiar/pegar ni clonar)

node scripts/setup.mjs ../nombre-del-repo            # instalar desde este repo
node scripts/setup.mjs ../nombre-del-repo --from https://github.com/<usuario>/<repo>.git
node scripts/setup.mjs                               # usa el directorio actual

Instala el nucleo en .agents/, detecta el stack, rellena el perfil de AGENTS.md, genera la capa raiz de compatibilidad (AGENTS.md, CLAUDE.md, .cursorrules, copilot-instructions.md) y ejecuta autoskills (preview por defecto; --skills para instalar). Registra el origen en .agents/manifest.json.

Traer cambios del harness mas adelante

node scripts/setup.mjs ../nombre-del-repo update               # usa el origen registrado
node scripts/setup.mjs ../nombre-del-repo update --from <url>  # desde otra fuente

Actualiza solo el nucleo; nunca pisa AGENTS.md, CODING_STANDARDS.md, DESIGN.md, planes, decisiones ni skills ya adaptados/creados.

Verificar

node scripts/verify.mjs ../nombre-del-repo   # health check: nucleo, planes, ADRs, compat, skills

Instalacion ligera (fallback)

bash scripts/install.sh ../nombre-del-repo          # usa setup.mjs si hay Node
bash scripts/install.sh ../nombre-del-repo --skills # ademas instala las skills detectadas

Detalle completo en .agents/bootstrap/INSTALL.md.

Fuentes

• Khatarsis: sistema de agentes v3.3 (Vue 3 + TypeScript + Tailwind + Bun), .agents en ../khatarsis/.agents.
• Alytos: sistema de agentes v1.0 (Java 21 + Spring Boot 4 + WebFlux), .agents en ../alytos/.agents.
• autoskills: midudev/autoskills (npx autoskills), registro auditado con manifest SHA-256 y skills-lock.json.

Version: 1.1 (harness generico)