Skip to content

Add Linear tools docs#661

Open
Pranesh-Raghu wants to merge 9 commits into
mainfrom
preview/linear-connector-docs
Open

Add Linear tools docs#661
Pranesh-Raghu wants to merge 9 commits into
mainfrom
preview/linear-connector-docs

Conversation

@Pranesh-Raghu
Copy link
Copy Markdown
Collaborator

@Pranesh-Raghu Pranesh-Raghu commented May 6, 2026

Summary

  • Populates linear.ts with all 52 Linear tools (issues, projects, cycles, teams, users, comments, attachments, labels, milestones, roadmaps, webhooks, workflow states)
  • Removes hardcoded ## What you can do bullets from linear.mdx — they live in capabilities.json and are injected by pnpm run sync-agent-connectors
  • Adds _section-before-tool-list-linear-resource-ids.mdx so the Getting resource IDs section is sync-safe

Preview

https://deploy-preview-{PR_NUMBER}--scalekit-starlight.netlify.app/agentkit/connectors/linear/

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Added a "Getting resource IDs" section to the Linear docs with a reference table mapping resources to API tools and response fields; placed it before the tool list and removed the "What you can do" guidance.
  • Refactor
    • Improved internal logic for detecting read-only tools and selecting quickstart candidates to be more robust (no user-facing behavior changes).

Review Change Stack

- Populate linear.ts with all 52 tools from the Linear GraphQL API
  (attachments, comments, cycles, issues, labels, milestones, projects,
   roadmaps, teams, users, webhooks, workflow states, viewer)
- Remove hardcoded What you can do bullets from linear.mdx — they live
  in capabilities.json and are injected by sync
- Create _section-before-tool-list-linear-resource-ids.mdx with
  Getting resource IDs table so the section survives sync
- Export SectionBeforeToolListLinearResourceIds from index.ts
@Pranesh-Raghu Pranesh-Raghu changed the title Add Linear connector docs (52 tools) Add Linear tools docs May 6, 2026
@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 6, 2026

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: de8cbd11-6443-4295-8e37-e8433d05793f

📥 Commits

Reviewing files that changed from the base of the PR and between d93b7ef and c84d325.

📒 Files selected for processing (1)
  • src/components/templates/agent-connectors/index.ts
📜 Recent review details
🧰 Additional context used
📓 Path-based instructions (10)
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{js,ts,tsx,jsx}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: Prefer interface for defining object shapes in TypeScript
Use camelCase for variable names

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{ts,tsx,py,go,java,mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,py,go,java,mdx,md}: Use the exact SDK variable names: Node.js (scalekit), Python (scalekit_client), Go (scalekitClient), Java (scalekitClient)
Never hard-code secrets or API keys in code examples; use environment variables
Include security comments that state the threat, why the pattern is required, and what can go wrong if omitted

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{ts,tsx,py,go,java}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,py,go,java}: Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments with parameter descriptions, return values, and types
Comments should not duplicate the code; explain what the code does conceptually, not literally
Use better variable names and structure instead of comments to explain poorly written code
Explain unidiomatic or redundant code in comments; clarify why a specific pattern was chosen
Document exceptions and edge cases in code comments
Include links to external references (standards, RFCs, official documentation) in comments where helpful
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{ts,tsx,js,json}

📄 CodeRabbit inference engine (CLAUDE.md)

Use pnpm for package management

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{ts,tsx,js,jsx,py,go,java}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx,js,jsx,py,go,java}: Comments should not duplicate the code; comments should add value beyond what's obvious. Use better variable names and structure instead of using comments to explain poorly written code
Don't use comments to excuse unclear code. Comments should dispel confusion, not cause it. Ensure comments clarify rather than obscure purpose
Explain unidiomatic code in comments: comment on code that might seem unnecessary or redundant; explain why you chose a specific pattern
Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments including parameter descriptions, return values, types, and descriptions
Document exceptions and edge cases in code comments
Include links to external references in code comments where helpful (standards, RFCs, official documentation)
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments in code

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{md,mdx,astro,ts}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

**/*.{md,mdx,astro,ts}: Use pnpm pretty-quick --staged via pre-commit git hook to auto-format all staged .md, .mdx, .astro, .ts files with Prettier
Run pnpm format to auto-format all .md, .mdx, .astro, .ts files before pushing changes

Files:

  • src/components/templates/agent-connectors/index.ts
**/*.{ts,js,mjs}

⚙️ CodeRabbit configuration file

**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:

  • Comments that "duplicate" or restate what the code does.
  • Missing comments on bug fixes, workarounds, or issue references.
  • Missing inline documentation or explanatory comments.
    Code comments are at the author's discretion.

Files:

  • src/components/templates/agent-connectors/index.ts
🔇 Additional comments (1)
src/components/templates/agent-connectors/index.ts (1)

146-146: LGTM!


Walkthrough

Adds a reusable MDX "Getting resource IDs" template (exports sectionTitle), registers and renders it in the Linear connector docs before the tool list, and reformats read-only detection/selection code in scripts/sync-agent-connectors.js with no behavior changes.

Changes

Linear connector resource IDs documentation

Layer / File(s) Summary
Resource ID fetching template
src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
Exports sectionTitle ('Getting resource IDs') and adds guidance plus a table mapping Linear resources to the API tools and response fields that contain each ID.
Linear doc integration and barrel export
src/components/templates/agent-connectors/index.ts, src/content/docs/agentkit/connectors/linear.mdx
Adds a barrel export for SectionBeforeToolListLinearResourceIds, imports it into linear.mdx, and inserts a "## Getting resource IDs" section before the tool list.
Script code style refactor
scripts/sync-agent-connectors.js
Reformats isReadOnlyTool and the readOnlyNoReq selection predicate to multi-line segmentation/predicate forms; logic and outputs unchanged.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Possibly related PRs

  • scalekit-inc/developer-docs#680: Both PRs add a “Getting resource IDs” MDX template (exporting sectionTitle = "Getting resource IDs") and register it via src/components/templates/agent-connectors/index.ts.
  • scalekit-inc/developer-docs#658: Adds similar sync-safe connector section templates and registers them in the same agent-connectors barrel.

Suggested reviewers

  • ravibits
  • saif-at-scalekit
  • amitash1912
  • Avinash-Kamath
🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'Add Linear tools docs' directly and clearly summarizes the main change: adding documentation for Linear tools, including the new section component and connector configuration.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch preview/linear-connector-docs
  • 🛠️ fix frontmatter
  • 🛠️ fix internal links

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.


Comment @coderabbitai help to get the list of available commands and usage tips.

@netlify
Copy link
Copy Markdown

netlify Bot commented May 6, 2026

Deploy Preview for scalekit-starlight ready!

Name Link
🔨 Latest commit c84d325
🔍 Latest deploy log https://app.netlify.com/projects/scalekit-starlight/deploys/6a055a5b2d63dc00085c9ffd
😎 Deploy Preview https://deploy-preview-661--scalekit-starlight.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Copy link
Copy Markdown
Contributor

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🤖 Prompt for all review comments with 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.

Inline comments:
In
`@src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx`:
- Line 15: The table row uses a vague description "issue response with
attachments" for the Attachment ID column; replace that text with the explicit
tool name and expansion pattern (for example, "linear_issue_get (with
attachments expanded)") so it matches the other rows' pattern and clearly
indicates the source of issue.attachments.nodes[].id; update the cell that
currently reads `issue response with attachments` to reference the specific tool
(e.g., `linear_issue_get`) and note that attachments are expanded to
`issue.attachments.nodes[].id`.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 97fde2e8-2d13-45aa-8efe-49f9d158cde5

📥 Commits

Reviewing files that changed from the base of the PR and between b00579b and 3bff352.

📒 Files selected for processing (3)
  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
  • src/content/docs/agentkit/connectors/linear.mdx
  • src/data/agent-connectors/linear.ts
💤 Files with no reviewable changes (1)
  • src/content/docs/agentkit/connectors/linear.mdx
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: Redirect rules - scalekit-starlight
  • GitHub Check: Header rules - scalekit-starlight
  • GitHub Check: Pages changed - scalekit-starlight
🧰 Additional context used
📓 Path-based instructions (13)
**/*.mdx

📄 CodeRabbit inference engine (.cursorrules)

**/*.mdx: Use clear, descriptive titles that explain the purpose of the document
Include comprehensive descriptions in frontmatter metadata
Organize content with logical heading hierarchy (H2, H3, H4)
Use tableOfContents property in frontmatter when content has multiple sections
Set appropriate sidebar labels for navigation in frontmatter
Use direct instruction writing style with phrases like 'This guide shows you how to...' and 'Create an authorization URL to...'
Use second person perspective ('your application', 'you receive', 'you must') in documentation
Keep sentences concise, aiming for under 25 words per sentence
Explain the 'why' in documentation with phrases like 'This prevents CSRF attacks by...' or 'Use this to validate that...'
Use action verbs in section headings: 'Store session tokens securely', 'Validate the state parameter', 'Exchange authorization code for tokens'
Use present tense for descriptions: 'Scalekit handles the complex authentication flow', 'The SDK provides methods to refresh tokens'
Use future tense for results: 'This will redirect users to...', 'You'll receive a JWT containing...', 'Scalekit returns an authorization code'
Use transition phrases between sections: 'After the user authenticates...', 'Once the state is validated...', 'Let's take a look at how to...'
Write 1-3 opening paragraphs that explain what users will accomplish, provide context about when/why, preview key concepts, and use direct instructional language
Begin introduction sections with a clear statement of what the guide covers and explain the problem being solved
Use collapsible sections in introduction for sequence diagrams, video demonstrations, data models, and JSON examples with appropriate icons
Use numbered format within Steps component: 1. ## Title with all step content indented with exactly 3 spaces
Use action-oriented headings in step-by-step guides within Steps components
Include code examples in all 4 languages (Node.js, Python, Go, Java) within Steps co...

Files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx

⚙️ CodeRabbit configuration file

**/*.mdx: You are reviewing Scalekit developer documentation written in MDX
(Astro + Starlight framework). Apply ALL of the following checks:

Frontmatter

  • title MUST be ≤ 60 characters and clearly state what the page does.
  • description MUST be ≤ 160 characters, action-oriented, unique per page.
  • sidebar.label MUST be present and ≤ 30 characters.
  • sidebar.order MUST be set on every page that lives inside a section
    with siblings, to enforce the journey order in sidebar.config.ts.
  • Flag any missing prev / next links on pages that are clearly
    part of a sequential flow (e.g., quickstart → implement-login →
    complete-login → manage-session → logout).

Voice & Style (CLAUDE.md standards)

  • Voice: confident, direct, collaborative, instructional.
  • Person: second person only ("you", "your application"). Reject "we",
    "our", "the developer", "the user".
  • Tense: present tense for descriptions; imperative mood for instructions.
  • Flag weasel words: "simply", "just", "easy", "straightforward",
    "obviously", "of course", "note that".
  • Flag passive voice constructions where active voice is clearer.
  • Headings must be sentence case, not Title Case (except proper nouns).
  • No heading should end with a colon or period.

Content structure

  • Journey how-to guides MUST contain numbered <Steps> (Starlight
    component). This does NOT apply to src/content/docs/cookbooks/**
    (blog-style recipes — optional <Steps>, <Tabs> after </Steps> OK;
    see cookbooks path_instructions).
  • Concept pages MUST NOT contain numbered steps — concepts explain, not instruct.
  • API reference pages MUST list parameters in a table with Name / Type /
    Required / Description columns.
  • Every page MUST end with a clear "what's next" signal — either a
    next: frontmatter link, a <LinkCard>, or an explicit paragraph
    pointing the reader forward in the sidebar journey.

Code examples

  • ALL code examples that show SDK usage MUST include all four language
    tabs...

Files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
**/*.{yml,yaml,md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/browsecentral-labels.mdc)

**/*.{yml,yaml,md,mdx}: BrowseCentral labels should be maximum 3-5 words - keep concise but add context when needed
BrowseCentral labels should be action-oriented - start with verbs when possible
BrowseCentral labels should be specific and clear - add context when simple labels are ambiguous
BrowseCentral labels should be outcome-focused - describe what users accomplish and the context
BrowseCentral labels should use 'Action + Object' pattern (e.g., 'Invite users', 'Restrict sign-up', 'Set up SCIM')
BrowseCentral labels should use feature names (e.g., 'Enterprise SSO', 'Passwordless quickstart')
BrowseCentral labels should describe task completion (e.g., 'Run migrations', 'Migrate auth', 'Merge identities')
BrowseCentral labels should include specific context when needed (e.g., 'Configure Scalekit MCP server', 'Validate incoming API requests')
BrowseCentral labels should use integration context when applicable (e.g., 'Build MCP auth with your existing auth system')
BrowseCentral labels should avoid instructional prefixes: 'How to', 'Guide to', 'Implement', 'Configure', 'Learn', 'Understand'
BrowseCentral labels should avoid verbose phrases: 'Step-by-step guide', 'Complete tutorial', 'Detailed documentation'
BrowseCentral labels should avoid weak verbs: 'Enable', 'Allow', 'Provide', 'Support'

Files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
**/*.{md,mdx}

📄 CodeRabbit inference engine (.cursor/rules/deno-docs-style.mdc)

**/*.{md,mdx}: Use sentence case for all titles and headings in MD/MDX documentation
Keep page titles short and descriptive (3–7 words when possible) in MD/MDX documentation
Use outcome-focused headings that describe results, not categories (e.g., 'Run a script' not 'Scripts')
Avoid gerunds in headings when an imperative works - prefer 'Configure proxies' over 'Configuring proxies'
Keep sidebar labels concise (1–3 words), use sentence case, and focus on outcomes or objects
Use sentence case in sidebar labels without punctuation
Set frontmatter title in sentence case with a clear outcome; description in one sentence (≤160 chars); sidebar.label as shorter form of title; enable tableOfContents on longer pages
Start documentation pages with a one-paragraph overview explaining what the page covers and when to use it
Present the primary use case (80% path) first in documentation, with edge cases later
Use numbered steps for task-focused sections in documentation, with each step beginning with a verb
Break up long documentation sections with subheadings every 3–6 paragraphs
Use asides for important notes, tips, cautions, and references in documentation
Provide runnable, minimal code examples that work as-is in documentation
Prefer CLI-first examples and show file layout when helpful in documentation
Label code blocks with titles for context (e.g., 'Terminal', 'main.ts') in documentation
Keep code block annotations brief and purposeful - annotate only what matters
Use consistent variable and file names across a documentation page
Use descriptive link text in documentation (e.g., 'See permission flags' not 'click here')
Prefer relative links for internal documentation pages and include anchors for section references
Reference APIs consistently using backticks for code, file names, CLI flags, and endpoints
Use backticks for code, file names, CLI flags, and endpoints in documentation
Use lists for options and features in documentation; tables only when comparisons are cleare...

Files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
**/*.{ts,tsx,py,go,java,mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,py,go,java,mdx,md}: Use the exact SDK variable names: Node.js (scalekit), Python (scalekit_client), Go (scalekitClient), Java (scalekitClient)
Never hard-code secrets or API keys in code examples; use environment variables
Include security comments that state the threat, why the pattern is required, and what can go wrong if omitted

Files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
  • src/data/agent-connectors/linear.ts
**/*.{mdx,md}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{mdx,md}: All code examples must use <Tabs syncKey="tech-stack"> format and include Node.js, Python, Go, and Java implementations (90% rule)
Use sentence case for all titles and headings in documentation
Use bold for first mention of important terms, UI elements, and dashboard paths (e.g., Dashboard > Authentication > Session Policy)
Use inline code for technical identifiers: variables, functions, endpoints, scopes, environment variables, file paths, and placeholders
Always include headers in tables; keep cell content concise and readable
Prefer fenced code blocks with language identifiers for all code; never use screenshots of code
Use descriptive link text; never use 'click here' or 'this' as link labels
Keep sentences simple, right-branching, and unambiguous; avoid ambiguous noun stacks and demonstrative pronouns
Use active voice; prefer 'Run the command' over 'The command should be run'
Use second person when giving instructions; address the reader as 'you'
Use present tense for procedures; 'This command installs…' not 'This command will install…'
Avoid hype, slang, and filler words like 'simply', 'just', 'obviously' in documentation
Use consistent terminology throughout; prefer standard names over synonyms
Explain security implications and threats for all security-related content
Use imperative verbs for procedure headings: 'Run a script' not 'Running a script'; 'Configure proxies' not 'Configuring proxies'
Headings must describe outcomes, not categories (good: 'Run a script'; bad: 'Scripts')
Split content into clear sections with descriptive, sentence-style titles that convey meaning without requiring the following paragraph
Keep paragraphs short; isolate critical points in their own short paragraphs
Begin sections and paragraphs with standalone topic sentences that preview content
Put the topic words at the beginning of topic sentences to support fast skimming
Put key takeaways and results at the top of documents and sections
Use bullets and tabl...

Files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy,gradle,xml,json}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

Comments should not duplicate the code - avoid comments that simply restate what the code does; comments should add value beyond what's obvious from reading the code

Files:

  • src/data/agent-connectors/linear.ts
**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

**/*.{js,ts,tsx,jsx,py,java,cs,go,cpp,c,rb,php,swift,kt,scala,rs,m,mm,groovy}: Good comments do not excuse unclear code - refactor the code to be self-explanatory instead of using comments to explain poorly written code; use better variable names, function names, and code structure
Comments should dispel confusion, not cause it - ensure comments clarify rather than obscure the code's purpose; avoid cryptic or joke comments
Explain unidiomatic code in comments - comment on code that might seem unnecessary or redundant and document why you chose a specific pattern over more common alternatives, especially when it deviates from team conventions
Provide links to the original source of copied code - always attribute code copied from external sources with URLs to Stack Overflow answers, GitHub repositories, or documentation
Include links to external references where helpful - reference standards, RFCs, and official documentation; link to relevant specifications when implementing protocols
Add comments when fixing bugs - document bug fixes with context about the issue, reference issue trackers and bug reports, and explain workarounds and their limitations
Use comments to mark incomplete implementations - use standard formats for TODO, FIXME, and NOTE comments with context about what needs to be done and reference issue trackers when possible
Always document public APIs with function/class comments - explain the purpose, parameters, return values, and exceptions; include usage examples for complex functions
Include file headers with copyright information, license, and authorship - provide a brief description of the file's purpose and document dependencies and requirements

Files:

  • src/data/agent-connectors/linear.ts
**/*.{js,ts,tsx,jsx}

📄 CodeRabbit inference engine (.cursor/rules/comment-standards.mdc)

Use JSDoc standards for all function, class, and complex logic comments in JavaScript/TypeScript - include parameter descriptions (@param), return values (@returns), types (@type), and descriptions; document exceptions and edge cases

Files:

  • src/data/agent-connectors/linear.ts
**/*.{ts,tsx}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx}: Prefer interface for defining object shapes in TypeScript
Use camelCase for variable names

Files:

  • src/data/agent-connectors/linear.ts
**/*.{ts,tsx,py,go,java}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{ts,tsx,py,go,java}: Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments with parameter descriptions, return values, and types
Comments should not duplicate the code; explain what the code does conceptually, not literally
Use better variable names and structure instead of comments to explain poorly written code
Explain unidiomatic or redundant code in comments; clarify why a specific pattern was chosen
Document exceptions and edge cases in code comments
Include links to external references (standards, RFCs, official documentation) in comments where helpful
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments

Files:

  • src/data/agent-connectors/linear.ts
**/*.{ts,tsx,js,json}

📄 CodeRabbit inference engine (CLAUDE.md)

Use pnpm for package management

Files:

  • src/data/agent-connectors/linear.ts
**/*.{ts,tsx,js,jsx,py,go,java}

📄 CodeRabbit inference engine (AGENTS.md)

**/*.{ts,tsx,js,jsx,py,go,java}: Comments should not duplicate the code; comments should add value beyond what's obvious. Use better variable names and structure instead of using comments to explain poorly written code
Don't use comments to excuse unclear code. Comments should dispel confusion, not cause it. Ensure comments clarify rather than obscure purpose
Explain unidiomatic code in comments: comment on code that might seem unnecessary or redundant; explain why you chose a specific pattern
Use JSDoc/JavaDoc/docstring standards for function, class, and complex logic comments including parameter descriptions, return values, types, and descriptions
Document exceptions and edge cases in code comments
Include links to external references in code comments where helpful (standards, RFCs, official documentation)
Add comments when fixing bugs; reference issue trackers
Use standard formats for TODO, FIXME, and NOTE comments in code

Files:

  • src/data/agent-connectors/linear.ts
**/*.{ts,js,mjs}

⚙️ CodeRabbit configuration file

**/*.{ts,js,mjs}: Do NOT enforce code-commenting style rules on these files.
Specifically, do not flag:

  • Comments that "duplicate" or restate what the code does.
  • Missing comments on bug fixes, workarounds, or issue references.
  • Missing inline documentation or explanatory comments.
    Code comments are at the author's discretion.

Files:

  • src/data/agent-connectors/linear.ts
🧠 Learnings (7)
📚 Learning: 2026-02-25T03:34:41.147Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 444
File: src/content/docs/agent-auth/start-agent-auth-coding-agents.mdx:31-31
Timestamp: 2026-02-25T03:34:41.147Z
Learning: In MDX files, import { Code } from 'astrojs/starlight/components' only if the MDX content actually uses the <Code> component. If the file uses only fenced code blocks (```), the import is not required. Apply this guideline to all MDX files (e.g., src/content/docs/**/*.mdx) to avoid unnecessary imports and reduce bundle size.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
📚 Learning: 2026-02-25T18:41:00.639Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 446
File: src/content/docs/authenticate/m2m/api-auth-quickstart.mdx:78-78
Timestamp: 2026-02-25T18:41:00.639Z
Learning: Preserve full URLs inside code comments in MDX code blocks (bash/python/js) when the URLs are part of copyable examples. Do not flag these in code examples. Use relative paths in prose and hyperlinks within MDX; only enforce relative paths for markdown prose links, not for URLs inside code comments.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
📚 Learning: 2026-03-10T10:37:47.033Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 475
File: src/components/templates/agent-connectors/_setup-asana.mdx:15-15
Timestamp: 2026-03-10T10:37:47.033Z
Learning: In src/components/templates/agent-connectors/**/*.mdx, it is acceptable to reuse a single shared redirect URI screenshot (use-own-credentials-redirect-uri.png) across multiple steps within the same connector file, even if different UIs are shown. Do not flag this reuse as an issue; ensure this behavior is intentional and documented for reviewers.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
📚 Learning: 2026-03-10T10:38:27.783Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 475
File: src/components/templates/agent-connectors/_setup-confluence.mdx:16-16
Timestamp: 2026-03-10T10:38:27.783Z
Learning: In all MDX templates under src/components/templates/agent-connectors, the pattern uses empty alt text (e.g., ![]()) for redirect URI screenshots like use-own-credentials-redirect-uri.png. This is intentional; reviews should not flag missing alt text for these images in this directory.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
📚 Learning: 2026-03-12T16:26:39.422Z
Learnt from: Pranesh-Raghu
Repo: scalekit-inc/developer-docs PR: 483
File: src/components/templates/agent-connectors/_setup-bigquery.mdx:18-22
Timestamp: 2026-03-12T16:26:39.422Z
Learning: In agent-connectors MDX templates, it is acceptable to reuse shared Google OAuth screenshots stored under `@/assets/docs/agent-connectors/gmail/` (e.g., oauth-web-app.png, add-redirect-uri.png) across different Google-service connector templates (e.g., _setup-bigquery.mdx, _setup-google-ads.mdx). Do not flag cross-connector image path reuse within Google service connectors as an issue. This guideline applies to all files in this directory.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
📚 Learning: 2026-04-25T07:22:18.321Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 633
File: src/components/templates/agent-connectors/_setup-heyreach.mdx:12-12
Timestamp: 2026-04-25T07:22:18.321Z
Learning: In this repo’s MDX documentation files, treat `@/...` paths as aliases that resolve to the `src/` directory (e.g., `@/assets/docs/foo/bar.png` -> `src/assets/docs/foo/bar.png`). When reviewing, do not flag `@`-prefixed image (or other asset) paths as broken; instead, verify that the corresponding physical file exists under `src/`.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
📚 Learning: 2026-05-06T07:23:46.423Z
Learnt from: saif-at-scalekit
Repo: scalekit-inc/developer-docs PR: 658
File: src/components/templates/agent-connectors/_section-before-tool-list-xero-common-patterns.mdx:15-63
Timestamp: 2026-05-06T07:23:46.423Z
Learning: In agentkit agent connectors documentation (files under src/components/templates/agent-connectors and src/content/docs/agentkit/connectors), do not require all four language tabs for SDK code examples. These docs may use only the language tabs relevant to the content (e.g., Node.js and Python). This is an exception to the standard multilingual guideline and should be applied consistently across connector docs.

Applied to files:

  • src/components/templates/agent-connectors/_section-before-tool-list-linear-resource-ids.mdx
🔇 Additional comments (1)
src/data/agent-connectors/linear.ts (1)

3-1209: Comprehensive Linear tool definitions look good.

The 52 tool definitions are well-structured with consistent naming (linear_resource_action), clear descriptions, and appropriate required/optional flags. Parameter types using schema descriptors (string | null, integer | null, array) are appropriate for documentation purposes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant