Your first project
Hand a piece of work to a coding agent, from selecting what describes it to a merged pull request, with a demo of the whole road.
A project is a piece of work handed to an agent. It starts from a spec, runs in its own container on your runner, and ends with pull requests you review and merge. This tutorial walks the whole road once.
You need a workspace on a runner, an agent account connected under Account settings, Agents, and for code changes a repository in the workspace (see repositories and git).
1. Gather what describes the work
Work starts in the work composer.
Press ⌘/Ctrl+J on any page to open it, or use the one on Home. On a
canvas, select blocks and it comes up with them as its chips. Give
it what the agent should start from: the note or doc that describes the
change, the mockup, the link to the research, the repository. + and @
add more; on a doc, Add this doc adds the doc and its repositories.
Nothing else goes along by itself: your sidebar's Pinned items show as
one chip you can open and leave out.
2. Start with a spec
Open the mode menu (it says Project) and tick Write a spec first, right under Project. Then:
- write what the project should do, in a sentence or two (for example "Add bulk select to the asset grid using the sketch. Keep Undo.");
- pick the agent and model with the model button.
If the instructions name a note that is not on the workspace canvas, the dialog warns
that the project will not get it. Each repository in the context gets a worktree the agent may change,
unless the workspace keeps it read-only. Press Start with a spec (or
⌘/Ctrl+Enter). The project opens with its agent drafting spec.md: a
goal and acceptance criteria, and for a change people see, pictures of the
page today and of how it could look
(pictures in the spec). Read it and edit
it like any note, together with your team, until it says what you mean.
3. Work
Choose Start work. The agent plans first, then works through its
plan in its own container, in a worktree of each repository on a
ctr/<project> branch. You see each step as it runs, and the criteria tick
off as soon as each one is verified (Yard keeps each tick with the commit it
was verified on). Stop halts it at any time.
If the agent stops with steps of its plan unfinished, the bar says how many are not done and Continue working is its main button; merging stays beside it.
If the agent is missing something it asks: the project shows Needs input and the questions appear in its chat as a short form.
Here is the whole road on sample data. Choose Start work, wait for the plan to finish, then follow the bar.
Runs on sample data · The spec is drafted. Work hands it to the project's agent.
4. Push, review, merge
When the work is done the next-step bar under the tabs always names the next step, and a button that cannot be pressed yet says why:
- Push branch sends the branches to GitHub. They are pushed as you; agents never push. (If the agent left changes uncommitted, the bar offers Review changes first, in the project's Changes tab.)
- Open PRs opens a pull request for each repository, also as you.
Review them on GitHub or in the project's Changes tab. If the agent left
criteria open, the project reads K criteria open instead of Done,
Yard asks before opening, and the pull requests open as drafts that list
the open criteria first; they are marked ready once the criteria are
ticked or you accept the project as it is. In a spec that marks its
criteria
(must),(should)or(nice), only open must-haves do this: the others are listed in the pull request without holding it up. - Merge PRs and finish once they are approved: it merges, then closes the project. Merge PRs only, in the menu beside it, merges and leaves the project open. If a pull request conflicts with its base, the bar offers Resolve conflicts instead: the agent merges the base in and commits, you push, and then it can be merged.
- Close project archives the project with its chat and files. It stays under Done on the Projects page (Go to projects in the command palette) and can be reopened. The blocks it linked keep a Done in "<project>" badge; its menu can archive them.
A project without a repository, or without commits, ends differently: the bar offers Take files into the workspace… to bring what the agent made into the workspace, then Close project.
Next
- Projects and specs in full.
- Example prompts to start from.