> ## Documentation Index > Fetch the complete documentation index at: https://docs-stg.outerlayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Draft a spec on a work item > Write a spec on a work item before an issue exists, add mocks and pins, and approve the spec to create the issue. 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](https://docs-stg.outerlayer.ai/write-a-spec.md). ## 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](https://docs-stg.outerlayer.ai/roles-and-permissions.md). ## 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](https://docs-stg.outerlayer.ai/review-the-work.md#send-a-pin-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 ` prints each current mock and its open pins. * `outerlayer work mock add --item --file --name --criterion ` adds a mock. `--name` is optional. Without it, the name is the file name without its extension. * `outerlayer work mock replace --item --file ` 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](https://docs-stg.outerlayer.ai/review-the-work.md#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](https://docs-stg.outerlayer.ai/review-the-work.md#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](https://docs-stg.outerlayer.ai/the-work-page.md#remove-an-item-from-work). ## Next steps * [Review and merge](https://docs-stg.outerlayer.ai/review-the-work.md) covers mentions, pins on proofs and approval. * [The Work page](https://docs-stg.outerlayer.ai/the-work-page.md) covers statuses and search. * [Write a spec](https://docs-stg.outerlayer.ai/write-a-spec.md) covers the `/spec` skill. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.