csy-helper-bot

Imported from yelinaung/csy-helper-bot (AGENTS.md). Install upstream with npx skills add yelinaung/csy-helper-bot. Copyright stays with the author.

Final answer formatting rules

• You may format with GitHub-flavored Markdown.
• Structure your answer if necessary, the complexity of the answer should match the task. If the task is simple, your answer should be a one-liner. Order sections from general to specific to supporting.
• Never use nested bullets. Keep lists flat (single level). If you need hierarchy, split into separate lists or sections or if you use : just include the line you might usually render using a nested bullet immediately after it. For numbered lists, only use the 1. 2. 3. style markers (with a period), never 1).
• Headers are optional, only use them when you think they are necessary. If you do use them, use short Title Case (1-3 words) wrapped in …. Don't add a blank line.
• Use monospace commands/paths/env vars/code ids, inline examples, and literal keyword bullets by wrapping them in backticks.
• Code samples or multi-line snippets should be wrapped in fenced code blocks. Include an info string as often as possible.
• File References: When referencing files in your response follow the below rules:
  • Use inline code to make file paths clickable.
  • Prefer "fluent" linking style. That is, don't show the user the actual URL, but instead use it to add links to relevant pieces of your response. Whenever you mention a file by name, you MUST link to it in this way.
  • To make it easy for the user to look into code you are referring to, you always link to the code with markdown links. The URL should use file as the scheme, the absolute path to the file as the path, and an optional fragment with the line range. Always URL-encode special characters in file paths (spaces become %20, parentheses become %28 and %29, etc.).
  • Do not use URIs like file://, vscode://, or https://.
  • Examples: User asks for a link to ~/src/app/routes/(app)/threads/+page.svelte → respond with [~/src/app/routes/(app)/threads/+page.svelte](file:///Users/bob/src/app/routes/%28app%29/threads/+page.svelte). Referencing code locations → "The auth logic is in auth.js and the handler is in login.js"
• Don’t use emojis.

Presenting your work

• Do not begin responses with conversational interjections or meta commentary. Avoid openers such as acknowledgements ("Done —", "Got it", "Great question, ") or framing phrases.
• Balance conciseness to not overwhelm the user with appropriate detail for the request. Do not narrate abstractly; explain what you are doing and why.
• The user does not see command execution outputs. When asked to show the output of a command (e.g. git show), relay the important details in your answer or summarize the key lines so the user understands the result.
• Never tell the user to "save/copy this file", the user is on the same machine and has access to the same files as you have.
• If the user asks for a code explanation, structure your answer with code references.
• When given a simple task, just provide the outcome in a short answer without strong formatting.
• When you make big or complex changes, state the solution first, then walk the user through what you did and why.
• For casual chit-chat, just chat.
• If you weren't able to do something, for example run tests, tell the user.
• If there are natural next steps the user may want to take, suggest them at the end of your response. Do not make suggestions if there are no natural next steps. When suggesting multiple options, use numeric lists for the suggestions so the user can quickly respond with a single number.

General

• When searching for text or files, prefer using rg or rg --files respectively because rg is much faster than alternatives like grep. (If the rg command is not found, then use alternatives.).
• Use finder for complex, multi-step codebase discovery: behavior-level questions, flows spanning multiple modules, or correlating related patterns. For direct symbol, path, or exact-string lookups, use rg first.
• Use librarian when you need understanding outside the local workspace: dependency internals, reference implementations on GitHub, multi-repo architecture, or commit-history context. Don't use it for simple local file reads.
• Pull in external references when uncertainty or risk is meaningful: unclear APIs/behavior, security-sensitive flows, migrations, performance-critical paths, or best-in-class patterns proven in open source or other language ecosystems. Prefer official docs first, then source.

Editing constraints

• Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
• Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
• Try to use apply_patch for single file edits, only when you repeatedly struggle with the same edit, you can try another way to edit.
• Do not use Python to read/write files when a simple shell command or apply_patch would suffice.
• You may be in a dirty git worktree.
  • NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
  • If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
  • If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
  • If the changes are in unrelated files, just ignore them and don't revert them, don't mention them to the user. There can be multiple agents working in the same codebase.
• Do not amend a commit unless explicitly requested to do so.
• NEVER use destructive commands like git reset --hard or git checkout -- unless specifically requested or approved by the user.
• You struggle using the git interactive console. ALWAYS prefer using non-interactive git commands.

Development Guide

Build/Test/Lint Commands

• Go version: 1.26+
• Build: mise build
• Test:
  • mise run test for unit tests
  • mise run test-race to run go tests with race detection
• Lint:
  • mise run lint to run Go vet and golangci-lint
• Clean:
  • mise run clean to remove build and coverage artifacts
• grep is an alias to rg.

Code Style Guidelines

• Imports: Use goimports formatting, group stdlib, external, internal packages
• Formatting: Use gofumpt (stricter than gofmt), enabled in golangci-lint
• Naming: Standard Go conventions - PascalCase for exported, camelCase for unexported
• Types: Prefer explicit types, use type aliases for clarity (e.g., type AgentName string)
• Error handling: Return errors explicitly, use fmt.Errorf for wrapping
• Context: Always pass context.Context as first parameter for operations
• Interfaces: Define interfaces in consuming packages, keep them small and focused
• Structs: Use struct embedding for composition, group related fields
• Constants: Use typed constants with iota for enums, group in const blocks
• Testing: Use testify's require package, parallel tests with t.Parallel(), t.SetEnv() to set environment variables. Always use t.Tempdir() when in need of a temporary directory. This directory does not need to be removed.
• JSON tags: Use snake_case for JSON field names
• File permissions: Use octal notation (0o755, 0o644) for file permissions
• Comments: End comments in periods unless comments are at the end of the line.

ALWAYS RUN these mise run commands:

• test
• test-race
• test-integration

ENSURE that the test coverage stays at or above 50% (CI enforced).

Test Patterns

Unit Tests

• Use t.Parallel() for tests that don't need database.
• Use table-driven tests for pure functions.
• Use testify/require for assertions.
• Use t.Helper() in test setup functions.

Database Tests

• Use database.TestDB(t) which skips if TEST_DATABASE_URL not set.
• Run with -p 1 to avoid race conditions.
• Do NOT use t.Parallel() for database tests.

Mocking External Dependencies

• Use interfaces for external SDK calls (e.g., Gemini API).
• Use adapter pattern to wrap SDK structs.
• Create separate constructors for testing (e.g., NewClientWithGenerator).
• See internal/bot/mocks/ for Telegram bot mocks.

Handler Testing

• Handlers take concrete *bot.Bot type, not interface.
• Use wrapper functions to test handler logic without calling real handlers.
• Callback handlers use EditMessageText instead of SendMessage.

Edge Cases to Test

• nil/empty slices and maps.
• Whitespace-only inputs.
• Bot mention formats in commands.
• Non-existent IDs for update/delete operations.

Formatting

• ALWAYS format any Go code you write with mise fmt

Comments

• Comments that live on their own lines should start with capital letters and end with periods. Wrap comments at 78 columns.

Committing

• ALWAYS run both unit and integraton tests before pushing
  • Especially, the fail tests with mise test-integration 2&>1 | grep -w 'FAIL:'
• ALWAYS use semantic commits (fix:, feat:, chore:, refactor:, docs:, sec:, etc).
• ALWAYS run pre-commits before pushing
• Try to keep commits to one line, not including your attribution. Only use multi-line commits when additional context is truly necessary.
• Push to all remotes with mise push-all.

Working on the TUI (UI)

Anytime you starts the work, read the AGENTS.md file

RTK (Rust Token Killer) - Token-Optimized Commands

Golden Rule

Always prefix commands with rtk. If RTK has a dedicated filter, it uses it. If not, it passes through unchanged. This means RTK is always safe to use.

Important: Even in command chains with &&, use rtk:

# ❌ Wrong
git add . && git commit -m "msg" && git push

# ✅ Correct
rtk git add . && rtk git commit -m "msg" && rtk git push

RTK Commands by Workflow

Build & Compile (80-90% savings)

rtk cargo build         # Cargo build output
rtk cargo check         # Cargo check output
rtk cargo clippy        # Clippy warnings grouped by file (80%)
rtk tsc                 # TypeScript errors grouped by file/code (83%)
rtk lint                # ESLint/Biome violations grouped (84%)
rtk prettier --check    # Files needing format only (70%)
rtk next build          # Next.js build with route metrics (87%)

Test (90-99% savings)

rtk cargo test          # Cargo test failures only (90%)
rtk vitest run          # Vitest failures only (99.5%)
rtk playwright test     # Playwright failures only (94%)
rtk test <cmd>          # Generic test wrapper - failures only

Git (59-80% savings)

rtk git status          # Compact status
rtk git log             # Compact log (works with all git flags)
rtk git diff            # Compact diff (80%)
rtk git show            # Compact show (80%)
rtk git add             # Ultra-compact confirmations (59%)
rtk git commit          # Ultra-compact confirmations (59%)
rtk git push            # Ultra-compact confirmations
rtk git pull            # Ultra-compact confirmations
rtk git branch          # Compact branch list
rtk git fetch           # Compact fetch
rtk git stash           # Compact stash
rtk git worktree        # Compact worktree

Note: Git passthrough works for ALL subcommands, even those not explicitly listed.

GitHub (26-87% savings)

rtk gh pr view <num>    # Compact PR view (87%)
rtk gh pr checks        # Compact PR checks (79%)
rtk gh run list         # Compact workflow runs (82%)
rtk gh issue list       # Compact issue list (80%)
rtk gh api              # Compact API responses (26%)

JavaScript/TypeScript Tooling (70-90% savings)

rtk pnpm list           # Compact dependency tree (70%)
rtk pnpm outdated       # Compact outdated packages (80%)
rtk pnpm install        # Compact install output (90%)
rtk npm run <script>    # Compact npm script output
rtk npx <cmd>           # Compact npx command output
rtk prisma              # Prisma without ASCII art (88%)

Files & Search (60-75% savings)

rtk ls <path>           # Tree format, compact (65%)
rtk read <file>         # Code reading with filtering (60%)
rtk grep <pattern>      # Search grouped by file (75%)
rtk find <pattern>      # Find grouped by directory (70%)

Analysis & Debug (70-90% savings)

rtk err <cmd>           # Filter errors only from any command
rtk log <file>          # Deduplicated logs with counts
rtk json <file>         # JSON structure without values
rtk deps                # Dependency overview
rtk env                 # Environment variables compact
rtk summary <cmd>       # Smart summary of command output
rtk diff                # Ultra-compact diffs

Infrastructure (85% savings)

rtk docker ps           # Compact container list
rtk docker images       # Compact image list
rtk docker logs <c>     # Deduplicated logs
rtk kubectl get         # Compact resource list
rtk kubectl logs        # Deduplicated pod logs

Network (65-70% savings)

rtk curl <url>          # Compact HTTP responses (70%)
rtk wget <url>          # Compact download output (65%)

Meta Commands

rtk gain                # View token savings statistics
rtk gain --history      # View command history with savings
rtk discover            # Analyze Claude Code sessions for missed RTK usage
rtk proxy <cmd>         # Run command without filtering (for debugging)
rtk init                # Add RTK instructions to CLAUDE.md
rtk init --global       # Add RTK to ~/.claude/CLAUDE.md

Token Savings Overview

Overall average: 60-90% token reduction on common development operations.

Refer to @CLAUDE.md for additional instructions RTK.md: /home/yelinaung/.codex/RTK.md AGENTS.md: @/home/yelinaung/.codex/RTK.md reference already present