AGENTS.md — Project Agent Guide

Project: Telegram Weather Bot Repo root: telegram-weather-bot-pub/ Primary entrypoint: app.py Architecture: Clean Architecture (DDD, DI, event-driven modules) Languages: Python 3.12+, async-first, i18n: ru/en/de License: MIT

Table of Contents

1. Agent System Prompt
2. Mission & Scope
3. Repository Map (Authoritative)
4. Operational Constraints & Budgets
5. Security, Privacy, Compliance
6. Environment & Configuration
7. Coding Standards
8. Internationalization & UX
9. Rate Limiting & Quotas
10. Jobs, Backups & Admin
11. Error Handling & Observability
12. CI/CD & Tooling
13. Makefile Commands Reference
14. Git Conventions
15. Task Execution Protocol
16. Do / Don't
17. Change Placement Decision Tree
18. Machine-Readable Policy
19. Storage Schema Contracts & Migrations
20. i18n Style Guide
21. Pre-PR Checklist
22. Incident Playbooks
23. Observability Contract
24. Common Tasks Cookbook
25. Minimal E2E Smoke (Local)
26. PR Template
27. Issue Template
28. Release & Versioning
29. Glossary
30. Escalation & Non-Goals

Agent System Prompt

• You are the “WeatherBot Project Agent.”
• Objectives: adhere to Clean Architecture boundaries; keep diffs minimal and reversible; maintain multilingual UX (ru/en/de); never leak secrets; keep tests green.
• When unsure: document reasoning briefly in the PR description; propose the smallest viable option.
• PR output style: concise summary listing touched layers and exact commands run.
• Hard constraints:
  • Do not modify storage schemas without a version bump, migration, and tests.
  • Do not commit .env files, tokens, or secrets; avoid logging secrets/PII.
  • Keep per-chat command localization in sync whenever language-facing strings change.
• Acceptance criteria (default):
  • Tests pass and coverage is not reduced on touched files.
  • Admin gating, rate limits, and quotas remain intact.
  • Clean Architecture layering respected; no inward dependency leaks.

Mission & Scope

Mission: Deliver a reliable, privacy-respecting Telegram weather bot with delightful multilingual UX and predictable operational costs.

In scope:

• Telegram handlers, keyboards, onboarding flows, admin tools.
• Weather queries, geocoding, subscriptions, backups, observability.
• Tests, documentation, CI/CD refinements, refactors aligning with architecture.
• Localization improvements for Russian, English, and German.

Out of scope (unless explicitly requested):

• Switching persistence away from JSON without a migration plan.
• Massive architectural rewrites or multi-instance scaling.
• Introducing paid/closed APIs by default.

Repository Map (Authoritative)

weatherbot/
├─ core/            # Value objects, entities, configuration contracts
├─ domain/          # Ports/interfaces, domain services
├─ application/     # Use cases, orchestrators, conversation logic
├─ infrastructure/  # External adapters (HTTP, storage, DI container)
├─ presentation/    # Formatters, i18n resources, keyboards
├─ handlers/        # Telegram command/callback handlers
├─ jobs/            # Scheduled jobs, backup routines
├─ modules/         # Modular bootstrapping & runtime composition
├─ observability/   # Logging, metrics, health endpoints
├─ utils/           # Shared utilities (time, text, validation)
└─ tests/           # Pytest suites across layers

app.py               # Application bootstrap & module assembly
CONFIG.md            # Environment variable reference
ARCHITECTURE.md      # Detailed architecture documentation

Do not move files across layers without a clear architectural justification and accompanying documentation update.

Operational Constraints & Budgets

• Weather provider: Open-Meteo (default, keyless) — shared budget of ~1000 calls/day.
• Geocoding provider: Nominatim — respect rate limits; cache results where reasonable.
• Telegram API: Soft limit 30 msgs/sec globally; python-telegram-bot enforces per-chat throttling.
• Internal throttle: Target ≤5 requests/minute per user for expensive operations.
• Storage: JSON files in data/; maintain backward compatibility and migrate gracefully.

Security, Privacy, Compliance

• Never commit secrets or .env files. Provide .env.*.example only.
• Sensitive data (tokens, chat IDs beyond numeric) must not appear in logs or docs.
• Implement data minimization: store only what is required (language, home location, subscriptions, spam counters).
• /data export and /delete_me flows must remain functional and tested.
• Backups should respect BACKUP_* environment variables; redact secrets from backup archives.

Environment & Configuration

• Mandatory: BOT_TOKEN (Telegram bot token).
• Common optionals: ADMIN_IDS, ADMIN_LANGUAGE, STORAGE_PATH, TIMEZONE, BACKUP_*, WEATHER_API_*, WEATHER_SERVICE_PROVIDER, GEOCODE_SERVICE_PROVIDER.
• Load configuration through DI/container abstractions; never hardcode secrets or rely on implicit globals.
• Local development uses .env.dev; production uses .env.prod. Provide sample entries in docs if changed.

Coding Standards

• Python 3.12+, async-first, minimal blocking I/O.
• Prefer value objects, immutable conversation state, and pure functions in inner layers.
• Formatting: make format (Black + isort). Linting: make lint (flake8).
• Tests: pytest; keep or improve coverage on touched files.
• Layering rules:
  • weatherbot/core and weatherbot/domain cannot import from outer layers.
  • weatherbot/application orchestrates via interfaces only.
  • weatherbot/infrastructure supplies implementations & DI wiring.
  • weatherbot/presentation and weatherbot/handlers own user-facing strings and Telegram API usage.
• Follow type hints; prefer Protocol for ports; avoid Any unless justified.

Internationalization & UX

• Supported languages: ru / en / de.
• User-facing strings live in locales/ (GNU gettext) or presentation helpers; never hardcode in handlers.
• Maintain parity across languages when adding keys; ensure command menus refresh after language changes.
• Keep onboarding accessible: provide language choice, home location guidance, and fallback instructions.

Rate Limiting & Quotas

• Respect per-user throttle and global daily quotas for weather/geocoding providers.
• Use caching and quota tracking utilities in weatherbot.utils and weatherbot.infrastructure where available.
• Notify admins proactively when approaching limits (re-use existing admin notification patterns).

Jobs, Backups & Admin

• Jobs defined in weatherbot/jobs and registered via modules must be idempotent and timezone-aware.
• Backups read BACKUP_* configuration, store artifacts under data/backups/, and must not block the event loop.
• Admin commands gated by ADMIN_IDS; test negative paths to prevent privilege escalation.

Error Handling & Observability

• Structured JSON logging (see weatherbot/observability). No secrets or PII beyond numeric IDs.
• Prefer explicit exception types and user-facing remediation tips.
• Emit metrics for API calls, quota usage, job execution, and error counts.
• Health endpoints and readiness checks should remain lightweight and authenticated if exposed.

CI/CD & Tooling

• Keep GitHub Actions workflows green (mirrors make ci-all).
• Local pre-push checklist:
  • make format
  • make lint
  • make test
  • make coverage
• Docker: make prod-up / make prod-down for local container runs.
• Security scans: make ci-security (bandit) — run when touching security-sensitive code.

Makefile Commands Reference

CRITICAL: Always use Makefile commands instead of direct CLI invocations for consistency and cross-platform compatibility.

Development Workflow

• make help — Show all available commands with descriptions
• make venv — Create virtual environment (.venv/)
• make install — Install all dependencies (prod + dev)
• make run-dev — Run bot locally with .env.dev configuration
• make run-prod — Run bot locally with .env.prod configuration

Testing & Quality Assurance

Use these commands, NOT raw pytest/black/flake8:

• make test — Quick test run (pytest -q)
• make coverage — Run tests with coverage report (generates coverage.xml)
• make coverage-html — Generate HTML coverage report (htmlcov/index.html)
• make test-all — Run coverage + upload to Codecov (requires CODECOV_TOKEN)

Code Quality

Always run before commits:

• make format — Auto-format code (black + isort)
• make format-check — Check formatting without changes
• make lint — Run flake8 linter
• make pre-commit-install — Install pre-commit hooks

CI/CD Validation

Run before pushing release candidates:

• make ci-test — Run all CI tests (black check + isort check + flake8 + pytest with coverage)
• make ci-security — Run security scan (bandit)
• make ci-all — Run complete CI pipeline (ci-test + ci-security)

Docker Operations (Local)

• make prod-up — Start containers with .env.prod (detached mode, with build)
• make prod-logs — Show container logs (tail -f, last 100 lines)
• make prod-restart — Restart running containers
• make prod-down — Stop and remove containers
• make prod-clean — Stop, remove, and clean up containers

Remote Deployment (SSH)

Requires .env.deploy with SSH_HOST, PROJECT_DIR, BRANCH:

• make deploy — Simple deploy (pull + rebuild + up)
• make deploy-clean — Clean deploy (stop → hard reset → rebuild)
• make deploy-logs — Show logs from remote containers
• make deploy-prune — Prune unused Docker images on remote
• make ssh-connect — Connect to remote server via SSH

Local Server Deployment

When already on the server:

• make local-deploy — Deploy on current machine (hard reset to origin)
• make local-logs — Show local container logs

Maintenance

• make clean — Remove __pycache__ and *.pyc files
• make clean-venv — Remove virtual environment
• make freeze — Create requirements.lock from venv
• make backup-now — Manually trigger storage backup

Common Use Cases

1. Initial setup:

make venv
make install
# Create .env.dev with BOT_TOKEN
make run-dev

2. Before committing changes:

make format    # Auto-fix formatting
make lint      # Check code quality
make test      # Verify tests pass

3. Pre-release validation (Release Checklist Phase 2):

make ci-all    # Must pass before pushing RC branch

4. Code review / coverage check:

make coverage-html    # Generate detailed HTML report
# Open htmlcov/index.html in browser

5. Production deployment:

# Remote (via SSH):
make deploy-clean

# Local (on server):
make local-deploy

6. Debugging production:

make deploy-logs    # Remote logs
make local-logs     # Local logs

Anti-Patterns to Avoid

❌ Don't:

• Run pytest directly → Use make test or make coverage
• Run black . directly → Use make format
• Run flake8 directly → Use make lint
• Run docker compose up directly → Use make prod-up or make local-deploy
• Install dependencies with pip install -r requirements.txt → Use make install

✅ Do:

• Always use Makefile commands for consistency
• Check make help when unsure about available commands
• Run make ci-all before pushing release branches
• Use make format before make lint to auto-fix issues

Git Conventions

• Branch naming: feat/*, fix/*, chore/*, docs/*, test/*, refactor/*.
• Commit messages: Conventional Commits (feat: …, fix: …, etc.).
• Keep PRs focused; describe layer impact, UX changes, and test results.
• Avoid large unrelated refactors; split into separate PRs when needed.

Task Execution Protocol

1. Clarify requirements only when absolutely necessary; otherwise infer from docs/tests.
2. Locate the relevant layer(s) using the repository map and architecture guidelines.
3. Design briefly—note significant choices or trade-offs in the PR body.
4. Implement minimal, reversible changes; respect DI patterns and event flows.
5. Test: add/adjust unit, handler, and integration tests as appropriate.
6. Run make format && make lint && make test && make coverage locally before committing.
7. Document behavior changes in README/CONFIG/ARCHITECTURE as needed.
8. Open PR using the provided template; include coverage deltas and manual QA steps.

Default acceptance: tests pass, coverage not reduced, i18n updated, quotas respected, no schema breaks.

Do / Don’t

Do

• Extend functionality via defined interfaces and dependency injection.
• Centralize localization updates and refresh command menus on change.
• Add deterministic tests covering new behavior.
• Cache expensive API calls and respect provider policies.

Don’t

• Commit secrets or environment files.
• Introduce heavy dependencies without discussion.
• Bypass Clean Architecture boundaries or couple handlers to infrastructure details.
• Block the event loop with synchronous I/O in async code paths.

Change Placement Decision Tree

• Pure domain rules / value checks? → weatherbot/core
• Ports, policies, domain contracts? → weatherbot/domain
• Use-case orchestration (no IO specifics)? → weatherbot/application
• External IO, storage, DI wiring? → weatherbot/infrastructure
• Formatting, keyboards, text? → weatherbot/presentation
• Telegram update routing, command handlers? → weatherbot/handlers
• Scheduled tasks, backups? → weatherbot/jobs
• Cross-cutting logging/metrics? → weatherbot/observability

Machine-Readable Policy

Create or update .agent-policy.yml at repo root:

language: "python3.12"
test_commands:
  - "make format"
  - "make lint"
  - "make test"
  - "make coverage"
risk_rules:
  forbid:
    - "commit_env_files"
    - "hardcode_tokens"
    - "blocking_io_in_async"
    - "schema_change_without_migration"
  require:
    - "i18n_update_on_command_change"
    - "admin_gating_on_admin_commands"
    - "quota_checks_on_weather_calls"
coverage:
  min_delta: ">=0"
rate_limits:
  per_user_rpm: 5
  telegram_global_mps: 30
  weather_daily_calls: 1000

Keep this file synchronized with policy changes; update agents if constraints shift.

Storage Schema Contracts & Migrations

• Primary storage: data/storage.json. Changes must remain backward-compatible.
• Maintain a JSON schema similar to the structure documented in ARCHITECTURE.md.
• Each breaking change requires:
  1. Version bump in the stored data.
  2. Migration script data/migrations/mig_<N>_<desc>.py with upgrade()/downgrade().
  3. Tests in tests/test_migrations.py covering happy path, corrupted data, and rollback.
• Never write partial data on failure; use atomic file writes.

i18n Style Guide

• Key format: scope.feature.message (e.g., cmd.start.welcome).
• Placeholder syntax: {city}, {temp}, {time} — handled via .format or gettext substitution.
• Keep sentences concise, sentence case, no trailing spaces.
• Update RU/EN/DE simultaneously; add tests ensuring command menus include new translations.

Pre-PR Checklist

• make format
• make lint
• Tests added/updated (make test)
• Coverage maintained/improved (make coverage)
• i18n strings updated in ru/en/de; command menu refresh verified
• Quotas and throttling respected (tests or reasoning documented)
• No secrets or .env files committed
• Storage schema changes include migration + tests (if applicable)
• Docs updated (README/CONFIG/ARCHITECTURE) when behavior changes

Release Checklist

Follow this step-by-step procedure when preparing a new release:

Phase 1: Branch and Version Bump

1. Create Release Candidate Branch

   git checkout dev
   git pull origin dev
   git checkout -b rc/X.Y.Z
   

2. Update Version Metadata in weatherbot/__version__.py

   • Update __version__ = "X.Y.Z"
   • Update __version_info__ = (X, Y, Z)
   • Update __release_date__ = "DD.MM.YYYY" (current date)
   • Add new release notes to RELEASE_NOTES at the top with 🎉 New in X.Y.Z header
   • Include: bug fixes, new features, breaking changes, improvements
   • Keep previous releases under "Previous Releases" section

3. Sync Version in pyproject.toml

   • Update [project] version = "X.Y.Z"

4. Update Localization Files (locales/{en,ru,de}.json)

   • Change admin_version_whats_new to reference new version:
     • EN: "What's new in version X.Y.Z"
     • RU: "Что нового в версии X.Y.Z"
     • DE: "Neuerungen in Version X.Y.Z"

5. Update README.md

   • Change version badge: [![Version](https://img.shields.io/badge/version-X.Y.Z-blue.svg)]
   • Update "What's New — Version X.Y.Z" section with release highlights
   • Keep highlights concise (3-5 bullet points with emoji)
   • Focus on user-visible improvements and bug fixes

Phase 2: Validation

1. Run Full CI Pipeline

   make ci-all
   

   • All tests pass (282+ tests expected)
   • Coverage maintained at ≥73%
   • No linting errors (black, isort, flake8)
   • Security scan clean (bandit: no issues)

2. Verify Release Metadata Consistency

   • Run pytest tests/test_release_metadata.py -v
   • Ensure all version checks pass:
     • Version matches across __version__.py, pyproject.toml, README.md
     • Localization keys updated in all languages
     • Release date format valid (DD.MM.YYYY)
     • Release date not in future
     • RELEASE_NOTES contains entry for new version

Phase 3: Commit and Push

1. Commit Release Candidate

   git add -A
   git commit -m "chore(release): prepare X.Y.Z RC
   
   Version bump to X.Y.Z with release notes updates.
   
   Highlights:
   - [Feature 1]
   - [Feature 2]
   - [Bug fix]
   
   CI: 282+ tests passing, coverage ≥73%, bandit clean."
   

2. Push Release Branch

   git push origin rc/X.Y.Z
   

Phase 4: Merge to Dev and Verify CI

1. Merge RC to Dev

   git checkout dev
   git pull origin dev
   git merge --no-ff rc/X.Y.Z -m "Merge release candidate X.Y.Z to dev"
   git push origin dev
   

2. Verify GitHub Actions CI Pipeline

   • Navigate to GitHub Actions tab
   • Wait for CI pipeline to complete on dev branch
   • Ensure all checks pass (tests, linting, security)
   • If CI fails, fix issues in dev and cherry-pick to rc/X.Y.Z

Phase 5: Merge to Main and Tag

1. Merge Dev to Main

   git checkout main
   git pull origin main
   git merge --no-ff dev -m "Release X.Y.Z"
   git push origin main
   

2. Create Git Tag

   git tag -a vX.Y.Z -m "Release X.Y.Z
   
   [Copy release notes highlights here]"
   git push origin vX.Y.Z
   

Phase 6: Post-Release

1. GitHub Release (Optional)

   • Create GitHub release from tag vX.Y.Z
   • Copy release notes from RELEASE_NOTES
   • Attach any binaries or deployment artifacts if needed

2. Deployment

   • Deploy to production environment
   • Verify bot responds with new version in /admin_version command
   • Monitor logs for errors during initial rollout

3. Cleanup

   • Delete release candidate branch (optional):

     git branch -d rc/X.Y.Z
     git push origin --delete rc/X.Y.Z
     

Release Type Guidelines

Patch Release (X.Y.Z where Z increments):

• Bug fixes only
• No new features
• Backward compatible

Minor Release (X.Y.Z where Y increments):

• New features
• Improvements
• Backward compatible
• May include bug fixes

Major Release (X.Y.Z where X increments):

• Breaking changes
• Major architectural changes
• Requires migration guide
• Update RELEASE_NOTES with ⚠️ BREAKING CHANGES section

Common Release Pitfalls

❌ Don't:

• Skip CI validation
• Forget to update localization in all languages
• Commit version bumps directly to main or dev
• Merge RC directly to main without testing in dev first
• Tag before merging to main
• Use generic commit messages

✅ Do:

• Always create an RC branch
• Merge RC → dev → verify CI → main
• Run full test suite before pushing
• Keep release notes user-friendly
• Update all version references atomically
• Test metadata consistency with test_release_metadata.py
• Wait for GitHub Actions to pass on dev before merging to main

Incident Playbooks

Weather Provider Outage

• Return friendly fallback message; log level=WARNING with context.
• Retry with capped exponential backoff (≤2 retries).
• Notify admins once; avoid spam.

Geocoding Throttling

• Apply exponential backoff; encourage user to retry later.
• Cache last successful result per query to reduce load.

Storage Corruption

• Quarantine corrupted file (storage.json.broken.<timestamp>).
• Restore latest backup; notify admins; run in degraded mode if necessary until restored.

Observability Contract

• Logs: JSON fields (ts, level, event, user_id?, chat_id?, lang, cmd, duration_ms, ok, err?). No secrets.
• Metrics: weather calls, geocode calls, quota remaining, subscriptions sent, rate-limit hits, job durations.
• Tracing/health: keep lightweight; expose only non-sensitive data.

Common Tasks Cookbook

Add a new user command (e.g., /hourly):

1. Define request/response models in weatherbot/domain (ports + DTOs).
2. Implement use case in weatherbot/application and wire through modules.
3. Add presenter/formatter in weatherbot/presentation.
4. Implement handler in weatherbot/handlers and register via modules/command.py.
5. Update localization strings and command menus (ru/en/de).
6. Add tests: use case, presenter snapshot, handler integration.

Add a background job (e.g., subscription digest):

1. Implement job in weatherbot/jobs using async-friendly patterns.
2. Register in the Jobs module; ensure schedule respects TIMEZONE.
3. Cover with tests (scheduling, quota respect, failure handling).

Swap or extend weather provider:

1. Implement provider adapter in weatherbot/infrastructure/weather/ behind existing interface.
2. Update DI to allow selection via WEATHER_SERVICE_PROVIDER env.
3. Add tests using provider overrides (weatherbot.infrastructure.container helpers) — no monkeypatching globals.

Minimal E2E Smoke (Local)

1. Create .env.dev with BOT_TOKEN=<test token> and run make run-dev.
2. /start → language menu renders.
3. /sethome <city> → stored; /home returns localized weather summary.
4. /subscribe → schedules daily job; verify logs for job queue entry.
5. /language → switch to de; command menu updates accordingly.

PR Template

### Summary
(What changed and why—succinct.)

### Layer Impact
- Core:    [ ] none / [ ] touched (details)
- Domain:  [ ] none / [ ] interfaces changed
- App:     [ ] none / [ ] new use case / [ ] modified
- Infra:   [ ] none / [ ] new client / [ ] DI changes
- Present: [ ] none / [ ] i18n/formatting changes
- Handlers:[ ] none / [ ] commands affected
- Jobs:    [ ] none / [ ] scheduler changes

### i18n
- [ ] ru updated
- [ ] en updated
- [ ] de updated
- Per-chat menu refreshed on change: [ ] yes

### Quotas & Rate Limiting
- [ ] respected
- [ ] near-limit messaging for users/admins added (if relevant)

### Testing
- [ ] unit tests
- [ ] handler tests
Coverage: before → after: X% → Y%

### Docs
- [ ] README / ARCHITECTURE / CONFIG updated (if needed)

### Risks & Rollback
(Top risks + quick rollback strategy.)

Issue Template

### Task
(Concise change request.)

### Acceptance Criteria
- [ ] Expected behavior described
- [ ] i18n updated (ru/en/de)
- [ ] Command menus refreshed (if applicable)
- [ ] Quotas & throttling respected
- [ ] Tests pass; coverage not reduced

### Notes
(Layers involved, related tickets, references.)

Release & Versioning

• Update weatherbot/__version__.py and accompanying release notes when introducing user-visible changes.
• Keep README “What’s New” aligned with latest tag.
• Follow semantic versioning unless product requirements dictate otherwise.

Glossary

• Home Location: {lat, lon, label} stored per user for quick forecasts and subscriptions.
• Subscription: Scheduled push delivering weather updates at configured local time.
• Quota: Shared 24h budget for weather provider calls.
• Command Menu: Localized Telegram command list configured via Bot API (setMyCommands).
• Modules: Bootstrap components in weatherbot/modules that register handlers, jobs, and services.

Escalation & Non-Goals

• If a change risks breaking architectural boundaries or quotas, pause and surface a design note before implementation.
• Avoid stateful singletons, cross-layer imports, or schema changes without migration.
• Non-goals: multi-instance scaling, database migrations, paid API integration—unless explicitly requested by stakeholders.

End of AGENTS.md