/oneshot

name: agtx-oneshot
description: "One-shot a whole project on an agtx board: decompose the goal, run every task unattended, unblock the workers, and merge each one. Use when the user wants a long autonomous run rather than a single session."
disable-model-invocation: true

agtx — One-Shotting a Project

You are **one-shotting** a project on an agtx kanban board: a goal too large for one session, run to completion unattended. Ordinarily a person sits at the board and does this. Here, you are that person.

This is not the built-in orchestrator (`O`), which only advances Planning → Running → Review and refuses to touch Backlog. **You own all five columns**: you decompose the goal into tasks, decide what starts, watch the workers, unblock them, judge Review, and merge. The workers do the coding; you never write feature code yourself.

Backlog → Planning → Running → Review → Done
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
              all of it is yours

Before anything else: verify the board is live

**Nothing you do executes unless the agtx TUI is running.** `move_task` writes a row to a queue; the TUI drains it and performs the real work — worktree creation, agent spawn, skill deployment. With no TUI, every transition sits pending forever and the board looks frozen for no visible reason.

1. Call `list_projects` and take the `project_id` of this project; pass it to every other agtx tool. If the MCP server does not answer, tell the user to register it and stop:

   claude mcp add --scope user agtx -- agtx mcp-serve

If this project is not listed, it has never been opened in agtx — ask the user to run `agtx` in the project root, which is needed anyway (below). Then call `list_tasks`. 2. Check `tui_connected` in that response. If it is `false`, no TUI is draining the queue — ask the user to open `agtx` in another terminal on this project, and do not queue anything into a dead board.

Also confirm before a long unattended run:

• **Call `get_config` and check `auto_trust`.** It must be `true`, or agents' trust and

bypass-permission dialogs are detected but left unanswered and every task parks as Blocked waiting for a human who is not there. Use the tool — do **not** read `~/.config/agtx/config.toml` yourself: `AGTX_CONFIG_DIR` relocates that file, so the path is not authoritative and you will get a stale answer. `get_config` also tells you which file to edit. `auto_trust` is global-only, so a project config cannot turn it on.

• **Open the coding agent once in the project root and accept its trust prompt** before

starting. Your own session parks on that dialog in a directory the agent has not seen, and an unattended run has nobody to answer it.

• The project has a **base branch** and a clean tree.

Four things that differ from a normal agtx session

**1. `allowed_actions` is not written for you.** `get_task` computes that field for the built-in orchestrator, which is forbidden from triaging Backlog — so it comes back empty for every Backlog task. **Ignore it.** `move_task` itself does not enforce it: `research`, `move_to_planning`, `move_to_running`, `move_forward`, `move_to_review`, `move_to_done` and `resume` all work from here. The only real gate is dependencies (below).

**2. No notifications reach you.** `get_notifications` only fills when the built-in orchestrator is running. Assume it returns nothing. `wait_for_board_change` is your whole feedback loop (see *The loop*).

**3. Read `phase_status` against `phase_age_secs`, never alone.** `list_tasks` and `get_task` both carry the board's own verdict on each task:

| `phase_status` | Meaning | |---|---| | `working` | The agent is producing output. Leave it alone. | | `ready` | The phase artifact was written this phase and the agent's turn is over — the phase is **complete**. Advance it. | | `blocked` | The agent reported it is waiting on a human. | | `idle` | No output for 15s. A guess, not a report. | | `exited` | The tmux window is gone. |

**`tui_connected` decides whether any of that is current.** `list_tasks` and `wait_for_board_change` both carry it. When it is `false`, nothing is executing transitions and every `phase_status` is frozen at whatever was last observed — **stop and tell the user**; do not read those rows as task state. A task can show `blocked` while its agent works normally, purely because the TUI has exited.

`phase_age_secs` is the corroborating detail: the board republishes every live task on every pass, so a small age means "seen just now". Check `tui_connected` first — it is the direct answer; age is the symptom.

Two other signals, for when you need more than the verdict:

| Signal | How | Use | |---|---|---| | `agent_state` | `get_task`, hook-reported | `blocked_reason` names the exact prompt the agent is waiting on | | `read_pane_content` | last N lines of the pane | Ground truth, but costs context — diagnose with it, never poll with it |

Artifact files are the fallback if `phase_status` is absent. For the default `agtx` plugin, relative to `worktree_path`: `.agtx/research.md`, `.agtx/plan.md`, `.agtx/execute.md`, `.agtx/review.md`. Other plugins declare their own under `[artifacts]` in `plugins/<name>/plugin.toml`.

**4. Starting tasks is serialized, and that is fine.** Worktree setup runs one at a time. Queue as many `move_to_planning` calls as you like in one pass — they line up and drain in order. A start waiting for the slot has simply not resolved yet. You do not need to poll `get_transition_status`: `wait_for_board_change` reports the outcome of every move you queued in its `transitions` list, and wakes you if one fails. Only an `error` means it will not happen.

Decomposition

A goal this size cannot be enumerated up front, and trying wastes the run. Work in **waves**.

1. Write a milestone spine first — 4–8 milestones, coarse, in `oneshot-state.md` (below). Nothing goes on the board yet. 2. Turn **only the current milestone**