This site is the payload,
not the point.

Why I built this

Most “AI writes code” demos stop at a snippet in a chat window. I wanted to see if an agent could actually ship, through the same machinery a human's change has to earn its way through: GitHub issues, pull requests, CI, a second reviewing agent, preview deploys, and a human merge. So I built the loop and ran it for real, not just designed it.

Here's how it works: a contributor opens a GitHub issue in plain language, a protocol name and a sentence about what it should teach. An author agent researches the spec, writes the flow, and opens a pull request. An independent, adversarial reviewer agent fact-checks that PR against the primary spec before I see it. CI, the reviewer, and a Vercel preview all run in parallel. I check the agent's work against the reviewer's findings, walk the preview, and make the merge call. That's the whole loop.

Why IAM protocols, specifically

I needed a domain where getting it wrong would be embarrassing and getting it right would be checkable, not just plausible-sounding. IAM and security protocols fit: OAuth 2.0, OIDC, SAML, SPIFFE, and the rest are precisely specified in RFCs and standards docs, so an agent's output can be checked word-for-word against a citable section. The educational app is the concrete domain I used to prove the pipeline works. It's the payload the pipeline was built to deliver, not the thing I'm actually trying to show you.

Two agents, different jobs

An author agent implements the request. It never touches the rendering engine, only a typed data file (steps.ts) and prose (content.mdx) that a Zod schema validates. A second, independent Security Architect reviewer agent is adversarial to the author's output: it fetches the flow's cited specs with WebFetch and checks the content against those primary sources, flagging fabricated parameters, wrong required/optional designations, and mislabeled security properties. It's advisory, not a merge block. I stay the decision-maker.

Proof it actually works

• An agent-authored feature is live in production. The OAuth 2.0 Client Credentials flow was specified in an issue, built by the author agent, gated, and merged. It's the /oauth2/client-credentials/ page on this site right now.
• The reviewer catches real inaccuracies. I planted a falsehood on purpose (“PKCE requires an S512 method”), and the reviewer flagged it with citations to RFC 7636 §6.2.2 and §4.2. It even caught the internal contradiction with the flow's own labels.
• It generalizes to domains it's never seen. A SPIFFE/SPIRE X.509-SVID flow, a protocol the engine had no prior content for, was authored by the agent and passed a spec-grounded accuracy review against the SPIFFE standards.

I don't know how far this generalizes past IAM protocols. What I can say is it held up on three different specs, one of them completely new to the system, and the reviewer caught a mistake I put there on purpose.

Two different kinds of “not real”, don't mix them up

The pipeline is real: the agent runs, the PRs are real PRs, the reviewer is a real second model checking real citations, and the merges are real production deploys gated by real CI. The payload data inside each protocol flow, tokens, client secrets, request bodies, is deliberately fake and illustrative, so nobody mistakes a teaching example for a live credential. The footer's “payloads are illustrative” disclaimer is about that content. It has nothing to do with whether the pipeline that shipped it is real.

What's still a proof of concept, honestly

The accuracy reviewer is advisory, not a required check. A human still has to read it and decide. Trigger authorization is gated on GitHub's author_association, so only trusted collaborators can spawn a run on a public repo; anyone can file a request, not everyone can spend the API budget. Both agent runs are bounded by --max-turns as a cost backstop. None of that is hidden. It's written up in the docs, along with the real production bugs I hit shipping this (a Vercel build that skipped codegen, a YAML form that silently fell back to a blank editor, a bot-to-bot permission gap) and how I fixed each one.

Read the source of truth

This page is a summary. The full spec, the pipeline end-to-end, the content engine and schema contract, the design decisions, and the operations runbook, lives in the repo's docs/ folder:

• docs/README.md - the thesis and the proof points, in one page
• docs/The-Agentic-Pipeline.md - issue to author agent to PR to gates to reviewer agent to production, stage by stage
• docs/The-Content-Engine.md - why “a feature is data, not code” is what makes the agent's work safe to delegate
• docs/Design-Decisions-and-Lessons.md - the real bugs I hit shipping this, and how I fixed each one
• docs/Operations-and-Extending.md - the runbook: secrets, gates, costs, how to add a flow

Or just go look at the code: github.com/koherenc3/protocol-academy.