agentleFS
cedricgnanscedricgnans/forge-solo/skills/forge-specification/SKILL.md

forge-specification

Skill0 starsChanged 3 months agoMITView on GitHub

Writes the behavioural specification of a capability — what the system does, observable and testable, with no technology choices. Uses EARS notation and Given/When/Then scenarios, plus the ADDED/MODIFIED/REMOVED delta format on existing codebases. Produces specs/<capability>/spec.md. Use this skill after framing, or whenever someone asks for requirements, a spec, user stories, acceptance criteria, or says "here's what it should do" — including when the feature looks obvious, because implicit requirements are the leading cause of rework.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    If a capability needs more than about fifteen requirements, it probably contains two.

    line 20
  2. Distinctive:

    Every non-trivial requirement gets at least one scenario.

    line 55
  3. Distinctive:

    Write them only if quantified and checkable.

    line 80
  4. Distinctive:

    Don't rewrite the system. Describe only what changes relative to existing specs:

    line 90
  5. Distinctive:

    No technology: No database, framework, transport format or library name.

    line 114
  6. Very specific:

    No invented requirement: If you don't know, write [NEEDS CLARIFICATION: the precise question] and ask.

    line 115
  7. Distinctive:

    Internal consistency: do two requirements contradict?

    line 127

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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

Behavioural specification

A specification describes what the system does, never how. The test is simple: if you can reimplement the spec on a different stack without rewriting it, it is correct. If it mentions PostgreSQL, React or a REST endpoint, it is contaminated.

This separation is not ceremony: it lets you review intent without arguing about technique, and reuse the spec when the technique changes.

One capability, one spec

Split by business capability ("invite a collaborator", "export a report"), not by technical layer. A spec that talks about "the database" or "the API" is badly split.

If a capability needs more than about fifteen requirements, it probably contains two. Flag it and propose the split before writing.

EARS notation

Each requirement follows one of these five patterns. They force you to name the trigger, which surfaces the cases prose leaves in shadow.

PatternFormUse
UbiquitousTHE SYSTEM SHALL <behaviour>Always true
Event-drivenWHEN <trigger> THE SYSTEM SHALL <behaviour>Reaction to an event
State-drivenWHILE <state> THE SYSTEM SHALL <behaviour>True during a state
Unwanted / conditionalIF <condition> THEN THE SYSTEM SHALL <behaviour>Error or exception case
Optional featureWHERE <feature present> THE SYSTEM SHALL <behaviour>Behaviour of a variant

Example:

### Requirement 2 — Invite a collaborator
**Story.** As a workspace admin, I want to invite a collaborator by email, so they can join
without me creating their account.

- R2.1 — THE SYSTEM SHALL restrict invitation creation to members holding the `admin` role.
- R2.2 — WHEN an admin submits a valid email address THE SYSTEM SHALL create an invitation and
  send an email containing a signed link.
- R2.3 — IF the address already belongs to a workspace member THEN THE SYSTEM SHALL reject the
  request with "this person is already a member" without creating an invitation.
- R2.4 — WHILE an invitation is unaccepted and less than 7 days old THE SYSTEM SHALL allow its
  recipient to complete signup.
- R2.5 — WHEN an invitation passes 7 days THE SYSTEM SHALL mark it expired and refuse the link.

Scenarios

Every non-trivial requirement gets at least one scenario. That is what makes it testable, and what an automated test will later reuse word for word.

#### Scenario: expired invitation link
- GIVEN an invitation created 8 days ago and not accepted
- WHEN the recipient opens the link
- THEN the system shows "invitation expired" and offers to contact the admin
- AND no account is created

The three zones everyone forgets

Working solo, nobody reviews. These three zones are what come back in production:

  1. Error paths. For each event-driven requirement, ask: what if the external service is down? if the event arrives twice? if the input is malformed? A third-party unreachable for thirty minutes is not a rare case.
  2. Boundaries. Zero items, one item, the maximum value, a negative value, two concurrent actions on the same object.
  3. Data lifecycle. What happens to a record when its owner is deleted? How long do you keep it? Who may read it? These questions get asked once, at spec time, or ten times afterwards.

Non-functional requirements

Write them only if quantified and checkable. "The system must be fast" is useless. "THE SYSTEM SHALL render the report list in under 2 s for 5,000 rows on a 3G connection" will arbitrate an architecture decision.

Cover at minimum: expected volume, acceptable response time on the hottest path, tolerated downtime, personal data handled, languages, and degraded or offline operation where the context demands it.

On an existing codebase: delta specs

Don't rewrite the system. Describe only what changes relative to existing specs:

# Delta — Capability "authentication"

## ADDED Requirements
### Requirement: second factor
...

## MODIFIED Requirements
### Requirement: session expiry
<Restate the requirement in full in its new wording, not just the difference.>

## REMOVED Requirements
### Requirement: magic-link sign-in
Reason: <…>

Once the feature ships, the delta is merged into the capability's canonical spec and archived with a date. The canonical spec stays a mirror of the real system, and the delta history explains how it got there.

Forbidden

  • No technology. No database, framework, transport format or library name.
  • No invented requirement. If you don't know, write [NEEDS CLARIFICATION: the precise question] and ask. A spec with three honest markers beats a complete and wrong one.
  • No unobservable requirement. "The code must be maintainable" is not a spec requirement; it is a constitution principle.
  • No "should". A requirement is owed or it does not exist. Desirable things go in a "later ideas" section, out of scope.

Self-review before presenting

Reread cold and fix in place:

  • Markers: any TBD or unintentionally empty section left?
  • Internal consistency: do two requirements contradict? Do R2.4 and R2.5 agree on the 7-day boundary?
  • Ambiguity: can a requirement be read two ways? If so, pick one and make it explicit rather than letting the reader choose.
  • Testability: for each requirement, could you write the test that fails when it is violated?
  • Scope: is the spec covered by the approved framing, or did it grow along the way?

Then present the file and ask for an explicit review before moving to design.

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.