Coordinate parallel tasks

You can improve several parts of a project at once without turning every handover into another job for you. Each separate task gets a worktreeWorktree↗A separate working copy and branch for one effort.: its own workspace and branch. discerndiscern↗A tool that installs and runs an agent development practice in a project. keeps the finished tasks that are waiting to land in one list, tells dependent agents when the work they need is ready, and explains any wait in one sentence.

This guide follows the work after you have agreed a task plan. If you are still deciding how to divide an idea, start with Delegate substantial work.

Suppose you are improving an app that keeps a reading list. One task adds search, another improves the phone layout, and a third updates the help. Your agent has checked which files they touch and proposed how to handle anything shared.

You can ask:

Start the agreed reading-list tasks in their own worktrees. Have the help task wait for the search result it needs. Keep track of where each task is working, and explain any decisions that need me.

Your project should already be set up with discern. If it uses a local database or similar service, the agent also checks that each worktree can have the separate resources it needs.

Your agent uses discern_start from the main checkout and moves each task into the path the result returns. The command-line equivalent for one task is:

discern start --name reading-search

The name helps you recognize the work; discern adds a unique suffix. The returned branch and absolute path identify the actual task. A second independent task gets a different worktree. Helpers working under one coordinating agent can share that agent's effortEffort↗One task carried through implementation and review: the work a worktree, its branch, and its submission all belong to., with their file assignments kept separate.

Keep each effort in its worktree through review and resumed sessions. An idle or clean worktree still belongs to its existing task. If a task cannot start, its result explains what needs attention; the agent should resolve that condition rather than move into another task's workspace.

Separate files are only part of a working environment. Each copy of an app may need its own development-server port or test database. Otherwise, one task's test could change the data another task is using.

discern prepares the resources declared for each worktree. Your agent can inspect them with discern identity --resources and use their returned values. You can ask it to check this without choosing port numbers or writing database setup commands yourself:

Check that these tasks can run the app and its tests side by side. Tell me if any shared service still needs a decision or setup from me.

If a required resource fails to start, discern leaves the unfinished setup visible and reports the failed command. The agent follows that recovery before continuing. The configuration reference contains the resource and environment settings.

The fleet is the set of task worktrees in the repository. Ask your agent for an account of what is moving and what needs you:

Check the fleetFleet↗The project's collection of task worktrees.. Tell me which tasks are progressing, which are waiting on another task, and which need my decision. Explain any overlap that could change our plan.

For a direct view, run this from the main checkout:

discern status

From inside a task, discern status --all includes the fleet. It reports worktree state and files changed by more than one task; it does not need to infer progress from chat summaries. Bare discern opens the desk in an interactive terminal. discern enter opens a child shell in a selected worktree when you want to inspect it yourself.

Treat file overlap as a reason to look closer. Search and the phone layout might both change the reading-list screen. The agent should explain whether the changes fit together, need an agreed order, or are better handled by one task.

When an earlier change lands on the trunk, the shared branch usually called main, other tasks can bring it into their own worktrees with discern_update:

discern update

The result names overlapping files for the agent to re-read. Git may combine two edits successfully even when their behavior disagrees. For example, search could add a button that the phone layout has no room for. Trying the combined screen is how you catch that problem.

Each task finishes through discern_done on its committed work. That runs the project's configured checks, called the gateGate↗The configured checks a change must satisfy for ordinary completion., and records Proof for the exact commit in the worktree. Follow the completion result's next action; it distinguishes evidence, pending work, and permission to land.

A finished task enters the landing queue when its agent submits it with discern accept. The submission names the exact commit and the Proof that covers it, so nothing waits in the queue that its agent is still changing. discern status from the main checkout, the deskDesk↗An interactive view of the project's tasks and the actions available for them., and the acceptance preview all show the same list: tasks you have pre-authorized first, in the order you granted them, then tasks waiting for your decision, in the order they were submitted.

Each line names the task's branch and, when it cannot land yet, the reason:

A submission the shared branch overtook does not wait on its author: its landing checks the combined version in a fresh integration worktreeIntegration worktree↗A disposable worktree a landing creates for itself when the trunk moved after a submission's Proof. and lands the exact commit it proved, and its queue line says the composition is what landing will do. A task you pre-authorized lands with its agent's next discern accept. A task that failed its checks, or that its agent never submitted, is not in the list. Approving one task approves that task alone; if the help task depends on search, each needs its own permission.

You do not have to land tasks in the order they finished. Decide about each one when you are ready; a task waiting for you does not block an independent task you have approved. When you land a selected task with discern accept --target, the remaining submissions follow in the queue's own order, each under its own grant, and the walk stops at the first task that still needs you — the result reports every landing it attempted.

Sometimes a later task needs a finished feature before you are ready to add it to the shared branch. The help writer might need to try search while you are still reviewing it.

Ask for that arrangement directly:

Let the help task build on the search task once it has current Proof. Keep the combined work available for review, and explain which approvals are still needed before it lands.

The earlier agent commits its work and runs the gate. The dependent agent uses discern_await to wait for current Proof, then follows the returned instruction to start from or update from the observed commit. That exact commit remains usable even if the earlier branch name later disappears.

The later agent verifies that the expected behavior is present and runs the full gate on the combined result. Starting from a checked change does not establish that the combination passes. Each task still lands through its own submission and permission: the search task lands first, and the help task's agent brings the landed trunkTrunk↗The shared branch that accepted work joins, usually main. into its worktree before landing its own work.

Wait for another task explains the choice between building on checked work and waiting for it to land.

Several agents can write at once. How many can run the project's tests at the same time is bounded by [gate].concurrent_test_runs, the setting the project chose during setup. A test run that reaches the limit waits its turn while the other checks continue, and the result names the task holding the slot and how long its tests usually take.

That sentence is the fact to act on. Raise the limit only after checking that the machine can carry another run. Agents run direct test commands through discern queue -- <test-command> so parallel tasks share the cap. A test runner still controls how many workers it uses inside its own run.

If the app and a shared library live in different repositories, each repository has its own configuration, worktrees, checks, and landing decisions. Ask the agent to name the commit or package version that connects the tasks and explain how it will test them together.

There is no single Proof or landing permission covering both repositories. You can still direct the overall result from one plan, with each part's evidence kept clear.

A landing removes the task's worktree, its resources, and its branch when the branch holds nothing beyond what landed. When the worktree stays, the landing result and discern status say why in one sentence and name the command that finishes cleanup: discern done then discern accept for commits the agent added after submitting, or discern worktree prune when the removal could not complete.

For worktrees left behind, ask your agent to inspect what can be removed and show the plan. The command-line preview from the main checkout is:

discern worktree prune --dry-run

A preview lets you see the affected paths before removal. If cleanup reports files or ownership it cannot account for, follow the reported recovery. A completed landing remains landed even when its checkout cleanup needs attention.

An earlier stageStage↗A group in the order the gate runs work. fully included in a later live branch may be offered for reclaim. This removes the eligible checkout while keeping its branch as a route back to the committed work.

Parking keeps committed work and its task wording while freeing the checkout and its resources. It is useful when a task is paused for more than a short dependency wait:

Park this task so we can return to it later. Show me the plan first, and make sure the work I want to keep is committed.

The preview is discern worktree park <id-or-path> --dry-run. Parking requires a clean checkout on a named task branch. Status then lists the branch under Work without a worktree. Your agent can resume it with discern start --from <parked-branch>; the resumed task needs fresh Proof and landing authorityLanding authority↗Permission for a particular change to join the trunk..

You should be able to tell what each task delivers, which result it depends on, whether it is waiting in the landing queue, and what comes back for your review. The agents carry the workspace setup, waits, updates, and checks. Use Finish and land a change to review the outcomes and follow what reaches the shared branch.

For more detail, Worktrees and the trunk explains the model, worktrees and status lists the fields, and worktree recovery covers interrupted setup or cleanup.