spec

Files (167)

• SKILL.md
• openai.yaml · agents/
• README.md · evals/
• case.yaml · evals/auto-agent-tool-withheld-asks-the-seams/
• asks-the-seams-naming-the-agent-tool.md · evals/auto-agent-tool-withheld-asks-the-seams/graders/
• no-agent-forked-in-its-place.md · evals/auto-agent-tool-withheld-asks-the-seams/graders/
• no-agent-ran.md · evals/auto-agent-tool-withheld-asks-the-seams/graders/
• nothing-written.md · evals/auto-agent-tool-withheld-asks-the-seams/graders/
• prompt.md · evals/auto-agent-tool-withheld-asks-the-seams/
• case.yaml · evals/auto-choice-taker-unlinked-asks-the-builder/
• asks-the-builder-with-the-reason.md · evals/auto-choice-taker-unlinked-asks-the-builder/graders/
• choice-taker-not-tried-twice.md · evals/auto-choice-taker-unlinked-asks-the-builder/graders/
• no-other-agent-forked-in-its-place.md · evals/auto-choice-taker-unlinked-asks-the-builder/graders/
• nothing-written.md · evals/auto-choice-taker-unlinked-asks-the-builder/graders/
• prompt.md · evals/auto-choice-taker-unlinked-asks-the-builder/
• case.yaml · evals/auto-choice-taker-unlinked-asks-the-seams/
• asks-the-seams-with-the-reason.md · evals/auto-choice-taker-unlinked-asks-the-seams/graders/
• choice-taker-not-tried-twice.md · evals/auto-choice-taker-unlinked-asks-the-seams/graders/
• no-other-agent-forked-in-its-place.md · evals/auto-choice-taker-unlinked-asks-the-seams/graders/
• nothing-written.md · evals/auto-choice-taker-unlinked-asks-the-seams/graders/
• prompt.md · evals/auto-choice-taker-unlinked-asks-the-seams/
• case.yaml · evals/auto-close-carries-the-flag/
• close-names-the-seams-as-ruled.md · evals/auto-close-carries-the-flag/graders/
• journey-line-carries-the-flag.md · evals/auto-close-carries-the-flag/graders/
• last-line-is-the-command.md · evals/auto-close-carries-the-flag/graders/
• prompt.md · evals/auto-close-carries-the-flag/
• case.yaml · evals/auto-extreme-seams-ask-the-developer/
• asks-the-seams-with-the-weaker-side.md · evals/auto-extreme-seams-ask-the-developer/graders/
• nothing-written.md · evals/auto-extreme-seams-ask-the-developer/graders/
• stand-in-forked-once.md · evals/auto-extreme-seams-ask-the-developer/graders/
• prompt.md · evals/auto-extreme-seams-ask-the-developer/
• case.yaml · evals/auto-flag-dropped/
• flag-is-not-the-plan.md · evals/auto-flag-dropped/graders/
• spec-written.md · evals/auto-flag-dropped/graders/
• prompt.md · evals/auto-flag-dropped/
• case.yaml · evals/auto-rules-the-builder/
• builder-and-impeccable-handed-over.md · evals/auto-rules-the-builder/graders/
• choice-taker-forked-once.md · evals/auto-rules-the-builder/graders/
• close-names-front-end-ruled.md · evals/auto-rules-the-builder/graders/
• front-end-line-is-the-ruled-side.md · evals/auto-rules-the-builder/graders/
• front-end-line-ruled.md · evals/auto-rules-the-builder/graders/
• no-question-to-the-user.md · evals/auto-rules-the-builder/graders/
• ruled-builder-carries-its-norm.md · evals/auto-rules-the-builder/graders/
• prompt.md · evals/auto-rules-the-builder/
• case.yaml · evals/auto-rules-the-seams/
• both-seam-sets-handed-over.md · evals/auto-rules-the-seams/graders/
• choice-taker-forked-once.md · evals/auto-rules-the-seams/graders/
• no-question-to-the-user.md · evals/auto-rules-the-seams/graders/
• ruled-seam-carries-its-norm.md · evals/auto-rules-the-seams/graders/
• prompt.md · evals/auto-rules-the-seams/
• case.yaml · evals/auto-seams-already-named/
• no-choice-taker-forked.md · evals/auto-seams-already-named/graders/
• seams-read-taken-none-ruled.md · evals/auto-seams-already-named/graders/
• skipped-in-one-line.md · evals/auto-seams-already-named/graders/
• tickets-line-carries-the-flag.md · evals/auto-seams-already-named/graders/
• prompt.md · evals/auto-seams-already-named/
• case.yaml · evals/auto-steered-ruling-asks-the-seams/
• asks-the-seams-with-the-reason.md · evals/auto-steered-ruling-asks-the-seams/graders/
• stand-in-forked-once.md · evals/auto-steered-ruling-asks-the-seams/graders/
• steered-set-never-written.md · evals/auto-steered-ruling-asks-the-seams/graders/
• …and 107 more

SKILL.md (first lines)

# Spec

This run turns a plan the conversation already decided into one spec, publishes it where the
project keeps its specs, and names the next command of the chain: `journey` or `tickets`, which
read the spec as written.

It is a synthesis, never an interview. The decisions were taken before this run, normally in a
`discuss` session, and the user already spent their attention there, so the run asks two things at
most: whether the test seams match what the user expects, and, only when a story has a screen, who
builds the front-end.

The plan is the subject of the spec, never a task to carry out. However concrete it reads, nothing
in it is built here: the run writes the spec and nothing else.

Every message to the user is written in the language the user opened the session in. Everything
written into the project (the spec, its file name, its slug) is in **English**; UI copy the spec
quotes stays in the product's language.

The run, in order: ground → seams → write → route → close.

## Vocabulary

Used consistently, in the thread and in the spec:

- _spec_: the decided description of one feature, in the format of
  [.agents/formats/spec-format.md](../../.agents/formats/spec-format.md).
- _path_: one thing the actor sets out to do, end to end, walked in steps: arrive, see, act, the
  system answers, or it fails.
- _seam_: the boundary a test drives the feature through.
- _verdict_: the `Journey:` line under the spec's title, read by `tickets`.
- _tracker file_: `docs/agents/issue-tracker.md`, which says where specs and tickets live in this
  project.
- _allocator_: `scripts/feature-folder.sh`, the script that names and dates a local spec's folder.
- _Home repository_: the repository this session sits in, whose `.scratch/` holds the spec.

## How a turn ends

A message with no tool call ends the turn, and the run waits there until the user writes again.
The turn ends at these points and no others:

- the message that sends the user to `/discuss` (step 1);
- the seams question (step 2), which a run under `--auto` hands to the `choice-taker` instead and
  asks only in the cases that step lists;
- the builder question (step 4), asked only when a story has a screen, which a run under `--auto`
  hands to the `choice-taker` instead and asks only in the cases that step lists;
- an allocator refusal (step 3);
- the close (step 5).

Everything between those points happens in one turn. Once the seams are settled, by the user's
answer, by the conversation or by a Ruling, and the builder question is answered where a story has
a screen, the run writes, routes and closes without stopping: it never ends a
turn to report progress, to show a draft of the spec for approval, or to offer the next step
instead of taking it. A status line is welcome, in the same message as the next tool call. A gap
the synthesis finds in the plan is never a reason to stop either: it goes into the close as a line
to reopen in `discuss` (step 5). Nor is a listed repository whose location is missing or is not a
git repository: the spec is written as decided, nothing is asked, and the close names the location
(step 5).

## 1. Ground

**The plan.** The input is the conversation, plus whatever came with the command (`$ARGUMENTS`: a
pasted `discuss` closing summary, when the session that produced it is gone).

- An `--auto` token among the arguments, before the summary, after it or inside it, is dropped
  wherever it sat and puts the run under `--auto`. The rest is read as it would be without the
  flag, so the token never reaches the plan or the spec. What the flag changes is in steps 2
  and 5.
- A `discuss` closing summary is the plan: its decisions, defaults and deferrals are carried into
  the spec as they stand, never re-argued and never improved on.
- A conversation that decided the plan some other way (the user chose among options, or stated what
  is to be built and how) is a plan too.
- A conversation that holds no decided plan gets one message telling the user to run `/discuss` on
  it, and nothing else: no read, no question about the feature, no proposed seams. This is settled
  from the conversation alone, before any tool call. A spec written over an undecided plan fills
  the gaps with decisions nobody took, and the next skills read every line of it as the user's.

**The reading.** Say in one line what is being read, then make the reads that do not depend on one
another in one batch:

- **The glossary and the ADRs.** `CONTEXT.md` (the root one, or the context `CONTEXT-MAP.md` names)
  and the titles under `docs/adr/`, bodies only for the ones the plan touches. The spec uses the
  glossary's words and respects every ADR in the area it touches.
- **The tracker file**, which resolves where the spec goes (the table below).
- **The project's `CLAUDE.md`**, for a Testing Policy that fixes the test surface (step 2).
- **The code the plan touches**, where the conversation has not already covered it: the modules,
  their public surface, the tests beside them. A search or a handful of reads stays in the thread.
  Exploration whose output would run to pages (a whole subsystem, many files) goes to one subagent
  on `model: sonnet`, and the thread keeps a summary of three to six lines.
- **The working tree.** `git status --short` and the branch: dirty files are the user's work in
  progress, left as they are.

**Where the spec goes**, from the tracker file:

| Tracker file says | The spec is |
|---|---|
| local markdown | `.scratch/<YYYYMMDD>-<feature-slug>/spec.md`, the folder dated with the day it was allocated |
| GitHub or GitLab | an issue, created with the CLI the file names |
| something else, in prose | whatever the file describes |
| no tracker file | the same local path, and the closing summary says the file was absent. Never a demand to run a setup skill |

The slug is the spec's title in kebab-case. The folder around it is the allocator's to name and
date (step 3), so nothing is created here: step 2 comes first, and nothing is written before its
answer. A tracker file that spells the local layout out as `.scratch/<feature-slug>/` is naming the
home, not the folder: the allocator dates it either way.

## 2. Seams, the one check

Sketch the seams at which the feature will be tested: existing seams before new ones, the highest
seam possible, as few as possible (the ideal is one).

**Already decided.** When the conversation names them (a testing decision in the `discuss` summary,
a `prove-it-works` answer, a Testing Policy in the project's `CLAUDE.md` that fixes the surface),
they are taken as decided and the check is skipped, said in one line, and the run continues to
step 3 in the same turn. `--auto` changes nothing on this branch: the developer already decided
these seams, so no `choice-taker` is forked for them and none of them reads ruled.

**Otherwise, one message**: the seams proposed, the reason for each in a clause, and whether they
match the user's expectations. Then the turn ends and the run waits. This is the only question the
skill asks about the plan, and no spec is written before it is answered: the seams decide what the Testing

From Thalisu/SKILLS, MIT.

More from Thalisu/SKILLS