What the agent does
The agent reads how posts are built before adding a list to them. In a site shaped like gatsbyjs/gatsby-starter-blog, package.json runs Gatsby 5.14 with gatsby-transformer-remark, gatsby-source-filesystem over content/blog, and gatsby-plugin-feed; the test script only prints a reminder and exits 1. gatsby-node.js queries allMarkdownRemark sorted by date, creates one page per post from src/templates/blog-post.js, and passes previousPostId and nextPostId in the page context. Its createSchemaCustomization declares Frontmatter as title, description and date, so a tags field would be absent from the schema until added. The three sample posts under content/blog/ have no tags, and blog-post.js already renders a previous and next link in .blog-post-nav.
The agent adds tags: [String] to the Frontmatter type in createSchemaCustomization, so a post without tags still builds, and gives the three sample posts two or three tags each so the feature is visible in the starter. In createPages it computes, for each post, the ids of up to three other posts ordered by how many tags they share, with the most recent post winning ties and recency alone as the fallback when a post has no tags or shares none. Those ids go into the page context as relatedPostIds, which keeps blog-post.js a pure query: the template's pageQuery gains a related: allMarkdownRemark(filter: { id: { in: $relatedPostIds } }) block selecting fields.slug, frontmatter.title, frontmatter.date and frontmatter.description.
In blog-post.js a RelatedPosts component renders those nodes as a short list between the article footer and the existing previous and next navigation, using the same <Link> and the post-list-item class that src/pages/index.js already styles in src/style.css, so there is no new CSS beyond a heading margin. The order of the list follows relatedPostIds rather than GraphQL's default, because the ranking was computed in gatsby-node.js. The feed in gatsby-config.js and the Seo component are untouched.
There is no test runner, so the proof is the build. The agent runs npm ci, npm run build and npm run serve, opens two post pages in the sandbox browser, and checks the related list and its links. It also runs npx prettier --check with the repository's .prettierrc, since the format script defines the style, and pastes the build output and a screenshot of one post in the pull request.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add related posts to this Gatsby blog and open a pull request. Read package.json, gatsby-config.js, gatsby-node.js, src/templates/blog-post.js, src/pages/index.js, src/style.css and the posts under content/blog/ first. Add tags: [String] to the Frontmatter type in createSchemaCustomization and give each sample post two or three tags. In createPages, compute up to three related post ids per post ranked by shared tag count, newest first on ties, falling back to the newest other posts, and pass them as relatedPostIds in the page context. Extend the pageQuery in blog-post.js with a related query filtered by those ids and render them in a RelatedPosts list between the article and the previous/next nav, reusing the post-list-item styling, in the order of relatedPostIds. Run npm ci, npm run build, serve the site and verify two post pages in the browser, run prettier --check, and paste the build output in the pull request. Do not change the feed, the Seo component or the index page.",
"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 changing gatsby-node.js, src/templates/blog-post.js, the three content/blog/*/index.md files and, if a heading needs spacing, src/style.css. The description shows the gatsby build output with the page count, the prettier --check result, and a screenshot of a post page with its related list under the article.
The starter has no CI workflow, so the pull request's checks are whatever the team has added; the run's own record holds the build and the browser session. A reviewer opens the preview, confirms that a post with no tags still builds and shows the recency fallback, and that the list never includes the post itself.
Before merging, the reviewer decides how many related posts to show and whether the ranking should also weight the description text, both of which are single constants in gatsby-node.js. Then they tag their real posts, since the starter's three samples are only there to show the list working.
Run it on every Linear issue labelled agent
A Rush automation with a linear trigger starts one run for each issue that gets the label, with this prompt as the instructions and the issue's title and description added after it. A content team's issue that asks for related posts on a specific site becomes a pull request on that site's repository with a preview the team can open.
Each run is independent and has its own max_runs_per_hour cap on the automation, so several blog issues labelled in one afternoon become several separate pull requests.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Related posts in Gatsby is a build-time problem: the ranking has to happen in gatsby-node.js where every post is in hand, and the only proof is a full gatsby build plus looking at the pages. In a Rush sandbox the agent runs the build, serves the site, opens the pages in a browser and keeps the screenshots with the run's record, so the pull request shows the list rather than describing it.
The same request works on any Markdown-based Gatsby blog, and because the computation is in createPages, a site with hundreds of posts gets the same ranking with no client-side cost. Reviewers read a diff and a screenshot instead of pulling the branch and building locally.
Frequently asked questions
Do I have to tag every post?
No. tags is optional in the schema, and a post with none gets the three most recent other posts. Tagging is what makes the list relevant, so the pull request tags the sample posts to show the difference.
Why compute the ranking in gatsby-node.js instead of the template?
The template's GraphQL query cannot sort by shared tag count, and doing it in React would ship every post's tags to the browser. createPages has all posts in memory once and passes only ids in the page context.
Will it slow down the build?
The ranking is a pass over the posts for each post, which is trivial for a blog of a few hundred entries. The pull request notes where to switch to a tag index if a site has many thousands.
Does it change the RSS feed or SEO markup?
No. gatsby-plugin-feed in gatsby-config.js and the Seo component are not touched, and the related list is plain links inside the existing Layout.
More Gatsby jobs
The same job on other stacks
- Add Related Posts to a Hugo Blog (Hugo)
- Add Related Posts to a Jekyll Blog (Jekyll)
- Add Related Posts to a Symfony Blog (Symfony)