From ef295c80417cc3fbd49a04a983a64f06750fa59b Mon Sep 17 00:00:00 2001 From: John Preston Date: Wed, 12 Aug 2026 21:23:07 +0400 Subject: [PATCH] [ai] Test workflow in Grok Build. --- .agents/skills/continue/SKILL.md | 3 + .agents/skills/perform-task/SKILL.md | 3 + .../perform-task/references/phase-prompts.md | 34 +++++ .../perform-task/references/pipeline.md | 17 ++- .agents/skills/process-inbox/SKILL.md | 3 + .grok/ai-workflow-adapter.md | 137 ++++++++++++++++++ .grok/commands/continue.md | 47 ++++++ .grok/commands/perform-task.md | 32 ++++ .grok/commands/process-inbox.md | 34 +++++ AGENTS.md | 5 +- GROK.md | 5 + 11 files changed, 311 insertions(+), 9 deletions(-) create mode 100644 .grok/ai-workflow-adapter.md create mode 100644 .grok/commands/continue.md create mode 100644 .grok/commands/perform-task.md create mode 100644 .grok/commands/process-inbox.md create mode 100644 GROK.md diff --git a/.agents/skills/continue/SKILL.md b/.agents/skills/continue/SKILL.md index ea55f3f445..f0a5779cf7 100644 --- a/.agents/skills/continue/SKILL.md +++ b/.agents/skills/continue/SKILL.md @@ -5,6 +5,9 @@ description: Continue autonomous Telegram Desktop development from the shared ai # Continue AI Work +When running in Grok Build, read `.grok/ai-workflow-adapter.md` completely +before any other host-specific delegation rule and apply its substitutions. + Act as the checkout-level scheduler. Choose one invocation mode at startup, freeze its task batch, and keep looping only through that batch and follow-ups discovered from its results. Do not drain unrelated tasks added while the run diff --git a/.agents/skills/perform-task/SKILL.md b/.agents/skills/perform-task/SKILL.md index 7b9825d9b3..3b137214da 100644 --- a/.agents/skills/perform-task/SKILL.md +++ b/.agents/skills/perform-task/SKILL.md @@ -5,6 +5,9 @@ description: Resolve, start or resume, implement, commit, and verify exactly one # Perform One AI Task +When running in Grok Build, read `.grok/ai-workflow-adapter.md` completely +before any other host-specific delegation rule and apply its substitutions. + Own exactly one task through a Telegram commit and a canonical AI `Approve` or exceptional `Block`. Do not process the inbox, split the task, drain the queue, select a follow-up, or consolidate pending tasks afterward. The `continue` diff --git a/.agents/skills/perform-task/references/phase-prompts.md b/.agents/skills/perform-task/references/phase-prompts.md index 02ce7ed32f..45ef59db77 100644 --- a/.agents/skills/perform-task/references/phase-prompts.md +++ b/.agents/skills/perform-task/references/phase-prompts.md @@ -52,6 +52,23 @@ every applicable placeholder: ``, ``, ``, once in a fresh Agent with more specific instructions before stopping to ask the user. +### Grok Build: blocking spawn, depth one + +- Follow `.grok/ai-workflow-adapter.md`. Its substitutions win over the + Codex wait ladder and over any prompt that assumes nested delegation. +- When this session is a top-level `/perform-task`, run each leaf as one + blocking `spawn_subagent` (`background: false`). The call returning is + the completion signal; validate the artifact checks below on return. +- Spawn the independent leaves of one step — the Phase 6a lenses plus the + iteration-1 Phase 6d test-design leaf, or assessed-disjoint Phase 4 + units — as parallel `spawn_subagent` calls in a single message. +- When this session is a `/continue` child, do not call `spawn_subagent`. + Run every phase as a same-session checklist. That is the supported + depth-1 fallback, not a retry. +- If a returned leaf fails its completion check, retry that disposable + phase once in a fresh `spawn_subagent` with more specific instructions + before stopping to ask the user. + ### Codex: asynchronous spawn and wait - Store the canonical target returned by `spawn_agent`. @@ -1154,6 +1171,23 @@ For review iterations, include the iteration and the lens in the file name, for small shell summaries and the completion checks above. 4. Write the result log from the validated outcome and the compact reply block. +## Subagent Pattern (Grok Build) + +1. Write the phase prompt file(s). +2. From a top-level `/perform-task` session, make one blocking + `spawn_subagent` call per leaf — parallel calls in a single message + for independent leaves of the same step — with self-contained + prompts and `background: false`. From a `/continue` child, use the + same prompt files as same-session checklists and do not spawn. +3. When a spawn returns, or when a same-session checklist finishes, + validate the expected artifacts or code changes with small shell + summaries and the completion checks above. +4. Write the result log from the validated outcome and the compact + reply block. + +Do not replace this pattern with a shell-launched `grok` process, a +workflow script, or the Codex wait ladder. + ## Subagent Pattern (Codex) Use this pattern conceptually for delegated phases: diff --git a/.agents/skills/perform-task/references/pipeline.md b/.agents/skills/perform-task/references/pipeline.md index 520d33ae17..8830a439f6 100644 --- a/.agents/skills/perform-task/references/pipeline.md +++ b/.agents/skills/perform-task/references/pipeline.md @@ -213,11 +213,14 @@ Write the delegated prompt first. Require a final reply containing only status, artifact paths, touched paths, and blocker. On Claude Code, run each leaf as a synchronous foreground call and validate its artifacts when the call returns; run independent leaves of one step as parallel calls in a single -message. On Codex, use the asynchronous wait ladder from the phase prompts: -poll no longer than 60 seconds, treat a timeout as not-failure, use artifact -mtimes and heartbeat counters, message the target after five minutes without -movement, and interrupt and retry that disposable phase once after a second -unchanged window. On either host, never replace a live stateful performer. +message. On Grok Build, follow `.grok/ai-workflow-adapter.md`: blocking +`spawn_subagent` leaves from a top-level performer, same-session checklists +from a `/continue` child, no Codex wait ladder. On Codex, use the +asynchronous wait ladder from the phase prompts: poll no longer than 60 +seconds, treat a timeout as not-failure, use artifact mtimes and heartbeat +counters, message the target after five minutes without movement, and +interrupt and retry that disposable phase once after a second unchanged +window. On any host, never replace a live stateful performer. ## Implementation phases @@ -468,8 +471,8 @@ Determine the prefix from the retained task implementation, not from the temporary test overlay. Start the subject with exactly `[ai] ` when the task changes permanent test-helper code, the agent harness, or agent documentation in any way. This includes `Telegram/SourceFiles/test/`, `.agents/`, `.claude/`, -`AGENTS.md`, `CLAUDE.md`, and files whose sole role is supporting those -systems. The disposable test overlay and external AI task artifacts do not +`.grok/`, `AGENTS.md`, `CLAUDE.md`, `GROK.md`, and files whose sole role +is supporting those systems. The disposable test overlay and external AI task artifacts do not count. For every other task, the subject must not contain `[ai]` anywhere. The prefix counts toward the subject length. diff --git a/.agents/skills/process-inbox/SKILL.md b/.agents/skills/process-inbox/SKILL.md index 03ed559448..cd05cc9062 100644 --- a/.agents/skills/process-inbox/SKILL.md +++ b/.agents/skills/process-inbox/SKILL.md @@ -5,6 +5,9 @@ description: Process the local ignored ai-tdesktop inbox into durable, independe # 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. + 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. diff --git a/.grok/ai-workflow-adapter.md b/.grok/ai-workflow-adapter.md new file mode 100644 index 0000000000..04bd2a8736 --- /dev/null +++ b/.grok/ai-workflow-adapter.md @@ -0,0 +1,137 @@ +# Grok Build AI Workflow Adapter + +Apply this adapter only when a command or shared skill explicitly loads it. +The shared `.agents/skills/` workflow remains authoritative for task +selection, artifacts, source changes, builds, testing, commits, +resumability, and AI publication. This file adapts harness mechanics. + +## Delegation + +- Use Grok's `spawn_subagent` tool wherever the shared workflow says to spawn + a subagent, worker, performer, planner, or leaf. +- Treat `fork_turns: "none"` as a fresh `spawn_subagent` call with a + self-contained prompt containing exact repository, task, artifact, and + input paths. Do not rely on the parent conversation being inherited. +- Always pass `background: false`. The call returning is the completion + signal. Validate the required files and repository state right there, + treating the short reply as notification only. +- Do not use `background: true` plus `get_command_or_subagent_output`, + shell `sleep`/`until` polling, the Codex wait ladder, heartbeat-mtime + checks, or five-minute stall windows. Those are Codex-only. Leaves still + write their progress files (they are cheap resumability evidence), but + the parent never polls them. +- There is no `wait_agent`, `list_agents`, `send_message`, `followup_task`, + `interrupt_agent`, or `spawn_agent`. Do not invent them. Do not launch + `grok`, `claude`, or `codex` from Bash. +- Do not use the `workflow` tool to reimplement this pipeline. +- Do not pass `isolation: worktree`. The shared `workspace.py` helper owns + every AI and inbox worktree. +- Omit `model` and any reasoning field so every child inherits this + session. Do not invent tool arguments the schema does not expose. +- Use `subagent_type: "general-purpose"` for inbox, performer, routing, + consolidation, and phase leaves. Do not restrict `capability_mode`; + those workers need shell plus writes. +- Tell every disposable phase leaf not to delegate and never to commit. + Publication-owning orchestrators — `process-inbox`, `perform-task`, + discovered routing, and pending-task consolidation — follow the shared + workflow's exact helper, commit, and publication contract. Preserve its + single-writer and one-stateful-performer constraints. +- When a blocking call returns without its required artifact, retry that + disposable worker once in a fresh `spawn_subagent` with more specific + instructions. If Grok returned a completed subagent id and more work is + needed from that same stateful worker, resume it with `resume_from`; + never create a duplicate performer or duplicate an agent whose writes + may still be in flight. +- A long Debug build may run as `run_terminal_command` with + `background: true`. Wait on its task id; do not poll its log with sleep + loops. + +## Depth + +Grok subagents cannot spawn subagents. Depth is one. A child that calls +`spawn_subagent` fails. Do not treat presence of the tool as a successful +nested-delegation probe. + +### `/continue` in this session + +This session is the scheduler only. Do not plan or implement Telegram +changes here. + +Spawn each inbox worker, performer, discovery-routing worker, and +pending-task consolidation worker as a blocking `spawn_subagent`. Tell +every one of those workers, in its initial prompt, to read this adapter +completely before the applicable shared skill or reference. + +A performer spawned from `/continue` is already at depth 1. Its prompt +must also say: + +```text +You are a Grok subagent at depth 1. Do not call spawn_subagent. +Run every phase leaf as a same-session checklist from +.agents/skills/perform-task/references/phase-prompts.md. +``` + +That is the shared same-session fallback, selected from the first +performer, not a degraded failure. Do not tell a continue-spawned +performer that it may use bounded leaf delegation. + +### `/perform-task` or `/process-inbox` in this session + +This session is the orchestrator and may spawn leaves. + +- Run each leaf as one blocking `spawn_subagent` with a self-contained + prompt. Do not tell leaf phase agents to read this adapter. +- Spawn the independent leaves of one step — the review lenses plus the + iteration-1 test-design leaf, or assessed-disjoint implementation + units — as parallel `spawn_subagent` calls in a single message. +- If the first real leaf is rejected before work begins because nested + delegation is unavailable, use the shared same-session fallback for + the rest of the run. + +## Text handling + +Do not run a dedicated line-ending or BOM check, normalization, repair, +phase, artifact, rebuild, or summary. In particular: + +- ignore the tracked-text line-ending validation item in `process-inbox`; +- skip perform-task Phase 7 entirely on every host; +- ignore the pipeline's Normalize step and every Phase 7 prompt, result, + retry, completion check, and reporting requirement; +- do not rewrite a file solely to change LF, CRLF, mixed endings, or BOM + state. + +Let normal Grok editing preserve the checkout's existing text convention. +This exception removes only explicit line-ending work; it does not relax +any content validation, owned-path rule, build, review, test, or +publication gate. + +## UI-driver capability + +The shared Computer Use reference describes Codex's driver. In Grok, +treat that driver as unavailable unless an equivalent UI-driver tool is +actually exposed in the current session. Preserve the same policy: `auto` +uses the already planned overlay fallback, while `required` reports the +exact unverified interaction. Driver availability never permits skipping +the ordinary overlay test loop, account setup, evidence, or safety rules. + +Judge overlay screenshots and supplied mockups by reading the image files +with `read_file`. Saved PNG/JPG artifacts are visual input. A missing +desktop driver is not missing evidence when the overlay captured the +widget or window. + +## Compaction + +Do not stop a `/continue` drain because a compact is approaching, remaining +compacts are low, or the parent window is large. The scheduler is a thin +loop: helper JSON, worker prompts, artifact checks. A compact of that +parent is fine. If the host compact or the session dies, that is the stop; +leave in-progress task state recoverable and let the next `/continue` +invocation resume it. + +The only scheduler state that is not already on disk is the frozen batch +(`invocation_mode`, `initial_batch_task_ids`, `batch_task_ids`, +`discovered_task_ids`, `attempted_blocked`, consolidation records). After +a compact, recover those lists from the compact summary and the last +scheduler notes. Do not take a fresh queue snapshot and freeze a new +batch. A later queue id that was never in this invocation's batch stays +out, exactly as the shared skill says. diff --git a/.grok/commands/continue.md b/.grok/commands/continue.md new file mode 100644 index 0000000000..c56384db10 --- /dev/null +++ b/.grok/commands/continue.md @@ -0,0 +1,47 @@ +--- +name: continue +description: Continue work from the shared ai-tdesktop queue. Use when the user invokes /continue or $continue in Grok Build, or asks to resume the active task and drain the frozen startup batch. +--- + +# Continue AI Work + +Read `.grok/ai-workflow-adapter.md` and +`.agents/skills/continue/SKILL.md` completely. Follow the shared skill with +the Grok adapter's delegation, depth, text-handling, UI-driver, and +compaction substitutions. At startup choose exactly one shared-skill mode +and record its frozen task ids: put any active task first and append the +matching existing queue snapshot, drain that snapshot when no task is +active, or, when both are empty, process one inbox transaction and drain +only its routed tasks. Never add unrelated tasks observed later in the +run. Append and implement only new follow-up tasks routed from results +produced by this invocation, including their transitive discovered +follow-ups. Preserve the shared skill's source-project inheritance rule; +detaching a follow-up requires its affirmative independence test. Continue +until that frozen-and-derived batch reaches the scheduler's normal stop +condition or a global hard stop. Do not stop on your own because a compact +is approaching. + +Apply the shared skill's pending-task consolidation phase too. At each +eligible clean AI-slot boundary, recover an older `pending_consolidations` +marker or consolidate newly routed tasks in one fresh blocking +`spawn_subagent`. Give it the effective frozen batch, keep its queue scan +and merge reasoning outside this scheduler context, and require it to read +the complete shared consolidation reference. Never run consolidation inside +the performer or discovery-routing worker, and defer it while the active +task owns dirty local phase state. + +Every inbox worker, performer, discovered-task routing worker, and +pending-task consolidation worker must be told in its initial prompt to +read `.grok/ai-workflow-adapter.md` completely before the applicable shared +skill or reference. Use `spawn_subagent` with `background: false` for those +workers. A continue-spawned performer is at depth 1 and must run every +phase leaf as a same-session checklist. Do not start Grok subprocesses +through Bash. + +Arguments, when present, are natural-language hints for new shared work; +their wording decides whether they merely prioritize or strictly restrict +selection: + +```text +$ARGUMENTS +``` diff --git a/.grok/commands/perform-task.md b/.grok/commands/perform-task.md new file mode 100644 index 0000000000..594d8efc8c --- /dev/null +++ b/.grok/commands/perform-task.md @@ -0,0 +1,32 @@ +--- +name: perform-task +description: Implement one existing AI task by short name or full id. Use when the user invokes /perform-task or $perform-task in Grok Build with a known task name. +--- + +# Perform One AI Task + +Read `.grok/ai-workflow-adapter.md` and +`.agents/skills/perform-task/SKILL.md` completely. Follow the shared skill +with the Grok adapter's delegation, depth, text-handling, and UI-driver +substitutions. Resolve, start or resume, implement, verify, and publish only +the named task. Do not continue with other queue work, route discoveries, or +consolidate pending tasks afterward; those post-result phases belong to the +`continue` scheduler. + +Apply the shared pipeline's conditional `[ai] ` commit-subject rule exactly; +the prefix is required for permanent test-helper or agent harness or +documentation changes and forbidden for every other task. Count `.grok/` +with `.agents/` and `.claude/` for that prefix. + +This session is the performer, so leaf delegation is available. Delegate +phases with blocking `spawn_subagent` calls per the adapter; leaf phase +agents receive self-contained prompts and are not told to read the adapter. +If the first real leaf is rejected because nested delegation is +unavailable, use the shared same-session fallback. Do not start Grok +subprocesses through Bash. + +Task short name or full id: + +```text +$ARGUMENTS +``` diff --git a/.grok/commands/process-inbox.md b/.grok/commands/process-inbox.md new file mode 100644 index 0000000000..5fcd9055de --- /dev/null +++ b/.grok/commands/process-inbox.md @@ -0,0 +1,34 @@ +--- +name: process-inbox +description: Route the local AI inbox into durable planned tasks. Use when the user invokes /process-inbox or $process-inbox in Grok Build. +--- + +# Process Inbox + +Read `.grok/ai-workflow-adapter.md` and +`.agents/skills/process-inbox/SKILL.md` completely. Follow the shared skill +with the Grok adapter's delegation, depth, and text-handling substitutions. +Process the ignored inbox associated with the current Telegram Desktop +checkout. Route and plan tasks only; do not implement, build, or test them. + +Preserve the shared skill's project-continuity bias. A request derived from +existing project work stays in that project unless it passes the skill's +affirmative independence test; shared or cross-surface files alone do not +make it standalone. + +Parallel task work is expected. Use the shared skill's `inbox_worktree`, +`inbox_branch`, and `inbox-*` helper commands exactly as documented. Never +substitute the task `slot_worktree`, stop merely because that slot is dirty, +or run broad Git staging from Bash. The shared helper owns the isolated +inbox commit, rebase, master publication, and resumable failure handling. + +If a planner subagent is used, tell it to read +`.grok/ai-workflow-adapter.md` before the shared skill instructions. Use +`spawn_subagent` with `background: false` for delegation; do not start Grok +subprocesses through Bash. + +Arguments, when present, are additional routing hints: + +```text +$ARGUMENTS +``` diff --git a/AGENTS.md b/AGENTS.md index 4ec2eea26c..aceec25137 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -185,8 +185,9 @@ user to close that checkout's Telegram/debugger before rebuilding. - For an `ai-tdesktop` task, start the subject with exactly `[ai] ` when the retained task implementation changes permanent test-helper code, the agent harness, or agent documentation in any way. This includes - `Telegram/SourceFiles/test/`, `.agents/`, `.claude/`, `AGENTS.md`, - `CLAUDE.md`, and files whose sole role is supporting those systems. Do not + `Telegram/SourceFiles/test/`, `.agents/`, `.claude/`, `.grok/`, + `AGENTS.md`, `CLAUDE.md`, `GROK.md`, and files whose sole role is + supporting those systems. Do not count the disposable test overlay or external AI task artifacts. For every other task, the subject must not contain `[ai]` anywhere. - For ordinary work not associated with an AI task, add a short plain-language body only when the subject can't carry it (what was done, not the technical how) — a line or two at most. diff --git a/GROK.md b/GROK.md new file mode 100644 index 0000000000..b1ae452d94 --- /dev/null +++ b/GROK.md @@ -0,0 +1,5 @@ +# Grok Build Pointer + +Read `AGENTS.md` and treat it as the canonical repository-wide instructions. +For `/continue`, `/perform-task`, and `/process-inbox`, also read +`.grok/ai-workflow-adapter.md`.