📋 Instructions — Briefing System & Progressive Disclosure

Objetivo: Crear un archivo de briefing que un agente pueda consumir en <30 segundos y entender qué proyecto es, qué stack usa y qué convenciones debe respetar.

Regla de oro: Máximo 80 líneas. Si superas las 120, el agente ignora la mitad. El AGENTS.md es un mapa que apunta a docs detalladas, no la fuente única de toda la información.

Estructura recomendada:

• Identidad: nombre del proyecto, propósito en una línea
• Stack: lenguajes, frameworks, herramientas clave
• Convenciones: estilo de código, estructura de commits, patrones de diseño
• How to use: comandos esenciales (install, test, build)
• Definition of Done: checklist mínimo antes de considerar una tarea terminada

Anti-patrones:

• ❌ Instrucciones contradictorias entre AGENTS.md y los archivos de código
• ❌ Documentar API endpoints en AGENTS.md en lugar de docs/API.md
• ❌ Dejar información obsoleta sin fecha de última actualización

Objetivo: Organizar la documentación en niveles de profundidad para que el agente solo cargue lo que necesita.

Jerarquía de 4 niveles:

• Nivel 1 — Visión: ROADMAP.md, ARCHITECTURE.md (qué se construye y por qué)
• Nivel 2 — Diseño: DESIGN.md, ADRs (cómo se construye, decisiones técnicas)
• Nivel 3 — Planes: PLANS.md, TASK.md, milestones (qué se está construyendo ahora)
• Nivel 4 — Especificaciones: product-specs/, api-specs/, detalles de implementación

Startup workflow del agente:

1. Leer AGENTS.md (30s)
2. Identificar tarea activa en TASK.md
3. Consultar docs/ de nivel correspondiente
4. Consultar ROADMAP.md solo si necesita contexto de prioridades

Cada nivel apunta al siguiente con links explícitos. El agente nunca debe tener que adivinar dónde buscar.

Objetivo: Mantener una fuente única de verdad sobre el rumbo del proyecto para evitar que el agente se desvíe hacia features futuras.

Estructura:

• Fases numeradas (Fase 1: Fundación, Fase 2: Core, Fase 3: Expansión)
• Cada fase tiene hitos con fechas estimadas o porcentajes de progreso
• Sección "No en scope" para ideas explícitamente descartadas
• Última fecha de actualización visible

# 🗺️ Roadmap

> Visión general del proyecto, fases e hitos.
> Última actualización: 2026-05-10

## Fase 1: Fundación
- [x] Repo inicial con harness básico
- [x] AGENTS.md y docs/ estructurados
- [ ] CI/CD pipeline (en progreso)

## Fase 2: Core
- [ ] Feature A: autenticación
- [ ] Feature B: dashboard principal

## Fase 3: Expansión
- [ ] Integraciones externas
- [ ] Optimización de rendimiento

## 🚫 No en scope (v1.0)
- Mobile app nativa
- Soporte offline completo

Este es un AGENTS.md que obtendría un score ≥90% en harness scan . --json:

# 🤖 Mi Proyecto — Agent Briefing

## Identidad
Eres un agente trabajando en **MiProyecto**, un sitio estático
que enseña harness engineering a agentes de IA.

## Stack
- **Frontend:** HTML5, CSS3 vanilla, JavaScript vanilla
- **Design:** Linear Dark
- **Hosting:** GitHub Pages

## Convenciones
- **CSS:** clases Utility-first en `css/style.css`
- **JS:** módulos en `js/shared.js` (sin framework)
- **Commits:** `feat:`, `fix:`, `docs:`, `chore:`

## How Agents Should Use This Repo
1. `pip install -e .`
2. `harness scan . --json` → diagnóstico
3. `harness fix .` → generar archivos faltantes

## Definition of Done
- Código según spec
- Sin regresiones visuales
- Documentado en AGENTS.md si aplica
- Comiteado con mensaje descriptivo