USEE: Software que se ensambla como piezas de LEGO

Un protocolo abierto para crear piezas de software intercambiables,
comprensibles y resilientes al paso del tiempo.

El software actual está enfermo

⚠️

COMPLEJIDAD INNECESARIA

Programas que deberían hacer una cosa, hacen cien.

OBSOLESCENCIA ACELERADA

Sistemas que deberían durar décadas se rompen en meses.

🚧

BARRERA DE ENTRADA ALTA

Herramientas que deberían ser accesibles requieren años.

🔒

DEPENDENCIA DE CONTEXTO

Soluciones que deberían ser universales solo funcionan en lugares específicos.

"Cada proyecto reinventa la rueda. Login, QR, analytics, validaciones...
una y otra vez, con los mismos errores."

USEE: Cuatro principios, software que perdura

U

ÚTIL

Resuelve un problema concreto que personas tienen hoy

S

SIMPLE

Pocas piezas, poca complejidad, fácil de entender

E

ESENCIAL

Hace una sola cosa completamente sin extra

E

ESTABLE

Resiliente a cambios, funciona años después

Piezas que hablan el mismo idioma

Comunicación universal via texto plano

(Formato de Texto USEE)

Terminal
APIs
Web
Legado
Cada pieza recibe texto → procesa → devuelve texto
Sin dependencias complejas, sin configuración obligatoria
Funciona con cualquier lenguaje: JavaScript, Python, Go, Rust, etc.

Anatomía de una pieza USEE

Estructura de archivos:

generar-qr/
├── PIEZA.usee ← Metadatos
├── LEEME.md ← Documentación
├── ejecutar ← Punto entrada
├── ENTRADA.ejemplo
└── SALIDA.ejemplo

Ejemplo de uso:

# Entrada
texto: https://mi-sitio.com
ancho: 256
# Salida
estado: ok
formato: png
imagen: iVBORw0KGgo... (base64)

"Una pieza = Un problema resuelto. Documentada, probada, lista para usar."

El poder está en la composición

extraer datos

Obtiene info de una fuente

analytics temporal

Calcula métricas por período

generar reporte

Produce el documento final
./extraer-datos | ./analytics-temporal | ./generar-reporte

"Arma soluciones complejas conectando piezas simples.
Sin código extra, sin configuración, sin dolor de cabeza."

Explora el protocolo

📄

Manifiesto USEE

Los 4 principios y filosofía del protocolo

Descargar
📄

Anatomía de Pieza

Estructura y archivos obligatorios de cada pieza

Descargar
📄

Especificación FTU

Formato de Texto USEE - sintaxis completa

Descargar
📄

Guía de Adaptadores

Cómo exponer piezas vía JSON y HTTP

Descargar
📄

Guía del Verificador

Sistema de validación automática de piezas

Descargar

Primeros pasos

Aprende a ejecutar y conectar piezas USEE en minutos

📚

Guía Rápida: Ejecutar y Unir Piezas USEE

Todo lo que necesitas saber para usar piezas USEE: formato FTU, ejecución básica, conexión con pipes, adaptadores JSON/HTTP, y ejemplos prácticos completos.

  • Formato de Texto USEE (FTU)
  • Cómo ejecutar una pieza
  • Conectar piezas con pipes
  • Adaptadores JSON y HTTP
  • Debug y errores comunes
Descargar

Scripts de integración

Herramientas y ejemplos listos para usar

ejemplo-pipeline.sh

Pipeline que conecta analytics-temporal → generar-qr

🔄

transformar-ftu.sh

Utilidad para transformar campos FTU entre piezas

Piezas de ejemplo

Explora piezas USEE reales para entender la estructura del protocolo

imagenes v1.0.0

generar-qr

Genera códigos QR personalizables a partir de texto

qr imagen png
reportes v1.0.0

analytics-temporal

Procesa datos de visitas en períodos temporales con agregaciones

analytics estadisticas metricas

Crea piezas USEE con ayuda de una IA

Copia el siguiente contexto y pégalo en cualquier IA (Claude, ChatGPT, Gemini…). Le da todo lo necesario para diseñar y escribir una pieza USEE correcta desde cero.

Prompt para la IA
Eres un asistente experto en el protocolo USEE. Tu tarea es ayudarme a crear una pieza USEE correcta según el estándar del protocolo.

## Qué es una pieza USEE
Una pieza USEE es un programa atómico (un CLI) que hace UNA sola cosa: lee de stdin y escribe a stdout usando FTU (Formato de Texto USEE, texto plano). Los errores van a stderr. El nombre de una pieza es siempre "verbo + sustantivo" (ej: generar-numero-orden, calcular-stock, convertir-unidad-insumo).

## Los 4 principios (deben cumplirse siempre)
- Útil: resuelve un problema concreto que alguien tiene hoy.
- Simple: pocas piezas, poca complejidad, fácil de entender.
- Esencial: hace una sola cosa completa, sin extras ni "features de conveniencia".
- Estable: entradas y salidas retrocompatibles. Un cambio incompatible = una pieza NUEVA con otro nombre, nunca romper la existente.

## Estructura de carpeta obligatoria (piezas/<nombre>/)
  PIEZA.usee          ← manifiesto en FTU
  ejecutar            ← punto de entrada ejecutable (lee stdin, escribe stdout)
  ENTRADA.ejemplo     ← ejemplo de entrada en FTU
  SALIDA.ejemplo      ← ejemplo de salida en FTU (debe producirse literalmente al correr ./ejecutar < ENTRADA.ejemplo)
  LEEME.md            ← documentación humana; debe decir explícitamente lo que la pieza NO hace
  pruebas/            ← casos: <nombre>.entrada + <nombre>.salida (o .codigo para errores esperados)

## Formato FTU
- Sintaxis "clave: valor", un par por línea.
- Comentarios con #.
- Bloques multilínea con | e indentación de 2 espacios.
- Claves repetidas (p.ej. linea:, orden:) representan listas/arrays.
- Codificación UTF-8.

## Manifiesto PIEZA.usee (secciones, en este orden)
  1. # Identidad — nombre, version, creador, fecha_creacion
  2. # Descripción — descripcion_corta, descripcion_larga (bloque |)
  3. # Clasificación — categoria, etiquetas
  4. # Capacidad — accion, entrada_descripcion, salida_descripcion
  5. # Requisitos — lenguaje, version_lenguaje_minima, dependencias_externas, dependencias_usee
  6. # Comercial — costo_por_uso, moneda, modelo_cobro
  7. # Configuración — opciones_configuracion, configuracion_requerida
  8. # Rendimiento — tiempo_respuesta_promedio_ms, memoria_maxima_mb
  9. # Compatibilidad — sistemas_operativos, requiere_red, requiere_almacenamiento
  10. # Metadatos adicionales — protocolo_usee, licencia

## Contrato del ejecutable "ejecutar"
- Soporta --ayuda/-h y --version/-v.
- Si no recibe entrada por stdin (TTY) → error con exit code 2.
- Parsea FTU de stdin, valida cada campo, y ante error emite a stderr: estado: error / codigo / mensaje / sugerencia.
- Salida OK a stdout: estado: ok / <campos de resultado>.
- Exit codes: 0 = ok, 2 = error de entrada/validación, 1 = error general/fatal.
- Configuración opcional vía variables de entorno con prefijo USEE_<NOMBRE>_<OPCION>. Nunca configuración obligatoria para el caso de uso común.
- Sin dependencias externas si es posible. Para dinero, decimales fijos (2), nunca float crudo.
- La pieza NO accede a base de datos ni a la red salvo que su acción lo requiera explícitamente: recibe todo por la entrada para que el consumidor decida la fuente.
- Determinista y componible: debe encadenarse con otras piezas (piezaA | piezaB | piezaC).

## Checklist antes de darla por terminada
- El propósito cabe en "verbo + sustantivo".
- PIEZA.usee tiene todos los campos requeridos y es FTU válido.
- "ejecutar" lee de stdin y escribe FTU a stdout; los errores van a stderr.
- ENTRADA.ejemplo produce literalmente SALIDA.ejemplo.
- LEEME.md documenta lo que la pieza NO hace.
- Sin dependencias externas injustificadas; sin configuración obligatoria.

## Qué necesito de ti
1. Pregúntame qué debe hacer la pieza si no lo he dicho.
2. Propón un nombre "verbo + sustantivo" y valida que sea atómica (una sola cosa).
3. Genera los archivos completos: PIEZA.usee, ejecutar, ENTRADA.ejemplo, SALIDA.ejemplo, LEEME.md y al menos un caso en pruebas/.
4. Muestra el comando para probarla localmente y verifica que ENTRADA.ejemplo produce SALIDA.ejemplo.

¿Quieres el detalle completo del protocolo? Consulta el Manifiesto y la documentación antes de publicar tu pieza.