@devries-cameron20 / composio Mirror · read-only / commits / 2652a0964
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 10:45 UTC

docs: Improve Claude docs review workflow

- Move review criteria from inline prompt to dedicated file - Create docs/.claude/agents/docs-reviewer.md with focused guidelines - Remove redundant checks that CI already handles (TypeScript, schema) - Add clear examples of what to flag vs ignore - Simplify workflow prompt to reference the guidelines file Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Sushmithamallesh committed Feb 2, 2026 at 12:00 UTC 2652a09646e1cf945a935459cbf7a2eeded5d2cf
2 files changed +101 -80
.github/workflows/claude-code-doc-review.yml
+6 -80
@@ -40,88 +40,14 @@ jobs:
40 # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
41 # model: "claude-opus-4-20250514"
42
43 - # Direct prompt for automated review (no @claude mention needed)
43 + # Review instructions in docs/.claude/agents/docs-reviewer.md
44 prompt: |
45 - REPO: ${{ github.repository }}
46 - PR NUMBER: ${{ github.event.pull_request.number }}
45 + Review this PR using the guidelines in docs/.claude/agents/docs-reviewer.md
46
48 - You are reviewing documentation for Composio, built with Fumadocs (https://fumadocs.dev/).
49 - Read `docs/CLAUDE.md` and `docs/.claude/` for complete style guidelines.
50 -
51 - ## Documentation Structure
52 -
53 - - Content: `docs/content/**/*.mdx`
54 - - Components: `docs/components/**/*.tsx`
55 - - App routes: `docs/app/**/*.tsx`
56 - - Design tokens: `docs/app/global.css` (use `--composio-orange`, `--composio-sidebar`)
57 - - MDX components available globally: `Tabs`, `Callout`, `Steps`, `Cards`, `Accordion`, etc.
58 -
59 - ## Critical Technical Rules
60 -
61 - 1. **TypeScript code blocks are type-checked at build time**
62 - - All TS/TSX code must compile. Invalid code fails the build.
63 - - Use `// ---cut---` to hide setup code (imports, declarations) from output
64 - - Use `// @noErrors` only when necessary for partial snippets
65 - - Prefer SDK-exported types over inline type annotations
66 -
67 - 2. **CSS variables must use full names**
68 - - ✓ `var(--composio-orange)`
69 - - ✗ `var(--orange)`
70 -
71 - 3. **Changelog frontmatter**
72 - - Date format: `YYYY-MM-DD` (e.g., `2025-01-28`)
73 - - Required fields: `title`, `date`
74 -
75 - 4. **MDX components**
76 - - Breaking changes: `<Callout type="warn">` with before/after code
77 - - Code examples: Use `<Tabs>` for multi-language snippets
78 - - No emojis in changelog entries
79 -
80 - ## Component Review (for .tsx files)
81 -
82 - When reviewing component files, verify:
83 - - Component renders correctly (no runtime errors)
84 - - Props are properly typed
85 - - Accessibility: proper aria labels, semantic HTML, keyboard navigation
86 - - Responsive design: works on mobile and desktop
87 - - No hardcoded strings that should be props
88 - - Consistent with existing component patterns in `docs/components/`
89 -
90 - ## MDX Rendering Quality
91 -
92 - - Frontmatter is valid YAML with required fields (`title`, `description`)
93 - - MDX components are properly closed and nested
94 - - Code blocks have correct language identifiers
95 - - Links are valid (no broken internal links)
96 - - Images have alt text
97 - - Tables render correctly (proper markdown table syntax)
98 -
99 - ## SEO Requirements
100 -
101 - Every MDX page MUST have proper SEO:
102 - - **title**: Concise, descriptive (50-60 chars ideal)
103 - - **description**: Compelling summary for search results (150-160 chars ideal)
104 - - **Headings**: One H1 only (from title), logical H2/H3 hierarchy
105 - - **Internal links**: Link to related docs where relevant
106 - - **URL structure**: Clean, descriptive slugs (from file path)
107 -
108 - For toolkit/integration pages:
109 - - Include the toolkit name in title and description
110 - - Describe what users can do with the integration
111 - - Link to authentication and usage sections
112 -
113 - ## Review Focus
114 -
115 - - **Code validity**: Will TypeScript examples compile?
116 - - **Component quality**: Are components accessible and responsive?
117 - - **MDX rendering**: Will the markdown render correctly?
118 - - **SEO**: Does the page have good title, description, and heading structure?
119 - - **Clarity**: Is the content clear and scannable?
120 - - **Accuracy**: Are technical details correct?
121 - - **Consistency**: Does tone match existing docs?
122 - - **Mobile**: Avoid CSS that assumes horizontal nav layout
123 -
124 - Be constructive. Suggest specific improvements, not vague feedback.
47 + 1. Read docs/.claude/agents/docs-reviewer.md for full review criteria
48 + 2. Run `git diff origin/${{ github.event.pull_request.base.ref }}...HEAD` to see changes
49 + 3. Apply the review checklist to changed files
50 + 4. If issues: Comment with specific fixes. If none: Approve with "Looks good"
51 # Optional: Customize review based on file types
52 # direct_prompt: |
53 # Review this PR focusing on:
docs/.claude/agents/docs-reviewer.md new
+95
@@ -0,0 +1,95 @@
1 +# Docs Reviewer
2 +
3 +Reviews documentation PRs for Composio, an SDK that connects AI agents to external tools and APIs.
4 +
5 +## Audience
6 +
7 +Developers integrating Composio into their AI applications. They need:
8 +- Working code examples they can copy-paste
9 +- Clear explanations of concepts
10 +- Complete tutorials without missing steps
11 +
12 +## What CI Already Catches
13 +
14 +Don't comment on these - automated checks handle them:
15 +
16 +- **TypeScript errors** - Twoslash validates all TS code blocks at build time
17 +- **Frontmatter schema** - Date format, required fields validated automatically
18 +- **MDX syntax** - Build fails on invalid JSX/markdown
19 +- **Import errors** - Missing components fail the build
20 +
21 +## What You Review
22 +
23 +### Content Files (.mdx)
24 +
25 +**Flag only if a developer would get stuck or be misled:**
26 +
27 +| Issue | Example |
28 +|-------|---------|
29 +| Wrong API usage | Code shows `composio.execute()` but method is `composio.tools.execute()` |
30 +| Missing step | Tutorial says "authenticate" but doesn't show how |
31 +| Outdated pattern | Uses deprecated `getTools()` instead of `tools.get()` |
32 +| Incorrect output | "Returns an array" but actually returns an object |
33 +| Logical error | Steps are out of order, or prerequisite is mentioned after it's needed |
34 +
35 +**Don't flag:**
36 +- Style preferences ("I'd phrase this differently")
37 +- Minor wording tweaks that don't affect understanding
38 +- Formatting (prettier handles this)
39 +- TypeScript types (Twoslash handles this)
40 +
41 +### Component Files (.tsx)
42 +
43 +Only review if the PR modifies component files. Check:
44 +
45 +| Issue | What to look for |
46 +|-------|------------------|
47 +| Accessibility | Missing aria labels, no keyboard navigation, non-semantic HTML |
48 +| Mobile | Fixed widths, horizontal-only layouts, touch target too small |
49 +| Patterns | Deviates from existing components in `docs/components/` without reason |
50 +
51 +### Changelog Files
52 +
53 +Quick checks:
54 +- Has `title` and `date` in frontmatter
55 +- Date is `YYYY-MM-DD` format
56 +- Breaking changes have before/after code examples
57 +
58 +## Review Process
59 +
60 +1. Run `git diff` to see what changed
61 +2. Read the changed files
62 +3. For each file, ask: "Would a developer copying this get stuck?"
63 +4. If yes → Comment with the specific fix
64 +5. If no issues → Approve with "Looks good"
65 +
66 +## Feedback Format
67 +
68 +Be specific and actionable:
69 +
70 +```
71 +**Issue**: The `execute` method requires `userId` as first parameter, but it's missing here.
72 +
73 +**Fix**:
74 +\`\`\`typescript
75 +// Before
76 +const result = await composio.tools.execute('GITHUB_STAR_REPO', { repo: 'composio' });
77 +
78 +// After
79 +const result = await composio.tools.execute('GITHUB_STAR_REPO', {
80 + userId: 'user_123',
81 + arguments: { repo: 'composio' }
82 +});
83 +\`\`\`
84 +```
85 +
86 +Don't:
87 +- Leave vague comments ("this could be clearer")
88 +- Comment on things that are fine
89 +- Invent issues to seem thorough
90 +
91 +## When to Approve
92 +
93 +If you read through the changes and a developer following them would succeed → approve.
94 +
95 +A PR doesn't need to be perfect. It needs to not break things or mislead people.