spec-writing
Skill1.3k starsChanged 3 days agoApache-2.0View on GitHub
Author, review, or reorganize accepted technical contracts under spec/, including domain models, lifecycles, APIs, protocols, ownership, security, and compatibility. Use when a task changes or evaluates those contracts; ordinary implementation details do not require a spec rewrite.
17 other projects use a version of this.
Trending
More talk lately.about the whole repository
Most recently taken up by
- crbnos/carbontheir own version, first seen Nov 15, 2026
- rajanrx/skillstheir own version, first seen Nov 8, 2026
- rioffe/specchecktheir own version, first seen Nov 6, 2026
- ragna-ai/ragna-studiotheir own version, first seen Nov 1, 2026
- OrionicsLtd/claude-skillstheir own version, first seen Nov 1, 2026
- dagarre00/claude-code-templatetheir own version, first seen Oct 15, 2026
Who's talking about converge-ai-labs/agent-foundation
- converge-ai-labs/a13n-sdk-typescript“chore(contract): update Service snapshot to 351d598a2315”GitHub · Nov 5, 2026
- converge-ai-labs/a13n-sdk-rust“chore(contract): update Service snapshot to 330c4af4e12a”GitHub · Nov 5, 2026
- converge-ai-labs/a13n-sdk-go“chore(contract): update Service snapshot to 351d598a2315”GitHub · Nov 5, 2026
- converge-ai-labs/a13n-sdk-python“chore(contract): update Service snapshot to e9ee726112f5”GitHub · Nov 5, 2026
- converge-ai-labs/a13n-sdk-rust“feat(sdk)!: support Environment desktop control in Rust SDK and CLI”GitHub · Oct 29, 2026
The biggest 5 of 50 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 50
Talked about on GitHub (50 times).
On GitHub · 50
- Nov 5, 2026chore(contract): update Service snapshot to 351d598a2315 — converge-ai-labs/a13n-sdk-typescript0 reactions
- Nov 5, 2026chore(contract): update Service snapshot to 330c4af4e12a — converge-ai-labs/a13n-sdk-rust0 reactions
- Nov 5, 2026chore(contract): update Service snapshot to 351d598a2315 — converge-ai-labs/a13n-sdk-go0 reactions
- Nov 5, 2026chore(contract): update Service snapshot to e9ee726112f5 — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 29, 2026feat(sdk)!: support Environment desktop control in Rust SDK and CLI — converge-ai-labs/a13n-sdk-rust0 reactions
45 more on GitHub
- Oct 29, 2026feat(sdk)!: support Environment desktop control and current Service APIs — converge-ai-labs/a13n-sdk-typescript0 reactions
- Oct 29, 2026feat(sdk)!: support Environment desktop control and current Service APIs — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 29, 2026feat(sdk)!: support Environment desktop control and current Service APIs — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 19, 2026feat(sdk)!: support committed Apps and recover truncated SSE — converge-ai-labs/a13n-sdk-rust0 reactions
- Oct 19, 2026feat(sdk)!: support committed Apps and recover truncated SSE — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 19, 2026feat(sdk)!: support committed Apps and recover truncated streams — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 19, 2026feat(sdk)!: support committed Apps and paginated Run usage — converge-ai-labs/a13n-sdk-typescript0 reactions
- Oct 18, 2026Separate deferred-tool discovery from callability for reusable programs — pydantic/pydantic-ai0 reactions · 3 comments
- Oct 16, 2026feat(sdk): support desktop control, tool discovery and context usage — converge-ai-labs/a13n-sdk-rust0 reactions
- Oct 15, 2026feat(sdk): support desktop control and native tool discovery — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 15, 2026feat(sdk): support desktop control, tool discovery and context usage — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 15, 2026feat(sdk): support desktop control and native tool discovery — converge-ai-labs/a13n-sdk-typescript0 reactions
- Oct 15, 2026feat(streams)!: add native Session snapshots and update Items readback — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 15, 2026feat(streams)!: add typed Session snapshots and update Items readback — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 15, 2026feat(streams)!: add typed Session snapshots and update Items readback — converge-ai-labs/a13n-sdk-typescript0 reactions
- Oct 13, 2026feat(sdk): support shared memory spaces and computer contracts — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 13, 2026feat(sdk): support shared memory spaces and run inspection — converge-ai-labs/a13n-sdk-rust0 reactions
- Oct 13, 2026feat(sdk): support Memory Spaces and execution diagnostics — converge-ai-labs/a13n-sdk-typescript0 reactions
- Oct 7, 2026feat(sdk)!: add Findings and preserve imported history order — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 7, 2026feat(sdk)!: add Findings, saved content and message-author reads — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 4, 2026feat(sdk): support ordinal Run display windows and continuation — converge-ai-labs/a13n-sdk-go0 reactions
- Oct 4, 2026feat(sdk): support paged Run display and sealed-history continuation — converge-ai-labs/a13n-sdk-python0 reactions
- Oct 4, 2026feat(sdk): expose ordinal Run display windows and nullable item metadata — converge-ai-labs/a13n-sdk-typescript0 reactions
- Sep 30, 2026🚨 自动扫描发现高危密钥 (2026-09-30) — butwedont/butwedont.github.io0 reactions
- Sep 18, 2026Add SDK-owned integration CI against pinned, main, and released Service targets — converge-ai-labs/a13n-sdk-python0 reactions
- Sep 17, 2026chore: update Service contract to 9d6ab5529b6d — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to 9d6ab5529b6d — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to 9d6ab5529b6d — converge-ai-labs/a13n-sdk-python0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to d26ece6d8b23 — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to d26ece6d8b23 — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to d26ece6d8b23 — converge-ai-labs/a13n-sdk-python0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to b271ada99701 — converge-ai-labs/a13n-sdk-python0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to b271ada99701 — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 17, 2026chore: update Service contract to b271ada99701 — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 8f60ca0fcfd9 — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 8f60ca0fcfd9 — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 0e5501328a3c — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 0e5501328a3c — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to e00e21d89fcd — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to e00e21d89fcd — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 59cd7756419f — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 59cd7756419f — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to e1d37353fb43 — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to e1d37353fb43 — converge-ai-labs/a13n-sdk-go0 reactions · 1 comment
- Sep 16, 2026chore: update Service contract to 23339a58f40e — converge-ai-labs/a13n-sdk-rust0 reactions · 1 comment
Other versions17 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 17
- crbnos/carbon★ 2.8ksame name
- itseffi/agentic-os★ 114same name
- khuynh22/agent-dev-team★ 9same name
- rioffe/speccheck★ 5same name
- anyoneanderson/agent-skills★ 3same name
- mariomile/builder-os★ 2same name
- rajanrx/skills★ 2same name
- bedomax/webdesigner-agent★ 1same name
- dagarre00/claude-code-template★ 1same name
- OrionicsLtd/claude-skills★ 1same name
7 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository5 other files it gives its agents.
- AGENTS.mdAGENTS.md
- audit-repository-consistencySkill
- commit-push-prSkill
- uiux-polishSkill
- worktree-prSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 15 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Read spec/README.md, the relevant subsystem index/reading path, and the documents that own changed concepts.
- Distinctive: line 20
Read structure-and-template.md when adding or splitting documents, changing ownership/navigation, or choosing a contract's structure.
- Distinctive: line 26
Write the resulting design in present tense with testable statements.
- Distinctive: line 28
Read domain-modeling-and-naming.md when adding or reshaping concepts, schemas, identities, lifecycles, or shared terms.
- Distinctive: line 30
Use upstream public primitives when they already own the semantics.
- Distinctive: line 34
Use a diagram or table when it clarifies the contract.
- Distinctive: line 38
Search changed terminology and update stale summaries, incoming links, and dependent contracts.
- Very specific: line 39
Verify one owner for each fact, consistent identity/version/state terms, and explicit independent completion boundaries.
“Common” is measured: kept by at least 6 in 10 of the 15 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.
Files
Specification Authoring
Maintain spec/ as the current, internally consistent accepted design. Follow AGENTS.md and CONTRIBUTING.md; Repository Model defines what belongs in specifications.
Establish Authority
Read spec/README.md, the relevant subsystem index/reading path, and the documents that own changed concepts. Search affected terms, states, schemas, and claims across spec/. Reuse context already read.
Use the accepted outcome supplied by the user or concluded discussion. Do not infer a new product or architecture decision from implementation behavior alone. If material alternatives remain unresolved, identify the decision and continue independent authorized work; keep the unsettled design out of spec/. The Issue-to-PR workflow does not itself authorize posting to GitHub.
Choose the Owner
Each durable fact has one owning contract. Update that owner first, then affected summaries, catalogs, reading paths, and incoming links. Preserve established terms and ownership unless the accepted change replaces them.
Read structure-and-template.md when adding or splitting documents, changing ownership/navigation, or choosing a contract's structure. Ordinary edits can retain the existing structure.
Keep platform definition in spec/README.md, subsystem navigation in its README.md, architecture in 00-overview.md, and detailed contracts in cohesive numbered documents. Overviews link to detailed schemas and state machines rather than becoming competing owners. Do not renumber stable files casually or create empty templates/placeholders in spec/.
Write the Contract
Write the resulting design in present tense with testable statements. Explain purpose, ownership, authority, and observable behavior. Include applicable data types, lifecycle/completion boundaries, failure/cancellation/retry/unknown-outcome semantics, security, compatibility, and verifiable invariants.
Read domain-modeling-and-naming.md when adding or reshaping concepts, schemas, identities, lifecycles, or shared terms. Derive models from representative flows before drafting fields or APIs.
Use upstream public primitives when they already own the semantics. Introduce project abstractions only for a stable cross-host or cross-provider contract. Label conceptual Python-like schemas explicitly; distinguish them from serialized wire formats.
Omit private classes, layouts, hooks, and algorithms that can change without affecting observable behavior, authority, security, or compatibility. Keep accepted trade-offs when they explain the cost of the selected design. Proposals, rejected alternatives, discussion history, progress, tutorials, runbooks, and contributor procedures belong in the surfaces assigned by Repository Model.
Use a diagram or table when it clarifies the contract. Prefer Mermaid for architecture, state, or interaction diagrams, and keep diagrams, schemas, tables, and prose semantically aligned.
Check Consistency and Validate
- Search changed terminology and update stale summaries, incoming links, and dependent contracts.
- Verify one owner for each fact, consistent identity/version/state terms, and explicit independent completion boundaries.
- Distinguish process-local observations from durable facts and transport delivery from execution authority.
- Make security and compatibility failures explicit. Remove stale text, orphan sections, duplication, and editing residue so the result stands alone without issue history.
For spec-only changes, format the affected files and run:
uv run --locked mdformat --number <changed-spec-files>
make verify
git diff --check -- specFor accompanying implementation or shared tooling, complete the applicable repository/component gates. Reuse valid results and rerun checks when their inputs change. Report validation and unresolved decisions without claiming that formatting proves semantic correctness.
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.

