What the agent does
The agent starts from the Linear issue and reads how posts are modelled before it adds a field. In a blog like satnaing/astro-paper, src/content.config.ts defines the posts collection with Astro's glob loader over src/content/posts matching **/[^_]*.{md,mdx}, and a zod schema with title, description, a required pubDatetime, optional modDatetime, author defaulting to the site author, featured, draft, tags defaulting to others, ogImage, canonicalURL, hideEditPost and timezone. src/pages/posts/[...slug]/index.astro builds its paths from getSortedPosts, which filters drafts and scheduled posts through postFilter and sorts newest first by modDatetime or pubDatetime, and passes a prevPost and nextPost to AdjacentPostNav.astro, which links to the chronologically adjacent posts under the share links. Tags already have the shape a series needs: src/utils/getUniqueTags.ts collects slugs with slugifyStr, src/pages/tags/index.astro lists them, and src/pages/tags/[tag]/[...page].astro paginates each tag's posts with config.posts.perPage, which astro-paper.config.ts sets to 4. Strings live in src/i18n/lang/en.ts with their types in src/i18n/types.ts, and src/content/posts/adding-new-post.mdx documents every frontmatter property in a table. There is no series concept anywhere in the tree.
The change follows the tag pattern with one difference: order. The schema gains series: z.string().optional() and seriesOrder: z.number().int().positive().optional(), so astro check refuses a post that sets one without the other. src/utils/getSeries.ts groups the filtered posts by the slugified series name, sorts each group by seriesOrder and then pubDatetime, and returns the series with their display names and parts; it reuses postFilter so a draft never counts as a part. src/pages/series/index.astro lists every series with its part count, and src/pages/series/[series].astro renders one series in order with Card.astro, under Breadcrumb, Main and Footer the way the tag pages do, without pagination because a series is read in order. @astrojs/sitemap picks the new routes up on its own.
On the post page, a new SeriesNav.astro under src/pages/posts/[...slug]/_components renders above the article for a post that belongs to a series: the series name linked to its page, Part n of m, and links to the previous and next part, built with getPostUrl so posts in subdirectories keep their URL segments. It carries data-pagefind-ignore like AdjacentPostNav.astro, so the Pagefind index does not fill with navigation text. en.ts and types.ts get seriesTitle, seriesDesc and a post.seriesPart string, the frontmatter table in adding-new-post.mdx gets rows for the two new properties, and two of the example posts under src/content/posts/examples are given a series so the feature is visible in the demo content.
There are no tests in the repository; the types and the build are the check. pnpm build runs astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/, pnpm lint runs ESLint with eslint-plugin-astro, and pnpm format:check runs Prettier with its Astro and Tailwind plugins. .github/workflows/ci.yml runs those three on Node 24 with pnpm 11.3.0 under a three-minute timeout, so the agent does the same in its sandbox, then runs astro preview and fetches /series/, one series page and one post in the series to read the navigator in the HTML before it opens the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "A Linear issue labelled agent says: \"Add post series: a series name and order in frontmatter, a part navigator on each post in a series, and a page per series.\" Do the work in this repository. Read package.json, astro.config.ts, astro-paper.config.ts, src/content.config.ts, src/pages/posts/[...slug]/index.astro and its _components, src/pages/tags/index.astro, src/pages/tags/[tag]/[...page].astro, src/utils/getUniqueTags.ts, src/utils/getSortedPosts.ts, src/utils/postFilter.ts, src/utils/getPostPaths.ts, src/components/Card.astro, src/i18n/lang/en.ts, src/i18n/types.ts, src/content/posts/adding-new-post.mdx and .github/workflows/ci.yml first. Add optional series and seriesOrder fields to the posts schema, refined so one is not set without the other. Add src/utils/getSeries.ts that groups filtered posts by slugified series and orders parts by seriesOrder then pubDatetime. Add src/pages/series/index.astro and src/pages/series/[series].astro modelled on the tag pages, without pagination. Add a SeriesNav component beside AdjacentPostNav that shows the series link, Part n of m and previous and next part links, marked data-pagefind-ignore, and render it above the article. Add the i18n strings and their types, document the two properties in adding-new-post.mdx, and give two example posts a series. Run pnpm install --frozen-lockfile, pnpm lint, pnpm format:check and pnpm build, then astro preview and fetch the series index, one series page and one post to read the navigator. Do not change astro.config.ts, the Pagefind step or any workflow. Open a pull request that links the issue, lists the files and quotes the check, lint and build output.",
"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 on its own branch that changes src/content.config.ts, src/pages/posts/[...slug]/index.astro, src/i18n/lang/en.ts, src/i18n/types.ts and src/content/posts/adding-new-post.mdx, adds src/utils/getSeries.ts, the two pages under src/pages/series and SeriesNav.astro, and sets the new frontmatter on two example posts. The body links the Linear issue, lists the files, explains the ordering rule and the refinement on the schema, and quotes astro check, the lint, the format check and the build summary with the Pagefind index step.
The transcript keeps the install from pnpm-lock.yaml, each check with its output including any astro check failure before the types were right, the build, and the three fetches from astro preview that show the navigator and the series page in rendered HTML. GET /o/{org}/p/{project}/sessions/{id}/changes returns the diff per file.
Before merging, a reviewer checks that a draft part is excluded from Part n of m the way postFilter excludes it elsewhere, that two posts with the same seriesOrder sort deterministically, that the series pages render with the Breadcrumb and Main components rather than a new layout, and that astro check is clean with the new optional fields.
Run it on every Linear issue labelled agent
In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue in the Project's repository. The trigger adds the issue's text after the saved prompt, so each issue carries its own wording, such as whether series pages should paginate or how the navigator should read, and it fills in no placeholder. Only a change by someone in your Rush org fires it; changes made by an app integration never do, and the automation's max_runs_per_hour bounds how many runs a burst of labelling starts.
From your own server, the same run is one POST /o/{org}/sessions per issue: put the repository in resources, and add the issue's https://linear.app/<workspace>/issue/<ID> URL there too so Rush reads it through your Linear connection into the prompt. A webhook_url on that key posts run.completed or run.failed when the turn finishes, with data.session_url to read the pull request.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A content-collection change is only real once astro check has typed the new frontmatter and astro build has rendered every post with it, and the Pagefind step after the build is where a navigator without data-pagefind-ignore quietly pollutes search. In a Rush sandbox the agent installs from the lockfile with the pnpm version CI uses, runs the three checks end to end and previews the result, so the pull request arrives with rendered HTML rather than a promise.
A label in Linear becomes a reviewable change with the evidence attached: the transcript shows the agent reading the tag pages and getPostPaths.ts before writing the series pages, so URLs for posts in subdirectories keep working, and several labelled Astro issues run at once, each in its own sandbox with its own branch.
Frequently asked questions
Do existing posts need a change?
No. Both fields are optional in the schema, so every post without them builds as before and shows no navigator. Only a post that sets series must also set seriesOrder, which the refinement enforces at astro check time rather than at runtime.
Why is the series page not paginated like a tag page?
Because a series is read in order and is rarely longer than a handful of parts, a single ordered list is the clearer page. The tag pages keep their pagination at config.posts.perPage. Say in the issue if your series are long and the agent paginates the series page the same way.
How are parts ordered?
By seriesOrder first and pubDatetime second, so two parts with the same order number still sort the same way on every build. Drafts and scheduled posts are excluded through postFilter, the same rule the home page and the tag pages apply.
Will the navigator show up in site search?
No. SeriesNav.astro carries data-pagefind-ignore like the adjacent-post navigation, so Pagefind indexes the article and not the part links. The search page in src/pages/search.astro is unchanged.
Does it work for posts in subdirectories?
Yes. Links in the navigator and on the series page are built with getPostUrl, the same helper Card.astro uses, which turns a post's directory segments into URL segments, so a part under src/content/posts/examples links to /posts/examples/<slug> as it does elsewhere.
More Astro jobs
More jobs like this: Turn a Linear label into a PR
- Add Priority Classes to Kubernetes Manifests (Kubernetes)
- Add Product Reviews to a Medusa Store (Medusa)
- Add Prometheus Metrics to an aiohttp App (aiohttp)