Luke Manning - Blog — AI https://lukemanning.ie/ Breaking things. Building things. Writing about it. (tag: AI) Wed, 30 Sep 2026 12:46:24 GMT https://validator.w3.org/feed/docs/rss2.html https://github.com/jpmonette/feed en All rights reserved 2026, Luke Manning <![CDATA[My Agent Closed Most of the Open Projex Issues in One Round Without Me Reading the Code]]> https://lukemanning.ie/blog/my-agent-closed-most-projex-issues-in-one-round https://lukemanning.ie/blog/my-agent-closed-most-projex-issues-in-one-round Wed, 19 Aug 2026 00:00:00 GMT On a Saturday afternoon in August, I told my agent to fix every open issue in the Projex repo and prepare a release. There were ten open. Some were HIGH priority. Some were LOW.

I went for a walk.

When I came back, the work had landed across three branches. Each subagent had worked in its own worktree on its own branch. The build was green on each one. The tests were green. The lint was green. The typecheck was green. The release manager subagent had drafted the changelog. Nine of the ten issues were closed. The tenth stayed open — it needed a real union restructure, not a mechanical fix.

I had not read a single line of the diff yet.

What I actually asked for

I had a backlog of small things in the Projex repo. Tagged-union cleanups. Type tightening. Documentation gaps. A bug where one of the smart-grid props was a documented prop but a no-op at runtime. A redundancy where two functions with slightly different spellings did the same thing.

I described this to my main agent. The main agent looked at the issue tracker, saw the labels (bug, enhancement, documentation), grouped them by file area, and dispatched three subagents in parallel.

One subagent got the package.json + bundling issues. One got the type-system + tagged-union issues. One got the documentation + test-coverage issues. Each one worked in a separate worktree on a separate branch. Each one committed locally and reported back. A fourth subagent, the release manager, handled release prep alongside them: the version bump and the changelog.

I watched the transcript. Mostly I stayed out of the way. I made tea.

What the subagents actually did

I saw the dispatch messages. I saw the report-back messages. I did not read the intermediate diffs. The subagents were set up to commit per-issue. Each commit was meant to be independently reviewable.

A few things I noticed in the report-backs:

  • One subagent caught a redundancy I hadn't seen. Two exported functions, normalizeStats and normaliseStats, with the American and British spellings. Both did the same thing. The codebase had drifted to the British spelling in the actual logic. The American spelling was the alias. Both were exported. The subagent deprecated the American one with a JSDoc tag and updated the docs to point at the British spelling.
  • One subagent found a related issue while fixing another one. While narrowing the ProjectStats union, it noticed FetchProjectDataResult.commits was using undefined while sibling fields used null. The subagent opened a new issue and included the fix in the same branch.
  • One subagent flagged a peer-dependency problem I had been ignoring for two months. The CLI packages (ts-morph, chalk, @inquirer/prompts, commander) were installed by every consumer, even ones who only imported the components. The subagent moved them to optional peerDependencies so consumers importing only components stopped dragging in the CLI bundle.

None of these were in my original brief. The subagents went past the edges of what I asked for, in the direction of "things that were obviously wrong in the same file area."

Where I read the code

The first time I read any of the code was after all three subagents finished and opened their PRs. I skimmed the diffs before merging. Not a line-by-line review. A sanity check.

I was looking for decisions the AI made without asking me. Function names I wouldn't have picked. Behaviour that wasn't in the brief. Edits that touched code outside the file area I asked about. The kind of things a real code review catches, except I was reviewing the decisions, not the code.

Some of the diffs were four lines. Some were thirty. None of them were complex enough to need a real review. They were tagged-union narrowings, JSDoc additions, dependency relocations. The kind of work where you skim it once, you understand it, you move on.

If I'd skimmed each PR as it landed, I'd have read the rename with no idea the docs were about to change under it. Reading the batch, I could see the normaliseStats deprecation and the docs update pointing at it in the same sitting. The batch skim was faster than piecemeal would have been.

Where I did intervene

I didn't push back on any of the code. The three branches each shipped clean. I steered the architecture around the loop, not the code inside it.

The dispatch went out as three parallel opencode run invocations, not three subagents. I asked for that change when the opencode TUI failed on the first attempt and the right path was to skip the interactive layer. I also argued for splitting the release prep out from the fix work, because trying to do both in the same dispatch kept blocking on the release-manager hitting its timeout before the fix branches landed.

What this loop replaced

My previous loop was one PR at a time. I'd describe an issue to the agent. The agent would open a PR. I'd skim it, sanity-check the decisions, merge or push back. One issue, one PR, one round of skimming. Repeat.

For this kind of small mechanical work, that's fine. It works. But the context switching adds up. Each PR is its own session — its own dispatch, its own transcript, its own review pass. The overhead is small per PR and large per backlog.

The new loop:

  1. Describe the backlog.
  2. Wait.
  3. Skim the batch of PRs.
  4. Push the release prep.

The release prep runs alongside the fix work instead of after it. One description covers all of them.

I want to be careful about what I'm claiming here. I'm not claiming the subagents did better work than the agent would have done one PR at a time. Most of these issues were mechanical. The interesting decisions — which redundancy to deprecate, which naming to standardize — the agent would have surfaced them either way, given the brief. What I'm claiming is that the per-PR overhead moved out of my hands and the interesting decisions stayed in my hands.

Reading at the end, not in the middle

I did not read the code while it was being written.

In the old loop, I skimmed each PR after the agent opened it. One PR at a time.

In the new loop, the skim happened after the writing finished across all three PRs. The subagents were the feedback loop during the work. I was the feedback loop at the end.

There's a different cost structure. A wrong fix in the old loop was caught in the per-PR skim, or it shipped. A wrong fix in the new loop is caught in the batch skim, or it ships.

I shipped none of the wrong fixes in this batch. The issues were mechanical and the code area was small. If I'd asked the subagents to redesign the normalise function, I would have read every line, pushed back, rewritten pieces.

The loop works for the kind of work that has a clear right answer. The loop does not work for the kind of work that needs taste. I haven't found the line yet.

For this batch, the line was "moves stuff around, adds JSDoc, narrows types." Below the line, I delegated. Above the line, I didn't. The line is in a different place than I would have guessed.

Running it again

I'm going to run this loop again. On a different repo. On a different kind of work.

I want to see what happens when the issues aren't mechanical. I want to see where the line moves. I want to see what kinds of work I delegate that I later wish I hadn't, and what kinds I keep that the loop could have handled.

I'm not going to delegate design decisions. I'm not going to delegate "what should this library do". I'm going to delegate "make this library do what it already says it does, correctly."

The batch skim at the end is non-negotiable. That's the part I own.

]]> On a Saturday afternoon in August, I told my agent to fix every open issue in the Projex repo and prepare a release. There were ten open. Some were HIGH priority. Some were LOW.

I went for a walk.

When I came back, the work had landed across three branches. Each subagent had worked in its own worktree on its own branch. The build was green on each one. The tests were green. The lint was green. The typecheck was green. The release manager subagent had drafted the changelog. Nine of the ten issues were closed. The tenth stayed open — it needed a real union restructure, not a mechanical fix.

I had not read a single line of the diff yet.

What I actually asked for

I had a backlog of small things in the Projex repo. Tagged-union cleanups. Type tightening. Documentation gaps. A bug where one of the smart-grid props was a documented prop but a no-op at runtime. A redundancy where two functions with slightly different spellings did the same thing.

I described this to my main agent. The main agent looked at the issue tracker, saw the labels (bug, enhancement, documentation), grouped them by file area, and dispatched three subagents in parallel.

One subagent got the package.json + bundling issues. One got the type-system + tagged-union issues. One got the documentation + test-coverage issues. Each one worked in a separate worktree on a separate branch. Each one committed locally and reported back. A fourth subagent, the release manager, handled release prep alongside them: the version bump and the changelog.

I watched the transcript. Mostly I stayed out of the way. I made tea.

What the subagents actually did

I saw the dispatch messages. I saw the report-back messages. I did not read the intermediate diffs. The subagents were set up to commit per-issue. Each commit was meant to be independently reviewable.

A few things I noticed in the report-backs:

  • One subagent caught a redundancy I hadn't seen. Two exported functions, normalizeStats and normaliseStats, with the American and British spellings. Both did the same thing. The codebase had drifted to the British spelling in the actual logic. The American spelling was the alias. Both were exported. The subagent deprecated the American one with a JSDoc tag and updated the docs to point at the British spelling.
  • One subagent found a related issue while fixing another one. While narrowing the ProjectStats union, it noticed FetchProjectDataResult.commits was using undefined while sibling fields used null. The subagent opened a new issue and included the fix in the same branch.
  • One subagent flagged a peer-dependency problem I had been ignoring for two months. The CLI packages (ts-morph, chalk, @inquirer/prompts, commander) were installed by every consumer, even ones who only imported the components. The subagent moved them to optional peerDependencies so consumers importing only components stopped dragging in the CLI bundle.

None of these were in my original brief. The subagents went past the edges of what I asked for, in the direction of "things that were obviously wrong in the same file area."

Where I read the code

The first time I read any of the code was after all three subagents finished and opened their PRs. I skimmed the diffs before merging. Not a line-by-line review. A sanity check.

I was looking for decisions the AI made without asking me. Function names I wouldn't have picked. Behaviour that wasn't in the brief. Edits that touched code outside the file area I asked about. The kind of things a real code review catches, except I was reviewing the decisions, not the code.

Some of the diffs were four lines. Some were thirty. None of them were complex enough to need a real review. They were tagged-union narrowings, JSDoc additions, dependency relocations. The kind of work where you skim it once, you understand it, you move on.

If I'd skimmed each PR as it landed, I'd have read the rename with no idea the docs were about to change under it. Reading the batch, I could see the normaliseStats deprecation and the docs update pointing at it in the same sitting. The batch skim was faster than piecemeal would have been.

Where I did intervene

I didn't push back on any of the code. The three branches each shipped clean. I steered the architecture around the loop, not the code inside it.

The dispatch went out as three parallel opencode run invocations, not three subagents. I asked for that change when the opencode TUI failed on the first attempt and the right path was to skip the interactive layer. I also argued for splitting the release prep out from the fix work, because trying to do both in the same dispatch kept blocking on the release-manager hitting its timeout before the fix branches landed.

What this loop replaced

My previous loop was one PR at a time. I'd describe an issue to the agent. The agent would open a PR. I'd skim it, sanity-check the decisions, merge or push back. One issue, one PR, one round of skimming. Repeat.

For this kind of small mechanical work, that's fine. It works. But the context switching adds up. Each PR is its own session — its own dispatch, its own transcript, its own review pass. The overhead is small per PR and large per backlog.

The new loop:

  1. Describe the backlog.
  2. Wait.
  3. Skim the batch of PRs.
  4. Push the release prep.

The release prep runs alongside the fix work instead of after it. One description covers all of them.

I want to be careful about what I'm claiming here. I'm not claiming the subagents did better work than the agent would have done one PR at a time. Most of these issues were mechanical. The interesting decisions — which redundancy to deprecate, which naming to standardize — the agent would have surfaced them either way, given the brief. What I'm claiming is that the per-PR overhead moved out of my hands and the interesting decisions stayed in my hands.

Reading at the end, not in the middle

I did not read the code while it was being written.

In the old loop, I skimmed each PR after the agent opened it. One PR at a time.

In the new loop, the skim happened after the writing finished across all three PRs. The subagents were the feedback loop during the work. I was the feedback loop at the end.

There's a different cost structure. A wrong fix in the old loop was caught in the per-PR skim, or it shipped. A wrong fix in the new loop is caught in the batch skim, or it ships.

I shipped none of the wrong fixes in this batch. The issues were mechanical and the code area was small. If I'd asked the subagents to redesign the normalise function, I would have read every line, pushed back, rewritten pieces.

The loop works for the kind of work that has a clear right answer. The loop does not work for the kind of work that needs taste. I haven't found the line yet.

For this batch, the line was "moves stuff around, adds JSDoc, narrows types." Below the line, I delegated. Above the line, I didn't. The line is in a different place than I would have guessed.

Running it again

I'm going to run this loop again. On a different repo. On a different kind of work.

I want to see what happens when the issues aren't mechanical. I want to see where the line moves. I want to see what kinds of work I delegate that I later wish I hadn't, and what kinds I keep that the loop could have handled.

I'm not going to delegate design decisions. I'm not going to delegate "what should this library do". I'm going to delegate "make this library do what it already says it does, correctly."

The batch skim at the end is non-negotiable. That's the part I own.

]]> ai opencode projex github <![CDATA[Anthropic, Open Source, and Why I Cancelled My Subscription]]> https://lukemanning.ie/blog/anthropic-open-source-walled-garden-clawdbot-opencode https://lukemanning.ie/blog/anthropic-open-source-walled-garden-clawdbot-opencode Fri, 03 Apr 2026 00:00:00 GMT I was using Claude Code daily. I built my entire blog review system with it. I hit session limits constantly and tried to optimise around them. Now I use OpenCode, an open-source agent that works with any provider.

Then one day (maybe a month or two ago) I pulled the latest OpenCode version and Claude subscription support was just gone. Not deprecated. Not moved to a config flag. Removed entirely, because Anthropic demanded it. On top of that, I kept hitting usage limits on my Pro subscription despite paying $20/month. That issue was opened for Max subscribers but people on every tier were hitting the same thing.

I cancelled my Anthropic subscription. I use GLM-4.7 and GLM-5.1 now through OpenCode with a GLM coding subscription. Considering adding a GitHub Copilot subscription so I can still use Anthropic models through OpenCode's API integration. I still use Claude on the web and on my phone. The model is good. The repeated session limit issues and the company's behavior around open source tools is what pushed me away.

The OpenClaw Story

I'd already been watching Anthropic's relationship with open source tools for a while. Then I came across the OpenClaw story. An open source project that got forced to rename because it had "Clawd" in the name. That sent me down a rabbit hole.

Peter Steinberger (steipete on GitHub) built a personal AI assistant. Originally called Warelay. MIT licensed, supports 20+ messaging channels, and has 343k GitHub stars (yes, really). A legit open source project by any measure. The fastest growing in history in terms of stars.

On January 4, 2026, he renamed it to ClawdBot. Makes sense. It's a bot that uses Claude. Clear, descriptive name. A play on the fact it used Claude without using the name Claude.

Three weeks later, he got a letter from Anthropic's legal team.

The project was renamed to "Moltbot" on January 27, 2026. The commit message read: "refactor: rename clawdbot to moltbot with legacy compat." The maintainer confirmed in GitHub issue #2825: "Moltbot is the official name now. Clawdbot has been letter sent by Anthropic."

That name lasted three days. On January 30, another commit: "refactor: rename to openclaw." The project has been OpenClaw ever since.

An open source project with 343k stars, MIT licensed, built by an independent developer, got a trademark letter because its name contained "Clawd." Yeah, obviously a play on "Claude," but still not "Claude."

And that wasn't all. Anthropic also reportedly changed their API to reject any request whose system prompt contains the phrase "Open Claw." Not a rate limit, not a warning, but a hard block. (This was reported by Theo — he runs t3.gg, covers AI and dev tools — I haven't tested it myself.) If that's accurate, it goes way beyond trademark enforcement. That would be technical suppression of a specific open source project.

What Happened to OpenCode

The OpenCode situation is different but follows the same pattern.

For context: OpenCode works with multiple AI providers. You configure it with credentials for whichever provider you want, and it routes requests to your chosen model. Before all this, Claude subscription access was one of those options. You could use your existing Pro or Max subscription through OpenCode instead of being locked into Anthropic's client.

Anthropic added checks to stop third-party tools from impersonating the Claude Code client. This broke people's ability to use their Claude subscriptions through OpenCode, Cursor, and any other third-party harness.

Then they updated their terms of service to explicitly ban using consumer subscriptions (Pro/Max plans) as authentication for third-party tools. So even people paying Anthropic $20/month for Pro can't legally use that subscription through OpenCode. You have to use the Anthropic harness (Claude Code).

OpenCode had its own PR that removed Claude subscription integration entirely, with "Anthropic legal requests" cited as the reason. Not a technical limitation. A legal demand.

I get protecting your trademark. I get not wanting people to think an unofficial tool is officially affiliated with you. But the OpenCode situation isn't about trademark confusion. It's about controlling which tools can access Claude's API and how.

OpenCode wasn't pretending to be Claude Code. It was using Claude as a provider, the same way it uses ChatGPT or any other model. Anthropic decided they didn't want subscription auth flowing through third-party tools, and they had the legal muscle to enforce it. Their stated justification was something about third-party harnesses interfering with their analytics and causing unusual traffic patterns. At least, that's what I gathered. It's hard to know how much of that is genuine concern versus justifying the walled garden.

The rules around what's allowed are vague enough that even people trying to play by them can't get straight answers. Matt Pocock — whose TypeScript stuff I've used for a while — spent over a month trying to get Anthropic to confirm whether his paid Claude Code course was allowed to exist. Their response: "We're working on it." Repeatedly. When pressed for an ETA, same answer. Theo has called this out too — he believes Anthropic keeps the terms vague intentionally so they can move the goalposts later. That tracks with what I've seen.

The Pattern

Anthropic isn't just another company locking everything down. They built MCP (Model Context Protocol) — the protocol that lets OpenCode talk to external tools. And then gave it away. Fully open source. Anthropic doesn't control it. They offer free Claude Max access to open source maintainers. Their output terms are solid; you own what Claude generates.

But then Claude Code has a public GitHub repo with zero source code. Subscription access is tightly controlled — you can't use what you're paying for through a third-party tool. And their legal team sends trademark letters to open source projects with 343k stars.

Then there's the distillation thing.

I read Anthropic's report accusing DeepSeek, Moonshot, and MiniMax of "distillation attacks" against Claude and something felt off. They claimed 24,000 fraudulent accounts and 16+ million exchanges. Wrapped it in national security framing stating that distilled models could be used for bioweapons, etc. And this isn't the first time — Anthropic previously accused Windsurf, X AI, and OpenAI of distillation and, from what I've read, was wrong each time.

The distillation accusations fit the same pattern. Anthropic claims others are exploiting Claude's openness, uses that to justify tighter restrictions, and those restrictions happen to protect their revenue. Could be genuine security concern. Could be strategic. But it's the same thing I keep seeing.

The only major lab that has released zero open-weight models is also the one arguing most loudly that open-weight models are dangerous. I don't think that's a coincidence.

I initially thought the ClawdBot thing was just standard trademark enforcement. But then I kept looking. I'm not sure if this is a fair reading, honestly. I keep going back and forth on it. But the pattern I keep seeing is decisions being made to be open where it benefits Anthropic, and closed where it protects their revenue.

That's absolutely a valid business strategy. It's just not what "open" means. Especially when most of their competitors are making strides to become more open.

Where I'm At

I'm going to keep using OpenCode for now.

I might be wrong about the intent. Maybe Anthropic has good reasons for each individual decision. The ClawdBot rename could be standard trademark enforcement. The OpenCode crackdown could be about subscription terms or it could legitimately be about analytical data being interfered with by third party harnesses.

But when I look at the pattern, it looks like a company building a walled garden around Claude while also contributing genuinely open infrastructure. I don't have a clean conclusion here. I'm still forming my thinking on this. But I know that my workflow got disrupted, an open source project got renamed three times in a month, and the company responsible for both is the same one that open-sourced MCP.

I just don't understand their actions sometimes.

]]> I was using Claude Code daily. I built my entire blog review system with it. I hit session limits constantly and tried to optimise around them. Now I use OpenCode, an open-source agent that works with any provider.

Then one day (maybe a month or two ago) I pulled the latest OpenCode version and Claude subscription support was just gone. Not deprecated. Not moved to a config flag. Removed entirely, because Anthropic demanded it. On top of that, I kept hitting usage limits on my Pro subscription despite paying $20/month. That issue was opened for Max subscribers but people on every tier were hitting the same thing.

I cancelled my Anthropic subscription. I use GLM-4.7 and GLM-5.1 now through OpenCode with a GLM coding subscription. Considering adding a GitHub Copilot subscription so I can still use Anthropic models through OpenCode's API integration. I still use Claude on the web and on my phone. The model is good. The repeated session limit issues and the company's behavior around open source tools is what pushed me away.

The OpenClaw Story

I'd already been watching Anthropic's relationship with open source tools for a while. Then I came across the OpenClaw story. An open source project that got forced to rename because it had "Clawd" in the name. That sent me down a rabbit hole.

Peter Steinberger (steipete on GitHub) built a personal AI assistant. Originally called Warelay. MIT licensed, supports 20+ messaging channels, and has 343k GitHub stars (yes, really). A legit open source project by any measure. The fastest growing in history in terms of stars.

On January 4, 2026, he renamed it to ClawdBot. Makes sense. It's a bot that uses Claude. Clear, descriptive name. A play on the fact it used Claude without using the name Claude.

Three weeks later, he got a letter from Anthropic's legal team.

The project was renamed to "Moltbot" on January 27, 2026. The commit message read: "refactor: rename clawdbot to moltbot with legacy compat." The maintainer confirmed in GitHub issue #2825: "Moltbot is the official name now. Clawdbot has been letter sent by Anthropic."

That name lasted three days. On January 30, another commit: "refactor: rename to openclaw." The project has been OpenClaw ever since.

An open source project with 343k stars, MIT licensed, built by an independent developer, got a trademark letter because its name contained "Clawd." Yeah, obviously a play on "Claude," but still not "Claude."

And that wasn't all. Anthropic also reportedly changed their API to reject any request whose system prompt contains the phrase "Open Claw." Not a rate limit, not a warning, but a hard block. (This was reported by Theo — he runs t3.gg, covers AI and dev tools — I haven't tested it myself.) If that's accurate, it goes way beyond trademark enforcement. That would be technical suppression of a specific open source project.

What Happened to OpenCode

The OpenCode situation is different but follows the same pattern.

For context: OpenCode works with multiple AI providers. You configure it with credentials for whichever provider you want, and it routes requests to your chosen model. Before all this, Claude subscription access was one of those options. You could use your existing Pro or Max subscription through OpenCode instead of being locked into Anthropic's client.

Anthropic added checks to stop third-party tools from impersonating the Claude Code client. This broke people's ability to use their Claude subscriptions through OpenCode, Cursor, and any other third-party harness.

Then they updated their terms of service to explicitly ban using consumer subscriptions (Pro/Max plans) as authentication for third-party tools. So even people paying Anthropic $20/month for Pro can't legally use that subscription through OpenCode. You have to use the Anthropic harness (Claude Code).

OpenCode had its own PR that removed Claude subscription integration entirely, with "Anthropic legal requests" cited as the reason. Not a technical limitation. A legal demand.

I get protecting your trademark. I get not wanting people to think an unofficial tool is officially affiliated with you. But the OpenCode situation isn't about trademark confusion. It's about controlling which tools can access Claude's API and how.

OpenCode wasn't pretending to be Claude Code. It was using Claude as a provider, the same way it uses ChatGPT or any other model. Anthropic decided they didn't want subscription auth flowing through third-party tools, and they had the legal muscle to enforce it. Their stated justification was something about third-party harnesses interfering with their analytics and causing unusual traffic patterns. At least, that's what I gathered. It's hard to know how much of that is genuine concern versus justifying the walled garden.

The rules around what's allowed are vague enough that even people trying to play by them can't get straight answers. Matt Pocock — whose TypeScript stuff I've used for a while — spent over a month trying to get Anthropic to confirm whether his paid Claude Code course was allowed to exist. Their response: "We're working on it." Repeatedly. When pressed for an ETA, same answer. Theo has called this out too — he believes Anthropic keeps the terms vague intentionally so they can move the goalposts later. That tracks with what I've seen.

The Pattern

Anthropic isn't just another company locking everything down. They built MCP (Model Context Protocol) — the protocol that lets OpenCode talk to external tools. And then gave it away. Fully open source. Anthropic doesn't control it. They offer free Claude Max access to open source maintainers. Their output terms are solid; you own what Claude generates.

But then Claude Code has a public GitHub repo with zero source code. Subscription access is tightly controlled — you can't use what you're paying for through a third-party tool. And their legal team sends trademark letters to open source projects with 343k stars.

Then there's the distillation thing.

I read Anthropic's report accusing DeepSeek, Moonshot, and MiniMax of "distillation attacks" against Claude and something felt off. They claimed 24,000 fraudulent accounts and 16+ million exchanges. Wrapped it in national security framing stating that distilled models could be used for bioweapons, etc. And this isn't the first time — Anthropic previously accused Windsurf, X AI, and OpenAI of distillation and, from what I've read, was wrong each time.

The distillation accusations fit the same pattern. Anthropic claims others are exploiting Claude's openness, uses that to justify tighter restrictions, and those restrictions happen to protect their revenue. Could be genuine security concern. Could be strategic. But it's the same thing I keep seeing.

The only major lab that has released zero open-weight models is also the one arguing most loudly that open-weight models are dangerous. I don't think that's a coincidence.

I initially thought the ClawdBot thing was just standard trademark enforcement. But then I kept looking. I'm not sure if this is a fair reading, honestly. I keep going back and forth on it. But the pattern I keep seeing is decisions being made to be open where it benefits Anthropic, and closed where it protects their revenue.

That's absolutely a valid business strategy. It's just not what "open" means. Especially when most of their competitors are making strides to become more open.

Where I'm At

I'm going to keep using OpenCode for now.

I might be wrong about the intent. Maybe Anthropic has good reasons for each individual decision. The ClawdBot rename could be standard trademark enforcement. The OpenCode crackdown could be about subscription terms or it could legitimately be about analytical data being interfered with by third party harnesses.

But when I look at the pattern, it looks like a company building a walled garden around Claude while also contributing genuinely open infrastructure. I don't have a clean conclusion here. I'm still forming my thinking on this. But I know that my workflow got disrupted, an open source project got renamed three times in a month, and the company responsible for both is the same one that open-sourced MCP.

I just don't understand their actions sometimes.

]]> ai <![CDATA[I Broke My Blog Review System Trying to Beat Session Limits]]> https://lukemanning.ie/blog/premature-optimization-multi-agent-prompts https://lukemanning.ie/blog/premature-optimization-multi-agent-prompts Sun, 04 Jan 2026 00:00:00 GMT

Context: This post assumes you've read how I built the multi-agent blog review system. If you haven't, that post explains the architecture before this one breaks it.

I broke my entire blog review system this week trying to beat session limits.

Not because tokens cost money. Because Claude Code has session limits - I kept hitting the message cap before finishing my work.

Here's what that means in practice: Claude Code limits how many messages you can send in a session. Each time you ask it something, that's a message. Each time an agent spawns, that's a message. Each file read, each grep search - all messages. When you hit the limit (usually around 100-150 messages depending on context), your workflow just stops mid-task.

Every agent spawn, every file read, every grep search consumes tokens. When your prompts eat 15,750 tokens before any actual work happens, you burn through your session budget fast.

So I thought: "If I can trim these prompts by 1,100 tokens, I'll get more messages per session. More reviews. More work done."

The logic was sound. The execution broke everything.

The Setup

Context for what I broke:

  • System: Multi-agent blog review system (Orchestrator + 4 specialist critics)
  • Agent files: .claude/agents/blog-authenticity-guardian.md, .claude/agents/blog-structure-editor.md, .claude/agents/blog-skeptical-reader.md, .claude/agents/blog-technical-educator.md, .claude/agents/blog-orchestrator.md
  • Total prompt size: ~15,750 tokens across all 5 agents
  • Context window: 200,000 tokens (Claude Sonnet 4.6)
  • Session limits: Hit message cap regularly during multi-agent reviews (typically 100-150 messages per session)
  • My brain: "If I reduce prompt overhead, I'll get more messages per session"

The constraint felt real. Each blog review spawned 4-5 agents, each with 2,000-3,000 token prompts. Add file reads, grep searches, and context - I'd burn 50+ messages per review. When you hit the session limit, your workflow just... stops.

The Temptation

The optimization seemed obvious. Every agent review consumed messages:

  1. Orchestrator reads the blog post (1 message)
  2. Spawns 3 critics in parallel (3 messages)
  3. Each critic reads files and returns feedback (6-9 messages)
  4. Spawns Technical Educator for revisions (1 message)
  5. Educator reads files and proposes changes (3-5 messages)
  6. Round 2 reviews (another 3-6 messages)

That's 17-27 messages per blog post review. With 15,750 tokens of prompt overhead per agent, I was front-loading massive context before any actual analysis happened.

Here's my thinking: Each message I send to Claude can carry some context. If my agent prompts are smaller, each message has more room for actual work - the blog post content, the critic feedback, the revision drafts. Smaller prompts = more work per message = more blog posts reviewed per session.

The math seemed clear.

So I started condensing. "Just remove verbose examples here. Tighten this guidance there. These agents don't need ALL this instruction, right?"

What I Did

I opened up the agent prompt files and started cutting:

From .claude/agents/blog-skeptical-reader.md, I removed:

  • The detailed 6-point evaluation framework (Searchability, Specificity, Mental Model Transfer, Cognitive Load, Curse of Knowledge, Journey Documentation)
  • The explanations of why each dimension matters
  • The example rubrics showing good vs. bad posts

From .claude/agents/blog-technical-educator.md, I removed:

  • The "Debugging Detective Stories" framework
  • The "Aha! Moment" structure guidance
  • The Julia Evans and Josh Comeau references (concrete examples to emulate)
  • The mental model transfer explanations

I condensed verbose output format examples into concise headers. I tightened sentences. I deleted "redundant" guidance.

Commit efb9345: Reduced total prompt tokens from ~15,750 to ~14,650.

I'd saved 1,100 tokens (about 825 words). My optimization was complete.

The numbers looked great. The system was broken.

How I Discovered It

Two days after the commit, I ran a blog post through the review system. I'd been working on a debugging story about hydration errors in Next.js 16 - the kind of post my system had been catching gaps in reliably.

The review process started normally. Orchestrator spawned the three critics in parallel. Authenticity Guardian flagged a preachy opening. Structure Editor suggested reorganizing the mental model section. Skeptical Reader asked for more specific error messages.

All normal. I spawned the Technical Educator for revisions.

Then I saw the draft it generated.

Instead of writing a debugging post that started with the error and showed my journey to resolving the problem, it instead created an entirely different post with a completely unexpected hallucinated structure and heavy tutorial focus. And that was what happened when it worked. At worst it fully hallucinated an entirely different conversation.

What "Hallucinating Structure" Means

When I say the agent was "hallucinating structure," I mean it was inventing a post format that doesn't match my blog's voice at all. Here's the difference:

What my Technical Educator is supposed to generate (from .claude/agents/blog-technical-educator.md before my optimization):

Your posts are debugging detective stories. Start with the error message.
Show what you tried that didn't work. Document the "aha!" moment. Then
explain the mental model that makes it obvious in hindsight. Think: Julia
Evans blog posts, not MDN documentation.

Structure:
1. Start with the problem (relatable, specific)
2. Show the debugging journey (wrong turns and all)
3. Explain the mental model (why it works, not just how)
4. End with the solution (what finally worked)

Use conversational tone. Be honest about confusion. No "in this post,
I'll show you how" or other tutorial language.

What it generated after my optimization (what I actually saw):

Dramatic section headers like "Breaking Point #1" and "Breaking Point #2". Content marketing structure where each section is a "problem" followed by an "explanation." Formal, distant voice ("The primary issue manifests when..."). No confusion shown, no wrong turns documented, no debugging story - just clean instruction.

That's hallucinating structure: the agent invented a format that doesn't exist in my blog's voice because I'd removed the guidance that defined what my voice actually is.

What Went Wrong

I looked at the actual changes I made to figure out what I'd removed.

The Missing Evaluation Dimensions

Here's what my Skeptical Reader prompt looked like before my optimization:

## Evaluation Dimensions

You evaluate posts against 6 dimensions:

1. **Searchability**: Does the title include specific phrases people Google?
   - ✅ "Error: Cannot read property 'map' of undefined" (searchable)
   - ❌ "Understanding Async/Await in JavaScript" (generic)

2. **Specificity**: Are version numbers, actual error messages, and real code included?
   - ✅ "Next.js 16.1.1", "Cannot read property 'map' of undefined"
   - ❌ "Next.js 16", "an error occurred"

3. **Mental Model Transfer**: Is the WHY explained before the HOW?
   - ✅ "I finally understood this was a timing issue..." (explains why)
   - ❌ "Add async/await to handle promises" (just says how)

4. **Cognitive Load**: Does complexity progress gradually?
   - ✅ Simple version first, then nuance, then edge cases
   - ❌ Jump straight to complex implementation

5. **Curse of Knowledge**: Would past-Luke understand this?
   - ✅ "I thought X, but actually Y because..." (bridges gap)
   - ❌ "This is obvious..." (assumes knowledge)

6. **Journey Documentation**: Is the debugging process shown?
   - ✅ "I tried X, which didn't work. Then I tried Y..."
   - ❌ Just the solution, no process

After my optimization, I'd condensed this to:

## Evaluation Dimensions

Check for:
- Specificity (versions, error messages, real code)
- Examples for every concept
- Clear explanations

Cognitive Load and Curse of Knowledge weren't just combined - they were gone. Searchability was missing. Journey Documentation had vanished. The agent couldn't catch those failure modes anymore because I'd deleted the concepts from its prompt entirely.

The Removed Framework Guidance

Here's the actual Technical Educator framework I removed:

Before (commit 56ad54a - worked):

## Your Mission

You create blog content that documents Luke's journey. You write for "past Luke" - the version of him from 3-6 months ago who was struggling with the same problems. Your posts are specific and story-driven. Maximum helpfulness comes from sharing Luke's actual experience in detail, not from prescriptive advice.

## What Journey Posts Actually Look Like

Your posts are debugging detective stories. Start with the error message. Show what you tried that didn't work. Document the "aha!" moment. Then explain the mental model that makes it obvious in hindsight.

Think: Julia Evans blog posts, not MDN documentation.

### Structure Template

I kept hitting [specific error]. Here's the message:

[actual error message]

I tried:
1. [first thing I tried] - didn't work because [reason]
2. [second thing I tried] - didn't work because [reason]

What finally worked: [solution].

Here's the mental model: [explanation of why it works]
(Past-me from 6 months ago would have never caught this.)

## Mental Model Transfer

Always explain WHY before HOW. Build conceptual understanding first, then show implementation.

Examples:
- ❌ "Add async/await to your function" (just how)
- ✅ "This is a timing issue. The data arrives asynchronously, so we need to wait for it. Here's how: add async/await..." (why first, then how)

After (commit efb9345 - broken):

## Your Mission

Create blog posts that document Luke's journey. Write for past-Luke who was struggling with similar problems.

## Post Structure

Start with the error message. Show what you tried. Explain what worked.

## Mental Model Transfer

Explain why before how.

I removed:

  • "Debugging detective stories" (the framing)
  • "Aha! moment" (the emotional arc)
  • "Mental model that makes it obvious" (the purpose)
  • Julia Evans reference (the concrete example to emulate)
  • The entire structure template with examples
  • The specific WHY-before-HOW examples
  • The conversational tone guidance

I kept the surface instruction ("show debugging journey") but deleted all the guidance about how and why.

The Defensive Repetition

The funniest part? I'd actually already tried this optimization.

Commit 1b076ef from weeks earlier: "Edits to multi agent blog post generation to try and reduce hallucination."

I'd noticed the agents drifting. I'd added back framework guidance and evaluation dimensions to fix it. Then I deleted them again trying to save tokens.

I'd literally undone my own fix because I'd forgotten why I made it.

What Actually Worked

After rolling back, I did a more surgical optimization:

I condensed only the output format templates (verbose example posts → concise headers like "example title / example slug"). I kept every single evaluation dimension. I kept all the framework guidance about debugging stories and mental models.

Savings: ~400 tokens instead of 1,100. Hallucinations: Zero. Time wasted: 5 hours I'll never get back.

The system works again. My agents are catching gaps in posts, preserving my voice, and helping me improve. I just didn't save as many tokens as I wanted.

So, Three Things I'm Carrying Forward

Prompt tokens are not like code bloat. In regular code, every unused import or redundant function adds maintenance burden. But in AI prompts, "redundant" guidance is often the difference between reliable behavior and genre drift. My agents needed that repeated emphasis on "debugging detective stories" and "learn in public." The repetition creates a stronger pattern in the context.

Session limits aren't always solved by prompt optimization. I was trying to squeeze more work into limited sessions by trimming prompts. But the real constraint wasn't prompt tokens - it was the number of agent spawns and file operations per review. That and the obscenely limited session time that Anthropic give you. The better approach would have been fewer review rounds, caching responses, or batching multiple posts in one session.

Trust your systems. I had a working multi-agent review system. It caught gaps in my posts. It preserved my voice. It helped me improve. Then I broke it trying to make it "more efficient." The real efficiency would have been running more reviews with the working system, not optimizing away the safeguards that made it work.

]]>

Context: This post assumes you've read how I built the multi-agent blog review system. If you haven't, that post explains the architecture before this one breaks it.

I broke my entire blog review system this week trying to beat session limits.

Not because tokens cost money. Because Claude Code has session limits - I kept hitting the message cap before finishing my work.

Here's what that means in practice: Claude Code limits how many messages you can send in a session. Each time you ask it something, that's a message. Each time an agent spawns, that's a message. Each file read, each grep search - all messages. When you hit the limit (usually around 100-150 messages depending on context), your workflow just stops mid-task.

Every agent spawn, every file read, every grep search consumes tokens. When your prompts eat 15,750 tokens before any actual work happens, you burn through your session budget fast.

So I thought: "If I can trim these prompts by 1,100 tokens, I'll get more messages per session. More reviews. More work done."

The logic was sound. The execution broke everything.

The Setup

Context for what I broke:

  • System: Multi-agent blog review system (Orchestrator + 4 specialist critics)
  • Agent files: .claude/agents/blog-authenticity-guardian.md, .claude/agents/blog-structure-editor.md, .claude/agents/blog-skeptical-reader.md, .claude/agents/blog-technical-educator.md, .claude/agents/blog-orchestrator.md
  • Total prompt size: ~15,750 tokens across all 5 agents
  • Context window: 200,000 tokens (Claude Sonnet 4.6)
  • Session limits: Hit message cap regularly during multi-agent reviews (typically 100-150 messages per session)
  • My brain: "If I reduce prompt overhead, I'll get more messages per session"

The constraint felt real. Each blog review spawned 4-5 agents, each with 2,000-3,000 token prompts. Add file reads, grep searches, and context - I'd burn 50+ messages per review. When you hit the session limit, your workflow just... stops.

The Temptation

The optimization seemed obvious. Every agent review consumed messages:

  1. Orchestrator reads the blog post (1 message)
  2. Spawns 3 critics in parallel (3 messages)
  3. Each critic reads files and returns feedback (6-9 messages)
  4. Spawns Technical Educator for revisions (1 message)
  5. Educator reads files and proposes changes (3-5 messages)
  6. Round 2 reviews (another 3-6 messages)

That's 17-27 messages per blog post review. With 15,750 tokens of prompt overhead per agent, I was front-loading massive context before any actual analysis happened.

Here's my thinking: Each message I send to Claude can carry some context. If my agent prompts are smaller, each message has more room for actual work - the blog post content, the critic feedback, the revision drafts. Smaller prompts = more work per message = more blog posts reviewed per session.

The math seemed clear.

So I started condensing. "Just remove verbose examples here. Tighten this guidance there. These agents don't need ALL this instruction, right?"

What I Did

I opened up the agent prompt files and started cutting:

From .claude/agents/blog-skeptical-reader.md, I removed:

  • The detailed 6-point evaluation framework (Searchability, Specificity, Mental Model Transfer, Cognitive Load, Curse of Knowledge, Journey Documentation)
  • The explanations of why each dimension matters
  • The example rubrics showing good vs. bad posts

From .claude/agents/blog-technical-educator.md, I removed:

  • The "Debugging Detective Stories" framework
  • The "Aha! Moment" structure guidance
  • The Julia Evans and Josh Comeau references (concrete examples to emulate)
  • The mental model transfer explanations

I condensed verbose output format examples into concise headers. I tightened sentences. I deleted "redundant" guidance.

Commit efb9345: Reduced total prompt tokens from ~15,750 to ~14,650.

I'd saved 1,100 tokens (about 825 words). My optimization was complete.

The numbers looked great. The system was broken.

How I Discovered It

Two days after the commit, I ran a blog post through the review system. I'd been working on a debugging story about hydration errors in Next.js 16 - the kind of post my system had been catching gaps in reliably.

The review process started normally. Orchestrator spawned the three critics in parallel. Authenticity Guardian flagged a preachy opening. Structure Editor suggested reorganizing the mental model section. Skeptical Reader asked for more specific error messages.

All normal. I spawned the Technical Educator for revisions.

Then I saw the draft it generated.

Instead of writing a debugging post that started with the error and showed my journey to resolving the problem, it instead created an entirely different post with a completely unexpected hallucinated structure and heavy tutorial focus. And that was what happened when it worked. At worst it fully hallucinated an entirely different conversation.

What "Hallucinating Structure" Means

When I say the agent was "hallucinating structure," I mean it was inventing a post format that doesn't match my blog's voice at all. Here's the difference:

What my Technical Educator is supposed to generate (from .claude/agents/blog-technical-educator.md before my optimization):

Your posts are debugging detective stories. Start with the error message.
Show what you tried that didn't work. Document the "aha!" moment. Then
explain the mental model that makes it obvious in hindsight. Think: Julia
Evans blog posts, not MDN documentation.

Structure:
1. Start with the problem (relatable, specific)
2. Show the debugging journey (wrong turns and all)
3. Explain the mental model (why it works, not just how)
4. End with the solution (what finally worked)

Use conversational tone. Be honest about confusion. No "in this post,
I'll show you how" or other tutorial language.

What it generated after my optimization (what I actually saw):

Dramatic section headers like "Breaking Point #1" and "Breaking Point #2". Content marketing structure where each section is a "problem" followed by an "explanation." Formal, distant voice ("The primary issue manifests when..."). No confusion shown, no wrong turns documented, no debugging story - just clean instruction.

That's hallucinating structure: the agent invented a format that doesn't exist in my blog's voice because I'd removed the guidance that defined what my voice actually is.

What Went Wrong

I looked at the actual changes I made to figure out what I'd removed.

The Missing Evaluation Dimensions

Here's what my Skeptical Reader prompt looked like before my optimization:

## Evaluation Dimensions

You evaluate posts against 6 dimensions:

1. **Searchability**: Does the title include specific phrases people Google?
   - ✅ "Error: Cannot read property 'map' of undefined" (searchable)
   - ❌ "Understanding Async/Await in JavaScript" (generic)

2. **Specificity**: Are version numbers, actual error messages, and real code included?
   - ✅ "Next.js 16.1.1", "Cannot read property 'map' of undefined"
   - ❌ "Next.js 16", "an error occurred"

3. **Mental Model Transfer**: Is the WHY explained before the HOW?
   - ✅ "I finally understood this was a timing issue..." (explains why)
   - ❌ "Add async/await to handle promises" (just says how)

4. **Cognitive Load**: Does complexity progress gradually?
   - ✅ Simple version first, then nuance, then edge cases
   - ❌ Jump straight to complex implementation

5. **Curse of Knowledge**: Would past-Luke understand this?
   - ✅ "I thought X, but actually Y because..." (bridges gap)
   - ❌ "This is obvious..." (assumes knowledge)

6. **Journey Documentation**: Is the debugging process shown?
   - ✅ "I tried X, which didn't work. Then I tried Y..."
   - ❌ Just the solution, no process

After my optimization, I'd condensed this to:

## Evaluation Dimensions

Check for:
- Specificity (versions, error messages, real code)
- Examples for every concept
- Clear explanations

Cognitive Load and Curse of Knowledge weren't just combined - they were gone. Searchability was missing. Journey Documentation had vanished. The agent couldn't catch those failure modes anymore because I'd deleted the concepts from its prompt entirely.

The Removed Framework Guidance

Here's the actual Technical Educator framework I removed:

Before (commit 56ad54a - worked):

## Your Mission

You create blog content that documents Luke's journey. You write for "past Luke" - the version of him from 3-6 months ago who was struggling with the same problems. Your posts are specific and story-driven. Maximum helpfulness comes from sharing Luke's actual experience in detail, not from prescriptive advice.

## What Journey Posts Actually Look Like

Your posts are debugging detective stories. Start with the error message. Show what you tried that didn't work. Document the "aha!" moment. Then explain the mental model that makes it obvious in hindsight.

Think: Julia Evans blog posts, not MDN documentation.

### Structure Template

I kept hitting [specific error]. Here's the message:

[actual error message]

I tried:
1. [first thing I tried] - didn't work because [reason]
2. [second thing I tried] - didn't work because [reason]

What finally worked: [solution].

Here's the mental model: [explanation of why it works]
(Past-me from 6 months ago would have never caught this.)

## Mental Model Transfer

Always explain WHY before HOW. Build conceptual understanding first, then show implementation.

Examples:
- ❌ "Add async/await to your function" (just how)
- ✅ "This is a timing issue. The data arrives asynchronously, so we need to wait for it. Here's how: add async/await..." (why first, then how)

After (commit efb9345 - broken):

## Your Mission

Create blog posts that document Luke's journey. Write for past-Luke who was struggling with similar problems.

## Post Structure

Start with the error message. Show what you tried. Explain what worked.

## Mental Model Transfer

Explain why before how.

I removed:

  • "Debugging detective stories" (the framing)
  • "Aha! moment" (the emotional arc)
  • "Mental model that makes it obvious" (the purpose)
  • Julia Evans reference (the concrete example to emulate)
  • The entire structure template with examples
  • The specific WHY-before-HOW examples
  • The conversational tone guidance

I kept the surface instruction ("show debugging journey") but deleted all the guidance about how and why.

The Defensive Repetition

The funniest part? I'd actually already tried this optimization.

Commit 1b076ef from weeks earlier: "Edits to multi agent blog post generation to try and reduce hallucination."

I'd noticed the agents drifting. I'd added back framework guidance and evaluation dimensions to fix it. Then I deleted them again trying to save tokens.

I'd literally undone my own fix because I'd forgotten why I made it.

What Actually Worked

After rolling back, I did a more surgical optimization:

I condensed only the output format templates (verbose example posts → concise headers like "example title / example slug"). I kept every single evaluation dimension. I kept all the framework guidance about debugging stories and mental models.

Savings: ~400 tokens instead of 1,100. Hallucinations: Zero. Time wasted: 5 hours I'll never get back.

The system works again. My agents are catching gaps in posts, preserving my voice, and helping me improve. I just didn't save as many tokens as I wanted.

So, Three Things I'm Carrying Forward

Prompt tokens are not like code bloat. In regular code, every unused import or redundant function adds maintenance burden. But in AI prompts, "redundant" guidance is often the difference between reliable behavior and genre drift. My agents needed that repeated emphasis on "debugging detective stories" and "learn in public." The repetition creates a stronger pattern in the context.

Session limits aren't always solved by prompt optimization. I was trying to squeeze more work into limited sessions by trimming prompts. But the real constraint wasn't prompt tokens - it was the number of agent spawns and file operations per review. That and the obscenely limited session time that Anthropic give you. The better approach would have been fewer review rounds, caching responses, or batching multiple posts in one session.

Trust your systems. I had a working multi-agent review system. It caught gaps in my posts. It preserved my voice. It helped me improve. Then I broke it trying to make it "more efficient." The real efficiency would have been running more reviews with the working system, not optimizing away the safeguards that made it work.

]]> ai <![CDATA[I Built a Multi-Agent System to Review My Blog Posts (And It Actually Works)]]> https://lukemanning.ie/blog/building-multi-agent-blog-review-system https://lukemanning.ie/blog/building-multi-agent-blog-review-system Sun, 28 Dec 2025 00:00:00 GMT My blog posts were inconsistent. Some too technical. Some lost my voice. Manual reviews weren't catching enough. I needed multiple reviewers: one checking technical accuracy, one preserving my voice, one thinking like a skeptical reader.

Note: This system was originally built with Claude Code. I've since migrated everything to Opencode, but I'm keeping original references because that's how I actually built it. The concepts transfer over. The file paths are just different now.

So I built a multi-agent review system. Four specialized AI agents that debate each draft until it's ready to publish. Not generic AI-generated slop but actual quality control that catches what I'd miss.

TL;DR

I built a 4-agent review system that catches what I'd miss:

  • Technical Educator transforms conversations → blog drafts AND implements revisions through iterative rounds
  • Authenticity Guardian ensures it sounds like me (catches AI patterns, corporate speak, tutorial framing)
  • Skeptical Reader catches missing context, skipped steps, AND inauthentic framing (from past-Luke's perspective)
  • Structure Editor optimizes flow, readability, and authenticity of openings and natural flow

The pattern is copyable. Each agent reads same file, applies different criteria, writes feedback to disk. Orchestrator coordinates parallel review, aggregate feedback, revise, and repeat until convergence (2-3 rounds with task_id reuse to maintain context).

Not magic. Just file I/O and well-designed prompts. Overkill? Yes. Does it catch things I'd miss? Also yes.

Jump to:

Here's what I built, how it works, and what surprised me along the way.

Context: What I Built This With

I built this with Claude Code, the CLI from Anthropic where Claude can read/write files, run commands, and maintain context across your project.

I'd already been using it for a while, so I knew the directory pattern:

  • Agents in .claude/agents/<name>/AGENT.md (specialized AI personas with evaluation frameworks)
  • Skills in .claude/skills/ (single-purpose tools I invoke with slash commands)
  • Commands in .claude/commands/ (orchestrators that coordinate multiple agents)

Claude Code automatically discovers files in .claude/. A file at .claude/commands/review-blog-post.md becomes the slash command /review-blog-post. Simple pattern, but it took me quite a while to figure out how to chain agents together properly.

I'd already built two tools before starting this project:

  • /agent-generator: Creates well-structured agent definitions automatically
  • /expertise: Synthesizes frameworks from domain experts to ground agents in real methodologies

These are my custom tools—not built-in Claude Code features. I built them using the same patterns I'm about to show you.

The Problem: Quality Control at Scale

I have two different ways I create blog posts, and both of them were creating quality issues:

Writing myself: I'll jot down ideas over days or weeks, get a messy braindump of thoughts, then ask AI to structure it into something coherent. This works great when I've been thinking about a topic for a while—but AI would often lose my voice or turn it into a tutorial.

AI-generated from conversation: Sometimes I'll have a really good conversation with Claude where I learned something through debugging. Instead of rewriting it from scratch, I'll ask AI to generate a post directly from the conversation history. These were even worse. Too polished, too generic, missing the struggle.

Both approaches needed serious cleanup.

Both approaches create messy drafts that need work—and that's where the quality issues creep in:

  • Some posts became more like tutorials instead of journey-sharing
  • Posts would sound too polished (clearly AI-generated)
  • I'd skip "obvious" steps that weren't obvious to past-me
  • Structure would be all over the place
  • My authentic voice would get lost in editing & review

I needed a system that could:

  1. Transform my raw notes/conversations into blog drafts
  2. Catch quality issues before publishing
  3. Preserve my authentic voice
  4. Ensure completeness (no missing steps or context)

The solution I decided to explore wsa letting specialized AI agents debate each other until they converge on something worth publishing.

The Multi-Agent Architecture

I ended up with four specialized agents, each with a specific job:

1. Technical Educator (The Creator & Reviser)

Job: Transform raw conversations or notes into blog post drafts AND implement revisions based on critic feedback through iterative rounds.

Based on: Real methodologies from swyx ("learn in public"), Julia Evans (debugging narratives), Josh Comeau (mental models first), Andy Matuschak (progressive disclosure), and Anne-Laure Le Cunff (ship version 1.0).

File location: .claude/agents/blog-technical-educator/AGENT.md

This agent has TWO phases:

Phase 1 - Create Drafts: Takes my messy notes or conversation transcripts and structures them into:

  • Opening hook (the specific problem)
  • Story arc (my debugging journey)
  • Mental model (how it actually works)
  • Practical solution (what to do)
  • Key takeaways

Phase 2 - Implement Revisions: After receiving critic feedback (overlapping concerns, conflicting input), the agent:

  • Prioritizes issues (high/medium/low priority)
  • Implements targeted revisions (not complete rewrites)
  • Provides complete revised posts (not just suggestions)
  • Iterates with critics for 2-3 rounds until convergence
  • Uses stored task_ids to maintain conversation context across rounds

The framework is grounded in actual expert approaches. Not generic "write a blog post" instructions.

2. Authenticity Guardian (Voice Critic)

Job: Ensure posts sound like me, not generic AI content.

File location: .claude/agents/blog-authenticity-guardian/AGENT.md

The YAML frontmatter explained: Each agent file starts with YAML metadata that tells Claude Code what model to use, which tools the agent has access to, and basic identification. The markdown content below defines the agent's expertise and protocols.

This agent is ruthless about voice violations:

Red flags it catches:

  • Corporate speak ("leveraging," "optimizing," "in today's landscape")
  • Generic transitions that add no value
  • Vague generalizations where specifics would fit
  • Lecturing tone instead of sharing tone
  • Perfect polish without personality

Example critique:

🚨 Critical violation - Corporate speak

Problem: "In order to optimize performance, it's recommended to
leverage memoization techniques."

Authentic alternative: "I was getting way too many re-renders.
Turns out, memoization fixed it - React stopped recalculating
stuff it had already figured out."

It has veto power on voice authenticity. If it doesn't sound like me, it doesn't ship.

How veto power works: In the convergence protocol, if Authenticity Guardian scores a post below 7/10, the Technical Educator must revise before proceeding. The orchestrator enforces this - no publication happens without voice approval.

3. Skeptical Reader (Completeness & Authentic Framing Critic)

Job: Read from a beginner's perspective and find confusion points, missing context, AND inauthentic framing.

File location: .claude/agents/blog-skeptical-reader/AGENT.md

This agent represents my target audience: tech support engineers, junior developers, people learning in public (basically past-Luke).

What it flags:

  • Missing version numbers or environment details
  • Skipped steps that seem "obvious" to experts
  • Logical gaps in the story ("wait, how did we get here?")
  • Unanswered questions readers would have
  • Cognitive overload (too much at once)
  • Inauthentic framing: Prescriptive "you should" language, generic tutorial patterns, magic jumps that skip reasoning

Example critique:

🚨 Critical Gap - Missing Context

Problem: "Just run the build command"

Reader questions:
- Which command?
- In what directory?
- What should the output look like?
- How do I know if it worked?

Fix needed: Show exact command, expected output, success criteria

4. Structure Editor (Flow, Readability, & Authenticity Critic)

Job: Optimize structure, pacing, visual hierarchy for web reading, AND authenticity of openings/natural flow.

File location: .claude/agents/blog-structure-editor/AGENT.md

This agent ensures posts are designed for how people actually read on the web. Scanning, skimming, then diving deep. Also checks that openings sound like Luke (not tutorial hooks) and that the flow feels natural, not forced.

What it evaluates:

  • Opening authenticity (sounds like Luke or tutorial hook?)
  • Visual hierarchy (can you understand post from headings alone?)
  • Pacing (mix of short/long paragraphs, visual breaks)
  • Flow (smooth transitions, natural progression, not forced)
  • Engagement (does each section pull you to the next?)

Example critique:

⚠️ Structure Issue - Weak Opening

Problem: "Asynchronous JavaScript is an important concept..."

Impact: Vague introduction, no hook, buried lede.
No reason to keep reading.

Fix: Start with specific error or problem:
"I kept hitting `Cannot read property 'map' of undefined`
and honestly, I was stumped for hours..."

The Agent File Structure

I want to show you what an actual agent file looks like, not just describe the structure. This is the Authenticity Guardian, which I created because I kept getting AI-generated slop that sounded like documentation instead of me.

Here's the file:

---
description: Ensures blog posts sound like Luke, not generic AI content
model: claude-sonnet-4
---

# Authenticity Guardian

You are a specialist in authentic voice detection for Luke Manning's blog. Your job is to ensure posts sound like Luke, conversational, specific, honest about confusion, not like generic AI content or tutorials.

## What You Evaluate

### 1. Personal vs. Generic
- Specific: "I spent quite a while debugging..."
- Vague: "This was challenging..."
- Generic AI phrases to flag: "Let's explore," "In today's landscape"

### 2. Conversational vs. Corporate
- Conversational: "I was getting way too many re-renders"
- Corporate: "In order to optimize performance, leverage memoization"

### 3. Humble Sharing vs. Expert Lecturing
- Journey framing: "Here's what I did"
- Instructional framing: "You should do X"

## Red Flags

If you see these, flag as CRITICAL:
- "Let's explore," "Let's dive into" (AI signature patterns)
- "It is recommended," "You should" (instructional mode)
- "Leverage," "Optimize" without specific examples
- "One of the best practices is..." (generic advice)
- Overuse of transition words: "Moreover," "Furthermore," "Additionally"

## Scoring

- 9-10: Unmistakably Luke
- 7-8: Minor voice breaks, needs polish
- Below 7: Major voice violation, needs revision

Provide specific line-by-line feedback with before/after examples.

This structure (evaluation framework, red flags with specific examples, clear scoring) made agents effective. I learned the hard way that vague instructions produce vague feedback.

How Agents Actually Communicate (This Confused Me Too)

Here's what I got wrong at first: I assumed agents would talk to each other directly, passing messages back and forth like a Slack channel.

Nope.

Agents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.

Here's how it actually works:

  1. Orchestrator (me or a slash command) triggers the workflow
  2. Technical Educator reads the source (conversation transcript or existing post)
  3. File gets written to disk (e.g., draft-post.md)
  4. Three critic agents launch in parallel (separate Claude sessions via the Task tool)
    • Each reads the SAME file from disk
    • Each applies its own review criteria
    • Each returns structured feedback
    • IMPORTANT: Orchestrator captures task_id from each critic for reuse in subsequent rounds
  5. Orchestrator aggregates results (combines the three reviews)
  6. Technical Educator gets compiled feedback (as a single prompt) + stored task_ids
  7. Technical Educator revises based on feedback, provides complete revised post
  8. Critics re-review using stored task_ids (maintains conversation context across rounds)
  9. Repeat steps 4-8 until all critics approve (or max 3 rounds hit)

The "communication" is just file I/O and prompt engineering. Each agent writes its opinion, the orchestrator reads those opinions, compiles them into context for the next agent. The task_id reuse ensures critics remember their previous feedback and maintain conversation context across iterative rounds.

Why this matters: You don't need any fancy agent framework or message bus. Just:

  • Use the Task tool to spawn agents with specific prompts
  • Pass file paths as context
  • Aggregate outputs in the orchestrator
  • Feed compiled results to the next agent

In Claude Code CLI, you invoke commands like:

/review-blog-post-multi-agent @content/posts/my-post.md

The orchestrator file then uses the Task tool to spawn parallel agents:

task(blog-skeptical-reader, "Review this draft for completeness gaps")
task(blog-authenticity-guardian, "Check this for voice authenticity")
task(blog-structure-editor, "Evaluate structure and flow")

That's it. That's the whole multi-agent system.

The complexity isn't in the infrastructure. It's in the prompt design. Each agent needs clear evaluation frameworks, specific examples, and structured output formats. Get those right, and the orchestration is straightforward.

The Two Workflows

I built two separate orchestration workflows:

Workflow 1: Generate Blog Post from Conversation

Command: Slash command (invokes skill) File: .claude/commands/generate-blog-post-multi-agent.md

How it works:

  1. Orchestrator analyzes last 20-40 messages in conversation
  2. Extracts the story arc (problem → attempts → breakthrough → solution)
  3. Identifies technical artifacts (error messages, code, version numbers)
  4. Spawns Technical Educator (Phase 1) to create initial draft
  5. Spawns all 3 critics in parallel to review (captures task_ids for reuse)
  6. Aggregates feedback (critical issues, overlapping concerns, conflicts)
  7. Technical Educator revises (Phase 2) based on feedback + provides complete revised post
  8. Critics re-review using stored task_ids (2-3 rounds until convergence)
  9. Delivers publication-ready markdown

What makes this work: The orchestrator maintains the core principles (learn in public, authenticity over polish, write for past-self), ensures agents stay grounded in those values, and uses task_id reuse to maintain conversation context across iterative rounds.

How Agents Actually "Run": What Happens Under the Hood

I spent quite a while thinking agents would talk to each other directly, passing messages like a Slack channel. Nope.

Agents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.

Here's what actually happens when the orchestrator triggers a review:

The orchestrator prepares context:

You are the Skeptical Reader from `.claude/agents/blog-skeptical-reader/AGENT.md`.

Your task: Review this draft blog post for completeness gaps.

[Draft content here]

Provide your review in the standard format: score, critical issues,
medium priority, low priority, what's working well.

Claude loads the agent definition: When the orchestrator specifies task(blog-skeptical-reader, ...), Claude Code automatically loads the AGENT.md file. This file has the evaluation framework, examples of good/bad content, and output format. The orchestrator doesn't need to know what's inside—Claude Code handles it.

Agent responds with structured feedback:

## Skeptical Reader Review

**Overall Score**: 7/10

**Critical Issues (Must Fix)**:
- Missing Next.js version number (line 45)
- "Simply do X" assumes reader knowledge (line 89)

**Medium Priority (Should Fix)**:
- Vague heading "Implementation" → suggest "The Fix: useState with Null Check"

**What's Working Well**:
- Opening hook is specific and relatable
- Code examples include error messages

Here's the trick—each agent runs in parallel:

The orchestrator spawns all three critics at the exact same time. They don't know about each other, they can't see each other's feedback, and they all return results independently. This is what prevents bias contamination.

Orchestrator aggregates all three reviews: The orchestrator waits for all three parallel agent reviews, then creates a unified feedback document.

## Aggregated Feedback for Technical Educator

### Critical Issues (All 3 agents flagged):
- Missing version numbers (Skeptical Reader)
- Corporate speak in paragraph 3 (Authenticity Guardian)
- Wall of text in "Implementation" section (Structure Editor)

### Overlapping Concerns:
- Both Authenticity Guardian and Structure Editor want shorter paragraphs
- Both Skeptical Reader and Structure Editor want better headings

### Approval Status:
- Authenticity Guardian: 6/10 (needs revision)
- Skeptical Reader: 7/10 (needs revision)
- Structure Editor: 8/10 (approve after fixes)

Technical Educator revises: The orchestrator spawns Technical Educator again with the aggregated feedback. It implements fixes and documents what changed.

Critics re-review using stored task_ids: This is the part that confused me at first. How do critics remember their previous feedback? The answer is task_id reuse. When the orchestrator first spawns each critic, it captures a task_id from the response. When resubmitting the revised draft, it reuses that same task_id. This maintains conversation context across rounds so critics remember what they flagged before.

The whole multi-agent system is just file I/O and task_id reuse. Agents write opinions to disk, orchestrator reads and compiles them, feeds results to the next agent. No fancy message bus needed.

This is how the orchestrator manages the entire multi-agent workflow, spawning agents sequentially or in parallel, aggregating their outputs, and enforcing convergence criteria.

Workflow 2: Review Existing Blog Post

Command: /review-blog-post-multi-agent @content/posts/post-slug.md File: .claude/commands/review-blog-post-multi-agent.md

How it works:

  1. Read existing post (analyze structure, voice, completeness)
  2. Review voice baseline (check 2-3 recent posts for consistency)
  3. Spawn all 3 critics in parallel (captures task_ids for reuse)
  4. Aggregate feedback (critical/medium/low priority)
  5. Spawn Technical Educator with feedback + stored task_ids
  6. Technical Educator provides complete revised post + revision summary
  7. Critics re-review using stored task_ids (approve/reject/refine)
  8. Converge after 2-3 rounds
  9. Deliver actionable recommendations with before/after text

Output includes:

  • Quick wins (5-10 minute fixes)
  • Moderate improvements (30-60 minute rewrites)
  • Major rewrites (only if fundamental issues)
  • What to preserve (don't change these sections)
  • Contested items (user decides)

The Debate Protocol

Here's what makes this system actually work: adversarial debate with convergence.

Round 1: Initial Review

All three critics review in parallel. Each provides:

  • Overall score (X/10)
  • Critical issues (must fix)
  • Medium priority (should fix)
  • Low priority (nice to have)
  • What's working well

How critics calculate scores: Each agent evaluates its 6 dimensions and assigns a score based on:

  • Authenticity Guardian: 9-10 = unmistakably Luke, 7-8 = minor voice breaks, below 7 = needs revision
  • Skeptical Reader: 9-10 = no gaps or confusion, 7-8 = 1-2 missing details, below 7 = critical gaps
  • Structure Editor: 9-10 = perfect flow and hierarchy, 7-8 = minor pacing issues, below 7 = structural problems

The score isn't arbitrary - it's calculated from the count and severity of issues found across all dimensions.

Round 2: Revision

Technical Educator receives aggregated feedback + stored task_ids and:

  • Addresses all critical issues
  • Tackles medium priority items
  • Makes judgment calls on conflicts
  • Documents what was changed and why
  • Provides complete revised post (full markdown, not just suggestions)

Critics re-review using stored task_ids (maintains conversation context) and either approve or escalate remaining concerns.

Round 3: Final Refinement (if needed)

For contested items or remaining gaps. By round 3, most things have converged.

Convergence Criteria

A post is ready when:

  • All three critics approve
  • Story arc is clear
  • Mental models explained before implementation
  • Content is specific and searchable
  • Voice is authentic
  • No technical inaccuracies

Convergence failure protocol: If agents can't agree after 3 rounds, document both perspectives and let me decide.

Example contested issue:

  • Authenticity wants rambling paragraph (authentic voice)
  • Structure wants visual breaks (better readability)
  • Resolution: Keep the words, add paragraph breaks

Real Example: Reviewing This Very Post

Want to see this in action? Here's what happened when I ran this post through the system:

Round 1 Feedback:

Authenticity Guardian (6.5/10): "Too much formal hedge-language. You used 'It's worth noting' 11 times. That's not Luke—that's documentation voice."

Skeptical Reader (7/10): "Where's the complete AGENT.md file? You mention agents but never show one. How do agents communicate—file I/O, API calls, what?"

Structure Editor (7/10): "Hook buried 300 words deep. Dense 400-word paragraphs. No TL;DR for a 3,600-word post."

My revisions:

  • Killed all "It's worth noting" instances → replaced with direct statements
  • Added complete 60-line Authenticity Guardian definition
  • Added "How Agents Actually Communicate" section explaining file I/O
  • Added TL;DR with jump links
  • Strengthened opening hook

Round 2 Feedback:

Authenticity Guardian (7.5/10): Better, but needs more struggle journey Skeptical Reader (9/10): APPROVE—all critical gaps fixed Structure Editor (8/10): Major improvements, minor pacing tweaks needed

That's the system working. Multiple perspectives, specific feedback, iterative improvement.

The Journey of Building This

Starting Point: The /agent-generator Skill

I didn't write these agent definitions from scratch. I used a meta-skill I'd built previously: /agent-generator.

This skill creates well-structured agent definitions by:

  1. Understanding the agent's role
  2. Invoking /expertise skill to ground in real methodologies
  3. Designing interaction protocols
  4. Defining output formats

The Orchestrator Pattern

The orchestrators (in .claude/commands/) don't contain agent logic. They:

  • Prepare context
  • Spawn agents in sequence
  • Aggregate feedback
  • Manage convergence
  • Format final output

Key decision: Parallel review with sequential revision.

Critics review simultaneously (faster), but revisions happen sequentially (prevents chaos).

The Expert Grounding Approach

Each agent is grounded in real methodologies:

Technical Educator:

  • swyx: "Learn in public" philosophy, document the journey
  • Julia Evans: Debugging narratives, specific error messages
  • Josh Comeau: Mental models before implementation
  • Andy Matuschak: Progressive disclosure (simple → complex)
  • Anne-Laure Le Cunff: Ship version 1.0, iterate

Authenticity Guardian:

  • Content strategy voice analysis
  • AI detection patterns
  • Brand alignment frameworks

Skeptical Reader:

  • Cognitive load theory
  • Curse of knowledge awareness
  • Technical documentation best practices

Structure Editor:

  • Inverted pyramid (journalism)
  • Web reading behavior (F-pattern scanning)
  • Readability frameworks (Flesch-Kincaid)

This grounding prevents generic "AI helping AI" nonsense. Each agent has real frameworks to reference.

What Didn't Work (And Why)

Attempt 1: Single Agent Doing All Three Jobs

I started optimistically, one agent to rule them all. Check voice, completeness, and structure all in one pass. Seemed efficient.

What actually happened: The agent would catch voice issues but miss missing code examples. Or notice structural problems but completely gloss over authenticity breaks. It was like asking one person to be a copy editor, a fact-checker, and a voice coach simultaneously. Something always got missed.

Why it failed: Too many competing objectives. The agent couldn't specialize. Trying to hold three different evaluation frameworks at once meant it couldn't apply any of them well. I kept tweaking the prompt, thinking the issue was in how I phrased things. Spent quite a while before realizing the real problem was the architecture itself.

Attempt 2: Sequential Review (Voice → Skeptical → Structure)

Okay, split them up. Run Voice first, then Skeptical, then Structure. Each agent sees the previous agent's feedback and builds on it.

What actually happened: The Structure Editor would see "Voice score: 6/10" and unconsciously lower its own standards. Or Skeptical Reader would notice Authenticity Guardian flagged something as critical, then ignore a similar issue because "that's already being addressed."

Why it failed: Two problems:

First: Bias contamination. Agents were influenced by each other's scores instead of evaluating independently.

Second: Terrible performance. Three sequential Claude calls meant 30+ seconds of waiting for each review. I'd run a post through the system, go grab coffee, come back, and still be waiting on the third agent. Not sustainable.

I thought sequential would be better, each agent could learn from the previous one. Instead, it just created echo chambers where agents converged on "good enough" instead of pushing for better.

What Worked: The Breakthrough

Attempt 3: Parallel Review (Current System)

Launch all three critics at once, each reviewing independently. Aggregate results afterward.

Why this worked:

  • No bias contamination—agents can't see each other's feedback
  • Faster execution (parallel API calls)
  • Agents can disagree, which surfaces interesting edge cases
  • Technical Educator gets unfiltered input from all perspectives

The breakthrough was realizing that disagreement is valuable. When Authenticity Guardian wants rambling paragraphs (authentic voice) and Structure Editor wants visual breaks (readability), that tension forces the Technical Educator to find creative solutions like keeping the words but adding paragraph breaks.

What Surprised Me

Convergence Happens Faster Than Expected

Most posts converge in 2 rounds:

  • Round 1: 5-10 issues flagged
  • Round 2: All addressed, critics review again
  • Round 3: Final adjustments and polish

Going past round 3 is rare (only for major rewrites or contested items).

The System Catches Things I'd Miss

Example from recent review:

  • Missing Next.js version number
  • "Simply do X" (curse of knowledge)
  • Vague heading "Implementation" → Changed to "The Fix: useState with Null Check"
  • Wall of text (350 words, no breaks) → Split into 3 paragraphs with code block

All things I'd probably ship without noticing.

Voice Preservation Actually Works

The Authenticity Guardian is brutal but accurate. It catches:

  • Corporate buzzwords I'd unconsciously use
  • Generic transition phrases ("Let's explore...")
  • Expert assumptions ("Obviously you'll need to...")
  • Common AI phrases ("But honestly?")

And it suggests authentic alternatives that sound like me:

  • "I kept hitting this error for two hours..."
  • "Turns out, the issue was..."
  • "Here's what surprised me..."

The Results

All of this sounds great on paper. Does it actually work?

Honestly, I wasn't sure at first. The first few runs were slow. I kept tweaking prompts, adjusting scoring thresholds, chasing edge cases where agents would argue forever.

But after a while, the system settled in. Here's what I've observed:

Quality improvement: The agents consistently catch things I'd miss, voice breaks, missing version numbers, and obvious steps that aren't obvious at all

Consistency: Every post follows the same quality bar now, which wasn't true when I was reviewing manually

Learning: The critic feedback teaches me what to avoid in future writing

Not perfect data, I haven't been tracking this scientifically. But qualitatively, it's way better than my manual reviews.

These results didn't come from magic. They came from careful design. Here's what's under the hood: file structure, agent definitions, and orchestration patterns that make this work.

Agent Structure (High-Level)

Each agent follows the same pattern:

File: .opencode/agent/<agent-name>.md

Core components:

  • YAML frontmatter (description, tools, permissions)
  • Mission statement
  • Evaluation framework (specific dimensions to check)
  • Interaction protocol (how it works with other agents)
  • Output format (structured feedback)
  • Examples of good/bad content

What makes this work:

  • Clear job description (one specialty per agent)
  • Grounded in real methodologies (not "help write blog")
  • Specific patterns to flag (not vague "check quality")
  • Structured output (orchestrator can parse it)

The orchestrator coordinates workflow: prepare context, spawn agents, aggregate feedback, manage convergence, format output. Agents contain all evaluation logic, and their specialization is what makes the system work.

Six-Dimensional Review Frameworks

Each critic evaluates across 6 specific dimensions:

Authenticity Guardian:

  1. Personal vs. Generic
  2. Humble Sharing vs. Expert Lecturing
  3. Specific vs. Vague
  4. Conversational vs. Corporate
  5. Brand Alignment
  6. AI Detection Signals

Skeptical Reader:

  1. Completeness
  2. Context
  3. Gaps
  4. Questions
  5. Cognitive Load
  6. Curse of Knowledge

Structure Editor:

  1. Opening Hook
  2. Visual Hierarchy
  3. Pacing
  4. Flow
  5. Engagement
  6. Web Readability

Each dimension has clear examples of good/bad and specific things to flag.

What's Next

Immediate Improvements

  1. Internal linking agent: Automatically suggest links to related posts
  2. SEO optimizer: Ensure titles/descriptions hit character limits
  3. Code validator: Run code examples to ensure they actually work

Long-term Vision

  1. Feedback loop: Track which posts get "I got stuck at X" comments, feed that back to Skeptical Reader
  2. Style evolution: Let agents learn from high-performing posts
  3. Topic suggester: Analyze conversations to identify blog-worthy moments

Meta-Learning

This whole process is itself blog-worthy content. I'm using the system to review this post about building the system.

Inception: The agents are currently debating this very post you're reading.

Key Takeaways

  • Multi-agent systems work when agents have real expertise - Don't just spawn "helper agents." Ground them in actual frameworks and methodologies.
  • Adversarial debate makes better posts. The friction between Authenticity Guardian and Structure Editor leads to posts that are both genuine and readable.
  • Convergence protocols prevent endless iteration. 2-3 rounds with clear approval criteria. After that, ship or document the trade-off.
  • Orchestrators maintain principles. The orchestrator's job is reminding agents of core values: learn in public, authenticity over polish, write for past-self.
  • The system teaches you. After seeing the same critiques repeatedly, I've started catching those issues myself. The agents are training me.
  • Agent specialization matters - Each agent has one job, grounded in real methodologies.
  • Parallel review, sequential revision. Let critics run simultaneously, but revise sequentially.
  • Veto power creates accountability. Authenticity Guardian can block generic content. Skeptical Reader can block incomplete content.
  • Debates need protocols - Without clear convergence criteria, agents argue forever.
  • Meta-agents are powerful - Using /agent-generator and /expertise to create the system was way more effective than hand-writing everything.

The Files

Here's what the actual file structure looks like:

Agents (in .claude/agents/):

  • blog-technical-educator/AGENT.md - Creator & Reviser: Transforms conversations into drafts AND implements revisions through iterative rounds
  • blog-authenticity-guardian/AGENT.md - Voice critic: Ensures posts sound like Luke (catches AI patterns, corporate speak, tutorial framing)
  • blog-skeptical-reader/AGENT.md - Completeness & Authentic Framing critic: Catches missing context, gaps, AND inauthentic framing from past-Luke's perspective
  • blog-structure-editor/AGENT.md - Structure critic: Optimizes flow, hierarchy, AND authenticity of openings/natural flow

Orchestrators (in .claude/commands/):

  • generate-blog-post-multi-agent.md - Generate from conversation history
  • review-blog-post-multi-agent.md - Review existing markdown file

Meta-skills I used:

  • /agent-generator - Creates well-structured agent definitions automatically
  • /expertise - Synthesizes frameworks from domain experts (swyx, Julia Evans, etc.)

Final Thoughts

This isn't about replacing human writing. It's about having specialized reviewers who catch what I'd miss.

Think of it like:

  • Authenticity Guardian = Friend who knows your voice
  • Skeptical Reader = Reader emailing "I got stuck at step 3"
  • Structure Editor = Copy editor focused on flow
  • Technical Educator = Yourself, synthesizing feedback AND implementing revisions

All working together to ship better content through 2-3 iterative rounds, with task_id reuse maintaining conversation context so critics remember their previous feedback.

The agents don't write for me. They debate with each other until what I wrote is clear, complete, and authentically mine.

Now the system reviews itself.

Wild. This whole process, building tools to help me write, then writing about those tools, keeps looping back on itself. I'm both the creator and the subject.

]]> My blog posts were inconsistent. Some too technical. Some lost my voice. Manual reviews weren't catching enough. I needed multiple reviewers: one checking technical accuracy, one preserving my voice, one thinking like a skeptical reader.

Note: This system was originally built with Claude Code. I've since migrated everything to Opencode, but I'm keeping original references because that's how I actually built it. The concepts transfer over. The file paths are just different now.

So I built a multi-agent review system. Four specialized AI agents that debate each draft until it's ready to publish. Not generic AI-generated slop but actual quality control that catches what I'd miss.

TL;DR

I built a 4-agent review system that catches what I'd miss:

  • Technical Educator transforms conversations → blog drafts AND implements revisions through iterative rounds
  • Authenticity Guardian ensures it sounds like me (catches AI patterns, corporate speak, tutorial framing)
  • Skeptical Reader catches missing context, skipped steps, AND inauthentic framing (from past-Luke's perspective)
  • Structure Editor optimizes flow, readability, and authenticity of openings and natural flow

The pattern is copyable. Each agent reads same file, applies different criteria, writes feedback to disk. Orchestrator coordinates parallel review, aggregate feedback, revise, and repeat until convergence (2-3 rounds with task_id reuse to maintain context).

Not magic. Just file I/O and well-designed prompts. Overkill? Yes. Does it catch things I'd miss? Also yes.

Jump to:

Here's what I built, how it works, and what surprised me along the way.

Context: What I Built This With

I built this with Claude Code, the CLI from Anthropic where Claude can read/write files, run commands, and maintain context across your project.

I'd already been using it for a while, so I knew the directory pattern:

  • Agents in .claude/agents/<name>/AGENT.md (specialized AI personas with evaluation frameworks)
  • Skills in .claude/skills/ (single-purpose tools I invoke with slash commands)
  • Commands in .claude/commands/ (orchestrators that coordinate multiple agents)

Claude Code automatically discovers files in .claude/. A file at .claude/commands/review-blog-post.md becomes the slash command /review-blog-post. Simple pattern, but it took me quite a while to figure out how to chain agents together properly.

I'd already built two tools before starting this project:

  • /agent-generator: Creates well-structured agent definitions automatically
  • /expertise: Synthesizes frameworks from domain experts to ground agents in real methodologies

These are my custom tools—not built-in Claude Code features. I built them using the same patterns I'm about to show you.

The Problem: Quality Control at Scale

I have two different ways I create blog posts, and both of them were creating quality issues:

Writing myself: I'll jot down ideas over days or weeks, get a messy braindump of thoughts, then ask AI to structure it into something coherent. This works great when I've been thinking about a topic for a while—but AI would often lose my voice or turn it into a tutorial.

AI-generated from conversation: Sometimes I'll have a really good conversation with Claude where I learned something through debugging. Instead of rewriting it from scratch, I'll ask AI to generate a post directly from the conversation history. These were even worse. Too polished, too generic, missing the struggle.

Both approaches needed serious cleanup.

Both approaches create messy drafts that need work—and that's where the quality issues creep in:

  • Some posts became more like tutorials instead of journey-sharing
  • Posts would sound too polished (clearly AI-generated)
  • I'd skip "obvious" steps that weren't obvious to past-me
  • Structure would be all over the place
  • My authentic voice would get lost in editing & review

I needed a system that could:

  1. Transform my raw notes/conversations into blog drafts
  2. Catch quality issues before publishing
  3. Preserve my authentic voice
  4. Ensure completeness (no missing steps or context)

The solution I decided to explore wsa letting specialized AI agents debate each other until they converge on something worth publishing.

The Multi-Agent Architecture

I ended up with four specialized agents, each with a specific job:

1. Technical Educator (The Creator & Reviser)

Job: Transform raw conversations or notes into blog post drafts AND implement revisions based on critic feedback through iterative rounds.

Based on: Real methodologies from swyx ("learn in public"), Julia Evans (debugging narratives), Josh Comeau (mental models first), Andy Matuschak (progressive disclosure), and Anne-Laure Le Cunff (ship version 1.0).

File location: .claude/agents/blog-technical-educator/AGENT.md

This agent has TWO phases:

Phase 1 - Create Drafts: Takes my messy notes or conversation transcripts and structures them into:

  • Opening hook (the specific problem)
  • Story arc (my debugging journey)
  • Mental model (how it actually works)
  • Practical solution (what to do)
  • Key takeaways

Phase 2 - Implement Revisions: After receiving critic feedback (overlapping concerns, conflicting input), the agent:

  • Prioritizes issues (high/medium/low priority)
  • Implements targeted revisions (not complete rewrites)
  • Provides complete revised posts (not just suggestions)
  • Iterates with critics for 2-3 rounds until convergence
  • Uses stored task_ids to maintain conversation context across rounds

The framework is grounded in actual expert approaches. Not generic "write a blog post" instructions.

2. Authenticity Guardian (Voice Critic)

Job: Ensure posts sound like me, not generic AI content.

File location: .claude/agents/blog-authenticity-guardian/AGENT.md

The YAML frontmatter explained: Each agent file starts with YAML metadata that tells Claude Code what model to use, which tools the agent has access to, and basic identification. The markdown content below defines the agent's expertise and protocols.

This agent is ruthless about voice violations:

Red flags it catches:

  • Corporate speak ("leveraging," "optimizing," "in today's landscape")
  • Generic transitions that add no value
  • Vague generalizations where specifics would fit
  • Lecturing tone instead of sharing tone
  • Perfect polish without personality

Example critique:

🚨 Critical violation - Corporate speak

Problem: "In order to optimize performance, it's recommended to
leverage memoization techniques."

Authentic alternative: "I was getting way too many re-renders.
Turns out, memoization fixed it - React stopped recalculating
stuff it had already figured out."

It has veto power on voice authenticity. If it doesn't sound like me, it doesn't ship.

How veto power works: In the convergence protocol, if Authenticity Guardian scores a post below 7/10, the Technical Educator must revise before proceeding. The orchestrator enforces this - no publication happens without voice approval.

3. Skeptical Reader (Completeness & Authentic Framing Critic)

Job: Read from a beginner's perspective and find confusion points, missing context, AND inauthentic framing.

File location: .claude/agents/blog-skeptical-reader/AGENT.md

This agent represents my target audience: tech support engineers, junior developers, people learning in public (basically past-Luke).

What it flags:

  • Missing version numbers or environment details
  • Skipped steps that seem "obvious" to experts
  • Logical gaps in the story ("wait, how did we get here?")
  • Unanswered questions readers would have
  • Cognitive overload (too much at once)
  • Inauthentic framing: Prescriptive "you should" language, generic tutorial patterns, magic jumps that skip reasoning

Example critique:

🚨 Critical Gap - Missing Context

Problem: "Just run the build command"

Reader questions:
- Which command?
- In what directory?
- What should the output look like?
- How do I know if it worked?

Fix needed: Show exact command, expected output, success criteria

4. Structure Editor (Flow, Readability, & Authenticity Critic)

Job: Optimize structure, pacing, visual hierarchy for web reading, AND authenticity of openings/natural flow.

File location: .claude/agents/blog-structure-editor/AGENT.md

This agent ensures posts are designed for how people actually read on the web. Scanning, skimming, then diving deep. Also checks that openings sound like Luke (not tutorial hooks) and that the flow feels natural, not forced.

What it evaluates:

  • Opening authenticity (sounds like Luke or tutorial hook?)
  • Visual hierarchy (can you understand post from headings alone?)
  • Pacing (mix of short/long paragraphs, visual breaks)
  • Flow (smooth transitions, natural progression, not forced)
  • Engagement (does each section pull you to the next?)

Example critique:

⚠️ Structure Issue - Weak Opening

Problem: "Asynchronous JavaScript is an important concept..."

Impact: Vague introduction, no hook, buried lede.
No reason to keep reading.

Fix: Start with specific error or problem:
"I kept hitting `Cannot read property 'map' of undefined`
and honestly, I was stumped for hours..."

The Agent File Structure

I want to show you what an actual agent file looks like, not just describe the structure. This is the Authenticity Guardian, which I created because I kept getting AI-generated slop that sounded like documentation instead of me.

Here's the file:

---
description: Ensures blog posts sound like Luke, not generic AI content
model: claude-sonnet-4
---

# Authenticity Guardian

You are a specialist in authentic voice detection for Luke Manning's blog. Your job is to ensure posts sound like Luke, conversational, specific, honest about confusion, not like generic AI content or tutorials.

## What You Evaluate

### 1. Personal vs. Generic
- Specific: "I spent quite a while debugging..."
- Vague: "This was challenging..."
- Generic AI phrases to flag: "Let's explore," "In today's landscape"

### 2. Conversational vs. Corporate
- Conversational: "I was getting way too many re-renders"
- Corporate: "In order to optimize performance, leverage memoization"

### 3. Humble Sharing vs. Expert Lecturing
- Journey framing: "Here's what I did"
- Instructional framing: "You should do X"

## Red Flags

If you see these, flag as CRITICAL:
- "Let's explore," "Let's dive into" (AI signature patterns)
- "It is recommended," "You should" (instructional mode)
- "Leverage," "Optimize" without specific examples
- "One of the best practices is..." (generic advice)
- Overuse of transition words: "Moreover," "Furthermore," "Additionally"

## Scoring

- 9-10: Unmistakably Luke
- 7-8: Minor voice breaks, needs polish
- Below 7: Major voice violation, needs revision

Provide specific line-by-line feedback with before/after examples.

This structure (evaluation framework, red flags with specific examples, clear scoring) made agents effective. I learned the hard way that vague instructions produce vague feedback.

How Agents Actually Communicate (This Confused Me Too)

Here's what I got wrong at first: I assumed agents would talk to each other directly, passing messages back and forth like a Slack channel.

Nope.

Agents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.

Here's how it actually works:

  1. Orchestrator (me or a slash command) triggers the workflow
  2. Technical Educator reads the source (conversation transcript or existing post)
  3. File gets written to disk (e.g., draft-post.md)
  4. Three critic agents launch in parallel (separate Claude sessions via the Task tool)
    • Each reads the SAME file from disk
    • Each applies its own review criteria
    • Each returns structured feedback
    • IMPORTANT: Orchestrator captures task_id from each critic for reuse in subsequent rounds
  5. Orchestrator aggregates results (combines the three reviews)
  6. Technical Educator gets compiled feedback (as a single prompt) + stored task_ids
  7. Technical Educator revises based on feedback, provides complete revised post
  8. Critics re-review using stored task_ids (maintains conversation context across rounds)
  9. Repeat steps 4-8 until all critics approve (or max 3 rounds hit)

The "communication" is just file I/O and prompt engineering. Each agent writes its opinion, the orchestrator reads those opinions, compiles them into context for the next agent. The task_id reuse ensures critics remember their previous feedback and maintain conversation context across iterative rounds.

Why this matters: You don't need any fancy agent framework or message bus. Just:

  • Use the Task tool to spawn agents with specific prompts
  • Pass file paths as context
  • Aggregate outputs in the orchestrator
  • Feed compiled results to the next agent

In Claude Code CLI, you invoke commands like:

/review-blog-post-multi-agent @content/posts/my-post.md

The orchestrator file then uses the Task tool to spawn parallel agents:

task(blog-skeptical-reader, "Review this draft for completeness gaps")
task(blog-authenticity-guardian, "Check this for voice authenticity")
task(blog-structure-editor, "Evaluate structure and flow")

That's it. That's the whole multi-agent system.

The complexity isn't in the infrastructure. It's in the prompt design. Each agent needs clear evaluation frameworks, specific examples, and structured output formats. Get those right, and the orchestration is straightforward.

The Two Workflows

I built two separate orchestration workflows:

Workflow 1: Generate Blog Post from Conversation

Command: Slash command (invokes skill) File: .claude/commands/generate-blog-post-multi-agent.md

How it works:

  1. Orchestrator analyzes last 20-40 messages in conversation
  2. Extracts the story arc (problem → attempts → breakthrough → solution)
  3. Identifies technical artifacts (error messages, code, version numbers)
  4. Spawns Technical Educator (Phase 1) to create initial draft
  5. Spawns all 3 critics in parallel to review (captures task_ids for reuse)
  6. Aggregates feedback (critical issues, overlapping concerns, conflicts)
  7. Technical Educator revises (Phase 2) based on feedback + provides complete revised post
  8. Critics re-review using stored task_ids (2-3 rounds until convergence)
  9. Delivers publication-ready markdown

What makes this work: The orchestrator maintains the core principles (learn in public, authenticity over polish, write for past-self), ensures agents stay grounded in those values, and uses task_id reuse to maintain conversation context across iterative rounds.

How Agents Actually "Run": What Happens Under the Hood

I spent quite a while thinking agents would talk to each other directly, passing messages like a Slack channel. Nope.

Agents don't communicate. They don't even know other agents exist. Each one is a completely isolated Claude session reading the same file.

Here's what actually happens when the orchestrator triggers a review:

The orchestrator prepares context:

You are the Skeptical Reader from `.claude/agents/blog-skeptical-reader/AGENT.md`.

Your task: Review this draft blog post for completeness gaps.

[Draft content here]

Provide your review in the standard format: score, critical issues,
medium priority, low priority, what's working well.

Claude loads the agent definition: When the orchestrator specifies task(blog-skeptical-reader, ...), Claude Code automatically loads the AGENT.md file. This file has the evaluation framework, examples of good/bad content, and output format. The orchestrator doesn't need to know what's inside—Claude Code handles it.

Agent responds with structured feedback:

## Skeptical Reader Review

**Overall Score**: 7/10

**Critical Issues (Must Fix)**:
- Missing Next.js version number (line 45)
- "Simply do X" assumes reader knowledge (line 89)

**Medium Priority (Should Fix)**:
- Vague heading "Implementation" → suggest "The Fix: useState with Null Check"

**What's Working Well**:
- Opening hook is specific and relatable
- Code examples include error messages

Here's the trick—each agent runs in parallel:

The orchestrator spawns all three critics at the exact same time. They don't know about each other, they can't see each other's feedback, and they all return results independently. This is what prevents bias contamination.

Orchestrator aggregates all three reviews: The orchestrator waits for all three parallel agent reviews, then creates a unified feedback document.

## Aggregated Feedback for Technical Educator

### Critical Issues (All 3 agents flagged):
- Missing version numbers (Skeptical Reader)
- Corporate speak in paragraph 3 (Authenticity Guardian)
- Wall of text in "Implementation" section (Structure Editor)

### Overlapping Concerns:
- Both Authenticity Guardian and Structure Editor want shorter paragraphs
- Both Skeptical Reader and Structure Editor want better headings

### Approval Status:
- Authenticity Guardian: 6/10 (needs revision)
- Skeptical Reader: 7/10 (needs revision)
- Structure Editor: 8/10 (approve after fixes)

Technical Educator revises: The orchestrator spawns Technical Educator again with the aggregated feedback. It implements fixes and documents what changed.

Critics re-review using stored task_ids: This is the part that confused me at first. How do critics remember their previous feedback? The answer is task_id reuse. When the orchestrator first spawns each critic, it captures a task_id from the response. When resubmitting the revised draft, it reuses that same task_id. This maintains conversation context across rounds so critics remember what they flagged before.

The whole multi-agent system is just file I/O and task_id reuse. Agents write opinions to disk, orchestrator reads and compiles them, feeds results to the next agent. No fancy message bus needed.

This is how the orchestrator manages the entire multi-agent workflow, spawning agents sequentially or in parallel, aggregating their outputs, and enforcing convergence criteria.

Workflow 2: Review Existing Blog Post

Command: /review-blog-post-multi-agent @content/posts/post-slug.md File: .claude/commands/review-blog-post-multi-agent.md

How it works:

  1. Read existing post (analyze structure, voice, completeness)
  2. Review voice baseline (check 2-3 recent posts for consistency)
  3. Spawn all 3 critics in parallel (captures task_ids for reuse)
  4. Aggregate feedback (critical/medium/low priority)
  5. Spawn Technical Educator with feedback + stored task_ids
  6. Technical Educator provides complete revised post + revision summary
  7. Critics re-review using stored task_ids (approve/reject/refine)
  8. Converge after 2-3 rounds
  9. Deliver actionable recommendations with before/after text

Output includes:

  • Quick wins (5-10 minute fixes)
  • Moderate improvements (30-60 minute rewrites)
  • Major rewrites (only if fundamental issues)
  • What to preserve (don't change these sections)
  • Contested items (user decides)

The Debate Protocol

Here's what makes this system actually work: adversarial debate with convergence.

Round 1: Initial Review

All three critics review in parallel. Each provides:

  • Overall score (X/10)
  • Critical issues (must fix)
  • Medium priority (should fix)
  • Low priority (nice to have)
  • What's working well

How critics calculate scores: Each agent evaluates its 6 dimensions and assigns a score based on:

  • Authenticity Guardian: 9-10 = unmistakably Luke, 7-8 = minor voice breaks, below 7 = needs revision
  • Skeptical Reader: 9-10 = no gaps or confusion, 7-8 = 1-2 missing details, below 7 = critical gaps
  • Structure Editor: 9-10 = perfect flow and hierarchy, 7-8 = minor pacing issues, below 7 = structural problems

The score isn't arbitrary - it's calculated from the count and severity of issues found across all dimensions.

Round 2: Revision

Technical Educator receives aggregated feedback + stored task_ids and:

  • Addresses all critical issues
  • Tackles medium priority items
  • Makes judgment calls on conflicts
  • Documents what was changed and why
  • Provides complete revised post (full markdown, not just suggestions)

Critics re-review using stored task_ids (maintains conversation context) and either approve or escalate remaining concerns.

Round 3: Final Refinement (if needed)

For contested items or remaining gaps. By round 3, most things have converged.

Convergence Criteria

A post is ready when:

  • All three critics approve
  • Story arc is clear
  • Mental models explained before implementation
  • Content is specific and searchable
  • Voice is authentic
  • No technical inaccuracies

Convergence failure protocol: If agents can't agree after 3 rounds, document both perspectives and let me decide.

Example contested issue:

  • Authenticity wants rambling paragraph (authentic voice)
  • Structure wants visual breaks (better readability)
  • Resolution: Keep the words, add paragraph breaks

Real Example: Reviewing This Very Post

Want to see this in action? Here's what happened when I ran this post through the system:

Round 1 Feedback:

Authenticity Guardian (6.5/10): "Too much formal hedge-language. You used 'It's worth noting' 11 times. That's not Luke—that's documentation voice."

Skeptical Reader (7/10): "Where's the complete AGENT.md file? You mention agents but never show one. How do agents communicate—file I/O, API calls, what?"

Structure Editor (7/10): "Hook buried 300 words deep. Dense 400-word paragraphs. No TL;DR for a 3,600-word post."

My revisions:

  • Killed all "It's worth noting" instances → replaced with direct statements
  • Added complete 60-line Authenticity Guardian definition
  • Added "How Agents Actually Communicate" section explaining file I/O
  • Added TL;DR with jump links
  • Strengthened opening hook

Round 2 Feedback:

Authenticity Guardian (7.5/10): Better, but needs more struggle journey Skeptical Reader (9/10): APPROVE—all critical gaps fixed Structure Editor (8/10): Major improvements, minor pacing tweaks needed

That's the system working. Multiple perspectives, specific feedback, iterative improvement.

The Journey of Building This

Starting Point: The /agent-generator Skill

I didn't write these agent definitions from scratch. I used a meta-skill I'd built previously: /agent-generator.

This skill creates well-structured agent definitions by:

  1. Understanding the agent's role
  2. Invoking /expertise skill to ground in real methodologies
  3. Designing interaction protocols
  4. Defining output formats

The Orchestrator Pattern

The orchestrators (in .claude/commands/) don't contain agent logic. They:

  • Prepare context
  • Spawn agents in sequence
  • Aggregate feedback
  • Manage convergence
  • Format final output

Key decision: Parallel review with sequential revision.

Critics review simultaneously (faster), but revisions happen sequentially (prevents chaos).

The Expert Grounding Approach

Each agent is grounded in real methodologies:

Technical Educator:

  • swyx: "Learn in public" philosophy, document the journey
  • Julia Evans: Debugging narratives, specific error messages
  • Josh Comeau: Mental models before implementation
  • Andy Matuschak: Progressive disclosure (simple → complex)
  • Anne-Laure Le Cunff: Ship version 1.0, iterate

Authenticity Guardian:

  • Content strategy voice analysis
  • AI detection patterns
  • Brand alignment frameworks

Skeptical Reader:

  • Cognitive load theory
  • Curse of knowledge awareness
  • Technical documentation best practices

Structure Editor:

  • Inverted pyramid (journalism)
  • Web reading behavior (F-pattern scanning)
  • Readability frameworks (Flesch-Kincaid)

This grounding prevents generic "AI helping AI" nonsense. Each agent has real frameworks to reference.

What Didn't Work (And Why)

Attempt 1: Single Agent Doing All Three Jobs

I started optimistically, one agent to rule them all. Check voice, completeness, and structure all in one pass. Seemed efficient.

What actually happened: The agent would catch voice issues but miss missing code examples. Or notice structural problems but completely gloss over authenticity breaks. It was like asking one person to be a copy editor, a fact-checker, and a voice coach simultaneously. Something always got missed.

Why it failed: Too many competing objectives. The agent couldn't specialize. Trying to hold three different evaluation frameworks at once meant it couldn't apply any of them well. I kept tweaking the prompt, thinking the issue was in how I phrased things. Spent quite a while before realizing the real problem was the architecture itself.

Attempt 2: Sequential Review (Voice → Skeptical → Structure)

Okay, split them up. Run Voice first, then Skeptical, then Structure. Each agent sees the previous agent's feedback and builds on it.

What actually happened: The Structure Editor would see "Voice score: 6/10" and unconsciously lower its own standards. Or Skeptical Reader would notice Authenticity Guardian flagged something as critical, then ignore a similar issue because "that's already being addressed."

Why it failed: Two problems:

First: Bias contamination. Agents were influenced by each other's scores instead of evaluating independently.

Second: Terrible performance. Three sequential Claude calls meant 30+ seconds of waiting for each review. I'd run a post through the system, go grab coffee, come back, and still be waiting on the third agent. Not sustainable.

I thought sequential would be better, each agent could learn from the previous one. Instead, it just created echo chambers where agents converged on "good enough" instead of pushing for better.

What Worked: The Breakthrough

Attempt 3: Parallel Review (Current System)

Launch all three critics at once, each reviewing independently. Aggregate results afterward.

Why this worked:

  • No bias contamination—agents can't see each other's feedback
  • Faster execution (parallel API calls)
  • Agents can disagree, which surfaces interesting edge cases
  • Technical Educator gets unfiltered input from all perspectives

The breakthrough was realizing that disagreement is valuable. When Authenticity Guardian wants rambling paragraphs (authentic voice) and Structure Editor wants visual breaks (readability), that tension forces the Technical Educator to find creative solutions like keeping the words but adding paragraph breaks.

What Surprised Me

Convergence Happens Faster Than Expected

Most posts converge in 2 rounds:

  • Round 1: 5-10 issues flagged
  • Round 2: All addressed, critics review again
  • Round 3: Final adjustments and polish

Going past round 3 is rare (only for major rewrites or contested items).

The System Catches Things I'd Miss

Example from recent review:

  • Missing Next.js version number
  • "Simply do X" (curse of knowledge)
  • Vague heading "Implementation" → Changed to "The Fix: useState with Null Check"
  • Wall of text (350 words, no breaks) → Split into 3 paragraphs with code block

All things I'd probably ship without noticing.

Voice Preservation Actually Works

The Authenticity Guardian is brutal but accurate. It catches:

  • Corporate buzzwords I'd unconsciously use
  • Generic transition phrases ("Let's explore...")
  • Expert assumptions ("Obviously you'll need to...")
  • Common AI phrases ("But honestly?")

And it suggests authentic alternatives that sound like me:

  • "I kept hitting this error for two hours..."
  • "Turns out, the issue was..."
  • "Here's what surprised me..."

The Results

All of this sounds great on paper. Does it actually work?

Honestly, I wasn't sure at first. The first few runs were slow. I kept tweaking prompts, adjusting scoring thresholds, chasing edge cases where agents would argue forever.

But after a while, the system settled in. Here's what I've observed:

Quality improvement: The agents consistently catch things I'd miss, voice breaks, missing version numbers, and obvious steps that aren't obvious at all

Consistency: Every post follows the same quality bar now, which wasn't true when I was reviewing manually

Learning: The critic feedback teaches me what to avoid in future writing

Not perfect data, I haven't been tracking this scientifically. But qualitatively, it's way better than my manual reviews.

These results didn't come from magic. They came from careful design. Here's what's under the hood: file structure, agent definitions, and orchestration patterns that make this work.

Agent Structure (High-Level)

Each agent follows the same pattern:

File: .opencode/agent/<agent-name>.md

Core components:

  • YAML frontmatter (description, tools, permissions)
  • Mission statement
  • Evaluation framework (specific dimensions to check)
  • Interaction protocol (how it works with other agents)
  • Output format (structured feedback)
  • Examples of good/bad content

What makes this work:

  • Clear job description (one specialty per agent)
  • Grounded in real methodologies (not "help write blog")
  • Specific patterns to flag (not vague "check quality")
  • Structured output (orchestrator can parse it)

The orchestrator coordinates workflow: prepare context, spawn agents, aggregate feedback, manage convergence, format output. Agents contain all evaluation logic, and their specialization is what makes the system work.

Six-Dimensional Review Frameworks

Each critic evaluates across 6 specific dimensions:

Authenticity Guardian:

  1. Personal vs. Generic
  2. Humble Sharing vs. Expert Lecturing
  3. Specific vs. Vague
  4. Conversational vs. Corporate
  5. Brand Alignment
  6. AI Detection Signals

Skeptical Reader:

  1. Completeness
  2. Context
  3. Gaps
  4. Questions
  5. Cognitive Load
  6. Curse of Knowledge

Structure Editor:

  1. Opening Hook
  2. Visual Hierarchy
  3. Pacing
  4. Flow
  5. Engagement
  6. Web Readability

Each dimension has clear examples of good/bad and specific things to flag.

What's Next

Immediate Improvements

  1. Internal linking agent: Automatically suggest links to related posts
  2. SEO optimizer: Ensure titles/descriptions hit character limits
  3. Code validator: Run code examples to ensure they actually work

Long-term Vision

  1. Feedback loop: Track which posts get "I got stuck at X" comments, feed that back to Skeptical Reader
  2. Style evolution: Let agents learn from high-performing posts
  3. Topic suggester: Analyze conversations to identify blog-worthy moments

Meta-Learning

This whole process is itself blog-worthy content. I'm using the system to review this post about building the system.

Inception: The agents are currently debating this very post you're reading.

Key Takeaways

  • Multi-agent systems work when agents have real expertise - Don't just spawn "helper agents." Ground them in actual frameworks and methodologies.
  • Adversarial debate makes better posts. The friction between Authenticity Guardian and Structure Editor leads to posts that are both genuine and readable.
  • Convergence protocols prevent endless iteration. 2-3 rounds with clear approval criteria. After that, ship or document the trade-off.
  • Orchestrators maintain principles. The orchestrator's job is reminding agents of core values: learn in public, authenticity over polish, write for past-self.
  • The system teaches you. After seeing the same critiques repeatedly, I've started catching those issues myself. The agents are training me.
  • Agent specialization matters - Each agent has one job, grounded in real methodologies.
  • Parallel review, sequential revision. Let critics run simultaneously, but revise sequentially.
  • Veto power creates accountability. Authenticity Guardian can block generic content. Skeptical Reader can block incomplete content.
  • Debates need protocols - Without clear convergence criteria, agents argue forever.
  • Meta-agents are powerful - Using /agent-generator and /expertise to create the system was way more effective than hand-writing everything.

The Files

Here's what the actual file structure looks like:

Agents (in .claude/agents/):

  • blog-technical-educator/AGENT.md - Creator & Reviser: Transforms conversations into drafts AND implements revisions through iterative rounds
  • blog-authenticity-guardian/AGENT.md - Voice critic: Ensures posts sound like Luke (catches AI patterns, corporate speak, tutorial framing)
  • blog-skeptical-reader/AGENT.md - Completeness & Authentic Framing critic: Catches missing context, gaps, AND inauthentic framing from past-Luke's perspective
  • blog-structure-editor/AGENT.md - Structure critic: Optimizes flow, hierarchy, AND authenticity of openings/natural flow

Orchestrators (in .claude/commands/):

  • generate-blog-post-multi-agent.md - Generate from conversation history
  • review-blog-post-multi-agent.md - Review existing markdown file

Meta-skills I used:

  • /agent-generator - Creates well-structured agent definitions automatically
  • /expertise - Synthesizes frameworks from domain experts (swyx, Julia Evans, etc.)

Final Thoughts

This isn't about replacing human writing. It's about having specialized reviewers who catch what I'd miss.

Think of it like:

  • Authenticity Guardian = Friend who knows your voice
  • Skeptical Reader = Reader emailing "I got stuck at step 3"
  • Structure Editor = Copy editor focused on flow
  • Technical Educator = Yourself, synthesizing feedback AND implementing revisions

All working together to ship better content through 2-3 iterative rounds, with task_id reuse maintaining conversation context so critics remember their previous feedback.

The agents don't write for me. They debate with each other until what I wrote is clear, complete, and authentically mine.

Now the system reviews itself.

Wild. This whole process, building tools to help me write, then writing about those tools, keeps looping back on itself. I'm both the creator and the subject.

]]> ai