> ## 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.

# Write a spec with /spec

> Turn an idea into an approved issue with /spec. It checks for duplicates, drafts criteria with proof forms, and files the issue after you approve it.

`/spec` turns an idea into an issue that a build can start from. You say what you want built. `/spec` searches for duplicates, drafts a spec with acceptance criteria, and files the issue after you approve it.

`/spec` files nothing before you approve, and it never creates a branch or edits code. It is the starter `spec` skill that `outerlayer init` installs. See [Starter skills and the build](https://docs-stg.outerlayer.ai/starter-skills.md).

## Before you start

* Run `outerlayer init` in the repository, so the `spec` skill is installed.
* Sign in with `outerlayer login`.
* Run `outerlayer spec target`. It prints `can file: yes` when the factory can file an issue in your tracker. See [Spec commands](https://docs-stg.outerlayer.ai/reference/cli-spec.md).

## Run /spec

In Claude Code, in your repository, type `/spec` and what you want built:

```text theme={"system"}
/spec Let a user export their sessions as a CSV file
```

To revise a spec that you already filed, name its issue instead, such as `/spec #42` or a Linear or Jira key. `/spec` then edits that issue in place and does not search for duplicates.

## What /spec asks you

`/spec` stops for you at these points:

1. **Duplicates.** `/spec` searches open and recently closed issues. It shows you a near-duplicate before it drafts anything.
2. **Size.** A spec with more than 24 criteria is not one story. `/spec` shows the work split into slices that each stand alone. You can redraw the split.
3. **Approval.** `/spec` shows the title, the body, the criteria with their proof forms, and the docs verdict. Ask for changes until the spec is right, then approve it. A spec you reject leaves no issue behind.
4. **Where to file.** When the factory has more than one tracker, team or repository, `/spec` asks which to use. It files the issue and prints the issue key and URL. It files only the slices that you name.
5. **Build.** `/spec` asks whether to build on a host, build in a new session, or not yet.

## What the spec holds

`/spec` writes the spec as the `writing-specs` skill describes: the problem before the solution, the non-goals, and the criteria. The criteria are under an `## Acceptance criteria` heading. Each criterion has an id and a Given, When, Then form.

Each criterion whose outcome a person can see gets a proof form, which the build must record:

| Outcome | Proof form |
| - | - |
| A flow of more than one step | `(proof: video)` |
| One state on the screen | `(proof: screenshot)` |
| Output a person reads in the CLI | `(proof: log)` |
| Nothing visible changes | A named test |

[Prove the work](https://docs-stg.outerlayer.ai/attach-evidence.md) shows how a build records the criteria and attaches the proofs.

Before `/spec` shows you the spec, it rewrites the text for a reader who was not in your session. The criteria keep their exact words.

## The docs verdict

Every spec declares a docs verdict with a one-line reason. The verdict is `docs-required` when the change alters what a user sees or does. A new capability with no page yet is `docs-required` too, and a criterion names the page to add. `/spec` judges the change against your README, your `docs/` folder and your docs site.

The `writing-specs` skill says to decide the verdict again from the finished change, before the pull request opens. A verdict that changes then is not a fault. State the difference, because it shows what the spec missed.

## Start the build

The answer you give to the last question decides what `/spec` does:

* **Build on a host.** `/spec` runs `outerlayer work build --issue <reference>`. A runner takes the item when it has a free slot. The factory needs a runner first. See [Set up a host](https://docs-stg.outerlayer.ai/set-up-a-host.md).
* **Build in a new session.** `/spec` runs `outerlayer work build --issue <reference> --local` and prints the line that starts your session. See [Debug a build in your own session](https://docs-stg.outerlayer.ai/launch-a-session.md).
* **Not yet.** `/spec` shows both commands for later and stops.

## Change how /spec works

The steps are in `outerlayer-spec`, a skill that follows your CLI version. To set a value, such as the most criteria in one spec, or to add to a step, edit your repository's own `spec` skill. See [The spec skill](https://docs-stg.outerlayer.ai/starter-skills.md#the-spec-skill).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.