What the agent does
The agent reads how the site is built and deployed before it writes a workflow. In a site like vuejs/docs, package.json has dev, build and preview scripts that call vitepress, a type script that runs vue-tsc --noEmit, and a preinstall hook of npx only-allow pnpm. It pins packageManager to pnpm 10.33.0, requires Node 20 or later in engines, depends on vitepress 2.0.0-alpha.17 with a pnpm override that maps its vite to version 8.0.7, and lists vitepress-plugin-llms and vitepress-plugin-group-icons as dev dependencies. netlify.toml builds with pnpm run build on Node 24 and publishes .vitepress/dist, and vercel.json only sets cache headers and rewrites. The only workflow in .github/workflows/ is automerge.yml, which auto-merges Dependabot updates to @vue/theme. .vitepress/config.ts sets srcDir to src, excludes tutorial/**/description.md, and never sets ignoreDeadLinks, so a build fails on a dead internal link by default. A pull request today gets no check at all; a broken link or a failing build is found by the deploy.
Then it writes .github/workflows/ci.yml. It runs on pull_request and on push to the default branch, with a concurrency group keyed on the ref and cancel-in-progress: true so a force-push cancels the stale build. The job checks out the repository, sets up pnpm through pnpm/action-setup, which reads the version from packageManager, sets up Node 24 to match netlify.toml with cache: pnpm, runs pnpm install --frozen-lockfile so a lockfile drift fails loudly, and runs pnpm run build. Because ignoreDeadLinks is unset, that one step is also the dead-link check: VitePress stops the build and prints every dead link with its source file.
The type check is added only if it passes today. The agent runs pnpm run type in its sandbox first; if vue-tsc is clean it becomes a second step, and if it reports existing errors the agent leaves it out and lists the errors in the pull request, because a check that is red on day one gets ignored. It does the same for the build itself: it runs pnpm run build on the current default branch, reads the dead-link output if there is any, and either confirms a clean build or lists the links so the team can decide whether to fix them or add targeted entries to ignoreDeadLinks.
The workflow is linted with actionlint, the automerge.yml workflow is left as it is, and a sentence is added to the Contributing section of README.md saying pull requests run the build. The agent does not touch .vitepress/config.ts, the content under src/ or the deploy configuration, so the only change in behaviour is that a pull request now shows a check.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add a build check for this VitePress site. Read package.json, netlify.toml, vercel.json, .vitepress/config.ts, README.md and the existing workflow under .github/workflows first. Write .github/workflows/ci.yml that runs on pull requests and on pushes to the default branch with a concurrency group that cancels stale runs, sets up pnpm from the packageManager field, sets up Node 24 with the pnpm cache, runs pnpm install --frozen-lockfile and then pnpm run build. Run pnpm run build in the sandbox first and record whether it passes or which dead links it reports; do not set ignoreDeadLinks. Run pnpm run type too, and add it as a step only if it passes today, otherwise list its errors in the pull request. Run actionlint on the new workflow, leave automerge.yml and the content untouched, add one sentence to the README's Contributing section, and open a pull request that quotes the build result.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that adds .github/workflows/ci.yml and one sentence to README.md. The description quotes the result of pnpm run build on the current branch, either the final line of a clean build or the dead-link list VitePress printed with each source file, says whether vue-tsc was clean and therefore added as a step, and names Node 24 and the pnpm version the workflow uses and where each came from.
The run's record keeps the pnpm install --frozen-lockfile output, the full VitePress build log, the vue-tsc output and the actionlint result, so a reviewer can see the exact commands the workflow will run already ran once in a clean environment.
Before merging, a reviewer checks the pull request's own workflow run is green, decides what to do with any dead links the build reported, and confirms the Node version matches what Netlify builds with so the check and the deploy cannot disagree.
Run it on every documentation repository
A team that owns several VitePress sites sends this body once per repository to POST /o/{org}/sessions, each with its own repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started rather than a second pull request. Each run reads that site's own package.json and deploy configuration, so a site on npm and Node 20 gets a workflow that matches it rather than a copy of this one.
After the workflow is merged, no Rush run is needed per pull request: GitHub runs the build check itself. A webhook_url on the key reports each setup run as run.completed with the pull request in result, and a run.failed names the site whose build does not pass today and needs a person first.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A workflow written without running it is a guess about the package manager, the Node version and whether the build passes at all. The agent installs with the real lockfile, runs the real VitePress build and the real vue-tsc in its own sandbox, and the first time the check is red is in that sandbox, with the dead links listed, not on a contributor's first pull request.
The build log stays with the run and is quoted in the pull request, so the team decides about existing dead links with the list in front of them, and the reviewer's only job is to confirm the check runs green on the pull request that adds it.
Frequently asked questions
Will it set ignoreDeadLinks to make the build pass?
No. The prompt forbids it, because the dead-link failure is the point of the check. If the current branch has dead links, the pull request lists them and the team chooses between fixing them and adding specific patterns to ignoreDeadLinks in .vitepress/config.ts.
Why Node 24 when engines says 20 or later?
Because netlify.toml sets NODE_VERSION to 24, and a check that builds with a different Node than the deploy can pass while the deploy fails. The agent reads the deploy configuration and matches it, and names the source in the pull request.
Does the check replace the Netlify deploy preview?
No. The preview still builds and publishes the site; the workflow adds a required-check candidate that fails fast on a broken build or a dead link, before anyone opens the preview. The two run the same pnpm run build command.
Why is the type check optional?
The agent runs pnpm run type first and adds it only if vue-tsc is clean today. A step that fails on the day it is added teaches contributors to ignore the check, so existing errors are listed in the pull request for a separate fix instead.