# USEE Manifesto ## A Protocol for the Development of Interchangeable Software **Version 1.0** --- ## Statement of Intent Today's software suffers from a disease: unnecessary complexity. Programs that should do one thing do a hundred. Systems that should last decades become obsolete in months. Tools that should be accessible require years of study to master. Solutions that should be universal only work in specific contexts. USEE is born as a response to this disease. We propose a protocol for creating software pieces that are interchangeable across projects, understandable by humans, and resilient to the passage of time. Pieces that anyone can assemble to build solutions without needing to code, yet that any programmer can extend and adapt. We are not trying to reinvent software. We are trying to remember what software was meant to be. --- ## The Four Principles ### USEFUL > *What is offered is what is received.* A USEE piece exists to solve a concrete problem. Not to impress with its sophistication, not to showcase technical skill, not to anticipate imaginary needs. **Criteria for usefulness:** - The piece solves a problem that real people have today - The problem can be explained in a single sentence - The solution can be demonstrated in less than a minute - The user gets value from the very first use, with no mandatory setup **Questions every piece must answer with "yes":** - Would someone use this tomorrow if it were available today? - Is the benefit self-evident without needing an explanation? - Does it do what it says it does, with no surprises? **What we reject:** - Speculative functionality ("just in case someone needs it") - Features that require extensive documentation to justify their existence - Solutions in search of a problem --- ### SIMPLE > *Few pieces, little complexity, easy to understand, easy to integrate.* Simplicity is not the absence of capability. It is the presence of clarity. A simple piece is one that a person can fully understand, predict its behavior, and trust its results. **Criteria for simplicity:** - The piece can be fully explained on a single page - A new programmer can understand the code in one hour - A non-technical user can configure it by choosing from predefined options - The piece has a single conceptual input and a single conceptual output **Simplicity metrics:** - Fewer than 10 configuration options for basic use - Fewer than 3 mandatory external dependencies - Fewer than 1000 lines of code for the core functionality - Zero configuration required for the most common use case **What we reject:** - Unnecessary abstractions - Mandatory configuration before first use - Dependencies the user did not explicitly choose - Documentation that requires documentation to be understood --- ### ESSENTIAL > *Fundamental, elemental, necessary. Without it, nothing works; with it, nothing is superfluous.* A USEE piece does one thing. It does it completely. It does nothing else. If a Login piece lets you sign in, that is all it does. It does not register users. It does not recover passwords. It does not manage profiles. Those are other pieces. **Criteria for essentiality:** - The piece has a single reason to exist - That reason can be expressed with a verb and a noun (e.g., "authenticate user", "send email", "generate report") - Removing any functionality would break its core purpose - Adding any functionality would turn it into two pieces **The name test:** If you cannot name the piece with a single clear word or concept, it probably does too much. - ✓ "Login" — clear, does one thing - ✓ "Registration" — clear, does one thing - ✗ "UserManager" — ambiguous, probably does several things - ✗ "CompleteAuthenticationSystem" — definitely does too much **What we reject:** - "Convenient" functionality that is not central to the purpose - Integrations included "because users expect them" - Features added to compete with other solutions - The temptation of "while we're at it, let's also add..." --- ### ENDURING > *Resilient to change, continues to work as the years go by.* A USEE piece that works today must work tomorrow. And next year. And a decade from now. Endurance is not a secondary goal; it is a fundamental requirement. Modern software owes its users a debt: it promises them solutions and delivers them dependencies. Updates that break. Frameworks that die. APIs that change. USEE rejects this debt. **Criteria for endurance:** - The piece does not rely on technologies with short life cycles - Updates are always backward compatible - Communication uses protocols that have proven their permanence (plain text, HTTP, stdin/stdout) - The code can run without a connection to mandatory external services **Endurance commitments:** - Valid inputs in version 1.0 will remain valid in every future version - Outputs will keep their structure; new fields are added, never removed or renamed - Existing behaviors do not change; new behaviors are opt-in - If a piece must change in an incompatible way, it becomes a new piece with a new name **The 30-year rule:** Before choosing a technology, ask: did it exist 15 years ago? Will it still exist 15 years from now? - ✓ Plain text — 50+ years old, will keep existing - ✓ HTTP — 30+ years old, will keep existing - ✓ JSON — 20+ years old, will probably keep existing - ✗ [The JavaScript framework of the moment] — 3 years old, probably not **What we reject:** - Dependencies on services that may disappear - Proprietary or undocumented formats - Updates that force the user to change their code - The excuse of "it's time to modernize" --- ## The Communication Doctrine USEE pieces communicate through structured text. This choice is not technical; it is philosophical. Text is universal. Text is readable. Text endures. ### Communication Hierarchy **Level 1 — Mandatory: USEE Text via stdin/stdout** Every USEE piece must be able to receive instructions via standard input and emit results via standard output, using the USEE Text Format (FTU — *Formato de Texto USEE*, kept as the normative acronym to avoid conflict with UTF-8). ``` # Input user: john@example.com password: secret123 # Output status: ok session: abc123 ``` **Level 2 — Recommended: Output separation** Pieces should use stdout for results and stderr for errors. **Level 3 — Optional: JSON Adapter** Pieces may offer JSON input/output for integrations that require it. **Level 4 — Optional: HTTP Adapter** Pieces may expose themselves as network services for web contexts. ### Why stdin/stdout is mandatory - It has worked on every operating system since 1970 - It works in every programming language - It requires no libraries, frameworks, or dependencies - It enables natural composition: `piece1 | piece2 | piece3` - It is testable with basic tools: `echo "input" | piece` - It is debuggable by humans without special tools --- ## Creator Commitments By publishing a piece under the USEE protocol, the creator commits to: ### 1. Truth in the description The piece does exactly what its description says. No more, no less. If the description says "sends emails", the piece sends emails. It does not schedule them, does not template them, does not analyze them. It only sends them. ### 2. Transparency in dependencies Every external dependency is documented and justified. The user knows, before installing, which other pieces or services will be required. ### 3. Respect for stability Updates do not break existing installations. If a change is incompatible, it is released as a new piece. ### 4. Honesty about limitations The documentation includes what the piece does NOT do. Limits are as important as capabilities. ### 5. Source code availability The source code is available for inspection. The user can verify what the piece does before trusting it. --- ## User Commitments By using USEE pieces, the user accepts that: ### 1. Pieces are tools, not magical solutions Pieces do what they say. The responsibility of combining them correctly belongs to the user. ### 2. Simplicity has limits A simple piece may not cover complex use cases. This is intentional, not a flaw. ### 3. Cost reflects value Pieces have a per-use cost that compensates their creators. This cost is part of a sustainable ecosystem. ### 4. Feedback improves the ecosystem Reporting issues, suggesting improvements, and rating pieces contributes to the quality of the marketplace. --- ## The USEE Ecosystem USEE is not just a technical protocol. It is an ecosystem where: ### Creators - Build atomic pieces that solve specific problems - Receive compensation proportional to the use of their pieces - Maintain their pieces following the protocol commitments ### Users - Assemble pieces to build solutions without coding - Choose between predefined options or custom configurations - Pay for the value they receive ### The Marketplace - Certifies that pieces comply with the protocol through automated tests - Measures and publishes quality metrics (uptime, stability, ease of use) - Facilitates discovery and trust between creators and users ### The Platform - Provides optional centralized services (storage, authentication, analytics) - Tracks usage to compensate creators - Maintains the infrastructure that makes the ecosystem possible --- ## USEE Quality Metrics Every piece in the marketplace is evaluated on: | Metric | Description | |---------|-------------| | **Operational time** | Months since publication without incompatible changes | | **Change frequency** | Average updates per month (less is better for stability) | | **Availability** | Uptime percentage for pieces with a service component | | **Integration time** | Average minutes for a new user to get it running | | **Cost per use** | Price per call/operation | | **Satisfaction** | Average user rating | | **Documentation** | Completeness and clarity of the documentation | --- ## What USEE Is Not ### It is not a framework USEE does not tell you how to structure your application. It gives you pieces; you decide how to combine them. ### It is not a language USEE works with any programming language. Pieces communicate with text, not with code. ### It is not a closed platform The protocol is open. Anyone can create USEE pieces. The marketplace is one implementation of the ecosystem, not the ecosystem itself. ### It is not a solution for everything USEE is ideal for discrete, well-defined functionality. Systems that require deep integration and complex shared state may not benefit from the atomic approach. --- ## Invitation If you believe software should be simpler, more stable, and more accessible, we invite you to: - **Use** USEE pieces in your projects - **Create** pieces that honor the protocol - **Contribute** to the definition and evolution of the standard Software can be better. USEE is our proposal for how. --- *This manifesto is a living document. It will evolve alongside the ecosystem, but its fundamental principles — Useful, Simple, Essential, Enduring — will remain constant.* --- **USEE**: Because software should work for people, not the other way around.