agentleFS
victorhqcvictorhqc/filbert/.agents/skills/writing-specs/SKILL.md

writing-specs

Skill4 starsChanged 12 days agoMITView on GitHub

Write or edit a spec in ./specs/ for this repo — the Spec-First protocol. Covers where a spec lives (specs/<topic>/NN-short-description.md), the outline template (Objective, Context, Acceptance Criteria, Plan, Risks), and the MANDATORY MLA in-text citation format — (topic NN) — for referring to other specs. Use this whenever you create, author, extend, or revise any spec/outline/acceptance-criteria file, or need to cross-reference one spec from another.

10 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use writing-plans.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • OpenAISkill

    writing-plans

    Use when you have a spec or requirements for a multi-step task, before touching code

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

5 rules. 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 2

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When a spec mentions another spec, cite it with an MLA-style in-text citation: the main topic followed by the spec number, in parentheses.

    line 45
  2. Very specific:

    Always parenthesized, lowercase topic, zero-padded number matching the file (03, not 3).

    line 56
  3. Very specific:

    Never write prose forms like spec 03, (spec 03), see spec 3, or a bare file path when you mean *another spec*.

    line 58
  4. Distinctive:

    Keep it concise — Hemingway, not academia.

    line 77
  5. Distinctive:

    STOP and wait for the user: before writing any code. The spec is a checkpoint, not a formality.

    line 121

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Writing specs

The Spec-First protocol: problem definition → small, safe change → change review → refactor → repeat. No code is written until a spec exists and the user has reviewed it. This skill is the authority on how a spec is structured and how specs cite each other; AGENTS.md is the authority on the surrounding workflow.

1. Where the spec lives

specs/
├── <topic>/
│   ├── 01-short-description.md
│   ├── 02-short-description.md
│   └── ...
  • Pick the closest existing topic folder or create one. Current topics: core, providers, ui, widgets, ci, site. Only create a new topic folder if the work fits none of them.
  • Number sequentially within that topic folder. List the folder's files, take the next number, zero-pad to two digits (07, not 7).
  • File name: NN-short-description.md — kebab-case, intention-revealing, no spaces.

Topic guide

TopicWhat belongs here
coreProvider protocol, hub, registry, Keychain, refresh
providersIndividual provider implementations (z.ai, Claude, …)
uiMenu bar, popover, settings, app lifecycle
widgetsDesktop widgets, Notification Center integration
ciGitHub Actions workflows, CI configuration, tooling
siteProject website on GitHub Pages

2. MLA cross-references (MANDATORY)

When a spec mentions another spec, cite it with an MLA-style in-text citation: the main topic followed by the spec number, in parentheses. This is the analogue of MLA's (Author Page) — here (topic number).

(core 03)                     one spec
(providers 02, ui 01)         several specs, comma-separated
(providers 04 AC10)           a specific acceptance criterion inside a spec

Rules:

  • Always parenthesized, lowercase topic, zero-padded number matching the file (03, not 3).
  • Never write prose forms like spec 03, (spec 03), see spec 3, or a bare file path when you mean another spec. Those are non-compliant.
  • A path like `Sources/Core/ProviderHub.swift` pointing at source code is not a spec citation — leave those as file paths.
  • Citations stay in specs/. Code, tests, scripts, and config never cite a spec or an AC. See the writing-code skill.

Fix on sight. Existing specs may use non-compliant spec 03 / (spec 03) forms. If you edit a spec that contains a non-compliant reference, convert it:

Non-compliantCorrect
(spec 03)(core 03)
in spec 03(core 03)
spec 04 AC10(providers 04 AC10)
see spec 3(ui 03)

3. The outline

Keep it concise — Hemingway, not academia. Short declarative sentences. Write as many acceptance criteria as the feature needs, no filler.

## Objective
1 sentence.

## Context
- Key files affected — `Sources/Core/Whatever.swift` — one line on why it matters
- Cross-referenced specs go here in MLA form, e.g. builds on (core 03)

## Acceptance Criteria

### AC1: <short description>
- **Given** <precondition>
- **When** <action>
- **Then** <outcome>

### AC2: ...

## Plan
Brief description of the approach. Code snippets ONLY when they clarify an
interface or data shape.

## Risks
- Any known regression or side effect

Section rules

  • Objective — exactly one sentence. If it needs two, the spec is doing too much; split it.
  • Context — bullet list of affected files, each with a terse reason. This is where you name the reference implementations and cite related specs in MLA form.
  • Acceptance Criteria — every AC is Given/When/Then. Number them AC1, AC2, … so they can be cited as (topic NN ACx). Make each one testable — a reviewer should be able to check it off.
  • Plan — the approach, not a diff. No large code blocks; a small snippet is fine only to pin down a protocol signature or data shape.
  • Risks — regressions and side effects a reviewer should watch for. Omit only if there are genuinely none.

4. After writing

  • STOP and wait for the user before writing any code. The spec is a checkpoint, not a formality.
  • During implementation the spec is the source of truth: re-read it before each change, mark items [x] as they land, and log new findings back into the spec.

Self-check before handing a spec back

  • File is at specs/<topic>/NN-short-description.md, number is the next free one in that folder, zero-padded.
  • Objective is one sentence.
  • Every AC is Given/When/Then and testable.
  • Every reference to another spec uses MLA (topic NN) form — no spec 03, no bare (spec NN).
  • If I edited an existing spec, I converted any legacy spec NN references I touched.
  • Plan has no diff-sized code blocks; Risks lists real regressions.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.