A deep research agent earns trust through verification, not fluency. I run two research workflows that prove the point from opposite ends. One is a heavyweight harness that fans out across sources and adversarially checks every claim — roughly 100 model calls for a single question. The other is a lightweight daily scanner that makes one model call and never fans out. The lesson is matching the workflow shape to the job, and this post shows both shapes with the real numbers behind them.

Here's the architecture of the heavy one, the verification mechanism that makes it trustworthy, the price that rigor costs, and when the cheap workflow is the right call instead.

The Shape of a Deep Research Agent

The harness runs as a Claude Code workflow — a script that fans work out to subagents and collects structured results. The question moves through five phases:

The first decision is the fan-out. A single agent searching one query sees one slice of the topic. Five agents searching five angles — broad, technical, recent, contrarian, practitioner — surface evidence no single query would. Search and fetch run as a pipeline with no barrier between them, so a source found by the fast "recent news" angle starts extracting while the "academic" angle is still searching:

phase('Scope');
const scope = await agent(scopePrompt(question), { schema: SCOPE_SCHEMA }); // 5 angles

// Search (parallel) -> dedupe URLs -> fetch + extract. No barrier between stages.
const sources = await pipeline(
  scope.angles,
  (angle) => agent(searchPrompt(angle), { phase: 'Search', schema: SEARCH_SCHEMA }),
  (found) =>
    parallel(
      capToFetchBudget(dedupeByUrl(found), MAX_FETCH).map(
        (src) => () => agent(fetchPrompt(src), { phase: 'Fetch', schema: EXTRACT_SCHEMA }),
      ),
    ),
);

Each fetched source returns two to five falsifiable claims — concrete, checkable statements — each carrying a direct quote and a rating of central, supporting, or tangential. Vague generalities are rejected at extraction. A claim with no quote behind it never enters the pool.

Adversarial Verification: Make the Agent Argue With Itself

This is the part that separates a research agent from a summarizer. Every claim that matters is handed to three skeptics, each told to refute it. Their job is not neutral assessment. They hunt for the source that contradicts it, the overreach past the quote, the stale benchmark, the marketing copy dressed as a finding. A claim survives only if fewer than two of three votes refute it, and only if enough valid votes came back to adjudicate it at all:

const VOTES_PER_CLAIM = 3;
const REFUTATIONS_REQUIRED = 2;

const voted = await parallel(
  rankedClaims.map((claim) => () =>
    parallel(
      Array.from({ length: VOTES_PER_CLAIM }, (_, v) => () =>
        agent(refutePrompt(claim, v), { phase: 'Verify', schema: VERDICT_SCHEMA }),
      ),
    ).then((verdicts) => {
      const valid = verdicts.filter(Boolean); // a vote can abstain (null) on error or skip
      const refuted = valid.filter((v) => v.refuted).length;
      // Survive only if a quorum actually adjudicated AND fewer than 2 refuted.
      // All-abstain must not pass: refuted=0 would otherwise look like a clean win.
      const survives = valid.length >= REFUTATIONS_REQUIRED && refuted < REFUTATIONS_REQUIRED;
      return { ...claim, survives };
    }),
  ),
);
const confirmed = voted.filter((c) => c.survives);

Two details carry the weight. First, the verifier's verdict is structured, not prose:

interface Verdict {
  refuted: boolean;
  evidence: string; // must be specific — a contradicting source or a misread of the quote
  confidence: 'high' | 'medium' | 'low';
  counterSource?: string;
}

Second, the prompt sets the default to refuted=true when uncertain. A neutral verifier rounds toward "sounds plausible," which is how hallucinations survive. A verifier that must clear a skeptical bar rounds toward "not proven," which is the safer error for research. The abstention handling matters for the same reason: if every voter errors out, the claim has zero refutations, and a naive count would pass it. Requiring a quorum of real votes closes that gap.

Why Structured Output at Every Hop

Every phase returns typed JSON against a schema — scope, search results, extracted claims, verdicts, the final report. The orchestrator never parses prose. It reads verdicts.filter(v => v.refuted) and moves on. This is the same lesson from moving agent orchestration into code: the model produces data, and plain code makes the decisions. Schemas are the contract that keeps the control flow deterministic while the agents stay creative inside their boxes.

The synthesis step is the one place judgment returns. It receives only the confirmed claims, merges the ones that say the same thing, groups them into findings, assigns a confidence per finding, and writes a short answer with caveats and open questions. The refuted claims ride along in a transparency block, so the report shows its work — what it killed, not only what it kept.

The Cost of Being Right

Rigor is not cheap. The total model calls for one question follow a clear formula:

1 (scope) + 5 (search angles) + ~15 (sources) + 25 × 3 (verify) + 1 (synthesize) ≈ 97

Close to a hundred model calls to answer one question well. That is the deliberate trade. Take a one-off, high-stakes question: a technical decision, a medical differential, a market claim you are about to repeat in front of a client. A hundred calls is a rounding error against being confidently wrong. The adversarial panel is the difference between a report you can cite and a paragraph you have to re-check by hand.

It is the wrong trade for anything you do at volume. Run this harness on a schedule across many topics and the call count multiplies past any reasonable budget. That is where the second shape comes in.

The Other Shape: a Daily Scanner That Doesn't Fan Out

The contrast is a market scanner I built into an internal tool. It watches a set of competitors and trends and surfaces what changed, ranked by how much it matters. The requirements invert the deep research agent's: it runs every day, across many watches, and a missed item is cheaper than a blown budget. So it makes exactly one model call per scan — claude-sonnet-4-6 with the server-side web search tool — and never fans out:

const res = await client.messages.create({
  model: 'claude-sonnet-4-6',
  max_tokens: 8000,
  tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: 8 }],
  system: SCAN_SYSTEM, // "Ground every signal in real results. If you can't verify it, drop it."
  messages: [{ role: 'user', content: watchBrief }],
});

The model searches up to eight times inside that single call, returns structured signals, and plain code does the ranking. Each signal scores on three factors, and the severity tier falls out of the score:

const score = materiality * relevance * recencyWeight; // each in 0..1
const severity = score >= 0.45 ? 'high' : score >= 0.25 ? 'medium' : 'low';

Recency is a bucketed decay — a result from today weights 1.0, one from the last month 0.8, anything past 90 days 0.6 — so fresh moves rise without a fragile timestamp formula. Deduplication is a fingerprint, sha1(lane | normalized-title), checked against history so the same development never surfaces twice. A daily cron at 00:00 UTC runs the scan for every active watch and writes a ranked digest.

The honest limitation: there is no adversarial verification here. The system prompt tells the model to drop anything it cannot ground in a real result, and then it trusts that instruction. For continuous monitoring that is the right floor — a low-stakes feed where a human reviews items before acting. For a claim I am about to stake a decision on, it would not be enough. Different job, different floor.

Match the Workflow to the Job

The two workflows are the same idea tuned to opposite constraints. Neither uses Claude Managed Agents, which I reached for in the durable build pipeline — a reminder that the heavy infrastructure is a choice, not a default. A research workflow needs web access and structured output, not a persistent sandbox.

Use the deep research agent when being wrong is expensive and the question is worth a hundred calls: a one-time investigation, a claim headed into a deliverable, a decision that is hard to reverse. Skip it when you need an answer in seconds, the stakes are low, or you are running the same query on a schedule — the verification overhead buys nothing there.

Use the single-call scanner when volume and cost dominate and a human stays in the loop. Skip it when the output feeds an irreversible action with no review, because one ungrounded item can slip through. The scanner is a floor; the deep research agent is a gate.

Conclusion

A deep research agent is not a smarter summarizer. It is a workflow that assumes its own sources are guilty until verified, and the adversarial panel is what makes the output worth citing. The cheaper scanner is the same instinct at a different price point — grounded, deduplicated, ranked, and deliberately un-verified because the job tolerates it. Both beat the default research agent that reports its first plausible result.

Key Takeaways:

• Make the agent argue with itself: three skeptics per claim, kill on two refutations, and default to refuted when uncertain — neutrality is how hallucinations pass
• Fan out across distinct angles so no single query defines the answer, and require a quote behind every extracted claim
• Keep structured output at every hop so the orchestrator is plain code reading typed JSON, not a parser of prose
• Adversarial rigor costs ~100 model calls per question — worth it for high-stakes one-offs, wrong for anything you run at volume
• Match the workflow to the job: a single grounded call with web search for continuous monitoring, a fan-out-and-verify harness for decisions you cannot take back

This is the companion to durable agent orchestration. That post fixed the routing in code; this one shows what to do when the routing is fixed but the evidence cannot be trusted — verify it, adversarially, before it counts.

Anthropic's callable_agents API lets one coordinator agent delegate to specialists, which is the approach I used in my multi-agent auto-PR pipeline. Both are legitimate agent orchestration patterns. This time I went the other way. Each stage is a durable step that creates a session, waits for the agent to finish, pulls its output file, and writes it to Postgres before the next stage starts. The control flow is plain TypeScript, not a model's runtime judgment.

Here's the full pipeline, the session-completion bug that cost me a day, the model-routing decision I reversed, the safety gate that stops generated plugins from auto-shipping, and when this approach is the wrong one.

Two Ways to Handle Agent Orchestration

There are two honest answers to "how do agents hand work to each other," and they suit different problems.

Agent Orchestration. One agent holds a callable_agents list and decides who runs next. Handoffs are messages between isolated threads. This fits when the routing itself needs judgment — when the next step depends on what the last agent discovered, or the graph branches in ways you can't enumerate ahead of time. The cost: the control flow lives in a model's head. It is nondeterministic, and it spends tokens having the coordinator reason about routing you may already know. Resuming after a crash at stage four means reconstructing where the coordinator was.

Agent workflow. The control flow is code. Stage order is fixed and visible in a file. Each step is durable — if the process dies after Scaffold, the run resumes at Review instead of starting over. Every stage writes its artifact to a database row, so a browser refresh replays the run from stored state rather than re-running agents.

I chose durable steps because my routing was fixed. A six-stage assembly line doesn't need a model to decide what comes next. It needs each station to be reliable, observable, and resumable. The orchestrator is Vercel Workflow; each stage is a "use step" function.

The Pipeline: Six Surfaces, Four Agents

The run moves through six surfaces. Only four of them are Managed Agents.

Stage 0 is the first design lesson. Intake is not a Managed Agent — it is one structured-output Messages API call. Parsing free text into a typed JSON spec needs no container, no tools, and no file output, so a session would add startup latency and cost for nothing. The rule I now follow: reserve Managed Agents for stages that need a sandbox, tools, and a written artifact. Everything else stays a Messages call.

Each Managed-Agent stage is the same durable shape — create a session, send the work, wait for a true finish, persist the output:

// One pipeline stage as a durable Vercel Workflow step
export async function designStage(runId: string, intent: IntentSpec) {
  'use step';

  const session = await client.beta.sessions.create({
    agent: env.ANTHROPIC_AGENT_ID_DESIGNER,
    environment_id: env.ANTHROPIC_ENVIRONMENT_ID,
  });

  await client.beta.sessions.events.send(session.id, {
    events: [{ type: 'user.message', content: [{ type: 'text', text: designPrompt(intent) }] }],
  });

  const design = await waitForArtifact(session.id, 'design.json');
  await persistArtifact(runId, 'design', design); // -> Postgres: runs · jobs · artifacts
  return design;
}

Because each stage is its own durable step, the run survives a deploy, a cold start, or a closed laptop. The next stage reads the prior artifact from Postgres, so replaying a stage that already finished returns the stored result instead of paying for the agent twice.

Running a Managed Agent to True Completion

This is the part that cost me a day. Managed Agent sessions start idle. The naive check waits until the session is idle, then downloads the output. It fires on that initial idle state, before the agent has done any work, and downloads a file that does not exist.

The fix is to detect a true finish: the session reports idle after doing work (its stop reason is not requires_action), or it reports terminated. I poll newest-event-first and gate on both signals:

const POLL_INTERVAL_MS = 3000;
const MAX_POLLS_PER_STAGE = 200; // 3s × 200 ≈ 10 min ceiling per stage

async function waitForArtifact(sessionId: string, file: string) {
  for (let poll = 0; poll < MAX_POLLS_PER_STAGE; poll++) {
    const { data: events } = await client.beta.sessions.events.list(sessionId, { limit: 100 });
    const latest = events[0]; // newest first
    const done =
      latest?.type === 'session.status_terminated' ||
      (latest?.type === 'session.status_idle' && latest.stop_reason?.type !== 'requires_action');
    if (done) return downloadArtifact(sessionId, file);
    await sleep(POLL_INTERVAL_MS);
  }
  throw new Error(`Stage timed out after ${MAX_POLLS_PER_STAGE} polls`);
}

Downloading the artifact has its own trap. The Files API indexes a session's outputs one to three seconds after the session goes idle, so an immediate listing comes back empty. The download needs a short retry loop, and every Files call needs both beta headers or the listing fails intermittently:

const FILE_BETAS = ['managed-agents-2026-04-01', 'files-api-2025-04-14'];

async function downloadArtifact(sessionId: string, name: string) {
  for (let attempt = 0; attempt < 4; attempt++) {
    const files = await client.beta.files.list({ scope_id: sessionId, betas: FILE_BETAS });
    const match = files.data.find((f) => f.filename.endsWith(name));
    if (match) {
      const blob = await client.beta.files.download(match.id, { betas: FILE_BETAS });
      return JSON.parse(await blob.text());
    }
    await sleep(1000); // wait for indexing, then re-list
  }
  throw new Error(`Output ${name} never indexed`);
}

I isolated every line that touches the beta API behind one module. When the beta header or the completion-signal shape changes — and on a public beta, it will — there is exactly one file to re-verify.

The Model-Routing Decision I Reversed

My first design routed by model tier: Sonnet for the cheap stages, Opus for Optimize, the stage that does the hardest reasoning. It read well on paper. In practice, Optimize on Opus ran six to nine minutes per stage, with high variance. That was close enough to my per-stage timeout to be a production risk, and slow enough that a live run felt broken.

I moved all four agents to claude-sonnet-4-6. Optimize stayed strong and dropped to a predictable runtime. The lesson: model tier is a latency decision as much as a quality one, and a slower top-tier stage that risks a timeout is worse than a faster stage that ships.

Cost lands where caching puts it. Each agent's system prompt is frozen at creation and never overridden per session, so repeated runs read it from cache at a tenth of the input price. A full six-stage run costs roughly $0.50 to $1.50, dominated by tokens — Sonnet runs $3 per million input and $15 per million output. A small managed-compute charge applies only while a session is actively running.

The Safety Gate: Validate, Then Review

The output of this pipeline is an installable Claude Code plugin. Plugins carry hooks and MCP configuration — code that runs on other people's machines. So the pipeline never auto-ships. It ends at a validated bundle behind a human gate, and two stages enforce that.

Stage 4, Validate, runs inside the Scaffolder's own session container and asserts the bundle is structurally correct. The plugin manifest must parse, every skill needs valid frontmatter, names must be kebab-case, and nothing nests where it shouldn't. A failure sets the bundle status to failed, surfaces the reason, and the pipeline does not advance. Reusing the Scaffolder's session here matters — the validator checks the exact files the agent wrote, in the same container.

Stage 5, Review, is a fresh agent reading the finished tree with no stake in having built it. It returns a typed verdict:

type ReviewVerdict = 'ship' | 'ship-with-fixes' | 'do-not-ship';

interface Review {
  verdict: ReviewVerdict;
  findings: { area: string; severity: 'blocker' | 'major' | 'minor'; issue: string; fix: string }[];
  risk_flags: string[]; // e.g. "hook runs a shell command", "MCP reads credentials"
}

A deterministic security scan runs before the Reviewer and is independent of it — plain pattern matching for hardcoded secrets, hooks that shell out, and MCP servers touching credentials. The Reviewer must triage every flag the scan raises rather than silently dropping it. That keeps a security floor even if the model misses something, because regex does not get tired or talked out of a finding.

I deliberately cut the stage that would have opened a pull request automatically. Unreviewed agent-generated code that runs on other machines is exactly the thing a human should approve. The gate is the product, not an obstacle to it.

Tradeoffs and When Not To Do This

Durable-step orchestration is not free, and it is not always right.

The complexity tax is real. You take on a durable workflow runtime, a Postgres schema for runs, jobs, and artifacts, and a streaming layer to show progress. I also built a mock mode (MOCK_AGENTS=1) that returns fixture artifacts with realistic pacing, so I could test the agent orchestration end to end without spending tokens. That is another surface to maintain. A coordinator agent needs none of it — you configure agents and let one of them drive.

Use a coordinator agent instead when the routing needs judgment: dynamic branching, an unknown number of steps, or a next-step that depends on what the last agent found. My graph was fixed, so code won. A research agent that decides what to investigate next does not have that luxury.

Use a single Messages API call instead when the task is a one-shot transform or needs sub-second latency. My Intake stage proves the point inside the same system — not every box in the diagram deserves a session.

Account for beta fragility. Managed Agents and the Files API both ship behind beta headers, and behaviors shift between releases. The completion-signal shape, the indexing lag, and the header strings are all things I expect to re-verify. Containing them in one module is what makes that survivable rather than a rewrite.

Conclusion

The portable lesson is about where agent orchestration logic belongs. If your routing is fixed, keep it in durable steps you can read, test, and resume — and treat each Managed Agent as a stateless worker that takes input, writes a file, and stops. If your routing needs judgment, give a coordinator agent the wheel and pay for the flexibility. Most real systems, like this one, are a mix: a Messages call where text becomes JSON, durable steps for the assembly line, and a human at the gate where the output runs on someone else's machine.

Key Takeaways:

• Put fixed routing in durable workflow steps, not a coordinator agent — you get determinism, resumability, and orchestration you can unit-test
• Detect a Managed Agent's true completion (idle-after-work or terminated), because sessions start idle and a naive check downloads an empty artifact
• Reserve Managed Agents for stages that need a sandbox, tools, and file output; a structured-output Messages call is faster and cheaper for parsing
• Model tier is a latency decision too — I reversed an Opus stage to Sonnet after six-to-nine-minute runs threatened timeouts
• When the output runs on other machines, end the pipeline at a human-reviewed gate with an independent verdict and a deterministic security scan

This is the first of two posts. The next one goes a layer down — the Managed Agents fundamentals behind these stages and how the same building blocks power a deep-research command. If you want the architecture primer first, start with why Managed Agents ends DIY agent infrastructure, then the orchestration systems I built before this one.

I manage CMS implementations for enterprise clients across all three platforms. Here's the platform-specific checklist I'm running right now, and what every CMS team should prioritize before the 90-day public disclosure window opens in July 2026.

What Mythos Found and Why CMS Teams Should Care

Mythos is Anthropic's most capable AI model. It wasn't built for security — but its code reasoning capabilities made it extraordinarily effective at chaining exploitable vulnerabilities. The findings relevant to enterprise CMS stacks:

The 90x improvement in exploit success rate between Opus 4.6 and Mythos (2 successes vs. 181 on Firefox exploit development) signals that AI-assisted vulnerability discovery now outpaces manual security research. Enterprise CMS platforms carry large dependency trees and legacy code — exactly the type of surface area Mythos excels at analyzing.

Sitecore: What to Patch and Harden Now

Sitecore's attack surface depends heavily on which generation you're running.

Sitecore 9.x–10.x (.NET Framework 4.8 / IIS)

Telerik UI is your top priority. Sitecore historically bundled Telerik UI for ASP.NET AJAX, which has a well-documented deserialization RCE history (CVE-2017-9248, CVE-2019-18935). If your Telerik.Web.UI.DialogParametersEncryptionKey is weak or default, an attacker with the capabilities Mythos demonstrates could chain this with the newly-discovered IIS/HTTP.sys vulnerabilities for full server compromise.

<!-- web.config — verify Telerik keys are rotated and strong -->
<appSettings>
  <!-- ROTATE these keys. Default or weak values are exploitable -->
  <add key="Telerik.Web.UI.DialogParametersEncryptionKey" value="YOUR-STRONG-KEY-HERE" />
  <add key="Telerik.Upload.ConfigurationHashKey" value="YOUR-STRONG-KEY-HERE" />
</appSettings>

Additional hardening:

• Block public access to /sitecore/admin/ and /sitecore/login/ via IP allowlisting or VPN
• Audit Newtonsoft.Json usage — any TypeNameHandling setting other than None enables deserialization attacks
• Patch Windows Server and IIS immediately against the disclosed HTTP.sys vulnerabilities
• Review Sitecore.config for hardcoded HashAlgorithm keys and rotate them
• Restrict media library upload extensions — Sitecore's default allows types that can trigger server-side processing vulnerabilities

Sitecore XM Cloud

XM Cloud shifts the server-side risk to Sitecore's managed infrastructure, but your rendering host (Next.js on Vercel or self-hosted) still needs attention:

• Update your Next.js rendering host dependencies
• Audit any middleware that processes media from the Sitecore CDN
• Review Experience Edge API keys and scope permissions

Umbraco: Backoffice and Media Pipeline Risks

Umbraco 10-14 runs on .NET 6/7/8, which means Kestrel is the default web server — and OpenSSL TLS vulnerabilities apply directly when hosted on Linux.

Critical Items

ImageSharp is your FFmpeg equivalent. Umbraco uses ImageSharp for server-side image processing. Pre-3.x versions had memory exhaustion vulnerabilities (CVE-2022-24795) triggered by crafted image uploads. With Mythos demonstrating the ability to find similar media processing bugs at scale, update ImageSharp to the latest version and validate that your upload validation rejects malformed images before they hit the processing pipeline.

// Startup.cs — restrict upload file types and sizes
services.AddUmbraco(_env, _config)
    .AddBackOffice()
    .AddWebsite()
    .Build();

// In appsettings.json — tighten allowed upload extensions
// Remove any media types you don't need
{
  "Umbraco": {
    "CMS": {
      "Content": {
        "AllowedUploadedFileExtensions": ["jpg", "jpeg", "png", "gif", "webp", "svg", "pdf"]
      }
    }
  }
}

Backoffice hardening:

• Umbraco's backoffice at /umbraco/ has no built-in rate limiting by default — add brute-force protection via middleware or a WAF
• TinyMCE (the rich text editor) has had XSS vectors in older versions (CVE-2024-38356). Update to the version bundled with your Umbraco LTS release
• If running on Linux/Kestrel: patch the kernel against Mythos-discovered privilege escalation chains
• If running on Windows/IIS: patch HTTP.sys and the Windows kernel

Umbraco Cloud vs Self-Hosted

Umbraco Cloud (Azure-managed) handles OS patching and TLS termination. Self-hosted instances inherit every OS and runtime vulnerability. If you're self-hosted, the Mythos findings add urgency to evaluating managed hosting — or at minimum, automating your patch pipeline.

Optimizely: DXP Cloud vs Self-Hosted Exposure

The security gap between Optimizely's DXP Cloud and self-hosted CMS 11/12 has never been wider.

Self-Hosted CMS 11 (.NET Framework 4.8)

CMS 11 is the legacy surface. It runs on .NET Framework 4.8, typically IIS on Windows Server. Every Windows kernel and HTTP.sys vulnerability Mythos found applies here.

Priority actions:

• Patch Windows Server immediately — the privilege escalation chains Mythos discovered grant kernel-level access
• Audit Newtonsoft.Json with TypeNameHandling — same deserialization risk as Sitecore
• Review /episerver/ admin UI exposure. Block public access via network rules
• Audit scheduled jobs endpoints — these accept remote execution triggers if misconfigured
• Check Microsoft.Data.SqlClient version (pre-5.1.4 has known vulnerabilities)

Self-Hosted CMS 12 (.NET 6+)

CMS 12 on .NET 6+ is more modern but still self-managed:

// Program.cs — add security headers middleware
app.Use(async (context, next) =>
{
    context.Response.Headers.Append("X-Content-Type-Options", "nosniff");
    context.Response.Headers.Append("X-Frame-Options", "DENY");
    context.Response.Headers.Append("Referrer-Policy", "strict-origin-when-cross-origin");
    context.Response.Headers.Append("Permissions-Policy", "camera=(), microphone=(), geolocation=()");
    context.Response.Headers.Append(
        "Content-Security-Policy",
        "default-src 'self'; script-src 'self'; frame-ancestors 'none'");
    await next();
});

• Audit the Optimizely add-on marketplace packages you've installed — these are community-contributed and not security-audited by Optimizely
• Review Content Delivery API authorization scopes. The default configuration is often more permissive than needed
• Check visitor group criteria for injection vectors

DXP Cloud

DXP Cloud manages OS patching, TLS termination, and includes a WAF. The Mythos findings are largely handled by Optimizely's infrastructure team. Your responsibility: audit application-level code, add-on packages, and Content Delivery API configurations.

Cross-Platform: The Shared .NET Attack Surface

Regardless of which CMS you run, these .NET-specific concerns apply to all three:

NuGet Packages to Audit Now

Automate Vulnerability Scanning

Running dotnet list package --vulnerable across 15 client solutions manually won't scale. Automate it.

# Audit all .NET projects in a client directory
for sln in ~/clients/*/*.sln; do
  echo "=== $(basename "$(dirname "$sln")") ==="
  dotnet list "$sln" package --vulnerable --include-transitive 2>/dev/null | grep -E "(Critical|High)"
done

Tooling for .NET CMS stacks:

• GitHub Dependabot — Enable NuGet source scanning on all repos
• Snyk — Supports .NET and NuGet with transitive dependency analysis
• dotnet-outdated — CLI tool for checking outdated NuGet packages across solutions
• OWASP Dependency-Check — Integrates with Azure DevOps and GitHub Actions

How to Prioritize: A Risk-Based Decision Matrix

Not every CMS instance carries the same risk. Use this matrix to triage which systems to patch first.

Patch Order

Tier 1 — Patch this week: Self-hosted .NET Framework 4.8 instances with publicly exposed admin panels. These combine the oldest runtime, the widest OS attack surface, and the most exploitable entry points (Telerik deserialization, HTTP.sys). Sitecore 9.x and Optimizely CMS 11 fall here.

Tier 2 — Patch within two weeks: Self-hosted .NET 6+ instances on Linux/Kestrel. The runtime is modern, but the Mythos kernel privilege escalation chains and OpenSSL TLS flaws apply directly. Umbraco 10-14 on Linux and Optimizely CMS 12 on Kestrel fall here.

Tier 3 — Patch within 30 days: Self-hosted .NET 6+ on Windows/IIS with admin panels behind VPN. The attack surface is smaller — Windows SChannel handles TLS (not OpenSSL), and the admin panel isn't publicly reachable. Still patch Windows Server and audit NuGet dependencies.

Tier 4 — Audit application code only: Cloud-managed platforms (XM Cloud, Umbraco Cloud, DXP Cloud). The provider handles OS, TLS, and infrastructure patching. Your responsibility is application-level: third-party packages, API authorization scopes, and upload validation.

When This Doesn't Apply

Managed cloud platforms absorb most of the risk. If you're on Sitecore XM Cloud, Umbraco Cloud, or Optimizely DXP Cloud, the OS-level and TLS-level vulnerabilities Mythos discovered are patched by the platform provider. Your responsibility narrows to application-level code, third-party packages, and API configurations.

Static/headless rendering hosts are lower risk. If your CMS uses a headless architecture with a static frontend (Next.js on Vercel, for example), the server-side CMS attack surface is isolated from the public-facing site. The CMS backoffice still needs hardening, but the blast radius of a compromise is contained.

This applies to everyone else. Self-hosted CMS instances on unpatched Windows Server or Linux, legacy .NET Framework 4.8 applications with known vulnerable dependencies, exposed admin panels without IP restrictions — the Mythos findings make this posture untenable. The window between disclosure and exploitation is shrinking from months to days.

Conclusion

Mythos demonstrated that AI can find and chain exploits across operating systems, browsers, TLS libraries, and server software at a rate 90x faster than the previous generation. For enterprise CMS teams running Sitecore, Umbraco, or Optimizely, the attack surface is broad: admin panels, media processing pipelines, deserialization endpoints, and the OS underneath it all.

Key Takeaways:

• Sitecore teams: Rotate Telerik encryption keys, block /sitecore/admin/ publicly, audit Newtonsoft.Json TypeNameHandling, and patch Windows Server
• Umbraco teams: Update ImageSharp, add backoffice brute-force protection, patch TinyMCE, and address Linux kernel vulnerabilities if on Kestrel
• Optimizely teams: Audit add-on packages, restrict Content Delivery API scopes, and patch self-hosted Windows/IIS instances immediately
• All .NET CMS teams: Run dotnet list package --vulnerable --include-transitive across every solution. Automate it with Dependabot or Snyk. Set a hard patch deadline of June 30, 2026 — before the 90-day Glasswing disclosures go public
• Evaluate managed hosting: The security gap between self-hosted and cloud-managed CMS has never been wider. If you're still self-hosting, the operational cost of staying patched post-Mythos may exceed the cost of migration

The Glasswing partner list — AWS, Apple, Google, Microsoft, CrowdStrike — tells you how seriously the industry is taking this. Match that energy across your CMS portfolio.

If you're exploring how AI capabilities are reshaping development workflows beyond security, check out how Claude Managed Agents replaces DIY agent infrastructure and multi-agent pipeline architectures. The same AI capability curve driving Mythos is transforming how we build software — understanding both sides matters.

I've built four generations of agent orchestration systems, each one teaching me something about coordination, drift, and crash recovery. Managed Agents solves many of the infrastructure problems I solved by hand in STUDIO — and introduces tradeoffs I didn't have to make. This post walks through both sides using a concrete example: a three-agent pipeline that takes a GitHub issue and produces a reviewed pull request.

Claude Managed Agents as an Operating System

Operating systems virtualize hardware so applications don't manage memory, disk I/O, or CPU scheduling directly. Managed Agents virtualizes agent infrastructure so developers don't manage execution loops, state persistence, or sandbox lifecycle directly.

The mapping is specific:

When I built STUDIO, I implemented my own versions of all five. The Planner-Builder-ContentWriter pipeline needed a custom event loop, crash recovery logic, and a preference persistence system. STUDIO's supervision model — confidence scoring, mandatory questioning, validation commands per step — was my "scheduler." The codebase itself was my "filesystem."

Claude Managed Agents standardizes these primitives. The question is whether the standard abstractions fit your workload.

Building the Pipeline: Three Agents, Three Roles

Here's the auto-PR pipeline: a Planner agent that breaks down a GitHub issue into implementation steps, a Coder agent that writes the code, and a Reviewer agent that validates the output before opening a PR. This maps to STUDIO's Planner-Builder pattern, but with Anthropic managing the orchestration.

Defining the Agents

Each agent gets its own model, system prompt, and tool configuration:

const planner = await client.beta.agents.create({
  name: "PR Planner",
  model: "claude-sonnet-4-6",
  system: `You are an implementation planner. Given a GitHub issue:
    1. Analyze the requirements
    2. Identify affected files
    3. Break the work into ordered implementation steps
    4. Specify a validation command for each step
    Output a structured JSON plan.`,
  tools: [
    {
      type: "agent_toolset_20260401",
      configs: [
        { name: "bash", enabled: true },
        { name: "read", enabled: true },
        { name: "glob", enabled: true },
        { name: "grep", enabled: true },
      ],
      default_config: { enabled: false },
    },
  ],
});

const coder = await client.beta.agents.create({
  name: "PR Coder",
  model: "claude-sonnet-4-6",
  system: `You are an implementation agent. Given a plan with ordered steps:
    1. Execute each step in order
    2. Run the validation command after each step
    3. If validation fails, fix and retry (max 3 attempts)
    4. Stop and report if a step cannot pass validation`,
  tools: [{ type: "agent_toolset_20260401" }],
});

const reviewer = await client.beta.agents.create({
  name: "PR Reviewer",
  model: "claude-sonnet-4-6",
  system: `You are a code reviewer. Review the implementation against the plan:
    1. Check that all plan steps were completed
    2. Run the full test suite
    3. Review code quality, patterns, and potential issues
    4. Either APPROVE with a summary or REJECT with specific fixes needed`,
  tools: [
    {
      type: "agent_toolset_20260401",
      configs: [
        { name: "write", enabled: false },
        { name: "edit", enabled: false },
      ],
    },
  ],
});

Notice the tool scoping. The Planner gets read-only access — it plans but doesn't modify. The Reviewer can read and run commands but can't write files. This is the "principle of least privilege" applied to agents. In STUDIO, I enforced this through agent prompt instructions. Managed Agents enforces it at the infrastructure level, which is more reliable.

Wiring the Handoffs

The coordinator agent declares which agents it can call via callable_agents:

const coordinator = await client.beta.agents.create({
  name: "PR Coordinator",
  model: "claude-sonnet-4-6",
  system: `You coordinate the auto-PR pipeline:
    1. Send the issue to the Planner for analysis
    2. Send the plan to the Coder for implementation
    3. Send the result to the Reviewer for validation
    4. If rejected, send fixes back to the Coder
    5. On approval, create the PR via bash`,
  tools: [{ type: "agent_toolset_20260401" }],
  callable_agents: [
    { type: "agent", id: planner.id, version: planner.version },
    { type: "agent", id: coder.id, version: coder.version },
    { type: "agent", id: reviewer.id, version: reviewer.version },
  ],
});

Each agent runs in its own thread — an isolated context with its own conversation history. The coordinator sees condensed summaries of thread activity on the primary session stream. To inspect what the Coder is doing in detail, you stream the thread directly:

// Stream the coordinator's primary session
const stream = await client.beta.sessions.events.stream(session.id);

// Drill into a specific thread for full traces
for await (const thread of client.beta.sessions.threads.list(session.id)) {
  if (thread.agent_name === "PR Coder") {
    const threadStream = await client.beta.sessions.threads.stream(
      thread.id, { session_id: session.id }
    );
  }
}

This is the "multiple brains" model from the Managed Agents architecture. Each brain has its own context, its own tools, and its own thread — but they share a filesystem inside the same container.

Session Durability and Crash Recovery

The most underappreciated feature of this architecture: sessions survive infrastructure failures.

In STUDIO, if the Builder crashed mid-execution, I had to implement recovery myself. The supervision system tracked which steps had completed, and the retry logic knew how to resume from the last successful validation. That recovery code accounted for roughly 20% of STUDIO's complexity.

Managed Agents handles this through the append-only session log. Because sessions live outside the harness, a crashed harness doesn't lose history:

// After a harness crash, recovery is three calls:
const session = await getSession(sessionId);     // Full history intact
const harness = await wake(sessionId);           // New harness instance
await emitEvent(sessionId, resumeEvent);         // Resume from last event

The Coder agent's thread retains its full conversation — every file it read, every command it ran, every validation result. A new harness picks up exactly where the old one stopped. No checkpoint files, no recovery protocols, no state reconciliation.

This matters for the auto-PR pipeline because implementation sessions can run for 30+ minutes with dozens of tool calls. A single infrastructure hiccup shouldn't invalidate all that work.

The Scaling Model: Multiple Brains, Multiple Hands

The pipeline described above uses one brain (harness) per agent. But the architecture supports scaling both axes independently.

Horizontal harness scaling: Because harnesses are stateless, you can run multiple coordinator sessions in parallel — each processing a different GitHub issue. No shared state means no coordination overhead between sessions.

Multiple sandboxes per session: A single harness can route tool calls to different execution environments. The Coder agent could theoretically fan out to parallel sandboxes — one for frontend changes, one for backend, one for tests — and merge results.

This is where the multi-agent research preview becomes interesting. The callable_agents API already supports one level of delegation (coordinator → specialists). The Coder and Reviewer can run in parallel on independent parts of the codebase. The event types tell the story:

The coordinator receives these events and decides when to proceed. If the Reviewer rejects, the coordinator routes the rejection reasons back to the Coder's thread — and that thread retains its full history from the first attempt.

Tradeoffs: Managed vs. Self-Built

I've run STUDIO for three months in production. Here's an honest comparison:

STUDIO wins when you need custom supervision logic. Confidence scoring, preference learning, mandatory questioning before execution — these require control over the agent loop that Managed Agents doesn't expose. If your agent's value comes from how it orchestrates rather than what it executes, self-built gives you the knobs.

Managed Agents wins when the orchestration is standard but the infrastructure is complex. Sandboxing, credential isolation, crash recovery, horizontal scaling — these are solved problems that shouldn't be solved again per-project. The auto-PR pipeline above would take weeks to build with proper infrastructure. With Managed Agents, the infrastructure is configuration.

When NOT to use either for this pattern:

• Single-turn interactions where a PR can be generated in one Messages API call
• Codebases requiring custom security scanning that can't run inside a managed container
• Environments where agent-generated code must be reviewed by humans before any file writes (Managed Agents writes files inside the sandbox — you review the output, not individual writes)

Conclusion

The OS metaphor holds because it predicts behavior. Sessions persist like processes. Harnesses restart like schedulers. Sandboxes swap like device drivers. When you understand the abstraction, you can predict what the platform handles and what you need to build yourself.

Key Takeaways:

• The OS mapping (session=process, harness=scheduler, sandbox=device) is structural, not cosmetic — it predicts crash recovery, scaling, and isolation behaviors
• Multi-agent pipelines use callable_agents and threads to isolate context while sharing a filesystem — each agent sees only its own conversation history
• Session durability eliminates custom crash recovery code — the append-only event log survives harness failures without checkpointing
• Self-built systems like STUDIO retain advantages in custom orchestration logic (confidence scoring, preference learning, supervision rules)
• The one-level delegation limit means complex agent hierarchies still need custom coordination — Managed Agents handles the leaf nodes, not the full tree

The direction is clear: Claude Managed Agents signals that agent infrastructure is becoming a platform concern, not an application concern. The teams that benefit most are the ones spending more time on plumbing than on the agent behavior they shipped the plumbing to enable.

If you've spent weeks building agent infrastructure — wiring up container orchestration, implementing retry logic, managing session state — this is the platform that makes most of that code unnecessary.

Here's what the architecture looks like, when it makes sense to adopt, and where the boundaries are.

How Claude Managed Agents Decouples Session, Harness, and Sandbox

The core design decision behind Managed Agents is a three-way separation of concerns that treats each component as independently swappable:

This decoupling exists because Anthropic's earlier architecture coupled the harness directly inside containers. When containers failed, entire sessions were lost. The new design treats the harness as stateless. It calls sandboxes via a standard execute(name, input) → string interface. If a container dies, a new one initializes via provision({resources}) without losing session history.

The performance gains are significant. By decoupling containers from harnesses, sessions no longer wait for container provisioning before inference begins. The p95 time-to-first-token dropped by more than 90%.

Session Durability in Practice

Because session logs live outside the harness, crash recovery becomes straightforward:

// Harness recovery after failure
const session = await getSession(sessionId);  // Retrieve full history
const harness = await wake(sessionId);        // Reboot harness
await emitEvent(sessionId, resumeEvent);      // Resume from last event

No complex recovery protocols. No lost context. The session is the source of truth, and harnesses are disposable workers that read from it.

Security Boundaries

Credentials never exist inside sandboxes where untrusted code executes. Managed Agents enforces this through two authentication patterns:

• Resource-bundled auth: Git tokens initialize repos during provisioning, then wire into local remotes — the token never appears in the execution environment
• Vault-stored credentials: OAuth tokens stored externally; a proxy fetches them for outbound service calls

This matters because agent sandboxes run arbitrary code. Any credential placed inside a sandbox is a credential that user-generated code can exfiltrate.

What You Get Out of the Box

Managed Agents provides a complete agent runtime with built-in tools:

• Bash: Run shell commands in the container
• File operations: Read, write, edit, glob, and grep files
• Web search and fetch: Search the web and retrieve URL content
• MCP servers: Connect to external tool providers
• Prompt caching and compaction: Built-in context management optimizations

The API surface centers on four concepts — Agent (model + system prompt + tools), Environment (container template with packages and network rules), Session (a running agent instance), and Events (messages exchanged via server-sent events).

Here's the minimal flow to get a session running:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 1. Create an agent
const agent = await client.beta.agents.create({
  model: "claude-sonnet-4-6-20260414",
  system: "You are a code review assistant.",
  tools: [{ type: "bash" }, { type: "file_editor" }],
});

// 2. Create an environment
const env = await client.beta.environments.create({
  packages: ["python3", "nodejs"],
  network_access: { allowed_domains: ["github.com"] },
});

// 3. Start a session and stream events
const session = await client.beta.sessions.create({
  agent_id: agent.id,
  environment_id: env.id,
});

await client.beta.sessions.events.create(session.id, {
  type: "user",
  content: "Review the PR at github.com/org/repo/pull/42",
});

The SDK sets the required managed-agents-2026-04-01 beta header automatically. Rate limits apply: 60 create requests/minute and 600 read requests/minute per organization.

Messages API vs. Managed Agents: When to Use Which

This isn't a replacement for the Messages API. It's a higher-level abstraction for a specific class of workloads.

Use Messages API when:

• You need sub-second response times for synchronous interactions
• Your agent loop has custom logic that doesn't fit the managed model
• You need fine-grained control over every tool call and retry

Use Managed Agents when:

• Tasks run for minutes or hours with dozens of tool calls
• You need secure code execution without building your own sandbox
• You want session persistence across disconnections
• You'd rather configure than build infrastructure

Who's Building With It

Several companies are already in production or late-stage integration:

• Notion: Agents handle parallel tasks — coding, content creation — with team collaboration features layered on top
• Rakuten: Enterprise agents deployed across product, sales, marketing, and finance departments, integrated with Slack and Teams for task delegation
• Asana: "AI Teammates" work alongside humans, picking up tasks and drafting deliverables within existing project workflows
• Sentry: A debugging agent pairs with a patch-writing agent, automating the bug-report-to-pull-request pipeline
• Vibecode: Uses managed sessions for rapid app deployment, reporting 10x faster infrastructure spin-up

The pattern across these deployments: teams that were spending months building agent infrastructure — sandboxing, credential management, crash recovery — redirected that effort to product features. If you've followed my work building autonomous coding agents with STUDIO, the appeal is obvious: Claude Managed Agents provides the infrastructure layer that every agent builder ends up reinventing.

The Multi-Brain, Multi-Hands Model

The decoupled architecture enables a scaling model worth understanding. Because harnesses are stateless and sandboxes are interchangeable, you can scale both axes independently:

Multiple brains: Spin up stateless harnesses horizontally. Each connects to sandboxes only when needed, then releases them.

Multiple hands: Each sandbox becomes an interchangeable tool. A single harness can reason about multiple execution environments and route work accordingly — containers, custom tools, MCP servers, or any system behind the execute() interface.

Multi-agent coordination (multiple harnesses collaborating on a task) is available as a research preview. So is persistent memory across sessions and outcome-based evaluation. These features require a separate access request.

Tradeoffs and Limitations

Managed Agents trades flexibility for operational convenience. Here's what you give up:

Less control over the agent loop. You can steer mid-execution and interrupt, but you can't customize the core orchestration logic. If your agent needs non-standard retry strategies, custom tool routing, or model-switching mid-conversation, the Messages API gives you that control.

Beta stability risks. The managed-agents-2026-04-01 beta header signals that APIs and behaviors may change between releases. Production workloads need to account for breaking changes.

Container startup overhead. While the decoupled architecture eliminated most provisioning delays (the 60% p50 improvement), the first interaction in a session still involves container initialization. For latency-sensitive, single-turn interactions, the Messages API is faster.

Vendor lock-in. Your agent logic lives inside Anthropic's infrastructure. Migrating to self-hosted or another provider means rebuilding the harness, sandbox management, and session persistence you didn't have to build initially.

Research preview features are gated. Multi-agent coordination, memory, and outcomes — three of the most compelling capabilities — require separate access approval and carry additional stability caveats.

When NOT to use Managed Agents:

• Single-turn Q&A or chatbot interfaces (overkill for the use case)
• Latency-critical applications under 500ms response time requirements
• Workloads requiring custom model routing or non-Claude models
• Environments where data residency prevents cloud-hosted execution

Conclusion

Claude Managed Agents represents a clear shift: Anthropic is moving up the stack from model provider to agent platform. The decoupled session-harness-sandbox architecture solves real infrastructure problems that every team building agents has encountered.

Key Takeaways:

• The three-way decoupling (session, harness, sandbox) is the key architectural insight — it enables crash recovery, horizontal scaling, and secure credential isolation in a single design
• Performance gains are concrete: 60% p50 and 90%+ p95 time-to-first-token reductions from eliminating container-inference coupling
• The Messages API remains the right choice for low-latency, high-control use cases — Managed Agents targets long-running, infrastructure-heavy workloads
• Multi-agent coordination, memory, and outcomes are in research preview — compelling features that aren't production-ready yet
• Five major companies (Notion, Rakuten, Asana, Sentry, Vibecode) are already building on the platform, validating the "managed over DIY" approach

The decision framework is straightforward: if you're spending more engineering time on agent infrastructure than on agent behavior, Managed Agents eliminates that overhead. If you need full control over every inference call, stick with the Messages API and build the infrastructure yourself.

This matters because AI agents are already the majority of web traffic. Bots account for 51% of all web requests, and most interact with sites through pixel analysis and HTML parsing — approaches that break whenever a CSS class changes or a button moves. WebMCP proposes a structured alternative.

This post covers how WebMCP works, its two API approaches, where it fits within the 17,000+ server MCP ecosystem, and the significant gaps you need to understand before building on it.

The Problem: Agents Are Scraping Like It's 2005

Current AI agents interact with websites the same way early screen readers did — by parsing visual layouts. Tools like Playwright MCP take screenshots, analyze DOM trees, and simulate clicks. This works, but it's fragile.

A website redesign breaks every agent that depends on specific HTML structure. A CSS change makes a button invisible to screenshot analysis. Processing entire DOM trees or full-page screenshots wastes tokens and adds latency to every agent action.

WebMCP addresses this by giving developers a way to declare what their site can do. Instead of agents guessing from visual cues, sites expose named tools with typed parameters and structured responses.

How WebMCP Works: Two API Approaches

WebMCP provides two ways to expose tools: a declarative HTML approach for forms, and an imperative JavaScript API for complex interactions. Both register tools through the same underlying navigator.modelContext interface.

Declarative API: HTML Forms as Tools

The declarative approach requires zero JavaScript. Standard HTML forms gain three new attributes that make them visible to AI agents:

<form toolname="book_table"
      tooldescription="Creates a dining reservation at the restaurant">
  <input name="email"
         toolparamdescription="Customer email for confirmation" />
  <input name="date" type="date"
         toolparamdescription="Reservation date in YYYY-MM-DD format" />
  <input name="party_size" type="number"
         toolparamdescription="Number of guests, 1-12" />
  <button type="submit">Reserve</button>
</form>

The toolname attribute declares the tool identifier. The tooldescription gives agents natural language context. And toolparamdescription on each input documents the expected parameter. An agent encountering this form knows it can call book_table with typed parameters — no screenshot parsing required.

Imperative API: JavaScript Tool Registration

For single-page applications and dynamic interactions, the imperative API provides programmatic tool registration:

navigator.modelContext.registerTool({
  name: "search_flights",
  description: "Search available flights between two airports",
  inputSchema: {
    type: "object",
    properties: {
      origin: { type: "string", description: "IATA airport code" },
      destination: { type: "string", description: "IATA airport code" },
      departure_date: { type: "string", format: "date" },
      passengers: { type: "integer", minimum: 1, maximum: 9 }
    },
    required: ["origin", "destination", "departure_date"]
  },
  outputSchema: {
    type: "string",
    description: "JSON array of matching flights with prices"
  },
  execute: async (params) => {
    const results = await flightAPI.search(params);
    return JSON.stringify(results);
  }
});

This gives developers full control over schemas, validation, and execution logic. Tools registered this way should follow component lifecycle patterns — register on mount, unregister on cleanup:

useEffect(() => {
  navigator.modelContext.registerTool(flightSearchTool);
  return () => navigator.modelContext.unregisterTool("search_flights");
}, []);

Which API to Use

The declarative API covers the 80% case — most web interactions are form submissions. The imperative API handles the remaining 20% where JavaScript execution is unavoidable.

Where WebMCP Fits Today

WebMCP targets three use cases in its early preview:

E-commerce. Agents call search_products, add_to_cart, and checkout with structured parameters instead of navigating product pages visually. This eliminates the brittle dependency on specific button placements and page layouts.

Travel booking. An agent parsing "round-trip flight for two from London to NYC, March 15-22" calls search_flights() with typed parameters. No form filling, no calendar widget navigation, no screenshot interpretation.

Customer support. Support agents auto-fill technical details into structured tools rather than copying text between windows and parsing unstructured responses.

If you've worked with MCP (Model Context Protocol) in desktop AI tools, the mental model translates directly. WebMCP brings the same tool-registration pattern to browser-based agents — websites become MCP servers, and in-browser AI becomes the client.

The MCP Ecosystem WebMCP Is Entering

WebMCP doesn't exist in a vacuum. It lands in an MCP ecosystem that exploded from roughly 100 servers at Anthropic's November 2024 launch to over 17,000 across all directories by January 2026 — a 16,000% increase. Monthly SDK downloads crossed 97 million. Every major AI company now backs the protocol.

In December 2025, Anthropic donated MCP to the Linux Foundation's newly formed Agentic AI Foundation, co-founded by Anthropic, Block, and OpenAI. Platinum members include AWS, Cloudflare, Google, and Microsoft. MCP is no longer one company's project — it's an industry standard with formal governance.

That context matters for WebMCP because the browser is the last major surface area without native MCP support. Desktop IDEs, CLI tools, and cloud platforms all have it. The web doesn't — yet.

First-Party MCPs That Define the Ecosystem

The shift from community-built servers to official, company-hosted integrations marks 2025-2026 as MCP's enterprise inflection point. These are the servers shaping how developers interact with MCP daily.

Figma MCP is the one developers talk about most. Figma's official MCP server — launched in beta June 2025 and generally available by October — lets AI coding agents pull design context directly from Figma into development workflows. Select a frame, and your AI agent generates React/Tailwind code with real design tokens, layout constraints, and component metadata. It works with Cursor, VS Code Copilot, Claude Code, and Windsurf. In February 2026, Figma expanded further with custom MCP connectors for Figma Make, plus certified integrations with Amplitude, Dovetail, and four other services.

Stripe MCP exposes full payment operations — manage customers, products, pricing, invoices, refunds, and subscriptions through AI agents. The remote server at mcp.stripe.com uses OAuth authentication with parallel tool execution for batch operations. The practical impact: developers query billing data, create test subscriptions, and debug payment flows without leaving their AI coding environment.

Notion MCP provides full CRUD on pages, databases, blocks, and comments. Enterprise features include MCP activity tracking in audit logs and multi-database queries. In February 2026, Notion launched Custom Agents — autonomous AI that works across Notion, Slack, Figma, Linear, and custom MCP servers.

GitHub MCP goes beyond basic repo access. It covers issue management, PR workflows, Actions monitoring, security findings, and code search — with content sanitization enabled by default for prompt injection protection. GitHub's December 2025 update added tool-specific configuration and lockdown mode.

Cloudflare plays a dual role: infrastructure provider for hosting remote MCP servers (used by Atlassian, Stripe, Linear, PayPal, Sentry, and others) and publisher of 13+ first-party servers for Workers, R2, KV, and D1. Their MCP Demo Day showcased 10 companies building production MCP servers on Cloudflare's edge network.

Other official servers worth tracking: Linear for issue tracking with OAuth 2.1, Supabase with 20+ tools for database management and migrations, Slack for channel search and messaging, Vercel for deployment management, Atlassian for Jira and Confluence, and Google Cloud for Maps, BigQuery, and Kubernetes Engine.

Where WebMCP Fills the Gap

Every server listed above operates outside the browser. They connect through local stdio processes, remote HTTP endpoints, or IDE extensions. When an AI agent needs to interact with a website — not an API, but an actual web interface — it falls back to Playwright screenshots and DOM scraping.

WebMCP closes this gap. A website that implements navigator.modelContext.registerTool() becomes a first-class MCP server, discoverable by in-browser AI the same way Stripe's MCP server is discoverable by Claude Code. The protocol difference: these servers live inside the page itself, exposing tools that reflect the site's actual capabilities rather than an external API's interpretation of them.

The 17,000+ existing MCP servers handle the API layer. WebMCP handles the presentation layer. Together, they cover the full stack of agent-to-service communication.

Tradeoffs and Limitations

WebMCP is an early preview with significant gaps. Understanding them before building on this protocol is essential.

No security model. The specification defines no authentication, permission, or sandboxing mechanisms. Malicious websites can create "poisoned" tools with misleading descriptions — a tool named confirm_order could execute a different action entirely. No CORS-like policies exist for tool access. Until the security model matures, treat every WebMCP tool as untrusted input.

No headless mode. WebMCP requires a visible browser window with UI synchronization. This blocks server-side agent architectures and automated testing pipelines that run headless Chrome. If your agents operate without a display, WebMCP doesn't work.

Tool discoverability is unsolved. There's no standard for agents to discover which tools a site exposes before loading the page. No registry, no manifest file, no robots.txt equivalent for tool declarations. Agents must visit each page to learn what's available.

No error handling standards. The protocol doesn't define how tools should report failures, validation errors, or rate limits. Each implementation invents its own error format, which defeats the standardization goal.

Early preview access only. Chrome 145+ with feature flags enabled, or Canary 146+. Chrome's early preview program signup is required for documentation access. Production deployment is not viable yet.

When NOT to Use WebMCP

• Production applications. The API surface is unstable and the security model is undefined. Building production features on this protocol is premature.
• Sites without agent use cases. A personal blog or portfolio has no meaningful tools to expose. WebMCP adds complexity without benefit for read-only content.
• Security-sensitive workflows. Payment processing, authentication flows, and data access should wait for sandboxing and permission models.
• Server-side agents. The headless mode limitation eliminates backend agent architectures entirely.

What This Means for Developers

WebMCP signals a directional shift in how the web handles AI agent traffic. Google and Microsoft back the proposal, which moves it beyond research experiment territory.

The practical impact depends on your timeline:

Right now: Experiment with the declarative API on non-critical forms. Adding toolname and tooldescription attributes to existing HTML is low-risk and reversible. It builds familiarity with the mental model before the protocol stabilizes.

Next 6 months: Watch the security model development. The permission and sandboxing specifications will determine whether WebMCP is viable for anything beyond demos.

Next 12 months: If the security model materializes, the imperative API becomes the primary integration point for SPAs and complex web applications. Start identifying which user flows would benefit from structured agent access. Companies like Figma, Stripe, and Notion already committed to MCP for their APIs — expect them to adopt WebMCP for their web interfaces once the protocol stabilizes.

Conclusion

WebMCP turns websites from opaque visual interfaces into structured tool providers for AI agents. Chrome 145's early preview delivers two APIs — declarative HTML attributes for forms and an imperative JavaScript interface for complex interactions — and it arrives at the right time: the MCP ecosystem has 17,000+ servers, 97 million monthly SDK downloads, and backing from every major AI company through the Linux Foundation's Agentic AI Foundation.

Key Takeaways:

• WebMCP replaces brittle DOM scraping with typed, schema-validated tool interfaces that AI agents call directly
• The declarative API (toolname, tooldescription attributes) requires zero JavaScript and works on any HTML form
• The imperative API (navigator.modelContext.registerTool()) handles stateful interactions with full JSON Schema validation
• The MCP ecosystem exploded to 17,000+ servers — Figma, Stripe, Notion, GitHub, and Cloudflare all ship official first-party integrations
• WebMCP fills the browser gap: existing MCPs handle APIs, WebMCP handles web interfaces
• The security model is undefined — no authentication, sandboxing, or permission mechanisms exist yet
• This is an early preview in Chrome 145+, not production-ready — experiment on non-critical surfaces only

The protocol addresses a real problem: 51% of web traffic comes from bots, and most interact through brittle scraping. The ecosystem infrastructure is already in place — first-party MCPs from Figma, Stripe, and GitHub prove that companies will invest in structured agent access. Whether WebMCP becomes the browser-native standard depends on how fast the security and discoverability gaps close. For now, understand the API surface, track the specification, and keep your forms ready.

Plugin Architect guides you through designing and building Claude Code plugins from scratch, covering all 6 extension points: Skills, MCP Servers, Hooks, Agents, LSP Servers, and Plugins. It follows a structured workflow — Discover, Classify, Design, Confirm, Build, Register — and writes complete, production-ready code. No TODOs. No placeholders.

This post covers why I pivoted from a code-heavy approach to pure prompt engineering, how the architecture works, and what the tradeoffs are.

Project Overview

The Challenge

Claude Code's plugin system supports 6 extension points, each with different file structures, configuration patterns, and use cases. A developer wanting to build a plugin faces scattered documentation, unclear component selection, and no scaffolding tools.

The questions stack up fast: Should this be a Skill or an MCP Server? Do I need Hooks? What goes in plugin.json vs .mcp.json? Where do agents live? The cognitive overhead of these decisions delays the actual building.

The Solution

Plugin Architect encodes all of that knowledge into a single skill. When you run /plugin-architect, Claude receives a comprehensive instruction set — a component selection matrix, complete file structure templates, 5 worked examples, and 8 integration patterns — then walks you through the design and build process step by step.

# Install and use
/plugin install plugin-architect@twofoldtech-dakota-plugin-architect

# Design and build a plugin
/plugin-architect Build a plugin that enforces code style rules

Tech Stack

Architecture

The architecture is intentionally minimal. Three Markdown files carry the entire product:

plugin-architect/                     (~35KB total)
├── .claude-plugin/
│   ├── plugin.json                   # Plugin manifest
│   └── marketplace.json              # Distribution config
├── skills/
│   └── plugin-architect/
│       ├── SKILL.md                  # Core instruction set (13KB)
│       ├── examples.md               # 5 complete plugin examples (11KB)
│       └── integrations.md           # 8 integration patterns (6KB)
└── README.md                         # User documentation

SKILL.md is the engine. At 13KB (~380 lines), it stays under the recommended 500-line limit for Claude Code skills while encoding decision logic, component templates, and workflow instructions. The two supporting files — examples.md and integrations.md — provide reference material that Claude pulls from when building specific plugin types.

The Component Selection Matrix

The core design decision is a classification system. Instead of asking developers to read docs for all 6 extension points, SKILL.md contains a mapping from intent to component:

"I want Claude to know about X"          → Skill
"I want a /command that does X"           → Skill (user-invocable)
"I want Claude to call X API"            → MCP Server
"I want to enforce X on every edit"      → Hook (PreToolUse)
"I want to auto-run tests after changes" → Hook (PostToolUse)
"I want to bundle all of this for team"  → Plugin

This matrix eliminates the most common point of confusion. Users describe what they want in natural language, and the skill maps it to the correct extension point with the right file structure.

The Confirm-Before-Build Gate

The 6-step workflow includes an explicit confirmation gate at step 4. After Discover, Classify, and Design, the skill presents the proposed architecture to the user and waits for approval before generating any files. This prevents unwanted code generation — a real risk when a skill has broad tool access.

Key Features

Complete Template Coverage

Every extension point has a production-ready template. MCP Servers get a full TypeScript setup with the @modelcontextprotocol/sdk, Zod validation, and stdio transport:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "server-name",
  version: "1.0.0",
  capabilities: { tools: { listChanged: true } },
});

server.registerTool("tool-name", {
  description: "What it does, what it returns, when to use it",
  inputSchema: {
    param: z.string().describe("What this param means"),
  },
}, async ({ param }) => {
  return { content: [{ type: "text", text: "result" }] };
});

const transport = new StdioServerTransport();
await server.connect(transport);

Hook configurations include complete bash scripts for common patterns like secret detection:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "./hooks/scripts/check-secrets.sh",
        "timeout": 10
      }]
    }]
  }
}

Context Injection at Load Time

Skills can execute shell commands dynamically when loaded. Plugin Architect uses this pattern in its examples to show how skills inject runtime context into their prompts:

Current branch: !`git branch --show-current`
Recent commits: !`git log --oneline -5`

This turns static Markdown into dynamic, context-aware instructions without writing runtime code.

5 Worked Examples and 8 Integration Patterns

The examples.md file contains 5 complete plugin implementations covering different component combinations. The integrations.md file provides patterns for connecting plugins to external services — SQLite, PostgreSQL, GitHub, Slack, Stripe, OAuth, Docker, and Cloudflare Workers.

These aren't abstract descriptions. Each example includes every file needed to ship: plugin.json, skill definitions, MCP server code, hook scripts, and configuration. Copy the structure, change the names, and you have a working plugin.

The Pivot: How This Claude Code Plugin Shed Its Codebase

Plugin Architect didn't start as a Markdown-only project. The commit history tells the story.

From February 10-13, the repository housed Hive — a code-heavy system with SQLite storage, configurable tool categories, workflow support, migrations, and a CI pipeline. Eight commits built out this architecture.

On February 15, I deleted all of it.

b9d0fca: Remove Hive source, docs, and templates

Nine commits followed in a single day, restructuring the entire repo as a lightweight prompt-only Claude Code plugin. The Hive codebase — with its database layer, migration system, and TypeScript runtime — was replaced by three Markdown files.

Why the Pivot

The code-heavy approach solved the wrong problem. Plugin Architect doesn't need to run anything. It needs to know things and guide decisions. Those are prompt engineering problems, not software engineering problems.

SQLite added complexity without value. Tool categories and filtering required configuration that slowed down the user. The CI pipeline tested infrastructure that wasn't the product — the product was the knowledge encoded in the prompts.

The pivot cut repository size from hundreds of files to 8. Build time went from "install dependencies, compile TypeScript, run tests" to zero. The install path went from "clone, install, build, configure" to a single command.

The Tradeoff

Pure prompt engineering trades validation for simplicity. The Hive approach could programmatically verify that generated plugins had correct file structures, valid JSON manifests, and matching tool registrations. The Markdown approach relies on Claude following the instructions accurately.

In practice, Claude follows well-structured instructions reliably. The cases where it deviates are edge cases — unusual component combinations or ambiguous user requests — and the Confirm-Before-Build gate catches most of those by showing the proposed architecture before generating code.

Lessons Learned

What Worked Well

Single-skill architecture. Keeping everything in one skill (/plugin-architect) with supporting reference files made the product discoverable. Users learn one command. Claude loads the full context on every invocation, ensuring it always has the complete picture regardless of which extension point the user needs.

No-placeholder policy. The instruction to write complete, production-ready code in every generated file eliminated the most frustrating failure mode: scaffolding that requires significant manual completion. Users get working plugins, not starter templates.

Intent-based classification. The component selection matrix is the most-used part of the skill. Mapping natural language descriptions to extension points removes a decision that blocks most first-time plugin developers.

What I'd Do Differently

Add more language examples. All MCP Server templates use TypeScript. The MCP protocol is language-agnostic, and Python developers are a large segment of the Claude Code user base. Adding Python SDK examples would broaden the audience.

Split the knowledge base. Loading the full 30KB context on every invocation wastes tokens when a user only needs help with one component type. A multi-skill architecture — /plugin-architect hooks, /plugin-architect mcp — would load targeted context and reduce token consumption.

Add a health check mechanism. There is no way to verify that a plugin generated by Plugin Architect is correctly structured after the fact. A companion validation tool — which I later built as plugin-ops — fills this gap.

Conclusion

Plugin Architect demonstrates that prompt engineering is a valid product architecture. A well-structured 30KB knowledge base, encoded in three Markdown files, replaces what would otherwise require a runtime, database, and build pipeline.

The key insight: match the solution to the problem type. Plugin Architect solves a knowledge and guidance problem, not a computation problem. Markdown and prompt engineering are the right tools for that job. Runtime code would have been over-engineering.

Key Takeaways:

• Zero-code plugins are viable products when the problem is knowledge transfer, not computation
• Intent-based classification (natural language → component type) removes the biggest friction point for new plugin developers
• Pivoting from a code-heavy architecture to pure prompts cut complexity by an order of magnitude with no loss in capability
• The Confirm-Before-Build gate prevents the most common failure mode of generative tools: unwanted output
• Supporting reference files (examples, integration patterns) scale the skill's knowledge without bloating the core instruction set

Source Code: GitHub

Plugin GTM exists because the gap between "I built something" and "people know about it" is where most developer projects die. The Claude Code plugin system turned out to be the right platform to close that gap.

Project Overview

The Challenge

Developers ship code, then stall on go-to-market. Positioning requires thinking about audiences. Messaging requires distilling technical capability into benefits. Content requires writing landing pages, README files, social posts, and launch emails.

The typical workflow: finish coding, open a Google Doc, stare at a blank page, context-switch between 5 tools, and spend a weekend on launch prep. The mechanical work of GTM — not the strategy — consumes the time.

The Solution

Plugin GTM keeps the entire GTM workflow inside Claude Code. Seven slash commands cover the full lifecycle:

Tech Stack

Architecture

The plugin follows a three-layer design:

┌─────────────────────────────────────────────┐
│           Skills Layer (7 SKILL.md)          │
│  /gtm  /gtm-analyze  /gtm-plan  /gtm-content│
│  /gtm-research  /gtm-publish  /gtm-refine   │
├─────────────────────────────────────────────┤
│        MCP Server (29 tools, 2 resources)    │
│   Product CRUD │ Plan CRUD │ Content CRUD    │
│   Launch Items │ Versions  │ Export/Diff     │
├─────────────────────────────────────────────┤
│           SQLite Persistence (WAL)           │
│   products │ plans │ content │ versions      │
│                launch_items                   │
└─────────────────────────────────────────────┘

The skills layer handles user interaction through prompt engineering that guides Claude through GTM workflows. The MCP server handles data: 29 tools for CRUD operations, content versioning, and file export. SQLite provides persistence with foreign key constraints and cascading deletes.

The Data Model

Five tables form the core, with a clear hierarchy:

Product (1) ──< Plan (N)
                  │
           ┌──────┴──────┐
           │              │
    Content (N)    LaunchItem (N)
       │
ContentVersion (N)

A product has plans. Plans have content and launch items. Content has automatic version snapshots. Deleting a product cascades through all associated data. This is a deliberate choice for clean project management, though it carries the risk of accidental data loss.

Key Features

Content Versioning with Automatic Snapshots

Every content update triggers an automatic snapshot of the previous version before overwriting. This happens at the data layer, not the skill layer. It works regardless of which skill or tool initiates the change.

export function updateContent(id: string, updates: Partial<Content>) {
  const existing = getContent(id);
  if (!existing) throw new Error("Content not found");

  // Auto-snapshot before change
  if (updates.body !== undefined && updates.body !== existing.body) {
    snapshotVersion(id);
  }

  // Proceed with update...
}

The version history is append-only. Restoring a previous version creates a new snapshot of the current state, then overwrites with the restored content. No data is lost at any step.

Content Export with Drift Detection

Generated content lives in the SQLite database until exported to files. The export system detects drift between the database and filesystem:

export type DiffStatus =
  | "not_exported"    // Never exported
  | "in_sync"         // File matches database
  | "file_modified"   // Someone edited the file
  | "db_modified"     // Content updated in database
  | "both_modified";  // Both changed independently

This prevents a common problem: generating content, editing it manually, then overwriting with a stale database version. The /gtm-publish skill surfaces conflicts and lets you choose which version to keep.

GTM Templates by Category

Five category-specific templates provide starting points with pre-configured positioning, messaging, ICP profiles, and launch checklists:

Each template is a ~6KB TypeScript object with real positioning frameworks, not generic placeholder text. The developer-tool template includes positioning for both individual developers and team leads — different audiences with different buying criteria.

Performance Results

The Tradeoffs

What This Costs

SQLite is synchronous and single-threaded. The DatabaseSync API from Node 22's native node:sqlite blocks the event loop during queries. For a single-user tool, queries complete in microseconds. For concurrent access from multiple Claude Code sessions, contention becomes real.

The MCP server is monolithic. All 29 tools live in a single 21KB index.ts file (~600 lines). Readable today, but adding 20 more tools would make a single file unwieldy. A tool registry pattern would scale better.

Templates are hardcoded. The 5 GTM templates are TypeScript objects compiled into the server. Adding a custom template requires modifying source code and rebuilding. A user-facing template system would be more flexible.

Content generation quality depends on the LLM. The MCP tools store and version content, but the writing happens in the skills layer through Claude. The quality of generated landing pages and social posts varies with how well the product was analyzed in step one.

When Not to Use This

Plugin GTM works for developer-focused products where the builder is also the marketer. It breaks down when:

• GTM requires cross-functional team coordination (no collaboration features)
• Distribution channels need API integrations (no automated posting)
• Content needs visual design (generates text only, no images or layouts)
• Market research needs quantitative data beyond what web search provides

Lessons Learned

What Worked Well

Codebase analysis as the entry point. Starting with /gtm-analyze — which reads README, package.json, source files, and git history — produces strong product profiles. Technical capability extraction maps directly to feature-benefit messaging. This approach works because the codebase is the product.

Separation of storage and generation. Keeping the MCP server as a pure CRUD layer and the skills as the intelligence layer made both easier to build and test. The 106 tests cover the data layer exhaustively without needing to test LLM output.

Content versioning by default. Making snapshots automatic (not opt-in) eliminated the "I liked the previous version better" problem. Users iterate freely knowing every version is preserved.

What I'd Do Differently

Add batch operations from the start. The initial 20 tools required individual calls for each operation. Version 0.2.0 added batch export and publish, but retrofitting batch semantics onto a per-item API required new tools rather than extending existing ones.

Integrate with at least one distribution channel. Even a single GitHub Releases integration would demonstrate the full pipeline: analyze → plan → generate → publish. Without automated distribution, the last mile is still manual.

Design the content model for collaboration. The single-user SQLite approach was fast to build but locks out the most valuable GTM pattern: getting feedback from others before launch.

Conclusion

Plugin GTM proves that developer marketing doesn't need to be a context-switching marathon. Persistent storage, structured workflows, and content versioning handle the mechanical work. Product analysis, positioning frameworks, content generation, and launch checklists stay in the environment where you built the product.

The real value isn't the content generation. It's the structured thinking that /gtm-plan forces: define your ICP before writing copy, establish positioning before creating content, track launch items with deadlines.

Key Takeaways:

• Codebase analysis is an effective starting point for product positioning — the code reveals technical capability that maps to messaging
• Content versioning should be automatic, not opt-in — iteration happens constantly, and users need to restore previous versions
• Drift detection between database and filesystem prevents the most common content management failure: accidental overwrites
• Category-specific GTM templates provide 80% of the strategy framework, letting you focus on the 20% that's unique to your product
• MCP server architecture separates data persistence from LLM-driven generation, making both independently testable

Source Code: GitHub

Plugin Ops completes a three-plugin lifecycle toolkit. Plugin Architect designs and builds plugins. Plugin GTM takes them to market. Plugin Ops keeps them healthy after launch.

Project Overview

The Challenge

Claude Code plugins ship fast. The ecosystem is new, documentation is evolving, and most plugins launch without health checks, issue tracking, or release processes. A plugin that works today might break tomorrow when APIs change, dependencies drift, or the Claude Code plugin spec updates.

Manual maintenance doesn't scale. Checking file structure validity, scanning for missing manifests, verifying skill frontmatter, auditing dependencies — these are repetitive tasks. Without automation, they get skipped until something breaks.

The Solution

Plugin Ops provides five operational commands that cover the maintenance lifecycle:

Register a plugin project once, then run health scans on demand. Issues discovered during scans feed directly into the tracker. Releases follow semver with auto-generated changelogs.

Tech Stack

Architecture

Plugin Ops mirrors the architecture established by Plugin GTM: a skills layer for user interaction, an MCP server for data operations, and SQLite for persistence.

┌──────────────────────────────────────────────┐
│           Skills Layer (5 SKILL.md)           │
│  /ops  /ops-health  /ops-issues               │
│  /ops-release  /ops-runbook                    │
├──────────────────────────────────────────────┤
│      MCP Server (32 tools, 3 resources)       │
│  Project CRUD │ Health CRUD │ Issue CRUD      │
│  Release CRUD │ Runbook Exec │ Templates      │
├──────────────────────────────────────────────┤
│          SQLite Persistence (WAL)             │
│  projects │ health_checks │ issues            │
│  releases │ runbook_executions                │
└──────────────────────────────────────────────┘

Project Auto-Detection

When you run /ops init in a plugin directory, the system scans the filesystem to classify the project:

export function detectProject(projectPath: string): {
  has_skills: number;
  has_mcp: number;
  has_hooks: number;
  has_agents: number;
  type: ProjectType;
  version: string | null;
  name: string | null;
} {
  // Check for skills/ directory
  if (existsSync(join(projectPath, "skills"))) has_skills = 1;
  // Check for .mcp.json or src/index.ts
  if (existsSync(join(projectPath, ".mcp.json"))) has_mcp = 1;
  // Check for hooks in .claude/settings.json
  // Check for agents/ directory

  // Classify type
  if (has_mcp && has_skills) type = "full";
  else if (has_mcp) type = "mcp";
  else type = "skill-only";

  return { has_skills, has_mcp, has_hooks, has_agents, type, version, name };
}

This detection maps directly to health check templates. A skill-only plugin gets 8 checks. An MCP plugin gets 10. A full plugin gets 15.

Key Features

Health Check Templates

Three templates scale checks based on project complexity:

Checks cover structure (directory layout, manifest validity), skills (frontmatter schema, file sizes), MCP (tool registration, transport config), and quality (README completeness, license presence).

The health check definitions exist in templates, but evaluation happens through Claude. The MCP tools record results — they don't perform the scanning. This delegates intelligence to the LLM while the data layer handles persistence and trend tracking.

Issue Tracking with Health Scan Integration

Issues flow from health scans into a structured tracker with priority, category, and lifecycle management:

server.tool(
  "ops_issue_create",
  "File a new issue for a project",
  {
    project_id: z.string(),
    title: z.string(),
    priority: z.enum(["critical", "high", "medium", "low"]).optional(),
    category: z.enum([
      "bug", "dependency", "quality",
      "structure", "feature", "tech-debt"
    ]).optional(),
    health_check_id: z.string().optional(),
  },
  async (params) => {
    const issue = createIssue(params);
    return { content: [{ type: "text", text: JSON.stringify(issue, null, 2) }] };
  },
);

The health_check_id foreign key links issues to the scan that discovered them. This creates traceability: which scan found the problem, when it was filed, and when it was resolved. Issue stats aggregate by status, priority, and category.

Release Management with Changelog Export

The release workflow handles semver versioning and generates changelogs from the issue history:

// Changelog export renders Markdown from release + issue data
export function exportChangelog(projectId: string): string {
  const releases = listReleases(projectId);
  return releases.map(release => {
    const issues = listIssuesByRelease(release.id);
    return `## ${release.version} (${release.released_at})\n\n` +
      issues.map(i => `- ${i.title}`).join("\n");
  }).join("\n\n");
}

Each release records the version, release date, notes, and associated file changes. The export produces a CHANGELOG.md with diff detection — the same drift detection pattern from Plugin GTM.

Performance Results

The Tradeoffs

What This Costs

Health scanning is LLM-driven, not deterministic. The check templates define what to look for, but Claude performs the evaluation. Results can vary between sessions. A deterministic linter would produce consistent output but couldn't evaluate subjective criteria like "README completeness."

No test suite. Plugin Ops ships without tests. For a tool that audits the health of other plugins — including checking for test coverage — this is an ironic gap. The architecture mirrors Plugin GTM, which has 106 tests, so retrofitting tests is straightforward.

Migrations run on every connection. The 5-second TTL on database connections means migrate() executes on every reconnection. The migrations are idempotent (CREATE TABLE IF NOT EXISTS and PRAGMA table_info checks), but the overhead is unnecessary for a stable schema.

Cascade deletes risk data loss. Deleting a project removes all health checks, issues, releases, and runbook executions. There's no soft-delete mechanism at the data layer. The skill layer asks for confirmation, but a direct MCP tool call bypasses that guardrail.

When Not to Use This

Plugin Ops works for solo plugin developers managing 1-10 projects. It breaks down when:

• Multiple developers need concurrent access to the same database
• You need deterministic, reproducible health scans (use a linter instead)
• Plugin maintenance requires integration with external issue trackers (GitHub Issues, Linear)
• You're managing non-plugin projects (the health templates are plugin-specific)

Lessons Learned

What Worked Well

Shared architectural patterns. Building Plugin Ops after Plugin GTM meant reusing the same patterns: TTL connection pool, Zod validation, SKILL.md conventions, WAL mode SQLite. The commit history shows 3 commits to reach feature completeness. Shared patterns eliminated most architectural decisions.

Template-based health checks. Scaling checks by project type avoids overwhelming simple plugins with irrelevant checks. A skill-only plugin doesn't need MCP transport validation.

Runbooks as first-class operations. Recording runbook executions — which steps were completed, how long they took, what failed — turns tribal knowledge into auditable procedures.

What I'd Do Differently

Add deterministic checks alongside LLM evaluation. Programmatic validation for objective criteria (JSON validity, file existence, semver format) would make health scans reproducible. Reserve LLM evaluation for subjective criteria (documentation quality, API design).

Implement soft deletes. Cascade deletion is aggressive for a maintenance tool. Archiving projects instead of deleting them would preserve historical data.

Write tests from the start. Plugin GTM's test suite caught edge cases in content versioning and export. Plugin Ops would benefit from the same coverage, especially for migration code.

Conclusion

Plugin Ops closes the lifecycle loop for Claude Code plugins. Design with Plugin Architect, launch with Plugin GTM, maintain with Plugin Ops.

The three plugins share architectural DNA: MCP servers with SQLite persistence, Zod-validated tools, and SKILL.md-driven user interaction. Building them in sequence — architect first, then GTM, then ops — created compounding velocity. Each plugin took less time than the last because the patterns were established.

Key Takeaways:

• Project auto-detection maps plugin structure to the right health check template, avoiding irrelevant checks for simpler projects
• Linking issues to health scans creates traceability from discovery to resolution
• LLM-driven evaluation handles subjective quality criteria that deterministic linters cannot assess
• Shared architectural patterns between plugins reduce time-to-ship for each subsequent project
• The lifecycle toolkit pattern (build → launch → maintain) covers gaps that individual tools leave open

Source Code: GitHub

This post covers Claude Code Skills in detail: the SKILL.md format, invocation control, subagents, hooks, and the open standard that makes Skills portable across platforms. Part 1 covered Skills for non-technical users. Part 2 covered the architecture and advanced patterns.

Claude Code Skills: The SKILL.md Format

Every Claude Code Skill lives in a directory with a SKILL.md file at its root. The file has two sections: YAML frontmatter for configuration and a markdown body for instructions.

Complete Frontmatter Reference

---
name: pr-review                    # Max 64 chars, lowercase + hyphens
description: Reviews pull requests against team coding standards
argument-hint: "[PR number]"       # Shown in autocomplete
disable-model-invocation: false    # true = manual /pr-review only
user-invocable: true               # false = Claude-only, hidden from / menu
allowed-tools: Bash(gh *), Read    # Tools Claude can use without asking
model: sonnet                      # Model override when active
context: fork                      # Run in isolated subagent
agent: Explore                     # Subagent type (with context: fork)
---

The name field has two restrictions: no "anthropic" or "claude" (reserved words), and no XML tags in any frontmatter value. Names must use lowercase letters, numbers, and hyphens only.

Directory Structure

pr-review/
├── SKILL.md              # Required — config + instructions
├── checklist.md          # Reference doc (loaded on demand)
├── scripts/
│   └── diff-stats.sh     # Executable (output enters context, not source)
└── examples/
    └── good-review.md    # Example output for Claude to follow

Storage Locations

Claude Code discovers Skills from four locations, in priority order:

In monorepos, Claude also discovers Skills from nested directories. Editing a file in packages/frontend/ triggers discovery of Skills in packages/frontend/.claude/skills/.

Backward compatibility: As of Claude Code v2.1.3 (January 2026), .claude/commands/ files and .claude/skills/ directories both work. A file at .claude/commands/review.md and a directory at .claude/skills/review/SKILL.md both create the /review command. Existing commands continue working with no migration required.

Dynamic Context Injection

The !`command` syntax runs shell commands before Skill content reaches Claude:

---
name: pr-summary
description: Summarizes the current pull request
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Context
- PR diff: !`gh pr diff`
- PR comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

## Task
Summarize this pull request. Focus on:
1. What changed and why
2. Potential risks or breaking changes
3. Test coverage gaps

The shell commands execute immediately. Their output replaces the !`command` placeholder before Claude sees the prompt. This loads real-time data into the Skill without Claude spending turns on tool calls.

The tradeoff: dynamic context runs on every invocation. If gh pr diff returns 50KB of output, that consumes 50KB of context window each time. Keep commands focused and pipe through filters when dealing with large output.

Invocation Control

The Control Matrix

Two frontmatter fields determine who can trigger a Skill:

Use disable-model-invocation: true for destructive operations (database migrations, deployments) where you want explicit user control. Use user-invocable: false for background knowledge that Claude should apply automatically — coding standards, project conventions, error handling patterns.

String Substitution

Skills accept arguments through substitution variables:

---
name: review-file
description: Reviews a specific file for code quality
argument-hint: "[file-path]"
---

Review the file at $ARGUMENTS for:
1. Code quality and readability
2. Security vulnerabilities
3. Performance issues

Invoking /review-file src/auth.ts replaces $ARGUMENTS with src/auth.ts. Use $0, $1, $2 for positional arguments when a Skill accepts multiple inputs.

Context Window Budget

Skill descriptions consume 2% of the context window — approximately 16,000 characters as a fallback limit. If you install many Skills, some descriptions get excluded from the system prompt.

Run /context to check which Skills loaded and which were excluded. Override the budget with the SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable if the default is too restrictive.

The tradeoff: more Skills means more competition for the description budget. Skills with disable-model-invocation: true don't consume description budget because they're excluded from auto-invocation. Use this flag on rarely-needed Skills to free up space.

Subagents and Hooks

Forked Execution

Adding context: fork runs the Skill in an isolated subagent. The Skill content becomes the subagent's system prompt. The parent conversation continues after the subagent completes.

---
name: security-audit
description: Runs a security audit on the codebase
context: fork
agent: general-purpose
allowed-tools: Bash(npm audit *), Read, Grep, Glob
---

Audit this codebase for security vulnerabilities:

1. Run `npm audit` and analyze results
2. Search for hardcoded secrets using patterns: API keys, tokens, passwords
3. Check dependency versions against known CVEs
4. Report findings with severity levels

Available agent types: Explore (fast, read-only codebase analysis), Plan (architecture design), general-purpose (full capabilities), or custom agents defined in .claude/agents/.

The tradeoff: forked Skills lose conversation history. The subagent starts with only the Skill content and the user's invocation arguments. Design forked Skills to be self-contained — include all necessary context in the Skill itself or load it via dynamic context injection.

Skill Preloading in Subagents

Custom subagents can preload Skills so the full Skill content is injected at startup:

# .claude/agents/api-developer.md
---
name: api-developer
description: Implements API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
  - database-patterns
---

Build API endpoints using the preloaded team patterns.
Always follow the conventions in the loaded Skills.

This differs from normal Skill discovery. Preloaded Skills inject their full content immediately rather than waiting for activation. Use this for domain-specific agents where certain conventions always apply.

Lifecycle Hooks

Skills support hooks that run at specific events:

---
name: safe-deploy
description: Deploys to staging with safety checks
hooks:
  PreToolUse:
    - matcher: Bash(rm *|git push --force*)
      type: prompt
      prompt: "Block this command. Explain why it's unsafe in a deployment context."
  Stop:
    - type: command
      command: "echo 'Deploy skill completed at $(date)' >> /tmp/deploy.log"
---

Hook events include PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, Notification, UserPromptSubmit, SessionStart, and SessionEnd. Hooks can be shell commands (type: command), single-turn model prompts (type: prompt), or multi-turn agents (type: agent).

The async: true option (added January 2026) runs hooks in the background without blocking Skill execution — useful for logging, notifications, or non-critical validation.

The Agent Skills Open Standard

Specification

Anthropic published the Agent Skills specification at agentskills.io in December 2025. The core format matches what Claude Code uses: a directory with a SKILL.md file containing YAML frontmatter and markdown instructions.

The open standard defines a minimal required schema:

---
name: my-skill          # Required: max 64 chars
description: What it does and when to use it  # Required: max 1024 chars
license: MIT            # Optional
compatibility: "Requires git, node >= 18"     # Optional: max 500 chars
metadata:               # Optional: arbitrary key-value pairs
  author: Dakota Smith
  version: 1.0.0
---

The specification mandates progressive disclosure: metadata (~100 tokens) loads at startup, core content (under 5,000 tokens recommended) loads on activation, supplementary files load on demand.

Platform Adoption

As of early 2026, these platforms read the Agent Skills format:

The key distinction: Claude Code extends the standard with platform-specific features. These extensions work only in Claude Code and degrade gracefully elsewhere — other platforms ignore unknown frontmatter fields.

What's Portable vs. What's Not

Write the core Skill (name, description, instructions, supporting files) for maximum portability. Add Claude Code extensions knowing they won't break anything on other platforms — unknown fields are ignored, not rejected.

Validation

The reference library provides validation:

npx skills-ref validate ./my-skill

This checks frontmatter requirements, directory naming conventions, and file size recommendations against the open standard specification.

Practical Migration: Commands to Skills

If you have existing .claude/commands/ files, they keep working. But the Skills format offers more capability. Here's the conversion pattern:

Before (.claude/commands/deploy.md):

Deploy the current branch to staging.
Run tests first, then build, then deploy.

After (.claude/skills/deploy/SKILL.md):

---
name: deploy
description: Deploys the current branch to staging after running tests and build
argument-hint: "[environment]"
disable-model-invocation: true
allowed-tools: Bash(npm run *), Bash(git *)
hooks:
  PreToolUse:
    - matcher: Bash(git push --force*)
      type: prompt
      prompt: "Block force pushes during deployment."
---

Deploy the current branch to $ARGUMENTS (default: staging).

1. Run the test suite: `npm run test`
2. Build the project: `npm run build`
3. Deploy: `npm run deploy:$ARGUMENTS`

If any step fails, stop and report the error. Do not proceed to deployment.

The Skills version adds: argument support, invocation control (manual-only for safety), tool permissions, and a hook to prevent force pushes. The commands version has none of these.

Limitations and Tradeoffs

Context budget is real. With 2% of the context window allocated to Skill descriptions, a project with 30+ Skills hits the limit. Prioritize: use disable-model-invocation: true on rarely-needed Skills to remove them from the description budget.

Subagents cannot nest. A forked Skill cannot spawn another subagent. Design your agent architecture as a flat hierarchy — one level of delegation, not a tree.

MCP tools are unavailable in background subagents. If your Skill relies on MCP servers (database connections, external APIs), it cannot run with context: fork. Run it in the main conversation context instead.

Platform behavior varies. The allowed-tools field is marked experimental in the open standard. Each platform interprets it differently or ignores it. Test Skills on every target platform before distributing.

Hot-reload has limits. Skills auto-reload on save within a running session. Subagent definitions in .claude/agents/ require a session restart or /agents reload to pick up changes.

When NOT to use Skills: One-off scripts that you'll run once and discard. Aliases shorter than their frontmatter (if the Skill body is shorter than the config, use a shell alias). Tasks requiring real-time bidirectional connections — Skills don't maintain open sockets or streaming API sessions.

Conclusion

The Agent Skills standard solved a real problem: AI capabilities locked inside individual platforms. A Skill written for Claude Code now works in GitHub Copilot, Cursor, and Gemini CLI without modification. Claude Code's extensions (hooks, subagents, dynamic context) add power for teams that need it, while the portable core ensures the investment transfers across tools.

Key Takeaways:

• SKILL.md is the universal format: YAML frontmatter for config, markdown body for instructions, supporting files for resources
• Claude Code extends the open standard with context: fork, hooks, dynamic context (!`command`), and subagent integration — powerful but not portable to other platforms
• The core Skill format (name, description, instructions, supporting files) works across 10+ platforms including GitHub Copilot, Cursor, and Gemini CLI
• Use disable-model-invocation: true for destructive operations and user-invocable: false for background conventions
• Skill descriptions consume 2% of the context window — monitor with /context and keep descriptions specific to avoid budget overflow

This is Part 3 of a series on Claude Skills. Part 1 covers what Skills are and why they matter for non-technical teams. Part 2 covers the architecture and advanced patterns for power users.

Part 1 of this series covered what Skills are and why they matter for non-technical teams. This guide goes deeper. You'll learn the architecture behind Skills, how to build advanced multi-step workflows with validation, and how to deploy Skills across an organization.

The Three-Tier Architecture

Every Skill loads in three stages. Understanding these stages is the difference between a Skill that wastes context and one that scales.

Tier 1 — Metadata (always loaded). Claude reads the Skill's name and description at the start of every conversation. Cost: ~100 tokens per Skill. This is how Claude decides whether your Skill is relevant to the current task.

Tier 2 — Instructions (loaded when triggered). When Claude determines a Skill applies, it loads the full instruction file. Cost: under 5,000 tokens. This contains the step-by-step playbook for the workflow.

Tier 3 — Resources (loaded as needed). Supporting files — templates, reference docs, scripts — load only when a specific step requires them. Cost: effectively unlimited because they enter context one piece at a time.

The result: Anthropic reports a 98% token reduction when Skills are present but not triggered. Install 20 Skills and pay the context cost of fewer than 2,000 tokens total until one activates.

This architecture also means the structure of your Skill matters more than its length. A 200-line instruction file that loads 5 reference files on demand outperforms a 1,000-line monolith that loads everything upfront.

Building Advanced Claude Skills

The Skill File Format

Every Skill is a directory containing a SKILL.md file. The file has two parts: YAML frontmatter (metadata) and markdown body (instructions).

---
name: weekly-report
description: Generates weekly status reports from raw notes, following the team's standard format with executive summary, risk flags, and metric tables.
---

## Instructions

When the user provides weekly notes, meeting summaries, or ticket updates:

1. Extract key metrics and progress items
2. Format using the team template in REPORT_TEMPLATE.md
3. Flag any items marked "blocked" or "at risk"
4. Generate executive summary (3 sentences max)

Two rules for the description field: write it in third person ("Generates weekly reports" not "I generate weekly reports"), and be specific about when the Skill applies. Vague descriptions like "helps with reports" cause poor activation accuracy. Specific descriptions like "generates weekly status reports from raw notes" trigger reliably.

Supporting Files

A Skill directory can contain anything Claude needs:

weekly-report/
  SKILL.md              # Main instructions (Tier 2)
  REPORT_TEMPLATE.md    # Team's report format (Tier 3)
  METRIC_DEFINITIONS.md # What each KPI means (Tier 3)
  examples/
    good-report.md      # Example of excellent output (Tier 3)

Claude loads REPORT_TEMPLATE.md when it reaches the "format using the team template" step — not before. This keeps the context window lean until the information is needed.

Executable Scripts

This is where Skills get powerful. A Skill can include Python or JavaScript scripts that Claude runs during execution. The script source code never enters the context window. Only the script's output does.

A PDF analysis Skill might include:

pdf-analyzer/
  SKILL.md
  scripts/
    extract_text.py     # Extracts text from PDF
    extract_tables.py   # Extracts tabular data
    validate_output.py  # Checks extraction quality

Claude runs extract_text.py on the uploaded PDF, receives the extracted text as output, and works with that text — without the script source code consuming context tokens. This makes scripts far more token-efficient than having Claude generate equivalent code from scratch each session.

The tradeoff: script availability depends on the platform. On claude.ai, Claude can install packages from npm and PyPI. On the API, only pre-installed packages are available. Know your deployment target before building script-heavy Skills.

The Validation Pattern

The most reliable advanced pattern is plan-validate-execute:

1. Claude creates an intermediate output (a draft, a data structure, a plan)
2. A validation script checks the output for errors
3. Claude fixes any issues before proceeding
4. Final execution only happens after validation passes

This catches errors before they compound. For a form-filling Skill, the sequence looks like: analyze form → generate field mapping → validate mapping against constraints → fill the form → verify output. Each step has a checkpoint. If validation fails at step 3, Claude returns to step 2 instead of producing a broken final result.

Patterns That Separate Good Skills From Great Ones

Chunk Over Monolith

A single 800-line Skill that handles voice consistency, audience targeting, format selection, and quality review will underperform four focused Skills that each handle one concern.

Rhonda Britten, a business coach, tested this directly: a master voice Skill combined with separate audience-specific Skills (public-facing vs. coaching clients) outperformed a monolithic voice profile. Each audience Skill activates independently based on context.

The principle: one Skill, one job. Composition happens through Claude's judgment, not through complex branching inside a single Skill.

Workflow Sequencing

Skills compose naturally when their descriptions are specific. A four-Skill content pipeline:

1. Business Case Builder — Analyzes opportunity and generates projections
2. Sales Page Writer — Takes the business case and creates conversion copy
3. Email Conversion Tester — Reviews the sales page for conversion optimization
4. Social Amplifier — Generates platform-specific posts from the sales page

Each Skill's description references the output of the previous step. Claude chains them automatically when you say "take this business case through the full content pipeline." No explicit chaining mechanism exists — composition happens through Claude's semantic understanding of each Skill's description.

Calibrate Freedom

Match prescriptiveness to risk:

• High freedom (text guidance only): Content analysis, brainstorming, code reviews. Claude uses judgment within guardrails.
• Medium freedom (templates and pseudocode): Reports with preferred structure, emails with required sections. Claude fills a framework.
• Low freedom (exact scripts): Data migrations, compliance documents, financial calculations. Claude executes precisely specified steps.

The higher the cost of error, the lower the freedom. A creative brainstorm Skill and a payroll calculation Skill need fundamentally different levels of prescriptiveness.

Real-World Results

These results come from published case studies, not synthetic benchmarks.

The common thread: each Skill encodes domain expertise that would otherwise require re-explanation every session. The Blue Fish Skill uses a two-word trigger ("PIN" to capture, "APPROVE" to confirm) to minimize friction during normal conversations.

Team Deployment

Skills distribution varies by plan:

Individual (Pro/Max): Skills are private to your account. No peer-to-peer sharing mechanism exists on claude.ai.

Team/Enterprise: Organization Owners upload Skills through admin settings. Provisioned Skills appear for all org members immediately. Owners choose whether Skills are enabled or disabled by default. Individual users can toggle provisioned Skills off but cannot delete org-provisioned ones.

Skills Directory: Pre-built partner Skills from Notion, Figma, Atlassian (Jira/Confluence), Canva, and Cloudflare. Admins provision these across the org in one click from claude.com/connectors.

The tradeoff: Skills do not sync across surfaces. A Skill uploaded to claude.ai must be separately uploaded to the API and separately configured for Claude Code. If your team works across multiple Anthropic surfaces, plan for maintaining Skills in each environment.

When Skills Break Down

Skills are not the right tool for every situation.

Vague descriptions cause misfires. Skills activate based on semantic matching between the conversation and the Skill description. If your description is generic ("helps with writing"), the Skill triggers when it shouldn't and stays silent when it should activate. Test activation with 10 different prompt phrasings before deploying to your team.

Session state resets. Skills don't persist data between conversations. Each session starts fresh. If your workflow requires memory across sessions, you need an external system (Notion, a database, a shared file) as the persistence layer.

500 lines is the practical limit. Anthropic recommends keeping SKILL.md under 500 lines. Beyond that, move content into supporting reference files that load on demand. A 1,200-line SKILL.md wastes context on instructions Claude doesn't need for the current step.

Security matters for shared Skills. A Skill can direct Claude to execute arbitrary code through bundled scripts. Only install Skills from trusted sources. For organizations, the admin provisioning path provides centralized control. For individuals, review any community Skill's scripts before installing.

One-off tasks don't need Skills. If you'll do something once, a normal prompt is faster than building a Skill. The return on investment starts at the second use and compounds with every use after that. Budget 15-30 minutes to build and test a first working Skill.

Conclusion

Skills are infrastructure, not features. The three-tier architecture makes them lightweight to install and powerful to execute — but only when built with that architecture in mind.

Key Takeaways:

• Skills use progressive disclosure: ~100 tokens at rest, under 5,000 when active, unlimited resources on demand — a 98% context reduction when idle
• Structure Skills as focused, single-purpose units; composition through multiple Skills outperforms monolithic mega-Skills
• Use the plan-validate-execute pattern for any Skill where errors are costly
• Match prescriptiveness to risk: high freedom for creative tasks, low freedom for precision tasks
• Team deployment requires admin provisioning; Skills do not sync across claude.ai, the API, and Claude Code

This is Part 2 of a series on Claude Skills. Part 1 covers what Skills are and why they matter for non-technical teams. Part 3 dives into Claude Code Skills and the Agent Skills open standard for developers.

MCP Apps launched on January 26, 2026, as the first official extension to the Model Context Protocol. The concept: tools no longer limit themselves to text responses. They ship interactive HTML interfaces—dashboards, forms, 3D visualizations, PDF viewers—that render directly inside the conversation. Six clients support MCP Apps at launch. Ten companies shipped integrations on day one. The ext-apps repository hit 1.4k GitHub stars in its first two weeks.

This post covers what MCP Apps are, how the architecture works, and why it matters for developers building on MCP.

What Changes With Interactive Tools

Traditional MCP tools accept input and return structured data. The host renders it as text, images, or resource links. That works for most tasks. But some interactions demand more than a text response.

Ask an AI "show me sales by region" and you get a list of numbers. With this extension, the same tool returns an interactive map. Users click regions to drill down, hover for details, and toggle metrics—all without additional prompts. The interaction stays inside the conversation, right alongside the discussion that prompted it.

Here's what interactive tool UIs enable that text responses cannot:

• Data exploration — Interactive dashboards with filtering, sorting, and export
• Configuration wizards — Forms with dependent fields, validation, and defaults
• Rich media — PDF viewers, 3D model renderers, sheet music displays
• Real-time monitoring — Live-updating metrics without repeated prompts
• Multi-step workflows — Approval flows, code review, issue triage with persistent state

The ext-apps repo ships 12+ working examples covering these exact use cases: Three.js 3D scenes, CesiumJS globe maps, cohort heatmaps, budget allocators, PDF viewers, system monitors, and more.

How the Architecture Works

MCP Apps combine two existing MCP primitives in a new way: tools and resources.

A tool declares a UI resource in its description using a _meta.ui.resourceUri field. That URI uses the ui:// scheme and points to an HTML page served by the MCP server. When the host calls the tool, four things happen:

1. UI preloading — The host fetches the ui:// resource before the tool completes, enabling streamed inputs
2. Resource fetch — The server returns bundled HTML (with CSS/JS inlined via tools like vite-plugin-singlefile)
3. Sandboxed rendering — The host renders the HTML inside a sandboxed iframe with restricted permissions
4. Bidirectional communication — The app and host exchange messages via JSON-RPC over postMessage

The app stays isolated from the host. It cannot access the parent DOM, read cookies, or escape its container. All communication flows through a structured, auditable message protocol.

// Server: register a tool with UI metadata
const resourceUri = "ui://dashboard/app.html";

registerAppTool(
  server,
  "show-dashboard",
  {
    title: "Dashboard",
    description: "Displays an interactive analytics dashboard.",
    inputSchema: { type: "object", properties: { region: { type: "string" } } },
    _meta: { ui: { resourceUri } },
  },
  async ({ region }) => ({
    content: [{ type: "text", text: JSON.stringify(await getAnalytics(region)) }],
  }),
);

// Client: the App class handles host communication
import { App } from "@modelcontextprotocol/ext-apps";

const app = new App({ name: "Dashboard", version: "1.0.0" });
app.connect();

// Receive the initial tool result
app.ontoolresult = (result) => {
  const data = JSON.parse(result.content?.find(c => c.type === "text")?.text);
  renderChart(data);
};

// Call server tools from the UI when users interact
document.getElementById("refresh").addEventListener("click", async () => {
  const result = await app.callServerTool({ name: "show-dashboard", arguments: { region: "us-west" } });
  renderChart(JSON.parse(result.content?.find(c => c.type === "text")?.text));
});

The App class from @modelcontextprotocol/ext-apps abstracts the postMessage protocol. It provides methods for receiving tool results, calling server tools, updating model context, logging events, and opening browser links. You can also skip the SDK entirely and implement the JSON-RPC protocol directly.

Why This Matters for Developers

Before this extension, building interactive experiences for AI chat required client-specific code. A Slack integration needed Slack Block Kit. A Claude integration needed Claude's custom format. Every platform had its own UI contract.

The new standard defines a single contract: HTML in a sandboxed iframe with JSON-RPC messaging. Write your app once, and it renders in Claude, VS Code Insiders, Goose, Postman, MCPJam, and ChatGPT (support rolling out now). JetBrains, AWS, and Google DeepMind have all signaled interest.

The practical impact: a tool developer ships one interactive experience that works across every compliant host. No client-specific code. No platform-locked UI. If you've followed the evolution of AI dev tools, this represents a similar shift—from fragmented, platform-specific approaches to a shared standard.

The SDK supports this portability with framework starter templates for React, Vue, Svelte, Preact, Solid, and vanilla JavaScript. Each template demonstrates the same patterns adapted to the framework's conventions.

Ten companies shipped launch-day integrations: Amplitude, Asana, Box, Canva, Clay, Figma, Hex, monday.com, Slack, and Salesforce. These aren't demos—they're production servers that return interactive UIs in any supporting client.

Building Your First MCP App

The fastest path uses the create-mcp-app skill with an AI coding agent:

# Install the skill in Claude Code
/plugin marketplace add modelcontextprotocol/ext-apps
/plugin install mcp-apps@modelcontextprotocol-ext-apps

# Then ask your agent:
# "Create an MCP App that displays a color picker"

For manual setup, the dependencies are minimal:

npm install @modelcontextprotocol/ext-apps @modelcontextprotocol/sdk
npm install -D typescript vite vite-plugin-singlefile express cors tsx

A typical project structure separates server from UI:

my-mcp-app/
├── server.ts          # MCP server with tool + resource registration
├── mcp-app.html       # UI entry point
├── src/
│   └── mcp-app.ts     # UI logic using the App class
├── vite.config.ts     # Bundles HTML into single file
└── package.json

Build, serve, and test:

npm run build && npm run serve
# Server runs at http://localhost:3001/mcp

To test locally with Claude, tunnel your server with cloudflared:

npx cloudflared tunnel --url http://localhost:3001

Then add the generated URL as a custom connector in Claude's settings.

The repo also includes a basic-host test interface at localhost:8080 that renders your app without needing a full AI client. Useful for rapid iteration during development.

What's Next

The extension went from proposal (November 2025) to production (January 2026) in about two months. The spec has a stable 2026-01-26 version and an active draft for the next iteration.

The ecosystem is moving fast. Microsoft 365 Copilot Chat plans to support interactive tool UIs with rich widgets starting late February 2026. ChatGPT support is rolling out. The collaboration between Anthropic, OpenAI, and the MCP-UI community on a shared standard signals that this isn't a vendor-locked feature—it's infrastructure. That cross-platform AI tooling convergence will reshape how developers build integrations.

For developers building MCP servers, the question shifts from "what data does my tool return?" to "what experience does my tool deliver?" The answer no longer has to be text.

Conclusion

MCP Apps represent the biggest expansion of the Model Context Protocol since its launch. Interactive HTML rendered inside AI conversations, secured by iframe sandboxing, portable across every major AI client—all from a single codebase. Two weeks in, the adoption signals are strong: 1.4k GitHub stars, 10 launch partners, 6+ supporting clients, and major platforms lining up.

Key Takeaways:

• MCP Apps are the first official MCP extension, enabling interactive HTML UIs inside AI conversations
• The architecture uses sandboxed iframes with JSON-RPC over postMessage for security and portability
• One codebase runs across 6+ AI clients with zero platform-specific UI code
• 10 companies shipped production integrations at launch; more adopting weekly
• The @modelcontextprotocol/ext-apps SDK supports React, Vue, Svelte, Preact, Solid, and vanilla JS

Start with the official docs, clone the ext-apps repo, and run any of the 12+ examples to see interactive tool UIs in action.

The conventional response to low adoption: "Those employees need training." But 87% of workers have received zero AI training, and the answer isn't another workshop with generic prompts. The answer is giving people structured tools that match how they already work.

The Blank Prompt Problem

Most people's first AI experience follows the same pattern. Open a chatbot. Stare at a blank text box. Type something vague. Get a vague response. Walk away unimpressed.

This isn't a user problem. It's a design problem.

A blank prompt box is the AI equivalent of handing someone an empty spreadsheet and saying "do finance." Without context about your role, your standards, and your workflow, AI produces generic output that requires so much editing it feels faster to do the work yourself.

The data confirms this: 45% of employees doubt AI's accuracy, according to SurveyMonkey's 2026 workplace report. A growing number of workers experience what psychologists now call FOBO — Fear of Becoming Obsolete. 73% worry about losing their professional skills to AI, so they avoid it entirely.

The irony: the people most skeptical of AI stand to benefit the most from structured AI workflows.

What Are Claude Skills?

Skills are Claude's answer to the blank prompt problem. Instead of starting every conversation from scratch, a Skill teaches Claude how you work — once — and applies that knowledge automatically going forward.

Think of a Skill as a playbook. You define:

• What Claude should produce (a weekly status report, a content brief, an onboarding checklist)
• How it should be structured (your team's format, your company's tone, your manager's preferred level of detail)
• What standards to maintain (word count, required sections, data points to include)

Once created, a Skill activates whenever the task is relevant. No re-explaining context. No copy-pasting previous prompts. The institutional knowledge is built in.

Here's the important part: creating a Skill requires zero coding. You build one by describing your workflow to Claude in a normal conversation. Claude generates the Skill structure for you. If you can describe how you do your job, you can create a Skill.

This isn't a developer tool repurposed for business users. Anthropic designed Skills for everyone — pre-built Skills for document creation (Excel, Word, PowerPoint, PDF) ship with every Claude account, including the free tier. Custom Skills require a Pro subscription, but the creation process stays the same: describe your process, let Claude build it.

Skills in Action: Four Business Workflows

Here's what Skills look like across four non-technical roles.

Project Manager: Weekly Status Reports

Before: Copy last week's report. Update each section manually. Chase down teammates for numbers. Spend 45 minutes formatting.

With a Status Report Skill: Feed Claude your raw notes, meeting summaries, and ticket updates. The Skill enforces your report template — executive summary first, risk items flagged, metrics in a consistent format every time. A polished status report in 3 minutes instead of 45.

The Skill doesn't do the thinking for you. You decide what's important. But the formatting, structure, and consistency happen without effort.

Marketing Manager: Content Repurposing

Before: Write a blog post. Manually adapt it for LinkedIn, the newsletter, social media, and an internal summary. Each version takes 15-20 minutes.

With a Repurposing Skill: Feed Claude the original post. The Skill produces all four versions — each adapted for the platform's format, character limits, and tone — while maintaining your brand voice. One input, four outputs, 60+ minutes saved per piece of content.

HR Professional: Onboarding Checklists

Before: Copy the template for each new hire. Customize by role. Miss the same items every third hire because the template drifted from the actual process.

With an Onboarding Skill: The Skill contains your complete onboarding process — role-specific requirements, equipment lists, access permissions, training schedules. Feed it the new hire details. It generates a customized, complete checklist every time. Zero items forgotten because the Skill is the single source of truth.

Sales Lead: Call Preparation

Before: Scan the CRM. Skim recent emails. Wing the opening pitch.

With a Call Prep Skill: Paste the prospect's information and recent communications. The Skill generates a briefing document: company context, previous touchpoints, suggested talking points, and three discovery questions. Preparation that took 20 minutes now takes 2.

Why Consistency Matters More Than Speed

Enterprise AI users report saving 40-60 minutes per day, according to OpenAI's 2025 Enterprise Report. Those time savings are real. But speed isn't the primary value of Skills.

Consistency is.

Without a Skill, Claude's output varies based on how you phrase the prompt. Ask the same question three different ways, get three different quality levels. Teams working without Skills produce work that depends entirely on who wrote the prompt and how much time they had.

With a Skill, the quality floor rises. Every output follows the same structure, meets the same standards, and includes the same required elements. The worst output your team produces with a Skill is better than the average output without one.

This matters most for teams where consistency is the goal: compliance documents, client deliverables, internal reporting, brand communications. One Skill that enforces your standard eliminates the variance.

OpenAI's enterprise research reinforces this: 75% of enterprise AI users report completing tasks they couldn't complete before. The gap isn't about doing things faster. It's about reaching a quality bar that previously required specialized expertise.

Getting Started in Five Minutes

No technical setup required. Four steps:

1. Identify your most repetitive workflow. Not the most complex — the most frequent. The report you write every Monday. The email structure you recreate weekly. The analysis format your stakeholders expect.

2. Describe it to Claude. Open Claude and say: "I want to create a Skill for [your workflow]. Here's how I do it today..." Walk Claude through your process, your format, and your quality standards. Be specific about what a good output looks like.

3. Let Claude build the Skill. Claude generates a structured Skill based on your description. Review it. Adjust any details. Save it.

4. Use it. Next time you need that workflow, the Skill handles the structure. You focus on the substance.

The entire process takes five minutes for a straightforward Skill. Every use after that compounds the return.

For teams, the math is compelling. A team of 10 people using 3-4 Skills each, saving 30 minutes per day — that's 25 hours of recovered capacity per week. At a loaded cost of $50/hour, that's over $65,000 per year in productivity gains.

Conclusion

The divide between AI adopters and AI skeptics isn't about technical ability. It's about whether people have structured tools that match their actual work.

The teams pulling ahead in 2026 aren't more technical. They're more systematic. They encode their workflows, their standards, and their institutional knowledge into Skills — and Claude works the way they work instead of the other way around.

Key Takeaways:

• 49% of workers avoid AI because the blank prompt produces inconsistent results — Skills solve this with built-in structure
• Creating a Skill requires zero coding: describe your workflow to Claude and let it build the Skill for you
• The biggest value isn't speed — it's consistency across every output, every team member, every time
• Start with your most repetitive workflow, not your most complex one
• Skills compound across teams: 10 people using 4 Skills each can recover 25+ hours per week

The question for your team isn't "should we use AI?" It's "have we given AI enough structure to produce useful output?" Skills are that structure.

This is Part 1 of a series on Claude Skills. Part 2 covers power-user techniques for building advanced Skills. Part 3 dives into Claude Code Skills and the Agent Skills open standard for developers.

That counterintuitive result—discovered after building four generations of AI orchestration systems—drives the thesis behind STUDIO. The problem with AI coding tools isn't speed. It's drift. Ask Claude to build a feature—you get working code. Ask for another—more working code. After ten features, your codebase has three different patterns for the same problem, duplicate utilities scattered across files, and state management that contradicts itself. Each change looked correct in isolation. The aggregate is a mess.

I spent four iterations trying to fix this. Here's the path from reactive review to proactive supervision.

The Drift Problem

AI optimizes for task completion, not system coherence. It solves the immediate problem without considering how that solution fits existing patterns. Junior developers do this too—but juniors learn from code review. AI accepts the review, then makes the same mistake in a different file.

After 14 years in enterprise .NET and Sitecore—the same platform-specific complexity that drove the CMS analysis marketplace—I've seen what drift looks like at scale. Codebases that started clean but accumulated "quick fixes" until the original architecture disappeared. AI accelerates this. It writes code faster than you can review it, and each generation of code is internally consistent but externally disconnected from what came before.

The core insight: prevention beats detection. Catching drift after it happens is cleanup work. Stopping it before execution is architecture.

Generation 1: APL — Reactive Review

APL—the Autonomous Phased Looper—was my first attempt. Three phases: Plan, Execute, Review. The reviewer used Reflexion to self-critique and catch mistakes after execution. The learner agent persisted patterns to disk for future sessions.

APL worked. It built this blog with 47 stories across 6 epics, hitting Lighthouse 99. But the review phase was reactive—it caught problems after they existed in the codebase. The self-learning system helped patterns compound over time, and the ReAct execution loops caught individual task failures. Cross-task drift, though, slipped through. The reviewer could find inconsistent import paths. It couldn't prevent the architectural decisions that led to them.

APL proved that phased execution with self-learning produces working software. It didn't prove that working software stays coherent at scale.

Generation 2: ORC — 19 Agents, 19 Opinions

If three agents couldn't prevent drift, nineteen might.

ORC decomposed development into specialists: Architect, Security Engineer, Database Engineer, Frontend Specialist, QA, Technical Writer, and more. It added codebase analysis, Epic→Feature→Story planning, anti-slop detection, and pattern learning.

The system was powerful. One prompt could generate complete features with tests, docs, and security review. But 19 agents meant 19 opinions. The coordination overhead ate tokens—each specialist wanted to weigh in on every decision. Debugging required figuring out which agent introduced a problem. Specialists sometimes disagreed (the Architect wanted one pattern, the Security Engineer wanted another), and resolving conflicts took longer than building the feature manually.

More agents didn't mean better code. It meant more complexity and more coordination surface area. ORC taught me that capability without accountability produces chaos.

Generation 3: ALLOY — The Hybrid That Couldn't Decide

ALLOY tried to split the difference—three core agents that could summon specialists when needed. Hybrid approach. Less overhead than ORC, more capability than APL.

The problem moved: deciding when to summon specialists became its own source of drift. The system would skip consultation to move faster, then produce work that needed specialist review anyway. When it did consult, the specialist's recommendation sometimes conflicted with what the core agent had already started building.

ALLOY proved something important: the problem wasn't capability. It was accountability. No amount of agent architecture fixes drift if the system can bypass its own quality gates. The moment an agent can skip a check to "move faster," it will—and the drift compounds from there.

Generation 4: STUDIO — Supervision Over Scale

STUDIO returns to three agents: Planner, Builder, Content Writer. The difference is supervision.

Before any plan executes, STUDIO runs a mandatory questioning phase. It consults domain expert personas, challenges its own plan against five criteria (requirements coverage, edge cases, simplicity, integration fit, failure modes), and presents a confidence score. Low confidence triggers more questions. High confidence proceeds to execution.

╔══════════════════════════════════════════════════════════════╗
║  PLAN CONFIDENCE: 85%                                        ║
╠══════════════════════════════════════════════════════════════╣
║  Requirements:    [████████░░] 80%                           ║
║  Step Quality:    [██████████] 100%                          ║
║  Context:         [████████░░] 80%                           ║
║  Risk:            [████████░░] 80%                           ║
╚══════════════════════════════════════════════════════════════╝

The Builder executes exactly what the plan specifies. Each step has a validation command. If validation fails, it retries with hints from the failure output. If retries exhaust, it blocks and asks for help. Work doesn't silently fail—every step either passes validation or stops the pipeline.

When you correct something, STUDIO asks if it should remember the preference. Say yes, and it persists to a rules file that applies to future builds. Corrections compound instead of disappearing between sessions. This is the same persistence principle from APL's .apl/ directory, but applied to supervision rules rather than coding patterns.

The preference file grows over time:

{
  "preferences": [
    {
      "rule": "Use named exports, never default exports",
      "learned_from": "session_2026-01-28",
      "applied_count": 47
    },
    {
      "rule": "All API routes return typed response objects",
      "learned_from": "session_2026-01-30",
      "applied_count": 12
    }
  ]
}

After 10 corrections, STUDIO's plans already reflect your preferences. After 50, it rarely needs correction at all. The supervision tightens automatically.

The Pattern: What Four Generations Taught Me

Supervision beats autonomy. AI writes code fine. AI can't judge if that code fits your architecture without explicit checks. Validation at each step prevents drift better than review after the fact. APL detected problems reactively. STUDIO prevents them proactively.

Constraints beat capabilities. ORC could do more than STUDIO. STUDIO's constraints—mandatory questioning, quality gates, five challenges before execution—produce more consistent results. Limiting what AI can skip forces thoroughness.

Memory compounds value. Ephemeral sessions waste corrections. Persisting preferences means projects get smarter over time. This applies to both APL's pattern learning and STUDIO's preference rules.

Simplicity enables debugging. When ORC failed, finding which of 19 agents broke took longer than fixing the problem. Three agents means three places to look. My dev setup evolved toward this same principle—subtraction matters as much as addition.

The agent count doesn't correlate with output quality. Three supervised agents outperform 19 unsupervised ones. The supervision architecture—confidence scoring, mandatory challenges, persistent preferences—matters more than the number of specialists. This insight applies beyond coding tools to any multi-agent system architecture.

The Tradeoffs

STUDIO's supervision model has costs:

Supervision adds 30-60 seconds of latency before execution. The mandatory questioning phase, confidence scoring, and five-criteria challenge run before any code is written. For a 5-minute feature, that's 10-20% overhead. For quick fixes or single-line changes, the supervision pipeline costs more than the work itself.

Rapid prototyping doesn't fit the supervised model. When the goal is "try three approaches and see which feels right," mandatory validation gates slow exploration. Use vanilla Claude Code or APL for exploratory work. STUDIO is for execution against known requirements.

The confidence threshold (default 85%) needs per-team tuning. At 85%, STUDIO asks additional questions on roughly 40% of plans. Some teams find this too cautious; others want it higher. Tuning the threshold requires 5-10 sessions of observation to find the right balance for your codebase and risk tolerance.

The preference file grows and needs periodic pruning. After 50+ sessions, accumulated preferences can conflict—an early rule about naming conventions might contradict a later architectural decision. Quarterly review of the preferences file prevents stale rules from degrading output. The same maintenance principle applies to APL's pattern directory.

Key Takeaways

• 19 agents produce more drift than 3 supervised ones. Coordination overhead and conflicting opinions outweigh the benefits of specialization.
• Prevention beats detection. Catching drift reactively (APL) works. Preventing it proactively (STUDIO) works better.
• Confidence scoring makes uncertainty visible. You see doubt before it becomes a problem in your codebase.
• Persistent preferences create compounding quality. Each correction makes future builds more accurate. After 50 corrections, the system rarely needs intervention.
• Constraints produce better output than capabilities. Mandatory quality gates force thoroughness. Optional checks get skipped.

Install STUDIO:

claude
/plugin marketplace add https://github.com/twofoldtech-dakota/studio.git
/plugin install studio@twofoldtech-dakota
/build "your goal here"

Watch the questioning phase. See the confidence score before execution begins. That visibility—knowing the system's uncertainty before it writes code—is the difference between supervised and autonomous development.

GitHub: twofoldtech-dakota/studio

Those numbers come from APL—the Autonomous Phased Looper—a Claude Code plugin I built to handle entire features autonomously. APL plans work using Tree-of-Thoughts decomposition, executes tasks through ReAct loops, reviews its own output with Reflexion, and persists what it learns to disk. It has since shipped several production projects, including this blog.

This post covers why vanilla Claude Code stalls on complex features, how the three-phase architecture solves it, and what APL learned from building real software.

Why Vanilla Claude Code Stalls on Complex Features

Claude Code excels at individual tasks. Write a function, refactor a component, debug an error—it delivers. But complex features require coordination: understanding requirements, breaking down work, executing in sequence, and verifying results.

Running Claude Code manually for each subtask introduces friction:

• Context gets lost between sessions
• No systematic verification of completed work
• Repeated mistakes without learning
• Human bottleneck for every decision

A new feature with 15 subtasks means 15 context switches, 15 opportunities for misalignment, and no guarantee the pieces fit together. I needed a system that could operate autonomously while maintaining quality. That system also needed to integrate with specialized plugins for domain-specific tasks.

The Three-Phase Architecture

APL structures autonomous work into three distinct phases: Plan, Execute, and Review. Each phase has a specialized agent optimized for its task.

┌─────────────────────────────────────────────────────────┐
│                    APL ORCHESTRATOR                      │
└─────────────────────────┬───────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
   ┌─────────┐      ┌──────────┐      ┌─────────┐
   │  PLAN   │ ───▶ │ EXECUTE  │ ───▶ │ REVIEW  │
   │  PHASE  │      │  PHASE   │      │  PHASE  │
   └─────────┘      └──────────┘      └─────────┘
        │                 │                 │
   Tree-of-Thoughts  ReAct Loops     Reflexion
   Task Breakdown    Parallel Exec   Self-Critique

Phase 1: Planning with Tree-of-Thoughts

The planner agent receives a goal and decomposes it into a structured task list. This isn't bullet points—it uses Tree-of-Thoughts reasoning to explore multiple approaches before committing to one.

// Example task decomposition output
{
  "goal": "Add user authentication to the API",
  "tasks": [
    {
      "id": "task_001",
      "subject": "Create User model with password hashing",
      "success_criteria": [
        "User schema includes email, passwordHash, createdAt",
        "Password hashing uses bcrypt with cost factor 12",
        "Model exports TypeScript types"
      ],
      "dependencies": [],
      "parallel_safe": true
    },
    {
      "id": "task_002",
      "subject": "Implement JWT token generation",
      "success_criteria": [
        "Tokens include userId and expiration",
        "Secret loaded from environment variable",
        "Expiration set to 24 hours"
      ],
      "dependencies": ["task_001"],
      "parallel_safe": false
    }
  ]
}

The key insight: success criteria are defined upfront. The coder agent knows exactly what "done" looks like before writing a single line. This same principle—explicit completion criteria before execution—later became central to how STUDIO validates every build step.

Phase 2: Execution with ReAct Loops

The coder agent implements each task using the ReAct pattern: Reason, Act, Observe, Verify.

┌──────────────────────────────────────────────────────┐
│                    ReAct LOOP                         │
│                                                      │
│  ┌─────────┐    ┌─────────┐    ┌─────────┐         │
│  │ REASON  │───▶│   ACT   │───▶│ OBSERVE │         │
│  │         │    │         │    │         │         │
│  │ "What   │    │ Write   │    │ Check   │         │
│  │ approach│    │ code,   │    │ output, │         │
│  │ solves  │    │ run     │    │ errors, │         │
│  │ this?"  │    │ tests   │    │ results │         │
│  └─────────┘    └─────────┘    └────┬────┘         │
│                                      │              │
│                      ┌───────────────┘              │
│                      ▼                              │
│                 ┌─────────┐                         │
│                 │ VERIFY  │──── Success? ───▶ Next  │
│                 │         │                   Task  │
│                 │ Check   │                         │
│                 │ success │──── Failure? ───▶ Retry │
│                 │ criteria│                         │
│                 └─────────┘                         │
└──────────────────────────────────────────────────────┘

When independent tasks exist, APL executes them in parallel. A task graph ensures dependencies are respected while maximizing throughput.

Phase 3: Review with Reflexion

After execution completes, the reviewer agent performs self-critique using the Reflexion pattern. It examines all changes holistically:

• Do the changes satisfy the original goal?
• Are there cross-task issues (inconsistent naming, conflicting patterns)?
• Did any task introduce regressions?
• What patterns worked well? What failed?

The reviewer outputs both fixes and learning insights. Fixes trigger another execution cycle. Insights persist to the learning system.

The Self-Learning System

APL maintains a .apl/ directory in each project with accumulated knowledge:

.apl/
├── patterns/
│   ├── success/           # Approaches that worked
│   └── anti-patterns/     # Approaches that failed
├── preferences/           # User coding style preferences
├── project-knowledge/     # Project-specific context
└── session-logs/          # Execution history

Before planning, the planner agent consults this knowledge base. Before coding, the coder agent reviews relevant patterns. The learner agent extracts insights after each session.

// Example learned pattern
{
  "id": "pattern_auth_001",
  "category": "authentication",
  "title": "JWT refresh token rotation",
  "context": "When implementing JWT auth with refresh tokens",
  "pattern": "Store refresh tokens in httpOnly cookies, rotate on each use, maintain a token family for revocation",
  "why": "Prevents token theft and enables immediate revocation of compromised sessions",
  "learned_from": "session_2026-01-15_auth_impl",
  "success_rate": 0.95
}

Over time, APL becomes more effective on your specific codebase. A project with 20 sessions of accumulated patterns produces measurably better output than a fresh project—fewer retries, fewer style mismatches, faster planning. This persistence model is what separates APL from running Claude Code repeatedly. My dev setup includes tools that make these learning loops visible across sessions.

Error Handling and Recovery

Autonomous systems fail. APL handles this through three mechanisms:

Graduated Retry Logic: Simple errors (syntax, imports) retry immediately. Complex errors trigger reasoning about the failure before retry. Repeated failures escalate to the user.

Checkpointing: APL saves state after each completed task. If a session crashes, it resumes from the last checkpoint rather than starting over.

Error Categorization: Errors are classified (transient, logic, environment, unknown) to select appropriate recovery strategies.

// Error handling configuration
{
  "retry_policy": {
    "max_retries_per_task": 3,
    "backoff_strategy": "exponential",
    "escalation_threshold": 2,
    "checkpoint_frequency": "per_task"
  },
  "error_categories": {
    "syntax": { "retry": true, "backoff": false },
    "test_failure": { "retry": true, "backoff": true },
    "environment": { "retry": false, "escalate": true }
  }
}

The Plugin Architecture

APL is implemented as a Claude Code plugin—a collection of markdown files defining agents, commands, and hooks. This architecture follows patterns from the Agent Skills Standard, where specialized agents provide domain expertise through a consistent interface.

apl-autonomous-phased-looper/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   ├── apl-orchestrator.md
│   ├── planner-agent.md
│   ├── coder-agent.md
│   ├── tester-agent.md
│   ├── reviewer-agent.md
│   └── learner-agent.md
├── commands/
│   └── apl.md
└── hooks/
    └── session-end.md

Each agent is a markdown file with a system prompt defining its role, available tools, and behavior. The orchestrator coordinates the phases, delegating to specialized agents.

# Planner Agent (excerpt)

You are the APL Planning specialist. Your role is to decompose
goals into structured task lists using Tree-of-Thoughts reasoning.

## Process

1. Analyze the goal and identify key requirements
2. Generate 2-3 possible decomposition approaches
3. Evaluate each approach for completeness and parallelism
4. Select the optimal approach and output structured tasks
5. Define success criteria for each task

## Output Format

Return a JSON task list with: id, subject, description,
success_criteria[], dependencies[], parallel_safe

Results

APL has handled dozens of features across multiple projects. The measured results:

The self-learning compounds over time. APL on a mature project (20+ sessions) outperforms APL on a new one because it has internalized the patterns—which frameworks to use, how to structure tests, what naming conventions the project follows.

The Tradeoffs

APL isn't free. Here's what it costs:

Token consumption runs 3-5x higher than manual Claude Code usage. The planning phase alone generates thousands of tokens exploring approaches. For a feature that costs $0.50 in manual prompts, APL runs $1.50-$2.50. The ROI is positive for features with 5+ subtasks, but negative for small changes.

Exploratory coding doesn't fit the phased model. APL needs clear goals with definable success criteria. If you're experimenting—"try this approach, see if it feels right"—the rigid Plan-Execute-Review cycle adds overhead without value. Use vanilla Claude Code for exploration, APL for execution.

Cold starts on new projects are slow. With no .apl/ knowledge base, the first session relies entirely on the planner's general knowledge. Patterns that APL would catch on a mature project (naming conventions, test structure, import paths) require manual correction on a fresh project.

The .apl/ directory requires periodic maintenance. Learned patterns accumulate without pruning. After 30+ sessions, outdated patterns can conflict with newer ones. A quarterly review of .apl/patterns/ prevents stale knowledge from degrading output quality.

Key Takeaways

• Structure beats prompting. A well-designed workflow with clear phases outperforms a single clever prompt. Each agent does one thing well.
• Success criteria are everything. Defining "done" upfront eliminates ambiguity and enables automated verification.
• Learning requires persistence. Ephemeral sessions waste insights. Persisting patterns to disk creates compounding value.
• Humans remain in the loop. APL escalates uncertainty rather than guessing. Autonomy doesn't mean unsupervised.
• Token cost is the price of autonomy. The 3-5x token increase buys structured execution. For complex features, it's worth it. For quick fixes, it isn't.

APL is open source. Install it:

/plugin install apl-autonomous-phased-looper@apl-marketplace

Then run:

/apl Build a REST API with user authentication

Watch the phases unfold. Check the .apl/ directory to see what it learns. The code is on GitHub: twofoldtech-dakota/apl

Autonomous coding removes the friction between intent and implementation. APL handles the mechanical work—planning subtasks, writing boilerplate, running tests, fixing lint errors—so I focus on architecture and product decisions. Four generations of iteration later, this foundation became STUDIO, which adds supervision and confidence scoring on top.

That's the ROI math behind every Claude Code customization in this setup. Boris Cherny, the creator of Claude Code, describes his setup as "surprisingly vanilla." Mine is the opposite: multi-machine hardware, 5 MCP servers, and custom skills that turn Claude Code into an autonomous development partner. I built APL, a CMS analysis marketplace, and STUDIO. Claude Code now handles entire features while I review the output.

The Multi-Machine Setup

The common thread: Cursor runs on all three. Having a consistent editor across machines reduces friction when switching contexts. Cursor handles inline completions while Claude Code tackles larger tasks—complementary tools, not competing ones.

Terminal and Shell

iTerm2 + Zsh + Oh My Zsh

# Key Oh My Zsh plugins
plugins=(
  git
  zsh-autosuggestions
  zsh-syntax-highlighting
)

The autosuggestions plugin alone saves hours per week. Type a few characters, hit right arrow, command complete. Syntax highlighting catches typos before execution.

I haven't switched to Warp, Ghostty, or other modern terminals. iTerm2 handles everything I need: split panes, search, profiles per project. New tools need to offer substantial improvement to justify switching costs—a principle that applies to choosing any tool in the AI dev ecosystem.

Editor: Cursor + Claude Code

Cursor started as a VS Code fork with AI features. It's matured into an editor designed around AI-assisted development. Key advantages over vanilla VS Code:

• Tab completion that understands context: Cursor's completions consider your entire codebase, not isolated files
• Inline edits with Cmd+K: Describe a change, see the diff, accept or reject
• Composer for multi-file changes: When a task touches several files, Composer handles the coordination

Cursor and Claude Code complement rather than compete:

The boundary isn't rigid. Match the tool to the task.

Claude Code Configuration

Here's where the setup diverges from vanilla.

MCP Servers

Five MCP servers extend Claude Code's capabilities:

Each server eliminates a context switch. Without GitHub MCP, every PR review requires switching to a browser. Without Database MCP, every schema question requires a separate terminal. Five servers, five fewer reasons to leave Claude Code.

Custom Skills and Hooks

Beyond MCPs, custom skills and hooks transform the workflow:

Skills (slash commands)

The /meta command alone transformed my workflow. Instead of manually orchestrating Claude Code through 15+ subtasks, I describe the goal and watch the phases unfold:

# Before APL: 15-20 manual prompts per feature
> "Create the user model"
> "Now add the authentication middleware"
> "Now write tests for the auth flow"
> "Now fix that import error"
> ...repeat 15 times...

# After APL: one command
> /meta Add user authentication with JWT tokens
# APL handles: planning, coding, testing, review, learning

Hooks automate session boundaries:

• Session end hooks trigger learning extraction to .apl/patterns/
• Pre-commit hooks run validation
• Context-gathering hooks populate project state on session start

Building skills follows the Agent Skills Standard, which defines a consistent interface for composable, shareable automation. The power user guide covers the architecture in depth.

The APL Workflow in Practice

APL is the centerpiece of my Claude Code customization. Here's how it fits daily work:

Morning: Review overnight changes, check APL session logs in .apl/session-logs/ Feature work: /meta with goal description, monitor progress, answer escalation questions Code review: APL's reviewer catches issues before I see the PR Learning: Insights persist to .apl/ for future sessions

The workflow isn't "fire and forget." I monitor active sessions, answer escalation questions, and review decisions. The mechanical work—boilerplate, tests, lint fixes—happens autonomously. APL built this entire blog using that workflow: 47 stories, 6 sessions, 2 hours of human input.

Design Workflow with Pencil.dev

Pencil.dev closes the design-to-code loop:

1. Design first: Create the component in Pencil's canvas
2. Generate code: Claude Code reads the design via MCP, generates React/Tailwind
3. Verify visually: Compare implementation to design in Pencil

No more "it looks different than the mockup" conversations. The mockup and the code stay synchronized. For this blog, Pencil handles component design before implementation, visual regression checking, and design system consistency verification.

What I Removed

The setup evolved through subtraction:

Each removal reduced cognitive load. The best tools are invisible—they don't demand attention.

The Tradeoffs

Heavy customization carries specific costs:

Customization creates friction in shared environments. My config includes 5 MCP servers, custom skills, and APL-specific hooks. Pairing on another developer's machine means working without these tools—or spending 20 minutes installing them. For teams, the customization tax is real. Shared skills need documentation; personal ones don't.

Multi-machine sync is manual and that's a deliberate choice. I don't use a dotfiles repo. Settings sync is ad-hoc: copy what I need, when I need it. The friction of maintaining sync scripts outweighs occasional manual copies when switching machines daily at most. If you switch machines hourly, invest in proper dotfiles.

APL creates platform lock-in. The .apl/ directory, learned patterns, and phased workflow are specific to Claude Code. Switching to a different AI coding tool means abandoning accumulated project knowledge. For projects with 20+ APL sessions of learned patterns, that's a significant switching cost.

5+ MCP servers require documentation for onboarding. Each server has configuration requirements, authentication setup, and interaction patterns. New team members need a guide explaining what each MCP provides and how they compose. Without documentation, the setup is opaque.

Key Takeaways

• Customize Claude Code aggressively. The "vanilla is fine" approach works for basic tasks. Skills, hooks, agents, and MCPs enable workflows that weren't possible before.
• ROI math justifies every customization. 30 minutes to build, 5-10 minutes saved per use, 10+ uses per week = one-week breakeven. Track it.
• Multi-machine setups work without elaborate sync. Match the tool to the task, accept manual sync, and move on.
• Cursor and Claude Code complement each other. Cursor for inline completions and small edits. Claude Code for multi-file features and autonomous development.
• Subtraction matters as much as addition. Every removed tool reduces cognitive load. The best tools are invisible.

The trend is clear: AI tooling rewards customization. Build the workflow that matches how you think, not the workflow the defaults provide. Start with Skills if you haven't explored them—they're the lowest-friction entry point to reshaping Claude Code around your workflow.

Enterprise CMS platforms—Sitecore, Umbraco, Optimizely—have steep learning curves and platform-specific patterns. Running a general-purpose linter on a Sitecore codebase produces noise: valid Helix architecture patterns flagged as issues, hardcoded GUIDs missed entirely, pipeline processor ordering problems invisible to generic tools, and XM Cloud migration blockers undetected. Enterprise teams need analysis that speaks their platform's language.

So I built a curated marketplace of specialized Claude Code plugins, each loaded with platform-specific expertise. The plugin architecture enables specialized agents to operate autonomously, following the same phased patterns used in APL's multi-agent orchestration.

Why Generic Linters Fail on Enterprise CMS Platforms

Generic code analysis tools optimize for language-level patterns—unused variables, potential null references, formatting violations. CMS platforms operate at a higher abstraction layer:

• Architecture violations require platform knowledge. Sitecore's Helix architecture enforces strict layer separation (Foundation → Feature → Project). A generic linter sees a valid C# reference. A Sitecore specialist sees a cross-layer dependency that breaks the entire module boundary.
• Configuration patterns are platform-specific. Hardcoded GUIDs, pipeline processor ordering, serialization configurations—these have meaning only within the CMS context.
• Migration blockers need version-aware detection. Moving from Sitecore Classic to XM Cloud requires identifying on-premise-only APIs, server-side rendering dependencies, and incompatible pipeline configurations.

A general agent can't know that Glass Mapper over-fetching is a Sitecore-specific anti-pattern, or that Umbraco content apps have specific registration requirements. Platform depth beats breadth.

The Marketplace Architecture

Rather than one monolithic tool, the marketplace offers platform-specific analyzers as standalone plugins:

claude-marketplace/
├── analyzers/
│   ├── sitecore-classic/     # Sitecore 10.x on-prem
│   ├── xm-cloud/             # Sitecore XM Cloud
│   ├── umbraco/              # Umbraco 14-16
│   ├── optimizely-cms/       # Optimizely CMS 12
│   └── optimizely-exp/       # Optimizely Experimentation
└── shared/
    ├── security-rules/       # Cross-platform security checks
    └── performance-rules/    # Common performance patterns

Teams install only what they need. This follows the same principle behind the Agent Skills Standard—composable, specialized capabilities instead of monolithic tooling.

Plugin Anatomy

Each analyzer plugin follows a consistent structure:

sitecore-classic/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── analyze.md            # Full codebase analysis
│   ├── security-scan.md      # Security-focused scan
│   └── setup.md              # Initial configuration
├── agents/
│   └── sitecore-expert.md    # Platform-specialized agent
├── skills/
│   ├── helix-patterns.md     # Helix architecture knowledge
│   ├── pipeline-analysis.md  # Pipeline processor expertise
│   └── template-review.md    # Template/rendering analysis
└── rules/
    ├── architecture.json     # Helix compliance rules
    ├── security.json         # Security vulnerability patterns
    └── performance.json      # Performance anti-patterns

The Expert Agent

Each analyzer includes a specialized agent with deep platform knowledge. The Sitecore expert agent, for example, knows Helix layer separation, dependency direction enforcement, serialization patterns (Unicorn, TDS, SCS), and common anti-patterns like cross-layer dependencies and Glass Mapper over-fetching.

# Sitecore Expert Agent (excerpt)

You are a Sitecore 10.x architecture specialist with expertise in:

## Helix Principles
- Foundation, Feature, Project layer separation
- Dependency direction (Project → Feature → Foundation)
- Module boundary enforcement
- Serialization patterns (Unicorn, TDS, SCS)

## Common Anti-Patterns
- Cross-layer dependencies (Feature referencing Project)
- Business logic in renderings
- Hardcoded item paths instead of queries
- Missing null checks on Sitecore.Context
- Glass Mapper over-fetching

Rule Definitions

Rules are defined in JSON with severity, detection patterns, and remediation guidance:

{
  "rules": [
    {
      "id": "SC001",
      "name": "Cross-Layer Dependency",
      "severity": "error",
      "category": "architecture",
      "description": "Feature layer must not reference Project layer",
      "detection": {
        "type": "reference_analysis",
        "pattern": "Feature.*/.*references.*Project.*"
      },
      "remediation": "Move shared functionality to Foundation layer or refactor the dependency direction",
      "documentation": "https://helix.sitecore.com/principles/architecture-principles/layers.html"
    },
    {
      "id": "SC002",
      "name": "Hardcoded Item GUID",
      "severity": "warning",
      "category": "maintainability",
      "description": "Item GUIDs should be centralized in constants",
      "detection": {
        "type": "pattern",
        "regex": "new ID\\([\"'](\\{?[0-9a-fA-F-]{36}\\}?)[\"']\\)"
      },
      "remediation": "Extract GUID to a constants class in the appropriate Foundation module"
    }
  ]
}

The Analysis Workflow

Running an analysis produces a structured markdown report:

/sitecore-classic:analyze

The report includes severity breakdown, critical issues with exact file locations, remediation guidance with links to documentation, and a full architecture dependency graph. Here's a representative output:

# Sitecore Classic Analysis Report

**Project:** Acme.Website
**Analyzed:** 2026-01-24 14:32 UTC
**Files Scanned:** 847
**Issues Found:** 23

## Summary

| Severity | Count |
|----------|-------|
| Critical | 2     |
| Error    | 7     |
| Warning  | 14    |

## Critical Issues

### SC-SEC-001: Hardcoded Connection String
**Location:** src/Foundation/Database/App_Config/ConnectionStrings.config:12
**Details:** Production database credentials in source control
**Remediation:** Move to environment variables or Azure Key Vault

### SC-SEC-003: Exposed Admin Endpoint
**Location:** src/Project/Website/Controllers/AdminController.cs:1
**Details:** /api/admin/* endpoints lack authorization attributes
**Remediation:** Add [Authorize(Roles = "sitecore\\Admin")] attribute

Safe Mode for Sensitive Codebases

Enterprise teams worry about sending proprietary code to AI systems. Safe mode addresses this:

/sitecore-classic:analyze --safe-mode

In safe mode, the analyzer:

1. Reads file paths and structure only (not file contents)
2. Analyzes project references and dependencies
3. Checks configuration file names (not values)
4. Reports structural issues without exposing code

## Safe Mode Analysis

**Note:** Content analysis disabled. Structural findings only.

### Project Structure
- 3 Project layer modules detected
- 12 Feature layer modules detected
- 4 Foundation layer modules detected

### Dependency Graph Issues
- Feature.Navigation references Project.Website (Helix violation)
- Missing Foundation.DependencyInjection reference in 3 Features

### Configuration Concerns
- ConnectionStrings.config present in source (verify secrets handling)
- 2 modules missing Unicorn serialization configuration

Safe mode catches approximately 40% of the issues that a full analysis finds. The remaining 60% require content inspection—code patterns, hardcoded values, logic anti-patterns. For security-conscious teams, safe mode serves as a first pass. Full analysis can follow in a controlled environment.

CI/CD Integration

The analyzers integrate into build pipelines for automated enforcement:

# Azure DevOps example
- task: Bash@3
  displayName: 'Run Sitecore Analysis'
  inputs:
    targetType: 'inline'
    script: |
      claude-code /sitecore-classic:analyze --output ./analysis-report.md

      # Fail build on critical issues
      if grep -q "Critical" ./analysis-report.md; then
        echo "##vso[task.logissue type=error]Critical issues found"
        exit 1
      fi

Pull requests get automated analysis comments. Critical issues block merges. This mirrors the same CI/CD philosophy used in this blog's content validation pipeline—automated gates that catch problems before they reach production.

Platform Coverage

The marketplace currently includes five analyzers:

Each analyzer averages 50 platform-specific rules across architecture, security, performance, and maintainability categories. The shared rule sets add cross-platform security checks and common performance patterns.

The Tradeoffs

Specialized plugins carry specific costs:

Rule maintenance scales per platform version. Each major CMS release requires rule review and updates. Sitecore's XM Cloud evolution alone generated 12 rule changes in three months. For teams tracking multiple platforms, the maintenance burden compounds. Budget 2-4 hours per platform per major release for rule updates.

Small projects don't justify the overhead. For codebases under 10K lines of code or greenfield projects without established patterns, the marketplace adds complexity without proportional value. A general-purpose linter suffices until the codebase grows enough to accumulate platform-specific patterns.

False negatives are the hidden risk. Missing a rule is worse than a false positive. If the analyzer doesn't flag a cross-layer dependency, the team assumes the architecture is clean. Regular rule audits against the latest platform documentation mitigate this, but gaps exist—especially for newer platform features.

Safe mode provides a fraction of full analysis. The ~40% detection rate means teams relying exclusively on safe mode miss the majority of issues. Safe mode works as a gate, not a replacement. My dev setup includes both modes in a staged pipeline—safe mode in CI, full analysis in local development.

Key Takeaways

• Domain expertise compounds. A specialized agent with 50 platform-specific rules outperforms a general agent with 500 generic rules. Depth beats breadth for CMS analysis.
• Safety enables enterprise adoption. Safe mode removed the primary objection from security teams. Address their concerns first, and capability conversations follow.
• Plugin architecture enables composition. Teams install only what they need. Adding a new CMS platform follows the same structure—no monolith, no bloat.
• CI/CD integration is table stakes. Analysis that runs only on-demand gets skipped. Automated pipeline integration ensures every change gets reviewed.
• Markdown is infrastructure. The entire plugin—agents, commands, rules—is markdown and JSON. No build process, no compilation. Edit and reload. This simplicity enabled APL to build complex projects using the same plugin patterns.

The marketplace is open source: twofoldtech-dakota/claude-marketplace

Install it:

/plugin marketplace add https://github.com/twofoldtech-dakota/claude-marketplace
/plugin install sitecore-classic@claude-marketplace
/sitecore-classic:setup

Contributions welcome. Each analyzer follows the same structure, so adding a new platform (Kentico, Contentful, Sanity) is straightforward. CMS development doesn't have to mean fighting the platform—specialized analysis turns Claude Code into a team member who understands your architecture, powered by the same supervision principles that keep autonomous agents aligned.

The blog you're reading was built by APL—the Autonomous Phased Looper. I wrote a spec document defining the architecture, design system, and performance targets. APL planned the work, executed it across six sessions, and reviewed its own output. Here's the full breakdown of what that looked like, where APL needed help, and what the numbers reveal about autonomous development.

The Spec: What APL Received

APL started with a CLAUDE.md file containing:

• Next.js 16 with App Router and SSG
• Neo-brutalist dark design (thick borders, hard shadows, no rounded corners)
• MDX content with advanced code highlighting via Shiki
• Lighthouse scores of 98+ across all categories
• WCAG 2.1 AA accessibility compliance
• Giscus comments, Vercel Analytics, Schema.org structured data

The spec included color values (#0A0A0A background, #F5F5F5 text, #333333 surface), typography rules (Space Grotesk, 400/600/700 weights), performance targets (LCP < 2.0s, CLS < 0.05), and content structure (MDX files in /content/posts/ with specific frontmatter schema). Everything APL needed to make decisions without asking.

Spec quality determines output quality. Vague specs produce vague code. The CLAUDE.md ran 400+ lines because every ambiguous decision was resolved upfront.

Planning: 6 Epics, 47 Stories

Using APL's Tree-of-Thoughts planning, I ran:

/apl Build the complete blog according to CLAUDE.md

The planner decomposed the project into six epics with dependency analysis:

Epic 1: Foundation & Project Setup         (5 stories)
Epic 2: Advanced Code Highlighting System   (4 stories)
Epic 3: Core UI Components & Design System  (8 stories)
Epic 4: Blog Pages & Content Display        (7 stories)
Epic 5: SEO, Analytics & Comments           (7 stories)
Epic 6: Performance Optimization            (11 stories)  ← 5 more stories than any other epic

The task graph identified parallelization opportunities:

Epic 1 ────────────────────────────────────────┐
   │                                            │
   ├── Epic 2 (parallel) ─────────────────────┐│
   │                                           ││
   └── Epic 3 ──── Epic 4 ──── Epic 5 ──── Epic 6

Epic 2 (code highlighting) had no dependencies on Epic 3 (UI components) and could run in parallel. Each story had explicit success criteria—the same pattern that STUDIO later formalized with mandatory validation commands per step.

{
  "id": "story_3_04",
  "subject": "Build BlogCard component with neo-brutalist styling",
  "success_criteria": [
    "Component renders title, excerpt, date, tags",
    "4px solid border with #333333 color",
    "Hard shadow offset (4px, 4px) with no blur",
    "Hover state with color transition",
    "Keyboard focusable with visible focus ring",
    "Passes axe accessibility audit"
  ]
}

Execution: Epic by Epic

Epics 1-2: Foundation and Code Highlighting

The coder agent initialized the Next.js project, configured TypeScript strict mode, set up Tailwind with custom design tokens, and installed the MDX pipeline. The Tailwind config encoded the spec's design system:

// Generated by APL - tailwind.config.ts
const config: Config = {
  theme: {
    extend: {
      colors: {
        background: '#0A0A0A',
        surface: '#333333',
        text: '#F5F5F5',
        muted: '#A9A9A9',
      },
      fontFamily: {
        sans: ['Space Grotesk', 'sans-serif'],
      },
      boxShadow: {
        'brutal': '4px 4px 0px 0px #333333',
        'brutal-hover': '6px 6px 0px 0px #333333',
      },
    },
  },
};

The Shiki integration required the ReAct loop to self-correct. APL's first attempt used rehype-pretty-code, but the line highlighting syntax conflicted with MDX processing:

REASON: rehype-pretty-code throws "Unexpected token" on line highlights
ACT: Switch to direct Shiki integration with custom rehype plugin
OBSERVE: Syntax highlighting works, line numbers render correctly
VERIFY: ✓ Code blocks highlight, ✓ Line numbers visible, ✓ Diff syntax works

The fix took one retry cycle. APL switched to direct Shiki integration and validated all three success criteria before moving on.

Epics 3-4: UI Components and Pages

Epic 3 produced 12 components with neo-brutalist constraints. Every component included focus states because the spec mentioned WCAG compliance and the success criteria included "keyboard focusable with visible focus ring":

// Generated by APL - components/ui/Button.tsx
export function Button({ children, variant = 'primary', onClick }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      className={cn(
        'px-6 py-3 font-semibold border-4 border-surface',
        'shadow-brutal hover:shadow-brutal-hover',
        'transition-shadow duration-150',
        'focus:outline-none focus:ring-2 focus:ring-text focus:ring-offset-2 focus:ring-offset-background',
        variant === 'primary' && 'bg-text text-background',
        variant === 'secondary' && 'bg-background text-text'
      )}
    >
      {children}
    </button>
  );
}

Epic 4 wired the components into pages. The blog listing and individual post pages connected through the MDX pipeline with static generation:

// Generated by APL - app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

Epics 5-6: SEO, Analytics, and Performance

APL generated Schema.org JSON-LD for BlogPosting, BreadcrumbList, and Person types. Giscus integration used IntersectionObserver for lazy loading—exactly as the spec prescribed.

The performance epic contained 11 stories, the largest epic. APL ran Lighthouse audits after each optimization:

Lighthouse (pre-optimization):     Lighthouse (post-optimization):
- Performance: 89                  - Performance: 99
- Accessibility: 100               - Accessibility: 100
- Best Practices: 100              - Best Practices: 100
- SEO: 100                         - SEO: 100

Issues identified and resolved:
- LCP 2.4s → 1.2s (hero image priority prop)
- 12KB unused CSS → 0 (Tailwind purge)
- Font render delay → 0 (next/font preloading)
- Layout shift → 0.02 CLS (blur placeholders)

The Review Phase

After execution, the reviewer agent examined all changes holistically:

## Review Summary

### Cross-Task Issues Found: 2
1. Inconsistent import paths (some relative, some alias)
   - Fixed: Standardized to @/ alias throughout

2. Missing error boundary on Comments component
   - Fixed: Added ErrorBoundary wrapper

### Patterns Learned
- Neo-brutalist focus rings: ring-2 ring-text ring-offset-2 ring-offset-background
- Lazy loading threshold: rootMargin 100px works well for comments
- Image priority: Always set priority={true} on above-fold hero images

### Regressions: None detected

The learner agent persisted these insights to .apl/patterns/ for future projects. The neo-brutalist focus ring pattern alone saved time on every subsequent component built with APL.

Where APL Needed a Human

APL isn't fully autonomous. I intervened for:

Design decisions the spec left open. The spec said "accent color TBD." I picked the specific neon green after seeing the dark theme in context. APL can't make aesthetic judgments—it needs concrete values.

Content creation. APL scaffolded the MDX files with correct frontmatter, but I wrote the actual posts. Content requires judgment about what to say and why it matters.

API keys and deployment config. Giscus repo ID, Vercel project settings, domain configuration—APL prompted me to provide these at the right moments.

Image assets. Thumbnails and hero images required human creation. APL sized the placeholders correctly but couldn't produce the visual content.

Total human time: approximately two hours across the entire build. Most of that was content, images, and design decisions—not code.

The Numbers

Eight errors across 47 stories is a 17% retry rate. All eight were resolved within APL's retry budget (3 attempts per task). No story required human debugging.

The Tradeoffs

This project demonstrates both the strengths and costs of autonomous development:

Token cost for 6 sessions adds up. Each epic-length APL session consumes 3-5x the tokens of manual Claude Code usage. Six sessions for the full blog build cost meaningfully more than a skilled developer prompting Claude Code interactively. The ROI works because APL handles coordination—47 stories with dependency tracking—not because it's cheaper per token.

Spec quality is the bottleneck, not agent capability. The 400-line CLAUDE.md took significant upfront effort. APL's output quality tracked the spec's specificity. Sections with precise values (color codes, shadow offsets, font weights) produced correct output on the first pass. Sections with vague guidance ("accent color TBD") required human intervention. The two-hour figure excludes spec-writing time.

Experimental UIs don't fit the autonomous model. APL works when success criteria are measurable: "4px border," "Lighthouse 99," "keyboard focusable." For design-first projects where the goal is "try this layout, see if it feels right," the phased model adds overhead without value. My dev setup separates these workflows—APL for execution, Pencil.dev for design exploration.

Review phase catches integration issues, not architectural problems. APL's reviewer found inconsistent imports and a missing error boundary. It did not question whether the overall architecture was optimal. Architectural decisions were locked in at spec time. For projects where the architecture is uncertain, the autonomous model is the wrong tool. STUDIO addresses this gap with its mandatory questioning phase before execution begins.

Key Takeaways

• Autonomous coding works for spec-driven projects. A detailed spec with measurable success criteria produces working software with minimal human intervention.
• 47 stories, 6 sessions, 2 hours human time. The ratio demonstrates that coordination—not individual task execution—is where autonomous agents add the most value.
• Lighthouse 99 without manual optimization. Performance targets in the spec translated directly to optimization stories with verifiable criteria.
• Spec investment pays for itself. The upfront cost of a thorough spec is repaid by reduced iteration cycles. Garbage in, garbage out applies to autonomous agents more than it does to manual development.
• Humans remain essential for judgment. Design aesthetics, content strategy, and architectural tradeoffs require human input. APL handles the mechanical translation from spec to code.

Try APL yourself: twofoldtech-dakota/apl

The blog is proof that autonomous development works—not for everything, but for translating clear specs into working software. The same Skills architecture that powers APL's commands can automate any repeatable workflow, from CMS analysis to content validation pipelines.