seam-test
Skill0 starsChanged 58 days agoMITView on GitHub
Decide whether a surface is a seam — something outside this project depends on it, so it warrants a contract — or an internal mechanism, which gets tests and no contract. Use when scoping contracts, when someone proposes writing one, when deciding whether a project needs one at all, or when a capability exists on one surface and nowhere else. Applies PROTOCOL.md §3.2's seam test and the "no third option" rule.
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- conformance/documents/fixtures/sample-good/AGENTS.mdAGENTS.md
- freeze-barSkill
- lane-briefSkill
- ledger-dispositionSkill
- proposing-a-changeSkill
The file
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 40
When a capability exists on one surface and nowhere else, it is one of exactly two things — there is no third:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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
The seam test
Semantics live in docs/PROTOCOL.md §3.2. This skill is the procedure — quote
the spec, don't paraphrase it into drift.
The definition and the test
A seam is a surface someone outside this project's own commits depends on.
The test is one question: if this changed silently, who breaks? If the answer names anyone beyond this project — another team's client, a colleague's tool, an automation reading a file format, a machine that will run this later — it is a seam, and it gets a contract.
- An experience someone builds against is a seam.
- A file format someone else reads is a seam.
- An internal mechanism is not a seam. It gets tests, not a contract.
Where a contract exists, the vision points at it
The vision is a thin pointer to the governing contract, not a restatement of it. And a project with no seam does not manufacture a contract. Inventing contracts where nothing outside depends on anything is one of the things this method deliberately refuses to do.
The "no third option" rule
When a capability exists on one surface and nowhere else, it is one of exactly two things — there is no third:
- Behavior that belongs in the contract, in which case promote it, or
- Debt.
Where one contract governs several implementations, each capability is marked
required, idiomatic to one surface, or forbidden — see docs/PROTOCOL.md §3.2.
When to escalate
For anything past "seam or not" — what a contract must contain, when a new
version is warranted, what triggers promotion — ask
converge:protocol-authority.
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.