RedditBot/agents.md

Agent Guidelines & Code Standards

Required orientation and documentation maintenance

Before changing code, read docs/README.md and the documents it routes to for the area you are touching. Treat the source code, tests, generated API reference, and migrations as authoritative when a document disagrees with implementation.

Documentation is part of the change, not a follow-up task:

• Update the relevant file in docs/ whenever behavior, architecture, configuration, data ownership, API contracts, operations, safety boundaries, or development workflow changes.
• Update docs/README.md when adding, renaming, or removing a document.
• Run npm run docs:api after changing src/web/api-catalog.ts; verify with npm run docs:api:check.
• Prefer durable explanations and links to owning source files over copied implementation details, line counts, credentials, production IDs, or other facts likely to drift.
• During final review, explicitly check whether the documentation still describes the code that will be committed.

Do not start, restart, deploy, or otherwise enable live outreach unless the user explicitly authorizes that operational action. A code or documentation request does not imply permission to run the bot. Never expose .env, imported account dumps, cookies, Matrix tokens, dashboard tokens, private media, or database contents.

Refactoring Goal

Refactor code to improve maintainability, testability, and clarity. Break down large components into smaller, single-purpose classes/modules.

Engineering Standards

1. Single Responsibility Principle (SRP)

• Avoid "God Classes" (e.g., massive Service classes that do everything).
• Extract logic into dedicated handlers, managers, or utilities.
• Example: Instead of one BotService handling login, monitoring, and messaging, split into AuthService, MonitorService, and MessagingService.

2. Design Patterns

• Dependency Injection: Pass dependencies via constructors. This makes swapping implementations (e.g., for testing) easier.
• Factory Pattern: Use factories for creating complex objects (e.g., configuring different AI models).
• Strategy Pattern: Good for interchangeable algorithms (e.g., differentsubreddit selection strategies).

3. TypeScript Best Practices

• Strict Typing: No any. Define interfaces/types for all data structures (especially API/Reddit responses).
• Zod Validation: Use zod (already in deps) to validate external data (config files, API responses).
• Async/Await: properly handle promises. Use p-queue or p-retry for rate-limited operations.

4. Testing

• TDD is not required. Agents may implement changes before writing or updating tests.
• Add or update tests when they provide useful coverage for new functionality or bug fixes.
• Tests live in tests/ (mirroring src/ structure) and run via vitest (npm test).
• Prefer behavior-focused tests (inputs → outputs / observable side effects) over tests that pin internal structure.

5. Project Specifics

• Tech Stack: Node.js, TypeScript, Playwright, Express, SQLite, Vitest.
• Directories:
  • src/services/ for business logic.
  • src/web/ for Express server and UI.
  • src/browser/ for Playwright interactions.
  • tests/ for vitest specs, mirroring src/ layout.
• Logging: Use winston for structured logging. Do not use console.log in production code.

Workflow for Agents

1. Orient: Read docs/README.md, the relevant topic documents, and the owning code/tests.
2. Analyze: Before writing code, read the file and understand the context.
3. Plan: Identify what needs to change and check if the change violates SRP.
4. Implement: Make the scoped change. Create new small files when SRP calls for it.
5. Test: Add or update useful tests as appropriate for the change.
6. Document: Update the routed documentation for any changed contract or workflow.
7. Refactor: Tidy the implementation and tests while preserving behavior.
8. Verify: Run the relevant tests, documentation checks, and type checks (npm run build or tsc --noEmit) in proportion to the change.

When Dokploy access is explicitly requested, use the credentials in the ignored .env file. Do not print, copy, commit, or blindly source that file.