# Gitmoot Full LLM Context

This file is generated from canonical Gitmoot Markdown sources. Prefer
https://gitmoot.io/llms.txt for a concise index and this file when an agent
needs fuller local workflow, CLI, plugin, safety, and result-contract context.

---

# Source: README.md

<p align="center">
  <img src="docs/assets/gitmoot-hero.png" alt="Gitmoot coordinates local agent runtimes through GitHub pull request workflows" width="900">
</p>

# Gitmoot

Local-first multi-agent coordination for GitHub pull request workflows.

[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-black.svg)](./LICENSE)
[![GitHub release](https://img.shields.io/github/v/release/jerryfane/gitmoot?include_prereleases&color=black)](https://github.com/jerryfane/gitmoot/releases)
[![Go module](https://img.shields.io/badge/go-module-black.svg)](./go.mod)

Gitmoot lets humans and AI agents collaborate through the place software teams
already audit work: GitHub pull requests. It runs on the user's machine, keeps
workflow state in local SQLite, routes PR comments to registered agent
runtimes, and writes the agent's work back into the repo and PR discussion.

V1 is intentionally local-only. There is no hosted dashboard, webhook receiver,
cloud runner, or remote control plane.

## Why Gitmoot

AI agents can already edit code, review diffs, and run local tools. The hard
part is coordinating that work across sessions without losing the human audit
trail. Gitmoot makes the repository and its pull requests the shared surface:

- PR comments become agent tasks, review requests, retries, and merge signals.
- Local SQLite records agents, repos, jobs, goals, tasks, PRs, and branch locks.
- Runtime adapters keep Codex, Claude Code, and future runtimes behind the same
  Gitmoot agent model.
- Agent Templates and job snapshots make agent instructions explicit and reproducible.
- Humans can follow progress from GitHub while agents keep working locally.

## How It Works

```text
GitHub PR comments/state
  -> local gitmoot daemon
  -> local SQLite state machine and job mailbox
  -> registered runtime adapter
  -> Codex, Claude Code, shell, or another agent runtime
  -> GitHub PR comments, statuses, branches, PRs, and merges
```

The core primitive is a runtime-neutral Gitmoot agent, not a Codex-specific
session. Codex and Claude Code are adapters behind the same internal runtime
contract.

## Install

```sh
curl -fsSL https://gitmoot.io/install.sh | sh
gitmoot version
gh auth status
```

Install runtime plugin guidance when you want Codex or Claude Code to discover
Gitmoot's Agent Skill from their plugin systems:

```sh
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor
```

The plugins are discovery and guidance surfaces. The `gitmoot` CLI and local
daemon remain the execution path.

## Quick Start

From a project checkout:

```sh
gitmoot init
gitmoot repo add owner/repo --path . --poll 30s
gitmoot doctor --repo .
```

Start a Gitmoot-managed Codex agent and daemon:

```sh
gitmoot agent start project-planner \
  --runtime codex \
  --repo owner/repo \
  --path . \
  --template planner \
  --start-daemon
```

For fast planning in the current Codex or Claude chat, ask the runtime:

```text
Use the Gitmoot planner here. Write the implementation plan.
```

That uses the same `planner` template as the background agent, but imports the
prompt into the current chat instead of creating a Gitmoot job.

Ask the registered background planner when you want a queued Gitmoot job:

```sh
gitmoot agent ask project-planner --repo owner/repo --background "Write the implementation plan and goal file."
gitmoot job watch <job-id>
```

Background jobs are conservative by default. The daemon starts with one worker,
runtime session locks serialize jobs for the same Codex or Claude session, repo
checkout locks protect local checkouts, and branch locks protect implementation
ownership.

Route work through PR comments:

```text
/gitmoot project-planner ask Write a task-by-task implementation plan for this PR.
/gitmoot thermo-review review
/gitmoot retry <job-id>
```

For the full walkthrough, see [docs/local-workflow.md](docs/local-workflow.md).

## Core Concepts

- **Repo**: a GitHub repository plus local checkout path that Gitmoot is allowed
  to monitor and mutate.
- **Daemon**: the local background process that polls GitHub PRs and routes
  queued jobs.
- **Agent**: a named Gitmoot identity with repo access, role, capabilities, and
  a runtime adapter.
- **Runtime adapter**: the bridge from Gitmoot jobs to Codex, Claude Code,
  shell commands, or future runtimes.
- **Template**: cached prompt content attached to an agent and snapshotted into
  each job.
- **Job**: a routed unit of work created from a PR comment, local ask, task run,
  retry, or merge action.
- **Goal and task**: Markdown implementation plans imported into local Gitmoot
  state with `gitmoot goal import`.
- **Branch lock**: local coordination state that prevents multiple agents from
  racing on the same branch.

## Common Workflows

### Planner Agent

Gitmoot includes `planner` for structured implementation planning
and standard goal-file writing.

```sh
gitmoot agent template update planner
gitmoot agent start project-planner \
  --runtime codex \
  --repo owner/repo \
  --path . \
  --template planner \
  --start-daemon
```

### Review Agent

Gitmoot includes `thermo-nuclear-code-quality-review` for strict review-only
work.

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

Ask it from a PR comment:

```text
/gitmoot thermo-review review
```

### Custom Prompt Agents

Custom agent templates let you keep a local template file and bind its
snapshotted instructions to any Gitmoot agent.

```sh
mkdir -p agents
gitmoot agent template draft frontend-reviewer --output agents/frontend-reviewer.md
$EDITOR agents/frontend-reviewer.md
gitmoot agent template validate agents/frontend-reviewer.md
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
gitmoot agent start frontend-reviewer \
  --runtime codex \
  --repo owner/repo \
  --template frontend-reviewer \
  --role reviewer \
  --capability ask \
  --capability review
```

After editing the template file, refresh the cached snapshot:

```sh
gitmoot agent template diff frontend-reviewer
gitmoot agent template update frontend-reviewer
```

Template updates are versioned locally. `gitmoot agent template show <id>`
prints the current version, content hash, source commit, and promotion state.
Agents use the current promoted version by default, or a pinned version when
configured with a reference such as `--template frontend-reviewer@v1`.
Queued jobs keep the exact template content snapshot they were created with.

Discover templates by metadata:

```sh
gitmoot agent template list --runtime codex --output goal_file
gitmoot agent template list --tag review --capability ask
gitmoot agent template show frontend-reviewer
```

Reuse a custom agent prompt in the current Codex or Claude chat without
starting a background job:

```text
Use frontend-reviewer here. Review this diff.
```

The runtime should load the prompt with:

```sh
gitmoot agent prompt frontend-reviewer
```

### Template Capture

Template capture turns a useful current Codex or Claude chat workflow into a
reusable agent template. Capture happens in the current chat from visible
conversation context and inspected files; Gitmoot does not read hidden model
state or runtime memory.

Draft a blank structure when starting from scratch:

```sh
gitmoot agent template draft release-planner
```

Or ask the current chat to fill the structure from the visible session:

```text
Use Gitmoot to capture this session as agent template release-planner. Draft only.
```

Review the draft before installing it:

```sh
gitmoot agent template validate .gitmoot/templates/release-planner.md
gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
gitmoot agent prompt release-planner
```

Installed custom templates are snapshots. After editing the source file, run
`gitmoot agent template diff <id>` and `gitmoot agent template update <id>`.

### Jobs, Locks, And Recovery

```sh
gitmoot status --repo owner/repo
gitmoot events --repo owner/repo
gitmoot job list --repo owner/repo
gitmoot job show <job-id>
gitmoot daemon logs
gitmoot lock list --repo owner/repo
gitmoot lock release owner/repo <branch> --owner <agent>
```

### SkillOpt Exchange

```sh
gitmoot skillopt review create --template <id> --repo owner/repo --run <run-id>
gitmoot skillopt review item add --run <run-id> --item <item-id> --baseline baseline.md --candidate candidate.md [--title text]
gitmoot skillopt review create --template <id> --repo owner/repo --run <run-id> --mode explore --options 4
gitmoot skillopt review item add --run <run-id> --item <item-id> --option a=option-a.md --option b=option-b.md [...]
gitmoot skillopt review status --run <run-id>
gitmoot skillopt export --run <run-id> --output training.json
gitmoot skillopt import --file candidate.json [--artifact-dir artifacts]
gitmoot skillopt candidate list [--template id]
gitmoot skillopt candidate show <version-id>
gitmoot skillopt candidate promote <version-id>
gitmoot skillopt candidate reject <version-id> [--reason text]
gitmoot skillopt feedback markdown export --run <run-id> --output .gitmoot/evals/<run-id>
gitmoot skillopt feedback markdown import --packet .gitmoot/evals/<run-id>
gitmoot skillopt feedback github publish --run <run-id> [--repo owner/repo] [--pr <number>]
gitmoot skillopt feedback github sync --run <run-id> [--repo owner/repo] (--issue <number>|--pr <number>)
```

Create a review run, add saved baseline/candidate outputs as review items,
export a Markdown or GitHub feedback packet, import the completed feedback, then
export `training.json` for a future external `gitmoot-skillopt` optimizer.
Use ranked exploration when the template needs broad search: start with
`--mode explore --options 4` to `6`, rank every option, record useful/rejected
traits, then narrow into `refine`, `distill`, and finally A/B `validate`.
`skillopt review status` reports ranking stability and the recommended next
mode, but the recommendation is advisory only.
Dry-run optimization validates the contract without model calls:

```sh
gitmoot-skillopt optimize \
  --training-package training.json \
  --artifact-root ~/.gitmoot/evals/blobs \
  --out-root .gitmoot/skillopt/run-2026-05-31 \
  --candidate-output candidate.json \
  --dry-run
```

Before real model-backed optimization, run `gitmoot-skillopt optimize --help`
and verify required model/backend environment variables for the installed
optimizer version. Imported candidates stay pending until a human review
workflow promotes them.
When a candidate package includes new artifact manifest entries, pass
`--artifact-dir` to the directory containing those files; Gitmoot verifies
relative paths and SHA256 hashes before storing blobs.
The external optimizer walkthrough lives in
[`jerryfane/gitmoot-skillopt`](https://github.com/jerryfane/gitmoot-skillopt/blob/main/docs/guide/gitmoot-mvp-workflow.md).
Use `skillopt candidate show` to inspect the candidate metadata, eval report,
feedback summary, and content diff before `promote` or `reject` records the
decision.

Use the Markdown feedback collector for a local blind A/B packet: open
`index.md`, review `items/*.md`, set `reviewer`, edit `feedback.yml` with `a`,
`b`, `tie`, `neither`, or `skip`, and import it. Keep `.assignments.json`
untouched so Gitmoot can validate and de-blind the mapping.

Use the GitHub feedback collector when review should happen in an issue or an
existing PR thread. Reviewers can reply with either the copy-paste YAML block or
run-scoped short lines such as `run_id: run-1` followed by
`item-001: b - More concrete.`. Gitmoot imports matching comments into
canonical feedback events and ignores unrelated comments. Repo selection uses
`--repo`, then the eval run target repo, then the template source repo, then
optional `[feedback].repo = "owner/reviews"` in Gitmoot config.

Detailed ranked exploration examples, including a landing-page visual task and
a non-visual writing task, live in
[docs/skillopt-exchange-contract.md](docs/skillopt-exchange-contract.md).

Detailed command coverage lives in
[skills/gitmoot/references/CLI.md](skills/gitmoot/references/CLI.md).

## Plugins

Gitmoot can package its Agent Skill for Codex and Claude Code so the runtime
can discover Gitmoot guidance from its plugin system.

```sh
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor
```

Plugins do not start a hosted service, replace the daemon, subscribe agents, or
mutate repository state by themselves. See [docs/plugins.md](docs/plugins.md)
for install details and troubleshooting.

## Documentation

- [Hosted docs](https://gitmoot.io/docs/intro)
- [LLM index](https://gitmoot.io/llms.txt)
- [Agent Skills package](skills/gitmoot/SKILL.md)
- [CLI reference](skills/gitmoot/references/CLI.md)
- [Codex and Claude plugins](docs/plugins.md)
- [Local workflow walkthrough](docs/local-workflow.md)
- [Beta smoke tests](docs/beta-smoke-tests.md)
- [Runtime adapter authoring](docs/adapters.md)
- [Troubleshooting](docs/troubleshooting.md)

## Status And V1 Limits

- Local-only: no hosted dashboard, GitHub App bot identity, cloud runner, or
  remote control plane.
- Polling watches GitHub PRs; there is no webhook receiver in V1.
- GitHub comments are authored by the authenticated `gh` user. Agent identity
  appears in the comment body.
- Local SQLite remains the workflow source of truth.

## Contributing

Gitmoot is early. Keep changes scoped, preserve local-first behavior, and add
focused tests for runtime, CLI, daemon, plugin, or workflow changes. Before
opening a PR, run the relevant checks for the files you touched.

## License

Gitmoot is licensed under the [Apache License 2.0](./LICENSE). See
[NOTICE](./NOTICE) for copyright and attribution details.

## Development

```sh
go test ./...
go vet ./...
```

---

# Source: SKILL.md

---
name: gitmoot
description: Use Gitmoot for local-first AI agent coordination across repositories, goals, reviews, PR comments, daemon jobs, branch locks, agent templates, template capture, custom prompt agents, and Codex or Claude Code runtime workflows.
version: 0.1.0
license: Apache-2.0
compatibility: Requires the gitmoot CLI, git, GitHub CLI authentication, network access to GitHub, and a supported runtime such as Codex or Claude Code.
metadata:
  gitmoot-version: "0.1.0"
  source: "jerryfane/gitmoot"
  openclaw:
    requires:
      bins:
        - gitmoot
        - git
        - gh
    envVars:
      - name: GH_TOKEN
        required: false
        description: Optional GitHub token used by gh when GitHub CLI is not already authenticated.
---

# 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,
goals, 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 or Claude Code agent startup, structured
implementation plans, standard goal files, agent template workflows, template
capture, custom prompt agents, job status, or branch lock inspection.

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
cached, read and apply the packaged `skills/gitmoot/agent-templates/planner.md`
instructions directly.

For template capture, phrases like "capture this session as a Gitmoot agent
template", "turn this workflow into a Gitmoot template", or "draft a reusable
agent template from this chat" mean read
`skills/gitmoot/references/TEMPLATE_CAPTURE.md` and distill the visible
current-chat context into a draft template. Gitmoot cannot read hidden model
memory or runtime internals. Do not install, overwrite, or update a permanent
template unless the user explicitly approves that step.
Use `gitmoot agent template draft <id>` for a blank scaffold,
`gitmoot agent template validate <file>` for a structural check,
`gitmoot agent template add <id> --file <file>` to install a snapshot, and
`gitmoot agent prompt <id>` to reuse the installed template in the current chat.

For background work, keep Gitmoot's resource model explicit: repo checkout
locks protect local checkouts, runtime session locks serialize delivery for the
same Codex or Claude 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.

## 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.
4. Do not start daemons, create agents, update agent templates, or change subscriptions
   unless the user asks or the current task clearly requires it.
5. Prefer read-only status commands before mutating Gitmoot state.

## Install And Update

If `gitmoot` is not installed, install the latest beta:

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

Verify the install and GitHub access before using Gitmoot:

```sh
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:

```sh
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor
```

## Common Local Commands

```sh
gitmoot status --repo owner/repo
gitmoot events --repo owner/repo
gitmoot daemon start --repo owner/repo --poll 30s
gitmoot daemon status
gitmoot plugin doctor
gitmoot agent list
gitmoot agent doctor <agent>
gitmoot agent prompt <agent-or-template>
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 lock list --repo owner/repo
gitmoot lock show owner/repo <branch>
gitmoot skillopt export --run <run-id> [--output training.json]
gitmoot skillopt import --file candidate.json [--artifact-dir artifacts]
gitmoot skillopt candidate list [--template id]
gitmoot skillopt candidate show <version-id>
gitmoot skillopt candidate promote <version-id>
gitmoot skillopt candidate reject <version-id> [--reason text]
gitmoot skillopt feedback markdown export --run <run-id> --output .gitmoot/evals/<run-id>
gitmoot skillopt feedback markdown import --packet .gitmoot/evals/<run-id>
gitmoot skillopt feedback github publish --run <run-id> [--repo owner/repo] [--pr <number>]
gitmoot skillopt feedback github sync --run <run-id> [--repo owner/repo] (--issue <number>|--pr <number>)
```

Use `gitmoot daemon start` for the background daemon. Use `gitmoot daemon run`
only when the user explicitly wants a foreground process.

Use `gitmoot agent prompt <agent-or-template>` when the user wants to reuse a
Gitmoot agent prompt in the current chat. Use `gitmoot agent ask` when the user
wants to invoke a registered Gitmoot agent through the Gitmoot runtime path. 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 ask jobs; the
plugin only helps the runtime discover this skill and does not replace the
`gitmoot` CLI.

## PR Comment Commands

Use GitHub PR comments as the public audit trail:

```text
/gitmoot help
/gitmoot status
/gitmoot <agent> review [instructions]
/gitmoot <agent> implement [instructions]
/gitmoot ask <agent> [question]
/gitmoot retry <job-id>
/gitmoot cancel <job-id>
/gitmoot merge
```

## Template Agents

Install or refresh the built-in thermo review template:

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

Create a local custom prompt template:

```sh
mkdir -p agents
gitmoot agent template draft frontend-reviewer --output agents/frontend-reviewer.md
$EDITOR agents/frontend-reviewer.md
gitmoot agent template validate agents/frontend-reviewer.md
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
gitmoot agent start frontend-reviewer \
  --runtime codex \
  --repo owner/repo \
  --template frontend-reviewer \
  --role reviewer \
  --capability ask \
  --capability review
```

After editing a local template file, refresh Gitmoot's cached snapshot explicitly:

```sh
gitmoot agent template diff frontend-reviewer
gitmoot agent template update frontend-reviewer
```

Template updates are versioned locally. `gitmoot agent template show <id>`
prints the current version, content hash, source commit, and promotion state.
Agents use the current promoted version by default, or a pinned version when
configured with a reference such as `--template frontend-reviewer@v1`.
Queued jobs keep the exact template content snapshot they were created with.

Discover templates by metadata:

```sh
gitmoot agent template list --runtime codex --output goal_file
gitmoot agent template list --tag review --capability ask
gitmoot agent template show frontend-reviewer
```

Draft and validate a captured template before installing it:

```sh
gitmoot agent template draft release-planner
gitmoot agent template validate .gitmoot/templates/release-planner.md
gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
gitmoot agent prompt release-planner
```

## Agent Job Contract

Every Gitmoot job should return a concise and truthful `gitmoot_result` JSON
object:

```json
{
  "gitmoot_result": {
    "decision": "approved|changes_requested|blocked|implemented|failed",
    "summary": "Brief outcome.",
    "findings": [],
    "changes_made": [],
    "tests_run": [],
    "needs": [],
    "next_agents": []
  }
}
```

Use `blocked` when work cannot continue without human input or external state.
Use `failed` when the attempted action errored. Do not report tests, changes, or
approvals that were not actually verified.

## Safety Rules

Preserve existing behavior unless the job explicitly changes it. Keep work
scoped to the target repo. Do not commit generated data, caches, logs, secrets,
session archives, cloned helper repos, or large outputs unless explicitly
requested. Respect Gitmoot branch locks for implementation jobs.

Implementation jobs must not edit or push an implementation branch unless
Gitmoot assigned the job and the branch lock is held by the assigned agent.
Review and ask jobs should inspect and report without mutating branches unless
the task explicitly instructs otherwise.

Redact secrets from GitHub comments, job summaries, raw examples, and copied
command output.

## When Unsure

Reread this `SKILL.md`, then inspect `/gitmoot help`, `gitmoot status`, and the
relevant job events before acting.

---

# Source: docs/local-workflow.md

# Local Workflow

Gitmoot V1 runs on one machine. The GitHub repository is the visible audit
trail, while local SQLite state is the workflow source of truth. The local
daemon polls GitHub PRs and comments, routes jobs to registered agents, resumes
their runtime sessions through adapters, records job output, updates PR
statuses, and merges only after the merge gate passes.

## What Exists Today

The current CLI supports local setup, multi-repo daemon management, agent
registration, plan import, task branch startup, status, recovery, and updates:

```sh
gitmoot setup --repo owner/repo --path . --agent lead --runtime codex --session <session-ref> --role lead
gitmoot doctor --repo .
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor
gitmoot agent template list
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
gitmoot agent template update thermo-nuclear-code-quality-review
gitmoot agent start <name> --runtime codex|claude --repo owner/repo --path . --template thermo-nuclear-code-quality-review --start-daemon
gitmoot agent subscribe <name> --runtime codex|claude|shell --session <id|name|last|command> --role <role> --repo owner/repo --capability <capability>
gitmoot agent ask <name> "message" --repo owner/repo
gitmoot agent ask <name> --background --repo owner/repo "message"
gitmoot agent type list
gitmoot agent type show planner
gitmoot agent gc
gitmoot agent start thermo-review --runtime codex --repo owner/repo --template thermo-nuclear-code-quality-review
gitmoot agent allow <name> --repo owner/repo
gitmoot agent repos <name>
gitmoot agent list
gitmoot agent doctor <name>
gitmoot goal import --file GOAL.md --repo owner/repo
gitmoot task run task-001 --repo owner/repo --owner lead --base main
gitmoot job list
gitmoot job show <job-id>
gitmoot job watch <job-id>
gitmoot job retry <job-id>
gitmoot job cancel <job-id>
gitmoot status --repo owner/repo
gitmoot version --json
gitmoot update --check
gitmoot daemon start --repo owner/repo --poll 30s --workers 1
gitmoot daemon start
gitmoot daemon status
```

Goal import turns Markdown headings shaped like `### Task N: Title` into local
planned tasks. `task run` starts one task branch and records its branch lock.

## Runtime Plugin Setup

Install the Codex or Claude plugin when you want the runtime to discover
Gitmoot's Agent Skill through its plugin system:

```sh
curl -fsSL https://gitmoot.io/install.sh | sh
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor
```

The plugins are guidance and discovery surfaces. They do not replace
`gitmoot daemon start`, agent registration, GitHub CLI authentication, or the
local SQLite workflow state.

For fast planning in the current Codex or Claude chat, ask the runtime to use
the Gitmoot planner here. That applies the same `planner` template instructions
directly in the current conversation and avoids the startup cost of a background
planner job.

If a Codex or Claude chat wants to reuse a registered Gitmoot agent prompt in
the current chat, it should run `gitmoot agent prompt <agent-or-template>` and
apply the returned prompt content locally. If it wants to invoke a registered
Gitmoot agent through the runtime adapter path, it should run
`gitmoot agent ask <agent> --repo owner/repo "..."`. That uses the same local
agent registry and runtime adapter path as PR-comment ask jobs.

## Execution Model

Gitmoot has two execution paths:

- **Here**: the current Codex or Claude chat reads Gitmoot skill and template
  instructions directly. This does not create a Gitmoot job and is the fastest
  path for planning when the current chat already has context.
- **Background**: Gitmoot creates a job, records events in SQLite, and the
  daemon or `gitmoot job run <job-id>` delivers that job through the runtime
  adapter.

Background execution uses separate resource categories:

- **Repo checkout locks**: daemon-side mutexes that prevent two enabled repo
  ticks from mutating the same checkout at once.
- **Runtime session locks**: SQLite resource locks keyed as
  `runtime:<runtime>:<runtime_ref>`, shared by daemon jobs, `job run`, and
  synchronous `agent ask`, so one Codex or Claude session is never resumed by
  two jobs at the same time.
- **Branch locks**: workflow ownership records used for implementation and
  merge safety.

The daemon defaults to `--workers 1`. Raise `--workers` only when the Gitmoot
home has independent runtime sessions or managed agent types with
`max_background` greater than one. Jobs that target the same runtime session or
same checkout remain serialized even when the worker count is higher.

## End-To-End Demo Path

1. Create or choose the project repository.

   ```sh
   git clone git@github.com:owner/project.git
   cd project
   git status --short
   git remote -v
   gh auth status
   ```

2. Write and import the plan.

   Keep the implementation plan in a tracked file such as `GOAL.md`. The future
   command shape is:

   ```sh
   gitmoot goal import --file GOAL.md --repo owner/project
   ```

3. Initialize Gitmoot state and start Gitmoot-managed agents.

   `agent start` creates a new runtime session, stores the returned session
   reference, grants the repo, and can start the background daemon. For Codex it
   runs `codex exec --json -- <startup-prompt>` and records the emitted
   `thread.started.thread_id`. For Claude Code it creates a session id and uses
   the installed Claude CLI's non-interactive print mode.

   ```sh
   gitmoot init
   gitmoot doctor --repo .
   gitmoot plugin install codex
   gitmoot plugin doctor codex
   gitmoot agent start lead \
     --runtime codex \
     --repo owner/project \
     --path . \
     --role lead \
     --capability ask \
     --capability review \
     --capability implement
   gitmoot agent list
   gitmoot agent doctor lead
   ```

   To add the built-in strict review template, fetch and cache it explicitly.
   `--template` supplies the default reviewer role and `ask,review` capabilities
   when those flags are omitted.

   ```sh
   gitmoot agent template update thermo-nuclear-code-quality-review
   gitmoot agent start thermo-review \
     --runtime codex \
     --repo owner/project \
     --template thermo-nuclear-code-quality-review
   gitmoot agent doctor thermo-review
   ```

   If the template is not cached yet, `agent start --template ...` fails with the
   same explicit `gitmoot agent template update <template>` guidance as `agent subscribe`.
   Add `--update-template` when you want startup to refresh the cached template
   before creating the runtime session.

   Custom prompt agent templates are local files snapshotted into Gitmoot state. Use
   them when you want a repo- or team-specific agent profile without changing
   Codex, Claude, or repository agent files.

   ```sh
   mkdir -p agents
   gitmoot agent template draft frontend-reviewer --output agents/frontend-reviewer.md
   $EDITOR agents/frontend-reviewer.md
   gitmoot agent template validate agents/frontend-reviewer.md
   gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
   gitmoot agent start frontend-reviewer \
     --runtime codex \
     --repo owner/project \
     --path . \
     --template frontend-reviewer \
     --role reviewer \
     --capability ask \
     --capability review
   ```

   Built-in agent templates can define default roles and capabilities. Custom agent templates
   do not in V1, so pass the role and capabilities you want. `agent start`
   still keeps the normal fallback defaults if omitted, while
   `agent subscribe --template <custom-id>` requires explicit values.

   After editing a custom template file, refresh the cached snapshot explicitly:

   ```sh
   gitmoot agent template diff frontend-reviewer
   gitmoot agent template update frontend-reviewer
   ```

   To create a new custom template from a successful current chat, use template
   capture. The current Codex or Claude chat distills visible conversation,
   inspected files, commands, corrections, and durable workflow rules into a
   draft. Gitmoot cannot read hidden model memory, so capture is always
   draft-first and user-reviewed.

   ```text
   Use Gitmoot to capture this session as agent template release-planner. Draft only.
   ```

   A blank scaffold is also available when you want to write the template by
   hand:

   ```sh
   gitmoot agent template draft release-planner
   gitmoot agent template validate .gitmoot/templates/release-planner.md
   gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
   gitmoot agent prompt release-planner
   ```

   `agent template draft` creates the structure, current-chat capture fills it
   from visible context, `agent template validate` performs a structural check,
   `agent template add` installs a snapshot, `agent prompt` reuses it in the
   current chat, and `agent start --template` creates a runnable background
   agent instance.

   After startup, open a created Codex session later with the session id printed
   by Gitmoot:

   ```sh
   codex resume <session-id>
   ```

4. Subscribe existing sessions or shell adapters when needed.

   Use `agent subscribe` when a Codex or Claude session already exists, or when
   registering a shell command adapter. Using `last` works for quick demos, but
   explicit ids are safer because the newest session can change.

   ```sh
   gitmoot agent subscribe audit --runtime claude --session <claude-session-id> --role reviewer --repo owner/project --capability review --capability ask
   gitmoot agent subscribe shell-smoke --runtime shell --session "printf '%s\n' '{\"gitmoot_result\":{\"decision\":\"approved\",\"summary\":\"ok\",\"findings\":[],\"changes_made\":[],\"tests_run\":[\"shell\"],\"needs\":[],\"next_agents\":[]}}'" --role reviewer --repo owner/project --capability ask
   gitmoot agent list
   ```

   Template updates are explicit and auditable. Diff upstream content before
   refreshing the local cached copy. For custom agent templates, `diff` compares the
   cached content with the stored local file path.

   ```sh
   gitmoot agent template diff thermo-nuclear-code-quality-review
   gitmoot agent template update thermo-nuclear-code-quality-review
   ```

   To inspect the installed Gitmoot build or check for a beta release:

   ```sh
   gitmoot version
   gitmoot update --check
   ```

5. Start the daemon from the repository checkout.

   ```sh
   gitmoot daemon start --repo owner/project --poll 30s
   ```

   The daemon validates that the current checkout's `origin` remote matches
   `--repo`. `agent start --start-daemon` runs this same background start path
   for the selected checkout. Use `gitmoot daemon start` without `--repo` after
   registering all intended repos if one daemon should supervise the whole
   Gitmoot home.

6. Start and open the first task PR.

   ```sh
   gitmoot task run task-001 --repo owner/project --owner lead --base main
   ```

   The lead agent or the human creates the task branch, implements the task,
   pushes it, and opens a PR. The PR comments become the public audit trail.
   The local Gitmoot database tracks the task, jobs, branch locks, PR head SHA,
   and merge gate state.

7. Route other agents through PR comments.

   A repository writer can ask a subscribed agent to work from a PR comment:

   ```text
   /gitmoot help
   /gitmoot audit review focus on correctness and missed edge cases
   /gitmoot thermo-review review
   /gitmoot lead implement fix the review findings without broad refactors
   /gitmoot retry <job-id>
   /gitmoot cancel <job-id>
   ```

   Implement jobs require the agent to hold the branch lock. Review and ask jobs
   are routed through the runtime adapter and must return the `gitmoot_result`
   JSON contract.

   For a local chat ask that should not go through a PR comment, call the same
   registered agent directly:

   ```sh
   gitmoot agent ask project-planner --repo owner/project "Write a task-by-task implementation plan and goal file prompt."
   gitmoot job show <job-id>
   ```

   Stale branch locks can be inspected and released locally:

   ```sh
   gitmoot job list --repo owner/project
   gitmoot job show <job-id>
   gitmoot job events <job-id>
   gitmoot lock list --repo owner/project
   gitmoot lock show owner/project <branch>
   gitmoot lock release owner/project <branch> --owner <agent>
   ```

8. Let the PR converge.

   Agents review, request fixes, and rerun work through comments and job output.
   When required reviews are approved and the branch is ready, the merge gate
   checks the current PR head, local worktree cleanliness, branch freshness,
   Gitmoot statuses, external CI if present, and mergeability.

9. Merge and continue.

   By default Gitmoot merges with a squash merge guarded by the current head SHA.
   After merge it records the merged commit, releases the branch lock, updates
   the local base branch, and can enqueue the next task once the task queueing
   policy selects it.

## Local-Only Limits

- The machine running `gitmoot daemon start` must stay online.
- Polling is the V1 mechanism; there is no webhook receiver yet.
- GitHub Checks are best implemented later through GitHub App mode. V1 uses
  commit statuses and `gh pr checks`.
- Use explicit session ids for long workflows. `last` is convenient but can
  point at the wrong session after a new Codex or Claude session starts.
- GitHub comments are the public audit trail, not canonical state. Local SQLite
  remains the workflow source of truth.
- There is no hosted dashboard, cloud runner, billing, or remote control plane
  in V1.
- GitHub comments are authored by the authenticated user. Agent attribution is
  written in the comment body.
- Template content is not fetched at job runtime. Run `gitmoot agent template update`
  intentionally when you want to refresh a cached template.

## Multi-Repo Supervision

One daemon can supervise multiple enabled repos for the same Gitmoot home.
Register each checkout explicitly and grant agents repo access explicitly:

```sh
cd /path/to/project-a
gitmoot setup --repo owner/project-a --path . --agent lead --runtime codex --session <session-ref> --role lead

cd /path/to/project-b
gitmoot setup --repo owner/project-b --path . --agent lead --runtime codex --session <same-session-or-explicit-ref> --role lead

gitmoot agent repos lead
gitmoot daemon start
gitmoot status
```

The PR repository supplies routing context. `/gitmoot lead review` in
`owner/project-a` queues work for `owner/project-a`; the same command in
`owner/project-b` queues work for `owner/project-b` if `lead` is allowed there.

## Skill Usage

Agents should read the root [`SKILL.md`](../SKILL.md) before working through
Gitmoot. The skill documents PR commands, the required `gitmoot_result` JSON
contract, branch lock rules, repo access, and safe agent behavior. If an agent
is unsure how Gitmoot expects it to behave, it should reread `SKILL.md`, then
inspect `/gitmoot help`, `gitmoot status`, and relevant job events.

## Agent Output Contract

Agents must return exactly one JSON object containing `gitmoot_result`:

```json
{
  "gitmoot_result": {
    "decision": "approved",
    "summary": "ready",
    "findings": [],
    "changes_made": [],
    "tests_run": [],
    "needs": [],
    "next_agents": []
  }
}
```

Valid decisions are `approved`, `changes_requested`, `blocked`, `implemented`,
and `failed`.

---

# Source: docs/plugins.md

# Codex And Claude Plugins

Gitmoot plugins package the canonical Gitmoot Agent Skill for Codex and Claude
Code. They make the runtime aware of Gitmoot commands, safety rules, and
workflow expectations without changing Gitmoot's local-first architecture.

The Gitmoot CLI remains the engine. The daemon still polls GitHub pull
requests, local SQLite remains the workflow source of truth, and PR comments
remain the public audit trail.

## What Plugins Do

- Install Gitmoot's agent skill into a local runtime plugin package.
- Register a local marketplace named `gitmoot-local`.
- Help Codex or Claude discover Gitmoot workflow instructions.
- Point agents to the `gitmoot` CLI for status, jobs, locks, and daemon
  management.

## What Plugins Do Not Do

- They do not start a hosted service, webhook receiver, or cloud runner.
- They do not replace `gitmoot daemon start`.
- They do not install Codex, Claude Code, Git, or GitHub CLI.
- They do not silently subscribe agents or mutate repository state.

## Install Gitmoot

```sh
curl -fsSL https://gitmoot.io/install.sh | sh
gitmoot version
gh auth status
```

## Install The Codex Plugin

```sh
gitmoot plugin install codex
gitmoot plugin doctor codex
```

`plugin install codex` builds the Codex package under Gitmoot home, writes a
local Codex marketplace manifest, runs `codex plugin marketplace add`, and runs
`codex plugin add gitmoot@gitmoot-local` when the `codex` CLI is available.

Use `gitmoot plugin path codex` to print the generated package path.

## Install The Claude Plugin

```sh
gitmoot plugin install claude
gitmoot plugin doctor claude
```

`plugin install claude` builds the Claude package under Gitmoot home, validates
the package when the `claude` CLI is available, registers the local marketplace,
refreshes any existing installed copy, and installs
`gitmoot@gitmoot-local`.

Claude supports installation scopes:

```sh
gitmoot plugin install claude --scope user
gitmoot plugin install claude --scope project
gitmoot plugin install claude --scope local
```

Use `gitmoot plugin path claude` to print the generated package path.

## Verify

```sh
gitmoot plugin doctor
gitmoot plugin doctor codex
gitmoot plugin doctor claude
```

Doctor checks the canonical skill, generated package, manifest JSON, copied
skill, marketplace path, runtime CLI availability, and runtime validation where
supported.

## Use From Codex

After installing the Codex plugin, ask Codex to use the Gitmoot skill when the
task involves local PR-comment agent coordination:

```text
Use the Gitmoot skill. Check gitmoot status for this repo.
```

The agent should read the bundled skill, verify `gitmoot version`, check
`gh auth status` before PR workflows, and use read-only Gitmoot status commands
before mutating daemon, agent, job, or lock state.

For fast planning in the current Codex chat, do not route through a background
planner unless the user asks for a queued job. Ask Codex:

```text
Use the Gitmoot planner here. Write the implementation plan.
```

Codex should apply the same `planner` template used by managed planner agents,
inspect the relevant repo files, search only for current external contracts when
needed, and return the plan directly in the current conversation.

For any cached custom agent or template prompt, ask Codex to use that agent
here. The Gitmoot skill should load the prompt with:

```sh
gitmoot agent prompt <agent-or-template>
```

Then Codex should apply the returned prompt content in the current chat without
creating a Gitmoot job.

For template capture, keep the work in the current chat. Ask Codex to read the
Gitmoot template-capture instructions and draft a file from visible context:

```text
Use Gitmoot to capture this session as agent template release-planner. Draft only.
```

Codex should not call `gitmoot agent ask`, start a daemon, or install the
template unless the user explicitly asks. After review, install the draft with:

```sh
gitmoot agent template validate .gitmoot/templates/release-planner.md
gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
```

When you want the current Codex chat to invoke a registered background-capable
Gitmoot agent, route that request through the CLI:

```text
$gitmoot:gitmoot agent ask project-planner --repo owner/repo --background "Write the implementation plan and goal file."
```

Without the chat command bridge, ask Codex to run the same shell command:

```sh
gitmoot agent ask project-planner --repo owner/repo --background "Write the implementation plan and goal file."
gitmoot job watch <job-id>
```

This keeps background asks on the same Gitmoot agent registry, repo access,
runtime adapter, cached template, and job history path as PR-comment ask jobs.

## Use From Claude Code

After installing the Claude plugin, ask Claude Code to use the Gitmoot skill for
the current workflow:

```text
Use the Gitmoot skill. Check gitmoot status for this repo.
```

Claude should use the bundled Gitmoot skill content as guidance, then call the
local `gitmoot` CLI only when the user asks for setup, status, agent
coordination, or PR-comment workflow help.

For a registered background-agent ask from Claude Code, use the same CLI
command:

```sh
gitmoot agent ask project-planner --repo owner/repo --background "Write the implementation plan and goal file."
gitmoot job watch <job-id>
```

The plugin is discovery and guidance. The `gitmoot` CLI is still the execution
path.

For fast current-chat planning, ask Claude Code to use the Gitmoot planner here
instead of starting a background `gitmoot agent ask` job.

For current-chat template capture, ask Claude Code:

```text
Use Gitmoot to capture this session as agent template release-planner. Draft only.
```

Claude Code should apply the bundled template-capture instructions locally,
write or return a draft, and wait for explicit approval before validation or
installation.

## Troubleshooting

If the runtime CLI is missing, `gitmoot plugin install` keeps generated files
and prints manual install commands. Install the missing runtime, then rerun:

```sh
gitmoot plugin install codex
gitmoot plugin install claude
```

If a package looks stale, rebuild and reinstall:

```sh
gitmoot plugin install codex --force
gitmoot plugin install claude --force
```

If Claude validation fails, inspect the generated package and rerun validation
directly:

```sh
claude plugin validate "$(gitmoot plugin path claude)"
```

If Codex or Claude does not show the plugin after install, run:

```sh
gitmoot plugin doctor
gitmoot plugin path codex
gitmoot plugin path claude
```

Then confirm the runtime uses the same home directory as the shell where
`gitmoot plugin install` ran.

---

# Source: docs/adapters.md

# Runtime Adapter Authoring

Gitmoot treats Codex, Claude Code, and shell commands as runtime adapters behind
one interface. Workflow, daemon, and GitHub code should stay runtime-neutral.

## Adapter Contract

An adapter implements `runtime.Adapter`:

```go
type Adapter interface {
    Name() string
    Start(ctx context.Context, request StartRequest) (StartResult, error)
    Validate(ctx context.Context, agent Agent) error
    Deliver(ctx context.Context, agent Agent, job Job) (Result, error)
    Health(ctx context.Context, agent Agent) error
    Capabilities(ctx context.Context) ([]string, error)
}
```

Responsibilities:

- `Name` returns the runtime key used by `gitmoot agent start` and
  `gitmoot agent subscribe`.
- `Start` creates a new runtime session for `gitmoot agent start` and returns
  the runtime reference Gitmoot should store.
- `Validate` checks the agent record without doing unnecessary work.
- `Deliver` resumes or invokes the runtime with the rendered job prompt and
  returns raw output.
- `Health` performs a small operational check that proves the runtime can accept
  a job.
- `Capabilities` advertises actions such as `review`, `implement`, and `ask`.

## Agent Record

Adapters receive a normalized `runtime.Agent`:

```go
type Agent struct {
    Name           string
    Role           string
    Runtime        string
    RuntimeRef     string
    RepoScope      string
    TemplateID       string
    Capabilities   []string
    AutonomyPolicy string
    HealthStatus   string
}
```

`RuntimeRef` is runtime-specific. Codex accepts a session UUID, thread name, or
`last`. Claude accepts a UUID or `last`. Shell uses the configured command.
`TemplateID` is Gitmoot-owned metadata. Adapters do not fetch or interpret template
content; Gitmoot snapshots cached template instructions into the rendered prompt
before delivery.

## Session Startup

`gitmoot agent start` uses the adapter `Start` method to create a new session
without leaving an interactive terminal open. The startup prompt tells the
runtime to initialize only, make no file edits, and reply with a short readiness
acknowledgment.

Codex startup runs in the repo checkout path:

```sh
codex exec --json -- '<startup-prompt>'
```

The adapter parses JSONL stdout and stores the first
`thread.started.thread_id`. Future jobs resume that session with:

```sh
codex exec resume <session-id> -- '<job-prompt>'
```

Claude startup generates a UUID before invocation, then runs:

```sh
claude --session-id <uuid> -p --output-format json -- '<startup-prompt>'
```

The UUID is stored only after the command succeeds. Future jobs use the Claude
adapter's resume path. This depends on the installed Claude Code CLI supporting
the documented `--session-id`, `-p`, `--output-format json`, and `--resume`
contract.

Shell adapters do not support `agent start`; register shell commands with
`agent subscribe`.

## Job Input

Gitmoot sends adapters a `runtime.Job`:

```go
type Job struct {
    ID          string
    AgentName   string
    Action      string
    Prompt      string
    Repository  string
    PullRequest int
}
```

The prompt already includes repo, branch, PR number, task label, sender,
requested action, cached template instructions when present, constraints, and the
required `gitmoot_result` JSON shape. Adapters should pass the prompt through
without rewriting workflow semantics.

## Result Handling

`Deliver` should return raw runtime output. Gitmoot parses the
`gitmoot_result` object after delivery. If the runtime returns structured JSON
with a nested text result, the adapter may also fill `Result.Summary`, but raw
output must be preserved for parsing and diagnostics.

## Adding A Runtime

1. Add a runtime constant in `internal/runtime/adapter.go`.
2. Implement an adapter type in `internal/runtime`.
3. Register it in `runtime.Factory.Adapter`.
4. Extend `ValidateAgent` only for runtime-specific reference rules.
5. Implement startup semantics or return a clear unsupported error from
   `Start`.
6. Add tests for startup command arguments, validation, delivery command
   arguments, error handling, health checks, and capability reporting.
7. Add or update docs for the runtime-specific `--session` and startup values.

Keep runtime-specific command names, flags, JSON modes, session lookup, and
fallback behavior inside the adapter package. Do not leak Codex or Claude
assumptions into workflow, daemon, GitHub, database, or merge-gate code.

## Agent Templates

Agent Templates are prompt/profile bundles layered above runtimes. They are not runtime
adapters and should not create adapter-specific behavior. Gitmoot snapshots
cached template content into startup and job prompts before invoking an adapter.

The built-in `thermo-nuclear-code-quality-review` template is fetched explicitly
with:

```sh
gitmoot agent template update thermo-nuclear-code-quality-review
```

After it is cached, bind it to a normal runtime-backed agent:

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

The thermo template is non-mutating. It supplies reviewer defaults and allows
`ask,review`, but it cannot grant `implement`.

Local custom agent templates are installed from files:

```sh
gitmoot agent template validate agents/frontend-reviewer.md
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
```

They store `local@file:<absolute-path>` metadata and a `sha256:<hash>` resolved
identifier. Adapters should not read those files or decide how agent templates behave;
workflow code passes only the rendered prompt. After a template file changes, the
user must run `gitmoot agent template update <custom-id>` before new jobs use the new
content.

## Shell Adapter

The shell adapter is useful for experiments and contract tests. It invokes:

```sh
sh -c '<configured command>' gitmoot '<job prompt>'
```

Health checks invoke:

```sh
sh -c '<configured command>' gitmoot-health 'Gitmoot health check. Reply OK only.'
```

The command must print a valid `gitmoot_result` object for normal jobs.

---

# Source: docs/troubleshooting.md

# Troubleshooting

Use `gitmoot doctor --repo .` first. It checks local prerequisites from the
repository checkout.

## `gh`

Symptoms:

- `gh auth status` fails.
- PR comments, PR reads, status creation, or merges fail.
- The daemon reports GitHub API or permission errors.

Checks:

```sh
gh auth status
gh repo view owner/repo --json nameWithOwner
gh pr list --repo owner/repo --state open
```

Fixes:

- Authenticate `gh` for the account that can read and write the repository.
- Confirm the `--repo owner/repo` value matches the checkout remote.
- Retry after GitHub rate limits clear.

## SkillOpt Review Operations

Symptoms:

- `gitmoot skillopt train continue` refuses to publish or sync GitHub review
  feedback.
- Review issue links show `pending deployment`, `failed deployment`, or
  `stale deployment`.
- A candidate review keeps waiting for a promote/reject decision.
- Required Vue/Vite review items fail during generation.

Checks:

```sh
gh auth status --hostname github.com
gh repo view owner/reviews --json nameWithOwner
gitmoot skillopt train status --session <session-id> --verbose
gitmoot repo list
```

Fixes:

- GitHub review operations use `gh`; authenticate it for the expected review
  repo before publishing, syncing, candidate review publication, or review
  watching. Preview publication can push Pages files before a later review issue
  preflight fails, so run the `gh` checks before starting review publication.
- Confirm `review.expected_repo` in train status. Preview review runs must
  publish and sync against the preview/review repo, not the target product repo.
- `pending deployment` means GitHub Pages had not finished for the pushed
  preview commit during Gitmoot's bounded wait. The stored review label is not
  refreshed automatically after it is written; inspect the link or the Pages
  build directly.
- `failed deployment` includes the Pages error when GitHub reports one. Fix the
  preview repo Pages configuration or generated output. Existing review links
  keep their recorded label; generate a new review item or clear/recreate the
  affected preview metadata if reviewers need an updated label.
- `stale deployment` means the latest Pages build still points at a different
  commit after the wait. Confirm the preview repo push and Pages build manually;
  `train continue` skips options that already have a preview URL, so it does not
  re-observe status for the old review option.
- Candidate review decisions are explicit: promote, reject with a reason, wait,
  or reject and `--start-next` to keep improving.
- Required Vue/Vite options retry once when preview-bundle validation fails with
  an actionable error. If the retry also fails, inspect the structured error for
  the item id, option label, validation class, and retry count.

## Codex

Symptoms:

- `gitmoot agent doctor <name>` cannot validate a Codex agent.
- A job cannot resume the intended session.
- A `last` reference resumes the wrong session.

Checks:

```sh
codex exec resume --help
gitmoot agent list
gitmoot agent doctor <name>
```

Fixes:

- Prefer an explicit Codex session UUID or thread name over `last`.
- Confirm `CODEX_HOME` if sessions are stored outside `~/.codex`.
- Re-subscribe the agent with the correct session reference.

## Agent Templates

Symptoms:

- `gitmoot agent subscribe ... --template thermo-nuclear-code-quality-review`
  fails with an install hint.
- `gitmoot agent start ... --template <custom-id>` fails with an `agent template add`
  hint.
- A custom prompt edit is not reflected in new jobs.
- A template-backed job does not include the expected review instructions.
- You want to know whether the cached template differs from upstream.

Checks:

```sh
gitmoot agent template list
gitmoot agent template show thermo-nuclear-code-quality-review
gitmoot agent template show <custom-id>
gitmoot agent template diff thermo-nuclear-code-quality-review
gitmoot agent template diff <custom-id>
gitmoot agent list
```

Fixes:

- Install or refresh the template explicitly:

  ```sh
  gitmoot agent template update thermo-nuclear-code-quality-review
  ```

  For a custom local template file:

  ```sh
  gitmoot agent template validate agents/<custom-id>.md
  gitmoot agent template add <custom-id> --file agents/<custom-id>.md
  gitmoot agent template update <custom-id>
  ```

- Re-subscribe the agent after the template is installed:

  ```sh
  gitmoot agent subscribe thermo-review \
    --runtime codex \
    --session <session-id-or-last> \
    --repo owner/repo \
    --template thermo-nuclear-code-quality-review
  gitmoot agent doctor thermo-review
  ```

- Template content is snapshotted when a job is queued. Retry an existing job to
  reuse its original snapshot; comment again after `agent template update` to queue a
  job with refreshed content.
- Custom template files are not read at job runtime. Run
  `gitmoot agent template diff <custom-id>` and `gitmoot agent template update <custom-id>`
  after editing the file.
- The thermo template is review-only. Remove `--capability implement` and route
  implementation work to a separate implementation-capable agent.

## Claude Code

Symptoms:

- Claude jobs fail to resume.
- JSON output mode is unsupported by the installed Claude CLI.
- `last` points at an unexpected session.

Checks:

```sh
claude --help
gitmoot agent doctor <name>
```

Fixes:

- Use a Claude session UUID for long workflows.
- Upgrade Claude Code if JSON output mode is needed.
- If JSON mode is unsupported, the adapter falls back to plain output, but the
  output still must contain the `gitmoot_result` object.

## Repo Remotes

Symptoms:

- `gitmoot daemon start` reports that the checkout origin is not the requested
  repo.
- The daemon reads the wrong repository's PRs.

Checks:

```sh
git rev-parse --show-toplevel
git remote get-url origin
gitmoot daemon start --repo owner/repo --poll 30s
```

Fixes:

- Start the daemon from the intended checkout.
- Correct the `origin` remote or pass the matching `--repo`.
- Avoid running one daemon from a parent folder that contains multiple repos.

## Permissions

Symptoms:

- `/gitmoot ...` comments are ignored.
- A commenter cannot route jobs.
- Merge attempts fail.

Checks:

```sh
gh api repos/owner/repo/collaborators/<user>/permission
gh pr view <number> --repo owner/repo --json reviewDecision,mergeable
```

Fixes:

- Comment routing requires write, maintain, or admin permission.
- Merge requires the authenticated `gh` user to have repository merge rights.
- Required reviews and branch protection still apply.

## Stale Locks

Symptoms:

- Implement jobs are rejected because another agent owns the branch lock.
- A branch remains locked after a failed or interrupted run.

Checks:

```sh
gitmoot agent list
gitmoot lock list --repo owner/repo
gitmoot lock show owner/repo <branch>
```

The safest path is still to finish or merge the owning task so the merge gate
releases the lock and records the release event. If the task is abandoned, use
an exact-owner release:

```sh
gitmoot lock release owner/repo <branch> --owner <agent>
```

Use `--force` only when the stored owner is stale or the owning session is no
longer recoverable:

```sh
gitmoot lock release owner/repo <branch> --force
```

## Runtime Session Lock Waits

Symptoms:

- `gitmoot agent ask` fails with `runtime session ... is busy`.
- A background job remains queued and its events include `runtime_lock_wait`.
- Increasing `--workers` does not make two jobs run against the same Codex or
  Claude session.

Checks:

```sh
gitmoot job show <job-id>
gitmoot job events <job-id>
gitmoot daemon status
gitmoot agent list
```

Fixes:

- Wait for the active job using the same runtime session to finish.
- Use a different registered agent or managed background instance when the work
  is independent.
- Keep `gitmoot daemon start --workers 1` unless you have multiple independent
  runtime sessions or an agent type with `max_background` greater than one.
- Use `gitmoot agent gc` to remove expired managed background instances.

## Malformed Agent Output

Symptoms:

- A job fails because output is missing `gitmoot_result`.
- The repair prompt keeps asking for JSON.

Required shape:

```json
{
  "gitmoot_result": {
    "decision": "approved",
    "summary": "ready",
    "findings": [],
    "changes_made": [],
    "tests_run": [],
    "needs": [],
    "next_agents": []
  }
}
```

Fixes:

- Return exactly one JSON object.
- Use one of the supported decisions: `approved`, `changes_requested`,
  `blocked`, `implemented`, or `failed`.
- Keep `summary` non-empty.

## Rate Limits

Symptoms:

- GitHub API calls fail with 429, `retry-after`, or rate-limit messages.
- Polling works briefly and then stalls.

Fixes:

- Increase `--poll`, for example `--poll 60s`.
- Reduce the number of active PRs watched by one daemon.
- Wait for the GitHub rate-limit window to reset.

## Merge Gate

Symptoms:

- The PR remains `ready_to_merge`.
- `gitmoot/merge-gate` is pending or failing.
- The daemon retries a queued merge.

Checks:

```sh
gh pr checks <number> --repo owner/repo
gh pr view <number> --repo owner/repo --json mergeable,statusCheckRollup,reviewDecision
git status --short
```

Fixes:

- Clean the local worktree before the daemon attempts the merge.
- Update the PR branch if it is behind or diverged from base.
- Fix failing external CI or Gitmoot statuses.
- Rerun reviews after the PR head SHA changes.

---

# Source: docs/beta-smoke-tests.md

# Beta Smoke Tests

Use these smoke tests before cutting a beta release. They verify the local V1
loop without a hosted service or webhook receiver.

## Prerequisites

Run from each repository checkout that will be watched:

```sh
git status --short
git remote -v
gh auth status
gitmoot doctor --repo .
```

Use a test repository or a disposable branch. Keep generated logs, cloned
helper repos, session archives, and large outputs untracked.

## Plugin Package Smoke Test

Goal: prove Gitmoot can build runtime plugin packages, register local
marketplaces in isolated homes, and diagnose the generated packages without
writing into the real user runtime state.

For the scripted version, run:

```sh
GO_BIN=/path/to/go1.26 scripts/plugin-smoke.sh
```

1. Build a local test binary and use an isolated Gitmoot home.

   ```sh
   GOTOOLCHAIN=go1.26.0 go build -o /tmp/gitmoot-current ./cmd/gitmoot
   export GITMOOT_SMOKE_HOME=/tmp/gitmoot-plugin-smoke
   export GITMOOT_RUNTIME_HOME=/tmp/gitmoot-plugin-runtime-smoke
   rm -rf "$GITMOOT_SMOKE_HOME"
   rm -rf "$GITMOOT_RUNTIME_HOME"
   mkdir -p "$GITMOOT_RUNTIME_HOME"
   /tmp/gitmoot-current init --home "$GITMOOT_SMOKE_HOME"
   ```

2. Build both plugin packages.

   ```sh
   /tmp/gitmoot-current plugin build codex --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current plugin build claude --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current plugin path codex --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current plugin path claude --home "$GITMOOT_SMOKE_HOME"
   ```

3. Diagnose the built packages.

   ```sh
   /tmp/gitmoot-current plugin doctor --home "$GITMOOT_SMOKE_HOME" || true
   /tmp/gitmoot-current plugin doctor codex --home "$GITMOOT_SMOKE_HOME" || true
   /tmp/gitmoot-current plugin doctor claude --home "$GITMOOT_SMOKE_HOME" || true
   ```

   Missing runtime CLIs are valid in this smoke path. Continue when doctor
   reports `runtime-cli` failures for missing `codex` or `claude`.

4. Install with an isolated runtime home.

   ```sh
   HOME="$GITMOOT_RUNTIME_HOME" /tmp/gitmoot-current plugin install codex --home "$GITMOOT_SMOKE_HOME" --force
   HOME="$GITMOOT_RUNTIME_HOME" /tmp/gitmoot-current plugin install claude --home "$GITMOOT_SMOKE_HOME" --scope user --force
   ```

   If `codex` or `claude` is not installed, the command should keep generated
   files and print manual install commands instead of failing after partial
   destructive work.

5. Validate diagnostics again after install.

   ```sh
   /tmp/gitmoot-current plugin doctor --home "$GITMOOT_SMOKE_HOME" || true
   /tmp/gitmoot-current plugin doctor codex --home "$GITMOOT_SMOKE_HOME" || true
   /tmp/gitmoot-current plugin doctor claude --home "$GITMOOT_SMOKE_HOME" || true
   ```

Expected signals:

- `plugin path codex` and `plugin path claude` point under
  `$GITMOOT_SMOKE_HOME/.gitmoot/plugins/build`.
- Each generated package contains `skills/gitmoot/SKILL.md`.
- Doctor reports readable manifests and copied skill files.
- Runtime marketplace or install state is written under `$GITMOOT_RUNTIME_HOME`,
  not the real user home.
- Missing runtime CLIs are reported as diagnostics with next steps, not as
  corrupt generated packages.

## One-Repo Smoke Test

Goal: PR comment -> queued ask job -> adapter result -> attributed PR comment
-> local job status update. This intentionally uses `ask`, not `review`, so
the smoke test cannot approve or merge the PR.

1. Register the repo and a shell smoke agent.

   ```sh
   gitmoot setup --repo owner/project --path . --agent shell-smoke --runtime shell --session "printf '%s\n' '{\"gitmoot_result\":{\"decision\":\"approved\",\"summary\":\"shell ask smoke passed\",\"findings\":[],\"changes_made\":[],\"tests_run\":[\"shell smoke\"],\"needs\":[],\"next_agents\":[]}}'"
   gitmoot agent repos shell-smoke
   ```

2. Start the background daemon.

   ```sh
   gitmoot daemon start --repo owner/project --poll 30s
   gitmoot daemon status
   ```

3. Open a small test PR in `owner/project`, then comment:

   ```text
   /gitmoot help
   /gitmoot shell-smoke ask smoke test routing
   ```

4. Confirm the job was queued and completed.

   ```sh
   gitmoot job list --repo owner/project
   gitmoot events --repo owner/project
   gh pr view <number> --repo owner/project --comments
   ```

Expected signals:

- The PR receives a Gitmoot queued-job acknowledgement.
- `gitmoot job list --repo owner/project` shows the job as succeeded.
- The PR receives a result comment with:

  ```md
  > Agent: `shell-smoke`
  > Runtime: `shell`
  > Job: `...`
  ```

- `gitmoot events --repo owner/project` shows the queued/running/succeeded
  job events.

5. Stop the daemon when finished.

   ```sh
   gitmoot daemon stop
   gitmoot daemon status
   ```

## Thermo Template Smoke Test

Goal: PR comment -> queued review job -> Codex resume with cached thermo template
instructions -> attributed PR result comment. Run this with a Gitmoot build that
includes `gitmoot agent template` commands.

1. Cache the template and start a Gitmoot-managed Codex review agent.

   ```sh
   gitmoot agent template update thermo-nuclear-code-quality-review
   gitmoot agent start thermo-review \
     --runtime codex \
     --repo owner/project \
     --path . \
     --template thermo-nuclear-code-quality-review
   gitmoot agent doctor thermo-review
   ```

   Gitmoot prints the created session id. To inspect that Codex thread later:

   ```sh
   codex resume <session-id>
   ```

   If you prefer registering an already-open Codex session, use
   `gitmoot agent subscribe ... --session <session-id-or-last>` instead.

2. Start the daemon for the test repo, or pass `--start-daemon` to
   `agent start`.

   ```sh
   gitmoot daemon start --repo owner/project --poll 10s
   gitmoot daemon status
   ```

3. Open a disposable PR, then comment:

   ```text
   /gitmoot thermo-review review
   ```

4. Verify the queued job and PR result.

   ```sh
   gitmoot job list --repo owner/project
   gh pr view <number> --repo owner/project --comments
   ```

Expected signals:

- The PR receives a queued-job acknowledgement for `thermo-review`.
- `gitmoot job list --repo owner/project` shows the review job.
- The result comment includes template attribution:

  ```md
  > Agent: `thermo-review`
  > Runtime: `codex`
  > Template: `thermo-nuclear-code-quality-review`
  > Job: `...`
  ```

5. Check or refresh the cached template only through explicit commands.

   ```sh
   gitmoot agent template diff thermo-nuclear-code-quality-review
   gitmoot agent template update thermo-nuclear-code-quality-review
   ```

## Planner Template Smoke Test

Goal: canonical goal template -> cached planner template -> Gitmoot-managed Codex
planner agent. This verifies the planning workflow is discoverable before using
it on a real PR.

1. Build a local test binary and use an isolated Gitmoot home.

   ```sh
   GOTOOLCHAIN=go1.26.0 go build -o /tmp/gitmoot-current ./cmd/gitmoot
   export GITMOOT_SMOKE_HOME=/tmp/gitmoot-planner-template-smoke
   rm -rf "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current init --home "$GITMOOT_SMOKE_HOME"
   ```

2. Confirm the canonical template and planner template are available.

   ```sh
   /tmp/gitmoot-current goal template | grep "codex exec review is clean; ready for manual /review."
   /tmp/gitmoot-current agent template list --home "$GITMOOT_SMOKE_HOME" | grep planner
   /tmp/gitmoot-current agent template update --home "$GITMOOT_SMOKE_HOME" planner
   /tmp/gitmoot-current agent template show --home "$GITMOOT_SMOKE_HOME" planner
   ```

3. From the test repo checkout, start the planner agent.

   ```sh
   cd /path/to/project
   /tmp/gitmoot-current agent start project-planner-smoke \
     --home "$GITMOOT_SMOKE_HOME" \
     --runtime codex \
     --repo owner/project \
     --path . \
     --template planner \
     --start-daemon
   /tmp/gitmoot-current agent doctor project-planner-smoke --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current daemon status --home "$GITMOOT_SMOKE_HOME"
   ```

4. Ask the planner directly through the local agent path.

   ```sh
   /tmp/gitmoot-current agent ask project-planner-smoke \
     --home "$GITMOOT_SMOKE_HOME" \
     --repo owner/project \
     "Write a task-by-task implementation plan for this feature, then create the goal file prompt."
   /tmp/gitmoot-current job list --home "$GITMOOT_SMOKE_HOME" --repo owner/project
   /tmp/gitmoot-current job show <local-ask-job-id> --home "$GITMOOT_SMOKE_HOME"
   ```

5. Open a disposable PR, then comment:

   ```text
   /gitmoot project-planner-smoke ask Write a task-by-task implementation plan for this feature, then create the goal file prompt.
   ```

6. Verify the queued PR job and PR result.

   ```sh
   /tmp/gitmoot-current job list --home "$GITMOOT_SMOKE_HOME" --repo owner/project
   /tmp/gitmoot-current job show <pr-ask-job-id> --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current events --home "$GITMOOT_SMOKE_HOME" --repo owner/project
   gh pr view <number> --repo owner/project --comments
   ```

Expected signals:

- `goal template` prints the canonical PR-per-task prompt.
- `agent template show` displays `default role: planner`, `default capabilities: ask`,
  and `mutation: true`.
- `agent doctor project-planner-smoke` succeeds.
- `agent ask project-planner-smoke` prints `state: succeeded`, `agent: project-planner-smoke`,
  `action: ask`, and a planner summary.
- `job show <local-ask-job-id>` includes `"sender": "local"`, the cached
  `planner` template metadata, and the planner result.
- The PR result comment includes `Template: planner`.
- The planner returns a structured plan and, when requested, a
  `GOAL-<short-slug>.md` path plus `/goal GOAL-<short-slug>.md`.

7. Stop the isolated daemon.

   ```sh
   /tmp/gitmoot-current daemon stop --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current daemon status --home "$GITMOOT_SMOKE_HOME"
   ```

## Ranked SkillOpt Exploration Smoke Test

Goal: clean temp home -> N-way exploration run -> option artifact registration
-> Markdown packet export/import -> ranked pairwise expansion -> training
package inspection. The optional GitHub step proves the same packet can be
published to a review issue or PR and synced back.

1. Build a local test binary and use isolated directories.

   ```sh
   GOTOOLCHAIN=go1.26.0 go build -o /tmp/gitmoot-current ./cmd/gitmoot
   export GITMOOT_SMOKE_HOME=/tmp/gitmoot-ranked-smoke
   export GITMOOT_SMOKE_WORK=/tmp/gitmoot-ranked-smoke-work
   rm -rf "$GITMOOT_SMOKE_HOME" "$GITMOOT_SMOKE_WORK"
   mkdir -p "$GITMOOT_SMOKE_WORK"
   /tmp/gitmoot-current init --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current agent template draft ranked-smoke-template \
     --output "$GITMOOT_SMOKE_WORK/ranked-smoke-template.md" \
     --force
   /tmp/gitmoot-current agent template add ranked-smoke-template \
     --home "$GITMOOT_SMOKE_HOME" \
     --file "$GITMOOT_SMOKE_WORK/ranked-smoke-template.md"
   ```

2. Create four tiny option artifacts.

   ```sh
   printf 'Hero A: compact title, mascot first.\n' > "$GITMOOT_SMOKE_WORK/hero-a.md"
   printf 'Hero B: long product explanation, no motion.\n' > "$GITMOOT_SMOKE_WORK/hero-b.md"
   printf 'Hero C: clear product explanation, balanced visual.\n' > "$GITMOOT_SMOKE_WORK/hero-c.md"
   printf 'Hero D: animation-heavy layout, weaker copy.\n' > "$GITMOOT_SMOKE_WORK/hero-d.md"
   ```

3. Create an exploration run and register the option artifacts.

   ```sh
   /tmp/gitmoot-current skillopt review create \
     --home "$GITMOOT_SMOKE_HOME" \
     --template ranked-smoke-template \
     --repo owner/gitmoot-web \
     --run ranked-smoke-001 \
     --mode explore \
     --exploration-level high \
     --options 4

   /tmp/gitmoot-current skillopt review item add \
     --home "$GITMOOT_SMOKE_HOME" \
     --run ranked-smoke-001 \
     --item hero-001 \
     --title "Ranked smoke hero" \
     --option a="$GITMOOT_SMOKE_WORK/hero-a.md" \
     --option b="$GITMOOT_SMOKE_WORK/hero-b.md" \
     --option c="$GITMOOT_SMOKE_WORK/hero-c.md" \
     --option d="$GITMOOT_SMOKE_WORK/hero-d.md" \
     --metadata-json '{"task":"landing-page","preview_url":"https://example.invalid/preview"}'
   ```

4. Export the local Markdown packet, fill ranked feedback, and import it.

   ```sh
   /tmp/gitmoot-current skillopt feedback markdown export \
     --home "$GITMOOT_SMOKE_HOME" \
     --run ranked-smoke-001 \
     --output "$GITMOOT_SMOKE_WORK/packet"

   cat > "$GITMOOT_SMOKE_WORK/packet/feedback.yml" <<'EOF'
   run_id: ranked-smoke-001
   reviewer: smoke
   items:
     - item_id: hero-001
       ranking:
         - C > A > D > B
       useful_traits:
         C:
           - clearest product explanation
         A:
           - strongest visual identity
       rejected_traits:
         B:
           - too generic
       reasoning: C is clearest overall, with A worth preserving visually.
   EOF

   /tmp/gitmoot-current skillopt feedback markdown import \
     --home "$GITMOOT_SMOKE_HOME" \
     --packet "$GITMOOT_SMOKE_WORK/packet"
   ```

5. Inspect status and export the training package.

   ```sh
   /tmp/gitmoot-current skillopt review status \
     --home "$GITMOOT_SMOKE_HOME" \
     --run ranked-smoke-001

   /tmp/gitmoot-current skillopt export \
     --home "$GITMOOT_SMOKE_HOME" \
     --run ranked-smoke-001 \
     --output "$GITMOOT_SMOKE_WORK/training.json"

   node -e 'const fs=require("fs"); const p=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); console.log(JSON.stringify({mode:p.eval_run.mode, options:p.items[0].options.length, ranked:p.ranked_feedback_events.length, pairwise:p.pairwise_preferences.length}, null, 2));' "$GITMOOT_SMOKE_WORK/training.json"
   ```

Expected signals:

- `review create` prints `created review ranked-smoke-001`.
- `review item add` prints `added review item hero-001`.
- `feedback markdown export` writes `index.md`, `feedback.yml`, hidden
  assignment metadata, and a collision-safe linked item file such as
  `items/hero-001-<hash>.md` under the temp work directory.
- `feedback markdown import` prints `imported 1 feedback events`.
- `review status` prints `mode: explore`, `feedback: 1`,
  `pairwise_preferences: 6`, `packet_blockers: 0`, and
  `training_blockers: 0`.
- The exported package inspection prints:

  ```json
  {
    "mode": "explore",
    "options": 4,
    "ranked": 1,
    "pairwise": 6
  }
  ```

6. Optional GitHub collector smoke with a disposable issue or PR.

   Use a repository intended for review packets, not the real project repo
   unless that is intentional.

   ```sh
   /tmp/gitmoot-current skillopt feedback github publish \
     --home "$GITMOOT_SMOKE_HOME" \
     --run ranked-smoke-001 \
     --repo owner/reviews

   gh issue comment <issue-number> --repo owner/reviews --body 'run_id: ranked-smoke-001
   hero-001 ranking: C > A > D > B
   best traits:
   - C: clearest product explanation
   - A: strongest visual identity
   reject:
   - B: too generic'

   /tmp/gitmoot-current skillopt feedback github sync \
     --home "$GITMOOT_SMOKE_HOME" \
     --run ranked-smoke-001 \
     --repo owner/reviews \
     --issue <issue-number>
   ```

   For PR comment mode, use `--pr <number>` instead of `--issue <number>` in
   `publish` and `sync`.

Expected GitHub signals:

- The published issue or PR comment contains a ranked feedback packet with the
  same item id, `hero-001`.
- `github sync` imports matching comments and ignores unrelated comments.
- A repeated sync does not duplicate already imported feedback from the same
  comment URL.

## Agent Start Smoke Test

Goal: prove `gitmoot agent start` can create a Codex session, store the session
reference, start the daemon, and route a PR comment job through that new
session.

1. Build a local test binary and use an isolated Gitmoot home.

   ```sh
   GOTOOLCHAIN=go1.26.0 go build -o /tmp/gitmoot-current ./cmd/gitmoot
   export GITMOOT_SMOKE_HOME=/tmp/gitmoot-agent-start-smoke
   rm -rf "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current init --home "$GITMOOT_SMOKE_HOME"
   ```

2. From the test repo checkout, cache the template and start the agent.

   ```sh
   cd /path/to/project
   /tmp/gitmoot-current agent template update --home "$GITMOOT_SMOKE_HOME" thermo-nuclear-code-quality-review
   /tmp/gitmoot-current agent start thermo-start-smoke \
     --home "$GITMOOT_SMOKE_HOME" \
     --runtime codex \
     --repo owner/project \
     --path . \
     --template thermo-nuclear-code-quality-review \
     --start-daemon
   /tmp/gitmoot-current agent list --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current daemon status --home "$GITMOOT_SMOKE_HOME"
   ```

3. Open a disposable PR, then comment:

   ```text
   /gitmoot thermo-start-smoke review
   ```

4. Verify the job and PR comments.

   ```sh
   /tmp/gitmoot-current job list --home "$GITMOOT_SMOKE_HOME" --repo owner/project
   /tmp/gitmoot-current events --home "$GITMOOT_SMOKE_HOME" --repo owner/project
   gh pr view <number> --repo owner/project --comments
   ```

Expected signals:

- `agent list` shows `thermo-start-smoke` with a generated Codex session id.
- The PR receives a queued-job acknowledgement.
- The job succeeds and the result comment includes agent, runtime, template, and
  job metadata.
- `codex resume <session-id>` opens the created session if manual inspection is
  needed.

5. Stop the isolated daemon.

   ```sh
   /tmp/gitmoot-current daemon stop --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current daemon status --home "$GITMOOT_SMOKE_HOME"
   ```

## Custom Prompt Template Smoke Test

Goal: local v1 template file -> cached custom template -> template-backed Codex
agent -> queued PR comment job with custom template metadata.

Prerequisites: a safe test repository, authenticated `gh`, installed Codex, and
a Gitmoot build that includes `agent template draft` and `agent template add`.

1. Build a local test binary and use an isolated Gitmoot home.

   ```sh
   GOTOOLCHAIN=go1.26.0 go build -o /tmp/gitmoot-current ./cmd/gitmoot
   export GITMOOT_SMOKE_HOME=/tmp/gitmoot-custom-template-smoke
   rm -rf "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current init --home "$GITMOOT_SMOKE_HOME"
   ```

2. From the test repo checkout, create and install a local v1 template.

   ```sh
   cd /path/to/project
   mkdir -p agents
   /tmp/gitmoot-current agent template draft local-reviewer \
     --output agents/local-reviewer.md \
     --force
   $EDITOR agents/local-reviewer.md
   /tmp/gitmoot-current agent template validate agents/local-reviewer.md
   /tmp/gitmoot-current agent template add local-reviewer \
     --home "$GITMOOT_SMOKE_HOME" \
     --file agents/local-reviewer.md
   /tmp/gitmoot-current agent template show --home "$GITMOOT_SMOKE_HOME" local-reviewer
   ```

3. Start or subscribe a Codex test agent with the custom template.

   ```sh
   /tmp/gitmoot-current agent start local-reviewer \
     --home "$GITMOOT_SMOKE_HOME" \
     --runtime codex \
     --repo owner/project \
     --path . \
     --template local-reviewer \
     --role reviewer \
     --capability ask \
     --capability review \
     --start-daemon
   /tmp/gitmoot-current agent doctor local-reviewer --home "$GITMOOT_SMOKE_HOME"
   ```

   To register an existing session instead, use:

   ```sh
   /tmp/gitmoot-current agent subscribe local-reviewer \
     --home "$GITMOOT_SMOKE_HOME" \
     --runtime codex \
     --session <session-id-or-last> \
     --repo owner/project \
     --template local-reviewer \
     --role reviewer \
     --capability ask \
     --capability review
   /tmp/gitmoot-current daemon start \
     --home "$GITMOOT_SMOKE_HOME" \
     --repo owner/project \
     --poll 10s
   ```

4. Open a disposable PR, then comment:

   ```text
   /gitmoot local-reviewer review
   ```

5. Verify the job and metadata.

   ```sh
   /tmp/gitmoot-current job list --home "$GITMOOT_SMOKE_HOME" --repo owner/project
   /tmp/gitmoot-current job show <job-id> --home "$GITMOOT_SMOKE_HOME"
   gh pr view <number> --repo owner/project --comments
   ```

Expected signals:

- `agent template show` displays `source: local@file:` and `resolved commit: sha256:...`.
- The PR receives a queued-job acknowledgement for `local-reviewer`.
- The result comment includes `Agent`, `Runtime`, `Template`, and `Job` metadata.
- `job show <job-id>` includes the custom template id and `sha256:` content hash.

6. Edit and refresh the template only through explicit template commands.

   ```sh
   $EDITOR agents/local-reviewer.md
   /tmp/gitmoot-current agent template validate agents/local-reviewer.md
   /tmp/gitmoot-current agent template diff --home "$GITMOOT_SMOKE_HOME" local-reviewer
   /tmp/gitmoot-current agent template update --home "$GITMOOT_SMOKE_HOME" local-reviewer
   ```

7. Stop the isolated daemon.

   ```sh
   /tmp/gitmoot-current daemon stop --home "$GITMOOT_SMOKE_HOME"
   /tmp/gitmoot-current daemon status --home "$GITMOOT_SMOKE_HOME"
   ```

## Template Capture Smoke Test

Goal: current-chat template capture semantics -> draft scaffold -> structural
validation -> local template install -> prompt reuse, without requiring a live
background agent or PR comment.

Prerequisites: a Gitmoot build that includes `agent template draft` and
`agent template validate`.

1. Build a local test binary and use an isolated Gitmoot home.

   ```sh
   GOTOOLCHAIN=go1.26.0 go build -o /tmp/gitmoot-current ./cmd/gitmoot
   export GITMOOT_SMOKE_HOME="$(mktemp -d)"
   export GITMOOT_DRAFT_FILE="$GITMOOT_SMOKE_HOME/release-planner.md"
   /tmp/gitmoot-current init --home "$GITMOOT_SMOKE_HOME"
   ```

2. Scaffold a draft file.

   ```sh
   /tmp/gitmoot-current agent template draft release-planner \
     --home "$GITMOOT_SMOKE_HOME" \
     --output "$GITMOOT_DRAFT_FILE"
   ```

3. In a Codex or Claude Code chat with the Gitmoot plugin/skill installed, fill
   that draft from visible current-chat context:

   ```text
   Use Gitmoot to capture this session as agent template release-planner. Draft only.
   ```

4. After reviewing the filled draft, validate, install, and inspect the captured
   template.

   ```sh
   /tmp/gitmoot-current agent template validate "$GITMOOT_DRAFT_FILE"
   /tmp/gitmoot-current agent template add release-planner \
     --home "$GITMOOT_SMOKE_HOME" \
     --file "$GITMOOT_DRAFT_FILE"
   /tmp/gitmoot-current agent template show \
     --home "$GITMOOT_SMOKE_HOME" \
     release-planner
   /tmp/gitmoot-current agent prompt release-planner \
     --home "$GITMOOT_SMOKE_HOME"
   ```

Expected signals:

- `agent template draft` writes `$GITMOOT_DRAFT_FILE` with the standard
  title and required sections.
- The current-chat capture step fills the draft from visible context without
  starting a daemon, queueing a job, or installing the template.
- `agent template validate` succeeds for the draft and reports clear missing
  sections or placeholders if the file is edited into an invalid state.
- `agent template show` displays `source: local@file:` and
  `resolved commit: sha256:...`.
- `agent prompt release-planner` prints the installed template content for
  current-chat reuse.

## Two-Repo Smoke Test

Goal: one daemon -> two registered repos -> same allowed agent -> ask jobs in
each repo -> no cross-routing. This intentionally avoids approving reviews.

1. Register both repos with the same agent identity.

   ```sh
   cd /path/to/project-a
   gitmoot setup --repo owner/project-a --path . --agent shell-smoke --runtime shell --session "printf '%s\n' '{\"gitmoot_result\":{\"decision\":\"approved\",\"summary\":\"repo ask smoke passed\",\"findings\":[],\"changes_made\":[],\"tests_run\":[\"shell smoke\"],\"needs\":[],\"next_agents\":[]}}'"

   cd /path/to/project-b
   gitmoot setup --repo owner/project-b --path . --agent shell-smoke --runtime shell --session "printf '%s\n' '{\"gitmoot_result\":{\"decision\":\"approved\",\"summary\":\"repo ask smoke passed\",\"findings\":[],\"changes_made\":[],\"tests_run\":[\"shell smoke\"],\"needs\":[],\"next_agents\":[]}}'"

   gitmoot agent repos shell-smoke
   ```

2. Start one daemon for all enabled repos.

   ```sh
   gitmoot daemon start
   gitmoot daemon status
   gitmoot status
   ```

3. Open one test PR in each repo. Comment in each PR:

   ```text
   /gitmoot shell-smoke ask repo routing smoke
   ```

4. Verify each repo saw only its own job.

   ```sh
   gitmoot job list --repo owner/project-a
   gitmoot job list --repo owner/project-b
   gitmoot events --repo owner/project-a
   gitmoot events --repo owner/project-b
   gh pr view <project-a-pr> --repo owner/project-a --comments
   gh pr view <project-b-pr> --repo owner/project-b --comments
   ```

Expected signals:

- Each PR receives exactly the acknowledgement and result for its own comment.
- `gitmoot job list --repo owner/project-a` does not show project B jobs.
- `gitmoot job list --repo owner/project-b` does not show project A jobs.
- The same agent name is allowed on both repos:

  ```sh
  gitmoot agent repos shell-smoke
  ```

## Execution Model Smoke Test

Goal: verify the final `here` versus `background` execution model and the
resource scheduling rules.

1. Confirm fast planner guidance does not start a background runtime job.

   In a Codex or Claude chat with the Gitmoot skill installed, ask:

   ```text
   Use the Gitmoot planner here. Write a task-by-task implementation plan for a README wording update.
   ```

   Expected signal: the answer appears directly in the current chat, and
   `gitmoot job list --repo owner/project` does not gain a new planner job.

2. Queue two background asks to the same registered Codex or Claude agent.

   ```sh
   gitmoot agent ask project-planner --repo owner/project --background "Say first OK."
   gitmoot agent ask project-planner --repo owner/project --background "Say second OK."
   gitmoot job watch <first-job-id>
   gitmoot job watch <second-job-id>
   ```

   Expected signal: both jobs finish, but their `job events` do not show
   overlapping runtime delivery for the same `runtime:<runtime>:<runtime_ref>`.
   If the session is already busy, the later job records `runtime_lock_wait` and
   remains queued until a worker can retry it.

3. Queue background asks that can use independent managed instances.

   ```sh
   gitmoot agent type set project-planner --runtime codex --template planner --max-background 2 --idle-timeout 20m
   gitmoot daemon start --repo owner/project --workers 2
   gitmoot agent ask project-planner --repo owner/project --background "Say planner A OK."
   gitmoot agent ask project-planner --repo owner/project --background "Say planner B OK."
   gitmoot job list --repo owner/project
   ```

   Expected signal: Gitmoot may create or reuse up to two managed planner
   instances, different runtime references can run concurrently, and
   `gitmoot agent gc` later removes expired idle instances.

## Recovery Checks

Run these against one smoke job if you need to verify recovery UX:

```sh
gitmoot job show <job-id>
gitmoot job events <job-id>
gitmoot job retry <job-id>
gitmoot job cancel <job-id>
gitmoot lock list --repo owner/project
gitmoot lock show owner/project <branch>
```

Only retry failed, blocked, or cancelled jobs. Only cancel queued or running
jobs. Use `gitmoot lock release owner/project <branch> --owner <agent>` for an
exact-owner stale lock; use `--force` only when the stored owner is stale.

## Known V1 Limits

- Local-only: the machine running the daemon must stay online.
- Polling watches GitHub; there is no webhook receiver.
- GitHub comments are authored by the authenticated `gh` user, not a bot.
- Agent identity is shown in the comment body.
- There is no hosted dashboard, GitHub App bot identity, cloud runner, billing,
  or remote control plane.

---

# Source: skills/gitmoot/SKILL.md

---
name: gitmoot
description: Use Gitmoot for local-first AI agent coordination across repositories, goals, reviews, GitHub PR comments, agent subscriptions, daemon checks, jobs, branch locks, agent-templates, template capture, custom prompt agents, and Codex or Claude Code runtime workflows.
license: Apache-2.0
compatibility: Requires the gitmoot CLI, git, GitHub CLI authentication, network access to GitHub, and a supported runtime such as Codex or Claude Code.
metadata:
  gitmoot-version: "0.1.0"
  source: "jerryfane/gitmoot"
---

# Gitmoot Agent Skill

Gitmoot is a local-first coordinator for AI agents working across repositories,
goals, 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 or Claude Code agent startup, structured
implementation plans, standard goal files, agent template workflows, custom
prompt agents, template capture, job status, or branch lock inspection.

For current-chat prompt import, "use <agent> here" or "use Gitmoot agent
<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. The natural phrase "use the Gitmoot planner here" maps
to the same `planner` template used by managed planner agents. If the planner
template is not cached, read and apply the packaged
`agent-templates/planner.md` instructions directly. 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 template capture, phrases like "capture this session as a Gitmoot agent
template", "turn this workflow into a Gitmoot template", or "draft a reusable
agent template from this chat" mean read [TEMPLATE_CAPTURE.md](references/TEMPLATE_CAPTURE.md)
and distill the visible current-chat context into a draft template. Gitmoot
cannot read hidden model memory or runtime internals. Do not install, overwrite,
or update a permanent template unless the user explicitly approves that step.
Use `gitmoot agent template draft <id>` for a blank scaffold,
`gitmoot agent template validate <file>` for a structural check,
`gitmoot agent template add <id> --file <file>` to install a snapshot, and
`gitmoot agent prompt <id>` to reuse the installed template in the current chat.

For background work, keep Gitmoot's resource model explicit: repo checkout
locks protect local checkouts, runtime session locks serialize delivery for the
same Codex or Claude 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.

## 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.
4. Do not start daemons, create agents, update agent templates, or change
   subscriptions unless the user asks or the current task clearly requires it.
5. Prefer read-only status commands before mutating Gitmoot state.

## Common Commands

Use `gitmoot status --repo owner/repo` for repo status, `gitmoot daemon status`
for daemon state, `gitmoot agent list` for registered agents, and
`gitmoot agent prompt <agent-or-template>` to import an agent prompt into the
current chat. Use `gitmoot agent ask <agent> --repo owner/repo "..."` to invoke
a registered Gitmoot agent through the runtime adapter path. Add `--background`
only when the user wants a queued background job. Use
`gitmoot job list --repo owner/repo` for queued or recent jobs. Use
`gitmoot plugin doctor` when checking whether Codex or Claude Code can discover
Gitmoot through an installed runtime plugin. Use `gitmoot goal template` when
writing a standard task-by-task goal file.

The plugin is only the runtime discovery surface for this skill. Local agent
invocation still goes through the `gitmoot` CLI and the same registered agent,
repo access, runtime adapter, and job history model used by PR-comment jobs.

For SkillOpt template learning, prefer the high-level
`gitmoot skillopt train start/status/continue/stop` workflow when the user wants
Gitmoot to enforce the full feedback, optimizer, candidate-review, and
promotion loop. Use low-level `gitmoot skillopt review`, `feedback`, `export`,
`import`, and `candidate` commands for advanced/debug work or when recovering a
specific step. In train mode, collect enough ranked feedback and trait notes
before optimizer handoff, keep promotion decisions explicit, and start follow-up
iterations only through `train continue --start-next`.

For complete command examples, read [CLI.md](references/CLI.md).
For end-to-end workflows, read [WORKFLOWS.md](references/WORKFLOWS.md).
For current-chat template capture, read
[TEMPLATE_CAPTURE.md](references/TEMPLATE_CAPTURE.md).
For the canonical goal prompt template, read
[GOAL_TEMPLATE.md](references/GOAL_TEMPLATE.md) only when the user asks for a
goal file.

## Agent Job Contract

Every Gitmoot job should return a concise and truthful `gitmoot_result` JSON
object. Use `blocked` when work cannot continue without human input or external
state, and `failed` when an attempted action errored.

For the required result shape and decision meanings, read
[RESULT_CONTRACT.md](references/RESULT_CONTRACT.md).

## Safety Rules

Preserve existing behavior unless the job explicitly changes it. Keep work
scoped to the target repo. Do not commit generated data, caches, logs, secrets,
session archives, cloned helper repos, or large outputs unless explicitly
requested. Respect Gitmoot branch locks for implementation jobs.

For detailed safety and lock rules, read [SAFETY.md](references/SAFETY.md).

## When Unsure

Reread this `SKILL.md`, then inspect `/gitmoot help`, `gitmoot status`, and the
relevant job events before acting.

---

# Source: skills/gitmoot/agent-templates/planner.md

---
id: planner
name: Gitmoot Planner
description: Structured planning and standard goal-file agent template for Gitmoot workflows, usable in current chat or as a managed agent.
kind: agent-template
version: 1
capabilities:
  - ask
runtime_compatibility:
  - codex
  - claude
tags:
  - planning
  - goals
  - pull-requests
inputs:
  - repo
  - task
  - visible_context
outputs:
  - plan
  - goal_file
evaluation:
  driver: gitmoot-planner
  preferred_gate: pairwise
---

# Gitmoot Planner

You are the Gitmoot planner agent template. You can be used in the current
Codex or Claude chat with "planner here", or as a Gitmoot-managed background
agent. Your job is to turn feature requests into clean implementation plans
and, when asked, write a standard Gitmoot goal file.

## Planning Workflow

1. Inspect the current repo state and relevant existing patterns before writing
   the plan. In current-chat mode, inspect only the files needed to plan.
2. Use web search when the request depends on current external APIs, CLI
   contracts, docs, standards, package behavior, deployment behavior, or
   best-practice claims. Prefer official or primary sources.
3. Ask clarifying questions only for high-impact product decisions that cannot
   be discovered from the repo or official sources.
4. Write a decision-complete plan that another engineer or agent can implement
   without guessing.
5. Split the plan into tasks. Each task should have a clear scope, PR boundary
   when relevant, acceptance criteria, tests/checks, and suggested commit
   message.
6. Keep the plan clean and organized. Preserve existing behavior unless the
   requested feature explicitly changes it. Avoid broad rewrites.
7. Avoid code duplication. When repeated logic appears, call out the helper or
   abstraction that should be reused or extracted.

## Goal File Workflow

When asked to write the goal file:

1. Read the canonical standard template with:

   ```sh
   gitmoot goal template
   ```

2. Create a goal file named `GOAL-<short-slug>.md`.
3. Fill the template with the approved plan.
4. Ensure each implementation task uses a heading in this exact form:

   ```markdown
   ### Task N: Task Title
   ```

5. Return the exact prompt the user should run:

   ```text
   /goal GOAL-<short-slug>.md
   ```

Do not implement the planned feature unless the user explicitly asks after the
plan and goal file are complete.

## Current-Chat Use

When the user says "use the Gitmoot planner here", apply these same planner
instructions directly in the current chat. Return the plan in chat. If the user
also asks for a goal file, write the goal file using the workflow above and
return the exact `/goal GOAL-<short-slug>.md` prompt.

---

# Source: skills/gitmoot/references/CLI.md

# Gitmoot CLI Reference

Use these commands from an agent session only when the user asks for Gitmoot
setup, status, agent coordination, or PR-comment workflow help.

## Install And Update

```sh
curl -fsSL https://gitmoot.io/install.sh | sh
gitmoot version
gitmoot update --check
gitmoot update --restart-daemon
```

Verify GitHub access before PR workflows:

```sh
gh auth status
```

## Runtime Plugins

Install Gitmoot's Agent Skill into Codex or Claude Code when the user wants the
runtime to discover Gitmoot workflow guidance from its plugin system:

```sh
gitmoot plugin install codex
gitmoot plugin install claude
gitmoot plugin doctor
```

Inspect or build packages without installing:

```sh
gitmoot plugin build codex
gitmoot plugin build claude
gitmoot plugin path codex
gitmoot plugin path claude
gitmoot plugin doctor codex
gitmoot plugin doctor claude
```

Claude scopes are supported with `--scope user|project|local`. Codex ignores
`--scope` because the current Codex plugin install command does not use it.

## Repo And Daemon Status

```sh
gitmoot status --repo owner/repo
gitmoot events --repo owner/repo
gitmoot daemon start --repo owner/repo --poll 30s --workers 1
gitmoot daemon status
gitmoot daemon logs
gitmoot daemon stop
```

Use `daemon start` for the background daemon. Use `daemon run` only when the
user explicitly wants a foreground process. Keep the default `--workers 1`
unless the Gitmoot home has multiple independent runtime sessions or managed
agent types with `max_background` greater than one.

## Agent Setup

Start a new runtime session managed by Gitmoot:

```sh
gitmoot agent start reviewer \
  --runtime codex \
  --repo owner/repo \
  --path . \
  --role reviewer \
  --capability ask \
  --capability review \
  --start-daemon
```

Subscribe an existing runtime session:

```sh
gitmoot agent subscribe reviewer \
  --runtime codex \
  --session <session-id-or-last> \
  --repo owner/repo \
  --role reviewer \
  --capability ask \
  --capability review
```

Inspect agents:

```sh
gitmoot agent list
gitmoot agent repos reviewer
gitmoot agent doctor reviewer
```

Ask a registered agent from the current local chat:

```sh
gitmoot agent ask project-planner --repo owner/repo "Return the plan status."
gitmoot agent ask project-planner --repo owner/repo --background "Write the implementation plan and goal file."
gitmoot job watch <job-id>
```

This uses the same agent registry, repo access grants, cached template snapshot,
runtime adapter, and local job history as PR-comment ask jobs. The runtime
plugin helps Codex or Claude Code discover Gitmoot guidance, but it does not
replace `gitmoot agent ask`. Synchronous asks and queued jobs both use the same
runtime session locks.

Configure managed background agent types:

```sh
gitmoot agent type list
gitmoot agent type show planner
gitmoot agent type set planner --runtime codex --template planner --max-background 2 --idle-timeout 20m
gitmoot agent gc
```

## Agent Templates

Install or refresh the built-in thermo review template:

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

Install or refresh the built-in full planner/goal template:

```sh
gitmoot agent template update planner
gitmoot agent start project-planner \
  --runtime codex \
  --repo owner/repo \
  --path . \
  --template planner \
  --start-daemon
```

For fast current-chat planning, use the Gitmoot skill with the same packaged
`agent-templates/planner.md` instructions instead of starting a background job:

```text
Use the Gitmoot planner here. Write the implementation plan.
```

The current chat can also import any cached custom agent or template prompt:

```sh
gitmoot agent prompt frontend-reviewer
gitmoot agent prompt frontend-reviewer --json
```

This prints the prompt content for the current chat to apply locally. It does
not create a job, start a daemon, resume a runtime session, or post a PR
comment.

Draft and validate a captured template before installing it:

```sh
gitmoot agent template draft release-planner
gitmoot agent template validate .gitmoot/templates/release-planner.md
gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
```

`agent template draft` only creates the standard markdown structure. For
current-chat capture, the active Codex or Claude chat reads
`references/TEMPLATE_CAPTURE.md` and fills that structure from visible
conversation context. Gitmoot does not extract hidden runtime memory.

Create a local custom prompt template:

```sh
mkdir -p agents
gitmoot agent template draft frontend-reviewer --output agents/frontend-reviewer.md
$EDITOR agents/frontend-reviewer.md
gitmoot agent template validate agents/frontend-reviewer.md
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
gitmoot agent start frontend-reviewer \
  --runtime codex \
  --repo owner/repo \
  --template frontend-reviewer \
  --role reviewer \
  --capability ask \
  --capability review
```

After editing a local template file, refresh Gitmoot's cached snapshot:

```sh
gitmoot agent template diff frontend-reviewer
gitmoot agent template update frontend-reviewer
```

Template updates are versioned locally. `gitmoot agent template show <id>`
prints the current version, content hash, source commit, and promotion state.
Agents use the current promoted version by default, or a pinned version when
configured with a reference such as `--template frontend-reviewer@v1`.
Queued jobs keep the exact template content snapshot they were created with.

Discover templates by metadata:

```sh
gitmoot agent template list --runtime codex --output goal_file
gitmoot agent template list --tag review --capability ask
gitmoot agent template show frontend-reviewer
```

## Goals

Print the standard Gitmoot goal prompt template:

```sh
gitmoot goal template
```

Import a goal file into local Gitmoot state:

```sh
gitmoot goal import --file GOAL-feature.md --repo owner/repo
```

## PR Comments

Use GitHub PR comments as the public audit trail:

```text
/gitmoot help
/gitmoot status
/gitmoot <agent> review [instructions]
/gitmoot <agent> implement [instructions]
/gitmoot ask <agent> [question]
/gitmoot retry <job-id>
/gitmoot cancel <job-id>
/gitmoot merge
```

## Jobs And Locks

```sh
gitmoot job list --repo owner/repo
gitmoot job show <job-id>
gitmoot job watch <job-id>
gitmoot job events <job-id>
gitmoot job retry <job-id>
gitmoot job cancel <job-id>
gitmoot lock list --repo owner/repo
gitmoot lock show owner/repo <branch>
```

## SkillOpt Exchange

```sh
gitmoot skillopt review create --template <id> --repo owner/repo --run <run-id>
gitmoot skillopt review item add --run <run-id> --item <item-id> --baseline baseline.md --candidate candidate.md [--title text]
gitmoot skillopt review create --template <id> --repo owner/repo --run <run-id> --mode explore --exploration-level high --options 4
gitmoot skillopt review item add --run <run-id> --item <item-id> --option a=option-a.md --option b=option-b.md [...]
gitmoot skillopt review status --run <run-id>
gitmoot skillopt export --run <run-id> [--output training.json]
gitmoot skillopt import --file candidate.json [--artifact-dir artifacts]
gitmoot skillopt candidate list [--template id]
gitmoot skillopt candidate show <version-id>
gitmoot skillopt candidate promote <version-id>
gitmoot skillopt candidate reject <version-id> [--reason text]
gitmoot skillopt feedback markdown export --run <run-id> --output .gitmoot/evals/<run-id>
gitmoot skillopt feedback markdown import --packet .gitmoot/evals/<run-id> [--reviewer name]
gitmoot skillopt feedback github publish --run <run-id> [--repo owner/repo] [--pr <number>]
gitmoot skillopt feedback github sync --run <run-id> [--repo owner/repo] (--issue <number>|--pr <number>)
gitmoot skillopt train start --template <id> --repo owner/repo --request <text> --items-file items.yml [--workspace-repo owner/workspace] [--preview-repo owner/previews] [--preview-mode none|optional|required] [--preview-renderer none|vue-vite] [--preview-publisher none|github-pages] [--preview-route-template template] [--yes]
gitmoot skillopt train status --session <id>
gitmoot skillopt train continue --session <id> [--generator-type skillopt-generator | --generator-agent name] [--skillopt-bin path] [--dry-run] [--promote version|--reject version --reason text] [--start-next]
gitmoot skillopt train stop --session <id> --reason <text>
```

Use `skillopt train` for the product workflow. It pins the template version,
tracks sessions and iterations, validates item diversity, generates temporary
agent options, publishes review packets, syncs feedback, hands off to the
external optimizer, imports pending candidates, publishes candidate review
context, and starts follow-up iterations only after a promoted/rejected/abandoned
decision. Use `skillopt review`, `feedback`, `export`, `import`, and
`candidate` directly only for advanced debugging, custom research runs, or
recovering one step of a train session.

`skillopt review create` starts a review run for a template and target repo.
Use the default A/B shape for validation, or pass `--mode explore|refine|distill`
with `--options N` for ranked exploration. `skillopt review item add` stores
saved baseline/candidate outputs as artifact-backed A/B review items, or
repeated `--option label=path` artifacts for ranked N-way items. `skillopt
review status` reports whether the run has items, complete artifacts, imported
feedback for every item, ranking stability, pairwise preference count, and a
recommended next mode. Recommendations are advisory; Gitmoot never changes mode,
imports a candidate, or promotes a template automatically.

`skillopt export` writes a JSON training package with the template snapshot,
eval run, review items, artifact manifests, feedback events when present, and
evaluator config. Use `gitmoot-skillopt optimize --training-package
training.json --artifact-root ~/.gitmoot/evals/blobs --out-root
.gitmoot/skillopt/<run-id> --candidate-output candidate.json --dry-run` first
to validate the contract without model calls.
Before real model-backed optimization, check `gitmoot-skillopt optimize --help`
and verify required model/backend environment variables for the installed
optimizer version. `skillopt import` validates a candidate package and stores
the candidate template as a pending version; it never promotes the candidate
automatically. If the candidate package includes new artifact manifest entries,
pass `--artifact-dir` so Gitmoot can verify relative paths and SHA256 hashes
before storing blobs. `skillopt candidate show` displays candidate metadata, eval
report JSON, preference summary, and a content diff against the base/current
version. `skillopt candidate promote` makes a pending candidate current, while
`skillopt candidate reject` records an auditable rejection and prevents that
version from being selected by `@latest`.

The Markdown feedback collector writes blind A/B review packets with `index.md`,
per-item Markdown files, editable `feedback.yml`, and hidden assignment metadata
that Gitmoot uses to validate the full response and import de-blinded canonical
feedback events. Open `index.md`, review every file in `items/*.md`, set
`reviewer`, edit `feedback.yml` with exactly one of `a`, `b`, `tie`, `neither`,
or `skip` for every item, and leave `.assignments.json` untouched.
Ranked packets use the same files, but `feedback.yml` contains ordered rankings
plus optional `useful_traits`, `rejected_traits`, and reasoning. After feedback
exists, packet summaries hide outcome-bearing phase details so later blind
reviewers do not see the current winner before responding.

The GitHub feedback collector publishes the same blind A/B review packet to a
new issue by default, or to an existing PR when `--pr <number>` is provided.
Repository resolution uses `--repo`, then the eval run target repo, then the
template source repo, then optional `[feedback].repo = "owner/reviews"` in
Gitmoot config. Reviewers can reply with full YAML or run-scoped short-form
lines such as `run_id: run-1` followed by `item-001: b - More concrete.`.
`github sync` imports valid comments into canonical feedback events and ignores
unrelated comments safely.
Ranked GitHub comments can use `item-001 ranking: C > A > D > B` plus trait
notes. Use the ranked workflow for exploration/refinement and return to A/B
validation for final promotion decisions on fresh items.

---

# Source: skills/gitmoot/references/WORKFLOWS.md

# Gitmoot Workflows

## First Repo Setup

1. Confirm the repo identity and GitHub auth.
2. Start the daemon for the repo.
3. Start or subscribe at least one agent.
4. Verify the agent is healthy before asking PR comments to route jobs.

```sh
gh repo view --json nameWithOwner
gh auth status
gitmoot daemon start --repo owner/repo
gitmoot agent start reviewer --runtime codex --repo owner/repo --role reviewer --capability ask --capability review --start-daemon
gitmoot agent doctor reviewer
```

## Review Agent From A PR Comment

1. Register a reviewer agent for the target repo.
2. Ensure the daemon watches the same repo.
3. Comment on the PR.
4. Inspect job status if no result appears.

```text
/gitmoot reviewer review
```

```sh
gitmoot job list --repo owner/repo
gitmoot job show <job-id>
gitmoot job events <job-id>
```

## Built-In Thermo Review Agent

Use the thermo template for strict review-only work. It should not implement code
or request implementation capability.

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

PR comment:

```text
/gitmoot thermo-review review
```

## Custom Prompt Agent

Use custom prompt agent templates for project-specific reviewers or helpers.

```sh
mkdir -p agents
gitmoot agent template draft frontend-reviewer --output agents/frontend-reviewer.md
$EDITOR agents/frontend-reviewer.md
gitmoot agent template validate agents/frontend-reviewer.md
gitmoot agent template add frontend-reviewer --file agents/frontend-reviewer.md
gitmoot agent start frontend-reviewer \
  --runtime codex \
  --repo owner/repo \
  --template frontend-reviewer \
  --role reviewer \
  --capability ask \
  --capability review
```

Custom template content is snapshotted into local Gitmoot state. After editing the
source template file, run `gitmoot agent template diff <id>` and `gitmoot agent template update
<id>` before expecting new jobs to use the changed prompt.

## Current-Chat Planner

Use the same `planner` template in the current Codex or Claude chat when the
user wants a fast implementation plan and the current session already has the
repo context. Load the prompt with `gitmoot agent prompt planner` when it is
cached, or read the packaged `agent-templates/planner.md` instructions from the
Gitmoot skill package. Inspect only the relevant files, use web search only for
current external contracts or best-practice claims, and return the plan directly
in chat.

```text
Use the Gitmoot planner here. Write a task-by-task implementation plan for this feature.
```

If the user asks for a standard goal file, read the canonical goal template and
write the goal file. Do not create a goal file unless explicitly requested.

## Current-Chat Custom Agent Prompt

Use a registered agent or custom template in the current chat when the user says
something like:

```text
Use frontend-reviewer here. Review this diff.
```

Resolve and load the prompt with:

```sh
gitmoot agent prompt frontend-reviewer
```

Treat the returned content as instructions for the current chat. This is prompt
import, not true system-prompt injection, and it does not create a Gitmoot job,
start a daemon, resume a runtime session, or post a PR comment. If the user
wants tracked background execution, use `gitmoot agent ask <agent> --background`
instead.

## Current-Chat Template Capture

Use template capture when the user wants to turn a successful visible Codex or
Claude Code conversation into a reusable agent template.

```text
Use Gitmoot to capture this session as agent template release-planner. Draft only.
```

The current chat reads `references/TEMPLATE_CAPTURE.md`, extracts durable
workflow rules from visible conversation context and inspected files, and writes
or returns a draft. It must not route the request through `gitmoot agent ask`,
start a daemon, queue a job, or install/replace a template without explicit user
approval.

For a blank starting point, scaffold the required sections:

```sh
gitmoot agent template draft release-planner
```

After the user reviews the draft:

```sh
gitmoot agent template validate .gitmoot/templates/release-planner.md
gitmoot agent template add release-planner --file .gitmoot/templates/release-planner.md
gitmoot agent prompt release-planner
```

The capture pieces are distinct:

- `agent template draft`: scaffold a blank structure.
- "capture here": current chat fills that structure from visible context.
- `agent template validate`: structural check.
- `agent template add`: install a snapshot.
- `agent prompt`: reuse the installed prompt in the current chat.
- `agent start --template`: create a runnable background agent instance.

## Background Planner Agent

Use the planner template when the user wants a structured implementation plan or a
standard Gitmoot goal file to run as a tracked Gitmoot background agent job.

```sh
gitmoot agent template update planner
gitmoot agent start project-planner \
  --runtime codex \
  --repo owner/repo \
  --path . \
  --template planner \
  --start-daemon
```

Ask from a PR comment:

```text
/gitmoot project-planner ask Write a task-by-task implementation plan for this feature, then create the goal file prompt.
```

Ask directly from a local Codex or Claude Code chat by having the runtime call
the Gitmoot CLI when the user explicitly wants a registered background-capable
agent path:

```sh
gitmoot agent ask project-planner --repo owner/repo --background "Write a task-by-task implementation plan for this feature, then create the goal file prompt."
gitmoot job watch <job-id>
```

If the Codex plugin exposes a Gitmoot command bridge in chat, the equivalent
form is `$gitmoot:gitmoot agent ask project-planner --repo owner/repo --background "..."`. The
important part is that background planner work goes through `gitmoot agent ask`;
fast "here" planning stays in the current chat and uses `gitmoot agent prompt`
only to read prompt content.

If the planner writes a goal file and the user wants Gitmoot to track it, import
it explicitly:

```sh
gitmoot goal import --file GOAL-feature.md --repo owner/repo
```

## SkillOpt Train Mode

Use `gitmoot skillopt train` when a user wants Gitmoot to enforce the complete
template-learning loop. Use low-level `skillopt review`, `feedback`, `export`,
`import`, and `candidate` commands only for advanced/debug work, custom
research runs, or one-step recovery.

```sh
gitmoot skillopt train start \
  --template planner \
  --session planner-train \
  --repo owner/product \
  --workspace-repo owner/product-workspace \
  --preview-repo owner/product-previews \
  --request "Improve release planning answers from reviewer feedback" \
  --items-file train-items.yml \
  --mode explore \
  --exploration-level high \
  --options 4 \
  --preferred-gate hard_then_soft \
  --yes

gitmoot skillopt train status --session planner-train
gitmoot skillopt train continue --session planner-train
```

Train sessions contain one or more iterations. Each iteration pins a base
template version, owns one eval review run, stores workspace/preview metadata,
collects ranked or A/B feedback, exports a training package, imports one
pending optimizer candidate, and records an explicit promote/reject/abandon
decision. The next iteration starts only through:

```sh
gitmoot skillopt train continue --session planner-train --start-next
```

If the previous candidate was promoted, the promoted candidate version becomes
the next base. Rejections require a reason. Manual append-style next iterations
are not part of the train workflow.

Preview modes are explicit. Text-only sessions use `preview.mode=none`,
`preview.renderer=none`, and `preview.publisher=none`; GitHub issues contain
inline review content. Landing-page preview sessions use
`--preview-repo owner/previews`, which defaults to `preview.mode=required`,
`preview.renderer=vue-vite`, `preview.publisher=github-pages`, and
`review.expected_repo=owner/previews`. Register the preview checkout first:

```sh
gitmoot repo add owner/previews --path /path/to/previews
```

Run `train continue` once to generate Vue/Vite bundles and a second time to
publish GitHub Pages previews and create the human review issue. Required
previews block inline fallback until every option has `preview_url`; optional
previews use URLs when present and fall back to inline Markdown only when
preview publication is unavailable.

Check `gh auth status --hostname github.com` and
`gh repo view owner/previews --json nameWithOwner` before GitHub-backed review
publication or watching. Gitmoot preflights GitHub issue/comment operations,
but preview publication can push Pages files before a later review issue
preflight fails.

Required Vue/Vite options are validated immediately. An actionable preview
bundle validation failure retries that option once while keeping valid sibling
options. GitHub Pages publication records `preview_commit`, `preview_status`,
and `preview_status_reason`; review links can show `open`,
`pending deployment`, `failed deployment`, or `stale deployment`. Existing
review links keep their recorded status label; `train continue` skips options
that already have a preview URL.

Low-level GitHub feedback publish/sync commands enforce the train run's expected
review repo. Candidate decisions are explicit: promote, reject with a reason,
wait, or reject and `--start-next` to keep improving. LaTeX/PDF, Storybook,
notebook, image, and other preview types are future adapters, not current
renderer/publisher pairs.

Run the deterministic smoke before changing train behavior:

```sh
scripts/skillopt-train-smoke.sh
```

## SkillOpt Ranked Exploration

Use ranked exploration when a template needs broad search before final
validation. Keep final promotion decisions on fresh A/B validation items unless
the user explicitly asks for a different evaluation design.

1. Explore with four to six diverse options per item.
2. Rank every option and capture useful/rejected traits.
3. Refine with two to three combined candidates once a direction stabilizes.
4. Distill the accumulated feedback into a candidate template.
5. Validate current template vs candidate on fresh A/B items.

Landing-page example:

```sh
gitmoot skillopt review create \
  --template landing-page-designer \
  --repo owner/gitmoot-web \
  --run landing-page-explore-001 \
  --mode explore \
  --exploration-level high \
  --options 4

gitmoot skillopt review item add \
  --run landing-page-explore-001 \
  --item hero-001 \
  --title "Gitmoot landing page hero" \
  --option a=previews/hero-a.md \
  --option b=previews/hero-b.md \
  --option c=previews/hero-c.md \
  --option d=previews/hero-d.md

gitmoot skillopt feedback markdown export \
  --run landing-page-explore-001 \
  --output .gitmoot/evals/landing-page-explore-001
```

Non-visual writing tasks use the same shape with text artifacts:

```sh
gitmoot skillopt review create \
  --template x-post-writer \
  --repo owner/content-workflows \
  --run x-post-style-explore-001 \
  --mode explore \
  --options 5

gitmoot skillopt review item add \
  --run x-post-style-explore-001 \
  --item thread-hook-001 \
  --option a=posts/hook-a.txt \
  --option b=posts/hook-b.txt \
  --option c=posts/hook-c.txt \
  --option d=posts/hook-d.txt \
  --option e=posts/hook-e.txt
```

After importing feedback, inspect:

```sh
gitmoot skillopt review status --run landing-page-explore-001
```

Only run the external optimizer when the user wants a candidate update and the
status recommendation is stable enough for the current phase. Do not run heavy
SkillOpt optimization after every tiny feedback round by default.

## Execution Model

Use `here` when the current chat should answer directly from the Gitmoot skill.
Use `background` when Gitmoot should create a tracked job, store events, and run
through a runtime adapter.

Background jobs are scheduled against three distinct resources:

- repo checkout mutexes for daemon ticks that use the same local checkout;
- runtime session locks keyed as `runtime:<runtime>:<runtime_ref>` for Codex
  and Claude delivery;
- branch locks for implementation ownership and merge safety.

The daemon default is `--workers 1`. Users can raise it when jobs target
different runtime sessions or managed agent types with `max_background` greater
than one. Gitmoot still serializes jobs for the same runtime session or checkout
even when more workers are configured.

## Multi-Repo Work

Agents are global identities with explicit per-repo access. When working across
multiple repos, always pass `--repo owner/repo` to status, daemon, job, and event
commands so jobs are routed in the correct repository context.

```sh
gitmoot agent allow reviewer --repo owner/project-a
gitmoot agent allow reviewer --repo owner/project-b
gitmoot status --repo owner/project-a
gitmoot status --repo owner/project-b
```

---

# Source: skills/gitmoot/references/TEMPLATE_CAPTURE.md

# Template Capture

Use template capture when the user wants to turn the current Codex or Claude
Code session into a reusable Gitmoot agent template.

Template capture is current-chat distillation. Gitmoot cannot read hidden model
memory, runtime internals, or private state outside the visible conversation and
files you inspect. Capture only durable, user-approved behavior that can be
reused safely by future agents.

## Trigger Phrases

Use this workflow for requests like:

- "capture this session as a Gitmoot agent template"
- "turn this workflow into a Gitmoot template"
- "draft a reusable agent template from this chat"
- "make this current agent behavior reusable"

Do not route template capture through `gitmoot agent ask`, PR comments, or the
daemon unless the user explicitly asks for a background job. Capture from
"here" means the current chat writes a draft.

## Capture Rules

- Draft first. Do not install, overwrite, or update a permanent template unless
  the user explicitly approves that step.
- Extract durable workflow rules, role, trigger conditions, inputs, commands,
  output contract, safety rules, examples, and non-goals.
- Exclude one-off mistakes, temporary debugging, private secrets, unrelated repo
  details, hidden model memory, and unverified assumptions.
- Prefer project-agnostic language unless the template is intentionally scoped
  to one project or repo.
- Preserve important user preferences that were corrected repeatedly, but write
  them as actionable rules instead of emotional transcript summaries.
- Mark uncertainty as a question or assumption rather than turning it into a
  permanent instruction.
- Ask before installing or replacing an existing template.

## Draft Structure

Use this structure for captured templates:

```markdown
# <Template Name>

## Role

Describe what this agent is responsible for.

## When To Use

List the request types, project contexts, or trigger phrases that should use
this template.

## Workflow

Give the repeatable step-by-step operating procedure.

## Inputs And Context

List the files, commands, tools, docs, conversation context, or repo state the
agent should inspect.

## Commands And Tools

List important CLI commands, runtime commands, web/source lookup requirements,
or tool usage constraints.

## Output Contract

Describe exactly what the agent should return or create.

## Safety Rules

List boundaries, approval gates, non-destructive behavior, secret handling, and
when to stop or ask.

## Examples

Provide a few concise example requests and the expected style of response.

## Non-Goals

List work this template should not do.
```

## Suggested Current-Chat Flow

1. Confirm the requested template id and intended scope if unclear.
2. Inspect relevant visible conversation context and repo files.
3. Draft the markdown template in chat, or write it to the path the user
   requested.
4. Tell the user to check the draft against the structure above before
   installing it:

   ```sh
   gitmoot agent template add <template-id> --file .gitmoot/templates/<template-id>.md
   ```

5. If the user approves installation, check that required sections are filled
   in, then install with `gitmoot agent template add`.

## Result Expectations

The final capture response should say what was drafted, where it is saved if a
file was written, whether validation ran, and whether the template was
installed. If installation was not explicitly requested, say that the draft is
not installed yet.

---

# Source: skills/gitmoot/references/SAFETY.md

# Gitmoot Safety Reference

## Repo Scope

A PR repository is the routing context for `/gitmoot <agent> ...`. Always confirm
or pass `--repo owner/repo` when the user works across multiple repositories.

## Branch Locks

Implementation jobs must respect Gitmoot branch locks. Do not edit or push an
implementation branch unless Gitmoot assigned the job and the branch lock is held
by the assigned agent.

Review and ask jobs should inspect and report without mutating branches unless
the task explicitly instructs otherwise.

Useful commands:

```sh
gitmoot lock list --repo owner/repo
gitmoot lock show owner/repo <branch>
```

## Files And Secrets

Do not commit generated data, caches, logs, build outputs, session archives,
cloned helper repos, secrets, credentials, or large artifacts unless the user or
plan explicitly says they are intended tracked fixtures or release assets.

Redact secrets from GitHub comments, job summaries, raw examples, and copied
command output.

## External Contracts

If the work depends on external APIs, CLIs, env vars, generated scripts, service
launchers, installers, deployment behavior, or third-party libraries, verify the
real contract with local commands and/or official documentation before editing.

## When To Stop

Stop and report `blocked` when the target repo is unclear, GitHub auth is
missing, the daemon cannot access the repo, branch lock ownership is wrong, or
continuing would require credentials or destructive operations the user did not
approve.

---

# Source: skills/gitmoot/references/RESULT_CONTRACT.md

# Gitmoot Result Contract

Every agent job must return a `gitmoot_result` JSON object. Keep it concise,
truthful, and tied to work that actually happened.

```json
{
  "gitmoot_result": {
    "decision": "approved|changes_requested|blocked|implemented|failed",
    "summary": "Brief outcome.",
    "findings": [],
    "changes_made": [],
    "tests_run": [],
    "needs": [],
    "next_agents": []
  }
}
```

## Decisions

- `approved`: review found no blocking issues.
- `changes_requested`: review found issues that should be fixed before merge.
- `blocked`: work cannot continue without human input or an external state change.
- `implemented`: the requested implementation work was completed.
- `failed`: the attempted action errored or could not complete.

## Reporting Rules

- Do not claim tests were run unless they were actually run.
- Do not claim files were changed unless they were actually changed.
- Use `needs` for missing credentials, unclear scope, unavailable tools, failing
  external services, or required human decisions.
- Use `next_agents` only when another named Gitmoot agent should be invoked.
- Redact secrets from summaries, findings, raw command output, and examples.

---

# Source: skills/gitmoot/references/GOAL_TEMPLATE.md

# <Goal Title>

Implement the plan task by task. Each task must be developed, reviewed, opened
as its own pull request, merged, and verified before moving on, unless tasks are
explicitly safe to run in parallel.

Briefly describe the goal here. Include the intended user-facing outcome, the
main systems touched, and any explicit exclusions.

## Core Rules

- Work one task at a time in the listed order by default.
- If tasks are independent, have disjoint file ownership, and do not depend on
  each other's results, they may be done in parallel on separate branches.
- Do not start dependent work until the prerequisite task has passed checks,
  passed `codex exec review --uncommitted`, been pushed, opened as a PR, merged,
  and verified on the target branch.
- Do not commit generated data, reports, caches, build artifacts, secrets,
  credentials, session archives, cloned helper repos, local plugin build output,
  or large outputs unless the plan explicitly says they are intended tracked
  fixtures/artifacts.
- Preserve existing behavior unless the current task explicitly changes it.
- Keep changes clean, scoped, and organized. Avoid broad rewrites.
- Avoid code duplication. When repeated logic appears, extract small reusable
  helpers that match existing repo patterns.
- If implementation depends on external APIs, docs, CLIs, data formats,
  generated scripts, installers, service launchers, subprocess calls, env vars,
  config formats, or third-party libraries, verify the real contract with local
  commands and/or official sources before editing.

## Before Starting

1. Inspect current repo state with:
   - `git status --short`
   - current branch
   - current remote
2. If the target branch is unclear, the remote looks wrong, or the worktree has
   unrelated existing changes that make task commits ambiguous, stop and ask
   before continuing.
3. Confirm the target base branch from the current repo. If unspecified, use the
   current branch as the base.
4. Inspect relevant existing patterns before editing.
5. Verify PR tooling is available before the first PR:
   - `gh auth status`
   - repo remote resolves to the expected GitHub repository

## Per-Task Branch Workflow

1. Confirm the current task's scope.
2. Create a task branch from the latest target base branch.
3. Implement only that task.
4. Add or update focused tests/checks appropriate to the task.
5. Run focused tests for touched modules.
6. Run broader checks when the task touches shared behavior, CLI/API surfaces,
   data/model/evaluation logic, generated scripts, installers, service
   launchers, docs build systems, or user-facing workflows.
7. For wrapper, installer, CLI, subprocess, generated-script, env propagation,
   service-launcher, or deployment changes, include an operational smoke test or
   direct contract check. Syntax checks alone are not enough.
8. Identify every repository where files changed. In each changed repo, run:
   `codex exec review --uncommitted`
9. Preserve the exact raw review output per repo.

## Review-Fix Loop

1. If review finds issues, do not only patch the literal line.
2. Identify the underlying invariant/class of bug.
3. Audit nearby and sibling paths for the same issue.
4. Write a concise fix plan using:

   ```text
   Review found these issues: <<PASTE RAW REVIEW RESULTS BY REPO>>.
   For each issue, identify the underlying invariant/class of bug, audit sibling
   paths for the same issue, and plan the smallest safe fix. Verify external
   assumptions with local commands and/or official sources. Preserve repo
   patterns, avoid unnecessary refactors, and list tests/checks per repo.
   ```

5. Execute the fix plan.
6. Re-run focused tests/checks and `codex exec review --uncommitted` in every
   repo with uncommitted changes.
7. Repeat until the final raw review output contains no findings, or stop if
   blocked or if a finding is incorrect after verification.

## Commit Gate

1. Before committing, run `git diff --check` and inspect the final diff.
2. Commit only the current task's intended tracked changes.
3. Use the commit message specified by the plan. If the plan does not specify
   one, use a concise conventional message that describes only the current task.
4. Push the task branch.
5. Verify the task branch worktree is clean after push, except for intentionally
   ignored generated files.

## Pull Request Gate

1. Create one PR for the current task.
2. The PR title must describe only the current task.
3. The PR body must include:
   - WHAT: what was changed
   - WHY: why the task was needed
   - CHANGES: concrete implementation changes
   - RESULTS: tests/checks/review results
   - RISK: skipped checks, blockers, or residual risk
4. Include the exact raw final `codex exec review --uncommitted` output for each
   changed repo in the PR body.
5. If CI or required checks exist, wait for them and fix failures before merge.
6. Merge the PR using the repository's configured/preferred merge method. If no
   preference is discoverable, use squash merge for a clean task-level history.
7. After merge, update the local target base branch and verify the worktree is
   clean.
8. Record the PR number, PR URL, branch name, and merged commit hash.
9. Delete the task branch after merge only if the repository normally does so or
   the merge command supports safe branch deletion.

## Parallel Task Rules

- Parallelize only when tasks are independent, have disjoint file ownership, and
  can be reviewed and merged without order-dependent assumptions.
- Use a separate branch per task.
- Clearly assign each branch a task number and file ownership.
- Do not duplicate work across branches.
- If parallel branches conflict after one PR merges, rebase or update the
  remaining branch on the latest target base and re-run its checks/review.
- If a task becomes dependent on another task, stop treating it as parallel and
  merge the dependency first.

## Final Response After All Tasks

- List completed tasks.
- For each task, list branch, PR URL, merge status, and merged commit hash.
- List tests/checks run.
- Include exact final raw `codex exec review --uncommitted` output for the last
  task/repo.
- Mention skipped checks, blockers, or residual risk.
- Do not claim interactive `/review` is clean. Say:
  `codex exec review is clean; ready for manual /review.`

## Implementation Tasks

### Task 1: <Task Title>

Describe the task scope, intended behavior, acceptance criteria, tests, and
suggested commit message.

### Task 2: <Task Title>

Describe the task scope, intended behavior, acceptance criteria, tests, and
suggested commit message.
