Skip to main content
/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.

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.

Run /spec

In Claude Code, in your repository, type /spec and what you want built:
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: Prove the work 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.
  • 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.
  • 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.