Contribute — TLL OS

Ways to Contribute

📦

Build a Module

Create a first-party module following the Module Contract. Modules ship with routes, services, models, events, commands, and tests. Publish for any TLL OS application to install.

🔌

Build a Plugin

Create a runtime-installable plugin. Plugins extend applications without modifying core. Follow the Plugin Contract with manifest, lifecycle, dependencies, and permissions.

🔗

Build an Adapter

Connect a new external system. Shopify, WordPress, Medusa, Laravel, any REST/GraphQL/SDK system. Each Adapter needs a Compatibility Manifest declaring support levels and migration cost.

📜

Propose a TEP

Found a bug? Want a new contract? Have an idea for the protocol? Submit a TLL Evolution Proposal. Auto-test, AI review, human review, merge.

🐛

Fix Bugs

Found something broken? Open an issue, then submit a fix. Every bug fix needs a regression test. AI Agents can discover and fix bugs through the TEP process.

📝

Improve Docs

Documentation is critical for both humans and AI Agents. Improve guides, add examples, clarify contracts. Agent-readable docs are especially valuable.

TEP — TLL Evolution Protocol

How protocol and runtime changes get proposed, reviewed, and merged.

TEP Flow

1. DISCOVER
   Agent or human finds: bug / optimization / new capability / protocol gap

2. PROPOSE
   Create Evolution Proposal:
   - Problem description
   - Impact analysis (based on Application Graph)
   - ChangeSet (protocol + runtime + tests + docs)
   - Auto-generated tests

3. VALIDATE
   - Run all existing tests
   - Compatibility verification
   - AI Review (contract consistency, architecture boundaries, security, performance)

4. REVIEW
   - GitHub PR created
   - Maintainer review (human)
   - Community discussion

5. MERGE
   - Approved changes merged
   - Protocol / Runtime release

6. RELEASE
   - Protocol version: 2.x (stable)
   - Runtime version: 0.x (evolving)

TEP Types

Type	Description	Review Required
`feature`	New feature or capability	AI + Human
`bugfix`	Bug fix	AI + Human (simple: AI only)
`breaking`	Breaking change	AI + Human + RFC + migration guide
`deprecation`	Deprecate contract/feature	AI + Human + replacement plan
`refactor`	Refactor (no behavior change)	AI (Human optional)

Core Principle: Don't Reinvent the Wheel

TLL OS unifies standards, not implementations. Before building something new, check if a mature solution exists.

What TLL OS Does NOT Build

HTTP Server → use Fastify
ORM → use Drizzle
Validation → use Zod
Queue → use BullMQ / NATS
Logging → use Pino
Testing → use Vitest
Cache → use Redis
Database → use PostgreSQL
Ecommerce → use Shopify / Medusa / Shopware
CMS → use WordPress / Strapi
ERP → use Odoo / ERPNext

What TLL OS Builds

Application Graph (shared understanding)
Module Contract (standard extension)
Plugin Contract (runtime extension)
Adapter Contract (connect external systems)
Projection (Graph → any output)
BuildTarget (multi-platform)
Capability Registry (discoverability)
Agent Contract (AI-native development)
Tool Contract (agent-callable capabilities)
Evolution Protocol (community-driven)
Permission Contract (secure agent ops)

Development Setup

terminal

# Fork and clone
git clone https://github.com/aliquanhou/tll-os.git
cd tll-os

# Install
npm install

# Verify
npx tsc --noEmit
→ No errors

# Run examples
npx tsx examples/hello-tll-agent/agent.ts
npx tsx examples/autonomous-task-manager/agent.ts

# Create a branch
git checkout -b feature/my-new-module

# Make changes, then run all tests
npx tsc --noEmit
npx tsx examples/hello-tll-agent/agent.ts
npx tsx examples/autonomous-task-manager/agent.ts

# Commit and push
git add .
git commit -m "feat: add my new module"
git push origin feature/my-new-module

# Open a Pull Request

Start Contributing

Join the community. Build the future of AI-native application development.

GitHub Repository Open Issues TEP for Agents

Contribute to TLL OS