codex-tg: Instructions file for Codex

AGENTS

Purpose: help AI agents work on codex-tg without increasing complexity or weakening the operator-facing Telegram control loop.

Good code is code that is easy to understand, change, test, and safely extend. Good agent work is evidence-backed, small in scope, and validated through the same surfaces the operator uses.

Repository Purpose

codex-tg is a Go daemon evolving into a local Codex Control Plane. Telegram is the first production adapter for observing, steering, approving, and routing local Codex App Server work.

The repo is public-facing. Keep every change safe for open-source publication: no private paths, tokens, Telegram ids, local sessions, databases, logs, screenshots with private data, or environment-specific credentials.

Working Mode

• First understand the current design. Read nearby code, tests, ADRs, and docs/testing/regression-map.md when it exists before editing.
• Do not treat a vague request as enough context. Ask focused questions when requirements, constraints, or tradeoffs are unclear and cannot be discovered safely.
• Prefer small steps: inspect -> plan -> test -> implement -> refactor -> validate.
• Do not generate large rewrites, broad refactors, or speculative frameworks unless the task explicitly requires them.
• Build what is needed now. Avoid adding libraries, build tools, abstractions, or cross-platform machinery without an immediate reason.
• Match the current user's language for working plans, handoffs, and status updates when clear. Public README, wiki, demo, release notes, and GitHub-facing docs may stay English-first.

Agent Workflow Kernel

• Do not start coding vague work. For unclear features, run alignment first: ask focused questions, lock goal, non-goals, UX, data, tests, and acceptance.
• Feature work needs a destination before implementation: a short issue, feature brief, or equivalent written target.
• Slice vertically. Prefer one small end-to-end behavior over horizontal phases such as storage first, daemon later, UI last.
• Use TDD for non-trivial behavior changes and bug fixes: failing or updated test, minimal implementation, refactor, targeted checks.
• Use fresh-context review for meaningful changes. The reviewer should inspect issue/brief, diff, tests, ADR/rules, and validation output, not the implementation chat.
• Human/live QA remains required for Telegram-facing behavior when a live contour is available.
• After compaction, context reset, or handoff, reread this file first, then pull only the docs called out by the Context Pull Map.