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.
In this repository6 other files it gives its agents.
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
- Distinctive: line 20
If a capability needs more than about fifteen requirements, it probably contains two.
- Distinctive: line 55
Every non-trivial requirement gets at least one scenario.
- Distinctive: line 80
Write them only if quantified and checkable.
- Distinctive: line 90
Don't rewrite the system. Describe only what changes relative to existing specs:
- Distinctive: line 114
No technology: No database, framework, transport format or library name.
- Very specific: line 115
No invented requirement: If you don't know, write [NEEDS CLARIFICATION: the precise question] and ask.
- Distinctive: line 127
Internal consistency: do two requirements contradict?
≈ “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.
Files
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.
| Pattern | Form | Use |
| Ubiquitous | THE SYSTEM SHALL <behaviour> | Always true |
| Event-driven | WHEN <trigger> THE SYSTEM SHALL <behaviour> | Reaction to an event |
| State-driven | WHILE <state> THE SYSTEM SHALL <behaviour> | True during a state |
| Unwanted / conditional | IF <condition> THEN THE SYSTEM SHALL <behaviour> | Error or exception case |
| Optional feature | WHERE <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 createdThe three zones everyone forgets
Working solo, nobody reviews. These three zones are what come back in production:
- 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.
- Boundaries. Zero items, one item, the maximum value, a negative value, two concurrent actions on the same object.
- 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.
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
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.

