Blog¶

June 11, 2026
14 min read

Cloud Native & Open Source AI Conference — Notes

These are my working notes from the sessions I attended.

The throughline across almost everything was the same tension platform teams have been sitting with for months: agents are genuinely useful, and making them safe to run at enterprise scale is harder than anyone wants to admit. Every speaker who touched on agentic workloads eventually arrived at the same place — governance isn't the constraint on adoption, it's the prerequisite for it. The Kafka session was the exception. That was about a completely different kind of complexity.

I'm not going to reproduce every bullet. What follows is what actually landed, what I'm thinking about differently, and what I'd do next week.

Keynote: Kubernetes, Headlamp, and Agentic Governance

Andrew Randall, Pal Lakatos-Toth — Microsoft

The keynote opened with a reflection on why Kubernetes won. The answer wasn't "better technology". It was better technology and a genuinely open, inclusive community. Both. Neither on its own.

That framing mattered more than it sounds. Because the second half of the keynote was about agentic workloads on Kubernetes, and the same logic applies. You don't make agents safe by picking the right model. You make them safe by building the right community of practice around them — and that starts with governance engineers actually trust.

On the UX side: Headlamp is now the official upstream Kubernetes UI. SIG UI has deprecated the previous dashboard. Multi-cluster visibility, a plugin model, a desktop app — real answers to onboarding friction, not cosmetic improvements. If you have engineers who avoid the CLI because it's overwhelming, Headlamp is worth a proper evaluation before the end of the quarter.

The demo that stuck with me was the agentic governance piece. CRD-driven controls specifying which tools an agent can call, what it can't do without operator approval, and how it routes through an inference policy before touching anything. Not "prompt the agent to be careful". Enforce it. Rate limits, budget controls, egress constraints — all expressed as Kubernetes resources. The agent proposes a fix, the operator approves, the controller reconciles. That's the loop you want.

The governance pattern that actually works

Tool policy, inference policy, runtime definition — all expressed as Kubernetes CRDs running live on-stage. The agent can still be useful. It just can't be reckless. The key distinction: separate agent autonomy from agent authority. Autonomy is what the agent decides to do. Authority is what it's actually permitted to do. Enforce the latter with policy, not prompts.

What to do next: - Evaluate Headlamp as your default multi-cluster UI in a lab before rolling it out broadly - Map one platform workflow that could become a CRD-backed agent contract - Define your minimum governance baseline: tool policy, inference policy, workload identity, audit trail - Build development and validation loops on kind before managed-cluster rollout

The Massively Parallel Agent Stack

Peter Bhabra — Doubleword

This was the talk I'd been hoping to see. Not "here's a demo where the agent writes code". But "here's why one giant agent is the wrong shape for this problem".

The use case was a security audit across a reasonably sized codebase — 512 files, roughly 2.5 million tokens of source. The single-agent approach burned through context, churned, and delivered weak coverage. You've probably seen this: the agent gets increasingly confused about what it's already seen and starts generating output that's plausible but thin.

The swarm approach worked differently. An orchestrator decides team composition and carves up the work. Specialist workers — each with a clear, bounded role like "find injection patterns" or "check unsafe file access" — process their slices in parallel. They return structured, schema-bound outputs. And critically: an independent verifier reviews each finding before it's included. A dedicated synthesiser then turns verified findings into an actionable report.

Better coverage, lower token cost. And the same runtime can be repointed at completely different use cases just by swapping prompts, schemas, and tools. The economic model for background audits is asynchronous inference — you don't need low-latency responses for something that runs overnight.

Context window size is not the same as coverage quality

Bigger context doesn't mean the agent sees more clearly — it often means it sees everything less clearly. The parallel worker approach isn't just about speed. It's about keeping each worker's context small, specific, and focused. A verifier stage before surfacing findings to engineering backlogs isn't optional. It's how you avoid noisy or hallucinated issues becoming real tickets.

What to do next: - Prototype a small swarm runtime for one internal use case — dependency review or secret scanning are good starting points - Define a minimal findings schema now (severity, confidence, file path, evidence, recommendation) before you need one - Add an independent verifier stage before creating issues in engineering backlogs - Benchmark single-agent vs swarm on the same repository with the same acceptance criteria

Silent Interpretation Errors at Scale

Maebh Booth — Senior Engineering Leader

This talk named something that's been quietly frustrating platform teams for months. Not "the agent failed" — but "the agent succeeded at the wrong thing and didn't mention it".

The term is silent interpretation drift. The agent makes an implicit decision, picks an interpretation, and moves forward without surfacing the ambiguity. It doesn't ask. It just gets on with it, because forward motion is what it's optimised for. The output often looks correct — tests pass, the prose is coherent — but it's missing something you specified, or it assumed something you didn't. At enterprise scale, across many teams and shared workflows, those small errors compound fast.

Her recommended controls are practical. Intent-based skills that route on cognitive operation rather than exact phrasing. Explicit "stop and ask" rules before agents commit inferred IDs, config defaults, or assumed paths. Deterministic pre-commit hooks that block known-bad patterns — not advisory, hard gates. And telemetry. Without transcript instrumentation and periodic evaluation, you can't prove your guardrails are working. You can only hope they are.

The point that landed hardest: require agents to bundle all their clarifications and ask them once, not interrupt five times mid-task. It sounds small. It changes the interaction model completely.

Soft prompts can't do the job of hard gates

Advisory guidance helps at the margins. But for anything high-impact — inferred paths, assumed IDs, hard-coded values — you need deterministic enforcement. One gate plus one measurable evaluation beats ten advisory skills with no feedback loop.

What to do next: - Audit current agent workflows for recurring overreach: assumed values, invented constants, ignored constraints - Add one explicit "stop and ask" gate for inferred values in a critical repository this week - Add push-time metrics for skill activation and non-compliance events - Schedule a weekly evaluation pass to catch behavioural drift before it compounds

Prompt-Driven Platforms: The Future of Self-Service Infrastructure

Salman Iqbal, Amir Tayabali — Wayfinder

Good demos are easy. Safe, repeatable, enterprise-wide adoption in high-security environments is the hard bit. That's where this talk lived, and it was more honest about the difficulty than most.

The central tension: give agents enough context and access to be genuinely useful, while still enforcing controls that security and compliance teams can audit. In locked-down environments, prompt conventions and local settings don't cut it. You need a gateway, a wrapper, and explicit trust boundaries — not because you distrust the AI, but because you need to explain what happened when something goes wrong.

The shadow IT angle was sharp. If platform teams don't provide a safe, easy path for AI tooling, engineers will build their own. And those homegrown setups won't have the governance controls you spent months designing. The paved road has to be genuinely paved — not a traffic cone maze that takes twenty minutes to navigate.

Context quality came up as a force multiplier. Teams getting the best agent outputs weren't just using better prompts. They were surfacing richer service-catalog metadata through Backstage. Who owns this service? What does it depend on? What are the constraints? When the agent has that context, it makes better decisions. When it doesn't, it guesses.

If you don't build the paved road, engineers will build their own

Shadow AI is the enterprise equivalent of shadow IT. It happens when the unofficial path is easier than the official one. Gateway enforcement and wrapper-based tool launch aren't bureaucracy — they're what lets you say "yes, use it" rather than "use it and good luck".

What to do next: - Map every current AI access path and identify which ones bypass policy controls - Pilot gateway-mediated model access in one team before broader rollout - Invest in service-catalog metadata quality — it's a force multiplier for agent output quality - Publish a small set of platform-curated skills and track actual adoption

Controlling AI Agent Access in Cloud-Native Engineering Workflows

Viola Lykova — nuclecode

The clearest reframe of the day: agent access control is a platform engineering problem, not a prompt engineering problem.

The moment agents move from autocomplete to autonomous action — triggering CI, opening PRs, mutating infrastructure — they become execution actors. And execution actors need the same rigour as human privileged access. The problem isn't that agents are malicious. It's that their scope tends to expand quietly over time. You add a tool. You widen a token scope. You give them access to production "just for diagnostics". Three months later you're looking at a token with write permissions across five services that was originally scoped to read-only logs.

Drift is the word she used. Not a single bad decision, but incremental scope expansion that's hard to notice until you audit it. And without continuous drift detection, you won't audit it until something goes wrong.

The state mutation framing matters. Every tool call can change platform reality. Every API call is evidence. The discipline is: explicit permission contracts, scoped tokens per tool per action class, approval checkpoints for high-risk changes, and forensic audit trails that attach actor, scope, rationale, and approval metadata to each meaningful mutation. Prompts can influence behaviour. They are not security boundaries.

A prompt is not a permission boundary

Natural-language instructions guide what an agent wants to do. Tokens, scopes, and policy enforcement determine what it can do. These are not the same thing, and treating them as equivalent is how you end up with an agent that's polite about exceeding its authority.

What to do next: - Create an agent access inventory: tool, token, scope, owner, environment — even a spreadsheet works to start - Replace broad shared credentials with purpose-specific scoped tokens per tool and action class - Add policy checks that block scope increases without explicit approval - Define and test rollback paths for high-impact mutations before you need them in production

Platform as a Product: What Happens When We Treat Security as a User?

Hannah Foxwell — Bimp

If your platform team genuinely builds "platform as a product" but security teams are still downstream reviewers rather than first-class users, you're not actually doing it.

That's the core provocation, and it landed. Developer experience has received enormous investment over the last few years — golden paths, self-service, reducing friction. Security teams have largely been left with manual triage queues that don't scale with the pace of discovery. And the AI-era wrinkle makes this worse: vulnerability discovery is accelerating. AI-assisted scanning will find more CVEs, faster. Traditional human-only triage is already approaching its limits, and we're at the beginning of the curve, not the middle.

The practical moves aren't glamorous but they're achievable. Filter and correlate findings before they hit human queues. Surface ownership metadata on every finding so the right team gets the right alert. Add runtime environment and data sensitivity to guide prioritisation urgency. Automate the obvious patches — not everything, just the changes with high confidence and low blast radius. That alone removes a significant chunk of the toil and lets security teams focus on the decisions that actually require human judgment.

Security teams are platform users — run the same discovery with them

Interview your security team the way you'd interview developers for user research. Map their current pain in your platform workflows. The gap between what security teams need and what platform teams have built for them is often embarrassingly wide, and most of it is fixable once you can see it clearly.

What to do next: - Run one user research session with your security team, treating them as platform users - Add ownership and impact metadata to every service and surface it in security findings - Pilot one automated remediation workflow for a high-frequency, low-risk vulnerability class - Define a response playbook for high-severity disclosures and rehearse it before you need it

Beyond the Portal: AI-Native Platforms with CNOE and MCP

Hossein Salahi

The portal isn't dead. But it's no longer the only surface that matters, and for some users it was never quite the right one.

That's the honest read of this talk. Portals did useful work: they standardised self-service and gave platform teams a way to offer repeatable workflows without writing a Slack bot for everything. But for operational users — SREs, incident responders, people who are in a terminal or a chat window when something is on fire — a static form wizard is the wrong shape.

The CNOE/MCP model being shown here is additive, not a replacement. Your existing GitOps, policy controls, and capability planes stay exactly where they are. What changes is the interface and control model. An alert triggers agent reasoning. The agent gathers context through MCP-connected tools. It proposes a Git-based fix. A human approves. The controller reconciles. No new control plane, no parallel infrastructure — just a better interface for an operational workflow that already exists.

The piece I'd push on in my own context: cross-session memory. If the same class of alert fires again next month, the agent should have context from the previous resolution. That's what turns a one-off demo into a durable operational pattern.

Start with one operational workflow that's currently too slow in a portal

Don't frame this as "AI-native replaces the portal". Frame it as "operational users who can't afford to navigate forms under pressure now have a better interface". Pick one high-friction workflow — noisy alert class, slow diagnosis path — and build the agent contract for that. Don't start with a platform overhaul.

What to do next: - Identify one operations workflow that's genuinely painful in portal-only mode - Define an agent contract for it: scope, tools, allowed actions, approval requirements - Route all production-affecting changes through PRs with required human review, even in the agentic path - Capture incident telemetry and assess whether agent-assisted workflows actually improve MTTR

Intro to Apache Kafka on Aiven: From Managed Simplicity to Inkless Architectures

Hugh Evans — Aiven

The different-shaped talk. Not about agents. About a real shift in how Kafka stores data.

Classic Kafka replicates partitions across brokers across availability zones. That's the durability model. It works. It's also expensive — cross-AZ data transfer is one of the biggest cost drivers in managed Kafka deployments. And operationally, it's heavy: rebalancing when you add or replace a broker is a genuine pain that gets worse as clusters grow.

Diskless Kafka — sometimes called "inkless" or "disaggregated", the terminology is still settling — moves durability off broker-local disks and onto object storage. The economics are materially different: object storage replication doesn't carry the same cross-AZ transfer cost as broker-to-broker replication. You also get less rebalancing friction when scaling horizontally, because broker state isn't tied to local disk.

The trade-off is latency. If your workload is latency-sensitive, the object storage path adds overhead you need to measure and design for. Mixed-mode support — running classic and diskless topics in the same cluster — gives you the flexibility to choose per workload rather than making a binary call for the whole cluster.

Worth watching, not uncritically adopting today. The open-source governance path involves competing KIPs and community alignment work, which is a useful reminder that "accepted direction" and "production ready" are different milestones.

Pull your cross-AZ transfer costs before anything else

That number is the entire justification for a pilot. For many teams it will be larger than expected, and the potential saving from diskless topics for the right workload class is real. The latency trade-off matters, but it's manageable if you profile first.

What to do next: - Profile current Kafka workloads by latency sensitivity and retention/replay patterns - Quantify cross-AZ transfer costs as a baseline before running any pilot - Test mixed-mode topics in a non-production cluster with p95/p99 latency measurement - Define clear topic placement rules (classic vs diskless) for engineering teams to use

The Age of "Big Tech" is Over

Sean M Tracey — Mitchell Technologies

The most contrarian talk of the day. Also probably the most honest.

The argument wasn't about market share or antitrust. It was more personal and more pointed: we've stopped questioning the assumption that progress requires giant platforms with giant defaults. We accept that a simple internal tool needs Kubernetes with five nodes, a managed database, a load balancer, and a monthly bill that would embarrass a small-team startup. We call it "enterprise-grade". Sometimes it's just overengineered.

Sean's counter: build small. Build local. Measure actual usage before sizing anything. The live demo — lightweight app deployment, a browser-based calling flow running with minimal resource usage — wasn't technically impressive by the standards of the rest of the conference. That was the point. Most of what we build doesn't need impressive infrastructure. It needs sufficient infrastructure.

The open source compounding argument is worth sitting with. Decades of shared tooling have made it dramatically cheaper to build good software than it was ten years ago. But we've developed habits of complexity that cancel out most of that gain. We reach for the same patterns we used when they were necessary, in contexts where they're not.

I'm not sure "the age of big tech is over" quite holds up as a thesis. But "our default infrastructure assumptions are probably wrong more often than we check" — that I buy.

Start from the minimum, measure your way up

When you next propose infrastructure for a new internal tool, start from the smallest thing that solves the real user need. "We'll scale later" is reasonable. "Let's start with enterprise defaults just in case" is where the waste compounds over years.

What to do next: - Audit one current service for over-provisioning against measured usage data, not assumed load - Pilot one new internal tool using the smallest viable deployment path and compare delivery speed - Compare total cost of ownership for one workflow across your current platform vs a lighter-weight path - Document a "small-first" engineering guide for new internal projects

What I'm taking away

Taken together, the sessions painted a fairly consistent picture.

Agents are moving into operational workflows — not as a future capability but as something teams are actively deploying now. The teams doing it well share three things: governance expressed as policy and code rather than prompts, genuine observability over what agents are actually doing, and a clear human-in-the-loop for high-impact changes. The teams doing it badly are relying on natural language instructions to enforce security boundaries. They're not.

On the platform side: portals aren't being replaced, but they are being supplemented. The operational interface is shifting toward conversational and MCP-connected patterns for users who live outside the portal. Context quality — service ownership, dependency metadata, team annotations — is becoming a force multiplier for agent usefulness. The teams with richer catalogs are getting better outputs.

And the Kafka session was a useful reminder that not everything interesting is about AI. Diskless architecture is a real cost and operational improvement for the right workloads, and it's worth following as it matures through the KIP process.

The question I keep coming back to is the one from Maebh Booth's session. If your team is using AI agents and hasn't explicitly defined what "stop and ask" means versus "use your judgment", you don't know what you're actually running. That conversation is worth having before something goes quietly wrong.

Which session was most immediately actionable?

The parallel swarm talk (Peter Bhabra) is probably the most directly applicable. The pattern is simple enough to prototype in a day or two, and the "independent verifier before backlogs" insight applies to almost every team running agents at scale.

Is governance-first realistic for smaller teams?

Yes. You don't need a full CRD-based control plane to start. Viola Lykova's access inventory approach — tool, token, scope, owner, environment — can live in a spreadsheet today. The principle scales down; the implementation grows with you.

What's the one thing I'd take into a Monday morning team meeting?

The silent interpretation drift frame from Maebh Booth. If your team is using agents and hasn't explicitly defined what "stop and ask" means versus "use your judgment", you don't know what you're actually running. That conversation is worth having before something goes quietly wrong.

Is the 'age of big tech is over' framing credible?

Probably not literally. But the underlying point — that our default infrastructure sizing assumptions are wrong more often than we check — is worth taking seriously regardless of how the headline lands.

June 10, 2026
10 min read

Your AGENTS.md Is Great. Now How Do You Roll It Out to 40 Repos?

Writing one AGENTS.md is a solved problem. You commit the file, the agents read it, the naming convention incident stops happening. Done.

Then someone asks: "Should all our repos have this?" And you say yes. And now you have 40 repos across three teams, some on GitHub, some on GitLab, one stubborn service still on Bitbucket — and the question of how you keep them consistent, how you propagate updates when the org-level conventions change, and how you know when a repo has drifted from the standard.

That's the harder problem, and it looks a lot like every other configuration management problem you've already solved for your infrastructure. The same instincts that made you reach for GitOps and policy-as-code apply here.

May 27, 2026
9 min read

Your AI Agent Doesn't Know You. Here's How to Fix That.

You open a new agent session. You paste in the problem. And the agent starts from zero.

It doesn't know you spent eighteen months migrating that monolith. It doesn't know you have a strong opinion about when to introduce abstractions (late) versus when not to (almost never). It doesn't know your default response to "let's just ship it and fix it later" is to ask what the rollback plan is. It doesn't know any of it. Every session is amnesia.

That's the cold-start problem. And most people solve it by writing better prompts — which works, until you forget to write the prompt, or the context window fills up, or you're halfway through a task before realising the agent is reasoning nothing like you would.

There's a better fix. Point a tool at your CV, your git history, your notes, your Slack export — and let it extract a behavioral profile. Not a biography. Not a career summary. A decision toolkit. The answer to "what would you do?" for every type of problem you routinely face.

That's experience-as-skill.

May 26, 2026
10 min read

From Prompt to Harness: The Three Eras of Working With AI

There's a moment every team hits after they've been running AI in production for a few months. The demos worked great. The initial results were impressive. And then the cracks appeared.

The agent ignored your naming conventions. It generated code that violated an architectural boundary you thought was obvious from context. Two parallel agent sessions clobbered each other's work. You added more detail to the prompt. You tuned the context window. And it still happened — not always, not predictably, but enough to matter.

What you ran into is the gap that neither prompt engineering nor context engineering was designed to close. And in 2026, there's a name for the discipline that closes it: harness engineering.

May 26, 2026
8 min read

MCP Goes Stateless: What the 2026-07-28 RC Actually Changes

If you've tried to run an MCP server properly on Kubernetes — not just kubectl apply a toy demo, but actually run it in production with horizontal scaling, rolling updates, and real traffic — you've hit the session problem. Sticky sessions at the load balancer. A Redis store bolted on to share session state across pods. Ingress rewrite rules that parse session IDs because your load balancer needs to route the same client to the same pod every time. It's the kind of infrastructure debt that accumulates quietly until someone tries to scale the thing and it falls apart.

The MCP spec release candidate locked on May 21st, and the headline change is that this whole problem goes away. MCP is now stateless at the protocol layer.

May 26, 2026
19 min read

The 6 GitHub Repos That Are Redefining How AI Agents Think, Act, and Talk to Each Other

There's a shift happening on GitHub that's easy to miss if you're filtering by star count alone.

The biggest numbers go to the obvious things — new model releases, ChatGPT wrappers, inference frameworks. But the interesting stuff is happening one layer up. People aren't just asking "which model should I use?" anymore. They're asking: how do I make an agent actually reliable? How do I give it the right skills, the right memory, the right coordination layer? And — increasingly — how do I make multiple agents talk to each other without it becoming a distributed systems nightmare?

These six repos are the honest answer to those questions right now. They span behavioural discipline, workflow methodology, persistence and memory, multi-agent orchestration, knowledge-aware agents, and the open protocol that lets agents from different vendors coordinate without anyone owning the bus. Between them, they've accumulated well over 400,000 GitHub stars in 2026.

The number that changes how you think about the agent stack

Skills, memory, and coordination — not the model itself — account for the biggest performance gaps between production agent systems in 2026. The harness matters more than the model.

Let me walk through each one, what it actually does, and why it matters if you're building or operating AI agents at any scale.

C4 Architecture Diagram

How These Repos Fit Together

Before we get into the individual repos, it's worth seeing the whole picture. These aren't six unrelated tools — they represent distinct layers of the agent stack.

Karpathy's skills repo is the discipline layer: the behavioural rules that stop an agent from going off-script. Superpowers is the methodology layer: composable skills that give your coding agent a complete software development workflow. Everything Claude Code is the persistence layer: the memory, project context, and domain-specific agents that survive between sessions. Ruflo is the orchestration layer: coordinating multiple agents so they work as a team rather than independently. Obsidian Copilot is the knowledge layer: giving an agent access to structured, personal knowledge rather than just context window scraps. And A2A is the interoperability layer: the protocol that lets agents from different vendors and systems actually talk to each other.

Stack them in that order and you've got something close to a complete production agent architecture.

1. andrej-karpathy-skills — The Discipline Layer

57k stars · multica-ai/andrej-karpathy-skills

There's a repo on GitHub with a single file in it.

No framework. No library. Just a CLAUDE.md — 65 lines of behavioural rules for AI coding agents, written by Andrej Karpathy and refined by thousands of contributors. It held the #1 spot on GitHub Trending for 28 consecutive days. If you haven't read it, stop here and go read it. It takes four minutes.

The four rules are deceptively simple. Think before coding — don't assume, surface tradeoffs, ask if uncertain. Simplicity first — minimum code that solves the problem, nothing speculative. Surgical changes — touch only what you must, every changed line traces to the user's request. Goal-driven execution — transform tasks into verifiable goals with binary exit conditions so agents can loop independently without constant clarification.

These rules exist because language models, by default, do the opposite of all four. They expand scope. They add "helpful" features. They refactor adjacent code. They continue trying variations when they should stop and ask. CLAUDE.md is the specific counter-force.

What this means for platform agents

Every agent you deploy against production infrastructure needs a version of this. Not the generic file — a version extended for your stack: blast radius awareness, approval tiers, what to touch and what to leave alone. The ai-capabilities repo has a ready-to-extend platform engineering version at templates/CLAUDE.md.

The 65-line file that reduced AI coding mistakes from 41% to 11% isn't magic. It's just the specific constraints that correct for how models behave by default. That's the whole insight.

2. superpowers — The Skills Framework

213k stars · obra/superpowers

Superpowers is what happens when you take the CLAUDE.md idea and build a full methodology around it.

Jesse Vincent built it as a composable skills framework for coding agents — but "skills framework" undersells what it actually is. Superpowers is a complete software development workflow encoded as skills that trigger automatically. The agent doesn't wait for you to invoke them. It checks for relevant skills before any task and applies them as mandatory workflows, not suggestions.

Here's the flow. When you give the agent a task, it doesn't jump into writing code. It runs the brainstorming skill first — asking questions, exploring alternatives, presenting a design in digestible chunks for your sign-off. Once you approve, writing-plans kicks in and breaks the work into bite-sized tasks, each with exact file paths, complete code, and verification steps. Then subagent-driven-development dispatches fresh subagents per task with a two-stage review (spec compliance, then code quality) after each one. Test-driven development is enforced throughout. The finishing-a-development-branch skill handles merge decisions and cleanup.

What makes it genuinely different: it works across every major coding agent. Claude Code, Codex, Gemini CLI, Cursor, Copilot — Superpowers installs as a plugin in each harness. The skills are harness-agnostic, which means your team can use whatever agent they prefer without forking your workflow conventions.

The subagent pattern

The subagent-driven-development skill is the one worth understanding in detail. Each task gets a fresh agent with no accumulated context from previous tasks — this is intentional. Accumulated context leads to cascading assumptions. Fresh agents stay on-spec. The two-stage review (does it match the plan? is the code quality acceptable?) happens before the next task starts. This is how Superpowers enables hours of autonomous work without deviation.

The skills library covers testing (red-green-refactor TDD enforced, not suggested), debugging (4-phase root cause process), collaboration (brainstorming, planning, parallel agents, code review in both directions), and meta skills like writing-skills for extending the framework. It's a methodology, not a tool.

3. ruflo — The Orchestration Layer

40k+ stars · ruvnet/ruflo

Ruflo answers a question that Superpowers doesn't: what happens when you need multiple agents working in parallel, coordinating across tasks, sharing memory, and — in the latest versions — federating across machines?

Built by Reuven Cohen, Ruflo started as an orchestration layer on top of Claude Code but has grown into something more general. It deploys agents as coordinated swarms with a self-learning memory layer that routes tasks, learns from successful patterns, and coordinates agents in the background. The latest v3.6 release adds agent federation: two or more Ruflo instances on different machines can communicate without exposing data — which starts to look a lot like proper A2A before the A2A protocol spec existed.

The numbers are striking. 84.8% solve rate on SWE-bench. 75% API cost reduction compared to using Claude Code directly. More than 40,000 stars and 6,000 commits. It's not a toy.

The A2A connection

Ruflo's federation model and the A2A protocol (repo #5) are solving the same problem from different directions. Ruflo builds coordination into the orchestration layer. A2A standardises the protocol so agents from different systems can coordinate. If you're building multi-agent infrastructure, you'll want both: Ruflo for internal coordination, A2A for cross-system interoperability. They're complementary, not competing.

For platform teams, Ruflo is the answer to "we want agents handling multiple concurrent infrastructure tasks without them conflicting." Drift detection, resource provisioning, incident triage — these don't have to run sequentially. With Ruflo's swarm model, they can run in parallel with explicit coordination. The self-learning hooks mean the orchestration improves over time without manual intervention.

4. obsidian-copilot — The Memory Layer

6.2k stars · logancyang/obsidian-copilot

This one has the smallest star count of the six. It's also the most underrated.

Obsidian Copilot is an AI agent that lives inside your Obsidian vault — the note-taking tool built on linked markdown files. But the interesting thing isn't the interface. It's what the vault becomes when you wire an agent into it: a structured, persistent, inspectable knowledge graph that the agent can read, write, and reason over.

Most agent memory is ephemeral — the context window fills up and older context falls off. What you end up with in practice is agents that know a lot right now and nothing next session. Obsidian Copilot flips this. The vault is the memory. The agent reads notes, writes notes, follows links between notes, and builds up a knowledge base that persists across every session and is completely transparent to you in plain markdown.

The agentic features have grown significantly in 2026: vault search, web search, YouTube summarisation, a Composer V2 with precise in-file editing tools, and long-term memory as an explicit tool the agent can use starting from v3.1.0. There's even a planned Obsidian CLI integration that will give the agent desktop-level vault operations.

Why the knowledge graph matters for agents

Context window management is one of the hardest problems in practical agent design. If the agent can only work with what fits in the window, you're constantly curating what to include and what to drop. If the agent has a searchable, linked knowledge graph it can query at will, the curation problem shrinks dramatically. The agent asks for what it needs rather than being given everything upfront. That's a fundamentally more scalable pattern.

For knowledge workers, researchers, and anyone who thinks in connected notes rather than linear documents, this is the agent that actually fits the way their work is organised. And for platform teams: if your runbooks, ADRs, and internal documentation live in a linked knowledge base, this pattern scales directly.

5. A2A — The Interoperability Protocol

22k+ stars · a2aproject/A2A

The other five repos solve problems within a single agent system. A2A solves the problem between systems.

A2A — Agent-to-Agent — is an open protocol, originally contributed by Google and now hosted by the Linux Foundation, that lets AI agents built by different vendors discover each other, delegate tasks, and coordinate work without a shared codebase or a vendor-owned message bus. As of April 2026, it's in active production use at more than 150 organisations.

The protocol works through an Agent Card — a JSON manifest that an agent publishes describing its capabilities, input schemas, and authentication requirements. Any A2A-compatible agent can discover another agent's card, understand what it can do, and delegate tasks to it using a standardised lifecycle: task creation, execution, progress streaming, and completion or failure handling. The delegating agent doesn't need to know anything about the implementation on the other side.

Think about what this enables. Your ArgoCD-aware agent can delegate to a Crossplane provisioning agent without you building a custom integration between them. Your incident triage agent can delegate a policy check to an OPA agent from a completely different team. Vendor-built agents (GitHub Copilot, Claude, Gemini) can participate in the same workflow as your internal agents. No custom APIs, no bespoke message formats, no vendor lock-in.

A2A and MCP are different things

This comes up constantly. MCP (Model Context Protocol) connects an agent to tools — APIs, databases, functions it can call. A2A connects an agent to other agents — delegates tasks to systems that have their own reasoning, their own models, their own tool access. You'll likely use both: MCP to give your agents platform tooling access, A2A to let those agents coordinate with agents in other systems.

For platform teams, A2A is the protocol you adopt before you need it, not after. Once you have multiple agent systems — which happens faster than you'd expect — retrofitting coordination is painful. Designing your agent interfaces as A2A-compatible from the start means your internal agents can interoperate with vendor agents, partner systems, and future tools you haven't built yet.

6. Everything Claude Code — The Persistence Layer

~100K stars · affaan-m/everything-claude-code

Claude Code has one glaring problem: it forgets everything between sessions. Team conventions, project-specific patterns, architectural decisions you've made — gone when you close the terminal. Superpowers gives you the workflow discipline. But discipline doesn't help if the agent doesn't know what your codebase is, what your team standards are, or what you've already decided.

Everything Claude Code (ECC) is the fix. Created by Affaan Mustafa after winning an Anthropic hackathon in September 2025, it layers a structured memory system, 30 specialised agents, 136 skills, 60 slash commands, and automated hook workflows on top of the base Claude Code agent. The v1.9.0 release in March 2026 added a selective-install architecture (you pull only the agents and skills you actually need) and support for 12 language ecosystems.

The key mechanism is a persistent memory layer that stores team conventions, project context, security scan results, and previous session outputs in structured files. When you start a new Claude Code session, ECC pre-loads the relevant context automatically. The agent walks in knowing what the project is, what patterns to follow, and what decisions have already been made.

The 30 agents aren't generic. There's a security agent that runs automated scanning before every commit, a documentation agent that keeps internal docs in sync with code changes, performance optimisation agents for specific language ecosystems, and architecture review agents that check new code against your documented patterns. You install the ones that match your stack.

ECC + Superpowers is the combination most teams end up at

Superpowers gives the workflow structure (the how: brainstorm before building, fresh subagents per task, spec compliance review). ECC gives the persistent context (the what: your project's conventions, your team's decisions, your codebase's patterns). They're complementary, not competing. Most mature Claude Code setups run both.

Why it hit 100K stars: Because the memory problem is universal. Every team using Claude Code hits the same wall — the agent is great in session one and increasingly unreliable by session three because it keeps re-deriving decisions you've already made. ECC solves that at the framework level rather than making every engineer manually curate context at the start of every session.

The platform engineering angle: ECC ships a dedicated infrastructure agent that understands IaC patterns, Kubernetes manifests, and CI/CD workflows. Pair it with the Karpathy rules and your platform-specific CLAUDE.md extensions, and you've got a coding agent that stays on-pattern across the entire team — not just in the sessions where someone manually explains your conventions.

The Pattern

Look at what these six repos have in common.

All of them treat the agent's environment as more important than the model. Karpathy's rules constrain behaviour. Superpowers provides structure. Ruflo manages coordination. Obsidian Copilot provides persistent memory. A2A defines the interface. None of them are about which LLM you use. The model is almost incidental.

That's the real shift in 2026. Twelve months ago, most of the GitHub activity was about models and inference. Now it's about the layer that wraps the model — the skills, the memory, the coordination, the protocol. The harness is the product.

If you're building an internal developer platform and you're thinking about where AI fits into it, these six repos show you the architectural vocabulary. Discipline layer, skills framework, orchestration layer, memory layer, interoperability protocol, persistence layer. Each one solves a distinct problem. Together they describe what a production-grade AI agent stack actually looks like.

What This Actually Looks Like in Practice

The architecture talk is useful, but let's get concrete. Here are five real workflows — one per role — that show how these repos translate into things people actually need to get done. None of these require you to be an engineer.

Product Owner: writing a PRD from scratch

You're a product owner. You've got a rough idea, a few customer interviews, and a half-finished Miro board. You need a proper PRD before the sprint planning session tomorrow.

This is where Obsidian Copilot earns its place. Your vault already has your interview notes, your competitor research, your previous PRD templates. You ask the agent to draft a PRD for the new feature. It searches the vault for related context — past decisions, open questions from previous planning, what the engineering team flagged as constraints last quarter. It pulls that in automatically rather than you curating it by hand.

Then Superpowers' brainstorming skill kicks in — the agent asks clarifying questions before it writes a single sentence. What's the user problem? What are the constraints? What does success look like in 90 days? You answer, it validates your understanding back, you approve the shape of it. Then it writes. The output follows your vault's PRD template (because that template is already in there as a note), includes links back to the source interviews, and flags three open questions it couldn't answer from existing context.

The Obsidian vault as your second brain

The difference between a generic AI-generated PRD and one that's actually useful is context — your product history, your team's constraints, your customers' words. Obsidian Copilot pulls that in from your vault automatically. The richer your vault, the better the output. This is why the memory layer is the most underrated part of the stack.

Engineering Lead: spinning up a feature branch

You've got a ticket. It's well-specified — scope, acceptance criteria, which files are in and out of bounds. You fire up your coding agent with Superpowers installed.

The agent doesn't jump into writing code. brainstorming activates first — it restates the spec back to you, flags two ambiguities it noticed, and proposes a design in chunks short enough to actually read. You approve. using-git-worktrees creates an isolated branch so this work can't bleed into anything else running in parallel. writing-plans breaks the implementation into 2–5 minute tasks, each with exact file paths and verification steps. Then subagent-driven-development dispatches fresh subagents per task, reviews each one before moving to the next, and runs test-driven-development throughout.

Two hours later you have a PR with a clean diff, a description that echoes the spec, and every changed line traceable to a specific sentence in the ticket. finishing-a-development-branch handles the merge decision and cleans up the worktree.

Why this beats just asking the agent to implement the ticket

The difference is the structure. Without Superpowers, an agent will implement the ticket — and it'll probably overreach, make assumptions, and produce a diff nobody wants to review carefully. With Superpowers, the workflow enforces the planning step, the scope constraint, and the verification before you see any output. The agent did two hours of work, but the result reads like a careful engineer did it.

Platform Engineer: parallel infrastructure tasks without conflicts

You need to run drift detection across three clusters, provision a new namespace for the data team, and rotate credentials — all while keeping those agents from stepping on each other.

This is the Ruflo use case. You configure a swarm: three agents with explicit task ownership, coordination hooks that prevent conflicting writes, and a shared memory layer that routes tasks based on learned patterns from previous runs. The drift agent checks cluster state against Git and opens targeted fix PRs. The provisioning agent creates the namespace and wires it up via Crossplane. The credential rotation agent runs against your secrets manager. All in parallel. All isolated. All feeding back into the same coordination layer.

When a task completes or fails, Ruflo's hooks route the result to the right place — a Slack notification, a PR, a follow-up task. You watch the summary rather than babysitting three terminal windows.

Add A2A to the mix

If your credential rotation agent is a vendor-built security tool rather than something you wrote, A2A is how you wire it in without building a custom integration. Publish an Agent Card for your Ruflo swarm. The vendor agent discovers it, delegates the rotation task via the standardised A2A lifecycle, and reports back. No custom API, no bespoke message format.

Researcher / Knowledge Worker: building a living literature review

You're tracking a fast-moving research area — say, agent memory architectures, or the regulatory landscape for AI in healthcare. You need something that stays current, not a one-shot document that's stale in three weeks.

Obsidian Copilot + a web search tool gives you a living review. You set up a note structure in your vault: a hub note for the topic, linked notes per paper or source, a synthesis note that the agent updates as new material comes in. When you ask the agent to add a new paper, it reads the paper, checks your existing notes for related work, updates the synthesis note with the new finding, and flags any contradictions with what's already there.

The vault becomes a knowledge graph the agent actively maintains. You read and edit in Obsidian. The agent does the indexing and synthesis. After a month, you have a structured, cross-linked literature review that an agent can query to answer specific questions — rather than a folder of PDFs nobody can find anything in.

This pattern scales beyond research

Legal teams tracking case law. Finance teams following regulatory changes. Marketing teams watching competitor moves. Any domain where you're accumulating knowledge over time and need to reason over it later fits this pattern. The knowledge graph is the product; the agent is the librarian.

CTO / Engineering Director: cross-system agent coordination

You've got a GitHub Copilot deployment for your dev team, an internal Claude-based triage agent for incidents, and a security scanning agent your vendor provides. Right now they don't talk to each other. When an incident involves a code change, someone manually bridges the three systems.

A2A is how you fix this. Each system publishes an Agent Card describing what it can do. Your incident triage agent discovers the GitHub Copilot agent's card, delegates the "find the commit that introduced this regression" task to it via standard A2A task lifecycle, waits for the result, then hands that to the security agent to check for CVEs. The whole chain runs on a standard protocol — no custom webhooks, no shared API keys, no bespoke integration code between each pair.

The agents are from three different vendors. They run on three different infrastructures. They coordinate as if they were one system.

Start with the Agent Card, not the integration

The instinct when you want two systems to talk is to build a custom integration. Resist it. If either system is A2A-compatible (or can be made A2A-compatible), publishing an Agent Card is a fraction of the work and gives you a reusable interface for every future integration. Design the interface once; every A2A-compatible agent gets it for free.

FAQ

Do these all only work with Claude?

No. Karpathy's CLAUDE.md works with any coding agent that reads context files (most of them do). Superpowers explicitly supports Claude Code, Codex, Gemini CLI, Cursor, and Copilot. Ruflo started as Claude-focused but the orchestration patterns are increasingly general. Obsidian Copilot supports any OpenAI-compatible API backend, including Ollama for local models. A2A is explicitly vendor-agnostic — it was designed from the start to work across any agent system.

Is A2A ready for production?

Yes, with caveats. The protocol is stable and in use at 150+ organisations. The implementation quality varies by vendor. Check which A2A versions your chosen agent runtimes support before designing your coordination architecture around specific features. The spec is evolving — the Linux Foundation governance means it moves more deliberately than a single-vendor standard would.

How does Superpowers relate to CLAUDE.md?

CLAUDE.md is the behavioural layer — it defines how an agent should make decisions. Superpowers is the workflow layer — it defines what steps an agent follows to get work done. They're complementary. Superpowers actually ships its own CLAUDE.md and AGENTS.md as part of the framework. You'd typically use both together: CLAUDE.md for the "how do I decide" layer, Superpowers skills for the "what do I do next" layer.

Can I use Ruflo with agents other than Claude?

The core orchestration concepts translate, but Ruflo's current implementation is tightest with Claude Code and Codex. Federation via A2A is the cleaner path if you need cross-vendor agent coordination — that's what A2A was designed for.

Where does MCP fit in this picture?

MCP gives agents their tools — the ability to call APIs, query databases, run commands. These six repos build the layer above that: how agents behave, coordinate, remember, and interoperate. You'll want MCP for the tool access layer and these repos for everything that sits on top of it.

Where to Start

If you're building agent workflows from scratch, start with Karpathy's CLAUDE.md as your discipline foundation, then layer Superpowers on top for workflow structure. If you're moving to multi-agent systems, Ruflo gives you internal coordination today; add A2A compatibility as you build external interfaces. If memory and knowledge management is your constraint, Obsidian Copilot shows you the pattern even if you implement it differently.

The six repos together describe the problem space. The right starting point depends on which layer is your current bottleneck.

Which coding tool do you use?

These frameworks aren't all equally compatible with every coding assistant. Here's where each one lands across the four most popular tools — so you know what you're getting before you commit to an integration.

Repo	Claude Code	GitHub Copilot	Cursor	Windsurf
andrej-karpathy-skills	✅ Native — CLAUDE.md is its home	⚠️ Adapt content to Copilot custom instructions	✅ Port to `.cursorrules`	✅ Port to `.windsurfrules`
superpowers	✅ Native Anthropic marketplace plugin	✅ Copilot CLI harness (v5.0+)	✅ `.cursor-plugin/` harness	⚠️ No official harness yet — use `.windsurfrules` manually
everything-claude-code	✅ Native (built specifically for Claude Code)	❌ Claude Code–specific hooks and memory system	✅ Supported (skills and slash commands port across)	⚠️ Partial — skills work, hook workflows don't
ruflo	✅ Native (built for Claude Code first)	❌ Copilot lacks the agent orchestration model Ruflo needs¹	✅ Supported	✅ Supported
obsidian-copilot	➖ Obsidian plugin — IDE-agnostic	➖ Obsidian plugin — IDE-agnostic	➖ Obsidian plugin — IDE-agnostic	➖ Obsidian plugin — IDE-agnostic
A2A	⚠️ Participate as protocol client via custom wiring	✅ GitHub/Microsoft are A2A contributors; Copilot agent supports it	⚠️ Participate as protocol client	⚠️ Participate as protocol client

Key: ✅ Official integration or native support · ⚠️ Works with manual adaptation · ❌ Not compatible · ➖ Not applicable (tool operates independently of your IDE)

A few notes worth highlighting:

Superpowers is the standout for multi-tool teams — it's the only framework here with explicit multi-harness support baked in. The same skills folder works across Claude Code, Cursor, Codex, and Copilot CLI with no content duplication. If half your team uses Cursor and half use Claude Code, Superpowers is the only framework on this list that doesn't force you to maintain separate skill sets.

ECC is the most Claude Code–specific repo of the six. The hook system that drives its memory and automated scanning is tightly coupled to Claude Code's plugin architecture. You get the most out of it with Claude Code; the skills and slash commands translate to Cursor reasonably well, but you lose the persistence and hook automation.

¹ Ruflo for Copilot users: The structural gap is real — Ruflo's swarm orchestration requires persistent background coordination that Copilot's current architecture doesn't expose. If you're on Copilot and need multi-agent orchestration, the closest alternatives are GitHub Copilot Workspace (Microsoft's own built-in multi-step agent, limited but native) or OpenHands (formerly OpenDevin — model-agnostic, runs against any OpenAI-compatible backend so it can coordinate the same underlying GPT-4o models Copilot uses). Ruflo itself also now supports multi-model via its web UI (OpenAI, Gemini, Qwen), so running Ruflo with GPT-4o directly — outside of Copilot's IDE integration — is a workable path for teams that need the orchestration capability.

The Obsidian Copilot row isn't a weakness — it's a feature. The knowledge graph pattern is IDE-independent because it lives entirely outside your IDE. Your vault is your memory layer regardless of what coding tool you're using that day.

Useful starting points

All of these repos are worth starring and tracking. The specific files to read first:

Repo	Start here	What it gives you
andrej-karpathy-skills	`CLAUDE.md`	65-line behavioural foundation for any agent
superpowers	`skills/README`	Full skills library and workflow methodology
everything-claude-code	`INSTALL.md` — use selective install	30 agents, 136 skills, persistent session memory
ruflo	`docs/USERGUIDE.md`	Multi-agent orchestration and swarm setup
obsidian-copilot	Plugin README	Agent memory architecture via knowledge graph
A2A	Protocol spec + samples	Agent discovery, task delegation, interop pattern

For the platform engineering versions of CLAUDE.md and AGENTS.md — extended with blast radius awareness, approval tiers, and audit trail requirements — see the ai-capabilities repo. And for the day-to-day setup that puts these repos to work — the context budget, the plugins to skip, the token discipline — see Claude Code for Platform Engineers.

May 24, 2026
10 min read

The Four Rules That Make AI Agents Actually Trustworthy

There's a repo on GitHub with over 100,000 stars and a single file in it.

No framework. No library. Just a CLAUDE.md — 65 lines of behavioural rules for AI coding agents, written by Andrej Karpathy and refined by thousands of contributors. It held the #1 spot on GitHub Trending for 28 consecutive days. And according to the engineers who've actually measured it, applying the four rules cuts AI coding mistakes from 41% down to 11%.

The number that made 100,000 engineers take notice

Karpathy's four rules reduced AI coding error rates from 41% to 11% across real production codebases. That's not a benchmark — it's a before/after from teams who added a 65-line file to their repo root.

The repo is called andrej-karpathy-skills, and if you haven't read it yet, stop here and go read it. It'll take four minutes.

Back? Good. Here's what struck me about it.

Those rules aren't just about code quality. They're about trust. And if you're a platform engineer who's been quietly worrying that the AI agents you're deploying might one day do something you didn't expect — rewrite a file you didn't ask them to touch, open a PR that goes further than it should, make a "helpful" change that breaks something adjacent — this document is the answer you've been looking for.

Let me walk through the four rules and show you exactly why they matter beyond the IDE.

How CLAUDE.md Fits Into Your Agent Workflow

Before we get into the rules, here's the architectural picture. CLAUDE.md isn't a tool — it's a discipline layer that sits between you and your agent, constraining how it behaves across every action it takes.

C4 Architecture Diagram — CLAUDE.md as the discipline layer in an agentic workflow

The key insight is that CLAUDE.md gets loaded into context before the agent does anything else. It's not a suggestion — it's the first thing the agent reads. Everything that follows gets filtered through those four rules. That's why 100,000 engineers put it in their repos.

Rule 1: Think Before Coding (or Acting)

Karpathy's first rule is blunt: don't assume. If the agent is uncertain, it should stop and say so. If multiple interpretations exist, surface them — don't silently pick one. If something is unclear, name it and ask.

This sounds obvious. It's almost never what happens by default.

The agents most of us deploy start doing the moment they have a task. That's the whole appeal — you give them a job and they get on with it. But there's a silent assumption baked into every agentic action: that the agent understood the intent correctly. And when it didn't? You find out later, usually from a diff that shows a change you didn't ask for, or a Slack message from a teammate asking why their config changed.

Here's the practical fix. In every agent workflow you design, build in an explicit planning step before any action is taken. Not a loop — a pause. Ask the agent to state what it understood the task to be, what it assumes is in scope, and what it'll leave alone. If it's using a tool that touches infrastructure — opening a PR, modifying a ConfigMap, calling an API — that statement should be visible somewhere before the action executes.

You don't need to make this interactive for every task. A structured output written to a log, a brief comment at the top of the PR, a plan.md file committed alongside the change — any of these work. The goal is that you can read it and immediately know whether the agent understood correctly.

If it didn't, you catch it there. Not three steps later.

Apply this in your AGENTS.md

Add a ## Before acting section to your AGENTS.md that requires agents to state their understanding of each task before executing. The walkthrough AGENTS.md at the end of this post includes a ready-to-use template.

Rule 2: Simplicity First

The second rule: minimum code that solves the problem. Nothing speculative. No abstractions for single-use code. No "flexibility" that wasn't requested.

Karpathy includes a check that I keep coming back to: "Would a senior engineer say this is overcomplicated? If yes, simplify."

For platform agents, this translates into something I'd call scope discipline. Every agent has a natural tendency to be helpful in ways you didn't ask for. You ask it to write a runbook section and it rewrites the whole document. You ask it to add a tag and it refactors the tagging structure. You ask it to diagnose a slow query and it proposes a schema change.

Each of these might be genuinely useful. That's not the point. The point is that the scope expanded without your consent.

The fix isn't to make agents dumber — it's to make their scope explicit at task creation time. In the repo-native AI workflow pattern, this means writing issue templates that spell out what's in scope and what isn't. The agent reads the issue, does exactly that thing, and opens a PR. The PR description echoes back what was in scope. If the agent noticed something adjacent that might be worth doing, it mentions it in a comment — it doesn't do it.

This is the "minimum viable change" principle applied to agentic work. It's not about limiting capability. It's about keeping diffs readable, keeping trust high, and keeping the feedback loop short.

The scope creep tell

If your agent's PR touches files that aren't mentioned in the task description, scope discipline has broken down. The walkthrough GitHub issue template has explicit "in scope / out of scope" fields that force this boundary at task creation time.

Rule 3: Surgical Changes

This one's my favourite because it describes the failure mode so precisely.

"Don't improve adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style, even if you'd do it differently."

And then this: "The test: every changed line should trace directly to the user's request."

That last sentence is a contract. If you can't point to the line in the user's request that caused a particular change, that change shouldn't be there.

For platform engineers, this rule has teeth when you're running agents that touch shared infrastructure. The agent that detects GitOps drift and opens a fix PR — does every line in that PR trace to the drift that was detected? Or did it also "clean up" some formatting, adjust a label it noticed was inconsistent, add a comment it thought would be helpful?

The drift detection pattern we use produces targeted PRs by design: the agent identifies the delta between live state and desired state and fixes exactly that delta. Nothing else. The diff is small. The reviewer knows what to look for. The PR merges quickly.

Agents that reach beyond their scope produce PRs nobody trusts enough to merge quickly, which defeats the whole point.

The surgical change test

Before merging any agent PR, ask: can every changed line be traced back to a specific sentence in the task description? If not, the agent over-reached. This isn't a failure — it's a signal that the task description needed tighter scope.

Surgical also applies to what agents leave behind. Karpathy's rule covers orphans: imports, variables, functions that your changes made unused should be removed — but pre-existing dead code should be left alone unless you were specifically asked to clean it up. The equivalent in infrastructure: if the agent's change made a resource reference obsolete, remove that reference. But don't audit and remove all the other stale references you noticed on the way through.

One thing at a time. On purpose.

Rule 4: Goal-Driven Execution

The final rule is the most operationally important one.

"Transform tasks into verifiable goals. Strong success criteria let you loop independently. Weak criteria require constant clarification."

Karpathy's example is sharp: "Fix the bug" is weak. "Write a test that reproduces the bug, then make it pass" is strong. The difference is that the strong version has a binary exit condition. The agent knows exactly when it's done.

This matters enormously for unattended agents. If an agent is running on a cron, responding to an alert, or triggered by a webhook — there's nobody watching. The agent needs to know what "done" looks like without asking. And if it hits something unexpected, it needs to know when to stop and escalate rather than continuing to try variations.

In the SLO-driven automation pattern, the success criteria are defined up front in the remediation catalogue: this action is complete when the SLO burn rate drops below the threshold within N minutes. If that doesn't happen, the agent escalates. It doesn't keep trying. The pre-approved catalogue defines what success looks like for each remediation action, so the agent can loop independently on the happy path and hand off cleanly when it can't reach the exit condition.

This is also where the agentic change management tier model connects. Tier 1 actions (low risk, pre-approved) have clear success criteria and run unattended. Tier 2 and 3 actions require human approval precisely because the success criteria are fuzzier — the agent can't verify correctness without a human in the loop. The tier model is really just a structured answer to: "how much do we trust this agent to know when it's done?"

Why These Four Rules Specifically

You might be thinking: these are pretty general. Don't all good engineering practices boil down to something like this?

Sort of. But here's what's different about Karpathy's framing.

These rules are written against the grain of how language models behave by default. A model that hasn't been given these constraints will naturally expand scope, add "helpful" features, refactor adjacent code, and continue trying variations rather than stopping and asking. The defaults are wrong for production use. These rules exist to correct them.

That's why 57,000 engineers starred this file. Not because the ideas are novel, but because they're the specific counter-forces you need to apply to get agents that behave like careful, disciplined colleagues rather than enthusiastic interns who haven't learned to ask before they do things.

If you're designing agentic workflows for your platform team, these four rules should be the first thing you embed — in your AGENTS.md, in your task templates, in your PR review process, in your remediation catalogue. Before you think about which tools the agent has access to, think about what constraints govern how it uses them.

The capability is almost never the problem. The discipline layer usually is.

FAQ

Is CLAUDE.md just for coding agents?

No, though that's where it originated. The four rules — think before acting, minimum scope, surgical changes, verifiable success criteria — apply to any agentic workflow where an AI is taking actions with real-world consequences. Infrastructure agents, doc update agents, triage agents: all of them benefit from these constraints.

Should I copy Karpathy's CLAUDE.md directly into my repo?

The file itself says "merge with project-specific instructions as needed" — which is the right framing. Use it as a base and extend it with context specific to your stack, your conventions, and your tolerance for autonomous action. The walkthrough CLAUDE.md at the end of this post is already extended for platform engineering teams specifically.

Does this mean agents should ask for permission constantly?

No — that's the opposite of useful. The goal is to design tasks clearly enough that the agent doesn't need to ask. The planning step in Rule 1 isn't interactive clarification; it's the agent stating its interpretation before acting so you can catch misunderstandings in the log rather than in the diff. For routine, well-scoped tasks, a well-constrained agent should be able to run completely unattended.

How do you enforce these rules technically?

You can't fully enforce them through prompting alone — the rules need to be backed by workflow design. Scope discipline comes from good task templates. Surgical changes come from code review and PR conventions. Goal-driven execution comes from pre-defined success criteria in your remediation catalogue or task definitions. The CLAUDE.md is the statement of intent; your tooling and process are what make it hold.

Karpathy's CLAUDE.md is worth keeping open in a tab while you design your next agentic workflow. Not because it'll tell you what tools to use or how to structure your pipelines — but because it'll keep asking you the question that matters most: does this agent know exactly what it's supposed to do, and exactly when to stop?

If you can answer yes to both, you've got something you can trust.

Walkthrough files

Everything from this post is ready to drop into your repository. All three files are in the ai-capabilities repo.

File	What it is
`templates/CLAUDE.md`	Production-ready CLAUDE.md extended for platform engineering — adds blast radius awareness, approval tiers, and audit trail requirements on top of Karpathy's four core rules
`examples/karpathy-claude-md.md`	AGENTS.md routing map for agents in your repo — defines what's Tier 1 (autonomous), Tier 2 (draft PR), and Tier 3 (synchronous approval), plus which tools agents can use and what's explicitly out of scope
`templates/github-issue-agent-task.md`	GitHub issue template that enforces Rule 4 at task creation — forces explicit scope, success criteria, approval tier, and rollback plan before an agent picks up any task

Drop templates/CLAUDE.md into your repository root as CLAUDE.md. Add examples/karpathy-claude-md.md as your AGENTS.md. Put the issue template in .github/ISSUE_TEMPLATE/agent-task.md. That's the minimum viable discipline layer.

For the workflow patterns that put these rules into practice at scale, start with Repo-Native AI Workflows for the task structure layer, Agentic Change Management for the governance tier model, and SLO-Driven Automation for what goal-driven execution looks like when the stakes are a production SLO breach.

May 22, 2026
9 min read

A2A and MCP Are Not Competing — They're the Stack

If you've been watching the MCP space, you've probably seen A2A mentioned in the same breath and wondered whether Google just launched a competing standard. They didn't. A2A and MCP divide the problem cleanly: MCP is how an agent talks to tools and data. A2A is how one agent talks to another. Once you see it that way, the question isn't "which one?" — it's "when do you need both?"

May 22, 2026
9 min read

You Can't Debug What You Can't See: OTel GenAI Conventions for Agent Workloads

A model call fails silently. Your agent stops mid-chain and returns an empty result. The logs show an HTTP 200. You have no idea which tool call caused it, what the model was given, how many tokens it burned, or where the latency actually went. This is what most teams running agents in production are dealing with right now. OpenTelemetry's GenAI semantic conventions are the fix — and the OTel Operator for Kubernetes means you can get this instrumentation without touching application code.

May 19, 2026
9 min read

Your Platform Repo Needs an AGENTS.md. Here's What Goes In It.

There are now 60,000+ public repos with an AGENTS.md. Every major AI coding agent — Claude Code, OpenAI Codex CLI, Cursor, GitHub Copilot, Gemini CLI, Aider — reads it before touching your code. It's the file that tells an AI what it can do, what it can't touch, and how your repo actually works. And almost none of those 60,000 files are written for a Kubernetes platform repo. That gap is going to cost someone an incident.