| name | add-spec |
| description | Add a new specification (RFC, IETF draft, or OpenID/Kantara spec) to the OAuth/OIDC dependency graph. Use whenever the user wants to add or update a spec in graph.md — handles the four-place sync (node, edges, click link, README) and verifies references against the source document. |
Add a spec to the graph
graph.md is the source of truth; README.md mirrors it. A spec lives in
four places that must stay in sync. Do all four for every spec.
1. Research the spec (do not guess)
Delegate to the spec-researcher subagent (or fetch the datatracker/openid.net
page yourself) to obtain:
- canonical title,
- latest revision number (for drafts),
- canonical URL (prefer adopted
draft-ietf-... over individual drafts),
- the normative references to specs already in the graph.
Edges must reflect what the document actually references — confirm against the
spec text, not memory. Use the IETF datatracker structured references view
(.../doc/<doc>/references/, which separates normative from informative) for
RFCs and drafts; for openid.net specs use the GitHub source markdown
([@!ref] normative, [@ref]/[@?ref] informative). Draw all normative
references to in-graph specs (completeness); normative only.
2. Pick id, label, and subgraph
- RFCs: id
RFC<number>, label "<Title> (RFC <number>)".
- Drafts / OpenID / Kantara: descriptive PascalCase id
(e.g.
OAuth2_IdentityChaining); label ends in (Draft) if unfinished.
- Place the node in the right
subgraph: OpenID_Connect, OAuth_2_0_RFCs,
JOSE_JWT, Discovery_Metadata, or UMA.
If the spec already exists, this may be an update (e.g. bump a draft to a
newer revision, or repoint a superseded individual draft to the WG version) —
edit in place instead of adding a duplicate node.
3. Edit graph.md (three sections)
- Node — add the
Id["Label"] line inside the chosen subgraph.
- Edges — add
Id --> Dep lines under the matching %% ---- Edges
block, one per normative dependency that exists in the graph.
- Click link — add
click Id "<url>" "<tooltip>"; tooltip matches the
label.
4. Edit README.md
Add a bullet under the matching ### ... category heading describing the spec
in one sentence, consistent with the existing entries.
5. Verify
- Node count must equal click-link count:
grep -cE '^\s+[A-Za-z0-9_]+\["' graph.md vs grep -cE '^\s+click ' graph.md.
- No edge may reference an undefined node id, except the four allowlisted ACE
externals (
RFC7252, RFC8152, RFC8392, RFC8747).
- Run the markdown linter (
mdlinter skill or markdownlint-cli2) and fix.
