Projects and specs
Start work or a spec from the work composer, review the spec on its own page, follow the project on one page with its agent chat, and finish with pull requests.
A project is one piece of work handed to an agent. It runs in a
container of its own, in its own branch, and ends with pull requests. You
start one from the work composer: on Home, or
with Start work (⌘J) from any page. Projects belong to the workspace and
are listed under Work in the sidebar; each is one page with its agent's
chat at the right.
Your projects
Projects in the sidebar lists every open project of the workspace by Needs you,
Working and Ready, and the filter menu on its header narrows them. The command palette and
/projects show them as a page too.
Several projects at once
While several projects are selected, a bar under them says how many and offers what can be done to them together. It shows an action only when it applies to at least one of them, and says in brackets how many it takes when that is not all of them:
- Queue for merge: the Done ones; see merge queue.
- Push: the Done ones with commits not on GitHub yet.
- Open PRs: the Done ones that are pushed and have no pull request yet.
- Start (drafts) or Resume (stopped work).
- Stop: the ones whose agent is working.
- Close: all of them, after a confirm. A project with changes not on GitHub yet is left open; the message after it says which.
Each runs on the projects one after the other; the message after it says how many went through and why one did not.
Right-click one of the selected projects, or press its ⋯, and the same actions open there, under how many are selected, with Deselect (that project only) and Clear selection last. A project outside the selection keeps its own menu. The other sections of the sidebar (docs, canvases, prototypes, goals, pinned) do the same with their own actions.
On a phone, the sidebar is a drawer, behind ☰.
Create a spec
With the work composer. On Home, or with Start work (⌘J) on
any page: add what the task is about as chips, write what the project should
do, open the mode menu and tick Write a spec first under Project, and press Start with a
spec (⌘/Ctrl+Enter). See the work composer.
The project is made at once, without a dialog, and you land on its spec
page while the agent writes the plan (from a doc's or a
prototype's page it opens as a tab of the chat column instead). The context
is what the chips show: what you added or dragged in, what is selected on
the page, and your Pinned items (one chip, N Pinned, that lists them;
remove one there to leave it out of this message, it stays pinned).
Repositories among them are checked out, as a worktree unless the workspace
has them read-only; a pinned or dropped branch or pull request is where that
repository's project starts. A doc among the chips goes with its text, and
the project keeps it: the doc shows it as linked
work. A project is not made on a canvas: everything in
the context is linked to it. Write spec in the command palette and
/spec in a chat open the composer with that choice made.
From a spec block. Write the spec on a canvas first
(specs on a canvas), then press Write
spec on the block or in its panel. A short confirmation lists the blocks
linked to the spec, the repositories (the ones those
blocks point at, as worktrees unless they are read-only) and the agent, all
filled in. Confirm, and the project is made: its spec.md starts as the
block's text, with the pictures it shows, and the linked blocks are its
context. The project's agent completes the spec (the plan, the
criteria that are missing) and waits for your review. Start work in the
panel does the same and goes straight to work.
From then on the block and the project show one document. The block on the canvas shows the project's status word and Open project; the text in its panel is the project's spec, so an edit in either place shows in the other. Deleting the project gives the block its draft back, with what the spec said last. A closed project leaves its text on the block, read-only.
The Write spec dialog
The work composer needs no dialog. The Write spec dialog is still what you get from a spec block (above), from a Write spec card the agent offers in a chat, and from New project from this on a pull request or branch of a repository block. It has:
- an instructions field for what the project should do: the work composer,
the same box as everywhere else, where you can attach files, type
@to attach a workspace file, use/attach,/modeland/spec, dictate with the microphone button, drag in rows of the sidebar or blocks of the canvas as context chips, and pick the agent and model with its model pill. Write a spec first, the checkbox under Project in the mode menu, chooses between a spec first and starting right away, and its button (Start with a spec or Start work, or⌘/Ctrl+Enter) creates the project; - the blocks it starts from, as chips you can remove or change with Edit context. With nothing selected, the project starts from its instructions alone. When the instructions name a file of the workspace canvas that is not there, a note above the buttons says the project will not get it;
- a Repositories list: for each repository, choose new worktree (the agent may change it) or read-only (it may only read it). Repositories that a selected repo or code block points at come first, marked from context: they are always checked out, as a worktree unless you switch them to read-only. Under each worktree, its branch button chooses where the project works: New branch from the branch the workspace reads (the default), New branch from… another branch (its pull request then goes into that branch), or Work on existing branch…, for a branch someone pushed: its commits are in the worktree and the project pushes to it, with its pull request going to the workspace's branch, or Read-only reference: the project only reads it, at the workspace's branch or one you pick, with no branch and no pull request of its own. The lists show each branch's last commit and are read from GitHub when you open them;
- from a spec block, where there is no instructions field, the agent and model at the foot, and Write spec or Start work.
You need a connected agent; see agents.
The instructions may stay empty when the project has context: at least one block or repository. Then tick No instructions: the agent will work from the context only; Create project stays off until you do. The agent works out the task from the context, and its first reply names the blocks and repositories it used.
Create without starting sets the project up, with its worktrees and an empty spec, but runs no agent. With no instructions it reads Create empty project: handy to look at a branch, review it or work on it yourself. It starts when you send the first message in its chat or write in spec.md (a few seconds after you stop typing).
A new project is first named after the instructions. A few seconds later an
agent's quick model suggests a short title and a branch name, and the project
takes them before the agent's first commit: the title, and a branch
ctr/<type>-<slug> such as ctr/fix-login-redirect, made unique in the
repository. If no suggestion comes, the first name stays. A title you typed
yourself is kept.
From what is picked or dragged in
What is ticked or selected on a page (docs, sections, prototypes) shows as chips in the work composer and goes with the project: Work with Create a spec first writes the spec from it. You can also drag a doc, file, prototype, project, investigation or repository (a sidebar row, or a branch or pull request from the repository's page) onto the composer, or choose From the workspace or A repository in its attach menu. The spec lives in that project, not on the canvas; its tab in the chat column follows the project. Write spec on a prototype's page makes a project that writes its spec from that prototype.
Start without a spec
When the task is clear and you just want it done, use the work composer: write what should happen, choose Project, leave Write a spec first unticked and press Start work. The project is made at once and you land on its page (from a doc or prototype, its tab in the chat column). It shows Setting up meanwhile, and the agent starts working in the worktrees as soon as it is ready, from your words and the chips in the composer's context. There is no spec to review; the Spec card shows the request instead, and you can still write a spec there to steer it. Questions, Stop and Done work as for any project.
A goal is a list of projects of this kind: each has its plan as its spec, and its page is the one described here.
What a project is
Each project gets its own directory, its own container on the runner and,
for every repository you chose as a worktree, a worktree on a branch of its
own (ctr/<slug>, or the suggested ctr/<type>-<slug>; a project started from
a pull request works on that pull request's branch); read-only ones are checked out without a branch. A repository
the context points at is always checked out, read-only if nobody chose it.
The Worktrees section of the project's page says how that project has
each repository. The blocks you selected are copied into the project's
context and stay on the workspace canvas as well.
The spec page
A project made with a spec first opens on its spec until you start the work. The page is the spec, with the project's chat at the right.
- The header reads Work / <name>, then Writing spec while the agent writes and Spec to review once it waits for you. At the right it says "Planned by the agent 2 minutes ago. Saved." More holds Files, Git, Apps and Ports, and the project's menu. Files, Git and Apps open as views of their own, whose header links Home (back to the spec), Files, Git, Apps and Ports in one row. The terminal is in the bottom bar.
- Under it is your request as a small card: who asked and when, the text, and "4 in context".
- Then the spec itself, every part edited in place. Everyone with edit access can change it together, live.
- The chat at the right is the project's agent. Tell it what to change ("split step 2", "leave billing out") and it rewrites the parts of the spec that are affected; the page shows the change without a reload. In a draft the agent does not touch code.
- Beside Chat the column has a second tab, Context 4: the blocks the spec is written from, attached files and the repositories. Add blocks, Attach and Add a repository are there; see the project's context.
- The foot says "Nothing is built until you start. The agent then works in its own branch of <repository>." with Discard (deletes the project) and the one filled button, Start work.
From a window 1150px wide the chat is a fixed column; on a narrower one the chat button opens it as a sheet. See chat.
The project page
Once work started, a project is one page with its agent's chat at the right. A header at the top, then six tabs.
The header has the project's title, its status, Open the spec and the
project's menu (⋯). Under the title it says how the project started
("Started by Alex from 2 blocks in the canvas Dev, 3 hours ago."), with
Open it when it was made from a spec block or blocks on a canvas. A line of four steps shows
where it is: Spec, Work, Review, Merged. Review means the
work is done and something is left to commit, push, open or merge; Merged
means every pull request is merged.
Under the steps, one row says what the agent is doing and holds what moves the project on, on every tab: Stop while it works, Answer the agent when it asked, Back to draft, Mark done and Resume when it stopped, and once the work is done Push branch, Open PRs and the merge (see done). There is never more than one filled button on the page. The terminal opens from the bottom bar (see terminals).
The tabs stay at the top of the page while the header scrolls away. Each has
its own address (?tab=plan), so Back and Forward move between them, and
the keys 1 to 4 go to the first four. After each name the tab says what
it holds:
- Overview, the first tab once there is anything to sum up: the report
once the agent has written it (see the report), then
Screenshots once there are pictures (see screenshots),
then short cards, in two columns when there is room:
- Plan: how many acceptance criteria are met, with a bar, and the plan's steps. Open Plan opens the Plan tab.
- Git changes: each worktree's repository,
branch → base, lines added and removed, the files and commits, and its pull request. Open Changes opens the Changes tab. - Context and Crew: what the project was given and who works on it, each with a link to its tab.
- Plan (
9/24 · 7 open): the phases of the plan beside the acceptance criteria, under one filter (Everything, Open, Needs you, Done) and one search for both. A step that waits for you has Answer. The criteria narrow further by priority (Must, Should, Nice to have), by tag (a chip, or#tagin the search), and are grouped by Area, Priority or None (open, met, skipped); an area folds with its chevron. Open with Must shows what holds up the merge, with each tag's open count. Clear filters undoes them all. An open criterion can be skipped from its⋯menu, see skip a criterion. - Changes (
+120 −34, the lines added and removed in the worktrees, as on Overview), only git (the report and pictures are on Overview): where the branches are on the way to merged, the pull requests of the worktrees, then Git (each worktree's commits, changed files and diff, with commit, push and the other git actions) or Review digest (see the review digest; it is off until you turn it on). - Files: the project's files, or a worktree's (Showing), in the file workbench.
- Apps (a badge: Live when every app runs, Partial when some do, Offline when none does or the runner is away, Failed when one is in error; its tooltip says which): the project's apps (see Apps), and under them Listening in the box, every port something in the box listens on (see Ports).
- Context (
9, how many things it holds): what the agent works from, linked docs in a Docs group (see the project's context), what the project was linked to when started (Linked), its Repositories (with Add a repository and Make writable), and Made by this project: the monitors and prototypes its agent made.
The chat at the right is headed Agent, with the project's status beside it. Write there to ask about the work or to change its course; Steer sends a message into the running turn and Stop ends it (see chat). A project has no canvas of its own.
On a phone the header is smaller, the tabs scroll sideways, and the chat is the field above the next-step bar. The Plan tab shows the steps or the criteria (Steps | Criteria), the Changes tab picks a commit and a changed file above the diff, and the Files tab opens its tree from Files.
Addresses from before still work: ?tab=git opens Changes, ?tab=ports
Apps, ?tab=progress Plan, ?tab=spec the spec, and ?tab=attached,
?tab=docs, #context, #worktrees and #made the Context tab (it was
called Attached). There is
no Docs tab: the docs linked to a project, the one it was started from first,
are the Docs group of Context.
What opens in place
Clicking a reference in a project's chat or work opens it over that part of the window. The other part, and the view underneath with its scroll and what you typed, stay as they were, and no tab opens.
- What opens this way: a doc, a file at its line, a picture or upload, the report, a sheet, a prototype, another project's summary, a monitor, a commit's diff and a goal. Anything else goes to its own page.
- It nests: a link in what you opened opens on top of it, and the bar at the top shows the way back.
- Back: the back arrow or
Escgoes back one step; a name in the bar goes back to that one; × closes them all. A file with unsaved changes asks first. - Expand opens the thing as its own page, in a tab of the strip. A doc opened in place has no chat column, Add repo or Add reference: Expand has them.
Ctrlor⌘-click, or a middle click, opens a new browser tab. Going to another project closes what was open.
Areas, priorities and tags
Acceptance criteria can say what they are about and how much they matter, in spec.md itself:
## Acceptance criteria
### Behaviour
- [x] Shift-click selects a range of tiles (must) #keyboard
- [ ] Delete offers undo for 10 s (should)
### Small screens
- [ ] The layout holds at 320 px wide (nice) #phone
- A
###heading under Acceptance criteria is the area of the criteria under it. (must),(should)or(nice)is the priority. Only open must-haves hold up the merge. A criterion without one is a should; a spec without any priority reads every criterion as a must-have, as before.- Each
#wordis a tag (#e2e,#a11y,#phone…), to filter by on the Plan tab.#123and link anchors are not tags.
The marks are left out of the text the page shows, and changing them keeps a criterion's tick and its skip. The agent writes criteria this way when it drafts a spec, and works on the open must-haves first.
Skip a criterion
On the Plan tab, ⋯ beside an open acceptance criterion offers Skip
criterion…. It asks first, with room for why (optional). A skipped
criterion is greyed with who skipped it and why, and Restore opens it
again. It counts as skipped, not met ("11 of 18 met · 1 skipped"): the agent
no longer works on it ("Continue working" leaves it out), and it no longer
holds up pushing or merging. Pull requests list skipped criteria under
Skipped criteria, with the reasons, and a draft opened for open criteria
is marked ready once every criterion is ticked or skipped. Ticking a skipped
criterion makes it met.
Rename a project
Choose Rename in the project's menu (the ⋯ on its row on the
Projects page, or More beside the project's title). Enter
saves, Escape leaves the title as it was. Everyone in the workspace sees the
new title at once.
Only the title changes. The folder, the address of the page and the branch keep the name the project was given when it was created, so open pull requests still belong to it.
The spec draft
First the agent reads the context and the repositories and writes
spec.md. While it does, the spec page reads Writing
spec and shows what the agent is doing right now (the file it reads, what
it searches, the steps it just finished), and the title changes from
"Reading the repositories…" to "Writing spec.md…" once it starts writing.
Home lists the project under In progress meanwhile. Then the project is
a Draft and the page reads Spec to review: everyone with edit access
can change the spec together in real time, and you can ask the project
agent in the chat beside it to refine it. In a draft the agent does not
touch code.
The foot of the page offers Discard (deletes the project) and Start work.
Pictures in the spec
When the change is something people see, the draft gets a Visuals
section: a screenshot of each page as it is today (the agent takes it on the
project's app and saves it under .yard/screenshots/), and how it could look.
For that the agent uses a prototype linked to the project, or makes a small
one in the project (one round, at most three screens). It does not make one
when a prototype adds nothing, for example for a renamed button or an email's
text; Visuals then says why in one line. Work nobody sees (an API, a
migration) gets no Visuals section.
A prototype in the spec shows as its kept screens. Press a screen to open it on the project's Screens tab, where you comment and refine as on any prototype. A picture and a prototype on lines of their own, one after the other, sit side by side; on a phone they stack. When the work starts, the agent builds to the screens and puts an after-shot beside each before-shot in its report.
The project's context
The Context card of the project page (the Context N tab of the chat on the spec page) lists everything the agent works from, one row each:
- the blocks linked from the workspace, with their kind (Note, Link, Code), the canvas each is on ("In the canvas Dev") and who added it. Click a row to open the block (a note in its editor); its × unlinks it from the project. The block stays where it is;
- the docs and files it was given with what they depend on (a doc's file in
docs/, an upload a prototype's comment attaches), each with its paths in the project and what pulled it in ("from Login"); - the files attached to the project, each with who attached it and when ("Attached by Alex, 1 hour ago"). Click a row to open the file; its × takes it off the project;
- the repositories, each with its base branch and whether it is a worktree or read-only.
A block that was made in the project (by its agent, or from its Files view) reads "Made in this project" and has Take into workspace: after you confirm, the block is put on the workspace's canvas, with what is inside it when it is a group, and its files move into the workspace. Blocks linked from the workspace do not have it; they are there already.
Whatever reaches a project, it gets the same: the files of what it was given
and of everything that depends on, copied into its directory at the same
paths. A doc brings its file and every block, doc, prototype, file and
repository it references, all the way down; a prototype brings its manifest,
its round's pages and pictures and its comments, with what the comments
attach. This is the same when you make the project, drop something on its row
in the sidebar, or link it later. A repository the context reads is checked
out (read-only when it is linked later). The project keeps the list in
.yard/context.json; its agent can add more with yard context add <path>
(a doc's file, a note, a prototype's page) and list it with yard context.
Repositories are also listed under Worktrees, with their git state, and
the files uploaded to a project are in its Files view, under
uploads/.
Blocks in a project's context are copies. Editing one marks it Edited here, and the Context card says "N blocks edited here. The workspace still has the text from before." with Send back to write the changes back, or Discard to drop them.
To add more context while a project runs:
- Add blocks opens the same picker as the work composer's + (the context picker): the library's items as a list, and each canvas as it opens on its own page, small and read-only, to click blocks or drag a box around several. Blocks already in the project are faded and marked In project. Add N blocks links them.
- Attach uploads files from your computer into the project (at most 50 per project). They are not put on a canvas.
- Link to project on a workspace block does the same from the canvas.
- In the project's chat, the paperclip's Blocks and A repository link a block or a repository from the composer. It shows as a chip there, and your next message tells the agent it was newly added.
The agent reads what you add at its next step: a turn that is already running is not interrupted for it, and its next turn is told. Linked blocks carry an In N projects badge. Pressing it lists the projects with their status; choose one to open it. Editors also find Unlink from … there.
Once every project that links a block is done (closed, or all its pull requests merged or closed), the badge turns green and reads Done in "<project>" (or Done in N projects). Its menu links each pull request on GitHub and offers Archive note, which puts the block away. See archived blocks.
Work
Start work hands the spec to the agent. While it works:
- the agent keeps its steps in a progress file,
.yard/progress.mdin the project: each step is pending, in progress, done or blocked, with notes for whoever goes on. Bigger work is split into phases, and each phase is committed on its own. The file is kept across turns, so Stop and Start (or Retry, or a follow-up in the chat) continue where the work stopped, and another agent can pick it up; - Plan and progress on the Progress card opens the spec at its plan: "5 of 12 steps done, 3 in progress." and the same bar as on the card, then those steps grouped by phase, with each phase's count ("3/5 done", "0/4 done, 2 in progress") and the commit that finished it (without a progress file, the agent's own task list), then the acceptance criteria, the last check and the time. No phase is singled out as the current one: the phases with work under way are open;
- the project's row, its Progress card, the plan under its spec and the line beside Agent working all count the same steps, so they always show the same numbers;
- the project moves to Review when a turn of the agent ends well with its
task list finished, or with its progress file at
state: doneand every step done; - when the work is done the agent writes the report;
- the Criteria card, beside Progress, counts the acceptance criteria
ticked in
spec.mdwith a bar, then lists them: met ones with the commits they were checked on, open ones with the agent's reason, the open ones first when there are more than six. The agent ticks a criterion only once it is met and verified; one it cannot meet or check stays unticked with anOpen:note saying why, and the spec shows that reason beside its checkbox. A criterion that fails only because of the base branch shows Blocked by base branch instead, and is ticked by Yard once the base is fixed (test baselines); - the project's row on the Projects page shows how far it is with the same
bar: green for the steps done across all phases, blue for the ones in
progress, the rest left, and under the status the numbers
(
5/12 steps done, 3 in progress), then the steps being worked on; without a progress file, the agent's task list (4/6 tasks done). Once the project is done it counts the criteria (9/10 criteria done). A blocked step or an open question turns the bar and caption amber. The row also says what the agent is doing: Working while the agent runs, Stopped if it stopped before finishing, and Failed in red if it stopped with an error (for example when the runner went offline). Hover the label to read the reason. A project that could not be set up reads Setup failed. The row names the step, not the commands the agent runs: those are in the chat and in the row under the steps on the project's page. Without a progress file or task list it says what the agent is doing now, without thecd <folder> &&in front of a command.
When every criterion is ticked and the work is committed, the agent marks the
project done itself with yard spec status done, from a Draft too (a project
worked on through chat only). In a spec that ranks its criteria, every
must-have being met is enough. The stage changes when its turn ends without an
error, a stop or a question, the chat says "The agent marked the project
done", and no worktree is removed. With criteria still open it cannot: it
ticks them, or leaves them open with a reason for a person to accept as is.
Commits are made as the person who pressed Start. Stop halts the agent and returns the project to draft (to done when only work it left running in the box was stopped and its progress file says every step is done). If the agent stops before finishing, choose Back to draft, Mark done or Resume.
An agent that ends its turn with must-haves open, no reason given for them, and a progress file that says neither blocked nor done is asked to carry on, up to twice in a row without ticking a criterion. After that the project reads Stopped, and the chat and a notification say it stopped early.
What a project reads follows its agent, not only its stage. If you send the agent a message in a draft (after a Stop, for example), the project reads Working for as long as that turn runs, or Working in background while work it left running in the box goes on (a test run among it says how far it is: see test progress). It is listed under Running, not under Drafts, and the next-step bar offers Stop. When the turn ends it reads Draft again.
The report
When the work is done the agent writes a report, .yard/report.md in the
project. It is for whoever reviews the work, so they can see what changed
without reading the diff or the chat. Export on the Report card saves it
as .md or as a PDF (see Files). It holds:
- a summary: what changed for the people who use it, and why;
- what changed in each repository, by area, with the files that matter;
- screenshots, when the change is something to look at: the agent starts
it, captures the result into
.yard/screenshots/and embeds the pictures (a before and an after for a page that existed); - the checks it ran and how they ended, and what it could not check;
- what the reviewer should look at: a decision it took, a risk, a migration, something left open.
- the follow-ups: more work an agent can take on next, which it left out of this project on purpose (an extension, a case it did not handle, a refactor, tests it could write), one item each, written as a task for an agent. Checks it could not run (by hand, on a real device) are listed under the checks, and what a person has to decide or do (a review, a deploy, a secret to set) under what the reviewer should look at: never as follow-ups.
The Report card on the project's page shows it as it reads, above the other cards, with when it was written. A long report is folded to its start; Show all of the report opens it. A picture opens in a viewer that steps through all of the report's pictures, and a file the report names opens in Files.
The follow-ups are listed under the report, each with a checkbox and two buttons. New sub-project makes it a sub-project of this project at once, without asking the agent: its instructions are the item as the agent wrote it, and it is not started. Continue here asks the agent to do it on this project's branch, and takes the item out of the report's follow-ups. Pick several (or Select all) and the bar under the list makes them all sub-projects in one go (Create N sub-projects), or sends them to the agent as one message (Continue all N here). A follow-up made into a sub-project links to it (Sub-project: …), also after a reload. When you close the project, the follow-ups still listed become entries of the workspace's Feedback, each linking back to the project, and the closed project's report links each one to its entry (In Feedback). A project closed before that has Add to Feedback instead, and its New project opens the work composer with the item. A report written before follow-ups had their own section shows the items of For the reviewer that call themselves a follow-up.
A follow-up in the chat that changes code makes the agent bring the report up to date, and the card follows at once for everyone.
The report is kept with the project, up to about 40,000 characters, and stays on its page after the project is finished and its files are gone.
Sub-projects
A project can have sub-projects: follow-up work that belongs to it. A sub-project is a project of its own, with its own box, branch, spec, chat and pull request, and it starts only when someone opens it. It is not a crew helper, which works inside one turn of a project.
- Where they come from. The report's follow-ups (above), New
sub-project on the parent's Overview, a project's agent running
yard project create(a sub-project of its own project unless it says--top-level), or Move under… in a project's menu. Many at once, from the report or withyard project create --batch, start no agent. - Their branch. Each repository the parent works on starts from the parent's branch, so the sub-project builds on its work even before it is merged: the parent's branch is pushed first, and uncommitted changes in the parent are refused. Its pull request goes into the parent's branch. When the parent's branch moves, its sub-projects are rebased on it (while their agents are idle); when it merges, they move onto the main branch with their pull requests. A parent whose branch is already merged gives a new sub-project the main branch, as any project.
- Where they show. In the sidebar's Active list a parent shows its sub-projects folded under it, with how many; its chevron unfolds them, and the project on screen is always shown. A parent is listed by whatever under it is most urgent: a sub-project that asks something puts it under Needs you. On the Projects page sub-projects sit indented under their parent in every grouping (one whose parent is in another group says the parent's name first), and Group: parent makes each parent a group of its own. Pick a parent and the bar offers Select N sub-projects; starting more than five projects at once asks first.
- On the parent's page. The Overview's Sub-projects card lists them with their state and branch, to pick and act on together. A sub-project's page shows its parents over its title.
- Moving and closing. Move under… puts a project under another (at most three levels deep, never under one of its own sub-projects); Move to top level takes it out. Closing a parent with open sub-projects asks whether to close them too or keep them, a level up; deleting a parent moves its sub-projects up a level.
- Talking to each other. A sub-project's agent is told its parent and its
siblings, and reaches them with
yard project familyandyard project message --siblings(or--parent,--children), as the CLI reference describes.
Screenshots
The pictures a project's agent takes go to .yard/screenshots/ in the
project, and so do those of Take a screenshot… in the project's menu.
The Screenshots card on the Overview shows them as thumbnails, newest
first, followed by the pictures in the project's uploads/ (where they went
before). A picture opens in a viewer that steps through all of them, with a
way to its file in Files; Files lists .yard/screenshots/ too. The card is
hidden while there are none. A picture the agent's yard-shot saves outside
the project (in /tmp, say) is copied to .yard/screenshots/ as well, so it
shows here all the same.
The agent's other work files are in the project too, and Files lists them:
the sources it makes pictures from in .yard/sources/, and its throwaway
files (and Claude Code's scratchpad) in .yard/scratch/, which is never kept
in the project's history (hidden files).
When a project's first report arrives, a large report block appears
beside the project where it was made from (its spec block on a canvas, or the
doc that places it) and on the project's canvas; later reports
update the same block. Pictures in it are read from the project's directory
(uploads/x.png).
Without a report (the agent has not finished, or the project is from before
reports) the card is not shown. GET /v1/containers/{id}/report returns the
text as Markdown.
When the agent needs input
When the agent cannot go on without a decision, it asks in the chat. The project's page says Needs your input, the project moves to Needs you on Home and on the Projects page, the sidebar counts it beside Projects, and the person who started the work is notified. Answer the questions in the chat and the agent carries on. The field under the questions takes anything else the agent should know, a correction or a constraint, and goes with your answers in the same message.
To hear about it by email too, turn on Agent needs my input (and Agent finished or failed, for a finished spec or an error) under Account settings, Email. Both are off until you do.
Done: push, pull requests, merge
When the work is done, the Git card of the project's page always names the next step, as its filled button:
- Push branch sends the branches to GitHub.
- Open PRs opens a pull request per repository.
- Merge PRs and finish merges them once they are approved, then finishes the project: it moves to Done on the Projects page. To merge and keep the project open, choose Merge PRs only from the menu beside it.
- Close project finishes it without merging.
Until then, a project whose agent is done reads where its branches stand, in the sidebar, on the Projects page and in the Projects tab of the workspace settings, rather than a plain Done: Ready to push (work not committed or not on GitHub yet), Ready for PR, PR conflicts, PR open (GitHub is still checking it), Ready to merge, and Merged once every pull request is in. A project that changed nothing reads Done. A project whose pull requests are all merged reads Merged even when some of its criteria are still open. Yard reads this from the pull requests' state on GitHub.
Or let Yard do steps 1 to 3 for you: Queue for merge, in the menu beside the main button, puts the project in the workspace's merge queue.
These act with the GitHub account of the person who presses them (under Account settings, GitHub). A button that cannot be used yet says why. With no repository or nothing committed, the bar offers Take files into the workspace… instead.
Anything in the way comes first, whatever the state of the pull requests:
- Finish or abort… when a merge was left half done in a worktree.
- Review changes when a worktree has uncommitted files. The bar names the repository and the number of files and opens its Git tab. This comes before Merge PRs even when a pull request is open: files that are not committed are not part of it.
- Push branch when there are commits GitHub does not have yet.
- Resolve conflicts when a pull request conflicts with its base. A card above the bar lists the files, and Resolve with the agent has the agent merge the base in, settle each file and commit. You push; GitHub checks the pull request again and Merge PRs becomes available.
- Checking merge status… while GitHub has not yet said whether a pull request can be merged. It checks again by itself.
Merge PRs merges all of a project's pull requests or none: if one conflicts, nothing is merged and the message names it.
Done with criteria still open
When the agent finished its work but left acceptance criteria unticked, the project never reads plain Done: it reads K criteria open in amber (for example 1 criterion open) on its page, on the Projects page, on its block and in the Projects tab of the workspace settings, and the bar on the Git card is headed the same way. The notification says it "finished" rather than "is done", and a line in the chat names the open criteria with the agent's reasons. A card above the bar lists each open criterion and offers two ways on:
- Continue working sets the agent to work on the open criteria.
- Accept as is keeps them unticked and lets the project go on to merge. A later change to the criteria takes the acceptance back.
Review criteria on the bar, the number on the Plan tab and See all on the Plan tab on the card lead to the same place: the Plan tab, showing only what holds up the merge. Above the criteria it says how many hold up the merge and offers Continue working and Accept as is there too, so you can decide next to the criteria themselves. The arrow beside Review criteria on the bar offers both as well.
Until one of them is chosen, Merge PRs and Queue for merge wait and say why. Queueing several projects at once queues the ones that are ready; the dialog names the others with their open count and a Review criteria link. When none is ready, nothing can be confirmed. Push branch and Open PRs stay available, but pull requests opened while criteria are open are drafts, and their description starts with an Open criteria checklist. Open PRs asks you to confirm first. Push and pull request lines in the chat end by naming the open criteria. Once the last criterion is ticked, or the project is accepted as is, Yard takes the section out and marks the drafts ready for review.
In a spec that ranks its criteria, only open must-haves do all this: the project reads K must-haves open, the card lists the open must-haves, and a pull request is a draft only while one is open, under Open must-haves. Open shoulds and nice-to-haves never hold it up: the pull request lists them under Still open, and with every must and should met the bar reads Ready for review.
Criteria left open only because the base branch fails too (blocked by base
branch) do not hold the merge queue back. Through the API, queueing a
project with other open criteria is refused (409 criteria_open) unless the
request sets force.
Agents tick each criterion as soon as it is verified, with yard criteria tick, and run their checks with yard check. Yard keeps each tick and the
last check with the commit it was verified on (hover the criteria count to
see them), so ticks survive the runner losing its copy of spec.md.
When this card and a merge conflict card show together, both start collapsed: each keeps its headline and its buttons, and Show criteria or Show files opens the full list. The area below the spec never takes more than half the pane and scrolls on its own, so the spec stays readable.
If you send the agent a message in a finished project, the project reads Working (on its page, on the Projects page and on its block) with what the agent is doing right now, and its page offers Stop instead of merge and close. When the turn ends it reads Done again.
A pull request opened from Yard lists its commits and, when a project changes several repositories, the project's other pull requests under Related pull requests, so a reviewer finds the rest of the change. By default it says nothing about Yard. A workspace owner can turn on Say where pull requests come from (workspace settings, General, Automation): pull requests then also link to their project, carry the agent's own summary of the change from the chat, and the spec.
From a finished project you can also choose Continue working or Start a new project…, which opens Write spec with the same blocks.
A message in the chat of a finished project sets the agent to work again. While that turn runs the project reads Working (its row adds "was done"), the bar shows what the agent is doing with a Stop button, and merging and closing wait. When the turn ends the project is Done again, and the bar names the next step for whatever the agent left behind.
The workspace setting Delete project worktrees when done removes worktrees once the pull requests are merged, never unpushed work.
Automation
A workspace owner can let Yard take these steps by itself, in the workspace settings under General, Automation. All of them are off at first.
- Approve specs automatically. When the agent has written a project's spec and has no questions, work starts at once, as if the project's author had pressed Start work. A spec that ended with a question or an error waits as usual.
- Push automatically. Each time the agent finishes a turn that changed code, in any stage but setup (a Draft project worked on through chat too), its branches are pushed. Code changes are always committed first: anything the agent left uncommitted is committed as it is, in the name of the person whose turn it was. Nothing is committed or pushed while work the agent left running in the box still runs, or when it stopped early with must-haves open; the chat says so, and the Git panel still pushes by hand.
- Open pull requests automatically. After the push, every repository that has no pull request yet gets one. This needs Push automatically, so turning it on turns that on too.
- Say where pull requests come from. Pull requests opened from Yard, by hand or automatically, also link to their project, carry the agent's summary from the chat and the spec. Off: they describe only the change.
Each step runs as the person whose agent turn just ended, with their GitHub account, and the chat says what was done. Nothing is pushed while the agent is waiting for an answer, after an error or a stop, or when that person has no GitHub connection. When there is work to push but Yard cannot push it now, the chat says why: the runner is offline, another chat of the project is still working (its turn pushes when it ends), or the project is still being set up. Merging stays with people, or with the merge queue when someone queues a project.
Merge queue
The merge queue merges finished projects one at a time, in the order they were queued, on the server: it carries on with every page closed. While the workspace's Ask before has Merging to main (Agents settings), only a person queues a project: a goal on Autopilot does not, and its agents are told merging is yours.
- Queue several at once. On the Projects page, ⌘-click (Ctrl-click on Windows and Linux) rows to pick them, or Shift-click to pick every row between the last one and this one. When a project is open, it is picked too: Shift-click another row to pick both and every row between, or ⌘-click one to pick it alongside the open one. A plain click still opens a project. The bar under the projects offers Queue for merge with the actions for several projects. Only Done projects are queued; the button says how many of the selection it takes.
- Queue one. Queue for merge in a Done project's row menu (⋯), or in the menu beside the main button of the bar under its spec.
The confirm lists the projects in order and lets you pick the merge method (squash by default) and whether each project is closed after merging (on by default; off leaves it open as Done with merged pull requests). It also says whether the queue waits for CI.
For each project, in turn, the queue:
- looks the pull requests up again. Merged already (by hand, here or on GitHub): the project counts as merged and the queue moves on.
- pushes what is not on GitHub yet and opens the missing pull requests, as the person who queued it.
- asks GitHub whether every pull request can be merged, and waits while GitHub is still working it out.
- when one conflicts with its base, merges the base into the branch. A clean merge is pushed and the project goes on without an agent. When git cannot merge it, the project's agent gets a turn to resolve the conflicts in the project's chat; once it has committed the merge, the queue pushes it. The agent gets two tries. The item fails with "asked a question" only when that turn's own reply asks one; a turn that stops with the merge still half done fails as "stopped without resolving the conflicts", with Retry.
- with wait for CI checks on, waits until every check of every pull request has passed.
- merges the pull requests, then closes the project if that was asked.
Each step is a line in the project's chat (a conflict is said once per pull request and head commit, not again by the queue), and each row on the Projects page shows where its project is (Queued #2, Resolving conflicts, Waiting for CI, Merge failed) for everyone in the workspace. The project's page says the same, with Remove from queue.
See what is queued
While anything is in the queue, the Projects page lists it above the projects, unfolded: Merge queue with how many projects it still works on, then one line per project in the order the queue merges them (the one being merged or next first), each with its place and what it is doing (Merging, Resolving conflicts, Waiting for CI, Queued #3). Projects whose merge failed come last as Merge failed, with Retry and Remove for editors; they are not counted. Click a title to open the project. Fold the list with its chevron; the browser remembers that.
The sidebar shows the same at a glance: Merge queue and its count at the top of its Projects pane, above the project rows. It opens the list on the Projects page.
A project the queue cannot merge (conflicts still there after two tries, a failing CI check, GitHub refusing the merge) is marked Merge failed with the reason, and the queue goes on with the next one. Retry puts it back at the end of the queue; Remove from queue takes it out.
While the queue runs you can still merge any project by hand, queue more (they go to the end) or take one out. Starting work on a queued project again, stopping its agent, closing or deleting it takes it out of the queue.
Pause the queue
While projects are in the queue, the line at the top of the Projects page says Merge queue with its count and Pause (the sidebar's Merge queue link reads Merge queue paused while it is). Pausing stops the whole queue for the workspace until someone presses Resume (there, in a queued project's row menu, or in the bar under its spec, which says Merge queue paused). A step already under way finishes (a merge already sent to GitHub stands). If the agent is resolving conflicts for the queue, its turn is stopped and that try does not count. You can still merge by hand and queue more projects while the queue is paused; they wait. Editors can pause and resume.
Restarts
The queue is kept in Yard's database, so it survives a restart of Yard and of the runner. Pausing does too: a paused queue stays paused. When the runner goes away (an update, a reboot), the queue waits for it however long it takes and carries on where it was. An agent turn the restart cut off is carried on by itself. A merge the restart left half done in a worktree is finished by the agent, not refused.
Wait for CI checks
Merge queue: wait for CI checks before merging, in the workspace settings under General, is off at first: the queue merges as soon as GitHub allows it (branch protection still applies). Turned on, every check run and commit status on a pull request's latest commit must pass first. A failing check marks the project Merge failed with the names of the failing checks; checks still running after 60 minutes do the same. Either way the queue goes on with the next project. Reading checks needs the GitHub App's Checks and Commit statuses read permissions.
GitHub's API limit
The queue calls GitHub as the person who queued the project, so it shares their GitHub API limit (5,000 requests an hour) with everything else Yard does for them. When GitHub says that limit is reached, the project is not marked failed: the queue waits until GitHub's reset time, says once in the project's chat when it carries on (Merge queue: GitHub's API limit is reached; it carries on at 14:05 UTC.), and makes no GitHub calls with that token meanwhile. It also pauses when fewer than 100 requests are left in the hour, so opening projects and merging by hand keep working. After GitHub's shorter "secondary" limit five times in a row, the project is marked Merge failed; Retry a few minutes later.
The queue only looks again when GitHub reports something about the queued pull request (a push to its branch, its own CI finishing). Pushes to the base branch and CI for other branches do not wake it.
Close, reopen or delete
Close project (or Merge PRs and finish) is the normal end. The project's worktrees and its container are removed, but nothing is deleted: the project moves to Done on the Projects page. Closing warns you when the agent is still working or when work is not on GitHub yet, and asks what to do with monitors the project made that were never merged.
A finished project stays readable. Open it from Done and its page shows the same sections, read-only: its report, the spec as it was when the project was finished (Open the spec shows the whole text), its criteria, the repositories with their branches and pull requests, the blocks it linked, and what it made. This is read from the workspace's archive on the runner, so it needs the runner to be online. The report's text is kept with the project itself and reads without the runner; its pictures come from the archive.
Reopen, in the header of that page or on the row under Done, brings the project back: its directory returns from the archive and its worktrees are checked out again from their branches.
A branch is checked out in one project only, but a closed project does not hold its branch: another project can Work on existing branch… with it, or work on its pull request, without deleting anything. Reopening the closed project then waits until that other project is closed too.
Delete project… (in the project's menu) removes it for good, and asks again before losing unpushed work. Its confirm shows what is done so far, and keeps it current while it is open: the plan's steps done and in progress, the step the agent is on (or its last action), the acceptance criteria ticked, and whether the agent is still working or work is not on GitHub yet. A finished project can be removed with Delete forever…, in the More menu of its page or on its row. Files of deleted projects stay in storage for the organization's retention period.
Closed projects are also deleted by themselves a set time after they were closed: Delete closed projects automatically in the workspace's Settings → Projects picks 1, 3, 7, 14 or 30 days, or Keep until deleted by hand. A new workspace starts at 3 days; a workspace from before the setting keeps its closed projects until someone picks a period. Each closed project's row there says when it will go, and whoever started it gets a notification a day before. Projects are deleted only while the workspace's runner is online, so one closed longer ago is deleted once the runner is back. Only workspace owners change the setting.
Chat log in the workspace
To keep the conversation with the work, choose Add chat log to the workspace in the project's More menu or the menu of its row on the Projects page. It becomes a block on the workspace's canvas and stays there even if the project is deleted. After that, the same item reads Show chat log in the workspace.