Skip to main content
A draft is a work item with a spec and no issue yet. You write the spec on the item, discuss it with your team, and approve it. Approval files the issue in the factory’s tracker. Use a draft when the idea is not ready to be an issue. Use the starter /spec skill when an agent writes the spec for you. See Write a spec.

Before you start

Two permissions apply:
  • File a spec starts a draft and approves it.
  • Edit a spec edits the spec text, changes mocks, and approves the spec again.
A member with neither permission can read the spec. See Roles and permissions.

Start a draft

  1. Choose Add work on the Work page.
  2. Find the block for work that has no issue yet.
  3. Type a Title.
  4. Choose Start a draft.
The item page opens. The item has your title, the factory’s next item number and the status Draft. A member who has File a spec and not Add work sees the dialog with this block only.

Find drafts

The Work list shows drafts in a Draft group. A draft’s row shows the title, the item number, Not approved and who started it. Choose Draft in the Status menu to list only drafts.

Write and edit the spec

The Overview tab shows the spec text where an item shows its issue.
  1. Choose Edit.
  2. Write the title and the text in Write. Use Preview to see the Markdown.
  3. Choose Save.
Each save adds a line to the item’s history. Choose Show the spec as saved here on a line to read that text. When two members save at once, the second save is refused. The text stays in the editor. Copy it, choose Cancel, and the editor loads the newest spec.

Approve the spec

Choose Approve spec. OuterLayer files an issue in the factory’s tracker with the draft’s title and its newest saved text. A build can then start from the issue.
  • When the factory files in more than one place, a dialog asks you to Choose where to file the issue. It asks again at each approval.
  • A spec with no text cannot be approved.
  • Save or cancel your edit before you approve.
  • When the tracker cannot be reached, the page says so. Try again.
The item keeps its number, its comments and its history. Before approval, Send to agent is off.

After approval

When a member edits the spec after approval, the spec block reads Edited after approval. Choose Approve again to write the newest text to the issue. You need Edit a spec. If someone changed the issue’s text in the tracker since the last approval, OuterLayer refuses and links to the issue. Choose Replace the issue’s text to write your text over theirs.

Add mocks

A mock is a PNG or JPEG image that shows what to build. An item holds 20 mocks, and each image is 8 MiB at most. An item that came from a tracker issue takes mocks too. To add a mock, do one of these:
  • Choose Add a mock in the Mocks row of the Overview tab.
  • Choose Use as a mock on an image in a comment. The comment keeps its image.
A mock opens in the viewer with the file’s name, without its extension. In the viewer you can:
  • Change the name in Mock name.
  • Choose Replace the image. The earlier image stays in the strip.
  • Choose Remove. An image that a comment holds stays in the comment.
  • Choose Change in the Criteria block to name the criteria the mock shows.
You need Edit a spec to change a mock. Without it, each control is off and says why.

What the build receives

The gateway’s GET /v1/work-items/{id} returns the item’s current mocks in a mocks list. Each mock has its name, its criterion ids, a download link for the image, and its open pins. A replaced image and a removed mock are not in the list.

Ask the agent for a mock

An agent adds or replaces a mock when you ask it to. Send the agent a message with Send to agent, such as “Add a mock of the empty state”. An agent job then makes the image and adds the mock. You can also send a pin on a mock to the agent. The agent changes a mock only in a job that answers a message you sent.
  • The mock strip shows Added by an agent, asked by and your name.
  • The timeline shows Agent added the mock, the mock’s name, and asked by and your name.
  • When the agent replaces an image, the timeline shows Agent replaced the mock, the mock’s name, and asked by and your name.
  • When the agent replaces an image, the old image stays in the strip marked Replaced, with its pins. The mock keeps its name and criteria.
  • The agent never removes or renames a mock, and never changes its criteria. A comment or pin that you did not send to the agent starts no job.
An agent’s mock follows your limits. A mock is a PNG or JPEG of 8 MiB at most. An item holds 20 current mocks. A name is 1 to 80 characters. To work with mocks from a terminal, use outerlayer work mock:
  • outerlayer work mock list --item <number> prints each current mock and its open pins.
  • outerlayer work mock add --item <number> --file <path> --name <text> --criterion <id> adds a mock. --name is optional. Without it, the name is the file name without its extension.
  • outerlayer work mock replace <mock id> --item <number> --file <path> replaces the image of a mock.
A signed-in member needs Edit a spec to add or replace a mock. A plain API key cannot write a mock, because a mock names the person who asked or wrote it.

Pin a comment on a mock

A pin is a comment on one point of an image.
  1. Open a mock in the viewer.
  2. Click a point on the image.
  3. Write the comment and choose Comment.
The image shows a numbered pin. The Pins block shows its thread. In the thread you can:
  • Write a reply and choose Reply.
  • Choose Resolve to take the pin off the image. The Resolved list keeps its thread.
  • Choose Reopen to put a resolved pin back with its number.
The mock’s thumbnail shows N open pins. An image holds 50 pins at most. A replaced image shows its pins and takes no new ones. You need Record a review to write, reply, resolve or reopen. You need the permission to read evidence to see pins. A pin is a comment. It records no verdict and starts no agent job until you send it to the agent. Choose Send to agent on an open pin of a current mock to send it to the agent. See Send a pin to the agent. The build receives the open pins of each mock in the mocks list. To pin a comment on a screenshot proof, see Pin a comment on a screenshot proof.

Remove a draft

Choose Remove from Work on the draft’s page. The draft leaves the Work list, and its spec text is kept. See Remove an item from Work.

Next steps