Project Harness 🤖

A LEAN, vendor-agnostic Agent Harness & CLI (v2.2) for software development using the RPI (Research ➔ Plan ➔ Implement) workflow, verification gates, automated documentation, and integrated Agent Skills Management.

🧭 ¿Qué es Project Harness y cómo funciona desde Cero?

Project Harness es la infraestructura liviana que le da a tus asistentes y agentes de IA (Antigravity, Claude Code, Cursor, OpenCode, Windsurf, etc.) un método de trabajo disciplinado y auditable.

🚀 Guía Rápida "Desde Cero" (Zero-to-Hero Workflow)

graph TD
    A["1. Instalar Harness"] --> B["2. harness init"]
    B --> C["3. harness plan new 'mi-tarea'"]
    C --> D["4. Agente Ejecuta RPI (Investiga -> Planifica -> Implementa)"]
    D --> E["5. harness verify (Tests & Lint)"]
    E --> F["6. harness plan finish 'mi-tarea'"]

Paso 1: Instalación (Elegir una opción)

# Opción A: Vía NPX / NPM (Recomendado)
npm install -g project-harness

# Opción B: Vía Installer Script de GitHub
curl -fsSL https://raw.githubusercontent.com/josinhr/project-harness/main/install.sh | bash

Paso 2: Inicializar en tu Proyecto

Navega al directorio de tu proyecto y ejecuta:

harness init --in-repo

Esto crea las carpetas .agents/skills/, .agents/plans/, docs/ y el archivo AGENTS.md con las reglas operativas del proyecto.

Paso 3: Crear un Plan de Trabajo (RPI)

Cuando vayas a desarrollar una nueva característica o refactorización:

harness plan new "autenticacion-jwt"

El agente de IA leerá la plantilla de plan generada, investigará el código existente, desglosará las fases con casillas de verificación (- [ ]), y esperará tu aprobación antes de modificar código.

Paso 4: Ejecución y Verificación

Durante la implementación, puedes consultar el estado del dashboard o verificar que los tests sigan pasando:

harness status   # Muestra progreso de planes, bugs abiertos y skills
harness verify   # Ejecuta linter y suite de pruebas automáticas

Paso 5: Finalizar y Archivar

Una vez completada la tarea y verificada:

harness plan finish "autenticacion-jwt"

El plan se traslada automáticamente a .agents/plans/archive/ y se registra el resumen de cambios (git diff --stat) en docs/CHANGELOG.md.

✨ Características Principales

• Dual-Mode Flexibility:
  • In-Repo Mode: Almacena la documentación (docs/) y planes (.agents/plans/) dentro del repositorio del proyecto.
  • Sidecar Mode: Mantiene el repositorio del proyecto 100% limpio almacenando planes y documentación en una carpeta externa sidecar.
• Gestión Integrada de Skills (harness skill):
  • Lista e instala skills de ingeniería nativas (TDD, Code Review, Security Audit, Agent Browser, Excalidraw Generator) o cualquier skill de la comunidad (skills.sh).
• RPI Workflow (Research ➔ Plan ➔ Implement):
  • Garantiza que los agentes investiguen antes de escribir código y sigan fases con control de calidad.
• Verification Runner (harness verify):
  • Integra comandos configurables de test_command y lint_command en .harnessrc.
• Dashboard & Audit (harness status):
  • Muestra un estado instantáneo del proyecto: rama Git, cambios pendientes, progreso de planes RPI, bugs abiertos por gravedad y skills activas.
• Vendor-Agnostic Open Specification:
  • Compatible con Antigravity, Claude Code, Cursor, OpenCode, Windsurf, y agentes CLI.

🛠️ Matriz de Comandos CLI

| Comando | Descripción | | :--- | :--- | | harness init [--in-repo \| --sidecar <path>] | Inicializa el arnés en el proyecto (modo In-Repo o Sidecar) | | harness update | Actualiza las skills del motor y plantillas a la última versión | | harness plan new <nombre> | Crea un nuevo plan RPI (PLAN-YYYYMMDD-<nombre>.md) | | harness plan us <nombre> | Crea un nuevo plan de User Story (PLAN-US-YYYYMMDD-<nombre>.md) | | harness plan status | Muestra el progreso de tareas de los planes activos | | harness plan finish <nombre> | Marca un plan como completado y lo archiva registrando el changelog | | harness skill list | Lista todas las skills de agente instaladas en el proyecto | | harness skill add <nombre> | Instala una skill nativa o descarga una skill desde la comunidad (skills.sh) | | harness verify | Ejecuta las verificaciones de test y linters configuradas | | harness bug add <titulo> [--severity high\|med\|low] | Registra un nuevo bug en docs/BUGS.md | | harness bug resolve <bug-id> <notas> | Marca un bug como solucionado en docs/BUGS.md | | harness log <mensaje> [--type feature\|fix\|adr] | Registra una entrada manual en docs/CHANGELOG.md | | harness status | Muestra el panel de control (Dashboard) completo del proyecto |

🧠 Agent Skills Incluidas en v2.2

Project Harness incluye una suite nativa de skills de ingeniería en .agents/skills/:

1. test-driven-development: Workflow de desarrollo guiado por pruebas (Red-Green-Refactor agéntico).
2. code-review-and-quality: Inspección de legibilidad, ausencia de logs temporales y cumplimiento de estándares.
3. sec-guardian: Auditoría de seguridad contra filtración de claves, secretos y llamadas inseguras.
4. agent-browser: Automatización e inspección de aplicaciones web en navegador para QA.
5. excalidraw-diagram-generator: Generación de diagramas de arquitectura visuales en formato Excalidraw.
6. frontend-design: Guía de diseño visual de alto nivel, tipografías modernas, dark modes y micro-animaciones.
7. rpi-plan, rpi-implement, rpi-verify: Protocolos del flujo de trabajo RPI.
8. project-onboarding, harness-audit, project-doc: Gestión y auditoría de proyectos.

📄 Guía de Publicación y Contribución

Consulta docs/PUBLISHING.md para ver los detalles sobre cómo publicar nuevas versiones del arnés en NPM y GitHub Releases.

📜 Licencia

Distribuido bajo la licencia MIT.