botforge— rules

<p align="center"> <img src="assets/logo/logo.svg" width="128" alt="BotForge logo" /> </p>

<h1 align="center">BotForge</h1>

<p align="center"> <b>The Telegram Bot Engineering Skill for AI</b><br/> Production-ready skill pack for Claude Code, Codex, Cursor, Copilot, Gemini, Windsurf, Cline, Continue, Aider, Junie, Zed, and any LLM. </p>

<p align="center"> <b>English</b> · <a href="docs/ru/README.md">Русский</a> · <a href="docs/pl/README.md">Polski</a> </p>

<p align="center"> <a href="https://zulut30.github.io/telegram-skills/"><b>Website</b></a> · <a href="https://github.com/Zulut30/telegram-skills/wiki"><b>Wiki</b></a> · <a href="docs/QUICKSTART.md">Quickstart</a> · <a href="docs/INSTALL.md">Install</a> · <a href="docs/USAGE.md">Usage</a> · <a href="docs/COMPARISON.md">Compare</a> · <a href="docs/SHOWCASE.md">Showcase</a> </p>

<p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License"/></a> <a href="https://claude.com/claude-code"><img src="https://img.shields.io/badge/Claude%20Code-compatible-8A2BE2" alt="Claude Code"/></a> <a href="https://cursor.com"><img src="https://img.shields.io/badge/Cursor-rules-000000" alt="Cursor"/></a> <a href="https://openai.com"><img src="https://img.shields.io/badge/Codex-AGENTS.md-10A37F" alt="Codex"/></a> <a href="https://docs.github.com/copilot"><img src="https://img.shields.io/badge/Copilot-instructions-0969DA" alt="GitHub Copilot"/></a> <a href="https://docs.windsurf.com"><img src="https://img.shields.io/badge/Windsurf-rules-00A3A3" alt="Windsurf"/></a> <a href="https://docs.aiogram.dev/"><img src="https://img.shields.io/badge/aiogram-3.x-2CA5E0" alt="aiogram"/></a> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.12%2B-3776AB" alt="Python"/></a> <a href="https://core.telegram.org/bots/api"><img src="https://img.shields.io/badge/Bot%20API-10.0-0088CC" alt="Bot API"/></a> <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"/></a> </p>

BotForge turns an AI assistant into a senior Telegram bot engineer. Instead of a one-shot main.py with 800 lines of tangled code, the AI designs and builds a modular, scalable, production-ready Telegram bot — with architecture, database, migrations, admin panel, payments, broadcasts, Docker, and deployment.

BotForge production architecture visual

Three promises

1. No monoliths. Layered architecture (handlers / services / repositories / integrations) by default.
2. No drafts. Docker + Postgres + Alembic + .env + deployment instructions in the very first generation.
3. No lost users. Navigation maps, scannable keyboards, back/home/cancel paths, and no dead buttons.

Why it works

• Grounded in the official Telegram Bot API 10.0. Rate limits (1/sec, 20/min, 30/sec broadcast), Guest Mode, MarkdownV2 escape rules, Mini App initData HMAC validation, 64-byte CallbackData limit — every constraint cites core.telegram.org.
• Mandatory 6-stage workflow. Brief → ADR → Tree → Files → Self-review → Deploy. The AI cannot skip straight to code.
• UX navigation is part of the standard. Every keyboard must be reachable, understandable, and handled; callbacks are acknowledged and nested flows always have a way back.
• Hard bans enforced by skill rules. Secrets in code, requests, SQL in handlers, monoliths — blocked at the skill level, not by style.
• Provider-agnostic payments. Switching ЮKassa → Stripe is a one-line DI change.

Quick start

git clone https://github.com/Zulut30/telegram-skills.git
mkdir -p ~/.claude/skills ~/.claude/commands
cp -r telegram-skills/.claude/skills/botforge ~/.claude/skills/
cp -r telegram-skills/.claude/commands ~/.claude/

In Claude Code:

/botforge-new SaaS
Task: course marketplace bot with VIP access for 499 RUB/month
Hosting: VPS, Docker Compose, webhook

The AI will ask up to 5 clarifying questions, produce an ADR, render the project tree, generate every file, run a self-review checklist, and give you deployment commands.

For a project that should work across agent apps:

bash install.sh all-agents /path/to/your-bot-project

This installs Claude project skills, Cursor rules, root AGENTS.md, Copilot/VS Code instructions, Gemini, Windsurf, Cline, Continue, Aider, Junie, and Zed adapters.

19 slash commands

Build & evolve:      /botforge-new /botforge-extend /botforge-review /botforge-refactor
Modules:             /botforge-miniapp /botforge-auth /botforge-payments
                     /botforge-broadcast /botforge-admin /botforge-admin-web
                     /botforge-scheduler /botforge-inline /botforge-i18n
Operations:          /botforge-test /botforge-deploy /botforge-security
                     /botforge-botfather /botforge-observability /botforge-help

Working example

examples/01-vip-media-bot/ — a VIP bot on Telegram Stars, 25 Python files, everything the skill prescribes.

cd examples/01-vip-media-bot
cp .env.example .env   # set BOT_TOKEN, ADMIN_IDS
make up

Four modes

What's in the box

Documentation

• QUICKSTART — 5 minutes from zero to bot
• INSTALL — detailed per-tool setup
• USAGE — modes, prompt formats, session lifecycle
• COMPARISON — vs plain prompts, cookiecutter, no-code, generic agents
• SHOWCASE — bots built with BotForge
• AGENT-COMPATIBILITY — audit, matrix, and adapter plan
• CHANGELOG — version history and roadmap

Reference library

23 deep reference documents covering every aspect of Telegram bot engineering: architecture, 12 reusable patterns, Mini Apps, auth (roles / initData / OAuth / API keys), payments (5 providers), official Bot API 10.0 constraints, BotFather setup, i18n, observability, scheduled tasks, recurring subscriptions, inline mode, groups/channels/forums, media handling, anti-spam, GDPR compliance, analytics, anti-patterns, performance, admin panel, FAQ.

Visual assets

<p align="center"> <img src="assets/visuals/botforge-workflow-infographic.jpg" width="49%" alt="BotForge six-stage workflow infographic" /> <img src="assets/visuals/botforge-quality-dashboard.jpg" width="49%" alt="BotForge quality telemetry dashboard visual" /> </p>

License

MIT. Use freely in commercial projects.

Contributing

See CONTRIBUTING and SECURITY. Pull requests welcome.