PR Comment Workflow

PR comments are the public coordination surface for Gitmoot.

/gitmoot help
/gitmoot status
/gitmoot ask planner Write a task-by-task plan for this PR.
/gitmoot planner review [instructions]
/gitmoot planner implement [instructions]
/gitmoot retry <job-id>
/gitmoot cancel <job-id>
/gitmoot merge
/gitmoot resume <job-id> retry|continue|abort|answer [instructions]

A bare @<agent> mention works as the same command (#389):

@planner ask What is blocking this PR?
@thermo-review review

Mentions are also routed on issue comments when the daemon runs with --watch-issues (on issues only the ask action is acted on).

Before parsing, Gitmoot removes triple-backtick and tilde fenced code blocks and closed inline backtick spans (including single-backtick spans).

Symptom: my command in a bulleted list did nothing. Any command line indented by four spaces or a tab is treated as code and will not run, including list-item continuation under a bullet or numbered item. For example, this command is ignored:

- Please run:

    @helper ask check the build

Put the command at column zero to run it:

@helper ask check the build

GitHub must then report that the comment author currently has write, maintain, or admin repository permission; unauthorized addressed commands are rejected without parsing their command text. Ordinary prose and code examples produce no reply. An authorized malformed command still produces a visible routing error. An unclosed fenced code block treats the remainder of the comment as code, so any later command is ignored without a reply.

/gitmoot merge replies with the observed outcome. A refusal names the cause and remedy: acting-role merge_rule, a required GitHub merge queue, a missing current-head approval, or an approval bound to an ancestor head. With merge_gate.auto_merge = false, no earlier gitmoot/merge-gate marker is expected. Its absence does not mean the gate passed; the explicit command runs the gate and reports that fact.

On a pull request, a line that is addressed by shape but names an action Gitmoot does not implement produces no reply — it is recorded in the daemon log instead. Source code reaches this path routinely, because a decorator or attribute line such as @Published private(set) var state = .uninitialized matches the @<agent> <action> mention form outside a code fence. A recognized action given a bad argument (for example @helper retry with no job id) still replies, so genuine command feedback is preserved.

On an issue, only ask is acted on, so any other action — recognized or not — is dropped before dispatch with no reply and no log entry. When an issue comment appears to have been ignored, the daemon log will not explain it.

The daemon polls GitHub, applies that author gate, queues jobs, invokes the selected agent runtime, and posts attributed results back to the PR. The selected agent's runtime can be codex, claude, kimi (Kimi Code CLI), or omp.

Expected result comments include the agent identity, runtime, the template when one is attached, and the job id:

> Agent: `planner`
> Runtime: `codex`
> Template: `planner`
> Job: `local-ask-...`

The Template line is present only when the job ran with a template. The body then continues with the Decision and Summary, plus any Findings, Changes Made, Tests Run, Needs, and Delegations the agent reported. If delivery of a stored result fails during workflow advancement, the durable job state and comment both report blocked rather than repeating an agent's earlier implemented decision. The original summary remains visible and the delivery failure appears under Diagnostics. A downstream precondition such as pending CI does not replace a successfully delivered job's terminal result.

Use gitmoot job list --repo owner/repo and gitmoot events --repo owner/repo to inspect routing state.

Resuming paused orchestrations

When a delegation tree pauses for a human — an escalate_human failure pause, or an ask-gate human_questions pause — the daemon @-tags the escalation handle in a comment with the resume instructions, and a comment on the tree's open PR resumes it. Resume commands are PR-comment-only: the issue watcher routes only the ask action, so /gitmoot resume posted on an issue is silently ignored — always resume on the tree's open PR:

/gitmoot resume <coordinator-job-id> retry [instructions]   # re-run the failing leg
/gitmoot resume <coordinator-job-id> continue               # proceed the continuation
/gitmoot resume <coordinator-job-id> abort                  # graceful finalize
/gitmoot resume <coordinator-job-id> answer q1: <value>     # answer an ask-gate question

See the result contract for the escalate_human / ask-gate pause semantics, TTLs, and how a paused tree announces itself on the PR.