Structured Vibe Coding

Tu proyecto, con
cualquier modelo de IA.

Comandos y roles model-agnostic que se instalan en cualquier proyecto. El agente lee las instrucciones y trabaja con las herramientas de Handoff — sin importar qué modelo estés usando.

Claude GPT-4o Gemini Mistral
Ver en GitHub Descargar extensión →
Cómo funciona

Tres pasos para empezar

Sin configuración, sin lock-in. El blueprint se instala en tu proyecto y el agente lo usa directamente.

1
Abre Handoff en VS Code (Cmd+Shift+H) y haz clic en Plugin en la barra del agente. Si no tienes la extensión → descárgala en VS Code Marketplace
2
Selecciona Handoff: Install Blueprint desde la paleta (Cmd+Shift+P). El blueprint se instala en .handoff/commands/ y .handoff/roles/. O manualmente: git clone https://github.com/handoffcl/handoff-blueprint
3
Haz clic en Plugin → elige un comando → el agente lo ejecuta con el modelo activo. Funciona con Claude, GPT-4o, Gemini, Mistral — lo que tengas configurado en Handoff
Extensión v0.9.0

El agente trabaja con visibilidad total

La extensión Handoff muestra el trabajo del agente en tiempo real — igual que Claude Code, pero con cualquier modelo.

✓
Historial intercalado — los pasos de herramientas y el texto del LLM aparecen en orden cronológico. Sin separaciones artificiales. Leer archivos, ejecutar comandos, escribir código — todo en el mismo flujo
✓
Outputs visibles en historial — los resultados de cada herramienta (OUT / ERR) quedan registrados en el chat. Al hacer handoff entre modelos, el nuevo LLM ve exactamente qué ejecutó el anterior
✓
Paste de capturas — Cmd+V en la barra de conversación pega screenshots directamente. Muéstrale al agente un error de UI, un log o cualquier imagen
✓
Auto-approve — modo autónomo que ejecuta herramientas sin confirmación para tareas de larga duración. Activar en la barra del agente; las operaciones destructivas siempre piden confirmación
Archivos clave

Los tres archivos que mantienen al agente alineado

Cada uno cumple una función distinta. Sin ellos, el agente improvisa, mezcla decisiones y deja deuda invisible.

WORKING-AGREEMENT.md NUEVO
La regla central: spec antes de código. Antes de tocar un archivo, el agente analiza, sumariza, propone y espera tu OK.
Qué cubre
Todo cambio: features, bug fixes, refactors. Excepción: solo preguntas y cambios cosméticos en lote.
Qué se gana
Control sobre la IA antes de que toque archivos. Validas intent antes de gastar tokens. Cada decisión queda en un spec que sirve a futuras sesiones.
Sin él
El agente improvisa. Mezcla decisiones, inventa convenciones, deja deuda que aparece semanas después cuando alguien pregunta "¿por qué está así?" y nadie sabe.
HANDOFF.md
El reglamento del proyecto que el agente lee al iniciar cada sesión.
Qué cubre
Reglas operativas: convenciones de código, quality gate, estructura de carpetas, qué NO hacer, roles disponibles. Apunta a CONTEXT.md y WORKING-AGREEMENT.md.
Qué se gana
Cada sesión arranca con las reglas del proyecto cargadas. El agente conoce tu naming convention, qué tests correr, qué archivos están off-limits.
Sin él
Re-explicas el setup cada sesión. El agente inventa convenciones que contradicen el resto del repo. Las inconsistencias se acumulan archivo por archivo.
CONTEXT.md
Memoria viva del proyecto, auto-actualizada después de cada commit.
Qué cubre
Estado actual: qué se entregó, qué está en progreso, qué se decidió y por qué, qué NO tocar. Recent Changes auto-actualizado por el git post-commit hook.
Qué se gana
Memoria continua entre sesiones. La sesión 50 empieza con la historia condensada de las 49 anteriores. El agente no re-abre decisiones cerradas ni rompe lo que se hizo a propósito.
Sin él
Cada sesión empieza de cero. Pagas 10-15 minutos (y tokens) re-explicando qué es el proyecto. El agente sugiere lo que ya descartaste. Decisiones cerradas se re-abren por accidente.
Metodologías que combina

No inventamos nada nuevo

El blueprint es la implementación automática de tres metodologías que la industria ya validó. Lo nuevo es que la IA las pone en práctica desde tu idea, en lugar de pedirte que las escribas tú.

Practice
GitHub Spec-Kit
Specs antes del código · constitution · clarify · plan. Aquí: los genera la IA desde tu idea, no los escribes tú.
Practice
Spec-Driven Development (SDD)
Un spec por feature ANTES de codear. Aquí: docs/specs/ contiene un .md por funcionalidad con su status.
Practice
Arquitectura modular + DDD lite
Módulos con contratos claros entre sí. Aquí: docs/modular/ define los contratos, docs/architecture/ el system design.
Comandos

Lo que puede hacer el agente

Cada comando es un archivo .md con instrucciones en lenguaje natural. Puedes modificarlos o agregar los tuyos.

bootstrap-app
Crea un proyecto completo desde una idea — estructura, docs, CI/CD y contexto vivo. El proyecto se crea en ~/proyectos/.
architecture-review
Evalúa límites de módulos, flujo de datos, acoplamiento y restricciones de escalabilidad con recomendaciones priorizadas.
code-quality
Detecta código muerto, brechas de tests, inconsistencias de tipos y problemas de legibilidad adaptado al stack real del proyecto.
security-review
OWASP Top 10, autenticación, secretos expuestos, inyección y hardening general. Reporta severidad y fix concreto por hallazgo.
Bootstrap

De idea a app en un solo comando

Ejecuta /bootstrap-app y el agente genera toda la estructura, los documentos y los quality gates desde una sola pregunta. Tú aportas la idea; el agente decide el stack y se encarga del andamiaje.

Agente Cuéntame tu idea: ¿qué hace, para quién es y qué puede hacer un usuario en ella?
Tú Un SaaS para gestionar turnos de veterinarias, con recordatorios automáticos por WhatsApp.
Agente Usaré SvelteKit + FastAPI porque necesitas Python para la integración con WhatsApp. ¿Seguimos?
Tú Sí.
Agente Creando ~/proyectos/vet-turnos/ con toda la estructura, specs y docs…
Lo que crea automáticamente
HANDOFF.md Reglas del agente, stack real, roles por área, qué NO hacer
CONTEXT.md Estado actual, arquitectura, módulos clave — se auto-actualiza tras cada commit
docs/architecture/ Arquitectura de alto nivel, contratos de API, decisiones técnicas (System Design)
docs/specs/ Spec-Driven Development — un spec por feature, escrito ANTES de codear
Makefile + quality gate ruff · mypy · pytest (o npm run check) — debe pasar antes de cada commit
GitHub CI + git hooks Workflow de CI en cada push + hook post-commit que actualiza los living docs
El flujo de desarrollo que impone el blueprint
Spec primero Antes de escribir una línea de código, el agente genera docs/specs/<feature>.md con el contrato de la feature. Sin spec, no hay código.
Rol correcto por área El agente activa el rol adecuado antes de trabajar: Senior Backend para APIs, Senior Frontend para UI, Security Review para auditorías.
Quality gate en verde make quality debe pasar antes de cada commit. El agente lo ejecuta y no avanza si falla.
Docs vivos post-commit El git hook actualiza automáticamente CONTEXT.md, el plan y las specs después de cada commit. El agente siempre tiene contexto fresco.
Roles

Expertise especializado por área

Los roles son personas que el modelo adopta antes de trabajar en un área. Se activan automáticamente según el contexto — el agente lee HANDOFF.md para saber cuándo usarlos.

senior-backend
Senior Backend Engineer APIs, bases de datos, performance, seguridad OWASP, patrones de arquitectura
senior-frontend
Senior Frontend Engineer Componentes, Core Web Vitals, accesibilidad, patrones de UI, formularios
senior-design
Senior UX/UI Designer Flujos de usuario, jerarquía visual, conversión, sistemas de diseño, mobile first
security-review
Senior Security Engineer Mentalidad de atacante, OWASP Top 10, crypto, infraestructura, hallazgos con prioridad
Ecosistema

Blueprints disponibles

Elige el blueprint según tu herramienta de IA. Todos comparten la misma filosofía — solo cambia el formato de los comandos.

Oficial
Disponible
Handoff Blueprint Model-agnostic — funciona con Claude, GPT, Gemini y Mistral dentro de la extensión Handoff
Claude GPT Gemini Mistral
handoffcl/handoff-blueprint →
Claude Code
Disponible
AI App Blueprint Optimizado para Claude Code — comandos /slash, skills con allowed-tools y hooks de sesión
Claude Code
handoffcl/ai-app-blueprint →
GPT
Próximamente
GPT Blueprint Optimizado para ChatGPT y la API de OpenAI con Custom GPTs e instrucciones del sistema
GPT-4o
Próximamente
Instalación

Empieza en segundos

No hay build step ni configuración. Solo instala y usa.

1
Instala la extensión Handoff en VS Code VS Code Marketplace · handoff.cl/vscode · requiere VS Code 1.85+ y tus propias API keys
2
Abre un proyecto en VS Code y ejecuta Cmd+Shift+P → Handoff: Install Blueprint Clona el blueprint y copia .handoff/commands/ y .handoff/roles/ en tu proyecto
3
Haz clic en Plugin en la barra del agente o presiona Cmd+Shift+K Aparece el selector con los comandos disponibles — elige y el agente lo ejecuta
4
Personaliza o agrega comandos en .handoff/commands/ — cualquier .md aparece en el selector El agente sigue cualquier instrucción en lenguaje natural usando sus herramientas locales
Harness

Infraestructura que envuelve al agente

scripts/update_docs.py no es solo un script — es el harness del flujo de desarrollo con IA. Un harness ejecuta acciones automáticamente antes y después de cada sesión del agente, sin intervención manual.

git commit
→
pre-commit hook → ⚠️ avisa si src/ cambió sin spec
post-commit hook → update_docs.py
Sesión del agente termina
→
onSessionEnd (.handoff/settings.json) → update_docs.py
scripts/watch.py (opcional) → update_docs.py
Últimos cambios — commits clasificados en CONTEXT.md
Specs pendientes — archivos sin spec detectados automáticamente
Working Agreement (activo) — regla visible en cada sesión

Ingeniería de contexto — rotación progresiva

Un CONTEXT.md de 600 líneas desperdicia tokens y entierra lo que importa. El harness rota el archivo automáticamente cuando supera el umbral configurado.

Activo
CONTEXT.md
Estado actual. Lean, < 250 líneas. El agente lo lee primero en cada sesión.
→
Supera umbral
rotate()
update_docs.py archiva CONTEXT.md y reinicia el archivo con solo el estado actual.
→
Archivo
CONTEXT-1.md
Historial comprimido de la fase anterior. El agente lo consulta solo si la tarea lo requiere.

Configurable en .blueprint → CONTEXT_ROTATE_LINES=250