/synthex:next-priority/synthex:next-priority

#What it does, end-to-end

/synthex:next-priority/synthex:next-priority is the command you re-run during the build phase. Each invocation:

1. Reads the implementation plan at docs/plans/main.md (configurable via documents.implementation_plan).
2. Picks the next batch of unblocked, non-overlapping tasks. Up to your concurrent_tasks budget. The selection rules:
   • Status is not done, blocked, or awaiting [H].
   • All listed dependencies are satisfied.
   • The task is in the current milestone — phase boundaries are never crossed in a single run.
3. Searches the codebase with sub-agents for existing implementations relevant to the selected tasks, so nothing gets built twice.
4. Marks the selected tasks in progress in the plan immediately, so concurrent runs (or future ones) don't re-pick them.
5. Gives each task its own checkout on branch {worktrees.branch_prefix}<task-id>-<slug>. On Claude Code with the default .claude/worktrees base path, each Tech Lead is spawned with the Agent tool's isolation: "worktree" and renames its branch to the task branch. Elsewhere, Synthex runs git worktree add {worktrees.base_path}/{worktrees.branch_prefix}<task-id>-<slug>. With cloud execution each worker gets its own VM, and with host workspaces each one gets an Orca or Herdr child workspace instead.
6. Delegates each task to a Tech Lead instance scoped to its worktree. The Tech Lead workers run in the background so the batch really runs in parallel; advisory and gate agents whose verdict is needed before continuing run in the foreground. Each Tech Lead writes its own commit messages following the project's convention (git.commit_convention).
7. Monitors completions, validates acceptance criteria, merges each task (fast-forward first, merge commit if that's not possible), and removes the task's worktree immediately after its merge — before touching the next task. A worktree with uncommitted changes is never force-removed; the command stops and reports the path instead.
8. Updates the plan with completion notes — including the test file + test name for each [T] criterion, the user's approval record for each [H] criterion, and (under --auto-decide) a record of each decision taken without asking.

#Parameters

#Model profiles

Each spawned agent's model and effort resolve in this order: the --profile flag, then models.agents.<name> in your config, then the models.profile tier, then the agent's own default. balanced is the shipped default; economy and premium adjust only the agents that differ from it. On Claude Code the resolved model is applied per spawn; on other hosts it's advisory, used only where the host supports choosing a model per sub-agent. A running standing review pool is unaffected — pools never re-spawn their reviewers.

#Cloud execution

By default every Tech Lead worker runs in a local git worktree. You can run them as cloud agents instead, each on its own VM and branch, so a large batch doesn't compete for your machine. See Cloud agents for setup and host support.

The execution environment is resolved before any worktree is created:

1. --local wins over everything (including --in-cloud or --in-workspace, if passed).
2. --in-cloud forces cloud for this call, and --in-workspace forces host workspaces. Passing both is refused with a one-line error.
3. Otherwise next_priority.execution_environment in .synthex/config.yaml (local, cloud or workspace).
4. Otherwise local.

/synthex:next-priority --in-cloud --loop

What changes in cloud mode:

• No local worktrees. Each worker forks from your remote-tracking base branch (usually the current branch's upstream), commits on the same {worktrees.branch_prefix}<task-id>-<slug> branch name it would use locally, and pushes it.
• Merging fetches the worker's branch (or its PR head) and merges it with the same fast-forward-then-merge-commit policy. Acceptance-criteria validation and the [H] gate are unchanged.
• Unpushed work refuses. Cloud workers can't see your uncommitted or unpushed local changes. If the selected tasks depend on them, the command stops before spawning and asks you to commit and push (or re-run with --local).
• Host support. Cloud mode needs a host whose sub-agent tool can launch cloud workers (Cursor today). Anywhere else the command prints Cloud execution is not supported on this host — falling back to local worktrees. and runs locally.

#Host workspaces

If you run Synthex inside Orca or Herdr, --in-workspace (or execution_environment: workspace) launches each Tech Lead as its own agent session in a child workspace. The workspace manager owns the checkout, so nothing is created under worktrees.base_path, and you can open any task in the tool's UI.

/synthex:next-priority --in-workspace --loop

• Opt-in only. Detecting Orca or Herdr never switches it on.
• Fresh checkouts. Child workspaces start from your current branch's committed state. If the selected tasks need uncommitted edits, the command stops and asks you to commit first.
• You answer the questions. If a worker is blocked on a prompt or approval, Synthex tells you which workspace needs you and never answers for you.
• Same merge, then cleanup. The task branch is merged with the usual policy, then the child workspace is removed through orca worktree rm or herdr worktree remove.
• Fallback. Conductor (detected, but its CLI can't create local workspaces) and every other session print Host workspaces are not supported here (<host>) — falling back to local worktrees. and run locally.

See Host workspaces for the full flow and the Claude Code worktree isolation used by local runs.

#When to run it

You re-run /synthex:next-priority/synthex:next-priority after every batch you finish. Some teams run it once per work session; others pass --loop to iterate it autonomously until the plan is complete or a configured completion-promise fires — see Native looping.

If your plan has lots of [H] criteria, you'll bottleneck on review attention rather than agent throughput. Drop concurrent_tasks so the review queue stays manageable.

#Common scenarios

#"All remaining tasks are blocked"

The command exits without picking up work and tells you which tasks remain and why. This is the correct behavior — it does NOT emit the --loop completion promise in this case, because the plan isn't complete; it's waiting on you.

#"A task fails or the Tech Lead gets stuck"

The blocker is captured in the task's plan record, the worktree is preserved for inspection (it is NOT deleted on failure — your in-progress work is safe), and the orchestrator moves on to other actionable tasks. Resolve the blocker on your own time; the next invocation picks up the unblocked work.

#"Pre-commit hook fails"

The Tech Lead diagnoses and fixes the underlying issue. Pre-commit hooks are never skipped — --no-verify is forbidden. If the hook reflects an outdated rule, fix the rule (and write the ADR to record the change), don't bypass it.

#"Merge conflict during fast-forward"

If main has advanced beyond the worktree's branch point, fast-forward fails. The orchestrator tries a merge commit; if that requires judgment, it pauses and reports — your git history is never modified silently.

#What it does not do

• Cross phase boundaries in a single session. It completes the current milestone's tasks before advancing to the next, and never crosses a phase boundary in one session.
• Pick more tasks than the concurrency budget. If you set concurrent_tasks: 1, the command runs strictly sequentially.
• Skip review. The Tech Lead reviews every change — including specialist output — before accepting it, and runs security review as a gate on security-sensitive changes. Nothing merges until [T] criteria have linked, passing tests and [H] criteria are approved.

See Parallel execution for the worktree isolation model and Quality gates for the merge contract.

#Native looping

Pass --loop to iterate this command until the implementation plan is complete (or --max-iterations is reached). This is Synthex's own looping, not the harness /loop skill. State lives in .synthex/loops/<loop-id>.json so the loop survives session restarts and crashes. See the Native looping framework explainer for the iteration contract.

Emission rule. The loop terminates when the agent emits <promise>{completion-promise}</promise> — and it does so only when either:

• Every task across all milestones and phases has status done, or
• exit_on_milestone_complete is true and every task in the current milestone is done.

The promise is not emitted just because no actionable work was picked up this iteration. Pending [H] reviews, blocked tasks, or unsatisfied dependencies all keep the loop alive. An idle iteration waits in place until the plan file changes (or a backoff timeout passes), then the next iteration picks up newly-unblocked work as you finish reviews in a parallel thread.

On Claude Code, setting native_looping.engine: workflow hands the "what's next / is it done?" decision to a read-only workflow run — see Workflow engines.

Example. Drive a plan to completion overnight, checkpoint at each milestone:

/synthex:next-priority --loop \
  --completion-promise "PLAN_DONE" \
  --max-iterations 30 \
  --name release-1 \
  exit_on_milestone_complete=true

Resume in a new session if you close Claude Code mid-loop:

/synthex:loop --resume release-1

#Auto-decide

Normally, when the delegated Tech Lead reaches a decision it doesn't have unilateral authority over — a high-impact architecture or technology choice, or a genuinely ambiguous requirement — it stops and asks you via an interactive prompt, even when it already has a clear recommendation. That's the right default for an attended session, but it stalls an unattended --loop run: the loop can't advance past a pending question.

Pass --auto-decide to change that. When set, the Tech Lead takes its own recommended option at those decision points instead of asking, and records the decision — along with the alternatives it considered and its reasoning — in the implementation plan, so you can review and, if needed, reverse it later.

This does not weaken review. [H] (human-validated) acceptance criteria are a separate, unconditional gate: they always require your explicit approval before a task merges, with or without --auto-decide. The flag only removes discretionary escalations that already have a recommendation attached — never a formal sign-off requirement. See Native looping for how this interacts with the loop's own [H]-gate guarantee.

The directive also propagates to any sub-agent the Tech Lead delegates to — otherwise the same blocking question would just resurface one level down.

#The auto-decide hook (Claude Code)

On Claude Code, --auto-decide also arms a PreToolUse hook on AskUserQuestion (scripts/auto-decide-gate.sh) for the current session only. It is disarmed when the command finishes — under --loop, when the loop ends for any reason. Other sessions are never affected. When every question in a prompt has exactly one option labelled (Recommended), and none mentions [H], the hook answers with that option and the dialog never opens. Any other question reaches you as usual: no recommendation, two recommendations, an [H] approval, or anything the hook can't parse. The hook fails open, so a problem in the hook means you get asked.

On other harnesses the hook isn't available. The Tech Lead still takes recommended options itself and records them the same way.

#Auditing auto-decisions

Every auto-decision, whether the hook answered it or an agent took it without asking, is recorded so you can review it:

• A log line (hook-answered decisions only) in .synthex/auto-decide/<session_id>.jsonl with the question, the choice, the alternatives, and the HEAD commit before the decision. The log is local to your machine and stays after the session ends.

• A commit trailer of the form Auto-Decision: <question> => <choice> on the first commit after the decision. Find them with:

  Copy

  git log --grep '^Auto-Decision:' --format='%h %(trailers:key=Auto-Decision,valueonly)'
  git checkout <sha>^   # the code before that decision

  Merge with --ff-only or a merge commit, not a squash, so the trailers survive.

• A bold section at the top of the PR description, before the summary:

  Copy

  **Auto-decisions (made without asking — please review):**
  
  - **Which cache?** → Redis (alternatives: Memcached, none) — `a1b2c3d`

  If nothing was auto-decided, the PR says **Auto-decisions: none.**

[H] approval questions always include [H] in their text and never carry a (Recommended) option, so the hook never answers them.

Example. Drive a plan overnight without stopping on every architectural judgment call:

/synthex:next-priority --loop \
  --completion-promise "PLAN_DONE" \
  --max-iterations 30 \
  --auto-decide

Review what it decided on your own time. Start with the Auto-decisions section at the top of each PR, or scan the plan for the autonomous-decision notes left alongside each task's completion record (each one names its trailer commit).