The agent guide

This repository is managed by garden, not plain git. garden is a cloud-backed monorepo platform: a virtual filesystem checkout (you never download the whole repo — files materialize on access), server-authoritative history, stacked commits instead of local branches, and a server-side merge queue. There is no local .git directory, so raw git commands do not work here. Drive everything through garden.

The good news: garden speaks git

For day-to-day work, lean on what you already know about git. garden wraps the underlying engine and translates git-style flags, so most git commands work verbatim with garden in front — think of it as alias garden=git for the common path:

garden status          garden add <f>         garden commit -m "..."
garden diff            garden log             garden show <rev>
garden blame           garden grep <pattern>  garden rebase
garden checkout <rev>  garden restore <f>     garden revert <rev>
garden cherry-pick     garden bisect          garden stash

When unsure, try the git verb you know with garden in front and check garden <cmd> --help.

What’s different (and what’s missing)

The model differs from git in a few ways that matter:

No local branches. You work as a stack of commits; bookmarks replace branches. garden branch maps to bookmarks, not git branches.
push creates pull requests. garden push creates or updates one PR per commit in your stack. There is no pr create — garden pr create just reminds you to push. A PR’s title/body come from its commit message; amend the commit and re-push to change them.
Merging is a server-side queue, not a local merge. No git merge. garden pr merge <pr> enqueues the PR; the queue rebases it onto current trunk, re-runs CI, and lands it automatically once it’s green and approved.
pull = fetch + restack. garden pull fetches trunk and restacks your work onto it. There’s no fetch/remote (one canonical server).
Don’t amend a commit that already landed as a merged PR (garden blocks it).
Worktrees for parallel work. garden worktree add <path> [<commit>] gives you another checkout of the same repo — like git worktree, same subcommands (add/list/remove/prune) and flags. Each has its own files and current commit, so you can run independent lines of work at once; commits are shared but don’t clutter each other’s view. -b <name> is accepted as a label (garden has no branches — you push to open a PR).
Missing / not yet wired — avoid for now: clean, tag, git revert -m. Intentionally N/A: remote, fetch, submodule, local merge, and git’s object-store plumbing (the server owns history).

Core loop

garden auth login              # once, to authenticate
garden clone <repo>            # mount the repo (instant — virtual FS, no full download)
# Or: garden init [path]        # import an existing folder into a new garden repo
# ...edit files...
garden commit -m "..."         # one commit, or stack several
garden push                    # creates/updates one PR per commit
garden review <pr>             # read the annotated diff with review threads inline
garden pr merge <pr>           # enqueue; the queue lands it when green + approved

Inspect with garden pr list, garden pr view <pr>, and garden stack (alias smartlog).

Hit a rough edge or have an idea? Send it straight to the team: garden feedback "..." (pass the message as an argument).

Why garden — capabilities to lean into

Virtual filesystem. Clone is instant and the working tree is virtual — files are fetched on access, so you never pull the whole repo. Be targeted: reading a few files is cheap, but scanning the entire tree (broad grep/find over everything) pulls a lot over the network — prefer narrow paths.
Instant checkouts. garden checkout <rev> and garden pr checkout <pr> jump to any commit or PR cheaply, fetched on demand — review or test anyone’s work without a heavy pull.
Built for a true monorepo. garden is designed to hold the whole project — frontend, backend, infra, tooling — at scale. Keep everything in one repo and make cross-cutting changes as a single stack rather than splitting work across repos.
Stacked PRs. Build dependent changes as a stack; each commit is its own PR and they land bottom-up through the queue.
A rich code-review suite (garden’s most differentiated surface): garden review <pr> shows an annotated diff with threads inline; per-file reviewed checkpoints (garden review mark-reviewed) mean a re-review only shows what changed since you last looked; draft comments you submit together; a declarative review document (garden review apply); and resolve/unresolve that gates the merge. See “Reviewing PRs” above for how the comment model differs from GitHub.
CI, automatic and manual. CI runs per revision and after landing; failures surface as inline review threads on the exact failing lines. Check status with garden pr checks <pr>. CI projects are declared by project.toml files in the tree (they scope what builds/tests and drive test selection).
Code ownership. OWNERS.toml files define per-path review ownership; the merge gate requires owner approval, green CI, and all review threads resolved.

Reviewing PRs — comments differ from GitHub

garden’s review surface diverges from GitHub in ways an agent must internalize before leaving comments:

Unresolved comments block merge. Open threads gate the merge queue alongside owner approval and green CI — there is no “merge and follow up.” Resolution rides the latest published item in the thread, so a reply can carry resolve: / unresolve: without restating the point.
Comments are drafts until published. garden review comment writes a draft only you can see; garden review submit publishes every pending draft and posts a verdict (approve/comment). Forgetting to submit leaves the whole review invisible. Pending drafts: garden review status.
Comments anchor to a specific commit, not to a diff position. Each one records the commit whose file/line it references; the diff viewer renders it on whichever side (base or head) matches the anchor (and nowhere if neither side matches). Comments survive rebases and new revisions — don’t re-post just because the diff changed.
Ranged, not single-line. The at: form is path:line[:col][-line[:col]] — e.g. api/foo.go:42-48 for an eight-line range. Comment on the whole construct, not a marker line.
Per-file reviewed checkpoints. garden review mark-reviewed <pr> [files...] records “reviewed up to this rev”; on re-review only changes since the checkpoint show for that file. The declarative document accepts reviewed: [paths] / unreviewed: [paths] ("*" expands to every file in the diff).
CI failures show up as inline threads on the failing line. A ci-bot reopens its thread (unresolved) when a test re-fails and resolves it when it passes — even if a human resolved it in between. They count toward the merge gate like any other thread.
Use garden review apply for whole reviews. It takes a YAML/JSON document (verdict + comments + per-file reviewed marks) applied atomically — the recommended path when an agent produces a full review. garden docs review has the full schema; --draft stages without publishing.
Each stacked PR has its own threads. Comments don’t propagate between a parent and child PR.

Responding to review on your own PR

The section above is the reviewer side. To clear review on a PR you authored:

Read the open threads with garden review <pr> --threads. Each thread is tagged with a short handle like c:1a2b3c4d.
After you amend + push a new revision, threads anchored to earlier revisions drop out of the default view. The header says how many and prints the exact command to bring them back — garden review <pr> --range <old>:<new> --threads (e.g. --range 1:2).
Reply and resolve in one step. Resolution rides the reply, so the reply carries it — no need to restate the point: garden review comment <pr> --reply-to c:1a2b3c4d --resolve -b "Fixed in rev 2.", or in a garden review apply document, reply_to: c:1a2b3c4d with resolve: true. The c:<short> handle from --threads is accepted directly (as is the full id from --json).
Amend, don’t re-push a new commit. Edit → garden commit --amend → garden push adds a new revision to the same PR; it does not open a second one. The PR becomes mergeable once every thread is resolved, CI is green, and an owner has approved — confirm with garden pr view <pr>.

Getting more help

garden --help and garden <command> --help are the authoritative reference.
Useful groups: garden pr --help, garden review --help, garden queue --help, garden repo --help.
Config & document formats: garden docs lists reference topics; run garden docs owners (OWNERS.toml), garden docs project (project.toml), or garden docs review (the garden review apply document) for the exact schemas the running version accepts.