Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (76 loc) · 4.07 KB

AGENTS.md

File metadata and controls

97 lines (76 loc) · 4.07 KB
Raw

gitmoot — Agent Guide

gitmoot is a local-first coordinator for AI coding agents working across GitHub repositories, pull requests, goals, reviews, and runtime workflows. It is a Go CLI plus a background daemon; workflow state lives in local SQLite.

This file is the shared context for AI coding agents. CLAUDE.md imports it via @AGENTS.md.

Build, Test, and Verify

Requires Go 1.26+ (see go.mod; CI resolves the version via go-version-file: go.mod). Run from the repo root and make these pass before committing — they mirror the CI gate in .github/workflows/ci.yml:

go build ./...
go vet ./...
go test ./...
go test -race ./internal/workflow/   # the workflow engine is race-tested in CI

The CLI entrypoint lives under cmd/.

Repository Layout

  • cmd/ — CLI entrypoint(s).
  • internal/ — all implementation. Key packages: cli (command surface), workflow (job/delegation engine + result contract), db (SQLite store), runtime (Codex/Claude/Kimi adapters), daemon (PR watcher), skillopt (template learning), agenttemplate, report (bug reports), presence, plugin*.
  • skills/gitmoot/ — the packaged Agent Skill: SKILL.md + references/ (CLI.md, WORKFLOWS.md, RESULT_CONTRACT.md, SAFETY.md, …) + agent-templates/.
  • docs/ — in-repo reference docs.
  • website/ — the Docusaurus site published to gitmoot.io (see below).
  • scripts/ — repo scripts.

Documentation — two independent trees

Docs live in two places that do not auto-sync, so a docs change usually needs to be applied to both:

  1. In-repo: docs/, skills/gitmoot/, README.md, SKILL.md, CONTRIBUTING.md.
  2. Website: website/docs/ (Docusaurus) — what publishes to https://gitmoot.io/docs.

The website is not auto-deployed. It is served by nginx from /var/www/gitmoot-docs/ and published manually (see website/docs/operations/deployment.md):

cd website && npm install && npm run build       # onBrokenLinks: throw — build fails on bad links/sidebar ids
rsync -a --delete build/ /var/www/gitmoot-docs/  # destructive; back up the target first

website/sidebars.ts is manual — add new pages there. website/static/llms.txt is a hand-curated index; website/static/llms-full.txt is generated by npm run build:llms (part of npm run build).

Conventions

  • Commits: Conventional Commits — feat:, fix:, docs:, chore:, ci:, perf:, with an optional scope, e.g. feat(workflow): …, docs(website): …. Reference issues with (#NNN).
  • Branches / PRs: do not push directly to main. Branch, open a PR, let CI (build / vet / test) pass, then squash-merge into main.
  • Scope: preserve existing behavior unless the change requires otherwise; keep work scoped to the task.

Agent Jobs & the Result Contract

gitmoot runs agents through registered runtimes — Codex, Claude Code, and Kimi Code (gitmoot agent start --runtime codex|claude|kimi). Jobs return a gitmoot_result JSON object, and agents can fan work out via a validated delegations[] DAG with a coordinator continuation job (the Orchestra pattern), bounded by depth, a per-root job budget, and loop detection. gitmoot orchestrate <agent> "..." [--repo R] is sugar for gitmoot agent run <agent> --background "...". The contracts live in:

  • skills/gitmoot/references/RESULT_CONTRACT.md — gitmoot_result + the delegations fields and termination bounds.
  • skills/gitmoot/references/SAFETY.md — checkout/runtime/branch locks and delegation termination bounds.
  • skills/gitmoot/SKILL.md — the entry point for the Gitmoot agent skill.

Gotchas

  • Gitignored (local-only, not in the repo): /GOALS/ (goal working docs), /repos/ (vendored helper repos), /dist/, /.gitmoot/evals/. Editing these never shows in git status.
  • The CI gate is Go-only — it does not build the website or run the live multi-runtime (codex/claude/kimi) E2E (those need a Node build / runtime auth).
  • For machine-local agent notes, use a gitignored CLAUDE.local.md rather than editing this shared file.