What the agent does
The agent reads how posts become pages before it adds a flag. In a blog shaped like gatsbyjs/gatsby-starter-blog, gatsby-node.js queries allMarkdownRemark sorted by date in createPages, calls createPage for each node with previousPostId and nextPostId in the context, sets a slug field in onCreateNode, and declares the Frontmatter type with title, description and date in createSchemaCustomization. src/pages/index.js runs its own allMarkdownRemark query for the list, src/templates/blog-post.js fetches the previous and next posts by id, and gatsby-config.js gives gatsby-plugin-feed a third query for /rss.xml. Posts live in content/blog/<slug>/index.md with title, date and an optional description in the frontmatter. package.json has Gatsby 5 with React 18, a prettier 2 format script, and a test script that only prints a reminder to write tests.
It then adds one decision in one place. createSchemaCustomization gains draft: Boolean on Frontmatter, so a post without the key reads as null instead of failing the query, and onCreateNode adds a second field beside slug, fields.released, which is true unless frontmatter.draft is true, or when process.env.NODE_ENV is development, so gatsby develop shows drafts and gatsby build does not. Every query then filters on fields: { released: { eq: true } }: the createPages query in gatsby-node.js, so no page is created for a draft and the previous and next links skip it; the pageQuery in src/pages/index.js; and the feed query inside gatsby-config.js, so a draft never reaches rss.xml.
The agent does not add posts to the reader's content. To prove the filter, it marks one existing post as draft: true in the sandbox, runs gatsby build, checks that public/ has no directory for that slug, that public/index.html does not link to it, and that public/rss.xml has no item for it, then reverts the frontmatter. It runs gatsby develop with the same flag and fetches the draft's URL from the dev server to confirm it still renders there. It also runs npm run format so the changed files match the .prettierrc the repository already uses.
The README.md gets a short section under the content notes saying how to mark a draft, that drafts are visible in gatsby develop only, and that a draft's frontmatter still needs a date because the index sorts on it. Nothing changes in gatsby-browser.js, gatsby-ssr.js or the Seo and Bio components, and the using-typescript.tsx page is untouched because it is not a markdown post.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "codex",
"input": "Add draft posts to this Gatsby blog and open a pull request. Read package.json, gatsby-config.js, gatsby-node.js, src/pages/index.js, src/templates/blog-post.js, README.md and one post under content/blog first. In gatsby-node.js add draft: Boolean to the Frontmatter type in createSchemaCustomization, and in onCreateNode add a fields.released boolean beside slug that is true unless frontmatter.draft is true, or always true when NODE_ENV is development. Filter on fields.released in the createPages query, in the pageQuery of src/pages/index.js and in the gatsby-plugin-feed query in gatsby-config.js, so a draft gets no page, no index entry, no previous or next link and no RSS item in a build, but still renders under gatsby develop. Do not add or change any post. To verify, temporarily mark one existing post draft: true, run gatsby build, confirm public/ has no directory for its slug and public/index.html and public/rss.xml do not mention it, run gatsby develop and fetch the draft's URL to confirm it renders there, then revert the frontmatter. Run npm run format. Add a short README section on marking drafts. Paste the build output and the checks in the pull request.",
"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 changes gatsby-node.js (the draft type, the released field and the filtered createPages query), src/pages/index.js (the filtered pageQuery), gatsby-config.js (the filtered feed query) and README.md. No file under content/blog changes. The description shows the gatsby build output from the sandbox, the ls public/ listing without the draft's slug, a grep of public/index.html and public/rss.xml finding nothing, and the dev server answering the draft's URL.
The repository has no CI workflow and its test script only prints a reminder, so the build and the three checks in the description are the evidence. The agent pushes one commit for the code and one for the README, and says in the description that the verification post was reverted.
A reviewer checks that the filter is on fields.released everywhere a post is listed, including the feed, that the development branch of the field is the only reason drafts appear anywhere, that the previous and next links in blog-post.js come from the filtered list in gatsby-node.js rather than a separate query, and that a post with no draft key is still published. Then they merge and start writing with draft: true.
Run it on every content feature request
A team running several Gatsby sites from the same starter starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. Each run reads that site's own gatsby-node.js and feed configuration, so a site that already has a createSchemaCustomization block or a second feed gets the filter added in the right places, and each ends in its own pull request. A request_id makes a retried call return the run it already started.
The key's webhook_url receives run.completed for each run it starts, with session_url for the result, so a script can post the pull request links to the team channel as they land.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The draft flag itself is three filters, and the mistake is always the fourth place you forgot, usually the RSS feed or the previous and next links. In a Rush sandbox the agent runs a real gatsby build with a post marked as draft, reads public/ to see the page is absent and the feed is clean, then runs gatsby develop to see the same post still renders, and every command and its output stays in the transcript.
Nothing has to be installed or rebuilt on a laptop, and the content directory is left as it was. The pull request carries the proof of both behaviours, so a reviewer reads a diff of three files and a build log rather than reproducing the check.
Frequently asked questions
Why a computed field instead of filtering on frontmatter.draft directly?
Page queries cannot branch on NODE_ENV, so a filter on frontmatter.draft would hide drafts in gatsby develop too. Computing fields.released once in onCreateNode lets the development server show drafts while the build hides them, and every query filters on the same boolean.
Does a draft still need a date?
Yes. The index and the feed sort on frontmatter.date, and the createPages query uses the same order to compute previous and next links. The README section the agent adds says so; a draft without a date would sort to one end rather than fail.
Will existing posts without a draft key disappear?
No. Declaring draft: Boolean in createSchemaCustomization makes a missing key read as null, and released is true for anything that is not exactly true. The verification in the sandbox builds the whole site with the three existing posts and shows them all in public/.
Can I preview a draft on a deployed branch?
Not with this change alone, since the build hides drafts whenever NODE_ENV is not development. If you want a preview deployment that shows drafts, ask in the prompt for a second variable such as GATSBY_SHOW_DRAFTS to be read in onCreateNode, and set it in that deployment only.
More Gatsby jobs
The same job on other stacks
- Add Draft Posts to a VitePress Blog (VitePress)