feat(adapters): ship discoverable schemas for every write endpoint#41
feat(adapters): ship discoverable schemas for every write endpoint#41khaliqgant wants to merge 1 commit intomainfrom
Conversation
📝 WalkthroughWalkthroughAdds a discovery framework: rules, metadata contracts, helper builders, generation/verification scripts, per-adapter docs, schemas and examples for write endpoints, package publishing config, code routing updates (Notion, Teams), and tests. Root test now verifies discovery artifacts before running other tests. ChangesWriteback discovery system
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 865a349548
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| endpoint('/slack/channels/{channelId}/messages/new.json', 'Post Slack message', 'Posts a top-level Slack message.', [], slackMessageProps(), { text: 'Replace example message text.' }), | ||
| endpoint('/slack/channels/{channelId}/messages/{messageTs}/replies/new.json', 'Post Slack thread reply', 'Posts a reply in a Slack thread.', [], { ...slackMessageProps(), reply_broadcast: bool('Whether Slack should also broadcast the reply to the channel.') }, { text: 'Replace example reply text.' }), |
There was a problem hiding this comment.
For the Slack message and reply templates, the generated schemas mark no fields as required, so {} validates against new.schema.json; however parseMessagePayload rejects the same object unless it contains text, blocks, or attachments (packages/slack/src/writeback.ts:148-153). Agents that rely on these discovery schemas can therefore produce documents that pass discovery validation but fail writeback immediately, so these schemas should express the content requirement, e.g. with anyOf over those fields.
Useful? React with 👍 / 👎.
| fields: obj('Jira issue fields.', { | ||
| project: obj('Project object. Usually includes `key` or `id`.'), | ||
| summary: str('Issue summary.'), | ||
| issuetype: obj('Issue type object. Usually includes `name` or `id`.'), |
There was a problem hiding this comment.
The Jira issue-create schema only requires the top-level fields object, so a document such as { "fields": {} } is valid per discovery, but the resolver rejects it because fields.project, fields.summary, and fields.issuetype are mandatory (packages/jira/src/writeback.ts:95-103). This makes the published schema under /jira/issues/new.schema.json under-specify the accepted write document; add nested required constraints for those fields so schema-driven clients don't generate writebacks that fail.
Useful? React with 👍 / 👎.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 16
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (10)
packages/zendesk/discovery/zendesk/.adapter.md (1)
11-23:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd field-level contract details for each write endpoint.
The adapter doc currently lists routes but does not specify endpoint fields (including required vs optional), which weakens discoverability for agent-authored writes.
As per coding guidelines, each
packages/**/.adapter.mdmust include “field-level descriptions” and “required vs optional field specifications”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/zendesk/discovery/zendesk/.adapter.md` around lines 11 - 23, Update the .adapter.md to include field-level contract details for each write endpoint: for /zendesk/tickets/{ticketId}/comments/new.json (refer to /zendesk/tickets/{ticketId}/comments/new.schema.json), /zendesk/tickets/new.json (refer to /zendesk/tickets/new.schema.json), and /zendesk/users/new.json (refer to /zendesk/users/new.schema.json) — enumerate each request body field name, type, description, whether it is required or optional, and give a short example value or pointer to the existing new.example.json; ensure required-vs-optional listings match the JSON schema definitions and add any notes about field constraints (e.g., max length, enums) so agents can author valid writes.packages/pipedrive/discovery/pipedrive/.adapter.md (1)
1-24:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftMissing required contract detail sections in adapter root doc
This
.adapter.mdstill lacks field-level write payload descriptions, required-vs-optional breakdowns, and provider enum values per write endpoint, which are required for discoverability parity.As per coding guidelines "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/.adapter.md` around lines 1 - 24, The adapter root doc is missing per-endpoint contract details: for each write endpoint (e.g., /pipedrive/deals/new.json, /pipedrive/persons/new.json, /pipedrive/organizations/new.json, /pipedrive/activities/new.json) add a field-level payload section that enumerates each field name and type, a clear required vs optional list, allowed/provider enum values where applicable, and an example payload reference (pointing to the existing new.example.json); update the adapter README (.adapter.md) to include these sections under each write endpoint so the doc mirrors the schema files and satisfies the discoverability contract.packages/jira/discovery/jira/.adapter.md (1)
1-23:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftAdapter root doc is missing required field contract details
This file documents paths and endpoint list, but it does not yet include field-level payload descriptions, required-vs-optional field specs, and provider enum values per write endpoint.
As per coding guidelines "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/jira/discovery/jira/.adapter.md` around lines 1 - 23, The adapter README (.adapter.md) is missing the required field-level payload descriptions, required-vs-optional specs, and provider enum values for each write endpoint; update the document to include, for each write endpoint (/jira/issues/new.json, /jira/issues/{issueIdOrKey}/comments/new.json, /jira/projects/new.json), a subsection that lists every payload field (matching the corresponding schema file e.g., /jira/issues/new.schema.json, /jira/issues/{...}/comments/new.schema.json, /jira/projects/new.schema.json), mark which fields are required vs optional, provide short descriptions for each field, and enumerate any provider-specific enum values (e.g., project types, issue types, comment visibility) with examples (point to the related new.example.json files where available) so the adapter meets the documented discovery requirements.packages/gitlab/discovery/gitlab/.adapter.md (1)
1-22:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftInclude required write-field contract details in this adapter spec.
The current document omits field-level descriptions, required-vs-optional breakdown, and provider enum values for the write endpoints.
As per coding guidelines: "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/gitlab/discovery/gitlab/.adapter.md` around lines 1 - 22, The adapter spec .adapter.md is missing field-level descriptions, required vs optional flags, and provider enum values for the write endpoints; update the GitLab adapter doc to add detailed write-field contract sections for each write route (/gitlab/projects/{projectPath}/merge_requests/{mergeRequestIid}/discussions/new.json and /gitlab/projects/{projectPath}/issues/{issueIid}/comments/new.json), referencing their schema files (new.schema.json) and examples (new.example.json); for each field listed in the schema include a short description, whether it is required or optional, allowed types/values, and any provider enum values so the document complies with the packages/**/.adapter.md guideline.packages/intercom/discovery/intercom/.adapter.md (1)
1-22:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftDocument field-level write contracts in
.adapter.md(required by repo rule).The write endpoints are listed, but this doc still lacks field-level descriptions, required-vs-optional specs, and provider enum values.
As per coding guidelines: "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/intercom/discovery/intercom/.adapter.md` around lines 1 - 22, The .adapter.md for the Intercom adapter is missing field-level write contracts: for each write endpoint listed (paths /intercom/conversations/new.json, /intercom/contacts/new.json, /intercom/companies/new.json) add per-field descriptions, indicate which fields are required vs optional, and list any provider enum values; derive the field names and types from the corresponding schema files (/intercom/*/new.schema.json) and optionally show canonical example values from the matching new.example.json files, and include a short note describing any validation rules or default behavior used by the adapter (e.g., auto-generated IDs or timestamp handling).packages/notion/discovery/notion/.adapter.md (1)
1-21:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftAdd mandatory field-level write contract details to
.adapter.md.This file needs explicit field-level descriptions, required-vs-optional specs, and provider enum values for the documented write path.
As per coding guidelines: "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/notion/discovery/notion/.adapter.md` around lines 1 - 21, Update the Notion adapter README (.adapter.md) to include a mandatory field-level write contract for the `/notion/databases/{databaseId}/pages/new.json` endpoint: add a dedicated section that enumerates every field expected by the `new.schema.json` (field name, type, description), clearly mark which fields are required vs optional, and list allowed provider enum values (exact strings) used by the adapter; reference the `new.schema.json` and `new.example.json` as canonical sources and ensure the write endpoint table links to this new field-level section so agents can programmatically discover required shapes and enums.packages/hubspot/discovery/hubspot/.adapter.md (1)
1-24:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftAdd the required field-contract section to this adapter doc.
This file is missing explicit field-level descriptions, required-vs-optional field specs, and provider enum values for the listed write endpoints.
As per coding guidelines: "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/hubspot/discovery/hubspot/.adapter.md` around lines 1 - 24, Add a "Field contract" section to this adapter doc that enumerates the request body schema for each write endpoint (/hubspot/contacts/new.json, /hubspot/companies/new.json, /hubspot/deals/new.json, /hubspot/tickets/new.json): for each endpoint list every field name, type, brief description, whether it is required or optional, and any allowed enum/provider values (e.g., owner, lifecycleStage, dealstage, ticketStatus) and example values; ensure the section references the corresponding schema files (/hubspot/*/new.schema.json) and includes provider enum values for fields that accept limited choices so readers and agents can validate and construct correct payloads.packages/teams/discovery/teams/.adapter.md (1)
1-23:⚠️ Potential issue | 🟠 Major | 🏗️ Heavy liftExpand this adapter doc with required field-level contract details.
The doc has overview/read-only/table, but it does not include field-level descriptions, required vs optional field specs, or provider enum values for these write routes.
As per coding guidelines: "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.mdin its discovery tree with overview, read-only mount summary, write endpoint table, field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/teams/discovery/teams/.adapter.md` around lines 1 - 23, The adapter README (.adapter.md) is missing field-level contract details for the write routes; update the Teams adapter doc to add per-endpoint field descriptions, required vs optional flags, and allowed provider enum values for every write endpoint listed (the three routes that reference new.schema.json and their corresponding new.example.json files). For each write endpoint (e.g., the channel message, reply, and chat message new.json routes) include a subsection that enumerates each schema property, its type, whether it’s required, allowed enum values (provider IDs), default/validation rules, and an example snippet reference to the matching new.example.json; also link or quote the exact new.schema.json property names so reviewers can verify the contract.packages/asana/discovery/asana/.adapter.md (1)
11-24:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd required contract details to the adapter doc.
The write endpoint section currently lists paths/schemas, but it does not include field-level descriptions, required-vs-optional field specs, or provider enum values in this
.adapter.md, which makes the discovery contract incomplete for agents.As per coding guidelines:
packages/**/.adapter.mdmust include “field-level descriptions, required vs optional field specifications, and provider enum values.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/asana/discovery/asana/.adapter.md` around lines 11 - 24, The adapter doc's write-endpoint list lacks field-level descriptions, required vs optional markers, and provider enum values; update the entries for /asana/tasks/new.json (asana/tasks/new.schema.json), /asana/projects/new.json (asana/projects/new.schema.json), /asana/sections/new.json (asana/sections/new.schema.json) and /asana/projects/{projectId}/sections/new.json (asana/projects/{projectId}/sections/new.schema.json) to include for each endpoint: a list of all top-level and nested fields pulled from the matching schema with a one-line description, an explicit "Required" vs "Optional" designation for each field, and any provider enum values and their allowed strings; make the format consistent with other packages' .adapter.md (field name, type, requiredness, description, allowed enum values) so agents can discover the contract directly.packages/salesforce/discovery/salesforce/.adapter.md (1)
1-26:⚠️ Potential issue | 🟠 Major | ⚡ Quick winMissing required discovery sections in
.adapter.md.This doc currently lacks endpoint field-level descriptions, required-vs-optional field specs, and provider enum values, which are required for adapter discovery docs.
As per coding guidelines: "
packages/**/.adapter.md: Each adapter must ship<adapter>/.adapter.md... with ... field-level descriptions, required vs optional field specifications, and provider enum values".🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/salesforce/discovery/salesforce/.adapter.md` around lines 1 - 26, The .adapter.md is missing the required discovery details: for each write endpoint (refer to `/salesforce/accounts/new.schema.json`, `/salesforce/contacts/new.schema.json`, `/salesforce/opportunities/new.schema.json`, `/salesforce/leads/new.schema.json`, `/salesforce/cases/new.schema.json`) add field-level descriptions for every property, mark each property as required vs optional (match the `required` arrays in those schema files), and enumerate any provider enum values (e.g., provider fields or picklists referenced by the schemas) with their allowed values; update the read-only endpoint entries (e.g., `/salesforce/accounts/<accountId>.json`) to include important response fields and which are guaranteed vs nullable.
🟡 Minor comments (18)
packages/zendesk/discovery/zendesk/tickets/new.example.json-1-3 (1)
1-3:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winExample is incomplete—consider including a description for a more realistic payload.
The schema only requires
subject, so the current example is technically valid. However, the schema also defines optionaldescriptionandcommentfields. The example should demonstrate a more complete, realistic ticket creation payload, since a ticket with just a subject and no body is rarely useful in practice.✏️ Suggested example update
{ - "subject": "Replace example ticket subject" + "subject": "Replace example ticket subject", + "description": "Replace example ticket description" }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/zendesk/discovery/zendesk/tickets/new.example.json` around lines 1 - 3, Update the example JSON payload to include realistic optional fields so it demonstrates a typical ticket creation: keep "subject" but add a "description" string (the ticket body) and a "comment" object or array (as defined by the schema) with a sample author/body/status if applicable; ensure field names match the schema (subject, description, comment) and use plausible sample text to make the example more useful for users.packages/asana/discovery/asana/projects/new.example.json-1-4 (1)
1-4:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winInclude
teamfield in the example and use consistent placeholder format.The Asana API requires a
teamGID when creating a project in an organization workspace, but the schema marksteamas optional and the example omits it entirely. This will cause failures for agents working with organization workspaces. Additionally, theworkspaceplaceholder value"1200000000000000"appears to be a literal GID rather than a placeholder (unlikename), which may confuse agents into treating it as a valid value to use directly.✏️ Suggested example update
{ "name": "Replace example project name", - "workspace": "1200000000000000" + "workspace": "Replace with your workspace GID", + "team": "Replace with your team GID" }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/asana/discovery/asana/projects/new.example.json` around lines 1 - 4, Update the example JSON to include a "team" field and make placeholders consistent: add a "team" property (e.g., "<team_gid>") alongside "workspace" and change the "workspace" value to a placeholder format (e.g., "<workspace_gid>") instead of a literal GID, keeping the "name" placeholder style intact so fields "name", "workspace", and "team" clearly indicate they are placeholders rather than real IDs.packages/zendesk/discovery/zendesk/.adapter.md-12-17 (1)
12-17:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winMarkdown table should be surrounded by blank lines.
markdownlintwarning MD058 is triggered here; add a blank line before and after the table block.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/zendesk/discovery/zendesk/.adapter.md` around lines 12 - 17, Add a blank line immediately before and after the Markdown table that begins with the header "| Path | Schema | What it does |" so the table is separated by empty lines from surrounding text (fixing markdownlint MD058); update the block in the .adapter.md file to ensure there is one empty line above the table header and one empty line after the final table row.packages/clickup/discovery/clickup/.adapter.md-12-19 (1)
12-19:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdownlint MD058 around the table block.
Please add blank lines around this table to satisfy the linter warning.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/clickup/discovery/clickup/.adapter.md` around lines 12 - 19, Add blank lines before and after the markdown table that starts with "| Path | Schema | What it does |" so the table is separated from surrounding text; modify the .adapter.md content to insert an empty line immediately above the table header and another empty line immediately below the last table row (the row ending with "Creates a folder inside a ClickUp space.") to satisfy MD058.packages/github/discovery/github/.adapter.md-12-15 (1)
12-15:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAddress MD058 for the write-endpoints table.
Insert blank lines before and after the table to clear markdownlint.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/github/discovery/github/.adapter.md` around lines 12 - 15, The markdown table for the write-endpoint (the row containing `/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.json`) is missing blank lines before and after it, triggering MD058; edit the .adapter.md content and insert a single blank line directly above the table header and another blank line directly below the table end (after the closing `</diff>`-style table block) so the table is separated from surrounding text.packages/linear/discovery/linear/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdownlint MD058 table spacing at Line 12.
Add a blank line before the table block.
🧹 Suggested diff
Write endpoints: + | Path | Schema | What it does | |---|---|---|🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/linear/discovery/linear/.adapter.md` around lines 11 - 13, The Markdown file has a table starting at the block that begins with "Write endpoints:" which violates MD058 because there is no blank line before the table; fix it by inserting a single blank line immediately before the table header (the line with "| Path | Schema | What it does |") so the table block is separated from the preceding paragraph or heading.packages/slack/discovery/slack/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdownlint MD058 table spacing at Line 12.
Add a blank line before the table declaration.
🧹 Suggested diff
Write endpoints: + | Path | Schema | What it does | |---|---|---|🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/slack/discovery/slack/.adapter.md` around lines 11 - 13, The Markdown file's table under the "Write endpoints:" header violates MD058 because there is no blank line before the table; insert a single blank line immediately before the table header line that starts with "| Path | Schema | What it does |" so the table is separated from the preceding paragraph and passes markdownlint; no other changes to table content are required.packages/pipedrive/discovery/pipedrive/.adapter.md-3-3 (1)
3-3:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winRoute capability text is inaccurate
Line 3 states the adapter has create-and-update writeback routes, but the documented endpoints in this file are create-only (
new.json). Please either remove “updating” or document the update endpoints.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/.adapter.md` at line 3, The capability sentence currently claims "creating and updating" but the documented endpoints are create-only (`new.json`); either remove the word "updating" from the sentence that begins "The Pipedrive adapter exposes deals, persons, organizations, and activities under `/pipedrive`..." or add the missing update endpoints to the doc (list the update routes and paths, e.g., the corresponding update/edit endpoints such as `update.json`/`edit.json` or `/pipedrive/{resource}/:id` update routes) and ensure each resource (deals, persons, organizations, activities) includes the exact update endpoint names and HTTP method to match the implementation.packages/jira/discovery/jira/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdown table spacing (MD058)
Please add a blank line before the table under
Write endpoints:.Suggested patch
Write endpoints: + | Path | Schema | What it does | |---|---|---|🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/jira/discovery/jira/.adapter.md` around lines 11 - 13, The markdown under "Write endpoints:" is missing a blank line before the table causing MD058; open .adapter.md, find the "Write endpoints:" heading/text and insert a single blank line immediately after it and before the table opening pipe row so the table is separated from the heading (ensuring the header "Write endpoints:" and the table start line "| Path | Schema | What it does |" have one blank line between them).packages/pipedrive/discovery/pipedrive/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdown table spacing (MD058)
Add a blank line between
Write endpoints:and the table to satisfy markdownlint.Suggested patch
Write endpoints: + | Path | Schema | What it does | |---|---|---|🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/.adapter.md` around lines 11 - 13, Add a blank line between the "Write endpoints:" heading and the following table to satisfy markdownlint rule MD058; edit the .adapter.md file so the line containing Write endpoints: is followed by an empty line before the pipe-delimited table (the table starting with "| Path | Schema | What it does |") to restore correct markdown spacing.packages/intercom/discovery/intercom/.adapter.md-10-12 (1)
10-12:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd blank line before the table (MD058).
Current table placement will trigger markdownlint warning MD058.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/intercom/discovery/intercom/.adapter.md` around lines 10 - 12, Insert a blank line between the "Write endpoints:" heading and the table that begins with "| Path | Schema | What it does |" to satisfy markdownlint rule MD058; update the section containing "Write endpoints:" so there is an empty line immediately before the table start.packages/gitlab/discovery/gitlab/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd blank line before the markdown table (MD058).
The current table placement violates markdownlint’s blanks-around-tables rule.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/gitlab/discovery/gitlab/.adapter.md` around lines 11 - 13, Markdown table in .adapter.md is missing a blank line before it, violating MD058; insert a single blank line immediately before the table header line starting with "| Path | Schema | What it does |" so the table is separated from the preceding text, then save the file to satisfy the blanks-around-tables rule.packages/notion/discovery/notion/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix table spacing to satisfy MD058.
Please add a blank line before the table header row.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/notion/discovery/notion/.adapter.md` around lines 11 - 13, The Markdown file's table under the "Write endpoints:" heading violates MD058 because there is no blank line before the table header; edit the .adapter.md content to insert a single blank line immediately before the table header row (the line starting with "| Path | Schema | What it does |") so there is an empty line between the "Write endpoints:" paragraph and the table header.packages/hubspot/discovery/hubspot/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdown table spacing for lint compliance (MD058).
Add a blank line before the table to satisfy markdownlint.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/hubspot/discovery/hubspot/.adapter.md` around lines 11 - 13, The Markdown file contains a table immediately after the "Write endpoints:" heading which triggers MD058; insert a single blank line between the "Write endpoints:" heading and the table (the line starting with "| Path | Schema | What it does |") so there is an empty line before the table to satisfy markdownlint.packages/teams/discovery/teams/.adapter.md-11-13 (1)
11-13:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix table blank-line formatting (MD058).
Insert a blank line before the table header to satisfy markdownlint.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/teams/discovery/teams/.adapter.md` around lines 11 - 13, The markdown table under the "Write endpoints:" header lacks a preceding blank line which triggers MD058; insert a single blank line between the "Write endpoints:" line and the table header ("| Path | Schema | What it does |") so the table is separated from the preceding paragraph/header and conforms to markdownlint rules.packages/asana/discovery/asana/.adapter.md-11-17 (1)
11-17:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix markdownlint MD058 around the write-endpoints table.
Add a blank line before and after the table block so this file stays lint-clean.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/asana/discovery/asana/.adapter.md` around lines 11 - 17, The markdown table under the "Write endpoints:" heading violates MD058 because it lacks surrounding blank lines; open the file and add a single blank line immediately before the line that starts the table header ("| Path | Schema | What it does |") and a single blank line immediately after the last table row ("| `/asana/projects/{projectId}/sections/new.json` ... |"), so the table block is separated from surrounding text and passes markdownlint; ensure you only add blank lines and do not alter the table content or headings.packages/pipedrive/discovery/pipedrive/activities/new.schema.json-26-33 (1)
26-33:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winEnforce HH:MM format for
due_timeandduration.These fields are documented as HH:MM, but the schema currently accepts any string.
💡 Proposed fix
"due_time": { "type": "string", + "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Due time in HH:MM form." }, "duration": { "type": "string", + "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$", "description": "Duration in HH:MM form." },🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/activities/new.schema.json` around lines 26 - 33, The schema currently allows any string for the due_time and duration properties; update both properties in new.schema.json to validate HH:MM (24-hour) format by adding a "pattern" that enforces hours 00–23 and minutes 00–59 (for example ^([01]\d|2[0-3]):[0-5]\d$) to the definitions of "due_time" and "duration" and optionally augment the "description" to indicate the enforced pattern; ensure you modify the objects named "due_time" and "duration" in the schema (not other fields).packages/salesforce/discovery/salesforce/.adapter.md-12-15 (1)
12-15:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd blank lines around the write-endpoints table.
The table starts immediately after “Write endpoints:” and triggers MD058 (
blanks-around-tables).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/salesforce/discovery/salesforce/.adapter.md` around lines 12 - 15, The markdown table under the "Write endpoints:" heading in .adapter.md lacks blank lines around it and triggers MD058; add a blank line after the "Write endpoints:" line and another blank line after the table (so there is an empty line before the table and an empty line after the table block containing the `/salesforce/accounts/new.json` row) to satisfy the blanks-around-tables rule.
🧹 Nitpick comments (4)
packages/pipedrive/discovery/pipedrive/deals/new.example.json (1)
1-3: 💤 Low valueExample structure looks valid, but consider standardizing placeholder patterns across adapters.
The instructional placeholder "Replace example deal title" clearly signals to LLM agents that this value should be replaced. However, placeholder patterns vary across adapters in this PR:
- Some use "Replace example [resource] [field]" (this file, ClickUp lists)
- Some use "Replace example [field] [description]" (Linear/GitLab/Zendesk comments, GitHub reviews)
- Some use realistic examples (Pipedrive persons: "Ada Lovelace", organizations: "Example Inc")
For the stated use case of LLM agents discovering write shapes, consistent placeholder conventions would reduce ambiguity.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/deals/new.example.json` around lines 1 - 3, The example value for the "title" field uses a different placeholder pattern; update the value in new.example.json so it matches the project's chosen placeholder convention (e.g., "Replace example deal title") or whichever standardized pattern you decide ("Replace example [resource] [field]") and ensure this file's "title" placeholder conforms to that pattern to keep placeholders consistent across adapters.packages/pipedrive/discovery/pipedrive/organizations/new.example.json (1)
1-3: ⚡ Quick winInconsistent placeholder pattern within Pipedrive adapter.
This example uses realistic data ("Example Inc") while the sibling
deals/new.example.jsonin the same Pipedrive adapter uses an instructional placeholder ("Replace example deal title"). For consistency and clarity to LLM agents, consider using the same pattern across all Pipedrive examples.♻️ Align with "Replace example..." pattern
{ - "name": "Example Inc" + "name": "Replace example organization name" }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/organizations/new.example.json` around lines 1 - 3, The example JSON uses a realistic value for the "name" field which is inconsistent with the sibling example pattern; update the "name" property's value in this organizations example to match the instructional placeholder pattern used elsewhere (e.g., use "Replace example organization name" similar to the "Replace example deal title" pattern in the deals example) so examples are consistent across the Pipedrive adapter.packages/pipedrive/discovery/pipedrive/persons/new.example.json (1)
1-3: ⚡ Quick winInconsistent placeholder pattern within Pipedrive adapter.
The Pipedrive adapter now has three different example patterns:
deals/new.example.json: "Replace example deal title" (instructional)organizations/new.example.json: "Example Inc" (fictional realistic)persons/new.example.json: "Ada Lovelace" (historical realistic)For LLM agents discovering write shapes, consistent patterns within an adapter improve clarity and reduce the cognitive load of determining which values are placeholders vs. valid examples.
♻️ Align with "Replace example..." pattern
{ - "name": "Ada Lovelace" + "name": "Replace example person name" }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/pipedrive/discovery/pipedrive/persons/new.example.json` around lines 1 - 3, The persons example uses a realistic historical name ("Ada Lovelace") which is inconsistent with the adapter's other examples; update the value for the JSON key "name" in the persons example to follow the instructional placeholder pattern used elsewhere (e.g., change it to "Replace example person name") so all write-shape examples in the Pipedrive adapter consistently indicate placeholders rather than concrete examples.packages/teams/test/teams-adapter.test.ts (1)
229-235: ⚡ Quick winAdd
resolveWritebackassertions for reply/chatnew.jsonaliases too.This test now covers channel-message alias routing, but the same alias behavior for replies and chats should be asserted in this block to prevent regressions.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/teams/test/teams-adapter.test.ts` around lines 229 - 235, The test only asserts channel-message alias routing for resolveWriteback; add equivalent assertions to cover reply and chat "new.json" aliases to prevent regressions. Invoke resolveWriteback with the reply alias path '/teams/team-1/channels/channel-1/messages/message-1/replies/new.json' and the chat alias path '/chats/chat-1/messages/new.json' (or the project's canonical reply/chat alias formats) and assert the returned object's objectType, objectId and url fields match expected values (e.g., objectType 'message', objectId reflecting reply/chat IDs, and url pointing to the appropriate Graph API endpoints). Update the same test block so resolveWriteback is exercised for channel new, reply new, and chat new aliases.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 8fc2ac4a-188a-4aaa-8ff1-52dc2e98b5cc
📒 Files selected for processing (124)
.claude/rules/adapter-writeback-discovery.mdAGENTS.mdpackage.jsonpackages/asana/discovery/asana/.adapter.mdpackages/asana/discovery/asana/projects/new.example.jsonpackages/asana/discovery/asana/projects/new.schema.jsonpackages/asana/discovery/asana/projects/{projectId}/sections/new.example.jsonpackages/asana/discovery/asana/projects/{projectId}/sections/new.schema.jsonpackages/asana/discovery/asana/sections/new.example.jsonpackages/asana/discovery/asana/sections/new.schema.jsonpackages/asana/discovery/asana/tasks/new.example.jsonpackages/asana/discovery/asana/tasks/new.schema.jsonpackages/asana/package.jsonpackages/clickup/discovery/clickup/.adapter.mdpackages/clickup/discovery/clickup/folders/{folderId}/lists/new.example.jsonpackages/clickup/discovery/clickup/folders/{folderId}/lists/new.schema.jsonpackages/clickup/discovery/clickup/lists/{listId}/tasks/new.example.jsonpackages/clickup/discovery/clickup/lists/{listId}/tasks/new.schema.jsonpackages/clickup/discovery/clickup/spaces/{spaceId}/folders/new.example.jsonpackages/clickup/discovery/clickup/spaces/{spaceId}/folders/new.schema.jsonpackages/clickup/discovery/clickup/spaces/{spaceId}/lists/new.example.jsonpackages/clickup/discovery/clickup/spaces/{spaceId}/lists/new.schema.jsonpackages/clickup/discovery/clickup/tasks/{taskId}/comments/new.example.jsonpackages/clickup/discovery/clickup/tasks/{taskId}/comments/new.schema.jsonpackages/clickup/package.jsonpackages/github/discovery/github/.adapter.mdpackages/github/discovery/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.example.jsonpackages/github/discovery/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.schema.jsonpackages/github/package.jsonpackages/gitlab/discovery/gitlab/.adapter.mdpackages/gitlab/discovery/gitlab/projects/{projectPath}/issues/{issueIid}/comments/new.example.jsonpackages/gitlab/discovery/gitlab/projects/{projectPath}/issues/{issueIid}/comments/new.schema.jsonpackages/gitlab/discovery/gitlab/projects/{projectPath}/merge_requests/{mergeRequestIid}/discussions/new.example.jsonpackages/gitlab/discovery/gitlab/projects/{projectPath}/merge_requests/{mergeRequestIid}/discussions/new.schema.jsonpackages/gitlab/package.jsonpackages/hubspot/discovery/hubspot/.adapter.mdpackages/hubspot/discovery/hubspot/companies/new.example.jsonpackages/hubspot/discovery/hubspot/companies/new.schema.jsonpackages/hubspot/discovery/hubspot/contacts/new.example.jsonpackages/hubspot/discovery/hubspot/contacts/new.schema.jsonpackages/hubspot/discovery/hubspot/deals/new.example.jsonpackages/hubspot/discovery/hubspot/deals/new.schema.jsonpackages/hubspot/discovery/hubspot/tickets/new.example.jsonpackages/hubspot/discovery/hubspot/tickets/new.schema.jsonpackages/hubspot/package.jsonpackages/intercom/discovery/intercom/.adapter.mdpackages/intercom/discovery/intercom/companies/new.example.jsonpackages/intercom/discovery/intercom/companies/new.schema.jsonpackages/intercom/discovery/intercom/contacts/new.example.jsonpackages/intercom/discovery/intercom/contacts/new.schema.jsonpackages/intercom/discovery/intercom/conversations/new.example.jsonpackages/intercom/discovery/intercom/conversations/new.schema.jsonpackages/intercom/package.jsonpackages/jira/discovery/jira/.adapter.mdpackages/jira/discovery/jira/issues/new.example.jsonpackages/jira/discovery/jira/issues/new.schema.jsonpackages/jira/discovery/jira/issues/{issueIdOrKey}/comments/new.example.jsonpackages/jira/discovery/jira/issues/{issueIdOrKey}/comments/new.schema.jsonpackages/jira/discovery/jira/projects/new.example.jsonpackages/jira/discovery/jira/projects/new.schema.jsonpackages/jira/package.jsonpackages/linear/discovery/linear/.adapter.mdpackages/linear/discovery/linear/issues/new.example.jsonpackages/linear/discovery/linear/issues/new.schema.jsonpackages/linear/discovery/linear/issues/{issueId}/comments/new.example.jsonpackages/linear/discovery/linear/issues/{issueId}/comments/new.schema.jsonpackages/linear/package.jsonpackages/notion/discovery/notion/.adapter.mdpackages/notion/discovery/notion/databases/{databaseId}/pages/new.example.jsonpackages/notion/discovery/notion/databases/{databaseId}/pages/new.schema.jsonpackages/notion/package.jsonpackages/notion/src/__tests__/writeback.test.tspackages/notion/src/writeback.tspackages/pipedrive/discovery/pipedrive/.adapter.mdpackages/pipedrive/discovery/pipedrive/activities/new.example.jsonpackages/pipedrive/discovery/pipedrive/activities/new.schema.jsonpackages/pipedrive/discovery/pipedrive/deals/new.example.jsonpackages/pipedrive/discovery/pipedrive/deals/new.schema.jsonpackages/pipedrive/discovery/pipedrive/organizations/new.example.jsonpackages/pipedrive/discovery/pipedrive/organizations/new.schema.jsonpackages/pipedrive/discovery/pipedrive/persons/new.example.jsonpackages/pipedrive/discovery/pipedrive/persons/new.schema.jsonpackages/pipedrive/package.jsonpackages/salesforce/discovery/salesforce/.adapter.mdpackages/salesforce/discovery/salesforce/accounts/new.example.jsonpackages/salesforce/discovery/salesforce/accounts/new.schema.jsonpackages/salesforce/discovery/salesforce/cases/new.example.jsonpackages/salesforce/discovery/salesforce/cases/new.schema.jsonpackages/salesforce/discovery/salesforce/contacts/new.example.jsonpackages/salesforce/discovery/salesforce/contacts/new.schema.jsonpackages/salesforce/discovery/salesforce/leads/new.example.jsonpackages/salesforce/discovery/salesforce/leads/new.schema.jsonpackages/salesforce/discovery/salesforce/opportunities/new.example.jsonpackages/salesforce/discovery/salesforce/opportunities/new.schema.jsonpackages/salesforce/package.jsonpackages/slack/discovery/slack/.adapter.mdpackages/slack/discovery/slack/channels/{channelId}/messages/new.example.jsonpackages/slack/discovery/slack/channels/{channelId}/messages/new.schema.jsonpackages/slack/discovery/slack/channels/{channelId}/messages/{messageTs}/reactions/new.example.jsonpackages/slack/discovery/slack/channels/{channelId}/messages/{messageTs}/reactions/new.schema.jsonpackages/slack/discovery/slack/channels/{channelId}/messages/{messageTs}/replies/new.example.jsonpackages/slack/discovery/slack/channels/{channelId}/messages/{messageTs}/replies/new.schema.jsonpackages/slack/package.jsonpackages/teams/discovery/teams/.adapter.mdpackages/teams/discovery/teams/chats/{chatId}/messages/new.example.jsonpackages/teams/discovery/teams/chats/{chatId}/messages/new.schema.jsonpackages/teams/discovery/teams/{teamId}/channels/{channelId}/messages/new.example.jsonpackages/teams/discovery/teams/{teamId}/channels/{channelId}/messages/new.schema.jsonpackages/teams/discovery/teams/{teamId}/channels/{channelId}/messages/{messageId}/replies/new.example.jsonpackages/teams/discovery/teams/{teamId}/channels/{channelId}/messages/{messageId}/replies/new.schema.jsonpackages/teams/package.jsonpackages/teams/src/path-mapper.tspackages/teams/test/teams-adapter.test.tspackages/zendesk/discovery/zendesk/.adapter.mdpackages/zendesk/discovery/zendesk/tickets/new.example.jsonpackages/zendesk/discovery/zendesk/tickets/new.schema.jsonpackages/zendesk/discovery/zendesk/tickets/{ticketId}/comments/new.example.jsonpackages/zendesk/discovery/zendesk/tickets/{ticketId}/comments/new.schema.jsonpackages/zendesk/discovery/zendesk/users/new.example.jsonpackages/zendesk/discovery/zendesk/users/new.schema.jsonpackages/zendesk/package.jsonscripts/generate-writeback-discovery.mjsscripts/verify-writeback-discovery.mjsscripts/writeback-discovery-data.mjs
| Write endpoints: | ||
| | Path | Schema | What it does | | ||
| |---|---|---| | ||
| | `/clickup/tasks/{taskId}/comments/new.json` | `/clickup/tasks/{taskId}/comments/new.schema.json` | Adds a comment to a ClickUp task. | | ||
| | `/clickup/lists/{listId}/tasks/new.json` | `/clickup/lists/{listId}/tasks/new.schema.json` | Creates a task in a ClickUp list. | | ||
| | `/clickup/folders/{folderId}/lists/new.json` | `/clickup/folders/{folderId}/lists/new.schema.json` | Creates a list inside a ClickUp folder. | | ||
| | `/clickup/spaces/{spaceId}/lists/new.json` | `/clickup/spaces/{spaceId}/lists/new.schema.json` | Creates a folderless list inside a ClickUp space. | | ||
| | `/clickup/spaces/{spaceId}/folders/new.json` | `/clickup/spaces/{spaceId}/folders/new.schema.json` | Creates a folder inside a ClickUp space. | | ||
|
|
||
| ## How to use (agents) | ||
| 1. Read the relevant `*.schema.json` to learn the required shape. | ||
| 2. Optional: read the matching `new.example.json` for a starter document. | ||
| 3. Write your document to the `new.json` path. | ||
| 4. Read back the most-recently-created sibling record written by the adapter. |
There was a problem hiding this comment.
Document write fields and required/optional status per route.
The table lists endpoints, but agents still lack field-level write contracts in this adapter doc.
As per coding guidelines, each packages/**/.adapter.md must include “field-level descriptions” and “required vs optional field specifications”.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 12-12: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/clickup/discovery/clickup/.adapter.md` around lines 11 - 24, The
adapter doc lists write endpoints but lacks per-field write contracts; update
packages/clickup/discovery/clickup/.adapter.md to add field-level descriptions
and required-vs-optional specifications for each route:
`/clickup/tasks/{taskId}/comments/new.json`,
`/clickup/lists/{listId}/tasks/new.json`,
`/clickup/folders/{folderId}/lists/new.json`,
`/clickup/spaces/{spaceId}/lists/new.json`, and
`/clickup/spaces/{spaceId}/folders/new.json`; for each route, reference the
corresponding schema file (e.g. `.../new.schema.json`) and the
`new.example.json` where useful, list every writable field with a one-line
description and mark it as required or optional, and include any default values
or validation notes so agents can programmatically understand the write
contract.
| Write endpoints: | ||
| | Path | Schema | What it does | | ||
| |---|---|---| | ||
| | `/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.json` | `/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.schema.json` | Submits a pull request review with optional inline comments. | | ||
|
|
||
| ## How to use (agents) | ||
| 1. Read the relevant `*.schema.json` to learn the required shape. | ||
| 2. Optional: read the matching `new.example.json` for a starter document. | ||
| 3. Write your document to the `new.json` path. | ||
| 4. Read back the most-recently-created sibling record written by the adapter. |
There was a problem hiding this comment.
Add per-field write contract details in the adapter guide.
This doc defines the route but not the endpoint field semantics (and which fields are required vs optional), which leaves the discovery contract incomplete.
As per coding guidelines, each packages/**/.adapter.md must include “field-level descriptions” and “required vs optional field specifications”.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...Schema | What it does | |---|---|---| | `/github/repos/{owner}/{repo}/pulls/{pullNumber}...
(GITHUB)
[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: .../pulls/{pullNumber}/reviews/new.json|/github/repos/{owner}/{repo}/pulls/{pullNumber}...
(GITHUB)
🪛 markdownlint-cli2 (0.22.1)
[warning] 12-12: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/github/discovery/github/.adapter.md` around lines 11 - 20, The
adapter doc for the pull review endpoint is missing per-field write contract
details; update the .adapter.md for the route
`/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.json` (and
reference
`/github/repos/{owner}/{repo}/pulls/{pullNumber}/reviews/new.schema.json` and
`new.example.json`) to include field-level descriptions and which fields are
required vs optional: enumerate every top-level and nested field from
`new.schema.json`, mark required vs optional, describe allowed values and
formats, note default behavior for omitted fields, and include a small example
snippet and any validation/side-effect notes so agents can author valid
`new.json` payloads.
| "type": "object", | ||
| "description": "Inline review comment.", | ||
| "properties": { | ||
| "path": { | ||
| "type": "string", | ||
| "description": "Repository-relative file path." | ||
| }, | ||
| "line": { | ||
| "type": "integer", | ||
| "description": "Line number on the selected side.", | ||
| "minimum": 1 | ||
| }, | ||
| "side": { | ||
| "enum": [ | ||
| "LEFT", | ||
| "RIGHT" | ||
| ], | ||
| "description": "Diff side for the comment. Defaults to RIGHT." | ||
| }, | ||
| "body": { | ||
| "type": "string", | ||
| "description": "Inline comment body." | ||
| }, | ||
| "suggestion": { | ||
| "type": "string", | ||
| "description": "Optional suggested replacement text appended to the comment body." | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| } |
There was a problem hiding this comment.
Require core fields for each inline review comment object.
Lines 27-56 define path, line, and body, but without an item-level required array each comment can be {} and still validate. That weakens the write contract and can produce invalid review submissions.
Suggested schema fix
"items": {
"type": "object",
"description": "Inline review comment.",
+ "required": [
+ "path",
+ "line",
+ "body"
+ ],
"properties": {
"path": {
"type": "string",
"description": "Repository-relative file path."
},📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "type": "object", | |
| "description": "Inline review comment.", | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Repository-relative file path." | |
| }, | |
| "line": { | |
| "type": "integer", | |
| "description": "Line number on the selected side.", | |
| "minimum": 1 | |
| }, | |
| "side": { | |
| "enum": [ | |
| "LEFT", | |
| "RIGHT" | |
| ], | |
| "description": "Diff side for the comment. Defaults to RIGHT." | |
| }, | |
| "body": { | |
| "type": "string", | |
| "description": "Inline comment body." | |
| }, | |
| "suggestion": { | |
| "type": "string", | |
| "description": "Optional suggested replacement text appended to the comment body." | |
| } | |
| }, | |
| "additionalProperties": true | |
| } | |
| "type": "object", | |
| "description": "Inline review comment.", | |
| "required": [ | |
| "path", | |
| "line", | |
| "body" | |
| ], | |
| "properties": { | |
| "path": { | |
| "type": "string", | |
| "description": "Repository-relative file path." | |
| }, | |
| "line": { | |
| "type": "integer", | |
| "description": "Line number on the selected side.", | |
| "minimum": 1 | |
| }, | |
| "side": { | |
| "enum": [ | |
| "LEFT", | |
| "RIGHT" | |
| ], | |
| "description": "Diff side for the comment. Defaults to RIGHT." | |
| }, | |
| "body": { | |
| "type": "string", | |
| "description": "Inline comment body." | |
| }, | |
| "suggestion": { | |
| "type": "string", | |
| "description": "Optional suggested replacement text appended to the comment body." | |
| } | |
| }, | |
| "additionalProperties": true | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@packages/github/discovery/github/repos/`{owner}/{repo}/pulls/{pullNumber}/reviews/new.schema.json
around lines 27 - 56, The inline review comment object schema currently allows
empty objects because it lacks an item-level required array; update the object
definition in new.schema.json for the inline comment (the object that defines
"path", "line", "side", "body", "suggestion") to include a "required" array
listing at least "path", "line", and "body" so each comment must provide those
core fields, and keep "additionalProperties": true if extra fields are allowed.
| "required": [], | ||
| "description": "Provide either a `properties` object or top-level HubSpot writable property keys.", | ||
| "properties": { | ||
| "properties": { | ||
| "type": "object", | ||
| "description": "HubSpot CRM property names and values. Read HubSpot object property metadata to discover object-specific keys.", | ||
| "additionalProperties": true | ||
| } | ||
| }, | ||
| "additionalProperties": { | ||
| "description": "Writable HubSpot CRM property value." | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, confirm the file exists and read its content
cat packages/hubspot/discovery/hubspot/tickets/new.schema.jsonRepository: AgentWorkforce/relayfile-adapters
Length of output: 651
🏁 Script executed:
# Check for sibling artifacts in the same directory
ls -la packages/hubspot/discovery/hubspot/tickets/ | grep -E "new\.(json|schema\.json|example\.json)"Repository: AgentWorkforce/relayfile-adapters
Length of output: 206
🏁 Script executed:
# Verify the schema structure is valid JSON and check for any syntax issues
python3 << 'EOF'
import json
import sys
try:
with open('packages/hubspot/discovery/hubspot/tickets/new.schema.json', 'r') as f:
schema = json.load(f)
print("Schema is valid JSON")
print("\nRoot level keys:", list(schema.keys()))
if 'required' in schema:
print("'required' field:", schema['required'])
if 'properties' in schema:
print("'properties' keys:", list(schema['properties'].keys()))
if 'additionalProperties' in schema:
print("'additionalProperties' type:", type(schema['additionalProperties']))
except json.JSONDecodeError as e:
print(f"JSON parsing error: {e}")
except FileNotFoundError:
print("File not found")
except Exception as e:
print(f"Error: {e}")
EOFRepository: AgentWorkforce/relayfile-adapters
Length of output: 309
🏁 Script executed:
# Check if new.json exists (the template file)
ls -la packages/hubspot/discovery/hubspot/tickets/new.jsonRepository: AgentWorkforce/relayfile-adapters
Length of output: 176
🏁 Script executed:
# Read the example to understand the intended payload structure
cat packages/hubspot/discovery/hubspot/tickets/new.example.jsonRepository: AgentWorkforce/relayfile-adapters
Length of output: 185
🏁 Script executed:
# Check the directory structure to understand artifact relationships
find packages/hubspot/discovery/hubspot/tickets/ -type f -name "*.json" -o -name "*.schema.json"Repository: AgentWorkforce/relayfile-adapters
Length of output: 196
Enforce the "either properties or top-level keys" contract with anyOf constraint
The schema currently allows empty objects {}, which violates the either/or requirement stated in the description (line 6). Add an anyOf constraint to enforce that consumers must provide either a non-empty properties object OR one or more top-level writable keys, but not both or neither.
Additionally, the new.json template file is missing from this directory. Per coding guidelines, adapters exposing write endpoints must ship new.json, new.schema.json, and new.example.json together. Only the schema and example are present.
Proposed schema constraint
"required": [],
"description": "Provide either a `properties` object or top-level HubSpot writable property keys.",
+ "anyOf": [
+ {
+ "required": ["properties"],
+ "properties": {
+ "properties": {
+ "type": "object",
+ "minProperties": 1
+ }
+ }
+ },
+ {
+ "minProperties": 1,
+ "not": { "required": ["properties"] }
+ }
+ ],
"properties": {📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "required": [], | |
| "description": "Provide either a `properties` object or top-level HubSpot writable property keys.", | |
| "properties": { | |
| "properties": { | |
| "type": "object", | |
| "description": "HubSpot CRM property names and values. Read HubSpot object property metadata to discover object-specific keys.", | |
| "additionalProperties": true | |
| } | |
| }, | |
| "additionalProperties": { | |
| "description": "Writable HubSpot CRM property value." | |
| } | |
| "required": [], | |
| "description": "Provide either a `properties` object or top-level HubSpot writable property keys.", | |
| "anyOf": [ | |
| { | |
| "required": ["properties"], | |
| "properties": { | |
| "properties": { | |
| "type": "object", | |
| "minProperties": 1 | |
| } | |
| } | |
| }, | |
| { | |
| "minProperties": 1, | |
| "not": { "required": ["properties"] } | |
| } | |
| ], | |
| "properties": { | |
| "properties": { | |
| "type": "object", | |
| "description": "HubSpot CRM property names and values. Read HubSpot object property metadata to discover object-specific keys.", | |
| "additionalProperties": true | |
| } | |
| }, | |
| "additionalProperties": { | |
| "description": "Writable HubSpot CRM property value." | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/hubspot/discovery/hubspot/tickets/new.schema.json` around lines 5 -
16, The schema allows empty objects and doesn't enforce the "either properties
or top-level keys" contract; update new.schema.json to add an anyOf at the root
with two exclusive branches: (A) require the "properties" key and ensure
"properties" is a non-empty object (e.g., set minProperties: 1 on the properties
schema) and disallow top-level writable keys in that branch, and (B) require
absence of "properties" and require at least one top-level writable property
(use additionalProperties with a value schema and require minProperties:1 on the
root branch); also add the missing new.json template to the same directory so
adapters exposing write endpoints include new.json, new.schema.json, and
new.example.json together.
| "body": { | ||
| "type": "object", | ||
| "description": "Jira rich-text document body. A plain string body is also accepted by the resolver.", | ||
| "additionalProperties": true |
There was a problem hiding this comment.
Schema and documented behavior conflict for body
body is typed as object, but its description says plain string is accepted. This makes the discoverable contract inaccurate for agents.
Suggested patch
"body": {
- "type": "object",
- "description": "Jira rich-text document body. A plain string body is also accepted by the resolver.",
- "additionalProperties": true
+ "description": "Jira rich-text document body, or plain string body.",
+ "oneOf": [
+ {
+ "type": "object",
+ "additionalProperties": true
+ },
+ {
+ "type": "string"
+ }
+ ]
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "body": { | |
| "type": "object", | |
| "description": "Jira rich-text document body. A plain string body is also accepted by the resolver.", | |
| "additionalProperties": true | |
| "body": { | |
| "description": "Jira rich-text document body, or plain string body.", | |
| "oneOf": [ | |
| { | |
| "type": "object", | |
| "additionalProperties": true | |
| }, | |
| { | |
| "type": "string" | |
| } | |
| ] | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/jira/discovery/jira/issues/`{issueIdOrKey}/comments/new.schema.json
around lines 9 - 12, The schema for the "body" property currently declares
"type": "object" but states a plain string is also accepted; update the "body"
definition (in new.schema.json) to allow both object and string (e.g., set
"type": ["object","string"] or use an anyOf with a string and an object schema),
keep "additionalProperties": true for the object case, and adjust the
description if needed so the schema and documented behavior match.
| "required": [], | ||
| "properties": { | ||
| "body": { | ||
| "type": "object", | ||
| "description": "Teams message body.", | ||
| "properties": { | ||
| "contentType": { | ||
| "enum": [ | ||
| "html", | ||
| "text" | ||
| ], | ||
| "description": "Message content type. The adapter sends html by default." | ||
| }, | ||
| "content": { | ||
| "type": "string", | ||
| "description": "Message body content." | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
| "text": { | ||
| "type": "string", | ||
| "description": "Plain text or HTML message content. Used when `body.content` is omitted." | ||
| }, | ||
| "content": { | ||
| "type": "string", | ||
| "description": "Plain text or HTML message content. Used when `body.content` and `text` are omitted." | ||
| } | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
For Microsoft Graph Teams channel message replies, what minimum fields are required in the request body to post a reply successfully?
💡 Result:
For Microsoft Graph Teams channel message replies, the request body must include exactly one mandatory top-level field: body. Everything else is optional. You can see this in the official Graph docs for posting replies to a channel message: - “In the request body, supply a JSON representation of a message object. Only the body property is mandatory. Other properties are optional.” [1][2] So, the minimum request body shape is: { "body": { "contentType": "html|text", "content": "..." } } Where contentType and content are the fields inside body used in the examples; the docs explicitly state only body is mandatory at the top level. [1][2][3]
Citations:
- 1: https://learn.microsoft.com/en-us/graph/api/chatmessage-post-replies?view=graph-rest-beta&tabs=http
- 2: https://learn.microsoft.com/en-us/graph/api/chatmessage-post-replies?view=graph-rest-1.0
- 3: https://learn.microsoft.com/en-us/graph/api/channel-post-messagereply?view=graph-rest-1.0
Require body field in request schema.
According to Microsoft Graph API documentation, only the body property is mandatory for Teams message replies. The schema currently allows empty payloads with required: [], which will fail at runtime. Change to "required": ["body"].
The text and content fields are optional fallbacks when body.content is omitted—they are not equivalent alternatives.
💡 Proposed fix
"type": "object",
- "required": [],
+ "required": ["body"],
"properties": {Reference: Microsoft Graph Teams message replies API
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "required": [], | |
| "properties": { | |
| "body": { | |
| "type": "object", | |
| "description": "Teams message body.", | |
| "properties": { | |
| "contentType": { | |
| "enum": [ | |
| "html", | |
| "text" | |
| ], | |
| "description": "Message content type. The adapter sends html by default." | |
| }, | |
| "content": { | |
| "type": "string", | |
| "description": "Message body content." | |
| } | |
| }, | |
| "additionalProperties": true | |
| }, | |
| "text": { | |
| "type": "string", | |
| "description": "Plain text or HTML message content. Used when `body.content` is omitted." | |
| }, | |
| "content": { | |
| "type": "string", | |
| "description": "Plain text or HTML message content. Used when `body.content` and `text` are omitted." | |
| } | |
| }, | |
| "required": ["body"], | |
| "properties": { | |
| "body": { | |
| "type": "object", | |
| "description": "Teams message body.", | |
| "properties": { | |
| "contentType": { | |
| "enum": [ | |
| "html", | |
| "text" | |
| ], | |
| "description": "Message content type. The adapter sends html by default." | |
| }, | |
| "content": { | |
| "type": "string", | |
| "description": "Message body content." | |
| } | |
| }, | |
| "additionalProperties": true | |
| }, | |
| "text": { | |
| "type": "string", | |
| "description": "Plain text or HTML message content. Used when `body.content` is omitted." | |
| }, | |
| "content": { | |
| "type": "string", | |
| "description": "Plain text or HTML message content. Used when `body.content` and `text` are omitted." | |
| } | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@packages/teams/discovery/teams/`{teamId}/channels/{channelId}/messages/{messageId}/replies/new.schema.json
around lines 5 - 33, The schema currently allows empty payloads because
"required" is empty; update the JSON schema so the top-level "required" array
includes "body" (i.e., "required": ["body"]) to enforce the Microsoft Graph
requirement that the body property is mandatory for message replies, leaving the
existing "body", "text", and "content" properties unchanged so text/content
remain optional fallbacks when body.content is omitted.
| "required": [], | ||
| "properties": { | ||
| "body": { | ||
| "type": "object", | ||
| "description": "Teams message body.", | ||
| "properties": { | ||
| "contentType": { | ||
| "enum": [ | ||
| "html", | ||
| "text" | ||
| ], | ||
| "description": "Message content type. The adapter sends html by default." | ||
| }, | ||
| "content": { | ||
| "type": "string", | ||
| "description": "Message body content." | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
| "text": { | ||
| "type": "string", | ||
| "description": "Plain text or HTML message content. Used when `body.content` is omitted." | ||
| }, | ||
| "content": { | ||
| "type": "string", | ||
| "description": "Plain text or HTML message content. Used when `body.content` and `text` are omitted." | ||
| } | ||
| }, |
There was a problem hiding this comment.
Prevent empty payloads in the create-message schema.
{} currently validates, so agents can produce writes with no content. Add a guard that requires at least one content source (text, content, or body.content).
Suggested schema adjustment
- "required": [],
+ "anyOf": [
+ { "required": ["text"] },
+ { "required": ["content"] },
+ {
+ "required": ["body"],
+ "properties": {
+ "body": {
+ "type": "object",
+ "required": ["content"]
+ }
+ }
+ }
+ ],🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In
`@packages/teams/discovery/teams/`{teamId}/channels/{channelId}/messages/new.schema.json
around lines 5 - 33, Add a validation rule so an empty object no longer passes:
include an anyOf (or oneOf) at the root requiring at least one of the content
sources to be present — e.g. require "text", or "content", or "body" with nested
required "content" — referencing the existing properties "text", "content", and
"body.content" so that a payload must include one of those fields before it
validates.
| "required": [], | ||
| "properties": { | ||
| "body": { | ||
| "type": "object", | ||
| "description": "Teams message body.", | ||
| "properties": { | ||
| "contentType": { | ||
| "enum": [ | ||
| "html", | ||
| "text" | ||
| ], | ||
| "description": "Message content type. The adapter sends html by default." | ||
| }, | ||
| "content": { | ||
| "type": "string", | ||
| "description": "Message body content." | ||
| } | ||
| }, | ||
| "additionalProperties": true | ||
| }, | ||
| "text": { | ||
| "type": "string", | ||
| "description": "Plain text or HTML message content. Used when `body.content` is omitted." | ||
| }, | ||
| "content": { | ||
| "type": "string", | ||
| "description": "Plain text or HTML message content. Used when `body.content` and `text` are omitted." | ||
| } | ||
| }, | ||
| "additionalProperties": false |
There was a problem hiding this comment.
Enforce at least one content field for message creation.
Line 5 leaves all content inputs optional, so {} is valid against this schema even though a create-message payload needs actual content. Add a schema constraint requiring one of: body.content, text, or content.
Suggested schema fix
"type": "object",
- "required": [],
+ "required": [],
"properties": {
"body": {
"type": "object",
"description": "Teams message body.",
+ "required": [
+ "content"
+ ],
"properties": {
@@
}
},
+ "anyOf": [
+ { "required": ["body"] },
+ { "required": ["text"] },
+ { "required": ["content"] }
+ ],
"additionalProperties": false
}🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/teams/discovery/teams/chats/`{chatId}/messages/new.schema.json
around lines 5 - 34, The schema currently allows an empty object because no
content fields are required; add an anyOf (or oneOf) constraint at the root that
requires at least one of the content properties to be present: body.content,
text, or content. Update the schema around the root object (the existing
"properties" block containing "body", "text", and "content") to include an anyOf
array with three entries that each use a required path or a property existence
check for "body"->"content", "text", and "content" respectively so validation
fails for {} and passes only when one of body.content, text, or content is
supplied.
| await assertFile(schemaFile, endpoint.schemaPath); | ||
| await assertFile(exampleFile, endpoint.examplePath); | ||
|
|
||
| const schema = JSON.parse(await readFile(schemaFile, 'utf8')); | ||
| const example = JSON.parse(await readFile(exampleFile, 'utf8')); |
There was a problem hiding this comment.
Missing-file handling can abort verification early.
Even after assertFile(...) records a failure, the script still reads/parses the missing file, which can throw and stop further checks instead of aggregating all failures.
Suggested fix
- await assertFile(schemaFile, endpoint.schemaPath);
- await assertFile(exampleFile, endpoint.examplePath);
+ const hasSchema = await assertFile(schemaFile, endpoint.schemaPath);
+ const hasExample = await assertFile(exampleFile, endpoint.examplePath);
+ if (!hasSchema || !hasExample) {
+ continue;
+ }
@@
async function assertFile(path, label) {
try {
await access(path);
+ return true;
} catch {
failures.push(`missing ${label}: ${path}`);
+ return false;
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| await assertFile(schemaFile, endpoint.schemaPath); | |
| await assertFile(exampleFile, endpoint.examplePath); | |
| const schema = JSON.parse(await readFile(schemaFile, 'utf8')); | |
| const example = JSON.parse(await readFile(exampleFile, 'utf8')); | |
| const hasSchema = await assertFile(schemaFile, endpoint.schemaPath); | |
| const hasExample = await assertFile(exampleFile, endpoint.examplePath); | |
| if (!hasSchema || !hasExample) { | |
| continue; | |
| } | |
| const schema = JSON.parse(await readFile(schemaFile, 'utf8')); | |
| const example = JSON.parse(await readFile(exampleFile, 'utf8')); |
| await assertFile(schemaFile, endpoint.schemaPath); | |
| await assertFile(exampleFile, endpoint.examplePath); | |
| const schema = JSON.parse(await readFile(schemaFile, 'utf8')); | |
| const example = JSON.parse(await readFile(exampleFile, 'utf8')); | |
| async function assertFile(path, label) { | |
| try { | |
| await access(path); | |
| return true; | |
| } catch { | |
| failures.push(`missing ${label}: ${path}`); | |
| return false; | |
| } | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/verify-writeback-discovery.mjs` around lines 34 - 38,
assertFile(schemaFile, endpoint.schemaPath) and assertFile(exampleFile,
endpoint.examplePath) may record failures but the current code still calls
readFile/JSON.parse and can throw, aborting further verification; change the
flow in the verify logic so you capture the result of assertFile (e.g.,
schemaExists = await assertFile(...), exampleExists = await assertFile(...)) and
only call readFile and JSON.parse to populate schema and example when the
corresponding exists flag is truthy, and additionally wrap JSON.parse calls for
schema and example in try/catch to record parse failures via the same
verification/failure collector instead of letting exceptions propagate.
| for (const requiredKey of endpoint.schema.required ?? []) { | ||
| if (!(requiredKey in example)) { | ||
| failures.push(`${adapterSlug}: ${endpoint.examplePath} missing required key ${requiredKey}`); | ||
| } | ||
| } |
There was a problem hiding this comment.
Validate required keys against the parsed schema artifact, not endpoint metadata.
validateExample currently uses endpoint.schema.required, so a drifted new.schema.json can pass without enforcing its own required keys. Use the parsed schema.required instead.
Suggested fix
- validateExample(adapter.slug, endpoint, example);
+ validateExample(adapter.slug, endpoint, schema, example);
@@
-function validateExample(adapterSlug, endpoint, example) {
+function validateExample(adapterSlug, endpoint, schema, example) {
@@
- for (const requiredKey of endpoint.schema.required ?? []) {
+ for (const requiredKey of schema.required ?? []) {🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@scripts/verify-writeback-discovery.mjs` around lines 91 - 95, The validation
loop in validateExample is checking required keys off endpoint.schema.required
(which can be stale) instead of the parsed schema object; update the loop to use
the parsed schema (schema.required) when determining required keys and ensure
you handle the case where schema.required is undefined (e.g., default to an
empty array) so missing required keys are checked against the actual parsed
artifact rather than endpoint metadata.
1 participant
Summary
Relayfile writeback shapes are now discoverable from the mounted adapter assets instead of living only in prompts or resolver code. Each adapter package ships a discovery tree with a root .adapter.md plus sibling new.schema.json and new.example.json files for every new.json write template, so agents can inspect the contract before writing back.
The PR also adds generation and verification scripts so future adapter changes keep those artifacts in sync, and adds repository/Claude guidance requiring schemas for new write endpoints. Notion and Teams now accept the documented new.json create aliases for their create-writeback flows.
Example use case
An LLM agent can read /linear/issues/new.schema.json, learn that teamId and title are required and that priority is enum 0-4, optionally read /linear/issues/new.example.json, then write a valid document to /linear/issues/new.json without being hand-fed the Linear issue shape.
Test plan