DOC-363: Run MVP docs agents automatically with GitHub Actions

[HarshCasper]

Summary

Adds a workflow_dispatch GitHub Actions workflow (docs-ci-agent.yml) that takes a Linear ticket ID and has an AI agent implement the docs ticket end to end, modeled on thrau/auto-code and this repo's existing bot workflows.

Flow: dispatch with ticket_id (e.g. DOC-362) → regex validation → checkout + Node 22 + npm ci → Claude Code CLI (pinned 2.1.218, model pinned claude-sonnet-4-5-20250929, --max-turns 75, 30-min job timeout) runs with the Linear MCP and LocalStack MCP wired in → the agent reads the ticket via Linear MCP, follows agents.md, edits docs, and writes a PR title/body (with the agents.md audit trail) to /tmp → the workflow fails loudly if the tree is unchanged, otherwise opens a ready-for-review PR via pinned peter-evans/create-pull-request on branch docs-agent/<ticket-id> with the LocalStack Bot identity.

Design decisions

• Agent never touches git credentials — it only edits files; commit/push/PR creation are deterministic workflow steps using PRO_ACCESS_TOKEN (so the created PR triggers normal CI).
• Fixed branch per ticket — re-dispatching a ticket updates the same PR; a per-ticket concurrency group prevents races.
• Linear write-back via branch-name autolink — branch names contain the ticket ID, so the Linear GitHub integration attaches the PR automatically.
• Prompt is inline in the YAML, deduplicated against agents.md (the agent reads that file as instruction docs: move snowflake docs into new IA structure #2); it carries only CI-specific rules: halt rule adaptation, file-scope allowlist, PR output contract, git prohibitions, MCP usage limits.
• Ticket text is treated as untrusted input — scope rules are prompt-enforced; human PR review and the PR's own CI are the safety net.

Verified end to end

Ran the exact production command locally against real ticket DOC-362 (Kinesis Rust Mock v0.1.6):

• ✅ Linear MCP fetched the ticket (API-key bearer auth verified headless, HTTP 200)
• ✅ Edits stayed in scope (2 files under src/content/docs/), matched repo conventions
• ✅ PR title/body written with full audit trail, honest gaps reporting
• ✅ 31 of 75 turns, ~4 minutes, $0.97 on Sonnet 4.5
• ✅ actionlint passes (including shellcheck on all run blocks)

Before first dispatch

1. Add repo secrets CLAUDE_CODE_OAUTH_TOKEN (generate via claude setup-token) and LINEAR_API_KEY. (PRO_ACCESS_TOKEN and LOCALSTACK_AUTH_TOKEN already exist.)
2. ⚠️ Known blocker: npm run build currently fails on main with 28 pre-existing invalid links in 15 files (verified unrelated to any agent change). The agent verifies its work with the build per agents.md, so real runs will halt-and-report until those links are fixed. Fixing them is a good first candidate ticket.

Future work (deliberately out of scope)

• Reviewer/verifier agent as a second pass
• Label- or webhook-triggered dispatch from Linear
• Hard diff-allowlist guard step

[cloudflare-workers-and-pages]

Deploying localstack-docs with    Cloudflare Pages

Latest commit:	d22e70c
Status:	✅  Deploy successful!
Preview URL:	https://b95d5698.localstack-docs.pages.dev
Branch Preview URL:	https://doc-363-docs-run-mvp-agents.localstack-docs.pages.dev

View logs