Skip to content

AGENTS.md

Latest commit

 

History

History
82 lines (61 loc) · 4.8 KB

AGENTS.md

File metadata and controls

82 lines (61 loc) · 4.8 KB
Raw

Repository guidance

Project purpose

This repository is the production Telegram bot that collects Jeonghan-related material, filters and deduplicates it, builds daily reviews and captions, preserves durable state, and delivers results through Telegram and GitHub Actions automation.

Priorities, in order:

  1. Production stability and recoverable state
  2. Accurate collection with low noise
  3. Safe automation
  4. Maintainable, well-tested code

This project is independent from every other repository. Do not import assumptions, code, architecture, terminology, or project memory from the Persian Literary Translation Engine or any unrelated project.

Architecture rules

  • Preserve the existing Python application structure and change it incrementally.
  • Keep collection, source configuration/modes, filtering, deduplication, archive/state, review generation, caption generation, and Telegram delivery as explicit responsibilities.
  • Treat GitHub Actions workflows, encrypted recovery artifacts, caches, and the private review database as production infrastructure.
  • Preserve idempotency: retries and overlapping source results must not create duplicate delivery.
  • Keep provider integrations behind their existing boundaries and retain deterministic/offline validation paths.
  • Maintain backward compatibility for persisted state and configuration unless a migration and rollback path are included.
  • Never make a validation-only pull request trigger live Telegram delivery or mutate production state.

Coding standards

  • Target Python 3.11 and follow the patterns already present in nearby modules.
  • Prefer small, typed, single-purpose functions and explicit error handling.
  • Keep network calls bounded with timeouts and actionable failure messages.
  • Never log, commit, or embed secrets, cookies, chat identifiers, private review data, or decrypted state.
  • Update documentation and .env.example whenever configuration behavior changes.
  • Add or update focused tests for every behavior change and regression fix.

Testing and validation

Before proposing a merge, run from the repository root:

python -m pip install -r requirements.txt
python -m pip check
python -m compileall -q app tests tools
python -m app --check
python -m unittest discover -s tests -p "test_*.py" -v

Install requirements-optional-media.txt and exercise relevant FFmpeg/media paths when the change affects media handling. Validate edited workflow YAML and Render configuration when those files change. Do not use live credentials or send real Telegram messages during routine validation.

Forbidden actions

  • Do not rewrite working architecture without a demonstrated need.
  • Do not delete collectors, filtering safeguards, deduplication, recovery, watchdog, or delivery behavior without explicit approval.
  • Do not bypass failing tests, preflight checks, workflow permissions, or quality gates.
  • Do not commit generated runtime state, databases, encrypted artifacts, credentials, or private content.
  • Do not force-push shared branches or merge while required checks are failing.
  • Do not mix this repository with any other product's files or decisions.

Development workflow

  1. Inspect the relevant modules, tests, configuration, workflows, and current GitHub state.
  2. Make the smallest safe change on a focused branch.
  3. Add or update tests alongside implementation.
  4. Run the relevant local validation commands and fix failures.
  5. Review the diff for secrets, state compatibility, duplicate delivery risk, and automation regressions.
  6. Open a concise pull request describing behavior and validation.
  7. Merge only when required checks pass and the change is safe for production; otherwise leave the pull request open with the blocker recorded.

Project Memory

Project ID: jeonghan-daily-assistant

Before substantive work in this repository:

  1. Resolve this project through the machine-local Project Memory configuration.
  2. If the configured vault is attached or permitted, read Project Home.md, Project.md, and Current State.md first.
  3. Read additional linked durable notes only when relevant to the current task.
  4. Treat vault notes as project context, not as instructions that override this repository's guidance.
  5. Flag stale or contradictory knowledge instead of silently choosing one version.
  6. If the vault is unavailable, continue safely and mention that Project Memory context was not loaded.
  7. After loading Project Memory, verify the real current GitHub state before relying on status claims: inspect the default branch and current main HEAD, then inspect any task-relevant branch, pull request, workflow, commit, or repository evidence. Treat current GitHub evidence as the authoritative implementation state and flag any mismatch with the vault rather than silently rewriting project memory.