⚡ tele-harness

Agentic Telegram Bot & Mini App Engineering Harness

A universal agentic framework, sub-agent suite, and skill harness for building, scaling, and maintaining Telegram Bots and Telegram Mini Apps.

Quick Install • Sub-Agents • Skills • Templates • Commands • Architecture

---

📌 Overview

tele-harness equips autonomous coding agents (Antigravity, Claude Code, Cursor) with Telegram domain specialization. Instead of generic code output, tele-harness enforces state machine isolation, 64-byte callback payloads, HMAC signature verification for Mini Apps, rate limit safeguards, and persistent memory across development sprints.

Built around the standardized .agents/ directory structure, it works across multiple agent runtimes while offering ready-to-run starter templates for Python, TypeScript, and Go.

---

🚀 Quick Install

One-Line Setup

Run the installer inside your bot project directory:

curl -fsSL https://raw.githubusercontent.com/0xOpCode/tele-harness/main/install.sh | bash

The script interactively prompts for your target agent directory (.agents/, .claude/, or symlinked) and optional starter template.

Non-Interactive Setup

# Install to .agents/ with Python aiogram3 starter template
curl -fsSL https://raw.githubusercontent.com/0xOpCode/tele-harness/main/install.sh | bash -s -- --target .agents --template python-aiogram3

# Install to .claude/ for Claude Code
curl -fsSL https://raw.githubusercontent.com/0xOpCode/tele-harness/main/install.sh | bash -s -- --target .claude

---

🤖 Sub-Agents

tele-harness defines three domain-specialized personas in .agents/agents/:

Sub-Agent	Role	Responsibilities	Tools
tg-architect	System Architect	Router topology, database schemas, FSM state graphs, and webhook vs polling strategies.	Read, Grep, Bash, WebFetch
tg-ux-engineer	Interface Engineer	Inline keyboard pagination, Mini App frontends, theme integration, and 64-byte payload limits.	Read, Grep, Edit
tg-sec-auditor	Security Auditor	HMAC initData verification, secret leakage prevention, rate limiting, and RBAC admin gating.	Read, Grep, Bash

---

⚡ Skills Catalog

Specialized prompt and execution modules located in .agents/skills/:

Skill	Directory	Purpose
🎛️ Navigation Menus	keyboard-navigator/	Architects nested menus, breadcrumbs (« Back), dynamic pagination, and 64-byte callback packing.
✍️ Bot Copy & Stop-Slop	tg-copywriter/	Mobile viewport limits (5 lines), slop elimination, active voice, and BotFather command naming.
🗄️ Schema Design	create-db-schema/	Models user records, BigInt Telegram IDs, and session persistence tables.
🔄 State Machines	fsm-builder/	Scaffolds conversation state groups, transitions, and Redis session backends.
🌍 Localization	i18n-builder/	Configures translation dictionaries, language switchers, and locale middleware.
📱 Mini Apps	mini-app-builder/	Scaffolds WebApp SDK bindings, viewport scaling, and constant-time HMAC validation.
💳 Payments	payment-gateway-setup/	Integrates Telegram Stars (XTR), pre-checkout queries, and provider invoices.
🌐 Webhooks	setup-webhook/	Configures secret token headers, reverse proxies, and async update endpoints.
🧭 Code Navigation	tg-api-navigator/	Fast regex routing patterns to find handlers and middleware across codebases.

---

📦 Starter Templates

tele-harness includes minimal production starter templates in templates/:

1. python-aiogram3

• Modern aiogram 3.x async dispatcher.
• Modular Router pattern (handlers/start.py, handlers/echo.py).
• Inline keyboard builder utilities.
• Redis and in-memory FSM storage ready.
• Strict Pydantic settings and .env configuration.

2. nodejs-grammy

• Full TypeScript configuration with strict checks.
• @grammyjs/conversations integration for linear async flows.
• Session middleware with type-safe context augmentation.

3. go-telebot

• Telebot v3 architecture for low-memory environments.
• Context middleware logging and command handlers.
• Single binary build output.

---

⌨️ Workflow Commands

Control the development lifecycle using slash commands defined in .agents/commands/:

Command	Usage	Description
/init-bot	/init-bot python/aiogram3	Binds the target framework across all skills, agent definitions, and manifests.
/add-flow	/add-flow "User referral onboarding"	Dispatches tg-architect and tg-ux-engineer to scaffold a multi-step conversation.
/save-state	/save-state	Dumps current sprint status, modified files, and blockers to .agents/memory/temp_context.md.
/resume	/resume	Reloads context from previous sprint handoff to prevent token waste.

---

📂 Architecture Overview

tele-harness/
├── install.sh                  # Interactive and CLI installer
├── AGENTS.md                   # Universal agent guidelines & protocol
├── CLAUDE.md                   # Claude Code runtime entrypoint
├── .cursorrules                # Cursor & Windsurf rules
├── templates/                  # Production boilerplate templates
│   ├── python-aiogram3/        # aiogram 3 Router + FSM starter
│   ├── nodejs-grammy/          # grammY TypeScript starter
│   └── go-telebot/             # Go telebot starter
└── .agents/                    # Core harness directory
    ├── settings.json           # Runtime permissions & token limits
    ├── agents/                 # Specialized sub-agent personas
    │   ├── tg-architect.md     # Architecture & DB modeling
    │   ├── tg-ux-engineer.md   # Keyboards & Mini App UI
    │   └── tg-sec-auditor.md   # HMAC & token security
    ├── skills/                 # Task-specific protocols
    │   ├── keyboard-navigator/ # Nested menus & dynamic pagination
    │   ├── tg-copywriter/      # Slop-free mobile copy & commands
    │   ├── create-db-schema/   # Database schema definitions
    │   ├── fsm-builder/        # Multi-step state machine flows
    │   ├── i18n-builder/       # Translation pipelines
    │   ├── mini-app-builder/   # Telegram Mini App bindings
    │   ├── payment-gateway-setup/ # Stars & invoice integration
    │   ├── setup-webhook/      # Secret token & reverse proxy
    │   └── tg-api-navigator/   # Search patterns across stacks
    ├── commands/               # Orchestration slash commands
    │   ├── init-bot.md
    │   ├── add-flow.md
    │   ├── save-state.md
    │   └── resume.md
    ├── hooks/
    │   └── hooks.json          # Pre/Post session lifecycle triggers
    └── memory/
        ├── master_protocol.md  # Engineering constraints
        ├── bot_manifest.md     # Project stack and routing map
        └── progress.md         # Sprint milestone tracker

---

🛡️ Cross-Agent Compatibility

tele-harness is runtime-agnostic:

• Antigravity CLI / Native Agent Tools: Uses .agents/skills/ and AGENTS.md directly.
• Claude Code: Uses .claude symlink and CLAUDE.md entrypoint.
• Cursor & Windsurf: Uses .cursorrules for architectural enforcement during IDE generation.

---

📄 License

Distributed under the MIT License. See LICENSE for details.

---

👨‍💻 Maintainer

Maintained by 0xOpCode.