AGENT SKILL

write-a-spec

Turn an accepted intent into a spec an engineer can build from in this repository: the goal restated, the approach and why, every path it touches, the steps, the tests that prove it, the risks, and what is still open. For a step that designs a change before anyone builds it.

License 许可
MIT
所属仓库
emyann/nemia
最近更新
2026-11-15
Stars
★ 3
Forks
0

01 前言 Front Matter

name
write-a-spec
description
Turn an accepted intent into a spec an engineer can build from in this repository: the goal restated, the approach and why, every path it touches, the steps, the tests that prove it, the risks, and what is still open. For a step that designs a change before anyone builds it.

02 资源文件 1

03 SKILL.md 正文

Write a spec

The intent says what should be true; the spec says how this repository gets there. The engineer and the reviewer read the spec, not the intent, so restate the intent's goal and constraints in it.

  1. Read the intent, under From run in your brief, then the code it touches. Facts are yours to find: read, search, run the suite, or dispatch a sub-agent for a wide search. Never ask the person for what you can look up.
  2. Read the rules the change meets: the repository's instruction files (CLAUDE.md at the root and in each folder the change touches) and every architecture or design document they name — its boundaries and what each owns, its size limits (a limit is met by cutting, never by raising a ceiling), how to test.
  3. Choose the approach, and say why this way rather than the obvious other. Challenge any mechanism the intent asserts: read the code that would carry it.
  4. Place each change by the boundaries the repository's own rules define, in their terms. Each change says where it lives and why there and not in the neighbouring place, citing the rule. The placement table gives each concept the change adds or moves: where it lives, the rule that puts it there, and the alternative rejected. A placement the rules do not settle is the person's: ask it in a round.
  5. List every change by path, the steps in order, and the tests: for each rule the change adds, the fixture that makes it refuse, and the check that it fails without the rule. Name the one layer that proves each rule, and ask for it there alone: a proof where the repository proves its pure decisions, a schema where the rule is a boundary's shape, else the cheapest test that can fail for it. A test of the running whole, in a browser or end to end, is for what only the running whole shows: an interaction, a layout, two parts wired together. A rule restated at every level is three tests to change for one fact, and every round after pays for each.
  6. Cut it by its seams, never by its cost. Cut the work into parts by where each lives: a layer, a package or a door, the boundaries your placement already names. Each part is a distinct area, says what it needs of the others, and is ordered only where one needs another, so parts with no need of each other can be built at the same time. Propose a second intent only for a seam of logic, where a part cannot be built until another has landed and been used; never cut to stay under a budget. When the whole costs more than a run usually does, say so, and size each step's budget to it.
  7. Ask what is the person's. A choice the intent leaves open, a trade-off only they can weigh: ask it in a round, numbered, each with your recommended answer. Record each answer, and who gave it, in decisions.

Read a file with Read, list a folder with Glob and search with Grep; never grep or a pipe in Bash. cat, head, tail, wc, cut and ls read a file or a folder inside the workspace, and your fence refuses each one a path outside it; never sed, awk, find, sort, uniq or tee, which can write a file or run a program, nor wc --files0-from, which reads the paths a file lists. Otherwise Bash runs the checks below and git's read-only questions — git diff, git log, git show, git status, git blame, git grep <pattern> <rev>, git ls-files, git rev-parse, git merge-base and the rest of the read-only set your fence allows — each bare and one per call, and never a write. Read, Grep and Glob reach this workspace, by paths from its root, and each folder your brief says you may read, under its own path; never another run's folder, the store (~/.agent-workflows), ~/.claude, ~/.cache or a system path: your fence refuses them without asking. What your brief quotes from outside them is all you have of it: ask in a round for anything more.

Run each check your step names bare, one command per call: never wrapped in timeout or ( … ), piped to tail or grep, or redirected; paths from the workspace root, never cd, git -C, VAR= or for. Anything else is refused.

A spec that reads well and names a function that does not exist is worse than none: name only what you read.

04 同仓库更多 Skills

emyann
emyann/nemia

groom-the-inbox

Read each card in play in the inbox against the repository and say, per card, done (the commit on the base that landed it), replaced (the decision or card that did), stale (each fact that moved, what it said and what it says now) or standing, reading closely only what the period touched. For the janitor's step, which proposes and never acts: a person removes or amends each card by the command the check writes.

★ 3
emyann
emyann/nemia

review-a-change

Review a change in this repository as a second engineer would: against its intent and spec, by reading the diff and the suite's verdict, with findings that name the file, the line and what goes wrong. For a read-only step that decides whether the work goes round again.

★ 3
emyann
emyann/nemia

read-the-stats

Read a factory's stats since the janitor's last run, against the same length of time before it, write a short report, and propose one correction per card — an allow or deny by name, a line in an agent's body or a skill, or a refusal kept on purpose — each with the numbers behind it, never one already in the inbox. For the janitor's step, which proposes and never acts.

★ 3
emyann
emyann/nemia

land-a-branch

Land a run's result on the base branch in this repository's own checkout, the way the step says it lands: make that one act, read its result, and write the message that records what landed — or change nothing and say why it refused. For a gated ending step (workspace: base).

★ 3
emyann
emyann/nemia

implement-a-change

Build a change from its spec in this repository: tests first where a rule is claimed, small commits, the tests of what changed green for the right reason, and each review finding answered in the next round. For a step that writes the code.

★ 3
emyann
emyann/nemia

trial-merge-a-branch

Stages the merge of a run's result branch in the repository's own checkout, and writes its commit message.

★ 3