Projects and specs · Yard docs

A project is one piece of work handed to an agent. It starts from a spec, runs in a container of its own, and ends with pull requests. Projects are listed in the left sidebar under Projects.

Create a spec

Select the blocks that describe the task on the canvas and choose Create spec → in the selection bar. With nothing selected, the whole canvas is used. You can also start one from + New beside Projects in the sidebar.

The Create spec dialog has:

an instructions field for what the project should do, where you can attach files, point at blocks, type @ to attach a workspace file, use /attach and /model, and dictate with the microphone button;
the blocks it starts from, as chips you can remove, plus any pinned blocks, which are always included;
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;
the agent and model to use.

Choose Create project. You need a connected agent; see agents.

Start without a spec

When the task is clear and you just want it done, choose Work → in the selection bar instead. It opens the same dialog set to Start right away (the switch under the instructions changes it either way; the button then reads Work). The project is set up the same way, shows Setting up meanwhile, and the agent starts working in the worktrees as soon as it is ready, from your instructions and the blocks you picked. There is no spec to review; the spec pane shows the instructions instead, and you can still write a spec there to steer it. Questions, Stop and Done work as for any project.

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 the branch ctr/<slug>; 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. On the project's canvas a repo block says how that project has it. The blocks you selected are copied onto the project's own canvas and stay on the workspace canvas as well.

The project page has the tabs Canvas + spec, Files and Git. Terminal in the footer opens a shell in the project (terminals). To go back to the workspace canvas, click the workspace at the top of the left sidebar; while the sidebar is hidden the toolbar has a ← Workspace button instead.

Rename a project

Choose Rename in the project's menu (the ⋯ on its sidebar row, or the ⋯ in the project's toolbar), or click the title in the toolbar. Enter saves, Escape leaves the title as it was. Everyone in the workspace sees the new title at once: in the sidebar, the toolbar and the browser tab.

Only the title changes. The folder, the address of the page and the branch ctr/<slug> keep the name the project was created with, 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 shows what it 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. The sidebar row and the toolbar show the same line, also for people who do not have the chat open. Then the project is a Draft: everyone with edit access can change the spec together in real time, and you can ask the project agent in the chat to refine it. In a draft the agent does not touch code.

The bar under the spec offers Discard (deletes the project) and Work →.

The project canvas

Blocks on a project's canvas are copies. Editing one marks it LOCAL EDIT and shows a bar, "N block(s) edited only in this project", with Discard and Sync to workspace to write the changes back. A block made inside the project can be copied out with Take into workspace, in its action bar.

To add more context later, use Link to project on a workspace block, or drag the block onto the project's row in the sidebar. Linked blocks carry an IN N PROJECTS badge that lists the projects and offers Unlink from ….

Work

Work → hands the spec to the agent. While it works:

the Agent plan card shows its task list, step by step;
a progress bar counts the acceptance criteria ticked in spec.md;
the sidebar row shows how far it is and what it is doing: WORKING while the agent runs, STOPPED if it stopped before finishing, and ERROR 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.

Commits are made as the person who pressed Start. Stop halts the agent and returns the project to draft. If the agent stops before finishing, choose Back to draft, Mark done or Resume →.

When the agent needs input

When the agent cannot go on without a decision, it asks in the chat. The bar says Needs your input, the sidebar row turns amber and the person who started the work is notified. Answer the questions in the chat and the agent carries on.

Done: push, pull requests, merge

When the work is done, the bar under the spec always names the next step:

Push changes sends the branches to GitHub.
Open PRs → opens a pull request per repository.
Merge PRs & close project merges them once they are approved, then archives the project. To merge and keep the project open, choose Merge PRs only from the arrow beside it.
Close project archives it.

These act with the GitHub account of the person who presses them (Account → 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 and commit → 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 changes 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.

If you send the agent a message in a finished project, the project reads WORKING (in the sidebar, the toolbar and on the canvas) with what the agent is doing right now, and the bar under the spec offers Stop instead of merge and close. When the turn ends it reads DONE again.

A pull request opened from Yard says which project it comes from, carries the agent's own summary of the change, the commits and the spec, and, when a project changes several repositories, lists the project's other pull requests under Related pull requests so a reviewer finds the rest of the change.

From a finished project you can also choose Continue working or Start a new project…, which opens Create 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 (the sidebar 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, under Settings → General → Automation. All three 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 Work. A spec that ended with a question or an error waits as usual.
Push automatically. Each time the agent finishes a turn in a project that is being worked on, 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.
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.

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 (the chat says so). Merging stays with people.

Close, reopen or delete

Close project is the normal end. The project leaves the sidebar and its worktrees are removed, but nothing is deleted: it is listed under Closed in the sidebar and Reopen project brings it back. Closing warns you when the agent is still working or when work is not on GitHub yet.

The sidebar's sections (Projects, Closed, Files) work like the panes of an editor: every header stays on screen, a click on one folds or unfolds its section, the open ones share the height and scroll their own rows, and dragging the line between two open sections resizes them. The sizes are remembered on this browser.

Delete project… (in the project's menu) removes it for good, and asks again before losing unpushed work. A closed project can be removed with Delete forever…. Files of deleted projects stay in storage for the organization's retention period.

Chat log on the canvas

To keep the conversation with the work, choose Add chat log to canvas in the chat's header, the project's menu or its sidebar row. It becomes a block on the workspace canvas and stays there even if the project is deleted. After that, the same item reads Show chat log on canvas.