agents.yaml
The file a project writes, the file uze derives from it, and what each one is allowed to say
Two files at the project root, both committed, with one rule between them:
| File | Written by | Holds |
|---|---|---|
agents.yaml | you | What the project declares: which marketplaces it draws from, which plugins it wants, and, under workspace:, how its agents work |
agents.lock | uze | What resolving those declarations produced: the commit each marketplace was read at, and a digest of the bytes that landed |
The lock carries no intent, so deleting it loses nothing: uze install
regenerates it. Deleting agents.yaml loses the project's decisions.
git clone && uze install reconstructs the environment from the pair alone.
agents.yaml
Two kinds of key, one per module. The package manager's sit at the root; the
workspace's live under one workspace: section, which a project that only
installs plugins never writes:
marketplaces:
ai:
git: https://github.com/you/plugins
ref: main
plugins:
- review
- changelog
workspace:
worktree: always
delivery: pushCreated by uze install or uze add <plugin>@<market>, explicit acts of
setting a project up, with the package manager's vocabulary written out and commented.
Nothing about the workspace is written, not even commented: the section appears
when you choose something in the workspace or write it yourself. Nothing that
merely reads a project creates the file.
Every key is optional; a project declaring only a workspace policy is as valid
as one declaring only plugins. Unknown keys are an error, not silence: a
typo in a file a person wrote should not be read as a decision, and neither is
a key written twice. Writing revision: or integrity: here is refused by
name: those belong to the lock. So is a version:, at the root or on a plugin:
the file has no schema version, and a plugin is pinned by its marketplace's
ref:. A plugin may be declared under one marketplace only.
This document is patched in place, so a comment you wrote beside an unrelated
entry survives uze <plugin>@<market>.
marketplaces
Every marketplace the project draws from, keyed by the name you refer to it by, with what it takes from each. Exactly one source per marketplace:
marketplaces:
ours:
git: https://github.com/acme/plugins
ref: main # optional: branch, tag or sha; also the pin that moves
subdirectory: market # optional
plugins: [review, changelog]
local:
path: ../marketplace
plugins: [bench-runner]Plugins are bare names: the source above says where they come from, and ref:
is what moves them.
A marketplace is a Git repository, whether you spell it as a URL or as a
directory on this machine. Not because Git is how the bytes travel (a
directory does that), but because a commit is the only thing that answers are
these the bytes I installed? and is there something newer? A path: is
therefore where this machine reads the repository; what the lock records
is its remote and a commit, which is what another machine can reproduce.
The lock records every Git source in one spelling: git@github.com:acme/plugins.git,
ssh://git@github.com/acme/plugins and https://github.com/acme/plugins.git all
become https://github.com/acme/plugins. That is a name, not a transport:
each machine reaches it anonymously when it is public, and with its own
credential helper or SSH key when it is private, so nothing in these files
says how to authenticate, and a collaborator with no key installs a public
marketplace as easily as you do. A marketplace you develop is read from your
checkout with uze market link, which touches neither file.
The official marketplace, uze, is built into the binary, so a project lists
what it takes from it with no source:
marketplaces:
uze:
plugins:
- workspaceA git: or path: on that name is refused: the binary is its only source. The
uze plugin itself is never listed, since every project has it already.
workspace
How uze workspace runs the agents it launches, and
where the project keeps the artifacts that describe it. One flat section.
Where a worktree lives, .worktrees/<id>, is fixed and deliberately not
declared here. Its branch starts as agent/<id> and takes the name the agent
gives its work, judged by branch.
The section is the workspace's. The package manager carries it without reading
it, so a mistake in it never fails uze install or uze status; the workspace
reports it.
| Key | Default | Meaning |
|---|---|---|
worktree | manual | When an agent launched here gets a worktree: always, at launch, or manual, only when you move it with To worktree. Until then it works in the primary checkout, on your branch |
delivery | none | Where finished work is put: merge (fast-forward the local target) or push (push the task's branch to the remote). Both rebase onto the target and run the gate first. Undeclared, there is no delivery |
target | the branch the primary checkout is on when the task is created | The branch finished work targets |
branch | conventional | The vocabulary an agent's own name for its work is judged against: a preset (conventional, gitflow, flat, agent) or your own list of types. flat takes a subject with no type; agent names no work and keeps the generated agent/<id> |
link | none | Ignored files a fresh worktree links from the primary checkout, like .env |
setup | none | Prepares a worktree, run in it after linking every time an agent takes it, once you approve it. Where a cache that records its own path is repaired after a checkout changes hands. A failure warns; it never blocks a launch |
gate | none | Run in the task's worktree on the rebased commits, once you approve it. A non-zero exit refuses delivery |
slots | peak concurrency | The most worktrees that may exist at once |
idle_days | 3 | Days a free worktree may sit unused, since an agent last left it, before it is removed, its branch kept. Until then it is reused, so a project keeps as many worktrees as it had agents at once |
actions | none | What the agent is asked at each state its work reaches; see below |
artifacts | none | Where the project keeps what describes it; see below |
Every key but branch, actions and artifacts is about a worktree, so none of them does
anything for an agent working in the primary checkout until it is moved into one. branch
still judges such an agent's name, which sets its label and never your branch.
setup and gate each take one command or a list run in order. Use the list
when a failure should say which step failed:
workspace:
worktree: always
delivery: push
target: main
branch: conventional
link: [.env, .env.local]
setup: pnpm install
gate:
- pnpm test
- pnpm lint
slots: 3
idle_days: 3
artifacts: docsA command is one line, and it runs the same on Linux, macOS and Windows. uze
runs it in a small shell of its own, so nothing depends on which shell the
machine has. That shell reads what a setup or gate line usually needs:
&&,||and;, pipes, and<,>and>>NAME=value command,$NAME,$(command), globs and~cat,cd,cp,echo,exit,export,head,mkdir,mv,pwd,rm,set,sleep,test,unsetandxargs, built in, socp .env.example .envworks on a Windows machine with nocp
workspace:
setup: test -f .env || cp .env.example .env
gate:
- pnpm test
- mkdir -p reports && pnpm lint > reports/lint.txtSome lines need more than that shell reads: if, for or while, functions,
${NAME}, [, or a flag its built-in commands do not have, like head -1.
Such a line still runs, in sh, on Linux and macOS, exactly as before. It does
not run on Windows, and uze status says which part kept it there. To run it
on Windows too, write it once for each shell. Windows runs the windows line
in Windows PowerShell:
workspace:
setup:
posix: for f in *.example; do cp "$f" "${f%.example}"; done
windows: Get-ChildItem *.example | % { Copy-Item $_ ($_.Name -replace '\.example$') }posix: alone also runs a line in sh when you want sh itself.
A step with no line for the machine it runs on is not run there. A setup
step is skipped with a warning naming it; a gate step refuses the delivery,
because work nothing checked never lands. uze status lists every such step.
Approving the commands
setup and gate are shell lines from the repository, and they run with your
permissions. So uze runs none of them until you have read the exact lines and
said yes, once per project on each machine. Until then a worktree is placed
without its setup, and nothing is delivered. The workspace asks with a
Review button when it opens the project, and uze workspace allow asks
from a terminal:
uze workspace allow # show this project's setup and gate lines, and approve them
uze workspace revoke # withdraw the approval; nothing runs until it is given againThe approval names those exact lines. Change one, add one or remove one, and
the workspace asks again before anything runs. An agent cannot approve its own
project's commands: uze workspace allow refuses inside an agent uze launched,
and needs a person at a terminal to answer. uze status says when a project's
commands are waiting for you.
A link entry must be relative, stay inside the repository, and be ignored
by it: a tracked file linked into a worktree would land in the agent's
commits as a symlink. All three are checked when the file is read, not
silently dropped. The agent writes through a link into your primary
checkout, so only what it reads belongs there.
The policy lives here rather than in machine state because it is the
project's decision, shared by everyone who clones it. Placement reads the
primary checkout's file: a worktree's own agents.yaml is its agent's work,
and applies once delivered.
actions
What the agent is asked when its work reaches a state: one line of text per
state, sent into the agent's pane as if you had typed it. The workspace opens no pull
request and fixes no check itself. It rebases, runs the gate and puts the
work where delivery says, and everything after that is the agent's, asked
in the project's own words.
workspace:
delivery: push
actions:
on_change: Commit your work with the git:commit skill, then end your turn.
on_publish: Open a pull request for this branch against main with the git:pr skill, then end your turn.
on_conflict: The rebase onto main is paused here. Resolve it preserving your change, run git rebase --continue and the checks, then end your turn.
on_fail: The project's checks failed after the rebase. Fix them on this branch, commit, and end your turn.| Key | The work is | Sent on its own when |
|---|---|---|
on_change | changed in the checkout, not committed | never |
on_publish | on the remote, with no request yet | a push delivery pushed it |
on_conflict | paused mid-rebase | a rebase uze ran stopped on conflicts |
on_fail | refused by the gate | the gate failed on a delivery |
Clicking the status in the workspace's tab strip sends that state's line too,
so on_change, which is never sent on its own, is one click away: with it
declared, an uncommitted status appears beside the change count. Nothing is
sent while the agent is working or while you have text typed in its input: the
click says why, and nothing is queued. Any other state is only shown.
on_conflict and on_fail have a line of uze's own when the project declares
none, since in both the agent's checkout is waiting on the agent: a rebase
paused, a branch the gate refused. Declaring them replaces those lines.
To ask for a skill, say so in the line, as you would in the prompt: Use the git:pr skill to open a pull request. An unknown key, or a value that is not a
line of text, is reported and left out, and the rest still works.
artifacts
Where the project keeps the artifacts that describe it: one directory, or a list of them, each read as deep as it goes.
workspace:
artifacts: docs
# or several:
# artifacts: [docs, design]It names places, never kinds. What a file is, it says by its own content, and each surface takes the files it recognizes and ignores the rest: the architect surface draws the Mermaid files it finds there, and the spec surface lists the decision records. A kind of artifact uze learns later needs no new key.
An entry that climbs out of the project (../) or starts at the machine's root
refuses the whole declaration, naming the entry, because this file is checked in
and would point somewhere else on every machine.
Nothing lists the files. Each one says what it is in its own first word, which is also the area it appears under, and names itself with Mermaid's own front matter, falling back to its file name:
---
title: System context
---
C4Context
Person(dev, "Developer")
System(uze, "uze")
Rel(dev, uze, "Installs, launches, reviews")| The diagram starts with | Area |
|---|---|
C4Context, C4Container, C4Component, … | C4 |
sequenceDiagram | Sequence |
flowchart, graph | Flowchart |
Levels, and the way down to the code
C4 is a model of levels (a system, the containers inside it, the components
inside one of those), and the files are joined into levels the same way they are
sorted into areas: by what they already say. An alias names one element in every
view, and a view's outermost boundary says which box it is the inside of: a
container view's System_Boundary is the inside of the System with its alias,
a component view's Container_Boundary the inside of the Container with its
alias:
system-context.mmd System(uze, "uze", …)
containers.mmd System_Boundary(uze, "uze") { … Container(cli, "uze CLI", …) … }
core-components.mmd Container_Boundary(cli, "uze CLI") { … }Several component views of one container sit side by side, each one level below
it. Where an alias cannot say it, an element's $link to another of the files
names its inside instead.
A box like that is marked, and entering it opens the file that draws its inside;
the way in is kept as a trail, every step of which goes back. The last level is
the code itself. Mermaid's own $link on an element names where it lives,
relative to the project, and entering that box opens it in the code surface:
Component(store, "store", "Rust module", "Owns installed bytes", $link="crates/core/src/store.rs")A flowchart says the same with click store href "crates/core/src/store.rs".
Within an area the files are listed by name, except C4, which is listed the way it is read: the context, then containers, then components, then the dynamic and deployment views.
A .mmd or .mermaid file of any other kind is still listed, under Other,
with the reason it was not drawn: a file that silently fails to appear looks
like a lost file.
Everything here is a file somebody wrote. What the project is (where its
lines are and which of them are hot) is measured rather than written, and is
the code surface's map: press m beside the file tree, or its Map chip.
agents.lock
Generated, never edited, and deleted outright when nothing is left to
reproduce. It is spelled the way agents.yaml spells things, so a reader
moving between the two files does not learn the same vocabulary twice:
version: 1
marketplaces:
ai:
git: https://github.com/you/ai
ref: main
revision: 02d2c9831eb619821c574622a78bbc5f6189485a
plugins:
git:
marketplace: ai
integrity: sha256:f429f157f7cec03d702f1749416ea59174b9af79c94fc281756467b0cb6b81cdResolution adds two things to a declaration (and, for the official marketplace, the uze version, below):
revision: the immutable commit the marketplace was read at. Non-optional besidegit, so "a marketplace with no pin" cannot be written down. Reproduction reads this, never the declaredref:: a lock that re-resolvedmainwould install whatever had been pushed since.integrity: SHA-256 over the bytes the Store ingested, verified on install before ingest and before any harness sees anything. A mismatch names both digests and installs nothing. Apath:marketplace records none: a digest of a directory somebody is editing would be wrong by the next command, and a pin that is routinely wrong teaches people to ignore pins.
The official marketplace has no repository and no commit, so it has no entry
under marketplaces:. The lock records the uze version that resolved its
plugins instead, at the top (uze: 1.0.0), and each of them with its
integrity as above. Those plugins follow the binary that runs: when the
machine's bytes or the lock's are another uze build's, uze install replaces
them with this one's, rewrites the lock and reports them as updated, never as a
mismatch.
Everything else in the file was already in the manifest, and is repeated only
so the lock stands alone on a machine that has never read one. version stays
at 1 while uze is pre-release; the number exists to tell apart shapes a
released uze wrote.
Staleness is decidable offline
Comparing the two files answers whether the lock still stands: no network, no
re-resolution, so uze status works in a tunnel. A declaration is stale when
the lock never resolved it, resolved it from a different marketplace, or the
marketplace it comes from is declared differently now. A lock entry the manifest
no longer declares is not staleness, it is a removal.
A floor, not a ceiling
A machine runs one revision of each plugin, shared by every project and every agent on it, and keeps it at the newest. The lock does not say what runs; it says what a machine starts from:
- A machine without the plugin installs exactly the locked revision. This is the fresh clone, the teammate, the CI runner.
- A machine behind the lock is raised to it by
uze install. A teammate moved the pin and you pulled it. - A machine past the lock keeps what it has.
uze installnever downgrades and never moves a pin, anduze statusshows the plugin as installed at a revision other than the lock's. That is the ordinary state after an update, not a fault;uze updatein the project records it.
What these files are not
They are project scope. Neither records what is installed on your machine:
that lives in the Store under ~/.uze, and uze add -m never writes
here. The two are independent by design; see
Machine and project.