Agtx Oneshot

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:

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:

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 into tasks. One task = one reviewable, independently mergeable PR. create_tasks_batch takes up to 50 and wires dependencies by 0-based index into the same array (no forward references).
3. When a milestone is mostly in Review/Done, write the next wave — informed by what the workers actually built, which is the point of not planning it all on day one.

Task quality decides whether the run survives:

• Title: imperative, ≤ 8 words, ≤ 120 characters (hard cap — creation fails above it).
• Description: 3–6 sentences. The worker agent has zero context from this conversation. Name the files, the interfaces it must match, the constraints, and what "done" looks like. A vague description is the single most common cause of a task that burns an hour and produces nothing.
• Dependencies are a real gate. A Backlog task whose referenced tasks are not yet in Review or Done cannot be advanced at all — the move is refused. Use this deliberately to sequence, and don't over-wire it: a false dependency stalls a whole branch of the DAG.

create_tasks_batch({
  "tasks": [
    { "title": "Add entity component store", "description": "..." },
    { "title": "Add physics step over the store", "description": "...", "depends_on": [0] },
    { "title": "Add render pass over the store", "description": "...", "depends_on": [0] }
  ]
})

Keep 3–6 tasks running at once. More than that and you cannot actually supervise them, and the machine starts thrashing on parallel agent sessions.

The loop

Call wait_for_board_change, act on what it returns, and call it again. It blocks inside the server until something needs you, then returns only the tasks that changed since you last looked. The first call returns the whole board.

Do not sleep and re-list instead. Every poll is a turn, and every turn re-reads your entire context — so a run's cost is set by how many turns it takes far more than by what any one call returns. A task starting to work does not wake the wait; you hear about a task when it needs you.

Each time it returns:

1. tui_connected: false → the TUI is gone and every phase_status is frozen. Stop and say so rather than acting on it.
2. transitions → the outcome of each move you queued. An error is the one failure nothing else on the board shows; read it and act on it (see Review and merge for merge refusals and conflicts).
3. For each task in tasks:
   • ready in Planning or Running → move_task with move_forward.
   • ready in Review → judge it (below).
   • blocked → get_task for blocked_reason. A permission or trust prompt is a config problem (auto_trust), not something to answer by typing into the pane — surface it to the user. A question: see Answering questions below.
   • idle → read_pane_content, then act on what you see. For an agent without hooks idle is a guess from pane output, so confirm before nudging.
   • exited → the session died. resume it, or investigate before restarting.
   • done → record it; its dependents may now start.
   • Backlog with deps_satisfied → start it if it fits the concurrency budget — move_to_planning. Starts serialize on their own.
4. Update oneshot-state.md, then wait again.

timed_out: true means nothing needed you — wait again. It is not a reason to inspect every task.

Keep the board in oneshot-state.md, not in your head. The wait tells you what changed; the state file is what you apply it to. When your context has been compacted, or you are picking up a run, call list_tasks once to re-sync — it leaves descriptions out, and get_task has the full task when you need one. A session that has memorised a stale board makes confident wrong moves.

Keeping durable state

Maintain oneshot-state.md in the project root. It is what a fresh session reads to pick up the run:

# Oneshot state — <goal>
Updated: <timestamp>

## Milestones
- [x] M1 core loop
- [ ] M2 world streaming   ← current wave
- [ ] M3 ...

## Board
| id | title | status | notes |
|----|-------|--------|-------|
| a1b2c3 | Add entity component store | Done | merged |
| d4e5f6 | Add physics step | Running | nudged once, was idle |

## Decisions
- Physics runs fixed-step at 60Hz; renderer interpolates. (M1, task a1b2c3)

## Open questions for the user
- (none)

Rewrite the Board table each pass; append to Decisions and Open questions. Decisions are what stop later tasks contradicting earlier ones.

Review and merge

Review is where an unattended run quietly produces garbage, so spend your judgment here rather than on scheduling.

1. Read the diff (git -C <worktree_path> diff <base>...HEAD). Ask only: does this do what the task said, and does it break the milestone spine? You are not doing a line-level code review — the Review phase agent does that.

2. If it is wrong, decide how wrong before acting. Small fixes go to the reviewer in place; resume is only for real rework.

   • A small, contained change — a wrong sentence, a missing guard, a rename, a test to add — send it with send_to_task while the task stays in Review. Say exactly what to change, and to commit and update .agtx/review.md when done. The reviewer makes it where it is: no transition, no second execute cycle. Its turn restarts, so phase_status reads working until it has finished; wait for ready, re-read the diff, then merge.
   • Significant rework — the approach is wrong, a requirement was missed, the work needs replanning — resume the task, then send_to_task the correction. resume puts the task back in Running, so when the agent is done you must move_forward to Review again before you can merge; merging straight after a resume is refused.

   Either way, act only once the agent has stopped. ready means that for an agent with hooks; for one without, read the pane first. An agent writes review.md and keeps working after it, and a message sent into a turn that has not ended lands in a busy pane. Vague feedback produces another wrong attempt, in either lane.

3. Land it with move_to_done_and_merge. This merges the branch into its base in the project checkout and then moves the task to Done. Plain move_to_done keeps the branch and merges nothing — use it only if you are integrating some other way, otherwise you finish the run with N parallel branches and an empty base branch.

4. On conflict the task stays in Review and its own agent is sent /agtx:merge-conflicts automatically, with the conflicting files named. The transition reports an error saying so. Do not retry immediately and do not try to resolve it yourself — wait for that task to go ready again, then call move_to_done_and_merge a second time.

5. A refusal is about the project checkout, not the branch. "on X, not the base branch" or "has uncommitted changes" means someone left the project root dirty or on another branch. Nothing was changed. Tell the user — you must not switch their branch or stash their work to get around it.

6. move_to_done is refused while the worktree has uncommitted changes. Different error, different fix: send_to_task telling the agent to commit, then retry. Do not queue it repeatedly; it will keep failing.

Merges are serialized with everything else the board does, so several tasks reaching Done in one pass is safe.

Answering questions

When a worker asks something, classify before acting:

• A tool's yes/no prompt — the uppercase letter is the default; send_to_task it.
• A numbered menu with a marked default — send that number.
• A question about the goal that your milestone spine or Decisions already answers — answer it. That is why you keep those.
• A question that changes the shape of the product, or a menu with no default, or a trust/permission prompt — stop and ask the user. Record it under Open questions and keep the rest of the board moving while you wait. Do not invent product decisions the user would want to make; a wrong answer here propagates into every later task.

If the same task goes idle twice after you nudged it, stop nudging. Escalate to the user or delete and rewrite the task with a better description.

Rules

• You never write feature code. You write tasks, and oneshot-state.md.
• Drive the run with wait_for_board_change, never with sleep. Use list_tasks to re-sync after a gap, never to poll.
• Ignore allowed_actions; respect dependency refusals.
• One task = one mergeable PR. Split anything with "and" in its title.
• Cap concurrency at what you can actually supervise (3–6).
• Nothing executes without the TUI. If transitions stop completing, or phase_age_secs climbs across the whole board, say so and stop.
• Never touch the user's checkout to get a merge through — no branch switch, no stash.
• Surface product decisions to the user rather than deciding them.
• Report honestly. A milestone with three failed tasks is a result; say it plainly.