# Write A Spec

Extend a core journey in evals/core or write a one-off proof in evals/proofs that...

- Repository: https://github.com/different-ai/openwork (24362 stars)
- Category: Git and review
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add different-ai/openwork --skill write-a-spec -g -a claude-code -y`
Codex: `npx skills add different-ai/openwork --skill write-a-spec -g -a codex -y`
Cursor: `npx skills add different-ai/openwork --skill write-a-spec -g -a cursor -y`
Gemini CLI: `npx skills add different-ai/openwork --skill write-a-spec -g -a gemini-cli -y`

## Description

Extend a core journey in evals/core or write a one-off proof in evals/proofs that proves a PR's change to a human reviewer. Use when a PR changes user-visible behaviour, when a reviewer asks "show me", or when the coverage decision says a journey is missing.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Skill: Write a Spec

Every `evals/core/*.e2e.test.ts` or `evals/proofs/*.proof.test.ts` a PR adds or
changes runs in CI on the PR head and is published as that PR's proof (private report + one PR comment).
Write the spec for the person who will read that report in thirty seconds,
not for the machine that runs it.

## Map: from change to reviewed proof

| Moment | Skill | Output |
| --- | --- | --- |
| Decide whether a journey is needed and design it | `write-a-spec` (this) | a spec whose titles, steps, and evidence read as the report |
| Run it and read your own record | `run-tests` | `evals/results/test-runs/<latest>/` with the captions in order |
| Let a reviewer click through the change | `preview-my-work` | a sandbox link in the report's **Show sandbox** panel |
| Describe it on the PR | `open-a-pr` | an `## Evidence` line naming the spec and its before → after |
| A proof or check is red | `diagnose-a-red-run` | classification before any code change |
| Extra screenshots or a video outside the spec | `record-a-demo`, `upload-photo` | PR attachments (these are not proof) |

### Which lane runs your spec (and when to tag)

CI picks the lane from the file name and tags alone. Pick the lane first:
it decides the world you can build.

| If the spec… | Name / tag | CI lane |
| --- | --- | --- |
| proves your change (default) | `evals/proofs/<name>.proof.test.ts` | the dev push that adds or changes it ("Core journeys"); on demand with `PR change proof` |
| changes one of the nine core journeys in `evals/journeys.ts` | `evals/core/<journey>.e2e.test.ts` | core journeys on every dev push and nightly |
| needs a reviewer to reopen the *running* browser at a screenshot | add `{ tags: ["checkpoints"] }` to the `test(...)` options | protected checkpoint lane on Freestyle (not run by manual proof runs) |

The rest: https://github.com/different-ai/openwork/blob/HEAD/.opencode/skills/write-a-spec/SKILL.md