[robert-hebel-sb]

Lessons from adding AsyncAPI 3.1.0 (#5261, #5262, #5263, #5264) and its review, folded into the spec-version skills. Independent of those PRs; based on main.

Changes

add-spec-version/scripts/verify-urls.mjs:

• GitHub directory links (bindings/blob/master/kafka#server) are checked against the directory's README.md, which GitHub renders on that page. They were reported BROKEN before; a directory without a README (bindings/.../sns) still is.
• An unbalanced ) ends a URL, so a markdown table cell glued to a link ([x](url)|Next) is no longer part of it.
• --new-only (with --diff) skips URLs that also sit on a removed line of the same file, i.e. links carried over by lines that were only rewritten.
• --list prints the collected URLs without fetching. The smoke test covers the new options offline.
• On the first AsyncAPI 3.1 LS commit (vs. its base) the checker went from 66 BROKEN to 11, all real pre-existing ones, and 0 with --new-only.

/add-spec-version:

• Field map: CHANGED-TEXT rows for prose-only changes (AsyncAPI 3.1's Operation messages note was missed until review) and DECIDE rows for disagreements between a binding README and the JSON Schema, resolved at the checkpoint.
• Gates: compare against the PR base, fail only on new findings (REDEFINED, broken links), require adapter tests to run (asyncapi-json-3 ran none), keep other specs' negative tests unchanged, run the LS reviewer on committed work and handle rejected or decision-needing findings explicitly.
• Extend checklists: bindings that exist only from a version, plain nested binding objects, version comments, fixture building, apidom-reference README sections for an undocumented family, version-scoped completion values and docs, renamed range files with their identifiers, real version-pattern rules, the empty-document default version.

Other skills:

• /add-parser-adapter, /add-reference-support: negative tests stay; check that tests run; keep a previous-version media type check.
• /update-ls-config: AsyncAPI v3.x doc anchors are server-rendered (checkable), binding links point at README files, range rules need a number guard, +1 codes for a second rule.
• /review-ls-changes: review against the base and recorded decisions, diff the prose, treat binding READMEs as the source, verify suggested links; three new key lessons.
• FOLLOW-UPS.md: progress on 2.10 and a new section 5 with the pre-existing problems found, including AsyncAPI 3 Server.pathName, which reads pathName while the refractor stores pathname.

Lessons from the #5264 review (8 comments, then 4 more in a second round):

• /update-ls-config: rules for fields that can hold references list the element name and the namespace's referenced-element value, so they pass after dereferencing ([['server', 'channel-servers']]; [['reference']] alone failed on dereferenced documents). Values that depend on a parent object's field use a parent condition path (parent.parent.action for the ROS 2 role); the dependent rules report any wrong value and the general rule runs only when the other field has none of their values (two apilintKeysContainsValue conditions), so each invalid value gets one diagnostic. Why negate and apilintFieldValueOrArray don't work here (missing paths fail before negate; root() doesn't know asyncApi3, added to FOLLOW-UPS 2.1). No --type rule next to --equals; renumber codes when a field's first rule is dropped. Messages read as diagnostics (the full empty-binding sentence, ... Its name is reserved for future use.), name an object only if the namespace has an element for it, and stay generic for fields accepting references and dereferenced objects ('servers' must be an array). Fixture locations per test kind, and running one test file with a temporary mocha config.
• /review-ls-changes: four new key lessons, checklist items 4.5/4.6 extended, and a snippet that finds --type rules next to --equals.
• /add-namespace: set referenced-element to the target's element name, the same in every visitor.
• FOLLOW-UPS.md: 5.8 (ROS 2 role vs. action) implemented in the review follow-up; the binding README's Pose example that contradicts its field table is treated as an upstream error (the table wins, also in /add-spec-version and /review-ls-changes); new 5.10 for AsyncAPI 3 referenced-element values that aren't element names (channel-servers, operation-reply-address vs. operationReplyAddress).

Verification

• bash .claude/skills/add-spec-version/scripts/test/smoke.sh: passed
• verify-urls.mjs on packages/apidom-ls/src/config/asyncapi/server-bindings (main): only the SNS directory link without a README is BROKEN
• documented diff commands checked against the AsyncAPI 3.0.0 and 3.1.0 markdown
• --type/--equals snippet run on the reviewed feat(ls): add support for AsyncAPI 3.1.0 #5264 commit (de8430e1b): flags both ROS 2 role--type.ts files
• parent condition paths and [['server', 'channel-servers']] checked against checkConditions, apilintElementOrClass and the AsyncAPI 3 dereference visitor; the feat(ls): add support for AsyncAPI 3.1.0 #5264 follow-ups pass the apidom-ls suite (666 tests); the one-diagnostic-per-value behaviour was also checked with an invalid action, a missing action and a binding under components

🤖 Generated with Claude Code