Process Inbox

Process Inbox

When running in Grok Build, read .grok/ai-workflow-adapter.md completely before any other host-specific delegation rule and apply its substitutions.

Before assigning workers, read phase effort and apply its scope-based effort selection and host mappings.

Turn the human-written ignored inbox into tracked planning artifacts. Route and plan only: do not edit Telegram source, build, test, claim, or implement tasks.

Workspace

Run from a Telegram Desktop checkout. Use the bundled helper with an available Python 3 interpreter:

python3 .agents/skills/process-inbox/scripts/workspace.py inbox-ensure
python3 .agents/skills/process-inbox/scripts/workspace.py prepare

Use python or py -3 when that is the host's Python 3 command. The helper:

• reads Telegram/build/ai-machine-tag;
• combines it with the checkout folder, for example macbook-twork;
• locates the sibling ai-tdesktop and ai-tdesktop-worktrees directories, with AI_TDESKTOP_ROOT and AI_TDESKTOP_WORKTREES_ROOT as overrides;
• ensures the isolated inbox/<checkout-tag> linked worktree exists without creating or inspecting the task execution worktree;
• snapshots the ignored inbox before planning and prints JSON paths.

prepare resumes the one active .processing-* snapshot when present. Save its transaction, digest, ai_main, inbox_worktree, inbox_branch, and checkout_tag values. Read raw input only from the transaction snapshot, not from the live inbox.

The task execution slot_worktree may be dirty or have unpublished task work. Ignore it completely while processing the inbox: do not read planning state from it, write to it, stage it, commit it, rebase it, or publish it.

For a new transaction, prepare requires clean ai_main and inbox_worktree state with no unpublished inbox commits. It fetches origin when configured, fast-forwards local master, and fast-forwards the inbox branch before taking the snapshot. If the inbox is empty, the machine tag is invalid, or either inbox publication worktree is unsafe, stop without changing or clearing the inbox. Never force-push shared AI history.

Route and plan

Follow the shared project-context policy for discovery, selective expansion, and compact project/index artifacts.

Read these before planning:

• source checkout AGENTS.md;
• ai_main/AGENTS.md;
• the transaction's inbox.md and every file it references.

For each request, start with explicit task/project lineage and relevant task metadata from <inbox_worktree>. Use project names/titles and targeted search matches across live and archived projects to identify candidates, then read their small overviews. Inspect relevant task specifications, input sections, index entries, or detailed references when needed to resolve a dependency or routing ambiguity. Do not load every project's overview or task history.

Some retained task directories have superseded.yaml instead of state.yaml. They are durable aliases created by queue consolidation, not missing or reusable paths. Follow superseded_by chains to their live task when deduplicating, resolving prior receipt references, or checking whether a same-digest result still exists. New dependencies and project links must name the final live task, never an alias. A dated slug occupied by an alias still counts as a collision. Some retired oversized tasks instead have split.yaml, whose split_into list resolves to several live successors. Treat the retained directory as history, deduplicate against all live successors, and never put the split id in a new dependency or project link. A split path is also permanently occupied.

Use one disposable leaf planner when the harness supports delegation; instruct it not to delegate. Otherwise perform the same work locally. The planner may write a proposed routing file inside the ignored transaction, but only the orchestrator writes tracked AI state.

Treat natural-language hints as evidence, not required syntax. Segment the inbox into requests, then decide for each request whether to:

• create a standalone task with no project;
• add one or more tasks to an existing project;
• create a new project when durable shared context is useful.

Never create a task whose work is to move an existing source commit between branches: no backport, forward-port, cherry-pick, rebase, merge, branch sync, or equivalent integration task. Branch placement is human release/history coordination, not product work for the autonomous queue. When a request only asks for that operation, record a receipt-only disposition naming the existing source task or commit description and the requested target branch, then leave the operation to the human. When new product work requires code shipped by an earlier task, route only the product work and express the source task as a dependency; do not create a companion task to bring that dependency onto a branch.

Bias project assignment toward continuity. When a request follows from an existing task, begin with that task's project and keep it unless independence is affirmatively established. A task belongs to the existing project when it builds on project code or behavior, requires source changes shipped by project tasks, assumes the project's branch or accumulated context, or must be ordered after project work. Touching shared infrastructure or an additional non-project consumer does not by itself make the task standalone: projects record feature and code lineage, not exclusive ownership of every touched file.

Route a derived request to another project or to project: null only when it remains coherent, implementable, and independently testable in a checkout where the originating project's changes are absent or reverted. Record that concrete independence evidence in the receipt; "cross-cutting", "cleanup", or "broader than the source task" is not enough. For a request without a source task, prefer an existing project whenever its code, plan, or prior tasks supply essential context, and use a standalone task only when no project does.

Do not create generic holding projects such as fixes. A release batch of unrelated regressions normally becomes standalone tasks or tasks in existing domain projects. Group requests into one task only when they form one cohesive, independently testable behavior that can be implemented, reviewed, and tested as one normal pass.

Split at product boundaries, not arbitrary file or line-count boundaries. A request needs multiple tasks when two or more parts have their own useful outcome and acceptance oracle, when a later part can consume an earlier part as a stable dependency, or when the parts require materially different context, failure analysis, or evidence setup. New network, persistence, concurrency or ownership machinery plus application lifecycle/UI integration are especially strong split signals when each can be exercised independently. Shared project context, overlapping files, or one eventual feature does not by itself justify paying one review and test loop over their combined implementation.

Do not over-split inseparable changes: keep a small API and its only caller together when neither has a meaningful standalone result, and keep one atomic behavior together when separating it would leave an unbuildable or untestable intermediate state. For every proposed task, state the one shipped boundary it owns and the direct evidence that can approve it without first implementing a sibling. If that sentence needs several independent outcomes or several unrelated instruments, split again.

This is the first scope gate, not an irrevocable ruling. Inbox planning uses the request plus light source inspection and deliberately does not construct the implementation plan. The later independent perform-task assessment sees exact files, APIs, phases, ownership boundaries, and evidence design; it may veto the single-task shape when that richer proof exposes independently shippable and testable boundaries. That veto does not mean task sizing is based on elapsed time or diff length, and it does not authorize the performer to mutate the queue itself. The performer publishes split-required; the checkout scheduler then launches a dedicated deep split transaction that creates replacements, rewrites dependencies and project links, and retires the source with a durable multi-target split record.

Project slugs are unique across projects/ and projects/archive/. When a request belongs to an archived project, restore it before routing to it:

python3 .agents/skills/process-inbox/scripts/workspace.py inbox-unarchive \
  --project <slug>

The helper moves the project back to projects/<slug>, rewrites its relative links, and leaves the restored files staged for this transaction's commit. Never point a task at a path under projects/archive/.

Briefly inspect Telegram source when needed to understand scope and testable seams. Do not plan implementation internals and do not modify the source tree.

Assign task paths

Use the processing date and a concise imperative kebab-case slug:

tasks/YYYY/MM/DD/<task-slug>/

The task identifier is the path below tasks/, for example:

2026/07/18/fix-community-forward

Never ask the human to choose or remember it. Consult existing directories and append -2, -3, and so on to resolve a same-day collision. Dependencies may name only task identifiers created earlier in the same routing result or existing tasks.