feat(ci): add api-reference sync agent workflow #1
Workflow file for this run
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| name: API Reference Sync | |
| on: | |
| workflow_dispatch: | |
| pull_request: | |
| types: [closed] | |
| permissions: | |
| actions: read | |
| contents: write | |
| pull-requests: write | |
| issues: write | |
| repository-projects: write | |
| id-token: write | |
| concurrency: | |
| group: api-reference-sync-${{ github.event.pull_request.number || github.run_id }} | |
| cancel-in-progress: true | |
| jobs: | |
| sync: | |
| if: github.event_name == 'workflow_dispatch' || (github.event.pull_request.merged == true && github.event.pull_request.base.ref == 'main') | |
| runs-on: ubuntu-latest | |
| steps: | |
| - name: Checkout code | |
| uses: actions/checkout@v5 | |
| with: | |
| fetch-depth: 0 | |
| - name: Run Claude API reference sync | |
| uses: anthropics/claude-code-action@v1 | |
| with: | |
| anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} | |
| github_token: ${{ secrets.GITHUB_TOKEN }} | |
| claude_args: | | |
| --model opus | |
| --max-turns 28 | |
| --allowedTools "Bash(pnpm:*)" "Bash(node:*)" "Bash(git:*)" "Bash(gh:*)" "Bash(cat:*)" "Bash(rg:*)" | |
| prompt: | | |
| You are the API reference sync agent. | |
| Trigger context: | |
| - Event: ${{ github.event_name }} | |
| - PR Number: #${{ github.event.pull_request.number || '' }} | |
| - PR Title: ${{ github.event.pull_request.title || '' }} | |
| - PR URL: ${{ github.event.pull_request.html_url || '' }} | |
| - PR Body: | |
| ${{ github.event.pull_request.body || '' }} | |
| Rules: | |
| - This workflow may create/update issues and PRs for API-reference drift. | |
| - Focus only on API-reference synchronization and directly related docs metadata. | |
| - Do not create noise issues or unrelated refactors. | |
| Load context before acting: | |
| - Read `CLAUDE.md` and `.claude/skills/README.md`. | |
| - Load and follow these skills in order: | |
| 1. `.claude/skills/api-reference/SKILL.md` | |
| 2. `.claude/skills/docs/SKILL.md` | |
| 3. `.claude/skills/api/SKILL.md` | |
| 4. `.claude/skills/gh-issue/SKILL.md` | |
| 5. `.claude/skills/commit-pr/SKILL.md` | |
| Analyze API-doc drift: | |
| - Inspect merged PR changed files plus linked/closing issues. | |
| - Determine impacted components/utils across core/html/react. | |
| - Run `pnpm install` and `pnpm -C site api-docs`. | |
| - Compare generated API JSON with docs in `site/src/content/docs/reference/`. | |
| - Check `site/src/docs.config.ts` for missing/stale sidebar entries. | |
| - Validate conventions: props/state/data attrs/css vars and JSDoc completeness for interface fields. | |
| Create/update issues only when drift exists: | |
| - Create/update one canonical issue per component using `.github/templates/api-reference-update-issue.md`. | |
| - Issue title: `docs(site): {component_name} api reference update`. | |
| - Keep at most one active canonical issue per component (across all source PRs). | |
| - If a canonical issue exists, update it and append new trigger references. | |
| - If only stale duplicates exist and cannot be safely normalized, close them with reason and open one canonical replacement. | |
| - Include triggering PR(s) and linked source issue(s), if any. | |
| - Fully render template fields; no placeholders. | |
| - Include concise implementation notes in the issue body (target files + drift-specific tasks + validation commands). | |
| Issue body requirements: | |
| - Fill `API Changes Summary` and `Out-of-Sync Docs` tables. | |
| - Do not request runnable examples/demos for API reference pages. | |
| - Provide concise usage-guidance scaffolding based on API surface and likely user intent. | |
| - Keep issue content human-focused; no hidden agent-only instruction blocks. | |
| Create/update PRs for actionable components: | |
| - If drift is clear/actionable, create or update one canonical PR per component tied to the canonical issue. | |
| - PR title: `docs(site): {component_name} api reference update`. | |
| - PR body must use `.github/templates/api-reference-update-pr.md`: | |
| - line 1: `closes #{{ISSUE_NUMBER}}` | |
| - line 2: short concise description | |
| - Search for existing open PR for the same component title and update it instead of opening duplicates. | |
| - If duplicate open PRs exist for the same component, keep one canonical PR and close stale duplicates with a short reason. | |
| - Keep each PR scoped to a single issue/component. | |
| - Do not open a PR when analysis is uncertain. | |
| Labels and planning metadata: | |
| - Required labels: `docs`, `api`, `site`. | |
| - Recommended label: `components`. | |
| - Add `test` only if test updates are needed. | |
| - Certainty routing: | |
| - uncertain/ambiguous: add `triage` | |
| - actionable: do not add `triage` | |
| - If linked source issue(s) have milestone/project assignments, copy them when possible. | |
| - If project assignment fails due permissions/platform limits, note that explicitly in issue body. |