ci: auto-generate AGENTS.md for agent-friendly SDK discovery

[jcpsimmons]

Summary

Adds a CI workflow that auto-generates an AGENTS.md file at the repo root on every push to main. The file is an agent-friendly description of this SDK, optimized for LLM-based coding assistants and routing layers that need to pick the right Customer.io SDK for a given task.

What this PR adds

• .github/workflows/agents-md-update.yml: Workflow that regenerates AGENTS.md and commits the result back to main. Uses a GitHub App token, Vertex auth, Claude Code action driven by a prompt file, and loop prevention via paths-ignore and commit-message skip patterns.
• .github/prompts/update-agents-md.md: The prompt that Claude Code runs. Defines the required structure (What this is, Install, Initialize, Common calls, Auth and regions, When to use this vs cdp-analytics-js, Best for, Links) and the style rules.

Notes for this repo

• This SDK is TypeScript, so there is no Go setup, no npm ci --prefix docs, and no make docs-generate step.
• There is no make docs-check validation step yet. Nothing to validate.
• The paths-ignore and the Guard update scope step are scoped to AGENTS.md only.

Setup blocker for the maintainer

The repo currently has zero Actions secrets set (gh api repos/customerio/customerio-node/actions/secrets returns total_count: 0). The workflow expects these, presumably inherited from the org or set explicitly:

• CIO_CLAUDE_ASSISTANT_APP_ID
• CIO_CLAUDE_ASSISTANT_APP_PRIVATE_KEY
• GCP_WORKLOAD_IDENTITY_PROVIDER
• VERTEX_GCP_SERVICE_ACCOUNT

Also, the workflow runs on cio-ubuntu-slim, which is a self-hosted runner label. Confirm that runner pool is reachable from this repo. The cio-claude-assistant GitHub App needs to be installed on this repo with contents: write.

Once the secrets and runner are in place, merging this PR will trigger the first run, which will generate AGENTS.md and push it back to main as a follow-up commit.

Test plan

• Confirm org-level secrets are inherited (or set them on this repo) before the workflow runs
• Confirm the cio-claude-assistant GitHub App is installed on this repo
• Confirm the cio-ubuntu-slim self-hosted runner is reachable
• After merge, observe the first workflow run, verify AGENTS.md is created and committed back to main
• Verify the generated AGENTS.md contains all required sections (What this is, Install, Initialize, Common calls, Auth and regions, When to use this vs cdp-analytics-js, Best for, Links)
• Trigger a second run via workflow_dispatch, verify it is a no-op (no commit pushed)
• Confirm a push that sets the commit message to docs: update agents md is correctly skipped

---

Note

Medium Risk
Adds a privileged GitHub Actions workflow that authenticates to GCP and pushes commits to main, so misconfiguration or prompt/action behavior could create unintended commits or CI failures.

Overview
Adds an automated agents md update GitHub Actions workflow that runs on pushes to main (and workflow_dispatch) to regenerate AGENTS.md via the Claude Code action, then commits and pushes changes back to main with loop-prevention conditions.

Introduces a dedicated prompt file that strictly defines the required AGENTS.md structure, content constraints, and style rules, and the workflow includes a guard to fail if any file other than AGENTS.md is modified.

^{Reviewed by Cursor Bugbot for commit 2564e91. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f897d5c. Configure here.}

[cursor]

First run silently skips commit of new AGENTS.md

High Severity

git diff --quiet -- AGENTS.md only compares tracked files. Since AGENTS.md does not yet exist in the repository, the first run creates it as an untracked file. git diff --quiet exits 0 for untracked files (reports no changes), so the workflow prints "AGENTS.md is already current" and exits without ever committing the newly generated file. This makes the entire first run a silent no-op. The check needs to also detect a newly created untracked AGENTS.md, for example by additionally checking git status --porcelain -- AGENTS.md.

 

^{Reviewed by Cursor Bugbot for commit f897d5c. Configure here.}