docs(rcp): publish v1.0.0 spec with explicit stability policy#36
Merged
Conversation
Adds docs/rcp/v1.md — the public Runtime Context Protocol spec that IDE and agent vendors integrate against. Closes the RFC 0001 workstream 4 deliverable. - Tools (12) and prompts (4) listed in canonical underscore form - Wire schemas: ManifestEntry, RuntimeContext, Annotation, ProblemDetails - Error code vocabulary (22 codes, full DomscribeErrorCode coverage) - Stability policy: frozen/additive/breaking rules with worked examples - Aliases-through-one-minor-cycle policy for dotted legacy names - Cross-linked from README MCP Tools section and TECHNICAL_SPEC.md §3.4 Depends on #32 (@domscribe/protocol package) and #33 (canonical underscore tool names) for full surface alignment; this PR ships the spec text. Verifier should sync tool-name tables in README and TECHNICAL_SPEC after #33 lands. Refs #35
|
View your CI Pipeline Execution ↗ for commit 836f7fa
☁️ Nx Cloud last updated this comment at |
The v1 spec (`docs/rcp/v1.md`) cross-links to `docs/rfcs/0001-rcp-as-versioning-unit.md` as the decision record for extracting `@domscribe/protocol` as the RCP versioning unit. The RFC was authored by principal-eng during sprint 2371 but had not been committed to the repo; the spec link would render broken on GitHub until this lands. Committing here so the spec PR satisfies its "renders cleanly on GitHub" acceptance criterion without requiring a separate landing. Verbatim RFC content — no edits. Refs #35
The spec stated the entry id matches `/^[A-Za-z0-9_-]{8}$/`, but the
actual `PATTERNS.MANIFEST_ENTRY_ID` in `@domscribe/core` enforces
`/^[0-9A-HJ-NP-Za-hj-np-z]{8}$/` — Crockford base32, excluding `I`,
`L`, `O`, `0` to avoid visual collisions. Since §7 freezes this field
as stable, the wrong regex would lock v1 to a contract the
implementation never produces. Update to the actual regex with a
parenthetical so readers don't need to decode the character class.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes the RFC 0001 workstream 4 deliverable: a public, versioned Runtime Context Protocol spec that IDE and agent vendors can integrate against.
docs/rcp/v1.md— full spec text (§§1-8)What's in the spec
Banner declares
RCP v1.0.0 — published from @domscribe/protocol@1.0.0as required by the acceptance criteria.Conformance — what a v1 server/client MUST do, separated from MAY.
Tools (12) in canonical underscore form, mapped 1:1 to current
MCP_TOOLSconstants:domscribe_resolvedomscribe.resolvedomscribe_resolve_batchdomscribe.resolve.batchdomscribe_manifest_querydomscribe.manifest.querydomscribe_manifest_statsdomscribe.manifest.statsdomscribe_query_by_sourcedomscribe.query.bySourcedomscribe_annotation_listdomscribe.annotation.listdomscribe_annotation_getdomscribe.annotation.getdomscribe_annotation_searchdomscribe.annotation.searchdomscribe_annotation_processdomscribe.annotation.processdomscribe_annotation_update_statusdomscribe.annotation.updateStatusdomscribe_annotation_responddomscribe.annotation.responddomscribe_statusdomscribe.statusUnderscore is chosen so every name passes
^[a-zA-Z0-9_-]{1,64}$(Windsurf-compatible, fixes MCP tool names use dots, which breaks Windsurf (and likely other clients) #18) and matches the existing prompt naming convention already inMCP_PROMPTS.Prompts (4) —
process_next,check_status,explore_component,find_annotations(verbatim from currentMCP_PROMPTS).Wire schemas for
ManifestEntry,RuntimeContext,Annotation,AnnotationSummary, summarised field-by-field with stable/experimental annotations.Error envelope (
ProblemDetails, RFC 7807) plus the full 22-codeDomscribeErrorCodevocabulary.Stability policy (§7) — frozen surface, additive-minor rules, patch rules, alias migration policy, v2 expectations, and a worked-example table letting any reader predict what counts as breaking.
Sequencing — depends on #32 and #33
This PR ships the spec text. Two sibling sprint tasks land the on-disk surface the spec refers to:
@domscribe/protocolpackage (RCP versioning unit) #32 extracts@domscribe/protocol. Until it lands, the package the banner names exists only in the spec. The spec's "source of truth" reference to@domscribe/protocol@1.0.0is correct once Extract@domscribe/protocolpackage (RCP versioning unit) #32 publishes.Acceptance criteria (issue #35)
docs/rcp/v1.mdexists and renders cleanly on GitHubMCP_TOOLSshape (canonical underscore form)What was NOT done (intentionally)
docs/rfcs/0001-rcp-as-versioning-unit.md. The spec references it; the RFC is principal-eng's deliverable and lands separately.@domscribe/protocolto exist (Extract@domscribe/protocolpackage (RCP versioning unit) #32). A follow-on can addpnpm docs:gen-rcponce the package lands.Test plan
docs/rcp/v1.mdon the PR preview and confirms tables/anchors render@domscribe/protocolpackage (RCP versioning unit) #32 lands: confirm the spec's "exported from@domscribe/protocol" claims match what the package exports