jerryfane/gitmoot/gitmoot

Gitmoot Agent Skill

This root SKILL.md is kept as a raw compatibility entrypoint for agents and gitmoot.io/SKILL.md. The canonical Agent Skills package lives at skills/gitmoot/, with deeper reference files under skills/gitmoot/references/.

Gitmoot is a local-first coordinator for AI agents working across repositories, reviews, PR comments, and runtime workflows. Use this skill when the user wants PR-comment agent workflows, repo-scoped agent subscriptions, background daemon checks, Codex, Claude Code, Kimi Code, or omp agent startup, structured implementation plans, agent template inspection, custom prompt agents, job status, branch lock inspection, declarative pipelines, agent memory, routing telemetry, or runtime metadata.

Gitmoot's CLI evolves quickly. If the user names a Gitmoot feature or command that is not covered here, verify the live surface with gitmoot --help and the relevant gitmoot <command> --help before answering. If this compatibility entrypoint disagrees with the live binary, trust the live help and treat the skill text as stale documentation that should be refreshed.

For current-chat prompt import, "use <agent> here" means run gitmoot agent prompt <agent> and apply the returned prompt content in this current chat. This is prompt import, not true system-prompt injection. Do not route a "here" request through a background gitmoot agent ask unless the user explicitly asks for background execution, PR-comment routing, or job tracking.

For fast planning, "use the Gitmoot planner here" is the natural-language shortcut for gitmoot agent prompt planner. If the planner template is not installed, read and apply the packaged skills/gitmoot/agent-templates/planner.md instructions directly.

Agent templates are READ-ONLY installed data (#2204). Gitmoot can inspect and read them — gitmoot agent template list, gitmoot agent template show <id>, and gitmoot agent prompt <agent-or-template> to reuse an installed template in the current chat — but it cannot author, update, or distribute one. There is no draft, validate, add, export, publish, pull, remote, diff, revert, or update verb. A template that must change is edited or re-seeded in its agent_templates store row by hand.

For background work, keep Gitmoot's resource model explicit: repo checkout locks protect local checkouts, runtime session locks serialize delivery for the same Codex, Claude, or Kimi session, and branch locks protect implementation ownership. The daemon default is --workers 1; raise it only for independent runtime sessions or managed agent types with max_background greater than one.

For runtime selection, gitmoot agent start <name> --runtime <runtime> accepts codex, claude, kimi, or omp. Kimi Code is a first-class runtime adapter alongside Codex and Claude Code. To use it, run kimi login, then restart the Gitmoot daemon so it inherits the session. omp is the oh-my-pi CLI, a multi-provider routing harness: authenticate it once (interactively, via a provider key in the daemon environment, or through an auth broker) and restart the daemon so it inherits the credential. omp holds review/implement/ask but not produce, runs a fresh session per job and never resumes, and its implement jobs get a loud cross-family-review refusal because an opaque router has no model family. agent subscribe additionally accepts --runtime shell, whose session is a command (for deterministic tests).

For Gitmoot health or status questions, run the relevant read-only Gitmoot CLI checks and answer directly from the results. Mention gitmoot dashboard only after that answer, as a live monitoring follow-up. Do not start daemons, create agents, change subscriptions, update templates, or release locks unless the user asks for that action.

Before Acting

1. Check whether gitmoot is installed with gitmoot version.
2. Confirm GitHub CLI access with gh auth status before using PR workflows.
3. Detect or ask for the target repo before starting daemons, subscribing agents,

or routing jobs.

1. Do not start daemons, create agents, update agent templates, change

subscriptions, or release locks unless the user asks or the current task clearly requires it.

1. Prefer read-only status commands and answer directly before mutating Gitmoot

state or pointing the user to live monitoring.

1. Use gitmoot --help and subcommand help for version-sensitive features such

as pipeline, memory, router, runtime, dashboard web, session jobs, and heartbeats.

Install And Update

If gitmoot is not installed, install the latest beta:

curl -fsSL https://gitmoot.io/install.sh | sh

Verify the install and GitHub access before using Gitmoot:

gitmoot version
gitmoot update --check
gh auth status

Install runtime plugin guidance when the user wants Codex or Claude Code to discover Gitmoot from its plugin system:

gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor

Common Local Commands

gitmoot status --repo owner/repo
gitmoot events --repo owner/repo
gitmoot daemon start --poll 30s
gitmoot daemon start --session <root-job-id>
gitmoot daemon start
gitmoot daemon status
gitmoot daemon restart
gitmoot daemon stop
gitmoot dashboard --json
gitmoot dashboard --web [--addr 127.0.0.1:8080]
gitmoot plugin doctor
gitmoot runtime list [--json]
gitmoot agent list
gitmoot agent doctor <agent>
gitmoot agent heartbeat list [--agent <agent>]
gitmoot agent prompt <agent-or-template>
gitmoot agent run <agent> --repo owner/repo "question or review request"
gitmoot agent review <agent> --repo owner/repo --pr <number> "review request"
gitmoot agent ask <agent> --repo owner/repo "question or instructions"
gitmoot job list --repo owner/repo
gitmoot job show <job-id>
gitmoot job events <job-id>
gitmoot job gates <job-id>
gitmoot job gates clear <job-id> --need "<text>"|--all
gitmoot job open --agent <name> --repo owner/repo --type ask|review|implement [--title "..."]
gitmoot job close <job-id> --decision approved|changes_requested|blocked|implemented|failed [--severity P0|P1|P2|P3] [--summary "..."]
gitmoot job record (--agent <name> | --acting-role <role>) --repo owner/repo --type ask|review|implement --decision implemented [--severity P0|P1|P2|P3] [--summary "..."]
gitmoot report bug --job <job-id> --preview
gitmoot report bug --job <job-id> --create --yes
gitmoot lock list --repo owner/repo
gitmoot lock show owner/repo <branch>
gitmoot pipeline add <spec.yaml> [--enable]
gitmoot pipeline list [--json]
gitmoot pipeline run <name>
gitmoot pipeline show <name|run-id> [--json]
gitmoot pipeline resume <run-id> [--from <stage>]
gitmoot pipeline cancel <run-id>
gitmoot pipeline enable|disable <name>
gitmoot pipeline remove <name>
gitmoot job answer <job-id> "<question-id>: answer text" [--json]
gitmoot router summary [--repo owner/repo] [--action ask|review|implement] [--since 30d] [--json]

Gitmoot does not dispatch implementation (#2203). agent implement, --action implement, task run/task recover/task resume-work, repo auto-fix, and the implement heartbeat are gone; an implement delegation leg and a /gitmoot <agent> implement comment are refused. Seats implement in their own session and record it — 568 of the last 570 implement rows were already exactly that:

gitmoot job record --agent <seat> --repo owner/repo --type implement \
  --decision implemented [--pr <number> --head-sha <sha>] [--task <task-id>] \
  --summary "What changed and why."

Use gitmoot daemon start for the background daemon. Use gitmoot daemon run only when the user explicitly wants a foreground process. --repo owner/repo SCOPES the daemon to a single repo: it polls only that repo's PRs and claims only that repo's queued jobs. Omit --repo to supervise every enabled registered repo from one daemon (#581). Both daemon run and daemon start accept --session <root-job-id> (alias --root) to pin the worker to one orchestration run: it then runs only jobs whose root_job_id matches that value plus the root coordinator job itself. Claude auth lives in runtime-auth.env; rotate it with gitmoot auth set claude and clear it with gitmoot auth unset claude. Adapter builds read the file per delivery, so no daemon restart is needed.

Use gitmoot agent prompt <agent-or-template> when the user wants to reuse a Gitmoot agent prompt in the current chat. Use gitmoot agent run for coordinator delegation through a registered Gitmoot agent; Gitmoot will route to ask or review and own read-only worktrees, branch locks, and workflow advancement. To orchestrate an orchestra of agents, gitmoot orchestrate <agent> "..." [--repo R] is sugar for gitmoot agent run <agent> --background "...". Use gitmoot agent ask only for analysis, planning, or questions. Add --background only when the user wants a queued background job. This is the same agent registry and runtime adapter path used by PR-comment jobs; the plugin only helps the runtime discover this skill and does not replace the gitmoot CLI.

Use gitmoot pipeline when the workflow is a fixed, repeatable DAG declared in YAML rather than a model-driven decomposition. pipeline add validates and stores the spec, stage commands must emit gitmoot_result, blocked parks the run, and pipeline resume reruns the halted stage plus dependents.

Use gitmoot job answer <job-id> "<question-id>: text" to resume a job paused at awaiting_human; it routes through the same escalation-resume path the daemon's PR-comment answer verb uses.

Use gitmoot runtime list to inspect runtime metadata and gitmoot router summary for local observed routing telemetry. Router telemetry is advisory only and not a benchmark.

Use gitmoot workflow list, gitmoot workflow show, and gitmoot workflow note for external-coordinator workflow groups. Attach --workflow <label> to agent ask/run/review, orchestrate, or job open; orchestration descendants inherit the label automatically.

Use gitmoot report bug --job <job-id> --preview when a failed, blocked, or cancelled Gitmoot job needs a user-shareable bug report. Preview first by default. Create with --create --yes only when the user explicitly asks or the active workflow policy permits filing reports, then report the created or existing GitHub issue URL back to the user.

PR Comment Commands

Use GitHub PR comments as the public audit trail:

/gitmoot help
/gitmoot status
/gitmoot <agent> review [instructions]
/gitmoot ask <agent> [question]
/gitmoot retry <job-id>
/gitmoot cancel <job-id>
/gitmoot merge
/gitmoot resume <job-id> retry|continue|abort|answer [instructions]
@<agent> ask|review [instructions]

Template Agents

Start an agent against the built-in thermo review template:

gitmoot agent start thermo-review \
  --runtime codex \
  --repo owner/repo \
  --template thermo-nuclear-code-quality-review \
  --start-daemon

Coordinator recipes are built-in templates for the Orchestra pattern: a coordinator that fans work out to ephemeral workers (no pre-registration) and reconvenes them in one continuation. review-panel convenes a panel of diverse-lens reviewers over a PR and synthesizes their verdict; verifier is the minimal one-producer + independent-verify pair. Route any coordinator agent through a recipe with the --recipe flag on gitmoot orchestrate:

gitmoot orchestrate project-planner "Review PR #123 in this repo." --repo owner/repo --recipe review-panel
gitmoot orchestrate project-planner "Produce the export-feature migration plan and prove it is complete." --repo owner/repo --recipe verifier

Start an agent against an installed custom prompt template:

gitmoot agent start frontend-reviewer \
  --runtime codex \
  --repo owner/repo \
  --template frontend-reviewer \
  --role reviewer \
  --capability ask \
  --capability review