DEV Community: Médéric Hurier (Fmind)

MCP 2026–07–28: Stateless core, enterprise authorization, and SDK betas

Médéric Hurier (Fmind) — Wed, 08 Jul 2026 04:54:59 +0000

Running a remote Model Context Protocol (MCP) server behind multiple instances presents immediate infrastructure challenges. Because the original spec requires an initialize handshake and pins sessions to a specific instance via the Mcp-Session-Id header, you are forced to configure sticky routing or a shared session store at the load balancer level. This makes scaling beyond a single process unnecessarily complex.

To address these limitations, the MCP project released three updates in mid-2026: a release candidate for the 2026–07–28 specification, a stable enterprise-managed authorization extension, and beta SDKs across Python, TypeScript, Go, and C#.

Together, these changes address three core production challenges: stateless scaling, centralized identity management, and protocol version stability.

Photo by Robynne O on Unsplash

Stateless core: scaling without handshakes

The 2026–07–28 specification removes the stateful handshake and session management. The initialize/initialized handshake is gone, and so is the protocol-level session. Client information, protocol version, and capabilities now travel in a request’s _meta field on every call, making each request self-describing.

This allows remote servers to run behind standard round-robin load balancers without session affinity or synchronization. Any instance can answer any request without first replaying a handshake or looking up shared session state.

A standard tool call now requires no prior initialization and carries all context self-contained:

POST /mcp HTTP/1.1
Mcp-Protocol-Version: 2026–07–28
Mcp-Method: tools/call
Mcp-Name: search
{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"search","arguments":{"q":"otters"},
"_meta":{"io.modelcontextprotocol/protocolVersion":"2026–07–28",
"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

The _meta block carries the client identity and protocol version. The Mcp-Method and Mcp-Name HTTP headers allow load balancers or gateways to route the call without parsing the JSON payload body.

Because the protocol is now stateless, servers can no longer interrupt an active connection to request input. Instead, the spec introduces Multi Round-Trip Requests. When a tool requires input, the server returns an InputRequiredResult containing an opaque requestState. The client must then re-invoke the tool call, passing the user’s input alongside the requestState token. This design allows any available instance to process the response without holding a connection open.

This stateless model increases request payload sizes because client capabilities and session parameters must be transmitted with each call. However, it enables standard production features: full JSON Schema 2020–12 validation, cache-control hints (ttlMs and cacheScope), W3C Trace Context propagation for OpenTelemetry, and a modular extensions framework. The first two official extensions are MCP Apps (sandboxed HTML-based user interfaces) and a stateless version of Tasks.

Centralized identity: enterprise-managed authorization

Beyond horizontal scaling, managing MCP server access across a team requires central authorization. The standard per-user OAuth flow forces every employee to authorize each MCP server individually, which complicates onboarding, lacks centralized audit logs, and mixes personal and corporate access.

To address this, the enterprise-managed authorization extension (stabilized in June 2026) implements the Identity Assertion JWT Authorization Grant (ID-JAG). During single sign-on (SSO), the client trades the user’s identity token for an ID-JAG scoped to a specific target server via RFC 8693 token exchange. The client then presents this grant to the MCP server’s authorization server to obtain an access token. This token exchange runs entirely in the background, removing the need for individual interactive consent screens:

# 1. IdP: swap the SSO identity for a grant good only for one MCP server
grant_type=urn:ietf:params:oauth:grant-type:token-exchange
requested_token_type=urn:ietf:params:oauth:token-type:id-jag
resource=https://mcp.example/ # the specific server this grant targets
subject_token=<the user's SSO id_token>
# 2. MCP authorization server: swap that grant for the server's access token
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<the ID-JAG returned by step 1>

Access control is governed by the organization’s existing identity provider (IdP) groups and roles. Administrators can configure permissions from a single control plane, and all access generates centralized audit trails.

This extension is additive and opt-in. The default remains per-user OAuth for consumer configurations. MCP servers advertise support for enterprise-managed authorization as a capability, and clients negotiate it during connection. The IdP only validates policy and mints the grant, meaning it never intercepts raw MCP traffic, and each access token is strictly audience-restricted to its target server.

Version stability: release deprecation windows and SDK betas

To make the protocol viable for long-term roadmaps, MCP has introduced a formal specification lifecycle. Features now transit through Active → Deprecated → Removed states, with a minimum deprecation window of twelve months. Furthermore, proposed changes to the Standards Track must be validated against a formal conformance suite, and specifications are versioned by calendar date.

In the 2026–07–28 revision, several legacy features (Roots, Sampling, and Logging) are deprecated. They will be replaced by tool parameters, resource URIs, direct provider APIs, and standard error output or OpenTelemetry streams.

To allow teams to validate these changes ahead of the final specification release on July 28, the project has published beta SDKs across four languages:

# Python - opt-in pre-release
pip install "mcp[cli]==2.0.0b1"
# TypeScript v2 - new split server/client packages
npm install @modelcontextprotocol/server@beta @modelcontextprotocol/client@beta
# Go - same module path, pre-release tag
go get github.com/modelcontextprotocol/go-sdk@v1.7.0-pre.1
# C#
dotnet add package ModelContextProtocol --prerelease

The existing v1 SDK lines will receive bug and security patches for at least six months following the final release. Backward compatibility is maintained: v2 servers continue to accept legacy 2025–11–25 handshake requests, allowing clients to upgrade independently.

What this means for teams running agents in production

MCP is now hosted by the Agentic AI Foundation under the Linux Foundation. This open governance model ensures neutral stewardship while retaining a focused specification enhancement process led by active maintainers. Implementing a predictable release cadence, formal deprecation timelines, and conformance testing establishes MCP as a reliable infrastructure standard rather than an unstable library.

With the 2026–07–28 specification locking at the end of July and SDK betas available, you should evaluate the following points in your deployment:

Identify session dependencies. If your setup relies on sticky routing or shared session tables, migrating to the stateless core will allow you to transition to standard round-robin load balancing and simplify your infrastructure.
Evaluate your onboarding flow. If your servers currently require individual user consent redirects, verify if your IdP and client support the new enterprise token-exchange extension to enable role-based authorization.
Plan your version migrations. If your systems are pinned to the original 2025–11–25 specification, utilize the 12-month deprecation window to map out updates to your tool and resource signatures.

The Affordable AI Agents

Médéric Hurier (Fmind) — Thu, 25 Jun 2026 11:23:59 +0000

As AI agents transition from isolated developer experiments into production-scale workflows, engineering organizations are waking up to a sobering financial reality: the cost of running AI systems scales linearly, not logarithmically.

In traditional software engineering, scaling a platform reduces the marginal cost per transaction toward zero. With agentic architectures, however, every loop, file traversal, and API call incurs a direct token cost.

At one of my enterprise customers, with a distributed engineering team of 5,000 developers, we recently lived through the consequences of this shift. WhenGitHub Copilot transitioned to strict usage-based billing (UBB) on June 1, 2026, it triggered a massive 5x cost increase in a single month. Background agents got caught in unoptimized autonomous debug cycles, consuming compute at machine speed and turning a promised productivity gain into an infrastructure budget emergency.

We haven’t ditched GitHub Copilot yet, but this bill shock forced our hand. We initiated a deep evaluation of alternative options, focusing heavily on self-hosted open-weights models running on our Google Cloud Platform (GCP) infrastructure.

To establish a path to genuine ROI, we had to apply strict Cartesian FinOps rigor to our AI token consumption. This article is a RETEX (Return on Experience) on evaluating managed SaaS APIs, GCP self-hosted infrastructure, and decentralized local execution to limit the financial bleeding.

Photo by Sasun Bughdaryan on Unsplash

1. The Collapse of VC-Subsidized Subscriptions

Flat-rate subscriptions were venture-backed land grabs. They were never a sustainable long-term option for agentic workloads, and they are now collapsing under the computational weight of autonomous loops.

The scale of this subsidization was staggering.Leaked financial disclosures (widely discussed in developer spaces like thisArs Technica thread) show that OpenAI spent $34 billion against $13 billion in revenue in 2025 — yielding an operating loss of $21 billion. Most of this capital flowed directly to infrastructure providers like Microsoft and NVIDIA.

Why our bill spiked: Previously, heavy Copilot usage was governed by a flat allowance of about 300 requests per user. Under the new UBB model, that was replaced by a pooled allowance of “AI Credits” (1 credit = $0.01) based on raw token throughput. A massive 30,000-token codebase ingestion used to count as one request. Today, that single agentic run drains dollars from the shared credit pool in days.

Data from theRamp AI Index (June 2026) reveals a profound polarization in corporate spend resulting from this shift:

The Median Company: Spends $11 per employee/month (mostly human-in-the-loop chat).
The Top 10%: Spends $611 per employee/month.
The Top 1%: Spends a massive $7,449 per employee/month.

A human developer is restricted by biology. Autonomous agents running parallel iterations are not.

2. The Managed SaaS Baseline

To rigorously evaluate our GCP self-hosting and local alternatives, we first needed to establish a pure API baseline. Our estimated workload for our standard agentic IDE setup is 1.85 million prompt iterations per month (5,000 developers × ~17 prompts per active workday).

Our baseline utilized the highly efficientGoogle Gemini 3.5 Flash API on Vertex AI. Standard pricing is $1.50 per 1M input tokens and $9.00 per 1M output tokens.

Let’s calculate the economics for a standard codebase query (10,000-token input, 2,000-token output):

Input cost: $0.0150
Output cost: $0.0180
Total cost per query: $0.0330

At 1.85 million queries, our baseline SaaS cost is $61,050 per month. This is mathematically sound and reflects a mature IDE doing continuous context injection and proactive suggestions.

However, running this exact same workload on premium flagship models quickly triggers budget overruns:

Claude 4.8 Opus ($5.00/M in, $25.00/M out): Inflates the bill to $185,000 / month.
Claude Fable 5 ($10.00/M in, $50.00/M out): Balloons the cost to $370,000 / month.

At these prices, an unoptimized sub-agent looping indefinitely in the background ceases to be a developer friction and becomes a board-level issue, as highlighted by Fortune reporting on Uber exhausting its entire 2026 AI budget in just four months on Claude coding tools.

3. The Challenges of Self-Hosting

Confronted with the risks of runaway API bills, our infrastructure team evaluated self-hosting open-weights models on Google Kubernetes Engine (GKE). SOTA models like Zhipu AI’s GLM-5.2 are rapidly closing the gap with proprietary giants.

However, a strict FinOps analysis reveals that self-hosting is not a silver bullet: it simply replaces a variable API bill with a massive, fixed infrastructure baseline. Based on a standard 730-hour cloud month , here are the real cluster economics:

Gemma 4 26B MoE : Served on cost-efficient GCP g2-standard-48 nodes (4x NVIDIA L4, 96GB VRAM) at $4.00/hr. An autoscaling cluster averaging 4 active nodes costs 4 × 730 × $4.00 = $11,680 per month.
Qwen3-Coder-Next (80B MoE): The 92GB FP8 runtime footprint causes immediate Out-Of-Memory (OOM) failures under concurrency on standard L4 nodes (which max out at 96GB of heavily fragmented VRAM). Because GCP does not offer “single-GPU” rentals for its flagship H100/H200 instances, hosting this requires falling back to an a2-ultragpu-2g instance (2x NVIDIA A100 80GB GPUs, 160GB total VRAM) at $10.14/hr. Averaging 3 active nodes costs 3 × 730 × $10.14 = $22,206 per month.
GLM-5.2 (744B MoE): Its massive footprint makes it physically impossible to run on standard 40GB GPU instances. Even aggressively quantized to INT4, the weights alone consume ~372GB of VRAM. Hosting it with a usable 1M-token KV cache demands high-end a2-ultragpu-8g instances (8x NVIDIA A100 80GB GPUs, 640GB total VRAM) at ~$40.55/hr. Averaging 3 active nodes scales the cluster bill to 3 × 730 × $40.55 = $88,804 per month — a massive premium over our managed SaaS baseline.

Committed use contracts can significantly reduce infrastructure bills by locking in lower compute rates. However, this demands high FinOps maturity: organizations must accurately forecast long-term AI usage and strictly commit the company to specific hardware families to avoid wasting budget on unused or obsolete GPUs.

The Hidden TCO: Managing a GKE LLM gateway requires at least 1–2 ML Platform Engineers to debug GPU drivers, handle routing, and optimize execution. Factoring in their fully loaded salaries ($20,000–$40,000/month) completely erases the raw compute savings of hosting mid-tier models like Gemma.

4. The Local Execution Fallacy

If centralized GCP self-hosting carries high overhead, what about decentralizing to developer workstations? We tested runningGemma 4 12B andQwen 3.7 locally on Apple Silicon M4 Macs. While this successfully bypasses cloud costs, it introduces severe bottlenecks to developer velocity:

1. macOS Memory Allocation Limits

Apple Silicon shares unified memory dynamically between the CPU and GPU. By default, the Metal API restricts GPU allocations via the recommendedMaxWorkingSetSize property to ~70% of physical RAM to prevent OS starvation. On a 32GB Mac, this leaves a hard VRAM ceiling of ~22GB. Attempting to force-override this limit locks wired memory that cannot page to disk, inevitably leading toApple MLX kernel panics and system crashes when developers multitask.

2. The Prefill Latency Bottleneck (The Flow Killer)

Prompt ingestion (the prefill phase) is heavily compute-bound. Because a base M4 chip lacks the compute density of a datacenter GPU, ingesting a standard 10,000-token codebase context locally takes 45 to 60 seconds.

Compare this directly to our baseline: Google’s TPU infrastructure processes that exact same 10,000-token prefill via the Gemini 3.5 Flash API in roughly 1 to 2 seconds. Waiting a minute for your local agent to “read” your code completely shatters the developer’s flow state.

3. The Bandwidth Ceiling

Once prefill completes, generation is memory bandwidth-bound. A base M4 chip has 120 GB/s of unified memory bandwidth. Pushing a 12B parameter model (quantized to roughly 8GB) across the bus establishes an absolute physical generation ceiling of ~15 tokens per second (120/8). No software framework optimization can bypass physical hardware limits.

Distributing quantized weights to endpoints and triaging local crashes adds an estimated IT maintenance overhead of 2 hours per month per developer. Combined with the lost productivity of 60-second wait times per prompt, the decentralized savings are a total illusion.

The Harsh Reality : With Appleconfirming price increases on its laptops and theglobal shortage of RAM, this hardware-dependent approach is simply not scalable. It is financially unfeasible to provision expensive, maxed-out Macs to every single developer across a 5,000-person engineering organization just to support local inference.

Furthermore, moving AI execution to individual workstations creates a decentralized black box. It completely strips away the centralized telemetry, usage tracking, and auditability required for enterprise security and strict FinOps compliance.

5. Our Architectural Playbook Moving Forward

Based on our evaluation of GCP infrastructure versus managed APIs and local execution, we stopped treating AI hosting as a binary choice. To navigate the new token economic realities, we propose a staged, hybrid roadmap:

Optimize context footprint with managed APIs first: For new use cases, we keep capital costs low by leveraging standard managed APIs. This is the easiest and most convenient way to experiment with LLMs and quickly adapt the model to the user context.
Classify workloads and route queries by task complexity: We treat LLMs like consultants. We recommend using ultra-premium flagship models (like Claude 4.8 Opus) exclusively for complex architectural design or security audits. Conversely, standard code completions, minor edits, and debugging queries are strictly routed to fast, cost-efficient mid-tier models (like Gemini 3.5 Flash or Claude 4.6 Sonnet).
Leverage enterprise subscriptions cautiously with growth margins: We haven’t migrated off Copilot yet because it still offers predictable seat-based budgeting in the short term. However, we are investing in providers willing to keep subscription-based pricing, knowing we need to have clear and long-term contracts to guarantee these costs and capacity.
Host selective open-weights models for high-frequency automation: Our GCP evaluation proved that self-hosting makes financial sense primarily for mature and predictable use cases. We can provide capacity for tasks like AI coding or day-to-day automation using models like Gemma 4. This caps our infrastructure cost on tasks running 24/7, keeping them completely off the pay-per-use meter.
Factor in the hidden hardware, latency, and personnel TCO: Before migrating any workload, we account for the full operational cost. Decoupling from SaaS APIs to run LLMs on local developer Macs introduces workflow-destroying latency bottlenecks, while GKE hosting requires specialized ML platform engineers. We only shift workloads when the ROI justifies the maintenance overhead.

The era of all-you-can-eat AI and token maxxing is over. As open-weights models close the performance gap with proprietary APIs, designing a hybrid infrastructure is the only path to long-term model independence and predictable costs.

How is your engineering team handling the shift to usage-based AI billing? Are you sticking with GitHub Copilot, evaluating GCP self-hosting, or testing local models? Let me know in the comments below or reach out to me directly here.

Agent Evolutions: Stop Guessing the Design — Evolve It

Médéric Hurier (Fmind) — Mon, 01 Jun 2026 18:59:29 +0000

Most coding-agent tasks have one right answer hiding behind a workflow. “Add password sign-in.” “Fix the off-by-one in the pagination cursor.” “Refactor this handler to use the new client.” The job is to converge — pick the path, drive it to done, ship the diff. That is the world agent-levers lives in.

Some tasks aren’t shaped like that. “Which prompt wins?” “Which caching strategy is fastest?” “Which library shape is friendlier to call from a worker?” There is no single correct path. There are five plausible ones, the differences are not obvious from inspection, and the only honest way to pick is to measure. The shape of the work is divergent — branch out, evaluate, keep what works.

I kept reaching for that second shape and finding nothing on the shelf. So I built agent-evolutions — a small set of Agent Skills that turn a coding agent into a budgeted genetic search over a design space, with verifiable scoring at every step.

This is the fourth post in a thread on the shared .agents/ ground, after supagents, agent-docs, and agent-levers. Same bet, different question: levers ask “did we build it right?”, evolutions ask “did we pick the right thing to build?”

Agent Evolutions: Genetic exploration of solution spaces, with verifiable scoring — https://github.com/fmind/agent-evolutions

The design-by-intuition tax

Three failure modes I keep watching teams pay for — including my own:

The five-minute eyeball test. Two prompts on the screen, both look reasonable. One person prefers the terser one; another prefers the structured one. The team picks whichever was authored by the loudest reviewer. Three weeks later a quiet regression appears on a slice of traffic nobody A/B’d against.

Taste vs. taste. “Which client shape should we expose — fluent builder or plain options bag?” Six people, six opinions, zero numbers. The argument lasts a week. Whatever ships is then defended for years because rolling it back is more expensive than living with it.

The benchmark that becomes a vote. “Which caching strategy is fastest?” Real, mechanical, measurable. Then someone runs one manual test, on one workload, and reports a winner. Nobody asks how sensitive the result is, nobody runs the loser to confirm, nobody bothers with a second seed.

These all share a common shape: a design question with multiple plausible answers and at least one mechanical measure — and we answered it with intuition anyway. The cost of guessing wrong is rarely visible at decision time. It shows up months later as a refactor.

What I wanted was a tool that made the right move — generate variants, measure, evolve, pick — cheaper than the wrong move. That is the gap agent-evolutions is aimed at.

Convergent and divergent loops, side by side

The clearest way I can frame the relationship to agent-levers is by the shape of the loop.

Levers is convergent. One workspace, one diff, one verifier set, plan → do → check → act in a sequential chain. The question being answered is how do we drive this single task to done. The whole machine is tuned to finish.

Evolutions is divergent, then convergent. N parallel workspaces (one per variant), N independent results, batched generations that learn from the previous batch, a final pick at the end. The question is which of several plausible designs measures best. The machine is tuned to explore first, then collapse.

Both loops live on the same .agents/ ground, both use file-based state, both let any compliant coding agent drive them. They are not competitors — they are complementary tools for different question shapes. Most non-trivial work, in my experience, is mostly levers and occasionally evolutions. The trick is knowing which kind of question you’re holding.

Genetic search, not random sampling

The first thing people picture when I say “spawn variants in parallel and pick the best” is brute-force Best-of-N: fan out thirty prompt mutations, score them, keep the top one. That is sampling. It is blind, and it scales badly — doubling the budget barely improves the answer because every sample is drawn from the same flat distribution.

Agent-evolutions runs a genetic loop instead:

Generation 1 seeds a small, diverse set of hypotheses — qualitatively different approaches, not minor variants of one idea.
Generation 2+ mutates the top survivors, crosses pairs over, and injects a small share of fresh exploration variants to avoid premature collapse.
Batches are sized to budget.parallel , deliberately, so the loop can learn between batches instead of fanning out blindly.
Stopping is automatic: budget cap, wall clock, score plateau across N generations, or no survivors.

Each generation conditions on what worked in the previous one. That is the qualitative difference — and the reason a small directed search routinely beats a much larger random one. The skill’s documented optimize cli startup walkthrough finishes in 24 evaluated variants across 4 generations, with the winner from generation 2 — not generation 1.

Three commands, three phases

The whole surface area is three slash commands, one per phase:

Capture — /new-agent-evolution discusses the brief (objective, gates, rubric, scope, budget) and commits it when you agree.</li> <li>Run — /run-agent-evolution <id> plans a batch, spawns variants in parallel, ingests each result.json, scores, evolves, and stops on a condition.</li> <li>Apply — /apply-agent-evolution <id> diffs the winner workspace against the live repo, confirms with you, copies it in, and optionally re-runs gates against the repo.</li> </ul> Diff winner workspace vs the live repo → confirm → copy in → optionally re-run gates against the repo. The state machine is the one design choice I find myself most pleased with. There is no step counter, no pause flag, no “current phase” field. Phase is derived from the presence of fields in evolution.yaml: <ul> <li>empty variants → ready to run</li> <li>has variants, no winner → running</li> <li>has winner, no applied → evaluated</li> <li>has applied → done</li> </ul> Each skill reads the yaml on entry, infers what phase the evolution is in, and refuses to run outside its own. Capture won’t recreate a brief that already exists. Run won’t re-rank a finished evolution. Apply won’t run without a winner. The skills are stateless; the disk is the source of truth. Crash mid-batch, restart, and the next invocation picks up exactly where the files left off. <h3> <a name="the-contracts-that-make-the-scoring-honest" href="#the-contracts-that-make-the-scoring-honest" class="anchor"> </a> The contracts that make the scoring honest </h3> A genetic loop with sloppy scoring is just an expensive random walk. Agent-evolutions leans hard on three contracts that keep selection grounded. Gates are binary. Each gate is a shell command. Exit 0 means pass, anything else means fail. A variant that fails any gate is excluded from ranking entirely — no partial credit, no negotiation. Gates are how the framework refuses to compare “fast but broken” against “correct and slow”. The rubric is numeric. Each rubric axis has a direction (minimize or maximize) and a weight. The composite score is a rank-normalized weighted mean across axes — robust to outliers, well-defined under partial data, and crucially recomputed on read by the run skill, never persisted in the yaml. The yaml stores raw rubric values; the leaderboard view derives from them. You cannot accidentally enshrine a stale score because there is no stored score to enshrine. Criteria are frozen up front. This is the load-bearing rule. Gates and rubric axes are agreed during the Capture phase and then locked. The run skill refuses to add a new rubric axis after results come in. Without that rule, the evaluator silently turns into a rationalization engine — adding the axis on which the variant the agent likes anyway happens to win. The unstated cousin of these contracts: no silent retries, no narrative scoring. A failing gate stays failed. A missing measurement is missing, not interpolated. The leaderboard is allowed to be ugly. <h3> <a name="the-filebased-subagent-contract" href="#the-filebased-subagent-contract" class="anchor"> </a> The file-based sub-agent contract </h3> Each variant runs as its own sub-agent, in its own workspace (a git worktree by default), starting from HEAD. The contract between the parent and each child is not chat — it is a file. <img src="https://dev-to-uploads.s3.amazonaws.com/uploads/articles/my1vunokqhl3xrdf98ma.png"/> Relationship between Agent Evolutions Concepts Every variant sub-agent writes variants/v<n>/result.json, validated against a <a href="https://github.com/fmind/agent-evolutions/blob/main/result.schema.json">JSON Schema</a>. The parent reads files, not chat output. Four properties fall out of that decision: <ol> <li>Crash-survivable. A child that finishes its work before the parent gets a chance to read its reply still leaves its result on disk. Partial batches don’t disappear.</li> <li>Audit trail. Every variant’s exact result lives in git. You can re-rank a historical evolution from its files alone, weeks later.</li> <li>No JSON-in-chat parsing. The classic failure mode where a sub-agent’s reply is “JSON-ish” — with a friendly paragraph in front, or three backticks, or a stray comma — never enters the pipeline. The schema validates a file.</li> <li>Parallelism stays clean. Six sub-agents writing to six different files do not pollute one shared transcript. No interleaved thinking, no merge step.</li> </ol> I would not bother spelling this out if I had not lost an afternoon, more than once, to the JSON-in-chat trap on a previous prototype. File-based sub-agent I/O is the kind of detail that looks pedantic on slide one and saves the whole loop by slide four. <h3> <a name="a-walkthrough optimize-cli-startup" href="#a-walkthrough optimize-cli-startup" class="anchor"> </a> A walkthrough — optimize cli startup </h3> The shipped example trims a Node.js CLI’s cold-start time on — version. The brief pins one gate set (build green, tests green) and one rubric axis (median of five hyperfine runs, minimize). <div class="highlight"><pre class="highlight console"><code>$ /new-agent-evolution "optimize cli startup" → discusses objective, gates, rubric, scope, budget → on "looks good", commits .agents/evolutions/1-optimize_cli_startup/ $ /run-agent-evolution 1 → gen 1: seeds 6 diverse hypotheses — lazy-load, build-time inline, plugin-registry map, polyfill strip, prebundled arg-parser, dotenv short-circuit → spawns 6 sub-agents in parallel; each materializes a worktree, implements its variant, runs gates, writes result.json → ranks: v2 (build-time inline) → 142.0 ms · v1 (lazy-load) → 184.2 ms v4 fails G2 (test regression) → excluded → gen 2: mutates v2 → v7 (v2 + tree-shake help chunk), mutates v1 → v8, crosses v2×v3, adds 1 explore → ... → plateau at gen 4 — top score unchanged across 2 generations → stops at 24/30 evaluated; winner v7 at 98.6 ms $ /apply-agent-evolution 1 → diffs variants/v7/workspace vs live src/, tsdown.config.ts, package.json → "Confirm to apply, or reply abort" → "looks good" → copies files in; re-runs G1 + G2 against the live repo; both green </code></pre></div> The moment I find the most instructive is the winner. v7 came from generation 2 — it is v2 plus a tree-shake tweak that only made sense once v2 had won the first round. Nobody on the team would have written v7 from scratch in generation 1. Evolution found it because the loop conditioned on v2’s win before composing the next batch. That is the entire pitch of genetic search over sampling, in one trace. <h3> <a name="where-this-skill-set-should-not-run" href="#where-this-skill-set-should-not-run" class="anchor"> </a> Where this skill set should not run </h3> Three patterns where I deliberately do not reach for evolutions, and the skill refuses to seed a brief when it spots them: <ul> <li>The task is a one-line bug fix, rename, or doc edit. Just do it. The overhead of a genetic loop is paid in seconds; the task is paid in seconds. The ratio is wrong.</li> <li>There is no mechanical measure — not even a proxy. “Make this prose more engaging” has no shell exit and no number. Use a normal review.</li> <li>The user has already decided the design. “Implement X.” is a levers job, not an evolutions job. Don’t manufacture a search space just to use the tool.</li> </ul> If a brief tries to start without a gate or a rubric axis, the Capture skill pushes back: “we need at least one mechanical check before variants make sense.” Either we co-author one, or the evolution doesn’t get a folder. That refusal is on purpose — it is the load-bearing reason variants ranking means something at the end. <h3> <a name="the-leverage-axis" href="#the-leverage-axis" class="anchor"> </a> The leverage axis </h3> Agent-levers makes one hour of human attention move more — clearer briefs, typed verifiers, lessons that compound, the same fulcrum logic <a href="https://fmind.medium.com/agent-levers-a-plan-do-check-act-loop-that-makes-coding-agents-finish-what-they-start">I wrote about before</a>. The asymmetry is human effort in, shipped work out. Agent-evolutions sits on a different axis. The input is not human attention, it is compute: six or twelve or twenty-four sub-agents running in parallel, each spending tokens on a variant of the same design question. The output is a defensible answer to which design to ship. The fulcrum is the same shape — small effort on one end multiplies into directed work on the other — but the lever is bolted to a different wall. Most teams, today, are spending compute the way a 1990s team spent CPU time on a build: cautiously, one job at a time. The price has dropped, the parallelism has arrived, and the workflows have not caught up. Genetic search on coding tasks is one of the places that gap is widest. The practical nudge I’ll leave you with: next time a which design wins? thread starts on Slack, count the design points raised against the design points measured. If the ratio is wildly skewed toward opinion — and it usually is — that is the shape of a question agent-evolutions was built to swallow. <h3> <a name="the-three-install-paths-mirror-the-three-coding-agents" href="#the-three-install-paths-mirror-the-three-coding-agents" class="anchor"> </a> The three install paths mirror the three coding agents: </h3> <div class="highlight"><pre class="highlight shell"><code># Claude Code /plugin marketplace add fmind/agent-evolutions /plugin install agent-evolutions@agent-evolutions # Gemini CLI gemini extensions install fmind/agent-evolutions # Antigravity CLI agy plugin install https://github.com/fmind/agent-evolutions # GitHub Copilot copilot plugin marketplace add fmind/agent-evolutions copilot plugin install agent-evolutions@agent-evolutions </code></pre></div> To run these skills in <a href="https://opencode.ai/">OpenCode</a>, place or clone the skill directories under <code>.agents/skills/</code> (for project scope) or <code>~/.agents/skills/</code> (for global scope). Then, inside a project: <div class="highlight"><pre class="highlight shell"><code>/new-agent-evolution <title> # capture the brief (Session 1) /run-agent-evolution <id> # drive the genetic loop (Session 2) /apply-agent-evolution <id> # land the winner (Session 3) </code></pre></div> The repository is at <a href="https://github.com/fmind/agent-evolutions">github.com/fmind/agent-evolutions</a>. The <a href="https://github.com/fmind/agent-evolutions/tree/main/examples/evolutions">examples/evolutions/</a> directory ships the full optimize cli startup walkthrough — brief, variants, scored leaderboard, applied diff — so you can read what the artifacts look like before running anything yourself. Pick a real question. Give it gates and a rubric. Let the loop run while you make coffee. The answer it comes back with will not be the one you would have written on a whiteboard — and that, more often than not, is the point.

Agent Levers: A Plan-Do-Check-Act Loop That Makes Coding Agents Finish What They Start

Médéric Hurier (Fmind) — Mon, 25 May 2026 05:19:47 +0000

A coding agent is only as useful as the spec you give it. That sentence sounds like a truism until you watch it play out for an afternoon.

Type too little — “add password sign-in” — and the agent improvises. It picks a JWT library you don’t use, skips rate-limiting, ships a flow that works on the happy path and fails the moment you blow on it. Type too much — every constraint, every test name, every file path — and you’ve done the agent’s homework. You are the bottleneck, not the multiplier.

I have been trying to find the shape of the work between those two extremes for months. I built agent-levers — a small set of Agent Skills that give the agent a structured plan → do → check → act loop on disk — to do the structuring work I kept doing by hand.

This is the third post in a thread about the shared .agents/ ground, after supagents (one subagent source, many targets) and agent-docs (a curated, local doc reference). Same bet, different layer: this one is about the workflow an agent runs inside a non-trivial task.

Agent Lever: Multiply the agent’s force, divide the human’s effort — https://github.com/fmind/agent-levers

The two failure modes of unguided agents

After enough sessions, I started noticing the same two failure patterns, no matter which coding agent I drove.

The agent claims success it didn’t verify. It says “I implemented the rate limiter,” shows a diff, and moves on. You ask “did the test pass?” and discover it never ran, or it ran in an ad-hoc shell, or — the meanest version — it passed in the agent’s session and fails the moment you re-run it from a clean terminal. The status report isn’t lying. It’s just not grounded in a verifier.

The agent runs away. The first test fails. The second attempt fails. The third attempt fails. Forty minutes later, the diff is twice as large as the original task, and nothing is green. There is no internal “I should stop and ask” trigger because the agent is doing what it was told: keep trying until the test passes.

Both failure modes have the same root cause: the loop is implicit. The agent makes up the loop on the fly. Each session improvises a new plan, a new sense of done, a new sense of when to give up.

The fix I kept reaching for, before I built this, was structure I imposed by hand: a numbered checklist in the prompt, an explicit “run this command after each change,” a polite “stop and ask if you’ve failed three times in a row.” It worked. It also lasted exactly one session, because the next task started from a blank prompt.

Agent Levers is that structure, externalized. Once.

The lever metaphor

The name is the bet. A lever multiplies force on one end while reducing effort on the other. The human pushes on the short side — a one-line brief, plus answers to a handful of clarifying questions — and the agent lifts the long side: investigation, planning, execution, verification, learning.

The shape of the work is the Deming cycle, borrowed from process engineering and applied to a different kind of factory: plan → do → check → act. Every non-trivial coding task already follows that shape; it just usually lives in the agent’s head, where you can’t audit it. The point of the framework is to push the loop onto disk, where each step is an artifact that can be reviewed, paused, resumed, and continued by a different session.

Relationship between Coding Agents and Agent Levers

Four commands, one folder

The whole surface area is four slash commands, three of them user-facing and one of them an internal dispatcher you mostly forget exists.

/lever-init — bootstraps the framework on a fresh repo.
/lever-new — captures intent. The first turn is chat-only — clarifying questions, proposed enhancements, a draft brief inline. No files land until you agree.</li> <li>/lever <id> — runs the chain. Plan → do → check → act, autonomously until a pause or a terminal state.</li> <li>/lever-status [<id>] — read-only inspector; lists levers, shows one in detail, or cancels one.</li> </ul> Everything else lives in two files, per lever, on disk: a lever.yaml that holds the machine state, and a LEVER.md that opens with a TL;DR and grows narrative sections as each step runs. Half a day of agent work, audited in twenty lines. <h3> <a name="the-twosession-split" href="#the-twosession-split" class="anchor"> </a> The two-session split </h3> The thing I keep coming back to is the deliberate split between /lever-new and /lever. /lever-new is high-context: you and the agent in chat, narrowing down what you actually want. The agent reads project conventions, asks clarifying questions, proposes enhancements you didn’t ask for but probably want (“you specified Google OAuth — want GitHub too?”), drafts the brief inline. No files land until you say “looks good.” /lever is mechanical: a fresh session, reading the state, executing the matching step, advancing the pointer. The dispatcher loads only the step it needs — never all four at once. The agent’s context stays clean across the chain. The two-session split has a property I value enough to call out: brief-time is the only place the human is in the loop. Once you run /lever 1, the chain runs to completion (or to a structural pause) without re-asking what you wanted. If the brief was crisp, you don’t see the chain again until there is a diff to review. I cannot overstate how much I prefer this to the “agent asks twenty questions while implementing” rhythm. The cost of a sharp brief is paid once, up front, in the cheapest part of the process. Everything after compounds on that investment. <h3> <a name="the-four-steps-briefly" href="#the-four-steps-briefly" class="anchor"> </a> The four steps, briefly </h3> Plan reads the brief, investigates the codebase and external docs itself — grep, reading tests, pinning dependency versions, fetching authoritative docs — and writes a small set of acceptance criteria, each paired with a typed verifier (a shell command, a screenshot to confirm, or a manual rubric). It also sets a budget — iterations, minutes, failed-streak — so the next step has an explicit leash. The hard rule on verifiers is: test the behavior, not the agent’s past actions. A criterion that says “function loginHandler exists in src/routes/auth.ts” is bookkeeping — the agent can satisfy it by writing the function and then grepping its own diff. A criterion that says POST /auth/login returns a JWT on valid credentials is verification — it passes when the handler works. Do drives the criteria one at a time. It picks the first failing one, makes the smallest change that should flip it (TDD-style by default for shell verifiers), runs the verifier, and logs the result. Out-of-scope ideas get parked, not silently bundled into the diff. When the budget runs out, the loop stops with state on disk — raise the cap, narrow scope, or hand off; prior passes stay green. Check is the step that earns the framework its keep. It re-runs every verifier from a fresh shell — not the agent’s session — to catch criteria that secretly relied on cached state. Then it does something I have not seen anywhere else: a chain audit. It walks the trail from brief to plan to events to diff, asking at each handoff whether the next step honored the previous one. The silent-killer audit is the last hop — does the diff actually deliver what the brief asked for, or did the agent build something adjacent? Tests can pass while intent quietly drifts; the chain audit is what catches that. Act runs only if check surfaced hints — moments where a decision deserved more guidance, or where a recurring pattern started to show. It picks the right surface for each: a project rule lands in AGENTS.md, a skill flaw lands in the skill, work that isn’t a rule becomes a follow-up /lever-new. The edits arrive as proposals in the working tree, reviewed in the same PR as the implementation. The next lever inherits the rule, not the mistake. This last property is the one I find most underappreciated: the framework has a built-in mechanism for the agent’s workflow to improve. A gotcha that surfaces three times in three separate levers earns its way into AGENTS.md by being staged three times. You don’t have to remember to tell the agent about it next session. <h3> <a name="a-walkthrough-on-a-real-task" href="#a-walkthrough-on-a-real-task" class="anchor"> </a> A walkthrough on a real task </h3> Two human inputs, two sessions, one finished feature. <div class="highlight"><pre class="highlight console"><code>$ /lever-new add password sign-in → first turn: chat-only — clarifying questions, proposed enhancements, draft brief → "rate-limit policy for /auth/login? OAuth uses 5/min/IP — match it?" → "looks good" → captures the brief on disk → "Brief captured. In a new session, run /lever 1 to start the chain." # Fresh session, hours or days later. $ /lever 1 → plan: investigates the auth + middleware code, writes 4 criteria with shell verifiers → do: C1 pass · C2 pass · C3 fail (limiter not wired) · C3 pass · C4 pass → check: rerun from fresh shell — all green chain audit: Brief→Plan · Plan→Do · Do→Result · Result→Intent — all pass 2 hints surfaced → act: hint 1 → AGENTS.md +5/-0 (explicit "attach middleware" sub-step in TDD) hint 2 → recommend /lever-new enforce_route_middleware_lint → "Ran: plan → do → check → act. 4/4 passed. 2 hints landed. Done — diff is staged." </code></pre></div> The interesting moment is the limiter miss at C3 — the kind of off-by-one that on a normal “agent, implement this” run becomes a Slack thread two days later, when QA notices the rate limit doesn’t fire. Here, it surfaces as a single fail row, recovered in the next iteration, lifted into a hint by check, and codified as a rule by act. That is the whole pitch in one trace: the loop catches its own mistakes before the human sees them, and the lessons compound for next time. <h3> <a name="install-and-try-it" href="#install-and-try-it" class="anchor"> </a> Install and try it </h3> The three install paths mirror the three coding agents: <div class="highlight"><pre class="highlight shell"><code># Claude Code /plugin marketplace add fmind/agent-levers /plugin install agent-levers@agent-levers # Gemini CLI gemini extensions install fmind/agent-levers # GitHub Copilot (CLI) copilot plugin marketplace add fmind/agent-levers copilot plugin install agent-levers@agent-levers </code></pre></div> Then, inside a project: <div class="highlight"><pre class="highlight shell"><code>/lever-init # bootstrap the framework /lever-new <title> # capture a new task (Session 1) /lever <id> # run the chain (Session 2) /lever-status [<id>] # inspect or cancel </code></pre></div> The repository is at <a href="https://github.com/fmind/agent-levers">github.com/fmind/agent-levers</a>. The <a href="https://github.com/fmind/agent-levers/tree/main/examples/levers">examples/levers/</a> directory ships two worked walkthroughs — a happy path and a scenario where check routes back to do — so you can see what the artifacts look like before you run anything. <h3> <a name="the-lever-effect" href="#the-lever-effect" class="anchor"> </a> The lever effect </h3> A real lever’s mechanical advantage is a ratio: force out per unit of effort in. For a coding agent, the equivalent is verified, intent-aligned work shipped per minute of human attention spent. Clear briefs, typed verifiers, bounded loops, on-disk state, lessons that compound — each one bends that ratio in the same direction. We are not trying to build an agent that needs us less. We are building the fulcrum that lets the same hour of human attention move more. Give <a href="https://github.com/fmind/agent-levers">agent-levers</a> a try — the lever is real when you can feel the asymmetry.

Agent Docs: Answer Locally Before the Web — A Shared Reference for Every Coding Agent

Médéric Hurier (Fmind) — Thu, 14 May 2026 06:41:15 +0000

Pair-program with a coding agent for an afternoon and you start noticing a quiet, recurring tax. Every time the agent reaches for a flag, a config field, or a CLI subcommand, it fires off a web search. Then another. Then a third when the second one returned a 2023-era blog post for a tool you upgraded last week.

Each round-trip is a few seconds, a few tokens, and — worse — a chance for the agent to pick a plausible-looking answer from the wrong version of the docs. Multiply that by every session, every contributor, every agent on the team, and the tax is no longer quiet.

I built agent-docs to make my agents answer locally before they answer remotely. It is a small set of file-based Agent Skills that seed, read, and refresh a curated .agents/docs/ reference for the tools your project actually uses. One install, three commands, three coding agents (Claude Code, Gemini CLI, GitHub Copilot) — the same answer for the same question, every run.

Agent Docs: Project Docs that Answer Locally — https://github.com/fmind/agent-docs

This is the follow-up to my previous post on supagents — same bet on the shared .agents/ ground, applied to a different layer of the stack.

The hallucination tax has a quieter cousin

When people talk about LLM failure modes, they usually mean hallucination — confident statements that turn out to be invented. That’s real. But there’s a quieter failure mode I see far more often in practice: lossy retrieval.

The agent doesn’t make things up. It does its honest best and lands on the wrong page. A search for “Gemini CLI hooks” returns a blog post that pre-dates the feature. A search for “Cloud Run revisions” returns the 2022 docs, before the rewrite. The agent reads what’s in front of it, summarizes correctly from the source it found, and produces an answer that is technically faithful to a stale or low-quality input.

You don’t catch lossy retrieval by reading the agent’s output. You catch it three turns later, when the implementation doesn’t compile against the current SDK and you trace it back to a flag that was renamed in v0.4.

The fix that occurred to me, after the third time the same agent web-searched the same gemini settings.json page, was almost embarrassingly simple: stop searching for what we already know. Pin the URLs once. Make every agent on the project read from the same shortlist before it touches the web.

The Code Wiki nudge

I won’t pretend I came up with the wiki framing in a vacuum. Code Wiki — a recent project out of Google Labs — was the nudge. The pitch resonated immediately: maintain a curated, version-aware knowledge base that a coding agent can query first, instead of asking it to re-discover the same facts every session.

What I wanted, though, was different in three specific ways. I wanted it local — committed to the repo, diffable in a PR, not behind a service. I wanted it scoped to the project — only the tools and services this codebase actually depends on, nothing else. And I wanted it to work across all coding agents I use daily, not just one.

So agent-docs is my take: a tiny on-disk reference set, owned by the project, read by any agent that respects the AGENTS.md convention.

What lives in .agents/docs/

After you run the gather skill, your project carries a small new directory:

.agents/docs/
├── INDEX.md
├── gemini-cli/
│ ├── DOC.md
│ └── HOOKS.md
└── cloud-run/
    └── DOC.md

INDEX.md is a one-line-per-topic dispatch table. Each DOC.md is the entry point for a topic, and large subsystems can split into sibling files (HOOKS.md, EXTENSIONS.md) with their own refresh clocks.

The crucial design choice is what each DOC.md is — and is not. It is a navigation map , not a copy of the docs. Concretely, every DOC.md carries:

A one-paragraph summary of the topic and where it fits.
A terse list of key concepts (settings file, slash commands, hooks, MCP servers).
A documentation map — the upstream sidebar, captured as one-line link entries grouped by section. Each entry is Page title — short hook on what’s there.
An optional Patterns section with paste-ready snippets, capped at five per topic, each tied to an inline _Source: …_ link.

The pattern I keep coming back to is: land the agent on the right upstream URL in one hop, then fetch upstream if it needs depth. Not every fact gets captured locally — only the navigation, plus a handful of high-frequency snippets when the team decides they’re worth it.

Three skills, one small loop

The whole thing is three skills. They are deliberately small and they compose into a loop you can reach for without thinking.

Relationships between Coding Agents, Skills, and Local/Remote Sources

/gather-agent-docs — seed the reference

/gather-agent-docs inspects your project’s manifests (package.json, pyproject.toml, go.mod, cloudbuild.yaml, apphosting.yaml, mise.toml) and picks three to eight real topics. It does not guess at what the project “might” use; it picks what the project declares.

For each topic, it fetches one upstream nav source — the docs sidebar, the README’s docs section, or the sitemap as a fallback — and writes a DOC.md with the navigation map mirroring how upstream organizes itself. INDEX.md gets one dated line per topic.

The default capture tier is intentionally light: title + URL + one-line hook for every page in the upstream nav. That’s it. Paste-ready snippets are opt-in (/gather-agent-docs deepen gemini-cli), capped at five per topic, and only added when the team actually reaches for them often.

/use-agent-docs — read before searching

This is the skill that earns its keep on every run. Before the agent reaches for the web on a topic that’s part of the project, it reads .agents/docs/INDEX.md, opens the matching DOC.md, scans the documentation map, and fetches the right upstream URL directly.

If the index is missing, it’s a no-op — the agent falls through to normal research. If a captured snippet covers the question, the agent uses it (each one carries its upstream source link, so it can verify). If the answer needs flag-level depth, it goes one hop upstream to a URL it already knows is the canonical one.

Crucially, this is the skill I do not have to remember to invoke. It’s wired as a trigger: “before web-searching for a project topic, check .agents/docs/”. Once installed, the agent reaches for it on its own.

/refresh-agent-docs — keep it honest

A curated doc set that is allowed to rot is worse than no doc set, because it lies with confidence. /refresh-agent-docs is the gardener.

Every DOC.md opens with YAML frontmatter:

---
last_verified: 2026-05-08
upstream_commit: 9f3c2b1
sources:
  docs: https://google-gemini.github.io/gemini-cli/
  repo: https://github.com/google-gemini/gemini-cli
  changelog: https://github.com/google-gemini/gemini-cli/releases
---

The refresh skill reads that metadata and tries cheap paths first. If upstream_commit matches upstream HEAD, the page is verified by definition — bump the date, move on. If the changelog has no entries newer than last_verified, same outcome. Only when those short-circuits miss does it fall through to a link-rot scan, then a full re-fetch.

The richer the frontmatter, the more refreshes complete in a single HTTP call. When a page can’t be re-verified this session, the skill stamps a visible > ⚠ Stale banner at the top so future agents see the warning before they trust the contents.

This is what I mean by honest staleness. The doc set is allowed to age — that’s fine — but the age is always declared, never hidden. The [YYYY-MM-DD] next to each topic in INDEX.md is the oldest verification date across the topic’s files, so the index shows the staleness floor at a glance.

A walkthrough on a real project

Here is what a typical session looks like, lightly compressed from a real run on a Cloud Run + Gemini CLI project:

$ /gather-agent-docs
  → inspects manifests, picks: gemini-cli, cloud-run, firebase-app-hosting
  → fetches one upstream nav per topic
  → writes .agents/docs/INDEX.md and 3 DOC.md files
  → "Seeded 3 topics under .agents/docs/. Review the diff before committing."

$ /gather-agent-docs deepen gemini-cli
  → adds up to 5 Patterns snippets to gemini-cli/DOC.md, each with _Source: …_
  → bumps last_verified

# Later, mid-session, the agent is asked to wire up a Gemini CLI hook…
$ "Can you add a pre-tool hook that blocks rm -rf?"
  → /use-agent-docs fires implicitly
  → reads INDEX.md, opens gemini-cli/DOC.md, scans the documentation map
  → finds gemini-cli/HOOKS.md, opens it, picks the snippet for pre-tool hooks
  → writes the hook against the current schema, not a 2024 blog post

# A month later…
$ /refresh-agent-docs gemini-cli
  → smart path: upstream_commit moved; scans changelog since last_verified
  → finds one entry touching hooks; re-fetches HOOKS.md's snippet sources
  → repairs two renamed links in DOC.md's documentation map
  → "gemini-cli: links repaired (DOC.md), snippet edits (HOOKS.md)."

The two things I notice consistently after running this for a few weeks:

Round-trips collapse. The “search → skim → search again” loop turns into a single fetch. The agent’s output shows up faster because there’s less network in front of it.
Answers stop drifting between sessions. Three contributors asking the agent “where is X configured?” get the same upstream page, because the agent reads the same map.

Local-first, on purpose

A few people asked me, when I described this, why I didn’t just point the agent at the upstream docs site directly and let it search. Two reasons.

First, scope. The upstream docs for any non-trivial tool are an ocean. The right answer for a given project is a narrow shoreline — the flags this team uses, the patterns this codebase follows, the canonical URL we trust. Curating the map shrinks the search space from “every page on the site” to “the dozen pages we actually touch”.

Second, commit-ability. .agents/docs/ lives in git. It travels with the code. It diffs in PRs. When a contributor updates the Gemini CLI version, the PR can include the refreshed map alongside the version bump, reviewed in the same place. A hosted service can’t be diffed in your PR.

There is a real cost: someone on the team has to run /refresh-agent-docs periodically, and someone has to decide when a snippet is worth capturing. That cost is the point. It is the same cost we pay to maintain a README.md that doesn’t lie — and we pay it because the alternative is worse.

Where this sits in the .agents/ stack

If you read my supagents post, the framing here will feel familiar. I keep finding the same pattern: a thing that should be one source, fragmented across N coding-agent harnesses, that we can unify in the shared .agents/ ground.

Supagents handles subagent personas — one markdown source compiled to .claude/agents/, .gemini/agents/, .github/agents/. Agent Docs handles project knowledge — one .agents/docs/ folder, read by any agent that follows the AGENTS.md convention (which now includes Claude Code, Gemini CLI, and GitHub Copilot).

These are two slices of the same bet: the future of coding agents is not a winner-takes-all framework. It’s a shared file-system layout, with small composable conventions, that every tool reads in its own way. The friction goes away when we stop reinventing storage formats and start respecting a common root.

Install and try it

The three install paths mirror the three coding agents:

# Claude Code
/plugin marketplace add fmind/agent-docs
/plugin install agent-docs@agent-docs

# Gemini CLI
gemini extensions install fmind/agent-docs

# GitHub Copilot (CLI)
copilot plugin marketplace add fmind/agent-docs
copilot plugin install agent-docs@agent-docs

The repository is at github.com/fmind/agent-docs. The examples/ directory ships a worked sample of what gather produces — two topics, one with a subtopic split — so you can see the output shape before you run it.

Small tools, on purpose

I keep coming back to the Linux philosophy when I build things in this space: small tools, one job, composable. Agent Docs is three skills (gather, use, refresh) that touch one folder (.agents/docs/) and respect one shared root (.agents/). That’s the whole surface area.

The bet is that this is enough. A curated map is cheaper than a clever retrieval system, the same way a README.md is cheaper than an auto-generated wiki. The reason README.md survived every documentation-platform fad for two decades is that it’s a flat file that travels with the code and reads correctly without a runtime. .agents/docs/ is the same shape, aimed at the agent instead of the human.

If you are running coding agents on a real project — and tired of watching them re-search the same SDK every afternoon — give it a try. If it saves you the third web round-trip on a Friday, it has earned its keep.

Supagents: One Source to Rule Your Coding Subagents

Médéric Hurier (Fmind) — Sun, 10 May 2026 19:30:48 +0000

The AI providers are in a horse race. Every quarter, a new model lands, a new harness ships, and the gap between “the best tool for this task” and “the best tool overall” keeps moving. As developers, we have already stopped picking sides — we pick the right tool for the job, and we switch between them constantly.

I noticed this pattern hardening in my own workflow. I drive Claude Code for deep refactors, Gemini CLI for long-context exploration, and GitHub Copilot for the IDE flow. Each one has carved out a niche. Locking myself to a single provider would be a serious productivity bottleneck.

The catch: every one of these tools has reinvented the same primitive — the subagent — and given it a slightly different shape. I got tired of maintaining the same persona five times.

So I built supagents: a single markdown source, compiled to every coding agent I use.

Compile a single AI supagent into multiple AI subagents — https://github.com/fmind/agent-supagents

The subagent fragmentation problem

Subagents are one of the best additions to modern coding agents in the last year. They isolate workloads, keep MCP servers and tools out of the main session’s context, and let you ship richer instructions through progressive disclosure. Claude Code has agents, Gemini CLI has them, Copilot in VS Code has them, Cursor has them, OpenCode and Kilo Code have them.

The persona I want is identical across all of them: “You are a code-investigation expert. You read first, edit never, and you cite file:line for every claim.”

The configuration is not. Each platform wants a different YAML frontmatter shape, a different directory layout, a different file extension. Claude wants tools: Read, Grep, Glob and a model field. Gemini wants kind: local and an mcp_servers block. Copilot wants target: vscode and a list of allowed models. The bodies are roughly the same prose, but the metadata diverges.

I tried hand-syncing for a while. It does not scale. You tweak the persona once on a Friday afternoon, forget to copy it across, and three weeks later you are debugging why “the same agent” behaves differently on two laptops.

The common ground that almost works

The good news is that the industry is converging on a shared root: the AGENTS.md file at the repository root, and the .agents/ directory next to it. GitHub now accepts AGENTS.md as a valid Copilot instruction file. Gemini CLI reads skills out of .agents/skills/. Claude Code, Cursor, and OpenCode all respect similar conventions.

This is real progress. A single AGENTS.md and a single .agents/skills/ tree can drive a Copilot session, a Gemini run, and a Claude Code job — without touching anything tool-specific.

But subagents have not landed in that shared ground yet. Each tool still keeps its agent definitions in its own private folder: .claude/agents/, .gemini/agents/, .github/agents/, and so on. There is no agents.md-equivalent for subagents.

That is the gap supagents fills.

How supagents works

Supagents is a small Python CLI. You write one markdown file per agent in .agents/supagents/.md (project) or ~/.agents/supagents/.md (global). The CLI compiles that source into one output per target tool, dropping each compiled file into the location the target expects.

One supagents source compiles into per-target agent files for Claude Code, Gemini CLI, GitHub Copilot, Cursor, OpenCode, and Kilo Code

The design is deliberately small. There are only two layers in the source file: shared frontmatter, and per-target blocks. A handful of UPPERCASE directives let you bend the output without leaving the file.

The source file

Here is a real source for an investigation agent:

---
name: code-investigator
description: Explore unfamiliar codebases without editing.

CLAUDE:
  model: sonnet
  tools: Read, Grep, Glob, Bash

GEMINI:
  kind: local
  tools: ["*"]
  mcp_servers:
    context7:
      command: npx
      args: ["-y", "@upstash/context7-mcp@latest"]

COPILOT:
  target: vscode
  model: ["gpt-5", "gpt-4.1"]
  APPEND_BODY: |
    ## Copilot-specific
    Reference tools with `#tool:<name>`.
---

# Code Investigator

You are a specialized code-investigation agent. Read the relevant files
before answering. Cite `file:line` for every non-trivial claim. Never
edit code; if a fix is needed, propose it as a diff in the response.

When the user asks "where is X?", search broadly across naming
conventions before reporting "not found".

The conventions are simple enough that I never need to read the docs again:

Lowercase keys at the top level (like name, description) are shared frontmatter — copied verbatim into every output.
UPPERCASE keys at the top level (CLAUDE, GEMINI, COPILOT, CURSOR, OPENCODE, KILO) are target blocks. Each block holds the frontmatter that only that target understands.
Lowercase keys inside a target block (model, tools, …) become that target’s frontmatter, verbatim. Supagents does not translate or normalize fields. If Claude wants tools: Read, Grep and Gemini wants tools: [“*”], you write them both — and that is fine, because they live in different blocks.
UPPERCASE keys inside a target block are directives — they shape the build instead of the output frontmatter.

These two extra directives extend the generation process:

OUTPUT : override the destination path for one target. Useful when a tool wants the file in an unusual place.
APPEND_BODY : append target-specific markdown to the shared body. Great for tool-specific syntax (Copilot’s #tool: references, for example) that would confuse the other agents.

The body of the markdown — everything after the frontmatter — is the persona. It is shared across all targets unless APPEND_BODY extends it. This is the part you write once and stop hand-syncing.

Verbatim, on purpose

I made a deliberate choice to keep the per-target frontmatter verbatim. Supagents does not try to translate model: sonnet into Gemini’s equivalent, or rewrite tools: Read, Grep into Copilot’s #tool: syntax. Every coding tool moves fast, breaks frontmatter conventions on minor releases, and adds new fields I have never heard of. A schema-translation layer would be obsolete before I shipped it.

Verbatim has a cost — you write each target block yourself — but it has one big payoff: when Claude Code adds a new field next week, supagents already supports it. The compiler is just a YAML splitter and a file router.

The CLI

Four commands cover the entire workflow:

supagents build [SCOPE] # compile sources → outputs
supagents clean [SCOPE] # remove orphaned outputs
supagents list [SCOPE] # show every source and its outputs
supagents init NAME # scaffold a new source from template

SCOPE is either project (the .agents/supagents/ next to your code) or global (the ~/.agents/supagents/ in your home). Skip it and supagents picks based on where you run.

The flags I reach for daily:

— dry-run — preview every write without touching the filesystem.
— check — exit non-zero if any output would change. This is the CI flag. Wire it into a GitHub Action and you get a hard guarantee that committed sources match committed outputs.
— target CLAUDE (repeatable) — operate on a single target. Great when you are iterating on a Gemini-only tweak and don’t want to rewrite five files.
— verbose — print the unchanged files too. Helpful when something is mysteriously not updating and you want to confirm supagents saw the source.

Builds are idempotent. If a source has not changed since last build, supagents preserves the output’s mtime so file watchers and pre-commit hooks don’t re-fire on noise.

Pre-commit and CI integration

I run supagents in two places. Locally, as a pre-commit hook:

# .pre-commit-config.yaml
- repo: https://github.com/fmind/agent-supagents
  rev: v1.0.0
  hooks:
    - id: supagents-build

This catches the common mistake of editing .agents/supagents/code-investigator.md and forgetting to commit the regenerated .claude/agents/code-investigator.md.

In CI, I run supagents build — check as a separate step. If someone edits an output by hand instead of editing the source, the check fails and the PR cannot land. Outputs are always derived; sources are always authoritative.

A configuration file when defaults are not enough

By default, supagents knows where each of the six built-in targets wants its files:

CLAUDE — project .claude/agents/, global ~/.claude/agents/, suffix .md
GEMINI — project .gemini/agents/, global ~/.gemini/agents/, suffix .md
COPILOT — project .github/agents/, global ~/.copilot/agents/, suffix .agent.md
CURSOR — project .cursor/agents/, global ~/.cursor/agents/, suffix .md
OPENCODE — project .opencode/agents/, global ~/.config/opencode/agents/, suffix .md
KILO — project .kilo/agents/, global ~/.config/kilo/agents/, suffix .md

When a tool moves its agents folder — and it will — you don’t need to wait for a supagents release. Drop a ~/.config/supagents/config.yaml and override only what you need:

targets:
  claude:
    global_path: ~/.config/claude-code/agents
    project_path: .claude-code/agents

Anything you omit falls back to the bundled defaults. The same mechanism lets you register a brand-new target without touching the source code, which I expect to use the moment the next coding agent ships.

Why it matters

The bigger bet is that subagents will eventually land in the shared .agents/ ground, the way AGENTS.md already has. When that happens, supagents becomes a transition tool — and that is the point. I would rather build a bridge that becomes obsolete than wait for every vendor to converge on a standard while my workflow rots.

In the meantime, supagents lets me do three things I could not do before:

Write a persona once. No more cmd-find-and-replace across five YAML files.
Ship subagents in a project. Commit the .agents/supagents/ source, list supagents build in CONTRIBUTING.md, and every contributor — whatever coding agent they use — gets the same agents.
Promote my best agents to global. When a project-scoped agent earns its keep, I move it to ~/.agents/supagents/ and it follows me into every repo.

If you are running more than one coding agent — and most of us are, whether we admit it or not — give it a try:

uv tool install supagents
supagents init code-investigator
supagents build --dry-run

The repository is at github.com/fmind/agent-supagents. Issues and pull requests welcome — especially for new target adapters. I want this to outgrow my own workflow.

The Linux philosophy taught us that small tools beat big protocols. The same is becoming true for AI agents: a tiny CLI that does one thing — compile a single source to many targets — beats yet another framework that tries to own the whole stack. Supagents is my attempt at the one thing well part. The “combine them to solve complex problems” part is up to you.

AI Agents as an Operating System: Rediscovering the Linux Philosophy

Médéric Hurier (Fmind) — Sat, 14 Mar 2026 07:06:11 +0000

We are building the most advanced AI systems in history, yet the best way to control them relies on paradigms from the 1970s. I see developers wrestling with this friction daily, trying to bridge the gap between bleeding-edge models and legacy toolchains.

As of 2026, a simpler and clearer trend is emerging: the Command Line Interface (CLI) is becoming the most practical foundation for building agents. Tools like OpenClaw and the Google Workspace CLI demonstrate this well. Handing an agent a raw shell and a file system is often faster and more reliable than wrapping it in a complex protocol. As Eric Holmes noted in MCP is dead. Long live the CLI, modern LLMs already excel at using standard command-line utilities. These tools are lightweight, trivial to debug, and compose naturally.

To understand why this approach works, we need to look at where agent protocols struggled, and why the path forward means returning to the Linux philosophy.

Photo by Kevin Horvat on Unsplash

The Problem with MCP (Model Context Protocol)

Model Context Protocol (MCP) was one of the first major agent protocols to emerge. Heavily inspired by how VS Code extensions work, its goal was noble: create a standardized way to expose all available resources and tools to an LLM.

In practice, however, MCP suffers from severe architectural flaws for everyday agentic workflows:

Context Bloat: MCP typically exposes all tools and their schemas at once. Massive tool descriptions eat up valuable context windows. On my Gemini CLI, simply booting up and saying “Hello” cost 50k input tokens.
Deployment Mess: The protocol tries to handle too many scenarios. It combines local runners (e.g., Docker, uvx, npx, …), remote execution, API keys, and OAuth into a single, often fragile deployment model.
Redundant Authentication: As Holmes pointed out, you often have to re-authenticate specifically for the MCP and define an entirely new set of tools, needlessly duplicating your existing environment.
Verbose Returns: Results are returned directly in the protocol’s format to the LLM, bloating the context even further with massive JSON structures rather than clean, human-readable text.

🛠️ MCP: Experience from the Field

Development: Personally, I don’t use any MCPs on my local machine anymore. It’s too bloated. I refuse to re-authenticate to yet another tool wrapper, and micromanage them by manually selecting which tools the agent should use for a given task.
Production: I often tell my team that MCPs are like the old regex joke: You had a problem that required MCP, now you have two problems. They lack maturity, and it’s rarely clear if a specific MCP was built for a slick local dev experience or for robust production. They are incredibly hard to debug, and I frequently find myself monkey-patching them just to keep pipelines running smoothly.

A2A (Agent-to-Agent) Is Not a Tooling Protocol

For a long time, I believed Agent-to-Agent (A2A) communication would emerge as the compelling alternative to tool-binding protocols like MCP. While A2A remains the best way to orchestrate agents across different domains, it is not a protocol meant for low-to-medium level tool execution:

The Double-Token Tax: If you have a client agent delegating a simple task to a remote agent via A2A, you are paying token costs and incurring latency for two LLMs in the loop. For low-level execution, the cost far outweighs the benefits.
Rigid Abstractions: The remote agent comes with its own baked-in instructions and tools. While great for isolation, it’s highly detrimental if the local client agent needs to dynamically override or tweak how the remote task is executed.
Network Overhead: A2A inherently treats everything as a remote network call. This is powerful for distributed systems, but absolute overkill for local development tasks.

🛠️ A2A: Experience from the Field

Development: I don’t know anyone actually using A2A in their local development loop. Providers like GitHub tend to build their own proprietary APIs to call remote agents. When you operate inside a closed ecosystem, it’s often faster and easier to use native APIs than to force-fit an external protocol.
Production: I think A2A is incredibly promising here, and we already leverage it in production. It’s a fantastic approach for large organizations where you need to mirror complex corporate structures, allowing agents to delegate high-level tasks to specialized “worker” agents at scale.

Agent Skills Are Too Abstract

I previously thought Agent Skills were going to be the golden hammer — a concept I explored in MLOps Coding Skills: Bridging the Gap Between Specs and Agents. I was wrong.

Premature Abstraction: Skills are designed to be reusable. The trap is making them overly verbose on Day 1, trying to account for edge cases that don’t exist yet.
Context over Skills: On a new project, you are much better off using an AGENTS.md file, system instructions, or context files like the 5XP framework. They are vastly easier to operate and tweak.
Incomplete Taxonomy: Structuring everything as a “skill” is a flawed mental model. Not everything is a skill. Way-of-working, product objectives, and business context cannot be neatly packaged into executable skills.
The “Static Fit” Problem: When you import open-source skills or skills written by others, they rarely align 100% with your needs. Because they are static, they either fit perfectly, or they break. There is no inherent mechanism for the skill to learn or adapt to the user’s specific workflow.

🛠️ Agent Skills: Experience from the Field

Development: I use the 5XP framework now. I only extract a “skill” a posteriori — after a major refactoring, when I actively want to reuse a specific workflow across multiple projects.
Production: Skills provide a clean way to formalize and version-control agent instructions to share among colleagues. They complement A2A beautifully: the A2A protocol provides the workers, while the Skills repository provides their standardized instructions.

Rediscovering the Linux Philosophy

If bloated protocols and rigid abstractions are slowing us down, what is the alternative? We need an approach to agent tooling that is dynamic, composable, and lightweight. Unsurprisingly, the industry is circling back to the CLI (Command-Line Interface).

For developers, treating the CLI as the primary interface for agents has undeniable benefits:

Battle-Tested Maturity: There are thousands of mature, edge-case-tested CLI tools already on the market. Furthermore, LLMs have ingested the man pages for these tools; they already know exactly how to use them.
Shared Environment: A human can step in and run the exact same command. The environment is already authenticated, and debugging is trivial (standard error messages, exit codes, easily readable flags).
Zero Bloat: It’s incredibly lightweight. You don’t need to deploy a wrapper or a daemon. You just execute the command.
Infinite Composability: Agents can natively pipe find, grep, jq, and curl together, without passing the intermediate tool output to the LLM.
Language Agnostic: It doesn’t matter if the underlying tool is written in Rust, Go, Python, or Bash. To the agent, it’s just a command.

What we are doing is rediscovering the Linux Philosophy:

Everything is a file (or a text stream).
Write small tools that do one thing well.
Combine them to solve complex problems.

🛠️ Experience from the Field

Development: During my day-to-day development, I now rely almost entirely on CLI tools combined with raw text context. It is incredibly liberating. I’m deeply curious to see how far this pure approach can scale. We are even seeing frameworks adapt to this reality; for instance, the Google ADK recently added native bash tools to give agents direct shell access.

Side Note: I finally feel less guilty about the 1283+ commits on my dotfiles.

What’s Next? From Linux to Kubernetes for Agents

Right now, the raw CLI is the 80/20 rule of agent development. It gives us maximum leverage with minimum setup, accomplishing 80% of what we need and making developers extremely productive locally. But local development is not the final destination.

While giving an agent CLI access is like giving it a personal UNIX terminal, security and scale are the ultimate blockers for the CLI in production.

You cannot simply hand an autonomous LLM unconstrained bash access to your AWS account or your production database. Real-world deployment requires a rigorous security layer: strict authentication, Role-Based Access Control (RBAC), sandboxing, and immutable audit logs. This is a highly complex problem that raw CLI execution cannot solve safely at an enterprise scale.

In traditional software, we didn’t abandon the Linux philosophy to build the cloud; we containerized and orchestrated it. We bridged the gap between a single bash instance and a globally distributed system.

We need the exact same evolution for AI. To bridge the gap between heavy, bloated agent protocols and the lightweight-but-insecure raw CLI, we need a new paradigm. We need something that adheres strictly to the composability of Linux, but is built for autonomous systems at scale.

My bet is that we don’t just need another protocol; we need an Operating System for Agents.

Just as the industry needed Kubernetes to safely orchestrate Linux containers across vast server networks, our agents will need an orchestration layer built specifically for AI workloads:

Process Management: Spinning agent loops up and down dynamically based on computing load.
Granular RBAC: Strict, declarative policies restricting exactly which binaries, data silos, and network endpoints an agent can touch.
Dynamic Service Discovery: An Istio-like service mesh for agents, allowing them to route tasks to specialized peers without hardcoded endpoints.
Message Queues: Enabling agents to share state and context asynchronously, freeing up expensive context windows.

Istio Architecture (Source: https://istio.io/latest/docs/ops/deployment/architecture/)

The history of software is wonderfully cyclical. We spent the last few years trying to invent complex new paradigms, only to rediscover the elegance of the Linux philosophy. As we transition from local development into enterprise-grade production, it’s becoming abundantly clear: we’ve finally found the Linux for agents.

The next frontier is building the Kubernetes to run it.

Photo by Growtika on Unsplash

The 5xP Framework: Steering AI Coding Agents from Chaos to Success

Médéric Hurier (Fmind) — Sat, 28 Feb 2026 12:13:44 +0000

AI Coding — or Spec-Driven Development — is a recent trend that amazes as much as it scares IT engineers. We now have access to powerful models capable of writing entire applications, but jumping from “Hello World” to a production-grade enterprise system exposes a glaring bottleneck: Context.

The hardest challenge isn’t the coding itself; it’s explaining to the AI Coding Agent how to work on the task. How do you capture your style, preferences, constraints, environment, tools, and workflow?

In my previous article, How I Revamped My Portfolio Website in 5 Nights Using AI Agents, I shared how setting up explicit context was the secret to steering the AI successfully. I refused to just “vibe code” and instead relied on firm architectural guidance.

In this follow-up article, I present the exact structure I use for my AI-assisted projects. After exploring many iterations and tools, I found that the key to success is providing the AI with the right context in a brutally simple, highly maintainable way.

Photo by ZHIDA LI on Unsplash

Note: To make it easier to adopt, I’ve created the AI Coding 5xP Template repository. This repository acts as the single source of truth for the framework, providing a ready-to-use directory structure you can use for your own projects.

Context is Everything

AI Coding Agents are amazing at parsing documentation, but they lack common sense. Put yourself in the shoes of an AI agent: you are dropped into a closed room, and you don’t know the person you are assisting. You don’t know who you are working for or for what purpose. You just have access to the code and whatever you can infer from it.

To steer the agent in the right direction, context is the fuel. It adapts the LLM to your skill level, your objective, and your expectations. But bringing context properly is a true challenge, and I know many engineers who struggle with it.

The Pitfalls of Current Solutions

I have experimented with several approaches to provide context, and each comes with its own trade-offs:

Autocompletion & Inference : Tools like GitHub Copilot and Google Antigravity are great for getting decent work done by inferring information from your existing codebase. However, they struggle when you start a project from scratch or when you have to rigidly copy-paste instructions over and over again to keep the agent aligned.
Interactive Scaffolding : Frameworks like Spec-kit and Conductor allow you to prepare your context by answering questions. In practice, I found these tools too verbose. They infer a lot of content from your answers that you wouldn’t necessarily write yourself, leading to dilution of the core instructions.
Protocol Integrations : The Model Context Protocol (MCP) is a fantastic standard for extending the capacities of your coding model by securely exposing external tools. But relying purely on MCP can bloat your LLM’s context window. Once you hit 100 tools, the model loses its focus, and you end up micromanaging tool selection instead of writing code.
Agent Skills: Dynamically loading specific skills into your LLM is amazing for quick task execution via lazy loading. However, it’s incredibly hard to generalize skills on day one. It’s often more practical to create specific rules for your current project first, and later refactor the recurring ones into standalone skills.

My Solution: The 5xP Framework

I found that the most sustainable strategy to steer an AI Coding Agent is to use flat, readable Markdown files. I organize them using what I call the 5xP Framework : Product, Platform, Process, Profile, and Principle.

Here is how to break it down. While you can customize it, the default template provides 4 files directly under a context/ directory:

PRODUCT.md: The objective. What are we building? Who are the users? What is the business logic? This prevents the AI from over-engineering features that don’t align with the goals.
PLATFORM.md: The technical stack. What tools, environment, frameworks, and architectural patterns are we strictly adhering to?
PROCESS.md: The workflow. How exactly should the AI collaborate with you? What are the quality assurance standards and AI engagement rules?
PROFILE.md (Optional but recommended): Who are you? Explaining your background, communication style, and expertise prevents the agent from making wrong assumptions.

The 5th xP is the most important: Principle. These are your Ten Commandments, and you should put this information in an AGENTS.md file at the root of your project. Acting as the master entry point for the AI, the principles sit at the top, and the file then links to the other 4xPs, explicitly instructing the agent to read them when necessary.

Rule of Thumb: Keep each file to 1 page maximum. You should not have to scroll to read the content. This forces you to be concise, avoiding information overload for both you and the LLM.

Example Project Structure

Let’s look at a fictional project — an open-source AI task manager called TaskBrain — and see how this structure is applied in practice based on the template.

The repository structure looks like this:

taskbrain/
├── src/
├── tests/
├── context/
│ ├── PLATFORM.md
│ ├── PROCESS.md
│ ├── PRODUCT.md
│ └── PROFILE.md
└── AGENTS.md

Here is exactly how you would wire the AGENTS.md file to act as the master prompt:

# Agent Guidelines

Assume the persona of an expert AI Coding Assistant dedicated to this project.

## Principles

1. **Simplicity First** : Keep dependencies minimal and favor straightforward, readable solutions over complex alternatives.
2. **Proactive Partnership** : Anticipate potential issues and challenge decisions that contradict the project's constitution.
3. **Maintainable Code** : Prioritize code clarity, clean architecture, and consistent formatting across the entire codebase.
4. **Contextual Awareness** : Adhere to the guidelines established in the context files to ensure all contributions align with them.
5. **Security by Design** : Identify and mitigate security issues proactively. Treat data privacy and secrets handling as fundamental requirements.

## Context Navigation

Read the following context files as needed to understand the project's core rules and guidelines.
Suggest to the user to update the context files as needed to reflect the project's current state.

- **[context/PROFILE.md](context/PROFILE.md)** (Who): My background, communication style, and expertise.
- **[context/PRODUCT.md](context/PRODUCT.md)** (What): Core objectives, target audience, and business logic.
- **[context/PLATFORM.md](context/PLATFORM.md)** (Where): Technology stack, infrastructure, and architectural principles.
- **[context/PROCESS.md](context/PROCESS.md)** (How): Workflows, AI engagement rules, and quality assurance standards.

By keeping the root AGENTS.md file short and linking to specific sub-files in a context/ directory, the AI agent can dynamically lazy-load exactly what it needs, precisely when it needs it.

Field-Tested Results

I have thoroughly tested this framework on two distinct projects: completely revamping my personal website and bootstrapping a complex new project centered on AI Agents. In both cases, the results were night and day compared to previous approaches.

The true power of this framework lies in its human-friendliness : the files are simple, focused, and I can quickly steer the model in a new direction just by tweaking a few bullet points in a Markdown file.

Furthermore, it does not bloat the LLM. By providing what essentially acts as a “table of contents” in the root AGENTS.md (similar to exposing agent skills), the model only pulls the context it needs for the task at hand. This naturally enforces a healthy rhythm: you spend 20% of your time thinking and structuring the context, allowing the AI to smoothly handle the 80% implementation burden.

Conclusion

Every expert I know keeps iterating on how to collaborate with AI Coding Agents. Many approaches are either far too verbose, drowning the LLM in noise, or far too simplistic, leading to repetitive manual prompting.

The 5xP framework is the best trade-off I have found so far: it is brutally simple, easy to maintain natively in Git, and it works across almost every LLM coding environment.

It does not take long to set up, but it forces you to think clearly about your project’s shape before you write a single line of code. And in the era of AI engineering, thinking clearly is your greatest superpower.

Photo by Van Tay Media on Unsplash

Ready to start? Grab the AI Coding 5xP Template on GitHub to get up and running instantly.

How I Revamped My Portfolio Website in 5 Nights Using AI Agents

Médéric Hurier (Fmind) — Thu, 19 Feb 2026 20:43:26 +0000

I see many friends and acquaintances generating amazing applications in mere weeks. We are in the midst of a craze of innovation, an era where inspired people can bring their ideas to life without being strictly bounded by the usual constraints of tool mastery.

This means there is no time to slack off. The go-getters will not wait for you to catch up. One representative aspect of this fast-moving landscape is your digital presence — your portfolio.

As a freelance AI/ML Architect, I realized I needed a space that truly reflected my expertise. In this article, I present the revamp of my own portfolio: fmind.dev.

New Homepage of Fmind.dev

The Old and Dusty Website

My previous website was built with Google Sites. It was cheap, highly functional, and effortless to maintain.

Previous version of Fmind.dev

But functional is no longer enough in 2026, especially for a freelancer who constantly needs to be on the bleeding edge of technology. Google Sites afforded me very little control over styling, strict limitations on SEO, and — crucially — zero ability to easily evolve it using modern AI coding assistants.

Something had to be done.

Preparing the Field: Setting Up the Agent

The secret to a successful AI-assisted project isn’t just jumping in and prompting; it’s about preparing the groundwork.

I started by defining several agent skills tailored to prepare my specific text stack. For this project, I created dedicated skills covering:

Backend Development
Frontend Development
GCP Deployment
GCP Observability
Mobile Optimization
Project Tooling
SEO Optimization

Then, instead of continuously reminding the agent who I am and what I want, I explicitly created two context files:

PROFILE.md : Outlining my professional identity, experience, and links.

# Profile - Médéric Hurier (Fmind)

## Headline

Freelancer • AI/ML Architect & Engineer • AI Agents & MLOps • GCP Professional Cloud Architect • PhD in AI & Computer Security

...

DESIGN.md : Defining my brand identity (e.g., “Space & Tech” aesthetic).

# Website Design

## Brand Identity

A professional, advanced, and modern digital presence for an AI/ML Architect.

Blending clean and modern style with a "Space & Tech" aesthetic to reflect deep expertise in Artificial Intelligence and MLOps.

...

By establishing these foundational documents, I set the ground rules. The AI agent had immediate access to my personality and brand identity, saving me from having to explain the context over and over again.

Building the Website: Steering the AI

Rather than “vibe coding” everything and blindly compiling the results, I made a strict rule: I would review every single file generated by the agent. As an engineer, I refuse to be responsible for a codebase I haven’t read or understood.

Despite the agent’s impressive capabilities, I noted several weaknesses that you must manage when using AI agents to generating code:

“Agents don’t care about your brand. They just want to get the task done.”

— A harsh truth of AI coding

It’s entirely up to you to rigorously maintain your identity and ensure the output matches your needs.

“Code quickly degenerates. Without supervision, AI can generate piles and piles of code lacking underlying logic.”

Agents are fantastic at refactoring, but you are the architect who must point them in the right direction.

Choosing the right tech stack is key. Call me old school, but I demand mastery over what I produce. I decided to use Python as the foundational layer for my programming logic. I am confident in my ability to maintain, debug, and evolve a Python-based architecture over the long term.

Once you actively tackle these limitations, the results are breathtaking. While I generally don’t enjoy writing repetitive boilerplate or templates, the AI agent excels at it and never gets tired. You can direct its focus entirely to the frontend, backend, deployment, SEO, or mobile optimization. Watching the pieces fall into place gives you an incredible dopamine rush.

The Result

I was able to finalize the website from scratch in just 5 nights.

This rapid timeline included everything: generating the base components, extensive optimizations, refactoring, and setting up proper deployment pipelines (including analytics and observability). While I could have let the agent run entirely autonomously, it is my website; I wanted to be an active part of the process.

Result of PageSpeed Insights (LightHouse)

I’m thrilled to report that the new site achieved a 100% Lighthouse score across every single category. The site is fast, modern, and beautifully aligned with my brand. I would have never been able to produce this level of polish by myself in such a short timeframe, and I’m incredibly proud of the result.

For context on the effort, here is a quick look at the codebase generated and reviewed during those 5 nights:

github.com/AlDanial/cloc v 1.98 T=0.10 s (915.2 files/s, 30379.3 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
HTML 57 33 40 1257
Markdown 11 277 0 580
Python 12 138 79 368
TOML 1 8 1 84
YAML 3 0 3 81
CSS 2 9 0 41
Text 4 7 0 33
JSON 1 0 0 31
Dockerfile 1 1 2 27
-------------------------------------------------------------------------------
SUM: 92 473 125 2502
-------------------------------------------------------------------------------

Conclusions

AI Coding is an absolute game-changer. I highly encourage any developer or freelancer to revamp their own website as soon as possible. It is the perfect, tightly-scoped exercise to discover the true, practical capacity of these tools for yourself.

Key Takeaways

Start with clear context files to ground your agent’s understanding.
Do not blindly trust generated code; review everything to maintain architectural control.
Avoid “shiny object syndrome.” Relying entirely on AI without architectural vision can lead to generic, unmaintainable results. Find the right balance between automation and engineering rigor.

Check out the final result at fmind.dev.

About me on Fmind.dev

If you tried ‘vibe coding’ on your own projects yet, let me know your experience in the comments!

Chaigent: An affordable alternative to Gemini Enterprise on Google Cloud

Médéric Hurier (Fmind) — Fri, 06 Feb 2026 20:14:02 +0000

The era of simple chatbots is over. Companies are now racing to build AI Agent platforms — systems that don’t just talk, but act. Whether it’s a support bot resolving Jira tickets or a data analyst agent querying BigQuery, these new digital teammates need a platform that offers more than just text generation: they require reasoning, security, and enterprise-grade observability.

Gemini Enterprise provides a great path to achieving this on Google Cloud. It offers a comprehensive set of features including agent exposition, governance, integrated knowledge search, and a visual agent builder, connecting with backends like Vertex AI Agent Engine, Conversational Agent, or A2A.

However, for some organizations or specific use cases, the cost can be a friction point. The catalog price sits at ~$7/user/month for agent users and ~$35/user/month for visual agent builders. While this pricing is competitive for knowledge workers who gain significant productivity, it can be prohibitive for large audiences with lower usage frequency, such as field workers or occasional users.

Enter Chaigent: https://github.com/fmind/chaigent .

Chaigent is an affordable alternative to Gemini Enterprise (Source: Gemini App)

In this article, I present “Chaigent” (Chainlit + Agent), a cost-effective, DIY alternative to Gemini Enterprise on Google Cloud. It leverages the same powerful underlying reasoning engine but replaces the managed frontend with an open-source framework, giving you control over features and costs.

The Architecture

Chaigent enables you to build a private, secure AI agent platform by combining serverless infrastructure with open-source tooling.

Architecture of Chaigent (Source: Fmind.dev)

The architecture consists of three main layers:

Frontend (Chainlit on Cloud Run): A Python-based UI that handles user sessions, chat history, and authentication.
Backend (Vertex AI Agent Engine): The “brain” of the operation, capable of reasoning and tool use.
Persistence & Auth : Cloud SQL for storing chat history and feedback, and OAuth (Google, GitHub, etc.) for secure identity management.

This approach allows you to pay for consumption only (Cloud Run CPU + Vertex AI tokens), significantly reducing costs for intermittent usage patterns compared to a flat per-seat license.

The “Do It Yourself” Trade-off

Gemini Enterprise provides a managed, “batteries-included” platform with built-in governance and visual tools. Chaigent, in contrast, offers a code-first, developer-centric approach.

What you gain:

Cost Efficiency : No monthly per-seat licensing fees.
Full Customization : You own the code. Want to add a custom feedback mechanism or a specific UI widget? You can.
Platform Independence : Using Chainlit (frontend) and Google ADK (backend) logic keeps you flexible.

What you lose (The “Subtext”):

No Visual Builder : You define agents in code, not a drag-and-drop UI.
Manual Governance : You must implement your own permission logic per agent.
Ops Overhead : You are responsible for deploying, securing, and updating the application.
Enterpise Features : Advanced features like Model Armor (Prompt Security) and integrated Knowledge Search (RAG) require manual implementation.

Implementation Highlights

Chaigent is surprisingly simple to set up. Here is a glimpse of the code.

1. Defining the Agent

The agent is defined declaratively using the Google ADK. It’s just a Python object specifying the model and tools.

# chaigent/agent.py
root_agent = agent(
    name="chaigent",
    model="gemini-2.5-flash",
    description="answer questions with google search.",
    instruction="you are an expert researcher. you always stick to the facts.",
    tools=[google_search],
)

2. The Bridge (Chainlit Adapter)

The app.py acts as the bridge. It connects the user’s chat session to the Vertex AI Agent Engine, handling the streaming response seamlessly.

# app.py

@cl.on_message
async def on_message(message: cl.Message):
    # Initialize response message
    answer = cl.Message(content="")
    await answer.send()

    # Retrieve session
    session = cl.user_session.get("session")
    user_id, session_id = session["userId"], session["id"]

    # Stream the query to Vertex AI
    response_stream = engine.async_stream_query(
        user_id=user_id, message=message.content, session_id=session_id
    )

    # Stream back the tokens
    async for chunk in response_stream:
        for part in chunk.get("content", {}).get("parts", []):
            text = part.get("text", "")
            if text:
                await answer.stream_token(text)
                await answer.update()

User Experience

Despite being a “DIY” solution, the user experience is premium. Chainlit provides features that users expect from modern chat apps.

Rich Chat Interface : Supports markdown, code highlighting, and streaming responses out of the box.

Chat interface of Chaigent

Authentication & Persistence : Secure login screens and persisted chat history allow users to resume conversations across devices.

Login screen of Chaigent

Data Layer : All interactions are stored in your own SQL database, giving you full ownership of the data for analytics or fine-tuning later.

Home screen of Chaigent

Conclusion

Chaigent is an excellent solution when cost efficiency is the primary driver, particularly for large audiences with low individual usage.

The decision comes down to ROI. At ~$7/month/user for Gemini Enterprise, you need to save each user at least one hour of work per month to break even. For knowledge workers, this is a no-brainer. But for field workers or casual users, a consumption-based “Pay-as-you-go” model like Chaigent might be the smarter financial move.

If you are ready to trade some convenience for control and cost savings, go build your own agents!

Source: Gemini App

mAIdAI: Building a Personal Assistant with Google Cloud and Vertex AI

Médéric Hurier (Fmind) — Thu, 05 Feb 2026 06:05:23 +0000

As an AI Architect, I spend my days designing AI systems and agents for others. I optimize workflows, fine-tune context windows, and architect serverless solutions to solve complex business problems.

But recently, I caught myself in a classic “cobbler’s children” scenario. While helpful bots supported my teams, I navigated my own workflow manually — answering the same repetitive questions, digging for the same documentation links, and context-switching constantly.

I realized I needed something different. Not another generic team bot, but a Personal AI Assistant — one that knows my specific context, my preferred shortcuts, and my tone.

So I built mAIdAI (My AI Aid) : https://github.com/fmind/maidai

mAIdAI Avatar (Source: Gemini App)

In this article, I’ll walk you through how I architected this personal agent using Google Chat , Cloud Run , and Vertex AI.

The Problem: The High Cost of “Quick” Tasks

We often underestimate the micro-friction in our daily work.

“Where is the design doc for Project X?”
“What’s the syntax for that specific gcloud command again?”
“Can you review this snippet?”

Standard team bots are great, but they are generic. They lack the specific context of your personal role and responsibilities. I wanted an agent that acts as a “Second Brain” — grounded in my personal knowledge and capable of executing my specific workflows.

The Solution: mAIdAI Pattern

mAIdAI is designed around three core interaction types:

Context-Aware Chat : A conversational flow grounded in a personal context.md file effective “system instructions”.
Quick Commands : Instant helpers that return static values (like commonly used links or snippets) without invoking the LLM.
Slash Commands : specialized triggers that wrap user input in a predefined prompt template (e.g., /fix to debug code).

Demo of mAIdAI on Google Chat (Generic Version)

About mAIdAI

Architecture

The system follows a lightweight, serverless event-driven architecture.

Architecture Diagram of mAIdAI (Source: Fmind.dev)

The Flow

Frontend : usage of the Google Chat app interface. No custom UI to build or maintain.
Transport : Chat events are delivered via HTTP webhooks.
Backend : A Cloud Run service hosting a FastAPI application processes the events.
Intelligence : The backend connects to Vertex AI (Gemini models) for reasoning, grounded by the personal context file.

Deep Dive: The Code

The implementation is surprisingly minimal, thanks to the Google GenAI SDK and FastAPI. The entire core logic resides in a single main.py file.

1. The Setup

We initialize the GenAI client using standard environment variables. This keeps the code portable and secure.

# main.py
client = genai.Client(
  project=os.environ["GOOGLE_CLOUD_PROJECT"],
  location=os.environ["GOOGLE_CLOUD_LOCATION"],
  vertexai=True,
)
# Loading the Second Brain
MODEL_CONTEXT = (ROOT_FOLDER / "context.md").read_text()
config = types.GenerateContentConfig(
  system_instruction=MODEL_CONTEXT,
  max_output_tokens=5000,
)

By reading context.md at startup and injecting it as the system_instruction, we ensure every interaction is grounded in my specific reality.

2. Handling Interaction Types

The core router handles the distinction between simple commands and AI interactions. This is crucial for latency and cost — not every interaction needs a round-trip to an LLM.

@app.post("/")
async def index(request: Request) -> dict:
    event = await request.json()
    # ... extraction logic ...

    if command_id := app_command_metadata.get("appCommandId"):
        # Handle Slash and Quick Commands
        if command_type == "QUICK_COMMAND":
            return respond(command_text)

        if command_type == "SLASH_COMMAND":
            # Contextualize the prompt
            prompt = f"{command_text}. USER INPUT: {user_input}"
            return respond(await chat(prompt))

    # Fallback to standard chat
    return respond(await chat(user_input))

This pattern allows me to have a /links command that returns immediately (0 latency, 0 cost), while a /rewrite command leverages Gemin 2.0 Flash for creative work.

3. Asynchrony by Default

Using async def and client.aio.models.generate_content ensures the Cloud Run container can handle multiple concurrent requests efficiently, even with a single instance.

Deployment Strategy

Simplicity was the primary constraint. I didn’t want to manage infrastructure for a personal tool.

Runtime : Cloud Run (fully managed, scales to zero, low-cost serving).
Configuration : Environment variables for model selection (gemini-3-flash) and project details.
Security : IAM-based authentication ensures only verified chat events reach the service.

Why Build This Locally?

You might ask, “Why not use a standard consumer AI chat?”

Privacy : Data stays within my Google Cloud project.
Context : I control the system prompt (context.md) explicitly.
Workflow Integration : It lives where I work — in Google Chat — not a separate browser tab.

Conclusion

We often accept friction because “it’s just how things are.” But as engineers, we have the tools to change that. mAIdAI is a proof of concept that a highly personalized, context-aware agent doesn’t require a massive engineering team. It just requires a few hundred lines of Python and the right cloud primitives.

If you find yourself copying the same text or answering the same questions repeatedly, maybe it’s time to build your own assistant.

Source: Gemini App

MLOps Coding Skills: Bridging the Gap Between Specs and Agents

Médéric Hurier (Fmind) — Wed, 28 Jan 2026 20:50:20 +0000

We are entering the golden age of AI Coding. Every day, I see colleagues, both technical and non-technical, marveling at how agents are rewriting the rules of software construction. The promise is intoxicating: describe what you want, and let the machine handle the rest.

However, when I see my colleagues try to apply these agents to strict engineering standards, they hit a wall. On one side, you have rigorous specification tools like spec-kit or conductor. They are deterministic and thorough, but setting them up feels like writing a legal contract. On the other side, you have generic tools like the Model Context Protocol (MCP). They act as incredible “hands” for the AI — reading databases, calling APIs — but they lack the brain for your specific context.

They don’t know that your team enforces uv over poetry. They don’t know you prefer just files for automation. They don’t know your specific flavor of “clean code.”

Then I discovered Agent Skills, and everything clicked.

I was immediately hooked. They offer the specific trade-off I had been looking for: lightweight enough to be flexible, yet opinionated enough to be useful.

Source: Gemini App

In this article, I want to share how I used Agent Skills to turn the theoretical “MLOps Coding Course” into a practical, actionable library: the MLOps Coding Skills project.

The Challenge: Making References Actionable

For the past few months, I’ve been deep in the trenches writing the MLOps Coding Course. It is a comprehensive curriculum teaching production-grade MLOps, from robust project initialization to advanced observability.

But as I wrote the documentation, I felt a friction point. Learning the standards is one thing; remembering to apply them in the heat of coding is another.

I didn’t just want another wiki page. I wanted to make these best practices actionable for valid AI Agents. I wanted to move from “reading the docs” to “installing the capability.”

The Logic: How to “Skillify” Knowledge

The beauty of an Agent Skill lies in its simplicity. It is essentially a markdown file (SKILL.md) that functions as a context injection module. It gives the agent “muscle memory” for a specific topic.

My methodology for building the MLOps Coding Skills repo was straightforward:

Isolate a Chapter : Take a specific section of the course (e.g., Automation or Observability).
Extract Patterns : Use an LLM to distill the generic engineering standards from the educational content.
Standardize : Format it into a SKILL.md that an agent can ingest.

A Concrete Example: Automating Ops

Let’s look at the mlops-automation skill.

In our course, we have strong opinions: we use just for command running and docker for containerization, with very specific layer caching strategies.

Here is what the skill looks like “on the wire”:

# MLOps Automation

## Goal

To elevate the codebase to production standards by adding Task Automation (just), Containerization ([docker](https://www.docker.com/)), CI/CD ([github-actions](https://github.com/features/actions)), and Experiment Tracking ([mlflow](https://mlflow.org/)).

## Instructions

### 1. Task Automation

Replace manual commands with a `justfile`.
1. **Tool** : `just` (modern alternative to Make).
2. **Organization** : Split tasks into `tasks/*.just` modules.
3. **Core Tasks** :
- `check`: Run all linters and tests.
- `package`: Build wheels.

### 2. Containerization

1. **Tool** : `docker`.
2. **Base Image** : Use `ghcr.io/astral-sh/uv:python3.1X-bookworm-slim` for minimal size.

When I load this skill, my agent stops guessing. It doesn’t offer me a Makefile. It doesn’t suggest a bloated Ubuntu image. It acts like a senior engineer who has been on the team for years.

The “Senior Engineer” Injection

This is the killer value proposition.

Most frustrations with AI coding come from a lack of context. We blame the model for being “dumb,” but usually, we just haven’t told it the rules of the house.

By using Agent Skills, you are effectively injecting a Senior Engineer into your chat context. You are giving the agent a “cheat sheet” that forces it to align with your organization’s reality.

I now use these skills for every new project I touch. I don’t spend an hour setting up boilerplate. I load or create a skill, and within minutes, I had a structure that matched my most rigorous standards.

The Friction Points

Of course, no solution is perfect. There are still rough edges in this workflow:

Local-First Friction : Currently, skills often sit in a local .agent/skills folder. It works, but copying them around feels archaic.
The Context Stack : We are seeing a fragmentation of context. We have MCP servers for tools, AGENTS.md for persona, and Skills for tasks. Managing this “Context Stack” is becoming a new engineering discipline.
Integration gaps : I love how the Gemini CLI handles this via extensions, but I’m eager to see this standardized across VS Code Copilot, Cursor, and other IDEs.

Conclusion

Despite the minor friction, Agent Skills are excellent “Low Hanging Fruit” for any engineering team.

The productivity gain is massive. For a few minutes of setup — writing a markdown file — you save hours of correcting boilerplate code and enforcing standards down the line. It bridges the gap between the rigidity of a spec and the chaos of a raw LLM.

If you are tired of fighting your AI to follow your style, stop arguing with it. Give it a Skill.

Check out the full MLOps Coding Skills repository to see the library in action.

Source: Gemini App