From a3992dfaa0e267a318f2fabb18aed4e3fb1f1511 Mon Sep 17 00:00:00 2001 From: John Preston Date: Fri, 4 Sep 2026 14:18:18 +0400 Subject: [PATCH] [ai] Use tasks for our AI tasks. --- AGENTS.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 0352553564..06fdd488d2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,59 @@ This guide defines repository-wide instructions for coding agents working with the Telegram Desktop codebase. +## AI Tasks + +In this repository "task" is a specific term. It always means one work record in +the sibling `ai-tdesktop` repository, never a `TODO` comment, a checklist item, +or a unit of work invented during the current conversation. "The tasks", "the +queue", "the board", "what's most pressing", and a bare task slug all refer to +that queue. + +- The queue lives in `../ai-tdesktop`, a sibling of this checkout, with one + record per directory under `tasks/YYYY/MM/DD//`. A task id is that dated + path, for example `2026/07/18/fix-community-forward`, and it is the only + durable link between a source commit and its task. Linked slot worktrees live + in `../ai-tdesktop-worktrees`. Read `../ai-tdesktop/AGENTS.md` before doing + anything inside that repository. +- Each record holds `task.md` — one `# ` title line, then one self-contained + paragraph that is the task's description wherever it is summarized — and + `state.yaml` with `status`, `type`, `depends_on`, `claimed_by`, and dates. + Open statuses are `todo`, `in-progress`, `blocked`, and `split-required`; + `approved` is completed history, and `split.yaml` / `superseded.yaml` mark + retired records. +- To browse the queue, read those files directly. Do not run `python3 ai.py`: it + is a full-screen browser for the user's own terminal and refuses to run in a + pipe. A compact open listing: + +```bash +cd ../ai-tdesktop && for state in tasks/*/*/*/*/state.yaml; do + status=$(sed -n 's/^status: //p' "$state") + case "$status" in todo|in-progress|blocked|split-required) + dir=$(dirname "$state") + printf '%-14s %-70s %s\n' "$status" "${dir#tasks/}" \ + "$(sed -n '1s/^# //p' "$dir/task.md")";; + esac +done | sort +``` + +- When ranking open work by urgency, use `in-progress`, then `blocked`, then + `split-required`, then ready `todo` (no `claimed_by`, and every `depends_on` + already `approved`), then `todo` still waiting on a dependency. Say who owns + claimed work. This checkout's tag is the `Telegram/build/ai-machine-tag` value + plus the checkout folder name, such as `macbook-tdesktop`, and work claimed by + another checkout is never taken over without an explicit human reassignment. +- Browsing is read-only. Listing, summarizing, comparing, or recommending tasks + never edits `state.yaml`, publishes a lifecycle commit, or starts + implementation, no matter how small the task looks. +- Acting on tasks goes through the workflow skills instead of by hand: + `perform-task ` starts or resumes and performs exactly one + known task, `continue` processes the inbox and drains eligible shared work, + and new requests are written to the ignored `../ai-tdesktop/inbox/inbox.md` + and routed by `process-inbox`. Source commits owned by a task use the + three-line form described under `## Commits`. +- Never guess between similarly named tasks. Report the matching full ids and + let the user choose. + ## Working from Codex on Windows + WSL This checkout may be opened in Codex Desktop through the Windows UNC path `\\wsl.localhost\{distro}\home\{user}\Telegram\tdesktop`, while the real Linux path is `/home/{user}/Telegram/tdesktop`. Treat it as a WSL/Linux checkout first, not as a native Windows checkout.