Managing tasks

A task is one branch, one git worktree and one state, tracked by PABLO until the pull request is merged. This page covers everything you can do with one, from starting it to closing it.

Start a task#

From an issue#

bash

pablo task:start https://github.com/acme/wallet-kit/issues/45
pablo task:start https://acme.atlassian.net/browse/PIM-123

PABLO matches the link against every project's issue tracker (and, for GitHub issues, against each repository's remote). If nothing matches, it stops with an error rather than guessing. You can also start a task from the dashboard, which accepts an issue key such as PIM-123 too.

What happens next:

a branch named after the issue, such as pim-123 (see branch names), and a worktree created from the remote primary branch;
the task-analyst agent, launched once for this task;
the project's startup script, if it has one, in parallel;
the task enters 🔨 in-progress.

Starting the same issue twice reuses the existing task instead of creating a second one.

From a prompt#

bash

pablo task:start --project wallet-kit "fix callback verification"

For work without a ticket. The branch name comes from a short AI summary of your prompt (for example wk-fix-callback-verification), and task-analyst works from the prompt instead of an issue.

If your prompt mentions a Jira or Linear key belonging to one of your projects (“fix the export per PIM-123”), PABLO treats it like the issue link and names the branch pim-123.

See your tasks#

bash

pablo task:list            # instant, from the poller's cache
pablo task:list --live     # fetch fresh data from GitHub and your tracker
pablo task:list --refresh  # run the poller first, then list

The list is split in two tables:

💭 Waiting for feedback: tasks that need you right now. A task lands here when it is in in-progress, ci-red, request-changes or testing-failed, an agent finished and is waiting for you (💭), and no agent is still working (🏃).
Other tasks: everything else, including tasks an agent is still working on. Tasks waiting on reviewers or QA live here: it's someone else's turn.

Columns: branch and project, PABLO state, the linked issue and its title (or the prompt summary), the tracker's own status, the pull request (📬 open, 📪 draft, ✅ merged), and agent activity such as 🏃 1 · 💭 1. Rows are sorted by state, most urgent first:

🚨 testing-failed · 🧪 needs-testing · ✅ approved · 🔁 request-changes · 👀 waiting-review · 🔴 ci-red · 📝 draft · ⏸️ waiting · 🔨 in-progress

The dashboard shows the same two tables, built from the same rules, so the terminal and the browser never disagree.

Ship your work#

When the work is ready, run this in an OpenCode, Claude Code or Copilot session inside the task's worktree:

/pablo-commit-and-pr

It commits your changes, pushes the branch, opens the pull request as a draft (with a description written in your project's pr_description_locale) if there isn't one yet, and moves the task to 📝 draft. From there the poller takes over.

It's the only way back into draft. A plain git push never changes a task's state.
It works from in-progress, ci-red, request-changes, testing-failed, waiting-review and approved, and refuses outside a PABLO worktree.
With nothing to commit, it stops and does nothing. If you committed by hand, use /pablo-commit-and-pr --force: it skips the commit and runs the rest.
It never changes your git identity: commits use whatever user.name and user.email git finds in your own configuration, and it stops with git's error if there are none.

Pause a task#

bash

pablo task:waiting   # run inside the task's worktree; run it again to resume

The first call saves the current state and switches to ⏸️ waiting; the second restores it. While paused, the poller only watches for a merge, and worktree sync keeps running. Events that happened during the pause (a QA label, for example) are handled after you resume, not lost.

You can't pause from request-changes or testing-failed: those states are already waiting for you.

Force a state#

bash

pablo task:state waiting-review               # runs the state's usual actions
pablo task:state needs-testing --no-trigger   # only records the new state

An escape hatch for when reality and PABLO disagree. Typical case: a reviewer's old “changes requested” blocks the task while they're on holiday; force it past. Forcing a state runs exactly what the automatic transition would (launching an agent, flipping the pull request…); --no-trigger skips that, except for waiting, which always saves the state to come back to.

Forcing needs-testing is refused when the project has no QA step (testing.enabled: false).

The dashboard does the same with its Force state button.

Adopt an existing worktree#

bash

cd ~/dev/wallet-kit-worktrees/my-branch
pablo task:attach draft

Turns a worktree you created yourself into a PABLO task, starting in the state you choose. It only writes the task record: no branch, no worktree, no agent, no pull request change. Requirements: run it inside a worktree (not the main checkout), on a branch that isn't the primary one and isn't already a task, in a repository that belongs to a project (or pass --project <name>).

Relaunch an agent#

bash

pablo task:relaunch                       # everything the current state launches
pablo task:relaunch --only=task-analyst   # just one of them

Fires the current state's agents again (and the startup script in in-progress). Accepted --only values: task-analyst, startup-script, ci-analyst, pr-feedback, task-feedback. PABLO already retries launches that never started on its own; this is for when you want to force it. See Troubleshooting.

Help with CI#

pablo task:retrigger-ci: Re-runs the latest GitHub Actions run of each workflow on the task's branch, and puts the pull request back in draft while they run.
pablo task:skip-ci: From ci-red only: ignores the failing checks and moves the task on to review. CI is ignored until the next /pablo-commit-and-pr. The dashboard shows a Skip CI button on ci-red tasks.

A check that never finishes (a manual deployment gate, for example) is better excluded for good with ci.ignore_checks.

Close a task#

Automatically, on merge. When the pull request is merged, the poller deletes the worktree and the task. It never merges or closes pull requests itself. If an agent is still running on the worktree, closing waits: the task shows ✅ merged until the agents finish, and closes on a later poll. Merges are detected even for paused tasks.

By hand, to abandon or clean up a task:

bash

pablo task:close                              # the task of the current worktree
pablo task:close pim-123                      # any task, from anywhere
pablo task:close pim-123 --project acme-pim   # when several projects have that branch

It refuses while agents are active (add --yes to close anyway), works even if the worktree folder is already gone, and moves you to the project's main checkout before deleting the worktree, so your shell isn't left in a deleted folder.

Inspect a task#

bash

pablo task:info current   # the current worktree's task record, as JSON

Useful for scripts and for checking exactly what PABLO knows: state, issue, pull request number, timestamps. The fields are described in Storage.