Context Organizer

context-organizer

Skill imperativa para mantener la Capa 1 (Los 5 Fantásticos) de documentación viva en la raíz del repo. Tu deber: que el contexto indexable nunca mienta.

Principios imperativos

• Boy Scout obligatorio: si detectás gap, contradicción o desalineación entre los 5 .md y el código, DETENÉ la tarea principal, corregí el .md y recién después continuá.
• Crear si falta: si README.md, AGENTS.md, DESIGN.md o ADR.md no existen, CREALOS ya con la plantilla mínima. BEHAVIOR.md se genera automáticamente ejecutando los tests (ver motor abajo).
• Actualizar proactivo sin consultar: ante un trigger (ver matriz), actualizá el .md correspondiente sin preguntar al usuario. Es tu responsabilidad, no una sugerencia.
• Síntesis y curación: condensá, deduplicá, ordená por módulo, eliminá ruido y entradas obsoletas. Prosa breve, jerárquica, alta densidad por token.
• Leer antes de codear: consultá los .md relevantes antes de inferir comportamiento, estilo o arquitectura desde el código fuente.

Matriz de los 5 archivos

Triggers proactivos (acción → archivo)

• Modificar/crear test verde → BEHAVIOR.md
• Crear/refactor componente UI, token visual, patrón de estado → DESIGN.md
• Usuario dice "decidimos", "vamos a usar X en lugar de Y", "regla:", "ADR:", "de ahora en más" → ADR.md (append) + posible DESIGN.md/AGENTS.md
• Cambio de runtime, framework, env var, script npm de bootstrap → README.md
• Nueva skill, tool, restricción, política de ejecución, regla de enrutamiento → AGENTS.md

Si un cambio dispara varios triggers, actualizá todos los .md afectados en la misma intervención.

Plantillas e inicialización

Inicializar un repo nuevo

bash skills/context-organizer/scripts/init-repo.sh

Este script:

• Copia README.md, AGENTS.md, DESIGN.md, ADR.md desde scripts/templates/ al root si no existen
• Crea .context/ para test-results.json
• Instala hook pre-commit si Husky está disponible

Plantillas

Las plantillas residen en scripts/templates/:

• README.md — propósito, stack, env, bootstrap
• AGENTS.md — matriz de consulta, restricciones operativas
• DESIGN.md — tokens, componentes, estados
• ADR.md — formato de decision records

Editá las plantillas según tu proyecto después de inicializar.

BEHAVIOR.md

NO crear manualmente. Se genera automáticamente al ejecutar la suite de tests y el script de compilación (ver motor abajo). Formato esperado:

# BEHAVIOR.md
> Generado por context-organizer. No editar a mano.
## Módulo: Auth
- DEBE permitir login con credenciales válidas y verificadas.
- NO DEBE permitir acceso con password incorrecto (retorna 401).
- DEBE bloquear cuenta 15 min tras 5 fallos consecutivos.
## Módulo: Pagos
- DEBE emitir `order.paid` a SQS tras confirmación de pasarela.
- DEBE revertir reserva de stock si la tarjeta es rechazada.

Motor BEHAVIOR.md (automatizado)

Flujo determinista:

[cambio en tests] → [suite en verde + reporter JSON] → [parse] → [síntesis semántica] → [BEHAVIOR.md]

Comandos de reporter

• Jest: jest --json --outputFile=.context/test-results.json
• Vitest: vitest run --reporter=json --outputFile=.context/test-results.json

Script de compilación

Ejecutá:

node skills/context-organizer/scripts/compile-behavior.mjs

(requiere .context/test-results.json generado por el reporter; ver scripts/README.md para detalles)

Hook pre-commit

Instalá:

cp skills/context-organizer/scripts/pre-commit.sh .husky/pre-commit
chmod +x .husky/pre-commit

(ver scripts/README.md para requisitos y flujo)

Descripciones ambiguas

Si encontrás it("should work"), it("test 4"), it("foo") o similares:

1. Leé el expect/assert del test.
2. Reescribí la descripción con la intención real (should <verbo> <objeto> when <condición>).
3. Recompilá BEHAVIOR.md.

No tolerés descripciones vacías de semántica: son deuda documental.

Reglas de curación

• Deduplicar: si dos bullets dicen lo mismo con palabras distintas, fusionalos.
• Agrupar: ordená por módulo/dominio, no por archivo de test.
• Podar: eliminá entradas que ya no aparecen en la suite verde.
• Compactar DESIGN.md: si un patrón se repite ≥2 veces, abstraelo a componente o token y documentalo.
• ADR.md es append-only: nunca borres ni reescribas un ADR. Para revertir, agregá uno nuevo con Status: Accepted, supersedes ADR-NNN y marcá el viejo como Superseded by ADR-MMM.
• AGENTS.md debe estar al día con las skills realmente disponibles: si agregás/quitás una, actualizalo en el mismo commit.

Anti-patrones (NO hacer)

• ❌ Inferir comportamiento leyendo código fuente cuando BEHAVIOR.md existe y está fresco.
• ❌ Crear componentes ad-hoc sin chequear DESIGN.md.
• ❌ Proponer refactors o cambios de stack sin leer ADR.md (riesgo de loop infinito).
• ❌ Editar BEHAVIOR.md a mano: siempre vía script.
• ❌ Sobrescribir o borrar un ADR.
• ❌ Preguntar al usuario "¿actualizo el .md?" cuando hay trigger claro: actualizá y avisá brevemente en el resumen.

Checklist mental por intervención

1. ¿Existen README.md, AGENTS.md, DESIGN.md, ADR.md? Si no, creá los faltantes. BEHAVIOR.md se genera vía script al correr tests.
2. ¿Leí los relevantes a la tarea? (matriz de enrutamiento de AGENTS.md)
3. ¿Mi cambio dispara algún trigger? Actualizá los .md afectados.
4. ¿Tests modificados? Corré el motor y regenerá BEHAVIOR.md.
5. ¿Quedaron entradas duplicadas u obsoletas? Curá.