USEE: Software that assembles like LEGO pieces

An open protocol for creating interchangeable software pieces,
understandable and resilient over time.

Today's software is broken

⚠️

UNNECESSARY COMPLEXITY

Programs that should do one thing, do a hundred.

⏰

ACCELERATED OBSOLESCENCE

Systems that should last decades break in months.

🚧

HIGH ENTRY BARRIER

Tools that should be accessible require years to learn.

πŸ”’

CONTEXT DEPENDENCY

Solutions that should be universal only work in specific places.

"Every project reinvents the wheel. Login, QR, analytics, validations...
over and over again, with the same mistakes."

USEE: Four principles, software that lasts

U

USEFUL

Solves a concrete problem that people have today

S

SIMPLE

Few parts, low complexity, easy to understand

E

ESSENTIAL

Does one thing completely without extras

E

ENDURING

Resilient to changes, works years later

Pieces that speak the same language

Universal communication via plain text

(USEE Text Format)

Terminal
APIs
Web
Legacy
β€’ Each piece receives text β†’ processes β†’ returns text
β€’ No complex dependencies, no mandatory configuration
β€’ Works with any language: JavaScript, Python, Go, Rust, etc.

Anatomy of a USEE piece

File structure:

generate-qr/
β”‚
β”œβ”€β”€ PIECE.usee ← Metadata
β”œβ”€β”€ README.md ← Documentation
β”œβ”€β”€ run ← Entry point
β”œβ”€β”€ INPUT.example
└── OUTPUT.example

Usage example:

# Input
text: https://my-site.com
width: 256
# Output
status: ok
format: png
image: iVBORw0KGgo... (base64)

"One piece = One problem solved. Documented, tested, ready to use."

The power is in composition

extract data

Gets info from a source
β†’

temporal analytics

Calculates metrics by period
β†’

generate report

Produces the final document
./extract-data | ./temporal-analytics | ./generate-report

"Build complex solutions by connecting simple pieces.
No extra code, no configuration, no headaches."

Explore the protocol

πŸ“„

USEE Manifesto

The 4 principles and philosophy of the protocol

Download
πŸ“„

Piece Anatomy

Structure and mandatory files for each piece

Download
πŸ“„

FTU Specification

USEE Text Format β€” complete syntax

Download
πŸ“„

Adapters Guide

How to expose pieces via JSON and HTTP

Download
πŸ“„

Verifier Guide

Automatic piece validation system

Download

Getting started

Learn to run and connect USEE pieces in minutes

πŸ“š

Quick Guide: Running and Connecting USEE Pieces

Everything you need to know to use USEE pieces: UTF format, basic execution, pipe connections, JSON/HTTP adapters, and complete practical examples.

  • USEE Text Format (UTF)
  • How to run a piece
  • Connect pieces with pipes
  • JSON and HTTP adapters
  • Debug and common errors
Download

Integration scripts

Ready-to-use tools and examples

⚑

ejemplo-pipeline.sh

Pipeline connecting analytics-temporal β†’ generar-qr

πŸ”„

transformar-ftu.sh

Utility to transform UTF fields between pieces

Example pieces

Explore real USEE pieces to understand the protocol structure

images v1.0.0

generar-qr

Generates customizable QR codes from text

qr image png
reports v1.0.0

analytics-temporal

Processes visit data in temporal periods with aggregations

analytics statistics metrics

Create USEE pieces with an AI

Copy the context below and paste it into any AI (Claude, ChatGPT, Gemini…). It gives everything needed to design and write a correct USEE piece from scratch.

Prompt for the AI
You are an expert assistant in the USEE protocol. Your task is to help me create a correct USEE piece according to the protocol standard.

## What a USEE piece is
A USEE piece is an atomic program (a CLI) that does ONE single thing: it reads from stdin and writes to stdout using FTU (USEE Text Format, plain text). Errors go to stderr. A piece name is always "verb + noun" (e.g. generate-order-number, calculate-stock, convert-unit).

## The 4 principles (must always hold)
- Useful: solves a concrete problem someone has today.
- Simple: few pieces, low complexity, easy to understand.
- Essential: does one complete thing, no extras or "convenience" features.
- Stable: backward-compatible inputs and outputs. A breaking change = a NEW piece with a new name, never break the existing one.

## Mandatory folder structure (pieces/<name>/)
  PIEZA.usee          ← manifest in FTU
  ejecutar            ← executable entry point (reads stdin, writes stdout)
  ENTRADA.ejemplo     ← example input in FTU
  SALIDA.ejemplo      ← example output in FTU (must be produced literally by ./ejecutar < ENTRADA.ejemplo)
  LEEME.md            ← human documentation; must explicitly state what the piece does NOT do
  pruebas/            ← cases: <name>.entrada + <name>.salida (or .codigo for expected errors)

## FTU format
- "key: value" syntax, one pair per line.
- Comments with #.
- Multi-line blocks with | and 2-space indentation.
- Repeated keys (e.g. linea:, orden:) represent lists/arrays.
- UTF-8 encoding.

## PIEZA.usee manifest (sections, in this order)
  1. # Identity β€” name, version, creator, creation_date
  2. # Description β€” short_description, long_description (| block)
  3. # Classification β€” category, tags
  4. # Capability β€” action, input_description, output_description
  5. # Requirements β€” language, min_language_version, external_dependencies, usee_dependencies
  6. # Commercial β€” cost_per_use, currency, billing_model
  7. # Configuration β€” configuration_options, required_configuration
  8. # Performance β€” average_response_time_ms, max_memory_mb
  9. # Compatibility β€” operating_systems, requires_network, requires_storage
  10. # Additional metadata β€” usee_protocol, license

## Contract of the "ejecutar" executable
- Supports --ayuda/-h and --version/-v.
- If it receives no stdin input (TTY) β†’ error with exit code 2.
- Parses FTU from stdin, validates every field, and on error emits to stderr: estado: error / codigo / mensaje / sugerencia.
- OK output to stdout: estado: ok / <result fields>.
- Exit codes: 0 = ok, 2 = input/validation error, 1 = general/fatal error.
- Optional configuration via environment variables prefixed USEE_<NAME>_<OPTION>. Never mandatory configuration for the common case.
- No external dependencies if possible. For money, use fixed decimals (2), never raw floats.
- The piece does NOT access a database or the network unless its action explicitly requires it: it receives everything through the input so the consumer decides the source.
- Deterministic and composable: it must chain with other pieces (pieceA | pieceB | pieceC).

## Checklist before considering it done
- The purpose fits in "verb + noun".
- PIEZA.usee has all required fields and is valid FTU.
- "ejecutar" reads from stdin and writes FTU to stdout; errors go to stderr.
- ENTRADA.ejemplo produces SALIDA.ejemplo literally.
- LEEME.md documents what the piece does NOT do.
- No unjustified external dependencies; no mandatory configuration.

## What I need from you
1. Ask me what the piece should do if I haven't said so.
2. Propose a "verb + noun" name and check it is atomic (one single thing).
3. Generate the complete files: PIEZA.usee, ejecutar, ENTRADA.ejemplo, SALIDA.ejemplo, LEEME.md and at least one case in pruebas/.
4. Show the command to test it locally and verify that ENTRADA.ejemplo produces SALIDA.ejemplo.

Want the full protocol detail? Check the Manifesto and documentation before publishing your piece.