<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Saurabh on Medium]]></title>
        <description><![CDATA[Stories by Saurabh on Medium]]></description>
        <link>https://medium.com/@saurabhraj042?source=rss-7af6964f5516------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*WCsEmv5ujv9OW4vAJL_Vpw.jpeg</url>
            <title>Stories by Saurabh on Medium</title>
            <link>https://medium.com/@saurabhraj042?source=rss-7af6964f5516------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 10:16:13 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@saurabhraj042/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[1 Year Into AI Engineering: The Roadmap, Minus the Noise]]></title>
            <link>https://medium.com/@saurabhraj042/1-year-into-ai-engineering-the-roadmap-minus-the-noise-e855cb416108?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/e855cb416108</guid>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[roadmaps]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Tue, 17 Nov 2026 11:07:46 GMT</pubDate>
            <atom:updated>2026-11-17T11:07:46.648Z</atom:updated>
            <content:encoded><![CDATA[<h4>Start here</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*z4FThGZxfwQTpScJHosXBw.png" /></figure><p>I am an SDE-2 and I am about 1 year into AI engineering.</p><p>A roadmap helps because it shows what to learn first.</p><p>You do not need a PhD. The roadmap itself says you start from a frontend, backend or full-stack base. If you can build apps, you can start.</p><h3>Step 0: Pick your base</h3><p>The roadmap’s first choice is frontend, backend or full-stack. Pick the one you already know.</p><p>An AI engineer mostly uses models that already exist and builds products around them. An ML engineer trains the models. This path is the first one.</p><h3>Step 1: Models, tokens and prompting</h3><p>Start by calling a model through an API. Claude, Gemini, OpenAI, Llama, Mistral and Cohere are all on the roadmap.</p><p>Three words to learn first:</p><ul><li><strong>Token:</strong> a small chunk of text. Models read and bill in tokens.</li><li><strong>Context window:</strong> how much the model can see at once.</li><li><strong>Prompt:</strong> your instructions. Techniques to know: zero-shot (just ask), few-shot (show examples), chain-of-thought (ask it to reason step by step) and ReAct (reason, then act).</li></ul><p>Settings like top-K and top-P control how random the answers are.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*asrvbgNZbiPUCtA3MXRXxw.png" /></figure><h3>Steps 2 to 4: Embeddings, vector databases and RAG</h3><p>These three go together. Learn them as one chain.</p><p><strong>Step 2: Embeddings.</strong> An embedding turns text into a list of numbers that captures its meaning. Similar meanings get similar numbers. That powers semantic search, recommendations and classification.</p><p><strong>Step 3: Vector databases.</strong> They store embeddings and find the closest ones fast. The roadmap lists Chroma, Pinecone, Weaviate, FAISS, LanceDB, Qdrant, Supabase and MongoDB Atlas. Pick one. Don’t compare all eight.</p><p><strong>Step 4: RAG (retrieval-augmented generation).</strong> The model answers using your own data. The pipeline is five parts: chunk your documents, embed the chunks, store them, retrieve the closest ones for a question, then generate the answer.</p><p>The roadmap also compares RAG with fine-tuning. A simple rule: RAG when the model needs your facts, fine-tuning when it needs a new behaviour.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SyiQ5dc0Dwej4kxWYt50QA.png" /></figure><h3>Steps 5 and 6: Agents, MCP and context</h3><p><strong>Step 5: Agents.</strong> An agent is a model that can use tools and decide its next step. The roadmap’s path is:</p><ol><li>Tool calling (function calling): the model asks your code to do something, like search or run a query.</li><li>ReAct: the model reasons, acts, looks at the result, and repeats.</li><li>Build a small agent by hand first.</li><li>Then try an agent SDK. The roadmap lists OpenAI’s AgentKit and Agent SDK, and the Claude Agent SDK.</li></ol><p><strong>MCP (Model Context Protocol).</strong> It is a standard way to plug tools and data into models. It has three parts: a host, a client and a server. The roadmap suggests building a small MCP server yourself.</p><p><strong>Step 6: Context engineering.</strong> This is deciding what goes into the model’s context window, and what stays out. The roadmap covers context sources, memory, long-context handling and the ways context fails. The roadmap lists context failure modes as their own topic.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tTH57Zx1MjxRRoM0IipE-Q.png" /></figure><h3>Steps 7 and 8: Evals, observability and safety</h3><p>This is the part that turns a demo into a product.</p><p><strong>Step 7: Evals and observability.</strong></p><ul><li><strong>Evals</strong> test whether your AI answers well. The roadmap lists three kinds: deterministic (exact checks), model-based (another model grades) and human (people review). Run them again after every change, as regression tests.</li><li><strong>Observability</strong> shows you what happened in production: traces and logs, cost, latency. Tools on the roadmap include LangSmith, Langfuse, Helicone and Arize for observability, and DeepEval and RAGAS for evals.</li></ul><p><strong>Step 8: Safety.</strong> The big one is prompt injection: someone hides instructions in the input to hijack your model. Also cover bias, privacy and adversarial testing. Two habits help most: constrain what goes in and what comes out, and never give a model more access than it needs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DieS6hNs4JMdmv2J6edSTA.png" /></figure><h3>Learn these later</h3><p>The roadmap also covers multimodal AI (images, audio, video), open-source and local models (Hugging Face, Ollama) and fine-tuning. They are useful. They are not where I’d start.</p><h3>The order, in one list</h3><ol><li>Pick your base: frontend, backend or full-stack</li><li>Call a model API. Learn tokens and context</li><li>Prompting</li><li>Embeddings, a vector database, then RAG</li><li>Agents and tool calling, then MCP</li><li>Context engineering</li><li>Evals and observability</li><li>Safety</li></ol><h3>The honest part</h3><p>A roadmap does not make you an engineer. Building does.</p><p>Pick one small project, and take it through all 8 steps. A document Q&amp;A bot is enough.</p><p>The roadmap changes often. Check the live page before you plan.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e855cb416108" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Review Doc I Wrote Before Every Promotion and Hike]]></title>
            <link>https://medium.com/@saurabhraj042/the-review-doc-i-wrote-before-every-promotion-and-hike-193e49cee61b?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/193e49cee61b</guid>
            <category><![CDATA[promotion]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[career-advice]]></category>
            <category><![CDATA[performance-reviews]]></category>
            <category><![CDATA[career-growth]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Mon, 16 Nov 2026 12:04:49 GMT</pubDate>
            <atom:updated>2026-11-16T12:04:49.236Z</atom:updated>
            <content:encoded><![CDATA[<h4>Your review is coming. Is your case written down?</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x_Ax4u76PyohL5Xh2AF0fA.png" /></figure><p>Most engineers walk into a review with nothing written down.</p><p>They hope their manager remembers a whole year of their work. Managers are busy. They forget.</p><p>I have 4 years 10 months of experience. 3 promotions. 1 switch to big tech. Every time I asked for a promotion or a hike, I got it.</p><p>Before every review, I wrote my case down. Same template, every time.</p><p>Here it is, in 4 steps. A blank copy is at the end.</p><h3>Step 1: Collect everything</h3><p>Pick your period first.</p><ul><li><strong>Mid-year check-in:</strong> the last 6 months.</li><li><strong>Yearly review:</strong> the full year.</li><li><strong>Promotion:</strong> everything since your last promotion.</li></ul><p>Now dig out every piece of work from that period. Every ticket. Don’t filter yet.</p><p>Look in your ticket tracker, pull requests, design docs, incident notes, and messages where someone thanked you.</p><p>Put it all in one list: link, one line, date.</p><p>Why? You remember the last few weeks. Your tickets remember everything.</p><h3>Step 2: Sort it into buckets</h3><p>A list of 50 tasks reads like a to-do list. Nobody can tell what matters.</p><p>So group your work by the skill it shows. I use <a href="https://www.amazon.jobs/content/en/our-workplace/leadership-principles">Amazon’s leadership principles</a> as bucket names. If your company has its own career ladder, use its words instead.</p><p>Six that fit engineering work well:</p><ul><li><strong>Ownership:</strong> you picked up something nobody assigned and finished it.</li><li><strong>Deliver Results:</strong> big work shipped, with a measured outcome.</li><li><strong>Dive Deep:</strong> hard bugs, root causes, performance work.</li><li><strong>Invent and Simplify:</strong> you automated or simplified something.</li><li><strong>Earn Trust:</strong> cross-team work and clear communication.</li><li><strong>Hire and Develop the Best:</strong> interviews and mentoring.</li></ul><p>Three rules:</p><ol><li>Pick 3 to 5 buckets. Not all of them.</li><li>Inside each bucket, biggest impact first.</li><li>Cut small tasks that show nothing new.</li></ol><p>You are not listing everything you did. You are showing what you should be promoted for.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MDXTx6Yrw3uUHJ3xH17Gfw.png" /></figure><h3>Step 3: Write each item in 4 lines</h3><p>Nobody reads long docs. So each item gets four lines:</p><ol><li><strong>Link.</strong> The ticket or pull request. Proof, one click away.</li><li><strong>What I did.</strong> One sentence. Your part only.</li><li><strong>Impact.</strong> A number.</li><li><strong>Recognition.</strong> A thank-you or shout-out, with its link. Skip it if you have none.</li></ol><p>An example, with made-up numbers:</p><pre>TICKET-1234 (link)<br>What: Redesigned the nightly data load to run in parallel.<br>Impact: Run time 9 hours to 2 hours. 3 teams get dashboards before 8 am.<br>Recognition: Thank-you note from the analytics lead (link).</pre><p>A reader gets it in 10 seconds.</p><p>No number? Look for one of these: time saved, cost cut, speed gained, teams using it, failures reduced. If you have to estimate, write “est.” next to it.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RknY7-3_bHSelyVKRvWFDA.png" /></figure><h3>Step 4: Add a growth section</h3><p>The first part shows the work you did. This part shows you are growing toward the next level.</p><p>List what you did beyond your tasks: courses, side projects, talks, articles, mentoring.</p><p>Same rule. A link, one line, and why it matters.</p><pre>GROWTH<br>- Gave a 30-minute session on data modelling to my team (link).<br>  Why it matters: teaching beyond my own work.<br>- Finished a distributed systems course, used it in TICKET-1234.<br>  Why it matters: designing for scale.</pre><p>Three real items beat ten stretched ones.</p><h3>Before your review: 3 quick checks</h3><ol><li><strong>Is it short?</strong> Keep your best items. Cut the rest.</li><li><strong>Is it yours?</strong> Write your part, not the team’s.</li><li><strong>Is it safe?</strong> Keep the real doc inside your company’s tools. Never share internal links or numbers outside.</li></ol><p>Then take it into your review and ask for one clear thing: the promotion or the hike. Let the doc do the proving.</p><p>One habit makes next time easy. Add one line to a running log every Friday.</p><h3>The honest part</h3><p>No doc can promise a promotion. Your work, your manager and your company still decide.</p><p>This doc makes sure they decide on your full record, not on memory.</p><h3>Copy this template</h3><pre>REVIEW DOC: [Your name] | [Period] | [Review type]</pre><pre>BUCKET 1: [e.g. Deliver Results]<br>1. [Ticket or PR link]<br>   What: [One sentence. Your part.]<br>   Impact: [A number. Add &quot;est.&quot; if estimated.]<br>   Recognition: [Link. Skip if none.]<br>2. [Next biggest item, same 4 lines]</pre><pre>BUCKET 2: [e.g. Dive Deep]<br>1. [Same 4 lines]</pre><pre>BUCKET 3: [e.g. Ownership]<br>1. [Same 4 lines]</pre><pre>GROWTH<br>- [What I did beyond my tasks] ([link])<br>  Why it matters: [the next-level skill it shows]</pre><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=193e49cee61b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How Fable 5.2 Thinks: 3 Habits Behind the 1,000-Agent Proof]]></title>
            <link>https://medium.com/@saurabhraj042/how-fable-5-2-thinks-3-habits-behind-the-1-000-agent-proof-d56b099b40cf?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/d56b099b40cf</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[fable]]></category>
            <category><![CDATA[claude]]></category>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Thu, 12 Nov 2026 13:18:21 GMT</pubDate>
            <atom:updated>2026-11-12T13:18:21.659Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VvDSi8r7EOm2jOuZFYsOqw.png" /></figure><p><em>A thousand copies of one model wrote a machine-checked proof of Fermat’s Last Theorem in 30 hours. Here is what that run tells us about how the model works, and what you can copy with three agents.</em></p><p>On November 9, 2026, Anthropic released Claude Fable 5.2. One line in the launch post is easy to scroll past.</p><p>A team of 1,000 Fable 5.2 agents wrote out the full proof of Fermat’s Last Theorem in a form a computer can check. It took them 30 hours, with very little human help.</p><p>An earlier attempt by an unreleased Claude model took 11 days. That attempt had a custom-built setup and human researchers guiding it.</p><p>Anthropic also ran the same 1,000-agent setup with Claude Opus 5.5. It finished 26% of the work in 18 hours and then barely moved.</p><p>So the same setup and the same task gave two very different results. The interesting question is why.</p><p>Anthropic has not published the model’s internals. But the launch post describes three behaviours clearly, and I think of them as three habits. Each one is something you can use yourself, even with a tiny setup.</p><h3>What you’ll walk away with</h3><ol><li><strong>The effort dial.</strong> The model chooses how hard to think on each task, and that changes both cost and quality.</li><li><strong>Delegation.</strong> One strong model can hand work down to smaller ones, or sit beside them as an advisor.</li><li><strong>The checklist.</strong> Progress is scored against a list written before the work starts, so “done” cannot be faked.</li></ol><p>At the end there is a simple order to apply these with three agents on your own project.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9elTBoJrAO72_CiXgy1VBw.png" /></figure><h3>The running example: what the Fermat run was</h3><p>The agents did not discover a new proof. Fermat’s Last Theorem was stated in 1637 and proved by Andrew Wiles in the 1990s. His proof runs over a hundred pages and leans on a huge amount of earlier mathematics.</p><p>What the agents did is called formalization. They rewrote the whole proof in Lean, a language where the computer checks every single step. If one step is wrong, the file does not compile.</p><p>Think of the difference between explaining a system design on a whiteboard and shipping code that passes every test. The whiteboard version can skip details. The code version cannot.</p><p>Here is the run, as Anthropic describes it:</p><ul><li>1,000 Fable 5.2 agents worked for 30 hours.</li><li>They started from minimal prompts and built their own way of coordinating.</li><li>They had no maths references. They only had a list of intermediate theorems to measure progress.</li><li>They used about one third of the action tokens of the earlier 11-day attempt.</li><li>The final proof was about seven times shorter than the earlier one.</li></ul><p>I will come back to this run in every section.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EJU4Ackm028Nfq63lCDKuQ.png" /></figure><h3>Habit 1: It picks how hard to think</h3><p>Fable 5.2 has five effort levels: low, medium, high, xhigh and max. Medium is the default in the Claude apps and in Claude Code. The API default is high.</p><p><strong>The mechanism.</strong> Effort is a thinking budget. At low effort the model answers quickly and spends few tokens. At max it reasons for much longer before it commits. It is the same model with a different amount of thinking.</p><p>A good engineer works the same way. You don’t hold a design review to rename a variable. You do hold one before you change a database schema.</p><p><strong>The numbers.</strong> These are from Anthropic’s launch post:</p><ul><li>At low effort, Fable 5.2 matches Opus 5.5’s best score on Humanity’s Last Exam, for less than one tenth of the cost per task.</li><li>At high effort, it scores 45.3% on FrontierCode 2.0. Opus 5.5 at its best scores 45.5%, at roughly twice the cost per task.</li><li>At xhigh effort, it scores 49.1% on the same test, the highest of any released model Anthropic tested.</li></ul><p><strong>How to use it.</strong></p><ol><li>Leave routine work on medium or low. That covers formatting, small edits, boilerplate and simple lookups.</li><li>Raise the effort for work where a wrong first step is expensive. That covers architecture, hard bugs and migrations.</li><li>Check the result before you raise the effort again. More thinking costs more, and it does not always help.</li></ol><p><strong>In the Fermat run.</strong> Anthropic does not say which effort level the agents used. But the logic is clear. With 1,000 agents running for 30 hours, every wasted token is multiplied a thousand times.</p><p><strong>The principle.</strong> Thinking is a budget, so spend it where mistakes are expensive.</p><h3>Habit 2: It delegates</h3><p>One model doing everything is slow and expensive. Anthropic describes two ways Fable 5.2 shares work with other models.</p><p><strong>Pattern A: the orchestrator.</strong> Fable 5.2 sits at the top. It breaks the job into pieces and hands the simpler pieces to smaller, cheaper models. It collects the results and decides what happens next.</p><p>Think of a head chef. The chef plans the menu and tastes every plate. The line cooks chop, fry and plate.</p><p><strong>Pattern B: the advisor.</strong> Here the smaller models are in charge of the work. Haiku, Sonnet or Opus do the task and call Fable 5.2 only when they get stuck.</p><p>Think of a senior engineer on call for a team of juniors. The juniors write the code. The senior answers the three hard questions of the day.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YBIfD7wbqNySDDvWMmHI_g.png" /></figure><p><strong>Real uses from the launch post.</strong></p><ul><li>Datadog describes it as an incident commander that sends faster models out to collect quick signals.</li><li>Uber reports a security audit that ran for 10 to 12 hours with about 170 reviewer agents.</li><li>An Anthropic engineer asked it to build a prototype operating system from an empty folder. It coordinated over 1,000 subagents for eight days. The result boots on a laptop.</li></ul><p><strong>In the Fermat run.</strong> The 1,000 agents started from minimal prompts and built their own coordination. Anthropic has not published what that coordination looked like. So we know that they organised themselves, and we don’t know how.</p><p><strong>How to use it.</strong></p><ol><li>Pick the pattern by where the hard part is. If planning is the hard part, use an orchestrator. If the work is mostly routine with a few hard moments, use an advisor.</li><li>Give each agent one small job with a clear output.</li><li>Keep the expensive model for decisions and the cheap model for volume.</li></ol><p><strong>The principle.</strong> Put the expensive thinking only where it is needed.</p><h3>Habit 3: It checks itself against a list</h3><p>This is the habit I find most useful, and it is the easiest one to copy.</p><p><strong>The mechanism.</strong> The Fermat agents were given no maths references. They were given a list of intermediate theorem statements. Progress was measured against that list.</p><p>The list did two jobs. It told every agent what “done” looks like. It also gave the whole team one shared score that everyone could see.</p><p>Lean added a second layer. A proof step in Lean either compiles or it does not. An agent cannot say “this is probably fine” and move on.</p><p>Put those two together and you get a system where nobody can fake progress. A milestone is either proved and checked, or it is still open.</p><p>Engineers already know this idea. It is a test suite written before the code. The tests define the target, and the green ticks show how far you are.</p><p><strong>The numbers.</strong> Reading off Anthropic’s chart, the Fable 5.2 team had roughly 86% of the milestones done at 18 hours and 100% at 30 hours. The Opus 5.5 team was at 26% at 18 hours and about 27% at 30.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HXD_ZxtCzKYw_Eq7H5WfMw.png" /></figure><p><strong>Why this matters for long runs.</strong> A long agent run fails quietly. One agent claims a task is finished, the next one builds on it, and the error spreads. A checklist that a machine can verify stops that at the source.</p><p><strong>How to use it.</strong></p><ol><li>Write the milestones before you start the agents. Keep them small and specific.</li><li>Make each milestone checkable by a machine. A passing test, a successful build and a query that returns the right rows are all good checks.</li><li>Let the agents see the list and the current score.</li><li>Never accept “done” from an agent without the check passing.</li></ol><p><strong>The principle.</strong> Define “done” before the work starts, and let a machine confirm it.</p><h3>Under the hood: what is documented, and what changed from Fable 5.1</h3><p>Anthropic has not published the architecture, the training method or the model size. Nobody outside the company can tell you which algorithms run inside it.</p><p>What is public is the developer documentation. It describes how the thinking works at the API level, and it lists what changed from Fable 5.1. That is the most technical material that exists today.</p><h3>How the thinking works</h3><p><strong>Adaptive thinking is always on.</strong> You cannot switch thinking off, and you cannot give it a fixed token budget. Both requests return an error. The model decides how much to think at each step, and effort is the only lever you get.</p><p><strong>Effort changes thinking and tool calls, not answer length.</strong> A higher effort means more reasoning and more tool calls. It does not make the reply longer.</p><p><strong>It thinks before almost every reply at high effort and above.</strong> Anthropic’s prompting guide says this includes greetings. Telling it to “answer directly” does not stop the thinking at medium and above. The only way to make it think less is to lower the effort.</p><p><strong>Most of the gain arrives by high.</strong> Above high, the gains are uneven. The Neuron reports that on FrontierCode 2.0, max effort cost over three times as much as xhigh and scored lower.</p><p><strong>Thinking is preserved across turns.</strong> The model’s reasoning from earlier steps is carried forward, so it does not start cold each turn. Each reasoning block is tied to the exact conversation before it. If you edit the system prompt, the tools or an earlier message, the API rejects the request.</p><p>Think of a lab notebook with numbered, signed pages. You can keep adding pages. If you tear one out or rewrite it, every page after it is no longer trusted.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cOJxkHf2te6yi5A1XNMAKg.png" /></figure><h3>What changed from Fable 5.1</h3><ul><li><strong>It reviews its own work with subagents.</strong> At xhigh and max effort, Fable 5.2 sends subagents to check what it produced. Fable 5.1 did not do this on the same tasks.</li><li><strong>Low effort now does what higher effort used to.</strong> Anthropic says Fable 5.2 at low effort scores close to Fable 5.1 at higher effort levels.</li><li><strong>It follows written cautions much more literally.</strong> One “never retry” note in memory cut retries after a busy tool from nearly every attempt to about four in ten. Fable 5.1 and Opus 5.5 kept retrying in a similar test.</li><li><strong>The history check applies to every account.</strong> On Fable 5.1 it applied only to accounts created on or after August 31, 2026.</li><li><strong>The advisor must also be a 5.2 model.</strong> A Fable 5.2 worker cannot take advice from Fable 5.1. The advice comes back encrypted.</li><li><strong>It is cheaper and faster.</strong> The price is 20% lower and output is up to 30% faster.</li><li><strong>It blocks less.</strong> DataCamp reports about 55% fewer safety blocks than Fable 5.1.</li><li><strong>The limits are unchanged.</strong> The context window is 1 million tokens and the maximum output is 128,000 tokens.</li></ul><p>The benchmark jumps from 5.1 to 5.2, from Anthropic’s launch table:</p><ul><li>FrontierCode 2.0: 32.4% to 49.1%</li><li>Remote Labor Index: 17.9% to 41.3%</li><li>RoboDojo Sim: 27.6% to 64.9%</li><li>Terminal-Bench-Science: 52.6% to 74.6%</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SUyNFR3D4ngqbAvMqq_hrg.png" /></figure><h3>One documented weakness</h3><p>On long tasks it sometimes stops early. It may hand back a list of remaining work or stop at an ordinary obstacle like a timeout. Anthropic says this is more common at low and medium effort. In one replay, a “finish the work” instruction in the system prompt roughly halved these early stops, at about 30% more output tokens.</p><p>This links back to the three habits. The self-review is habit 3 built into the model. The early stopping is the reason you still need your own checklist.</p><h3>Priority order: try it with three agents</h3><p>You don’t need 1,000 agents or Fable 5.2 to use these habits. They work with three agents and any capable model. Apply them in this order.</p><p><strong>First, write the checklist.</strong> This gives the biggest return for the least effort. Without it, the other two habits only help you produce wrong work faster.</p><p><strong>Second, split the work.</strong> Use one planner and two workers. The planner owns the checklist and assigns one milestone at a time. Each worker does one milestone and reports back with the check result.</p><p><strong>Third, set the effort.</strong> Give the planner high effort, because its mistakes spread to everyone. Give the workers medium or low, because their jobs are small and checked.</p><p>Here is an example. Say you want to move a small service from one web framework to another.</p><ol><li>The checklist is the existing test suite, plus one line per endpoint: “returns the same response as before”.</li><li>The planner reads the codebase and orders the endpoints from simplest to hardest.</li><li>Worker one migrates an endpoint. Worker two runs the tests and compares responses.</li><li>A milestone is ticked only when the tests pass. Then the planner hands out the next one.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xH87ZYmtvipZF4G5GtBuiQ.png" /></figure><h3>Honest summary</h3><p>There are a few things this article should not leave you believing.</p><ul><li><strong>No new maths was created.</strong> The agents formalized a proof that already existed. DataCamp reports mathematician Kevin Buzzard making this point, and notes there was no outside review at launch.</li><li><strong>The coordination method is not public.</strong> Anthropic says the agents built their own. Nobody outside can inspect it yet.</li><li><strong>“Three habits” is my framing.</strong> Anthropic does not use that phrase. These are behaviours it describes, not a diagram of the model’s internals.</li><li><strong>It is expensive.</strong> Fable 5.2 costs $8 per million input tokens and $40 per million output tokens. Opus 5.5 costs half that. Trending Topics reports that Fable 5.2 is the most expensive model to run on the Artificial Analysis index, and that Anthropic recommends Opus 5.5 for everyday work.</li></ul><p>The result still matters. The same 1,000-agent setup stalled at 26% with one model and finished with another. That gap shows the newer model is better at staying on track through very long work.</p><p>The part you can use today is not the model. It is the three habits. Decide how much thinking each task deserves. Split the work and keep the strong model for decisions. Write down what “done” means and let a machine check it.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d56b099b40cf" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[I Haven’t Picked an AI Model in a Week. Copilot Fusion Did.]]></title>
            <link>https://medium.com/@saurabhraj042/i-havent-picked-an-ai-model-in-a-week-copilot-fusion-did-9f8e91e3f284?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/9f8e91e3f284</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[github-copilot]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Wed, 04 Nov 2026 11:46:33 GMT</pubDate>
            <atom:updated>2026-11-04T11:46:33.817Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kGt5R33rF31tXwoUtoObOw.png" /></figure><p><em>What GitHub’s new model router really does, what the independent benchmark says, and which plan you need to use the setting that was tested.</em></p><h3>The headline everyone is repeating is wrong</h3><p>Some headlines say GitHub Copilot Fusion “matches” Claude Code. It does not.</p><p>The independent benchmark from Artificial Analysis scores Claude Code with Opus 5.5 at 62. Fusion Max scores 60. Fusion loses two of the three tests inside that score. It wins the third, and it wins big on cost and time: $5.59 a task against $11.42, and 36 minutes against an hour.</p><p>That is a better story than “matches”. Fusion is not a smarter model. It is a router that decides which model, and how many models, your prompt deserves.</p><p>I have spent four years in backend and about two years building with AI agents, including a fleet of Copilot agents in VS Code. Every task starts with the same question: which model? Most of us guess. Fusion takes that guess away.</p><p>In this article: what Fusion does, how it works, what the benchmark really says, how it differs from Claude Code, what a week with it feels like, what it costs, which plan you need for the setting that was tested, and everything else GitHub shipped the same day.</p><h3>What Fusion is, and what it can do</h3><p>Fusion went generally available on October 28, 2026, at GitHub Universe. It sits in the model picker. You choose Fusion and an effort level. It then picks the models, the execution pattern and the reasoning effort for each request, and returns one final answer. You never see the drafts in between.</p><p>Why now? GitHub’s Octoverse report says 61% of Copilot users who chose their own model in September used more than one, so people were already juggling models by hand. It also says more than 40% of pull requests now start with a draft from an agent, up from 17% in March. Fusion does the juggling for them.</p><p>What it can do today:</p><ul><li><strong>Pick per request.</strong> One session can mix patterns, so a quick question and a hard bug get different treatment.</li><li><strong>Check model health.</strong> It looks at real-time availability when it chooses.</li><li><strong>Respect your limits.</strong> It only uses models your plan and your admin allow. If none are allowed, Fusion does not appear in the picker.</li><li><strong>Show its work.</strong> Hover over the effort label under a response to see which models ran.</li><li><strong>Run in four places.</strong> VS Code, Copilot CLI, the Copilot app and JetBrains IDEs.</li><li><strong>Use local models (public preview).</strong> At Standard only: MAI Code 1.1 Flash on Windows, and Qwen3.8 Flash Next through a provider such as Ollama.</li><li><strong>Replace the old previews.</strong> If you had picked Auto, HydraFusion or HydraFusion Max, GitHub moved you to the matching Fusion level.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3YABKnChO8A5Jc05eXmZUQ.png" /></figure><h3>How it works: three patterns</h3><p>Fusion is not a model. It is a runtime router and orchestrator. For each prompt it picks one of three patterns.</p><ol><li><strong>Single.</strong> One model does the whole task.</li><li><strong>Cascade.</strong> An efficient model drafts. A judge accepts the draft or sends the task to a stronger model.</li><li><strong>Critique.</strong> One model drafts. Several models review it in parallel. The first model revises using the combined feedback.</li></ol><p>Cascade and Critique take longer, because they make extra model calls.</p><p>To keep cached tokens useful, the main conversation stays on one model when possible. Helper models, like reviewers, get only the context they need.</p><p><strong>Image prompt for Gemini (light mode, three flows side by side):</strong></p><h3>The effort levels, and who gets them</h3><p>You choose the effort. Fusion chooses everything else.</p><ul><li><strong>Standard.</strong> Balances cost, quality and speed. It usually picks one model per task. Built for everyday work.</li><li><strong>High.</strong> Moderate token savings. Built for substantial, well-scoped tasks like complex bugs and multi-file changes.</li><li><strong>Max.</strong> Highest capability, with token efficiency still in mind. Built for the deepest reasoning.</li><li><strong>Fast.</strong> You cannot select it. It exists only in VS Code inline chat.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PM_ClDrYqfyzixZuftmW_w.png" /></figure><p>The plan limits matter, because they decide whether the benchmark applies to you. Standard is on every plan. High starts at Pro+. Max is only on the Max, Business and Enterprise plans.</p><h3>The benchmark, read properly</h3><p>Artificial Analysis ran Fusion on its Coding Agent Index v2.0. The score is a composite of three tests: FrontierCode, Terminal-Bench 4.0 and SWE-Atlas-QnA. It compared Copilot Fusion at Max with Claude Code running Opus 5.5 at Max.</p><p>Score by score:</p><ul><li><strong>Overall index:</strong> Claude Code 62, Fusion 60. Claude Code ahead.</li><li><strong>FrontierCode:</strong> Claude Code 56%, Fusion 51%. Claude Code ahead.</li><li><strong>Terminal-Bench:</strong> Claude Code 63%, Fusion 71%. Fusion ahead.</li><li><strong>SWE-Atlas-QnA:</strong> Claude Code 66%, Fusion 57%. Claude Code ahead.</li></ul><p>Run by run:</p><ul><li><strong>Cost per task:</strong> Claude Code $11.42, Fusion $5.59.</li><li><strong>Time per task:</strong> Claude Code about 1 hour, Fusion 36 minutes.</li><li><strong>Tokens per task:</strong> Claude Code 14.5M, Fusion 7.3M.</li></ul><p>Two honest readings. Fusion does not beat Claude Code overall. And a close composite score hides different strengths: Fusion is stronger on terminal-style work and weaker on the other two tests.</p><p>GitHub also reports its own numbers, up to 77% lower cost in its internal DeepSWE tests. Treat that as the vendor’s claim. The independent average is about 51% lower.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gaHB5eKKYudNCD4I2oEYQQ.png" /></figure><h3>The critical difference: one strong model vs the right amount of model</h3><p>Claude Code, as benchmarked, is one agent running one model: Opus 5.5 at Max. Fusion is neither a model nor an agent. It is a router that decides, prompt by prompt, which models to use, how many, and how hard they should think.</p><ul><li><strong>Claude Code bets on one strong model.</strong> Same model and same effort setting on every prompt.</li><li><strong>Fusion bets on the right amount of model.</strong> An easy prompt takes the short path. A hard one gets a stronger model, or a review round.</li><li><strong>What the scores say.</strong> Fusion is ahead on the terminal test, cost, time and tokens. Claude Code is ahead on the overall index and the other two tests.</li><li><strong>Versus the old Auto.</strong> Auto picked a model. Fusion combines that with the multi-model orchestration from the HydraFusion preview, so it also decides how many models work on your prompt.</li><li><strong>What you give up.</strong> Predictability. Two prompts that look alike can take different routes, and some routes are slower. If you want the same model every time, you can still pick one yourself in the picker.</li></ul><p>In one line: Claude Code bets on one strong model. Fusion bets on the right amount of model.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5iQ6lg81NDuTUP1KAY2zhw.png" /></figure><h3>What “half the cost” means, and what it does not</h3><p>The $5.59 is an API cost, not your bill. Artificial Analysis measures the average pay-per-token cost of a task: input, cached input, cache writes and output. It leaves out consumer plan prices and your own engineering time.</p><p>That makes it a fair like-for-like number. It does not tell you what you will pay on a Copilot plan.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*nWLflf0Paz5WNt7KBvPDjQ.png" /></figure><p>Here is how Copilot bills Fusion:</p><ul><li><strong>No separate Fusion charge.</strong> You pay the standard rate for each model Fusion uses.</li><li><strong>High and Max can cost more than Standard.</strong> They can call several models for one task.</li><li><strong>A 30% discount, for now.</strong> Through November 30, 2026, paid Copilot plans get 30% off model costs when using Fusion. This is separate from the benchmark savings.</li></ul><p>One more thing the benchmark cannot count: the minutes you spend reviewing the result. Half the cost is not half the work.</p><h3>How to turn it on</h3><ol><li><strong>Update your client.</strong> Fusion replaced the old Auto and HydraFusion preview switches.</li><li><strong>Open the model picker.</strong> In VS Code, JetBrains and the Copilot app, click the model name. In Copilot CLI, run /model.</li><li><strong>Pick Copilot Fusion, then an effort level.</strong> The levels you see depend on your plan.</li><li><strong>Send a prompt, then hover over the effort label.</strong> It shows which models actually ran.</li></ol><p>If Fusion is missing from the picker, your plan or your admin’s policy has excluded all of its models.</p><p>Want to try the local model preview? In the Copilot app, turn on <strong>Local model auto routing</strong> under Experimental in settings. In Copilot CLI, start with --experimental or run /experimental on. It only applies at Standard.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Ie1G3STZzUnMIZGGLVZS3A.png" /></figure><h3>A week with Fusion: what changes day to day</h3><p>I have used Fusion for a week, and I have not picked a model once. That is the whole change, and it is bigger than it sounds. Every task used to start with a small decision about the model. Now it starts with the task.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mjAWrtZnfTKq0E9GSO-fhw.png" /></figure><p>What else you notice over a week:</p><ul><li><strong>You stop thinking in model names.</strong> You watch the effort label. When you are curious, you hover over it and see which models ran. The answer changes from prompt to prompt, because Fusion chooses per prompt.</li><li><strong>Speed is uneven.</strong> Quick answers come fast. Cascade and Critique take longer, because they make extra calls.</li><li><strong>Standard stays simple.</strong> At Standard, Fusion usually uses one model per task.</li><li><strong>Review matters more.</strong> A discarded draft can leave file edits behind, so you read the whole diff, not only the summary.</li><li><strong>Credits follow the level.</strong> High and Max can call several models, so they can use more credits than Standard.</li></ul><h3>Which level for which job</h3><p>This is my read of GitHub’s own descriptions, not a tested rule. Start low and move up only when the work asks for it.</p><ul><li><strong>Standard for the daily grind.</strong> Small edits, questions about the code, boilerplate, tests.</li><li><strong>High for the task that spans files.</strong> A bug that touches several modules, or a change that needs a plan. You need Pro+ or above.</li><li><strong>Max when the problem is hard to reason about.</strong> Deep debugging, tricky design calls. You need the Max, Business or Enterprise plan.</li></ul><p>On any level, keep one score: credits spent per change you actually merged. A cheap run that you throw away is not cheap.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XN7yS8eiz4PRNdIYVJ_juw.png" /></figure><h3>Gotchas and limits</h3><ul><li><strong>Rejected drafts can leave edits behind.</strong> If Fusion discards a draft, the file changes that draft made are not undone. Review the full diff before you commit.</li><li><strong>No subagents.</strong> Fusion does not start or work with them.</li><li><strong>No context window of its own.</strong> It shows a conservative number, the smallest limit among the models it uses.</li><li><strong>Slower on hard prompts.</strong> Cascade and Critique make extra calls.</li><li><strong>The pool and the patterns can change.</strong> GitHub says so in its docs.</li><li><strong>The tested tier is not for everyone.</strong> Max is not on Free, Student, Pro or Pro+.</li><li><strong>The discount is temporary.</strong> It ends after November 30, 2026.</li><li><strong>One benchmark is a hint, not proof.</strong> It averages its own tasks. Your codebase is different, so run your own test.</li></ul><h3>Also announced on October 28</h3><p>Fusion was the headline. It was not the only launch. GitHub’s changelog lists 22 Copilot entries for October 27 and 28. These are the ones that matter if you write code for a living.</p><ul><li><strong>Code review Max (public preview).</strong> A third review level above Lite and Balanced, built for risky changes like auth logic and shared libraries. Several independent review agents, each on a model from a different provider, review the pull request. An aggregation agent then merges their findings into one review. It takes longer and uses more AI credits. GitHub claims the top ReviewBench score for high-severity issues, which is its own claim.</li><li><strong>Approvals (generally available).</strong> Copilot can approve a pull request, and that approval counts toward the required approvals. It is off by default, admins switch it on, and new commits dismiss the approval. Available on Pro, Pro+, Max, Business and Enterprise.</li><li><strong>Agent Merge.</strong> Choose “Watch and fix” in the merge box. Copilot fixes failing Actions workflows, merge conflicts or both, in a cloud environment. Pair it with auto-merge. It needs a paid plan.</li><li><strong>Connected cloud sessions (generally available on paid plans, rolling out from October 28).</strong> Start a task on github.com, GitHub Mobile, the CLI, the Copilot app, VS Code, Slack or Teams, then continue it somewhere else. Each session runs in a cloud sandbox with no one-hour limit. Sandbox billing begins in November 2026, and the included Actions allowance becomes one shared dollar-based pool.</li><li><strong>Copilot app: Projects and computer use (both public preview).</strong> Projects group work across repositories, with the context, agents and results in one place. Computer use lets Copilot operate desktop apps on macOS and Windows, with your approval.</li><li><strong>Automations.</strong> Prompts, triggers and tools combined into cloud workflows that a team can share. They are rolling out to Pro and above, and the credits are billed to whoever owns the repository. GitHub says they now learn from outcomes and propose changes for you to approve.</li><li><strong>Enterprise credits.</strong> GitHub Enterprise customers can use every Copilot feature without a separate subscription and pay for the AI credits they use. For now, it goes through GitHub sales.</li><li><strong>The rest of the list.</strong> GitHub Agentic Workflows became generally available, Copilot can generate and edit images, and the Copilot SDK is becoming the Microsoft Copilot SDK.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HH2giPLr1aCUe5jlxwScUQ.png" /></figure><h3>Run your own 30 minute test</h3><p>Benchmarks average other people’s tasks. Your repo is the only one that counts. Here is a fair test.</p><ol><li>Pick one real bug that has a failing test.</li><li>Run it once with Fusion Standard.</li><li>Reset the branch and run it again with the model you normally pick.</li><li>Write down four things for each run: credits used, minutes taken, whether the test passes, and how much you had to clean up.</li><li>Hover over the effort label to see which models Fusion used.</li><li>If your plan allows, repeat on High.</li></ol><p>Fixing one model for the comparison run removes routing as a variable. That is what makes the test fair.</p><h3>The verdict</h3><p>Fusion does not beat Claude Code. On the independent benchmark it trails by two points overall, wins the terminal test, and costs about half as much to run, in about 40% less time.</p><p>So do not switch tools because of a headline. Do this instead:</p><ul><li>On any plan, try Fusion Standard for everyday work and watch the credits.</li><li>On Pro+, add High for multi-file tasks.</li><li>On Max, Business or Enterprise, test Max against the model you use today.</li><li>Use the discount while it lasts. It runs through November 30, 2026.</li></ul><p>The real change is not a new best model. It is that choosing the model is no longer your job.</p><p>I broke this down in a short reel on Instagram, @raaz.builds. Comment <strong>FUSION</strong> there and I will send the setup.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aGzrGEpLpFC9sjT_kPPsBQ.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9f8e91e3f284" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Anthropic Just Launched Its Personal AI Agent (Claude Duet)]]></title>
            <link>https://medium.com/@saurabhraj042/anthropic-just-launched-its-personal-ai-agent-claude-duet-e2144f3c494d?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/e2144f3c494d</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[claude]]></category>
            <category><![CDATA[automation]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Sat, 31 Oct 2026 11:16:24 GMT</pubDate>
            <atom:updated>2026-10-31T11:16:24.408Z</atom:updated>
            <content:encoded><![CDATA[<h4><em>Here’s how it works, its core capabilities, and 5 ways it differs from OpenClaw and Hermes.</em></h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wxo7CXvBQ5rXnzaAv1pTcw.png" /></figure><p>Every personal AI agent promises the same thing: it handles the boring part of your Monday while you do the real work. Chase the unpaid invoice, draft the customer follow-up, flag the email that actually matters. What differs is who runs it and who holds the keys to your accounts.</p><p>On <strong>October 21</strong>, 2026, Anthropic added a new option with Claude Duet, a hosted agent that works in the background and asks before it acts. It lands in a field already shaped by two open-source agents, OpenClaw and Hermes. This article compares all three on the things that decide whether you can trust them: where they run, how they remember, what they are allowed to do on their own, and what you have to maintain.</p><p>The name is the pitch. In a duet, two parts play together and neither carries the whole song. Claude Duet is built on that idea: you set the direction, it watches your accounts, does the groundwork, and comes back to you before anything consequential happens.</p><h3>What You’ll Walk Away With</h3><ol><li><strong>Two types of personal AI agents</strong>, and why who holds the keys decides your risk.</li><li><strong>How Claude Duet works</strong>: where it runs, how it finds work, and where it stops to ask you.</li><li><strong>Its core capabilities</strong>, in plain language.</li><li><strong>The two open alternatives</strong>, OpenClaw and Hermes, with what each costs you in setup.</li><li><strong>A side-by-side image</strong> you can generate and drop in.</li><li><strong>Five ways Duet differs</strong> from the open agents, and where it loses.</li><li><strong>Which one to pick</strong> for your situation.</li><li><strong>How to get started</strong> with each, plus a hardening checklist.</li><li><strong>A priority order</strong> and an honest summary.</li></ol><h3>Two Types of Personal AI Agents: Who Holds the Keys</h3><p>Personal agents come in two families.</p><p><strong>Hosted agents</strong> run on someone else’s infrastructure. You connect your apps, the vendor runs the agent, and the vendor is responsible for the sandbox, the credential handling and the uptime. Claude Duet is in this family. So are Meta’s Muse and OpenAI’s Dots, which VentureBeat names as its direct rivals.</p><p><strong>Self-hosted agents</strong> run on hardware you control, on your laptop, a home server or a rented VPS. You choose the model, you install the skills, and you own every security decision. OpenClaw and Hermes Agent are in this family, and both are open source under the MIT license.</p><p>The trade is simple. Hosted gives you less setup and a vendor-managed safety layer, and costs you control and access. Self-hosted gives you control and customisation, and makes you the security team.</p><h3>The Running Example: One Overdue Invoice</h3><p>We use one scenario throughout. It is Monday morning. A client invoice is two weeks overdue, a customer is waiting on a follow-up, and you want a short list of what needs you today. For each agent we ask the same four questions:</p><ol><li>Where does it run, and does it need your laptop on?</li><li>How does it know the invoice is overdue?</li><li>What may it do without asking?</li><li>What happens if it gets it wrong?</li></ol><p>Keep these four questions in mind. Every section below answers them in the same order.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*WLIE0Sul9Oc1XQyEnWIVxw.png" /></figure><h3>How Claude Duet Works</h3><p>Anthropic announced Claude Duet on October 21, 2026 as a research preview. Its own description: an agent that surfaces what needs your attention, completes tasks you assign, keeps working when you step away, and checks with you before acting on your behalf. It is aimed at professionals and small business owners. VentureBeat and MacRumors both report it runs on Opus 5.5.</p><p><strong>1. Where it runs.</strong> On its own virtual machine with its own browser, in Anthropic’s cloud. Your laptop or phone does not need to be on. You reach it through a standalone iOS and Android app or on claude.ai, in one ongoing thread by typing or voice, and it carries over the memory, skills and connected apps from your Claude account. (MacRumors describes the apps slightly differently, as web plus iOS. Anthropic’s own page lists iOS, Android and claude.ai.)</p><p><strong>2. How it knows the invoice is overdue.</strong> Through connectors. Anthropic says it works with more than 6,000 connectors and plugins in the Claude Marketplace, with examples including Gmail, Slack, QuickBooks, Stripe, Gusto, LinkedIn, DocuSign, HubSpot, Canva and Shopify. It sends a short morning brief, and it checks connected accounts every few hours, messaging you only when something needs attention. You choose what you hear about and how often. VentureBeat stresses this is not continuous, real-time monitoring, and that more frequent checks use up your usage allowance faster.</p><p><strong>3. What it may do without asking.</strong> It reads, drafts and prepares work on its own. Before it sends a message, makes a payment, signs a document or deletes anything, it shows you the action and waits for your approval. Some actions are off-limits even with approval: trading securities and moving money between accounts. For purchases it can use a Stripe Link virtual card, so your real card number is not shared, or check out with Shop Pay.</p><p><strong>4. What happens if it gets it wrong.</strong> Anthropic lists its own caveats: it may misread a thread or misjudge what is urgent, personal errands such as booking tickets are weaker because it was built around work, and you cannot yet watch its browser. The approval gate is the safety net for the actions that matter, and you can disconnect any app at any time.</p><p><strong>Safety design, as described by Anthropic.</strong></p><ul><li>Credentials are isolated: it does not directly see passwords or sign-in tokens.</li><li>A classifier and system prompt screen messages for sensitive data. The strictest tier, such as card numbers and government ID, is designed to be rejected. Health and personal finance information is shared only when you explicitly tell it to.</li><li>Prompt-injection defenses, red-team and external penetration testing, and a public bug bounty program.</li><li>Anthropic also says its protections are still being developed. VentureBeat’s read: these are descriptions of safeguards, not proof of reliability.</li></ul><p><strong>Who can get it, and what it costs.</strong> The preview is by waitlist, starting with US Pro and Max subscribers. VentureBeat reports it is not available on Team or Enterprise plans, and no API or enterprise rollout date has been announced. There is no separate price: it is included in Pro and Max and shares your plan’s usage limits, and background checks and bigger tasks such as financial models or decks use more of that allowance. Coming soon, per Anthropic: a visual Shopify storefront editor and 1Password sign-ins with your permission.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GFvaCgPiudB2tVeuEoubww.png" /></figure><h3>Its Core Capabilities</h3><p>As described by Anthropic and the launch coverage:</p><ol><li><strong>A morning brief.</strong> A short summary of the key items across your connected apps.</li><li><strong>Background checks.</strong> It looks at your connected accounts every few hours and messages you only when something needs attention. You tune the topics and the frequency.</li><li><strong>Work that continues without you.</strong> Tasks run on its own virtual machine and browser, and you get a notification when one finishes or needs review. Anthropic’s examples include chasing unpaid invoices, drafting customer follow-ups, building financial forecasts, preparing briefings and creating web apps.</li><li><strong>Thousands of connectors.</strong> More than 6,000 connectors and plugins through the Claude Marketplace, including Gmail, Slack, QuickBooks, Stripe, Gusto, LinkedIn, DocuSign, HubSpot, Canva and Shopify.</li><li><strong>One ongoing thread.</strong> Text or voice, with the memory, skills and connected apps from your Claude account carried over.</li><li><strong>An approval gate.</strong> Anything that sends, pays, signs or deletes waits for you.</li><li><strong>Safer purchasing.</strong> It can buy through a Stripe Link virtual card or check out with Shop Pay, so your real card number is not shared.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OlWyQEaSeITZnZVAd70IvQ.png" /></figure><h3>The Open Alternative #1: OpenClaw</h3><p>OpenClaw describes itself as an open-source AI assistant that runs on your own computer and works through the chat apps you already use. It is MIT licensed, stewarded by an independent nonprofit (the OpenClaw Foundation, a 501(c)(3)), and has no paid tier or hosted service. Its GitHub page showed about 393,000 stars when I checked on October 31, 2026.</p><p><strong>1. Where it runs.</strong> On your hardware. The core is the Gateway, which its docs call the control plane for sessions, tools, events and channel connections. The same Gateway can serve one person or a shared team deployment. Native apps exist for macOS, iOS, Android, Windows and Linux. Install options include a shell script, PowerShell, npm (npm install -g openclaw@latest, which needs a recent Node version), Docker and Nix.</p><p><strong>2. How it knows the invoice is overdue.</strong> You wire it up. It reaches you and your tools through channels (Discord, iMessage, Slack, Teams, Telegram, WhatsApp, Google Chat, Signal and 20+ others) and gains abilities through tools, skills and plugins shared via ClawHub. Models are swappable: hosted providers including Claude and Codex, or local models. State, memory and credentials stay on your own machine.</p><p><strong>3. What it may do without asking.</strong> This is the part to read twice. OpenClaw’s page states that tools run on the host for the main session unless you configure sandboxing, and it links a sandboxing guide. Whatever autonomy the agent has is whatever you configured.</p><p><strong>4. What happens if it gets it wrong.</strong> The consequences land on your own machine and accounts. The Kilo comparison reports the following, and I flag it as a secondary source: six agent-specific CVEs in 2026, more than 135,000 exposed instances found on Shodan, defaults designed for a personal laptop rather than a public server, 341+ malicious skills found in the community repository, and community complaints about unreliable memory. Treat those figures as a reason to audit your setup, not as a verdict. They come from one blog, and both OpenClaw and Hermes offer sandboxing and approval flows.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QVJL_kX3byUwq4N9vjStqw.png" /></figure><p><strong>Best at:</strong> reaching you wherever you already chat, a huge skill ecosystem, and team deployments. <strong>Costs you:</strong> setup, hardening, uptime and constant review of what you install.</p><h3>The Open Alternative #2: Hermes Agent</h3><p>Hermes Agent is built by Nous Research and is described on its GitHub page as “the self-improving AI agent.” It is MIT licensed, and the page showed about 253,600 stars on October 31, 2026. Where OpenClaw starts from the gateway, Hermes starts from the agent: Kilo’s summary is that Hermes packages a gateway around a learning agent.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*RTYPJnnH5zQTWwpKETOdwA.png" /></figure><p><strong>1. Where it runs.</strong> Wherever you point it. One gateway process connects the agent to Telegram, Discord, Slack, WhatsApp, Signal and Email, alongside a terminal UI. Seven terminal backends decide where its commands actually execute: local, Docker, SSH, Singularity, Modal, Daytona and Vercel Sandbox, with Modal and Daytona offering serverless persistence. Install on Linux, macOS or WSL2 with the official one-line script (curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash), with a PowerShell version for native Windows.</p><p><strong>2. How it knows the invoice is overdue.</strong> Through the tools and skills you give it, and then through its own memory. Hermes keeps agent-curated persistent memory and user profiles, searches past conversations, and builds a model of you over time. It has a built-in scheduler that runs recurring tasks and delivers results to any connected chat platform. That scheduler is how a “check invoices every morning” job would live. It can use Nous Portal (300+ models) or OpenRouter, OpenAI and custom endpoints, and you switch with hermes model.</p><p><strong>3. What it may do without asking.</strong> That depends on the backend and approval settings you choose. The sandbox choice matters: running commands in Docker or a remote sandbox is a very different risk from running them locally. Kilo’s write-up notes checkpoints with a /rollback command.</p><p><strong>4. What happens if it gets it wrong.</strong> The distinctive risk is the learning loop. Hermes creates skills from completed tasks, refines them during use, and prompts itself to save knowledge. That is the feature, and it is also where Kilo reports drawbacks: it can rate its own work as successful, and self-learning can overwrite skills you edited by hand. Review the skills it writes the way you would review a teammate’s pull request.</p><p><strong>Best at:</strong> getting better at repeated work such as research synthesis, code review and recurring reports, plus subagents and multiple sandbox choices. <strong>Costs you:</strong> a smaller ecosystem than OpenClaw, and the same self-hosting duties.</p><h3>Side by Side</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pwd53Q0MmJ2i6u1PDOwFJg.png" /></figure><h3>5 Ways Claude Duet Differs From OpenClaw and Hermes</h3><p>These are documented differences, not a ranking. Each one is a trade, and the last section says when the trade goes the other way.</p><ol><li><strong>Nothing to host.</strong> Duet runs on Anthropic’s cloud VM, so your laptop can be off. OpenClaw and Hermes run where you install them, and you handle uptime and updates.</li><li><strong>The approval gate ships built in.</strong> Duet shows you any send, payment, signature or deletion and waits, and it refuses trades and account-to-account transfers even with approval. In the self-hosted agents, what needs approval depends on how you configure them.</li><li><strong>Credentials stay out of the agent’s hands.</strong> Anthropic says Duet does not directly see passwords or sign-in tokens and uses the same credential design as Claude Managed Agents. With a self-hosted agent, credentials live on your machine and protecting them is your job.</li><li><strong>A curated connector marketplace.</strong> Duet draws on 6,000+ connectors in the Claude Marketplace. OpenClaw’s community skill repository is larger and more open, and one secondary report found 341+ malicious skills in it, so you must vet what you install.</li><li><strong>Your Claude memory comes along.</strong> Duet carries over memory, skills and connected apps from your Claude account into one thread. Hermes instead builds its own memory and skills through its learning loop, and OpenClaw keeps state on your own hardware.</li></ol><p><strong>Where Duet loses.</strong> It is a US-only research preview on a waitlist for Pro and Max, it is not on Team or Enterprise plans, it checks every few hours instead of continuously, it is weaker on personal errands, and you cannot see its browser yet. If you need access today, control, a choice of model, or a learning loop, the open agents win those rounds.</p><h3>Which One to Pick</h3><p>Three questions decide it. Answer them in this order.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bgcqBkuTf7a2X7H_ywWd3g.png" /></figure><p><strong>1. Are you eligible, and does the work fit?</strong> Duet is a US-only research preview for Pro and Max subscribers, by waitlist, and VentureBeat reports it is not on Team or Enterprise plans. Anthropic says it was built around work (inbox, invoices, customers, documents), and personal errands are weaker. If you are outside that, or your work is mostly code and research, the self-hosted agents are your only option today.</p><p><strong>2. How much of the security job do you want?</strong> With Duet, Anthropic runs the sandbox, isolates credentials and gates the risky actions. With OpenClaw or Hermes, all of that is yours. If nobody on your side will own it, pick hosted.</p><p><strong>3. What shape is the work?</strong></p><ul><li>Many chat apps, a big ecosystem, a shared team assistant: OpenClaw.</li><li>Repeated work that should get better over time, subagents, a choice of sandbox: Hermes.</li><li>Inbox, invoices, customer follow-ups, documents, with an approval before anything goes out: Duet.</li></ul><p><strong>Combinations that make sense.</strong> The Kilo write-up’s author runs both open-source agents together: OpenClaw as the orchestrator for messaging and scheduling, and Hermes as the execution specialist, connected through ACP. Beyond that, a natural split is a hosted agent for admin work on your business accounts and a self-hosted one for engineering tasks you want full control over. That split is my own suggestion, not a documented setup.</p><p><strong>Shortcuts by persona.</strong></p><ul><li>Solo founder or freelancer in the US on Pro or Max: join the Duet waitlist, and start a self-hosted agent while you wait.</li><li>Developer who wants to tinker: Hermes if you like the learning loop, OpenClaw if you want reach and plugins.</li><li>Team that needs one shared assistant: OpenClaw’s team deployment, with sandboxing and an owner for it.</li><li>Anyone handling sensitive client data: prefer the setup whose approval and credential model you can actually verify.</li></ul><h3>Get Set Up</h3><p><strong>Claude Duet.</strong></p><ol><li>Check you are on a US Pro or Max plan.</li><li>Join the waitlist on Anthropic’s Duet page. Anthropic says it will email you when access is ready.</li><li>When access opens, connect only the apps the job needs (for the invoice example: your accounting tool and your email), then set what you want to hear about and how often. More frequent checks use more of your plan’s allowance.</li><li>Treat every approval prompt as a real decision. The gate only protects you if you read what it shows.</li></ol><p><strong>Hermes Agent.</strong></p><pre>curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash<br>hermes model        # pick your model provider</pre><p>Then pick a sandbox backend before you give it real tasks, connect one chat platform, and schedule one small recurring job with the built-in scheduler.</p><p><strong>OpenClaw.</strong></p><pre>npm install -g openclaw@latest</pre><p>The shell-script, PowerShell, Docker and Nix routes are on its GitHub page. Set up sandboxing first, since the main session runs tools on the host otherwise, then connect one channel.</p><p>A general habit for any curl | bash installer: open the script in your browser or editor first and read it before you run it.</p><p><strong>A hardening checklist for the self-hosted pair</strong> (general good practice, not taken from either project’s docs):</p><ul><li>Run commands in a container or remote sandbox, not on your daily machine.</li><li>Do not expose the agent’s port to the public internet.</li><li>Give it its own accounts and API keys with the narrowest permissions that work. Use a virtual or low-limit card for anything that spends money.</li><li>Install skills and plugins only after reading them. Community repositories have contained malicious entries.</li><li>Require approval for sending, paying, deleting and signing, and keep logs you actually review.</li><li>With Hermes, review every skill it writes, and keep your hand-edited skills under version control so they cannot be silently overwritten.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ItI3fEq_Svj0bdzU9a2U5w.png" /></figure><h3>Priority Order</h3><ol><li><strong>Decide who holds the keys.</strong> Hosted or self-hosted is the real choice. Everything else follows.</li><li><strong>Start with one narrow job</strong>, like the overdue-invoice chase, not “run my life”.</li><li><strong>Connect the minimum number of accounts</strong>, and keep approvals on for send, pay, sign and delete.</li><li><strong>Add proactivity last.</strong> Morning briefs and scheduled jobs are useful, but they spend your usage allowance or your own compute.</li><li><strong>Only then compare ecosystems</strong>: channels, skills, marketplace size.</li></ol><h3>The Honest Summary</h3><p>Claude Duet’s pitch is not that it can do something the open-source agents cannot. It is that the vendor takes on the sandbox, the credential handling and the approval gate, in exchange for you giving up control and waiting for access. OpenClaw and Hermes give you the reverse: full control, free software, and the whole security job. Anthropic itself says Duet can misread a thread, misjudge urgency and is weaker on personal errands, and that its protections are still being developed. No head-to-head performance data against Muse, Dots, OpenClaw or Hermes exists yet, so any claim that one “wins” is an opinion. Pick on who you want holding the keys, not on a leaderboard.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e2144f3c494d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Build an Agentic Knowledge Graph From Scratch: No Graph DB, No Extraction Model]]></title>
            <link>https://medium.com/@saurabhraj042/build-an-agentic-knowledge-graph-from-scratch-no-graph-db-no-extraction-model-074d944a68b3?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/074d944a68b3</guid>
            <category><![CDATA[data-engineering]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[rags]]></category>
            <category><![CDATA[knowledge-graph]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Sat, 31 Oct 2026 07:00:20 GMT</pubDate>
            <atom:updated>2026-10-31T07:00:20.604Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x8C2YRTNTrUJhU1LaLgP2A.png" /></figure><p>Most teams that want an AI agent to answer multi-hop questions over a big pile of documents do the same thing: pay an LLM to read every page, extract entities, and build a knowledge graph. One published estimate puts that indexing step at roughly $33,000 for a single large corpus. But if your documents already contain their own links, citations or categories, that bill is optional. The graph is already there. You only have to parse it.</p><p>This article is the blueprint for building that system from scratch: a laptop-sized graph engine, an agent that walks it, cites every step, and refuses to answer when no path exists. Everything below is runnable with Python and DuckDB, and every number I report as measured was measured on a 2-core, 7 GB sandbox.</p><h3>What You’ll Walk Away With</h3><ol><li><strong>The one idea</strong> that makes this cheap, and the exact test for when it does not apply.</li><li><strong>A running example</strong> you can reproduce: a Wikipedia slice, one real question, traced end to end.</li><li><strong>The high-level design</strong>: six components, no graph database, no extraction model.</li><li><strong>The build, step by step</strong>: parse dumps to Parquet, resolve redirects, build the path engine, add search, wire the agent.</li><li><strong>The evaluation harness</strong> that generates its own multi-hop questions and scores accuracy, citation precision and refusals.</li><li><strong>How to point it at your own corpus</strong>: docs, papers, wikis, code.</li><li><strong>Cost, scale and failure modes</strong>, with the honest limits.</li><li><strong>A priority order</strong> so you build the right thing first.</li></ol><h3>The One Idea: Parse, Don’t Extract</h3><p>When a corpus already ships its edges, building the graph is a parse, not an extraction.</p><p>The usual GraphRAG pipeline sends every chunk of text to an LLM to find entities and relations. Microsoft’s own description says the build step “uses an LLM to extract and describe entities and their relationships” and a second LLM pass summarizes each community. Microsoft’s cheaper LazyGraphRAG variant avoids both and, in their words, costs “0.1% of the costs of full GraphRAG” to index.</p><p>But some corpora are already graphs in disguise:</p><ul><li><strong>Wikipedia</strong> ships page links, categories and redirects as plain database dumps.</li><li><strong>PubMed</strong> ships citations and controlled vocabulary tags (MeSH) in every record.</li><li><strong>Docs sites and wikis</strong> ship hyperlinks and tables of contents.</li><li><strong>Code</strong> ships imports and call sites.</li></ul><p>For those, an LLM would be re-discovering relationships a human author already wrote down, with errors. Parsing them is deterministic, free and reproducible.</p><p><strong>The test for when this does NOT work:</strong> if your corpus has no explicit links, citations or tags (raw meeting notes, support tickets, PDFs of contracts), there are no edges to parse. Then you need extraction, and the honest answer is a hybrid: parse whatever edges exist, and run an LLM only on the slice that has none.</p><p><strong>What you give up.</strong> Parsed edges are untyped. A Wikipedia link says “A mentions B”, not “A founded B”. That is enough to answer “how are these two things connected?” with a citable path. It is not enough for questions that depend on the relation type. We handle that in the agent step by reading the cited text, and I flag it again in the limits section.</p><h3>The Running Example: Wikipedia, Two Questions</h3><p>We use English Wikipedia because anyone can download it, it needs no account, and it ships exactly the three edge types we want: page links, categories and redirects. It is licensed CC BY-SA, so you must attribute and share-alike if you republish derived text.</p><p>Two questions follow us through the whole article:</p><ul><li><strong>Q1 (answerable):</strong> “How is Alan Turing connected to the Enigma machine?”</li><li><strong>Q2 (should be refused):</strong> “What did Alan Turing think of the 2024 Olympics?” There is no path from the question’s entities to any page that supports it.</li></ul><p>The shape of what the agent returns for Q1 (illustrative format, not a captured run; your real path depends on your slice and dump date):</p><pre>Q: How is Alan Turing connected to the Enigma machine?<br>PATH (2 hops): Alan Turing -&gt; Bletchley Park -&gt; Enigma machine<br>CITE: [1] Alan Turing, link to &quot;Bletchley Park&quot;<br>      [2] Bletchley Park, link to &quot;Enigma machine&quot;<br>ANSWER: Turing worked at Bletchley Park, which is linked to the Enigma machine page. (sentence checked against the cited text)</pre><p>And for Q2 the correct output is a refusal:</p><pre>Q: What did Alan Turing think of the 2024 Olympics?<br>PATH: none within 3 hops<br>ANSWER: Not supported by the corpus. No cited path.</pre><p>That second output is the product. Any chatbot can answer Q1. A trustworthy system is one that visibly declines Q2.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b6Qk8tBJwU6UNsllTa788Q.png" /></figure><h3>The High-Level Design</h3><p>Six components, one direction of data flow, zero external services except the model that drives the agent.</p><ol><li><strong>Ingest.</strong> Stream the raw dumps (SQL or XML, gzipped) without unpacking them to disk. Output: Parquet files. Nothing else is stored.</li><li><strong>Edge store.</strong> Four Parquet tables queried in place by DuckDB: pages(id, title, ns), redirects(from_id, to_id), links(src, dst), page_cats(page_id, category).</li><li><strong>Graph engine.</strong> Redirects are folded into links once, then links is turned into a CSR adjacency (two integer arrays) in memory. Path queries are a bidirectional breadth-first search with a hop cap.</li><li><strong>Entry-point search.</strong> BM25 full-text search over titles and lead text. Its only job is to turn a natural-language question into start nodes. It never answers anything.</li><li><strong>Agent loop.</strong> An LLM with five tools: search, neighbors, path, categories, read (returns the cited text). The loop is capped, and it must cite a path or refuse.</li><li><strong>Eval harness.</strong> Generates held-out multi-hop questions from the graph itself, runs the agent, and scores accuracy, citation precision and refusal correctness.</li></ol><p><strong>Why no graph database.</strong> A graph DB buys you a query language and transactions. This workload is read-only, bulk-loaded and needs only neighbour lookup and shortest path. Parquet plus an in-memory CSR does that with fewer moving parts. I measured it (below). If you later need live updates or graph algorithms at scale, add a database then. That is a decision you can defer.</p><p><strong>Why DuckDB.</strong> It queries Parquet directly, runs on a laptop, and its recursive queries are enough for SQL-side path checks. I verified a depth-limited recursive path query with cycle protection on DuckDB 2.0.0. The final path engine in step 3 uses arrays in memory instead, because it is faster for repeated queries.</p><p><strong>Data model decisions that matter:</strong></p><ul><li>Store integer IDs only. Titles live once in pages. Edges are 8 bytes.</li><li>Keep ns (namespace) so you can restrict to articles and drop talk pages, user pages and files.</li><li>Keep category links as a separate edge type. They give you a second, coarser path (two pages sharing a category) when direct links do not connect.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*sU-9_m-xDahn5o1pTo9sVA.png" /></figure><h3>Steps 1 and 2: Ingest the Dumps, Measure Retention First</h3><p><strong>Get the files.</strong> The English Wikipedia dumps live at dumps.wikimedia.org. For the 20260201 dump the relevant gzipped SQL files are listed at these sizes: page 2.2 GB, pagelinks 6.4 GB, linktarget 1.3 GB, categorylinks 2.2 GB, redirect 173 MB. Start with a smaller wiki (Simple English Wikipedia is the same format) to get your parser right before touching the big one.</p><p><strong>Parse by streaming.</strong> The SQL dumps are giant INSERT INTO ... VALUES (...),(...); statements. Do not load them into MySQL. Read the gzip stream, split each INSERT line into tuples with a small state machine that respects quotes and escapes, and append batches to Parquet with PyArrow. Memory stays flat because you never hold more than one batch.</p><p><strong>Mind the schema change.</strong> Modern MediaWiki no longer stores the target title inside pagelinks. A link row carries a numeric pl_target_id that you resolve by joining to the linktarget table (lt_id, lt_namespace, lt_title), then joining the title to page. Check the CREATE TABLE header at the top of your own dump file before you write the parser. Categories are simpler: categorylinks still stores the category name in cl_to with cl_from as the page ID and a cl_type of page, subcat or file.</p><p><strong>Resolve redirects once.</strong> Many links point at a redirect page (“USA”), not the real article. Build a map from redirect ID to final page ID, then rewrite links.dst through it. Do this at build time, not at query time. Collapse redirect chains with a bounded loop (three passes is plenty), and drop self-links.</p><p><strong>Measure retention before you trust the graph.</strong> This is the step most tutorials skip. After resolution, report:</p><ul><li>how many raw link rows you read</li><li>how many survive after dropping non-article namespaces</li><li>how many survive after dropping links whose source or target is missing from pages</li></ul><p>If you build from a slice (a subset of pages), edges that point outside the slice are lost, and a thin slice can lose most of them. The reference article that inspired this build reports that a recent 10M-page slice keeps only 28.1% of its citation edges. Your number will differ, but measure it. A graph that silently dropped most of its edges will answer “no path” for things that are in fact connected, and your refusal rate will look good for the wrong reason.</p><p><strong>Scale to expect.</strong> I benchmarked the storage format on synthetic data on a 2-core, 7 GB machine: writing 50 million random edges to zstd Parquet took 2.6 s and produced a 319 MB file, and loading it into DuckDB took 0.7 s. Real link data compresses differently, so treat these as a floor on feasibility, not a promise. The parse step, not storage, is the bottleneck: expect it to dominate your wall-clock time.</p><h3>Steps 3 and 4: The Path Engine and the Entry-Point Search</h3><p><strong>Step 3: CSR adjacency.</strong> Load links from Parquet into two integer arrays: indptr (where each node&#39;s neighbours start) and indices (the neighbours). Build one for forward links and one for reversed links, so you can search from both ends. This is the whole &quot;graph database&quot;.</p><pre>def build_csr(src, dst, n):<br>    order = np.argsort(src, kind=&quot;stable&quot;)<br>    indices = dst[order].astype(np.int32)<br>    indptr = np.zeros(n + 1, dtype=np.int64)<br>    indptr[1:] = np.cumsum(np.bincount(src, minlength=n))<br>    return indptr, indices</pre><pre>def nbrs(g, u):<br>    return g[1][g[0][u]:g[0][u + 1]]</pre><p>Then a bidirectional breadth-first search with a hop cap. It always expands the smaller frontier, which is what keeps it fast on graphs with hub nodes:</p><pre>def shortest_path(fwd, rev, a, b, max_hops=3):<br>    if a == b:<br>        return [a]<br>    pf, pb = {a: None}, {b: None}<br>    ff, fb = [a], [b]<br>    for _ in range(max_hops):<br>        side_f = len(ff) &lt;= len(fb)<br>        front, seen, other, g = (ff, pf, pb, fwd) if side_f else (fb, pb, pf, rev)<br>        nxt = []<br>        for u in front:<br>            for v in nbrs(g, u).tolist():<br>                if v in seen:<br>                    continue<br>                seen[v] = u<br>                nxt.append(v)<br>                if v in other:                      # frontiers met<br>                    left, x = [], v<br>                    while x is not None:<br>                        left.append(x); x = pf[x]<br>                    right, x = [], pb[v]<br>                    while x is not None:<br>                        right.append(x); x = pb[x]<br>                    return left[::-1] + right<br>        if side_f: ff = nxt<br>        else:      fb = nxt<br>        if not nxt:<br>            return None<br>    return None</pre><p>I ran this prototype. On a toy six-edge graph it returned the correct shortest path (1 -&gt; 5 -&gt; 4) and correctly returned None when no path existed within the cap. Building both arrays for 10 million random edges took about 4 seconds on a 2-core machine. I did not benchmark path latency on a real link graph, because random graphs are not shaped like Wikipedia; measure yours. Keep max_hops at 3 or 4: on a real link graph, longer paths run through hub pages and stop meaning anything.</p><p><strong>Hub pages are your main quality risk.</strong> A page like “United States” links to and from everything. A path that goes through it is technically valid and semantically empty. Mitigation: compute each node’s degree at build time, and either skip nodes above a degree threshold as intermediate hops or report them to the agent as “weak connector”. Log how often paths use them.</p><p><strong>Step 4: entry points with BM25.</strong> Build a full-text index over page titles plus the lead paragraph, using DuckDB’s full-text search extension or the SQLite FTS5 engine. The question “how is Turing connected to Enigma” goes in, two or three candidate page IDs come out. The agent then picks the right ones. The search is deliberately dumb: it does not answer, it only finds doors into the graph. Add embeddings later if title and lead search misses paraphrased questions. Do not start with them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Xvs4NFDT1bBOBtZNwBHIIw.png" /></figure><h3>Step 5: The Agent Loop and the Refuse-When-No-Path Rule</h3><p>The agent is a plain tool-use loop. The model decides which tool to call, your code runs it against the graph, and the result goes back. Five tools are enough:</p><ul><li>search(query) returns up to 5 candidate pages (id, title, first sentence).</li><li>neighbors(page_id, limit) returns linked pages, highest-signal first (low-degree before hubs).</li><li>path(a, b, max_hops) returns the shortest path as a list of pages, or null.</li><li>categories(page_id) returns the page&#39;s categories, for the fallback &quot;shared category&quot; route.</li><li>read(page_id, max_chars) returns the lead text, so the agent can check what a link actually says.</li></ul><p>The loop, using the standard Messages API tool-use pattern (this is a sketch; it needs your API key and was not run end to end for this article):</p><pre>import anthropic<br>client = anthropic.Anthropic()</pre><pre>SYSTEM = &quot;&quot;&quot;You answer only from the knowledge graph.<br>Rules:<br>1. Every claim must cite a page you read with the read tool.<br>2. A connection claim must cite a path returned by the path tool.<br>3. If path returns null within the hop cap, reply exactly: NOT SUPPORTED BY THE CORPUS.<br>4. Never use outside knowledge to fill a gap.&quot;&quot;&quot;</pre><pre>def run(question, tools, execute, max_turns=8):<br>    msgs = [{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: question}]<br>    for _ in range(max_turns):<br>        r = client.messages.create(model=MODEL, max_tokens=1024,<br>                                   system=SYSTEM, tools=tools, messages=msgs)<br>        msgs.append({&quot;role&quot;: &quot;assistant&quot;, &quot;content&quot;: r.content})<br>        if r.stop_reason != &quot;tool_use&quot;:<br>            return r, msgs<br>        results = [{&quot;type&quot;: &quot;tool_result&quot;, &quot;tool_use_id&quot;: b.id,<br>                    &quot;content&quot;: execute(b.name, b.input)}<br>                   for b in r.content if b.type == &quot;tool_use&quot;]<br>        msgs.append({&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: results})<br>    return None, msgs   # turn cap hit: treat as a refusal</pre><p>Three details make this trustworthy instead of just plausible:</p><ol><li><strong>The refusal is enforced in code, not only in the prompt.</strong> After the loop ends, a checker parses the final answer. If it asserts a connection and no path result in the transcript supports it, the answer is replaced with the refusal. The model is not the last line of defence.</li><li><strong>Citations are machine-checkable.</strong> Each citation is a page ID that must appear in a tool result in the transcript. Citing a page the agent never retrieved is flagged automatically.</li><li><strong>Untyped edges are checked by reading.</strong> Because a link only says “mentions”, the agent calls read on the pages along the path and confirms the sentence it wants to write is actually supported. This is the cost of skipping relation extraction, and it is cheap: a few short reads per question.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kXkwC1bLL68bu3xHaNz2cQ.png" /></figure><h3>Step 6: Evaluate It With Questions the Graph Writes Itself</h3><p>You cannot trust a graph agent you have not tested, and writing hundreds of test questions by hand does not scale. The graph can generate them.</p><p><strong>Answerable questions.</strong> Sample a random page A, walk 2 or 3 hops along non-hub edges to page B, and keep the pair. The gold answer is the path you sampled. Ask an LLM once, offline, to phrase it as a natural question (“How is A connected to B?”). Hold these out: never tune your prompts on them.</p><p><strong>Unanswerable questions.</strong> Take pairs with no path within your hop cap, or swap one endpoint for a real page from an unrelated area. The gold answer is the refusal. These are what prove the system is honest.</p><p><strong>Score four numbers, not one:</strong></p><ul><li><strong>Accuracy:</strong> on answerable questions, did the agent return a valid path between the right endpoints?</li><li><strong>Citation precision:</strong> of all pages cited, what fraction actually appeared in tool results and support the claim?</li><li><strong>Refusal rate on unanswerable questions:</strong> should be near 100%.</li><li><strong>False refusal rate on answerable questions:</strong> the price of being careful. Track it so you can see the trade-off.</li></ul><p>The reference article reports 83.2% on 600 held-out questions for its own PubMed build. That is a claim by its author about a different corpus and question set, so do not use it as your bar. Use it as a reminder that a held-out set of a few hundred questions is the right size to start, and that you should publish your own number with its method.</p><p><strong>Caveat on this method.</strong> Questions generated from the graph test whether the agent can navigate the graph. They do not test whether real users ask such questions. Add 30 to 50 hand-written questions from real use as a separate set.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iY7oLQxzY3MrbGDOl1upWA.png" /></figure><h3>How Others Can Use It: Bring Your Own Corpus</h3><p>The engine only needs four tables. Anything that can produce them works. Write one small adapter per source that outputs pages, links, page_cats (tags) and redirects (aliases, optional).</p><ul><li><strong>Scientific papers (PubMed-style).</strong> Papers are pages, citations are links, controlled-vocabulary tags (MeSH) are categories, and synonyms of those tags are redirects. This is the setup the reference article uses. NLM publishes the annual baseline as 1,334 gzipped XML files for 2026 (pubmed26n0001 to pubmed26n1334, released January 30, 2026) with MD5 checksums, so you can verify your download.</li><li><strong>Your company docs or wiki.</strong> Pages are docs, hyperlinks and “see also” blocks are links, folders and labels are categories. Keep the permissions: build one graph per access group, never one graph for everyone.</li><li><strong>A codebase.</strong> Files or symbols are pages, imports and call sites are links, directories are categories. The agent can then answer “what depends on this module?” with a cited path.</li><li><strong>Legal or policy text.</strong> Sections are pages, cross-references (“see section 4.2”) are links.</li></ul><p><strong>When your corpus has few or no edges.</strong> Add an extraction step, but only where you need it: run an LLM over the pages that lack links, ask it for a short list of linked entities, and write those into the same links table with a flag column source = &#39;llm&#39;. Now parsed and extracted edges live together, and your eval harness can report accuracy separately for each. That separation is how you learn whether extraction is worth its price for your data.</p><p><strong>Cost orientation, from primary sources.</strong> Microsoft states that full GraphRAG needs LLM calls to extract entities and relations and to summarize each community, and that its lazy variant indexes at 0.1% of that cost with no LLM at index time. The $33,000 figure for one corpus is the reference article’s own estimate; I could not verify it from a primary source, so treat it as an order-of-magnitude claim and price your own corpus from your provider’s current rate card before deciding.</p><p><strong>Legal notes.</strong> Check the licence of every corpus. Wikipedia text is CC BY-SA, which requires attribution and share-alike for derived text. Internal documents carry your own confidentiality rules: do not send them to any model you have not approved for that data.</p><h3>Scale Plan, Failure Modes, and Honest Limits</h3><p><strong>Scale plan.</strong></p><ol><li><strong>Laptop (up to tens of millions of edges).</strong> Everything above, as is. A smaller wiki or a 1M-page slice is the right first target.</li><li><strong>Single big machine (hundreds of millions to about a billion edges).</strong> Same design. The CSR arrays for 1B edges are about 4 GB for the neighbour array at 4 bytes per edge, per direction, so plan 8 to 10 GB of RAM for both directions plus pages. Build the Parquet files in parallel by shard.</li><li><strong>Beyond that.</strong> Partition by connected region, or move adjacency to a memory-mapped file. Only here does a graph database or distributed engine start to earn its place.</li></ol><p>The reference article claims 929,824,202 edges built in 10.8 minutes. I did not reproduce that, but the arithmetic above is consistent with a billion-edge graph fitting on one large machine.</p><p><strong>Failure modes to expect:</strong></p><ul><li><strong>Silent edge loss</strong> from slicing or unresolved redirects. Fix: the retention report from step 2, checked in every build.</li><li><strong>Hub paths</strong> that are valid but meaningless. Fix: degree-aware path search and a “weak connector” flag.</li><li><strong>Dump schema drift.</strong> MediaWiki moved link targets into a separate table; another change will come. Fix: parse the CREATE TABLE header and fail loudly when columns differ from what you expect.</li><li><strong>Stale data.</strong> Dumps are snapshots. Stamp every answer with the dump date.</li><li><strong>Agent over-confidence.</strong> Fix: the code-level refusal check, not just the prompt.</li><li><strong>Entry-point misses.</strong> If BM25 never surfaces the right page, the graph is never reached. Track search recall in your eval.</li></ul><p><strong>Honest limits.</strong></p><ul><li>Edges are untyped. The system proves a connection exists, not what the connection means.</li><li>It answers connection and navigation questions well. It is a poor fit for aggregation (“how many”), numeric reasoning and anything that needs facts not stated in the text.</li><li>Wikipedia links reflect editor habits, not truth. A missing link is not evidence that no relationship exists.</li><li>I validated the storage format, the CSR build and the path logic on synthetic or toy data. I did not run the full pipeline end to end on a real Wikipedia dump for this article, because the sandbox could not reach the dump host. Treat the code as a design with verified parts, then run your own build on a small wiki first.</li></ul><h3>Priority Order: What to Build First</h3><ol><li><strong>Parser plus retention report</strong> on a small wiki. If you cannot trust the edges, nothing else matters.</li><li><strong>Redirect resolution</strong> and namespace filtering.</li><li><strong>CSR graph and the path function</strong>, tested on pairs you know.</li><li><strong>BM25 entry search.</strong></li><li><strong>The agent with the code-level refusal check.</strong></li><li><strong>The eval harness</strong> with answerable and unanswerable questions.</li><li><strong>Only then:</strong> embeddings, hub handling refinements, and LLM extraction for edge-poor sources.</li></ol><h3>The Honest Summary</h3><p>If your corpus already contains its links, you can skip the most expensive part of GraphRAG and replace it with a parse that runs on a laptop. The agent’s value is not that it answers; it is that it shows a path and refuses when there is none. What is proven here: the storage format scales, the path logic is correct on a toy graph, and the design hangs together. What is not proven here: end-to-end accuracy on a real Wikipedia dump. Run the six steps on a small wiki, publish your four numbers, and you will know more than any benchmark claim in this article can tell you.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=074d944a68b3" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Claude Code Mods Explained: Install One in 2 Minutes, Check It First, Then Try Our Two]]></title>
            <link>https://medium.com/@saurabhraj042/claude-code-mods-explained-install-one-in-2-minutes-check-it-first-then-try-our-two-f6eaa62606ae?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/f6eaa62606ae</guid>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 05:10:57 GMT</pubDate>
            <atom:updated>2026-10-30T05:10:57.619Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x10zIubYrmUwBln9US2Zvw.png" /></figure><p>Claude Code now has mods. A mod is a small plugin that changes how Claude Code looks and behaves: a panel beside the chat, a status line, a slash command, a rule that runs before or after a tool call. Mods are on by default from Claude Code v2.1.287, and the feature launched on Oct 1, 2026.</p><p>Most posts about mods hand you a list. This one explains what a mod is, how to install any of them, and how to check one before you trust it. Then it walks through two examples we are building in the open: Compaction X-ray, which is finished and tested, and Organic Truth, which is still being designed.</p><p>The running example for the first mod: a two-hour session where you decided “we use the existing retry helper, we do not add a new library,” and then Claude Code compacted the session and forgot it.</p><h3>What You’ll Walk Away With</h3><ol><li>What a mod is, and where it runs</li><li>How to install any mod in two commands</li><li>How to check a mod before you trust it</li><li>Example 1, Compaction X-ray: see what compaction threw away and pin what must survive</li><li>Example 2, Organic Truth: the creator and business-owner mod, still in design</li><li>The honest limits, including the machines where mods get skipped</li></ol><p>Only read the parts you need. If you just want to install a mod, jump to section 2.</p><h3>What a mod is, and where it runs</h3><p>A mod is a plugin with three small pieces:</p><pre>my-mod/<br>  .claude-plugin/plugin.json   the name and version<br>  hooks/hooks.json             points at the code: {&quot;modules&quot;: [&quot;./register.js&quot;]}<br>  hooks/register.js            exports register(on, options)</pre><p>Inside register, you attach functions to engine events. Each function looks like ($, e, next): e is the event, next runs whatever would normally happen, and $ is the only way a mod can touch anything outside itself. Code before next can change what happens. Code after it can react.</p><p>The events cover most of a session: tool calls, prompts, turns, session start and compaction, slash commands, and the screen itself. A mod can draw a pane, a banner above the prompt, or a spinner line. The same mod runs in the terminal CLI, the Desktop Code tab and VS Code.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NhO4iTrfcDoVI-mrEtSWrg.png" /></figure><h3>How to install any mod</h3><p>Mods ship as plugins in a marketplace, which can be any GitHub repo that has a marketplace file. Two commands:</p><pre>/plugin marketplace add &lt;owner&gt;/&lt;repo&gt;<br>/plugin install &lt;mod-name&gt;@&lt;marketplace-name&gt;</pre><p>Mods are on by default from v2.1.287 (desktop v2.1.286). If a slash command from the mod does not show up, restart the session once.</p><h3>How to check a mod before you trust it</h3><p>Mods are not sandboxed. They run inside Claude Code, so a bad one can do real damage. Three checks take a minute:</p><ul><li>Run claude plugin validate on it. It lists every event the mod hooks and every $ call it makes.</li><li>Look for the risky namespaces: $.http (network), $.fs (files), $.process (commands), $.model (calls to a model). A mod that only needs a panel has no reason to use them.</li><li>Run claude plugin test. It runs the mod against stubbed data, so you can see it behave before it touches your session.</li></ul><p>Anyone who publishes a mod can make this easy for you. The two mods in this article are built to pass all three checks.</p><h3>Example 1: Compaction X-ray</h3><p>The next four sections are the first example. It is finished, tested, and does one job: after Claude Code compacts your session, it shows you what was summarized away and lets you pin facts that must survive.</p><h3>What compaction actually is</h3><p>Think of a two-hour meeting that ends with someone writing one page of minutes. The page is useful, but it is not the meeting. Whatever the note-taker thought was unimportant is gone, and nobody can check.</p><p>Compaction works the same way. When your context fills up, Claude Code takes the older messages, asks the model to write a summary, and swaps them for that summary. Some recent messages stay as they were. The engine hands a mod both lists: the messages before, and the messages after, where the summary shows up as one new message and the survivors keep their original handle. That difference is exactly what the X-ray reads.</p><p>It can start four ways: you run it by hand, it fires automatically near the limit, a plugin triggers it, or the engine precomputes one in the background. The mod ignores the background precompute and sub-agent compactions, and only reports on the real ones.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MhmH3u2PEKzQSypAx2CBSg.png" /></figure><h3>What tends to survive, and what tends to get lost</h3><p>The summarizer is a model writing a short note, so it keeps the big picture and drops detail. I have not measured this across many sessions, so treat the list below as a rule of thumb, not a result. The X-ray exists so you can check it on your own sessions instead of trusting me.</p><ul><li><strong>Usually safe:</strong> the overall goal, the files you are working on, the last few messages.</li><li><strong>At risk:</strong> a decision you made in one casual line (“let’s not add a new library”), the exact wording of an error, the contents of files Claude read earlier, small constraints you stated once.</li></ul><p>The second group is where the retry-helper decision from our running example lives. It was one line, two hours ago, between two long tool outputs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rXTydxinGv1_XXyFgseCJg.png" /></figure><h3>The X-ray: see what got summarized away</h3><p>Right after a compaction, a toast appears with the one-line verdict. The format looks like this (the numbers here are made up to show the shape, not from a real run):</p><p>compacted 142K → 31K tokens (−78%) · 64 messages summarized · pins 2/3 survived · /xray</p><p>Type /xray and you get the detail:</p><ul><li><strong>Before and after bar:</strong> how much of the window the compaction freed.</li><li><strong>Dropped tab:</strong> how many messages were yours, how many were Claude’s, how many were tool output, and the twelve biggest ones with a one-line preview each.</li><li><strong>Files out of context:</strong> up to fifteen files Claude had read that are no longer in the window, so you know which ones to ask it to re-read.</li><li><strong>Pins tab:</strong> each pinned fact with its status (next section).</li></ul><p>If your screen has no room for the pane, /xray prints the same report as plain text. The report is saved per project, so it is still there after you restart.</p><p>One word needs care. “Dropped” means summarized away, not deleted. The summary may still mention a dropped message in a sentence. The X-ray tells you which original messages are no longer in the window, not what the summary says about them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XcwWaVDdgngo_dXEVm-a8Q.png" /></figure><h3>Pins: tell the summarizer what must survive</h3><p>Seeing the loss is half of it. The other half is preventing it. In our example, you type:</p><p>/pin we use the existing retry helper, we do not add a new library</p><p>The mod stores the pin for this project and, on the next compaction, adds a rule to what the summarizer is told: keep these pinned facts in the summary, word for word. You can keep up to 20 pins of 300 characters each. /pins lists them and /unpin removes one.</p><p>After the compaction, the X-ray checks every pin against the new transcript and gives it one of three marks:</p><ul><li><strong>Kept:</strong> your exact words are in the summary or in a message that stayed.</li><li><strong>Paraphrased:</strong> at least 80% of the pin’s words appear, so the idea survived but the wording changed.</li><li><strong>Lost:</strong> it did not make it. Say it again, or pin it harder.</li></ul><p>That last mark is the real value. A pin is a request to the summarizer, not a guarantee, and now you find out in one glance whether the request was honoured.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4fadyZbEjjW0jFknjI-9ng.png" /></figure><h3>How it works inside: one hook</h3><p>A mod is a plugin that registers functions on engine events. The whole trick is one function on session.compact. It adds your pins to the summarizer&#39;s instructions, lets the compaction run, then diffs before and after:</p><pre>on(&#39;session.compact&#39;, async ($, e, next) =&gt; {<br>  if (e.trigger === &#39;precompute&#39; || e.agentId !== undefined) return next(e)<br>  const told = pins.length &gt; 0 ? { ...e, instructions: withPins(e.instructions, pins) } : e<br>  const result = await next(told)<br>  if (result.skip !== undefined) return result<br>  report = analyze(e.messages, result.messages, { trigger: e.trigger, pins })<br>  await $.store.set(reportKey, report)<br>  $.ui.invalidate(&#39;ui.render&#39;)<br>  await $.ui.toast(summaryLine(report))<br>  return result<br>})</pre><p>The next call is the engine doing its normal compaction. Everything before it changes what the summarizer is told. Everything after it only reads. The mod never rewrites the summary itself.</p><p>The diff logic lives in a separate file with no engine calls in it, which is why it can be tested with plain data.</p><h3>Install it, and check what it can touch first</h3><p>Mods are not sandboxed. They run inside Claude Code, so read what a mod can do before you add it. This one is built to make that easy.</p><pre>/plugin marketplace add &lt;your-github-user&gt;/raaz-mods<br>/plugin install compaction-xray@raaz-mods</pre><p>Then run claude plugin validate on it. The validator lists every event the mod hooks and every engine call it makes. For Compaction X-ray the calls are: $.command.register, $.session.cwd, $.store.get, $.store.set, $.ui.invalidate, $.ui.open, $.ui.resolve and $.ui.toast. There is no $.http, no $.fs, no $.process and no $.model. So it cannot reach the network, read your files, run commands or call a model of its own.</p><p>It also ships with 12 tests that run the hooks against stubbed engine data, and all 12 pass. I tested it on Claude Code 2.1.312.</p><h3>Honest limits</h3><p><strong>It does not run on managed machines.</strong> On a machine with managed settings, or for Team and Enterprise users, a security guard plugin (cc-plugin-sec-default) sits outermost and passes session.compact straight past user-installed mods. When I ran the mod on the real engine in a container that had this guard, Claude Code printed: &quot;its session.compact hook was skipped. &#39;cc-plugin-sec-default&#39; runs first and sent the event on past it.&quot; I did not try to get around it, and you should not either. The slash commands and the rest of the mod still worked; the compaction diff did not. On a personal account on your own machine it should run, but I have not yet recorded a real compaction through the hook on one. That check is still on my list.</p><p><strong>“Dropped” is not “deleted.”</strong> It means summarized away. The summary can still mention it.</p><p><strong>The pin check is text matching.</strong> It compares words. A pin the summarizer expressed in very different words can show as lost even though the idea survived, and a pin can show as kept even if the summary uses the words in a misleading way.</p><p><strong>Token counts can be estimates.</strong> When the engine does not report them, the mod estimates at about four characters per token and labels the report as an estimate.</p><h3>Example 2: Organic Truth (in design, not built yet)</h3><p>The second mod is for creators and small business owners, not developers. Instagram’s follower number hides a question that matters: how many of those follows came from your content, and how many came from paid reach? The idea for Organic Truth is to read an insights file you export yourself and show that split in a pane, so you can see what is really working.</p><p>What I can say honestly today: it is a design, not a release. It needs the column layout of your real Instagram insights export before the first line gets written, and I will not guess at it. It will not log in to Instagram or scrape anything. When it is built, tested and passes the same three checks as Compaction X-ray, this section gets install steps. Until then, do not look for it in the repo.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uaeK0x_ZuEwabDAgcE__Hw.png" /></figure><h3>What to do first, second, third</h3><ol><li><strong>First:</strong> pin the two or three facts you would be angry to lose, before your next long session. Decisions and constraints, not goals.</li><li><strong>Second:</strong> after your next compaction, open /xray and read the Pins tab and the files list. Re-read any file Claude needs again.</li><li><strong>Third:</strong> if a pin shows as lost, say it again in plain words in your next message. Do not assume it came back.</li></ol><h3>The honest summary</h3><p>Mods are small, inspectable plugins, and you can check what one touches before you install it. Compaction X-ray is built, tested and fixes a real blind spot in long sessions, but it will not run on managed machines. Organic Truth is a plan, and I will say so until it is built. If a mod passes the three checks, try it. If it does not, skip it.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f6eaa62606ae" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your AI Agents Run One at a Time. Here’s How to Build an Office That Runs Them All Safely]]></title>
            <link>https://medium.com/@saurabhraj042/your-ai-agents-run-one-at-a-time-heres-how-to-build-an-office-that-runs-them-all-safely-16ea703448bf?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/16ea703448bf</guid>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[github-copilot]]></category>
            <category><![CDATA[ai-agents-in-action]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Thu, 29 Oct 2026 10:18:17 GMT</pubDate>
            <atom:updated>2026-10-29T10:18:17.809Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-gLjUX72jbTWYF7OZLdD-A.png" /></figure><p>One AI coding agent is easy to run. You open a session, give it a task, and watch. Then you set up a second agent for another job, and a third, and you realise you are the scheduler. Which one is stuck? Which one is waiting on you? Which one just tried to push to a branch you did not mention?</p><p>The agents were never the problem. The missing piece is an office around them: a place where work goes in as tasks, the right agent picks it up, risky actions stop and wait for a person, and you can see everything at a glance.</p><p>This article is the recipe for that office. I built one for myself on a work laptop. It is a small local app with a task queue, team definitions in plain config files, headless agent runs through the GitHub Copilot CLI, an approval gate, and a browser control room. I removed every company, repo and person name, so you can copy the shape and make it yours.</p><p>One honest note before we start. The engine, the UI and 31 unit tests are built and pass. The first run against the real Copilot CLI is still ahead of me, and I mark clearly where that matters.</p><h3>What You’ll Walk Away With</h3><ol><li>The four layers of an agent office, and what each one does</li><li>How to define a team in one config file</li><li>A task queue with a state machine that cannot get confused</li><li>How a lead agent splits work without being able to do damage</li><li>How to run agents headless with the Copilot CLI and never use allow-all</li><li>An approval gate that stops risky actions and denies when anything fails</li><li>A control room in the browser: board, agents, live terminal</li><li>The security choices that make it safe on a laptop</li><li>How to make it yours: new teams, new roles, a different engine</li><li>What is built and what I have not proven yet</li></ol><p>One running example: a small team with a lead and three roles that turns “add a daily data-quality check” into three tracked tasks, and stops at the moment it wants to push code.</p><h3>The big picture: four layers</h3><p>The office is a small server on your laptop with a browser UI in front. Think of a real office. Config is the org chart, the engine is the manager with the task board, runners are the staff who do the work, and the UI is the glass wall you watch through.</p><ol><li><strong>Configuration.</strong> Teams, roles, allowed tools, approval rules and repos, all in YAML files.</li><li><strong>Engine.</strong> The queue, the task state machine, lead-to-subtask routing, approvals, cancel and follow-up.</li><li><strong>Runners.</strong> Each one turns a task into an agent process and converts its output into one common event shape.</li><li><strong>UI.</strong> A browser app that only knows that event shape, so you can swap the agent engine without touching the UI.</li></ol><p>The server uses Python with FastAPI and SQLite and listens on loopback only. The UI is React and TypeScript with no extra libraries beyond the basics. You can use any stack you like; the layering is what matters.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jgb0iQYrCx5dIvMDZEL7VA.png" /></figure><h3>Step 1: a team is a config file, not code</h3><p>The rule that makes the office easy to customise: adding a team never means writing code. One YAML file per team, loaded with a safe loader and validated on startup. Here is a generic example:</p><pre>id: quality<br>name: Quality<br>color: &quot;#9b6bff&quot;<br>runner: copilot<br>repo: service-a              # a key in repos.yaml<br>lead:<br>  id: quality-lead<br>  prompt: |<br>    You plan only. Split the task into subtasks.<br>    Reply with JSON only: {&quot;subtasks&quot;:[{&quot;role&quot;:&quot;...&quot;,&quot;title&quot;:&quot;...&quot;,&quot;details&quot;:&quot;...&quot;}]}<br>roles:<br>  - { id: check-author, prompt: &quot;...&quot;, tools_allow: [&quot;shell(git:*)&quot;, &quot;write&quot;],<br>      tools_deny: [&quot;shell(git push)&quot;, &quot;shell(rm:*)&quot;] }<br>  - { id: reviewer, prompt: &quot;...&quot;, read_only: true }<br>  - { id: researcher, agent: my-existing-agent, read_only: true }<br>mcp_servers: [my-knowledge-server]<br>approval_required_for: [&quot;shell(git push)&quot;, &quot;github(create_pull_request)&quot;, &quot;shell(make deploy:*)&quot;]<br>limits: { max_parallel_agents: 2, task_timeout_min: 30 }</pre><p>What each part buys you:</p><ul><li><strong>Lead.</strong> One agent per team that only plans. Its prompt forces a JSON answer.</li><li><strong>Roles.</strong> Each has its own allow and deny lists. A role marked read_only can never write or push.</li><li><strong>Reuse.</strong> A role can point at a custom agent file you already have, so you do not rewrite what works.</li><li><strong>Approval list.</strong> Actions that must stop for a human, covered in step 5.</li><li><strong>Limits.</strong> How many agents run at once and when a task times out.</li></ul><p>Validation is strict and boring on purpose: IDs must match a simple pattern, colours must be hex, the runner must be one of the known engines, and role IDs must be unique inside a team. A typo fails at startup, not at 2 a.m. in the middle of a run.</p><p>A second file, repos.yaml, maps short repo keys to paths, protected branches, test and lint commands, and a writable flag. In my build every repo is marked not writable. Agents only ever edit throwaway worktrees.</p><h3>Step 2: a task queue with a state machine</h3><p>Every piece of work is a task, and every task is always in exactly one state. The engine owns every change, and each change is checked against a whitelist of legal moves:</p><pre>backlog -&gt; in_progress          (run)<br>backlog -&gt; failed               (cancel)<br>in_progress -&gt; waiting_approval (a gated tool call)<br>waiting_approval -&gt; in_progress (allow, deny or timeout)<br>in_progress -&gt; done             (runner exit 0)<br>in_progress -&gt; failed           (error, timeout, cancel, bad plan)<br>waiting_approval -&gt; failed      (cancel)<br>failed -&gt; backlog               (requeue)</pre><p>Anything not on the list raises an error. done is terminal. If you want more work on a finished task, that is a new task linked to the old one. This sounds strict, and that is the point: with many agents running, a machine that cannot reach an impossible state is worth more than a flexible one.</p><p>The small rules around it:</p><ul><li>Each team has a semaphore, so only the allowed number of agents run at once.</li><li>A task has a timeout, and log lines are capped per task so one chatty agent cannot fill your disk.</li><li>Cancel on a running task denies its pending approvals first, then ends the process.</li><li>Every change emits an event that is saved and then pushed to the UI.</li></ul><p>The store is SQLite with three tables: tasks, events and approvals. All queries are parameterised, and an approval decision can only be written once.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dCDZLw3Sr5gujDijUh8FzA.png" /></figure><h3>Step 3: leads plan, roles execute</h3><p>In our example you create one task for the Quality team: “add a daily data-quality check”. It goes to the lead, not to a worker. The lead’s only job is to answer with a JSON plan:</p><pre>{&quot;subtasks&quot;:[<br>  {&quot;role&quot;:&quot;researcher&quot;,&quot;title&quot;:&quot;Find where checks live&quot;,&quot;details&quot;:&quot;...&quot;},<br>  {&quot;role&quot;:&quot;check-author&quot;,&quot;title&quot;:&quot;Write the check&quot;,&quot;details&quot;:&quot;...&quot;},<br>  {&quot;role&quot;:&quot;reviewer&quot;,&quot;title&quot;:&quot;Review the change&quot;,&quot;details&quot;:&quot;...&quot;}<br>]}</pre><p>The engine does not trust that answer. A small router parses the first JSON object it finds, rejects an empty plan, rejects more than 12 subtasks, and rejects any role that is not defined in that team. A bad plan fails the lead task only, and nothing else runs.</p><p>This is the safety idea worth stealing. A lead can only choose from roles you defined, so even if a ticket or a document tricks it, the worst it can do is assign work to a role that already has limited tools. Leads plan. They never execute.</p><p>With auto-dispatch on, the subtasks start as soon as they are created, and each role runs under its own allow and deny lists.</p><h3>Step 4: run agents headless with the Copilot CLI</h3><p>A runner is a small adapter. It takes a task, builds a command, starts the process, and turns every line of output into the office’s common event shape. This is the command the Copilot runner builds, using flags that GitHub’s programmatic reference documents:</p><pre>copilot -p &quot;&lt;role prompt + task + details&gt;&quot; --output-format=json --no-ask-user \<br>  [--agent=&lt;existing agent&gt;] \<br>  --allow-tool=&lt;each allowed tool&gt; --allow-tool=read \<br>  --deny-tool=&lt;each denied tool&gt; \<br>  [--deny-tool=write --deny-tool=&quot;shell(git push)&quot;]   # read-only roles \<br>  --add-dir=&lt;knowledge folder&gt;</pre><p>A few choices that matter:</p><ul><li><strong>Never allow-all.</strong> The docs say --allow-all (or --yolo) equals allow-all-tools, allow-all-paths and allow-all-urls. The runner asserts none of these flags ever appear in the command.</li><li><strong>Spawn without a shell.</strong> Build the command as an argument list, never as a string passed to a shell.</li><li><strong>Read both pipes at once.</strong> Output and errors go into one queue, so neither pipe can fill up and freeze the agent.</li><li><strong>Keep every raw line.</strong> With --output-format=json, the CLI prints one JSON object per line, but GitHub does not document the event schema for these runs. So the parser is defensive, unknown shapes stay as terminal-only lines, and the raw log is always saved.</li><li><strong>One shot only.</strong> --no-ask-user stops the agent from pausing to ask you anything, so you cannot type into a running agent. That is why instructions become linked follow-up tasks (step 6).</li></ul><p>Two details to check in the docs before you copy my setup. First, wildcards in tool patterns are only documented for shell subcommands (like shell(git:*)) and URLs, so keep your allow and deny rules in that style. Second, exit codes are documented for copilot workflow run, not for -p runs, so do not build logic that depends on a specific code until you have seen your own.</p><h3>Step 5: an approval gate for risky actions</h3><p>This is the part that lets you walk away. Copilot CLI supports a preToolUse hook: a script that runs before every tool call and can allow or deny it. The docs list its input as toolName, toolArgs and cwd. User-level hook files live in ~/.copilot/hooks/, repo-level ones in .github/hooks/.</p><p>The flow for a gated action, such as a push:</p><ol><li>The agent tries a tool call. The hook script receives it on stdin.</li><li>The script asks the office server: “is this one gated?” Ungated tools are allowed at once.</li><li>For a gated tool, the server creates an approval, moves the task to waiting_approval, and shows you a toast and a raised hand in the UI.</li><li>You click allow or deny. The server answers the hook, and the hook answers the agent.</li><li>No answer in 300 seconds counts as deny.</li></ol><p>The rules are matched by pattern, like shell(git push), shell(make deploy:*) or github(create_pull_request). A shell command that cannot be read is always gated. The hook script only accepts a loopback server URL and sends a per-process token, so another process cannot approve for you.</p><p>The design rule is fail closed. A bad URL, a missing task, a server that is down, a timeout, an exception: all of them print a deny.</p><p>What the docs told me to double-check, and you should too:</p><ul><li><strong>Hook timeout.</strong> timeoutSec defaults to 30 seconds. If the hook waits for a human for up to 5 minutes, set timeoutSec in the hook file above that wait, or the CLI may give up before you click.</li><li><strong>Crash behaviour.</strong> The docs say a command hook that crashes or exits non-zero denies the tool call. But if a hook exits cleanly with empty or invalid output, default behaviour applies. So always print a valid decision.</li><li><strong>Output format.</strong> The docs I read show {&quot;permissionDecision&quot;: &quot;allow&quot;} in examples. Capture one real payload and one real response from your own CLI version before you trust the gate.</li></ul><p>Also install the hooks at user level, not inside one repo. Then they cover every repo the agents touch.</p><h3>Step 6: the control room</h3><p>The UI is four views over one stream of events:</p><ul><li><strong>Office.</strong> An ambient map. Each team is a desk cluster, and agents type, hold up papers and raise a hand when they need approval.</li><li><strong>Board.</strong> All tasks in five columns, with filters by team, agent, text and time, and the right action on every card.</li><li><strong>Agents.</strong> One card per agent: state, current task, last activity, allowed and denied tools, MCP servers, and buttons to assign, open the terminal, or send an instruction.</li><li><strong>Terminal.</strong> The list of runs with live output, a copy button for the exact command so you can re-run it yourself, a Stop button, and a follow-up box.</li></ul><p>The terminal is read-only on purpose. A shell in the browser on a laptop is a remote-code-execution hole, so the office gives you the command to copy and a curl -N line to stream the raw events in your own terminal. A follow-up instruction creates a new linked task for the same role, and the UI says so plainly instead of pretending it typed into the old run.</p><p>The office map is drawn on a canvas with no sprite files and no animation library. One rule keeps it honest: an agent’s status only ever comes from real task state or real events. Idle wobble is cosmetic and switches off if the user prefers reduced motion. If the server is down, the UI falls back to a demo simulator that emits the same event shapes and labels every screen DEMO, so you can build and review the UI without running anything.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FMvWD7ZurF7Gzlr9c4to7A.png" /></figure><h3>Step 7: security choices that keep it safe on a laptop</h3><p>An office that runs agents with real tools is a security product whether you planned it or not. These are the choices I made, each aimed at one specific threat:</p><ul><li><strong>Loopback only.</strong> The server and the UI dev server listen on 127.0.0.1, so nothing outside the machine can reach the control API.</li><li><strong>Two tokens.</strong> UI writes need a session token in a custom header, which a page from another site cannot send. The hook endpoint needs a separate per-process token, compared in constant time.</li><li><strong>Fail closed.</strong> Every error path in the gate returns deny.</li><li><strong>Least privilege.</strong> Explicit allow and deny lists per role, read-only roles that cannot write or push, and a hard assertion against allow-all flags.</li><li><strong>Prompt-injection blast radius.</strong> Roles that read untrusted text, such as tickets and documents, get no push, write or run power without a gate, and leads can only pick roles you defined.</li><li><strong>No injection paths.</strong> Subprocesses take argument lists. Repos come from the registry, never from user input. Branch names and task IDs are validated. SQL is parameterised.</li><li><strong>No secrets in the office.</strong> The CLI authenticates with your own token from the environment. Nothing goes into the YAML files, and MCP discovery lists server names only.</li><li><strong>Read-only knowledge.</strong> Agents get the knowledge folder as a read-only directory. Drafts go to a separate output folder, and promoting a draft is a gated human step.</li><li><strong>Escaped output.</strong> Agent text is rendered through React or drawn on canvas, with no raw HTML injection.</li><li><strong>Throwaway worktrees.</strong> Each task gets its own git worktree and branch, and protected branches are refused.</li></ul><h3>Make it yours</h3><p>Everything above uses placeholder names. Here is how to fit it to your own work without touching the engine.</p><ul><li><strong>Add a team.</strong> Copy a team file, change the ID, colour, repo key and roles, and restart. Nothing else changes.</li><li><strong>Add a role.</strong> Write its prompt, decide its allow and deny lists, and mark it read_only unless it truly needs to write. If you already have a custom agent file, point the role at it with agent: instead of rewriting the prompt.</li><li><strong>Choose your gates.</strong> List every action you would be nervous to leave unattended: pushes, pull requests, deploys, writes to chat or wiki tools, anything that runs a job in a data platform. Start with too many gates and remove them as you build trust.</li><li><strong>Map your repos.</strong> Put each repo in repos.yaml with its protected branches and its real test and lint commands. Fill those in by reading the repo&#39;s own build files, not by guessing.</li><li><strong>Pick your knowledge folder.</strong> Give agents read-only access to your notes or docs, and send their drafts somewhere else.</li><li><strong>Add your own numbers.</strong> Each team can show a few KPIs, but the metric names are whitelisted in code, so a config typo cannot query anything unexpected.</li><li><strong>Swap the engine.</strong> A runner only has to start a task and yield events in the common shape. If you add a second engine, do not give it write access until it has something equivalent to the approval gate.</li></ul><p>A good first team is the smallest one that touches real work: a lead, one read-only researcher and one reviewer. Add a writer role only after the first runs look right.</p><h3>What to build first, second, third</h3><ol><li><strong>First:</strong> prove one read-only task end to end. Run a single research task through copilot -p, capture the real output, and fix the parser against it.</li><li><strong>Second:</strong> prove the gate. Trigger one gated action, capture the real hook input and response, set the hook timeout above your approval wait, and add a fixture test.</li><li><strong>Third:</strong> turn on worktrees for every team and fill in real test commands per repo.</li><li><strong>Fourth:</strong> pin and audit dependencies, then add cost tracking.</li><li><strong>Last:</strong> add more teams and roles. They are only config once the first four are solid.</li></ol><h3>The honest summary</h3><p>The value of an agent office is not more agents. It is knowing what each one is doing and having a hard stop before anything risky. The recipe is simple: teams as config, a strict task state machine, leads that only plan, runners that never get allow-all, a gate that fails closed, and a UI that shows only what really happened. Mine is built and tested in parts, and the first real run is still ahead. Use it as a recipe and verify the CLI-specific pieces on your own version before you trust them.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=16ea703448bf" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Claude Just Killed Instagram Guesswork. Here’s the Machine Inside the Skill Pack That Does It.]]></title>
            <link>https://medium.com/@saurabhraj042/claude-just-killed-instagram-guesswork-heres-the-machine-inside-the-skill-pack-that-does-it-92ea90a53b3d?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/92ea90a53b3d</guid>
            <category><![CDATA[claude]]></category>
            <category><![CDATA[claude-code]]></category>
            <category><![CDATA[instagram]]></category>
            <category><![CDATA[automation]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Tue, 27 Oct 2026 12:20:15 GMT</pubDate>
            <atom:updated>2026-10-27T12:20:15.537Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5CB4ef8OF6bP_8FAoNNxDQ.png" /></figure><p>Every reel you post is a bet placed blind, and the hook is the part of the bet you could have tested first.</p><p>The hook is about twelve words. It is the one piece of a reel you can measure before you record anything. Most of us still judge it by feel, post it, and read the verdict from the views.</p><p>There is a free, open-source pack of 13 Claude skills that stops doing that. It scores a hook on five checks, times your script to a tenth of a second, and strips the machine fingerprints out of your caption. The part that makes it interesting is how it does it: ordinary Python scripts sit beside the instructions, so the numbers are computed, not guessed by the model.</p><p>This article opens that machine up. What a skill pack is made of, how the hook scorer actually decides, what it cannot tell you, and how to install it without trusting a stranger’s code blindly.</p><h3>What You’ll Walk Away With</h3><ul><li>All 13 skills in the pack and what each one produces, then what a skill pack is physically made of, and why keeping judgment (the model) apart from arithmetic (scripts) is the whole trick.</li><li>How a five-check hook scorer reaches a number, including the exact formula, and the three things it cannot see.</li><li>How a beat timer enforces two rules most creators only feel: a hook under 3 seconds, and no idea held on screen past 4.</li><li>How to rank other people’s reels by outlier multiple instead of raw views, so you copy formulas and not follower counts.</li><li>How to install a third-party skill pack from a pinned commit, and the 5-minute check to run before you trust it.</li></ul><h3>What the Pack Can Do: 13 Skills in 5 Jobs</h3><p>The pack covers the whole loop of running an Instagram account: decide what to make, make it, post it yourself, talk to the people who respond, and learn from the results. Every skill drafts. None of them posts.</p><p><strong>1. Make the content</strong></p><ul><li><strong>/ig-reel:</strong> turns one idea into three hook options (from 26 formulas) with scores, a spoken script, a separate list of on-screen text, and a timed beat sheet. It will not invent your numbers.</li><li><strong>/ig-carousel:</strong> writes the slide-by-slide copy (a cover of six words or fewer, the stake, the body, a recap, one ask), writes the caption, then builds 1080 x 1350 slide files once you approve the copy.</li><li><strong>/ig-story:</strong> lays out a day&#39;s Stories frame by frame, picks the right sticker for each frame, and sets up a reply-based follow-up for the people who respond.</li><li><strong>/ig-caption:</strong> writes the caption so its first line survives the roughly 125-character &quot;... more&quot; cut, adds one ask, search terms and a few hashtags, then lints the result.</li></ul><p><strong>2. Find out what works</strong></p><ul><li><strong>/ig-viral:</strong> takes reels you collect by hand from about ten accounts and ranks them by outlier multiple, names the hook formula each used, and drafts your own versions. It flags hook shapes that match none of the 26 formulas.</li><li><strong>/ig-audit:</strong> takes your own pasted insights and ranks your posts by outlier multiple, sends per reach and hold at three seconds, then reports the pattern and how many posts it rests on.</li></ul><p><strong>3. Fix the profile and plan the week</strong></p><ul><li><strong>/ig-profile:</strong> scores your profile out of 100 on a 12-part rubric (the name field and bio first line carry 12 points each), rewrites the weakest parts first, and re-scores honestly so you see the real change.</li><li><strong>/ig-plan:</strong> produces a week: what to post, in which format, on which day and time, plus a daily list of accounts to engage with. It saves the plan so the other skills can read it.</li><li><strong>/ig-repurpose:</strong> takes a long video, podcast or newsletter, pulls out the claims, numbers, stories and mistakes, and spreads them across a week of reels and carousels.</li></ul><p><strong>4. Talk to people</strong></p><ul><li><strong>/ig-comment:</strong> drafts two comment options of different types, from nine comment types, and says which one it would post and why.</li><li><strong>/ig-reply:</strong> sorts the comments on your posts into keyword, lead, substance, question, support and noise, drafts replies for the ones worth answering, and spots a question comment that deserves a whole Reel.</li><li><strong>/ig-dm:</strong> covers the three kinds of DM it considers worth writing (a reply to someone who raised a hand, a warm approach, a collab pitch), with two follow-ups and the day each goes out.</li></ul><p><strong>5. Quality gate</strong></p><ul><li><strong>/ig-human:</strong> strips em dashes, invisible characters and stock phrases from any draft, then scores it on five checks. Every other skill runs its output through this one first.</li></ul><p><strong>What it will not do.</strong> It will not post for you, scrape Instagram, read your analytics by itself (you paste your insights in), or promise reach. The sample outputs in the skill files are illustrations, not results.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/825/1*NEHmI_91S47pkdDKgKy08w.png" /></figure><h3>One Hook, Scored: The Example We’ll Use All the Way Through</h3><p>Here is the hook this article follows from start to finish:</p><blockquote><em>Claude just killed Instagram. Watch it score my hook before I shoot.</em></blockquote><p>The scorer returns <strong>83.0, STRONG</strong>. Delete the second sentence and keep only “Claude just killed Instagram.” and the same tool returns <strong>57.2, OK</strong>. One extra sentence moved the score by 26 points. The rest of the article explains why.</p><p>The pack’s own code produces the number with one formula:</p><pre>\text{overall} = 0.6 <br>\times \text{mean of 5 checks} + 0.4 \times \text{weakest check} - 15 \times \text{dealbreakers}</pre><p>Check it against the example. The five checks scored 88, 100, 100, 100 and 70. Their mean is 91.6, so 0.6 × 91.6 = 54.96, plus 0.4 × 70 = 28, gives 82.96, which prints as 83.0.</p><p>Two details in that formula matter. The weakest check carries 40% of the total, so one bad property cannot hide behind four good ones. And a hook only earns the label STRONG if the total is at least 70, no single check is below 55, and no dealbreaker pattern fired.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/825/1*rU1xUdy2ddzkY7k-4mPanQ.png" /></figure><h3>What a Skill Pack Is Actually Made Of</h3><p>A skill is a folder. Inside it is one required file, SKILL.md, which opens with a name and a description and then holds instructions in plain Markdown. Anything else in the folder is optional: scripts, reference files, data. That is the whole format.</p><p>This pack has 13 skill folders, six Python scripts totalling about 1,470 lines, and a handful of JSON files that act as editable rulebooks:</p><ul><li>hooks.json: the 26 hook formulas, each with a template, an example and a way it gets ruined.</li><li>slop.json: 154 stock words and phrases the humanizer strips, plus invisible characters, typographic tells and structural tells.</li><li>rubric.json: the profile rubric, 12 items worth 100 points in total.</li><li>voice.md: your own file, which every skill reads first.</li></ul><p>The design choice that matters is the split. The SKILL.md tells the model <em>when</em> to act and <em>how</em> to behave. The scripts do the arithmetic. The JSON files hold the rules you will want to change without touching code. The model is never asked to &quot;estimate&quot; a score. Its instructions say to run the script instead.</p><p>That split also keeps the context window small. A skill pack loads in layers: the Agent Skills specification says an agent reads only each skill’s name and description (about 100 tokens) at startup, loads the full SKILL.md when a skill activates, and opens scripts and reference files only when the task needs them. Thirteen skills therefore cost thirteen short descriptions until you ask for one.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cCEUZvwWnIo9j12p56vtPg.png" /></figure><h3>Inside the Hook Scorer: Five Checks, No Magic</h3><p>The scorer is one 313-line script, hookscore.py. It reads your line as plain text and runs five checks. Each is a short function you can read in a minute.</p><ol><li><strong>Length.</strong> Five to twelve words scores 100. Under five loses 20 points per missing word. Over twelve loses 11 per extra word. More than 60 characters costs another 12, because the on-screen version has to fit in two lines. Speed is assumed at 165 words per minute.</li><li><strong>Specificity.</strong> It looks for a number, a proper noun or a spoken number. No hit scores 15. One hit scores 75. Two or more reach 100.</li><li><strong>Stakes.</strong> It looks for tension words, such as “killed”, “nobody” or “before”, and prices. No marker scores 20, one scores 70, two or more score 100.</li><li><strong>Frontload.</strong> It finds the first payload word. If that is within the first four words the check scores 100. Words five to seven score 70. Later than that scores 40. A weak opener (a throat-clearing start) takes 30 points off.</li><li><strong>Address.</strong> “You” or “your” scores 100. An imperative opener scores 90. First person with no viewer named scores 70. Third person scores 35.</li></ol><p>Now the example makes sense. “Claude just killed Instagram.” has no viewer in it, so Address returns 35 (“third person, nobody in the room”). That one weak check is worth 40% of the final formula, which is why the bare line lands at 57.2. Adding “Watch it score my hook before I shoot.” lifts Address from 35 to 70 and adds a second tension word (“before”), so Stakes rises from 70 to 100. The total climbs to 83.0.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gzarD_JfFBMdUnHPwUjpPw.png" /></figure><h3>What the scorer cannot see</h3><ul><li><strong>Delivery.</strong> It reads words. It cannot hear your pace, see your first frame or judge your face.</li><li><strong>Meaning.</strong> Tension words come from a list. “Killed” counts as stakes whether or not the sentence is true, so a dramatic lie can score well.</li><li><strong>Performance.</strong> Its author tested it on 74 YouTube Shorts hooks, not Instagram Reels. It separated weak hooks from good ones well (AUC 0.83) but did not reliably predict which good hook would do better (AUC 0.56). Read the score as a floor check, not a forecast.</li></ul><h3>The Beat Timer: Two Rules You Only Felt Before</h3><p>A second script, beats.py, takes your script as a text file, one line per beat, and times each beat from its word count. The default speaking rate is 165 words per minute, and you can pass your own with --wpm.</p><pre>python3 beats.py script.txt --target 36 --wpm 165</pre><p>It enforces two constants that are written at the top of the file:</p><ul><li><strong>The hook window is 3.0 seconds.</strong> If the first beat runs longer, it is flagged.</li><li><strong>No beat may hold one idea longer than 4.0 seconds</strong> without something changing on screen.</li></ul><p>It also flags a run of beats with nothing concrete in them (no number, name or price), checks the total against your target length, and checks for a loop: whether the last beat repeats a word from the hook, which makes the replay feel clean.</p><p>Our example shows it working. The first draft of the script, with the hook as one line, ran 52 seconds against a 38-second target, and the hook beat took 4.4 seconds. The timer flagged both. The fix was to split the hook into two beats, so the claim (“Claude just killed Instagram.”) lands in 1.4 seconds and the promise (“Watch it score my hook before I shoot.”) becomes beat two. After trimming, the same script ran 32.7 seconds, and the timer reported the loop: the closing line repeats “killed” from the opening.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kR4LK9_Sm97vAJckGn64RQ.png" /></figure><p>Note the quiet disagreement between the two tools. The hook scorer rates the 12-word version highly on length, while the timer says it takes 4.4 seconds to say. They answer different questions: one asks whether the line is short enough to read, the other whether it is short enough to say.</p><p>The limit is plain. Timings come from word counts, not from your recorded audio, so treat them as a plan and re-time once you have recorded.</p><h3>The Humanizer: Cleaning Machine Fingerprints Before Anything Ships</h3><p>Two more scripts handle text that has to sound like a person. humanize.py cleans a draft. detect.py scores it. Both read slop.json, the editable lexicon of stock phrases and fingerprints.</p><p>The cleaner removes what can be removed automatically: invisible characters, em dashes, curly quotes and similar typographic tells. It deliberately does not rewrite structural tells, which it only flags. One of them is the rule of three, a list of exactly three items, which it calls the model’s default rhythm.</p><p>The detector gives five scores:</p><ol><li><strong>Burstiness:</strong> how much sentence length varies. It wants a variation of 0.55 or more.</li><li><strong>Specificity:</strong> concrete markers per 100 words. It wants four or more.</li><li><strong>Slop density:</strong> stock words per 100 words from the lexicon.</li><li><strong>Fingerprint:</strong> invisible characters, em dashes, curly quotes, ellipses and hard spaces.</li><li><strong>Voice:</strong> contractions and personal pronouns, plus any structural tells.</li></ol><p>Our script shows the loop. The first draft opened a line with “You write, post, and hope.” The cleaner reported zero artefacts but flagged that line as a rule-of-three triad. Rewriting it to “You post and hope. Then it flops.” removed the flag and lifted the voice score from 81.8 to 89.1.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8qeo2Ty_nQEL00t3Fyf6dA.png" /></figure><p>The overall score stayed in review territory, 67.9, because the weakest check was burstiness (0.46 against the 0.55 target). That is the honest tension in this tool: a reel script is built from short, even, punchy lines, which is exactly what a burstiness check penalises. Use the number as a prompt to read your script aloud, not as a pass or fail.</p><p>One limit comes from the author’s own documentation. These are local heuristics, not validated against commercial AI detectors, so “human score” means “fewer known tells”, not “will pass a detector”.</p><h3>The Research Skill: Rank by Outlier, Not by Views</h3><p>The fourth mechanism is swipe.py, behind the /ig-viral skill. Its job is one correction: raw views are not evidence. A 2,000,000-follower account getting 400,000 views had a quiet day. A 4,000-follower account getting 400,000 views found something.</p><p>So the script ranks each reel by its <strong>outlier multiple</strong>: the reel’s views divided by that account’s own median views. If you give it only follower counts, it falls back to followers as the baseline and says so.</p><p>The skill’s own example row shows the arithmetic. An account with 48,000 followers and a median of 11,000 views has one reel at 412,000 views. That is 412,000 ÷ 11,000, about 37.5 times its normal. This row is an illustration from the pack’s documentation, not a real account.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lFYfw6zlLN5952iYG6oPQQ.png" /></figure><p>You feed it a tab-separated file with one reel per row (account, followers, median, views, hook). It names the hook formula each reel used, scores each hook with the same scorer from the earlier section, and prints what separates the top third of reels from the bottom third.</p><p>How the data gets collected is where the pack draws hard lines:</p><ul><li><strong>Reading, not scraping.</strong> About ten accounts and a dozen reels each, at human speed, in your own logged-in browser. The skill says automated collection violates Instagram’s terms and gets accounts action-blocked, so it forbids building a crawler or looping in the background.</li><li><strong>Never your password.</strong> The agent must not log in for you or ask for credentials.</li><li><strong>Copy the formula, never the video.</strong> The hook shape, the structure and the length, not their script, voice or edit. Every row is attributed to the account it came from.</li><li><strong>A second corpus.</strong> If Instagram shows too little, the same hook grammar runs on YouTube Shorts, where view counts and transcripts are public, collected with the separate yt-dlp tool.</li></ul><p>This is the part of the pack that tells you what to make next. Everything else helps you make it.</p><h3>voice.md: The Memory File Every Skill Reads First</h3><p>Every skill in the pack starts by reading one file you write: ~/.claude/instagram/voice.md. If it does not exist, the reel skill asks for three of your own reels and infers your voice from them.</p><p>The template has six parts: who you are and who you talk to, what you sound like (including words you would never say out loud), your positions, what is off limits, proof you can use, and your keyword call-to-action. The speaking pace you record there also feeds beats.py --wpm.</p><p>The section that earns its keep is <strong>Proof I can use</strong>. The skills are instructed never to invent a number, client or result under your name. If that section is empty, every draft comes back with a {{your number}} placeholder and a flag. That is a deliberate design choice: the safe failure is a visible blank, not a plausible lie.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mI_Mvz-njj4gpQEgmhAumQ.png" /></figure><p>One gotcha. The README tells you to fill in templates/voice.md, but the skills read ~/.claude/instagram/voice.md. Copy the template to that path first, or your edits will never be read.</p><h3>Install It Safely: Pin the Version, Read the Code First</h3><p>This is third-party code that runs on your machine, so treat it that way. The five-minute check below is what was done before this article was written.</p><ol><li><strong>Read the imports.</strong> The six scripts import only Python’s standard library: sys, re, json, argparse, statistics, os, unicodedata and textwrap.</li><li><strong>Search for risky calls.</strong> There is no subprocess, os.system, eval, exec, socket, urllib or requests anywhere in them. The only file writes go to a path you pass with --out.</li><li><strong>Read what the skills tell the agent to do.</strong> The research skill forbids asking for passwords or building a crawler. It uses your own browser session at human speed.</li><li><strong>Pin a commit.</strong> The version reviewed is d03c56b, dated 13 September 2026. Install that one, not whatever the repo becomes next month.</li></ol><p>Then install. Open Claude Code and paste:</p><pre>Install the Instagram agent skill from https://github.com/Jakeschincariol/instagram-agent-skill<br>pinned to commit d03c56b.<br>Clone it to a temp folder, check out d03c56b, then:<br>mkdir -p ~/.claude/skills ~/.claude/instagram<br>cp -r skills/ig-* ~/.claude/skills/<br>cp templates/voice.md ~/.claude/instagram/voice.md<br>Delete the temp clone, then run:<br>python3 ~/.claude/skills/ig-reel/hookscore.py --hook &quot;nobody tells you your first 30 reels are supposed to flop&quot;</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CNCpIQmtg4HuOvG8ElEe8w.png" /></figure><p>If the last command prints a score (that hook scores 87.0, STRONG), the scripts run. Fill in voice.md, restart Claude Code, and try /ig-reel on one real idea.</p><p>Two things to expect. Skills load when a session starts, so a skill added mid-session may not appear until the next one. And nothing in the pack posts for you: the README says “Nothing gets posted until you say yes”, and you still press publish.</p><h3>What to Do First, Second and Third</h3><p>Do these in order. Each one is worth more per minute than the next.</p><ol><li><strong>Install the pinned version and run the test hook.</strong> Ten minutes. It proves the scripts run on your machine.</li><li><strong>Fill in the Proof section of </strong><strong>voice.md with real numbers only.</strong> Twenty minutes. Every later draft depends on it, and an empty section produces visible blanks instead of invented results.</li><li><strong>Run </strong><strong>/ig-reel on one idea you already have.</strong> Let the scorer rank three hooks, split any beat the timer flags, then re-time once you have recorded your voice.</li><li><strong>Run </strong><strong>/ig-profile on your own profile.</strong> Fix the highest-priority gaps it lists before you post more. Your profile is what a new viewer sees after a good reel.</li><li><strong>Only then try </strong><strong>/ig-viral.</strong> It needs about ten accounts read by hand, and its results mean more once you have a baseline of your own.</li></ol><h3>The Honest Summary</h3><p>Claude did not kill Instagram. What this pack kills is one specific kind of guesswork: judging a hook by feel, estimating a script’s length by eye, and shipping a caption that reads like a machine wrote it.</p><p>It works because the arithmetic lives in short Python scripts you can read, not in the model’s mood. It is trustworthy because its author states the limits: the scorer was tested on YouTube Shorts, it catches weak hooks better than it picks winners, and the humanizer is not validated against commercial detectors.</p><p>It will not tell you what to say, it cannot see your delivery, and a high score is no promise of views. It is one maintainer’s project with a short commit history, so pin a version and read the code before you trust it.</p><p>Use it as a floor under your hooks, not a crystal ball over them.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fII24HfSYqBcbYNISbkgOw.png" /></figure><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=92ea90a53b3d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your AI Agent Writes Code Before It Understands the Task. Here’s the Gate That Fixes It.]]></title>
            <link>https://medium.com/@saurabhraj042/your-ai-agent-writes-code-before-it-understands-the-task-heres-the-gate-that-fixes-it-de89f1856aba?source=rss-7af6964f5516------2</link>
            <guid isPermaLink="false">https://medium.com/p/de89f1856aba</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[github-copilot]]></category>
            <dc:creator><![CDATA[Saurabh]]></dc:creator>
            <pubDate>Sun, 25 Oct 2026 13:34:44 GMT</pubDate>
            <atom:updated>2026-10-25T13:34:44.381Z</atom:updated>
            <content:encoded><![CDATA[<p>I gave my coding agent a ticket and went to get coffee.</p><p>When I came back, it had changed eleven files. The code looked clean. The tests passed. And it had solved a slightly different problem from the one I asked for.</p><p>The wrong assumption was made in the first thirty seconds. I found it two hours later, inside a diff.</p><p>That is the real cost of agents that start coding immediately. They are fast, so a small misunderstanding turns into a large, convincing pull request before anyone has agreed on what the task is.</p><p>The fix I use is not a better prompt. It is a gate. Before my agent is allowed to change a single file, it has to write down what it understood and what it plans to do, then stop and wait for me. This article is how that setup works, how to build it, and where it breaks.</p><h3>What You’ll Walk Away With</h3><ol><li><strong>Why agents code too early,</strong> and why reviewing a diff is the most expensive place to catch a misunderstanding.</li><li><strong>The gate:</strong> one rule that stops the agent from touching a file until you approve its plan.</li><li><strong>The 7 documents</strong> the agent writes first, and the one thing to check in each.</li><li><strong>How to build it in GitHub Copilot,</strong> including a stronger version where the agent physically cannot edit files during planning.</li><li><strong>A 5-minute review checklist</strong> so approving the docs does not become a rubber stamp.</li><li><strong>What to reuse across tasks</strong> and what to regenerate every time.</li><li><strong>When it fails,</strong> and which tasks should skip it entirely.</li><li><strong>A priority order</strong> if you only have an hour.</li></ol><h3>One Task We’ll Use Throughout</h3><p>This ticket is made up, so there is no production code anywhere in this article. It is a common shape for backend work, and the same pattern fits a data pipeline.</p><p><strong>ORD-1423: Add retries and a dead-letter queue to the order-events consumer.</strong></p><p>Today the consumer reads a message, calls the order handler, and if anything throws, it logs the error and drops the message. The ticket asks for three things: failed messages retry up to three times with backoff, messages that still fail go to a dead-letter queue, and duplicate deliveries must never create duplicate orders.</p><p>That last sentence hides the trap. Retries create duplicates. An agent that jumps straight to code will happily add a retry loop and quietly break the third requirement. Watch what the gate does with it.</p><h3>Why Agents Code Too Early</h3><p>An agent has one strong habit: it turns a request into action as fast as it can. That is great for a typo fix. It is risky for anything with a hidden requirement.</p><p>Here is what happens on ORD-1423 without a gate:</p><ol><li>The agent reads the ticket and a few files.</li><li>It guesses how retries should work, because nothing forced it to say.</li><li>It writes a retry loop inside the consumer, changes the handler, and adds tests that pass against its own guess.</li><li>You open a diff of eleven files and try to reverse-engineer what it was thinking.</li></ol><p>The expensive part is step 4. A diff shows you what the agent did, not what it assumed. You can approve code that is perfectly clean and still wrong, because the mistake lives in a decision nobody wrote down: retry inside the consumer or re-enqueue with a delay? Who guarantees idempotency?</p><p><strong>The principle: review the plan, not the diff.</strong> A plan is short and reads like English. A wrong assumption in a plan costs you a sentence to fix. The same assumption in a finished diff costs you the whole change.</p><p>I am not claiming this has a measured payoff. It is the same logic behind design reviews before code reviews, applied to an agent that never gets tired of writing code and never asks whether it should.</p><h3>The Gate</h3><p>The whole system is one rule:</p><blockquote><strong><em>Do not create or change any file until the documents are written and the human has approved them.</em></strong></blockquote><p>The workflow behind it has two halves, and the line between them is the gate. Paste this into Gemini for the diagram:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QUDK9WGzskvsr3KlSFBJXw.png" /></figure><p>Two details make it work:</p><ul><li><strong>The agent writes its understanding down first.</strong> Not a chat message that scrolls away, but files you can read, edit and keep.</li><li><strong>A rejection loops back to the start of the docs,</strong> not to the code. If the analysis is wrong, everything built on it is wrong.</li></ul><p>On ORD-1423, the gate is where you catch the retry-versus-duplicates trap. The analysis lists “duplicate deliveries” as a risk, the design has to answer it, and you see the answer before a line of code exists.</p><h3>The 7 Documents, and What to Check in Each</h3><p>Each document answers one question an engineer would ask before starting. Together they replace the “read the ticket and start typing” step.</p><ol><li><strong>Task Analysis</strong> answers <em>what are we really changing, and what exists today?</em> It restates the ticket, lists acceptance criteria, describes current behaviour, names the files involved, and writes down assumptions, risks and what is out of scope. <strong>Check:</strong> is every assumption one you agree with?</li><li><strong>Design</strong> answers <em>how will we change it?</em> It holds the high-level design with a flow diagram, the low-level design (functions, schemas, interfaces), and the alternatives considered. <strong>Check:</strong> does it explain why the rejected option was rejected?</li><li><strong>Architecture</strong> answers <em>what rules must this change respect?</em> Layers, dependency rules, data contracts, delivery guarantees, failure handling, observability, security. <strong>Check:</strong> does the design break any rule here?</li><li><strong>Code Style</strong> answers <em>how does this repo write code?</em> Naming, error handling, logging, config and imports, learned from the existing code. <strong>Check:</strong> are the examples taken from your repo, not generic advice?</li><li><strong>Testing</strong> answers <em>how will we prove it works?</em> Test levels, a map from each acceptance criterion to a test, edge cases, how to run them. <strong>Check:</strong> does every acceptance criterion have a test?</li><li><strong>Implementation Plan</strong> answers <em>what order, and how do we undo it?</em> Small steps with the file each one touches, rollout, rollback, definition of done. <strong>Check:</strong> is each step small enough to review alone?</li><li><strong>AGENTS.md</strong> is the one document the agent reads, not writes. It holds the rules of the game, including the gate itself.</li></ol><p>Medium has no tables, so paste this into Gemini for a cheat sheet image:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gVsV2RaZcFgVbIFNvpxNnA.png" /></figure><p>If you only have time to review two documents carefully, make it the first two. A wrong analysis or a wrong design poisons everything after it.</p><h3>How to Build It in GitHub Copilot</h3><p>There are three ways to build the gate, from weakest to strongest. File names below come from the <a href="https://code.visualstudio.com/docs/agent-customization/overview">VS Code agent customization docs</a> and a community guide dated February 2026; Copilot’s customization features change often, so check the current docs before copying anything.</p><p><strong>Level 1: an instruction file (a request).</strong> Put the rule in AGENTS.md at the repo root, or in .github/copilot-instructions.md. VS Code reads both for Copilot, and root AGENTS.md support is on by default. Here is a generic version, my sketch, not a tested production file:</p><pre># Agent instructions</pre><pre>## Before you change any file<br>1. Read the ticket and explore the relevant code.<br>2. Write these documents in docs/&lt;ticket-id&gt;/:<br>   TASK_ANALYSIS.md, DESIGN.md, ARCHITECTURE.md,<br>   CODE_STYLE.md, TESTING.md, IMPLEMENTATION_PLAN.md<br>3. Then STOP. Do not create or edit any other file.<br>   Tell me the documents are ready and wait for my approval.</pre><pre>## After approval<br>Follow IMPLEMENTATION_PLAN.md step by step. Run the tests.<br>Update the docs if the code diverges from them.</pre><pre>## Rules<br>- If the ticket is unclear, ask. Do not guess.<br>- If the docs and the code disagree, say so before continuing.</pre><p><strong>The catch with Level 1.</strong> The VS Code docs say discovery confirms a file is loaded, not that the agent follows it. Instructions are guidance. An agent under pressure can skip a request.</p><p><strong>Level 2: a skill (a reusable workflow).</strong> Move the “how to write each document” detail into a skill, a folder with a SKILL.md, so the templates are loaded only when needed. The community guide places workspace skills under .github/skills/&lt;name&gt;/, and says Copilot reads a skill&#39;s name and description first and loads the rest on demand. This keeps AGENTS.md short and makes the workflow portable across projects.</p><p><strong>Level 3: a read-only planning agent (a lock).</strong> This is the version I trust most. Custom agents live in .github/agents/*.agent.md, and the community guide says they can restrict tools and use handoffs, a button that moves you to another agent with context filled in. Build two agents:</p><ul><li><strong>Planner:</strong> its tools are limited to reading and searching, plus writing documents under docs/. It <em>cannot</em> edit source files, so the gate is physical, not polite.</li><li><strong>Implementer:</strong> full editing tools. You reach it only through the handoff button, after you have read the docs.</li></ul><p>I could not confirm the full frontmatter syntax or the exact tool names from the pages I opened, so I am not printing a sample file here. Look up the fields (tools, handoffs) in the current VS Code docs before you write yours.</p><p><strong>Two checks that save you time:</strong></p><ul><li>Test in a fresh chat and look at the response’s References, which VS Code says shows which instructions and skills were included.</li><li>Instructions from several files are additive, and VS Code says there is no general precedence order. If two files contradict each other, fix the source.</li></ul><p><strong>Using another tool?</strong> The documents themselves are plain markdown, so any agent can read them. I did not verify how each tool discovers AGENTS.md, so check yours.</p><h3>A 5-Minute Review Checklist</h3><p>The gate only works if you actually read. Here is the order I would review in, and what to look for. On ORD-1423 it takes five minutes.</p><ol><li><strong>Task Analysis, 90 seconds.</strong> Read only the assumptions, risks and out-of-scope lists. Ask: what did it assume that I never said? On our ticket, the risk list should mention duplicate processing. If it does not, the agent missed the trap.</li><li><strong>Design, 90 seconds.</strong> Find the decision. Which option was chosen and why? The design should answer the duplicate question explicitly, for example with an idempotency check.</li><li><strong>Architecture, 45 seconds.</strong> Does the design respect the layering? If the design has the handler calling the database directly and the rules say it must not, send it back.</li><li><strong>Testing, 45 seconds.</strong> Look at the criteria-to-tests map. Every acceptance criterion needs a test. A missing row is a missing guarantee.</li><li><strong>Plan, 30 seconds.</strong> Are the steps small? Is there a rollback? A step that says “implement the feature” is a red flag.</li></ol><p>Three outcomes:</p><ul><li><strong>Approve</strong> and let it code.</li><li><strong>Edit a document yourself</strong> and tell the agent to follow your version. These are files, so you can just change them.</li><li><strong>Reject with one sentence,</strong> such as “retry by re-enqueueing, not in-process”, and have it rewrite from the analysis down.</li></ul><p>The habit that makes this honest: if you cannot explain the design in two sentences after reading it, do not approve it.</p><h3>What to Reuse and What to Regenerate</h3><p>Not every document should be rewritten from scratch for every ticket. They fall into two groups:</p><ul><li><strong>About the repo (reusable):</strong> Architecture, Code Style and Testing conventions. These describe how the codebase works, and they change slowly. Let the agent generate them once, you review them carefully once, and then each task only checks that the new work follows them.</li><li><strong>About the task (regenerate every time):</strong> Task Analysis, Design and the Implementation Plan. These are specific to the ticket.</li></ul><p>This matters for two reasons. It cuts the review load, since you read the task documents fresh and only skim the repo documents for changes. And it gives you a place to put lessons: when a review catches something, fix the repo document, so the next agent run starts with it.</p><p>The risk is staleness. A repo document that no longer matches the code is worse than none, because the agent trusts it. That is why the rules in AGENTS.md include &quot;update the docs if the code diverges&quot;, and why you should spot-check them periodically.</p><h3>When It Fails, and When to Skip It</h3><p>A workflow you cannot criticise is one you do not understand. Here is where this one breaks.</p><ul><li><strong>The agent ignores the gate.</strong> With Level 1 (an instruction), it can. The VS Code docs themselves say a loaded file is not the same as a followed file. That is the reason to prefer the read-only planning agent, and to test by giving a deliberately tempting ticket.</li><li><strong>You rubber-stamp.</strong> Seven documents can turn into seven things you scroll past. If your approval takes ten seconds, the gate is decoration. Use the checklist above.</li><li><strong>The documents are long and confident but wrong.</strong> An agent can write a polished design for a misread codebase. The gate gives you a chance to catch that, but only if you read critically. Polished is not the same as correct.</li><li><strong>Stale documents.</strong> Repo-level documents drift from the code. Spot-check them.</li><li><strong>Overhead on small tasks.</strong> Renaming a variable or fixing a typo does not need seven documents. A reasonable rule: skip the full gate for changes that touch one file and have no design choice. Use a short plan for medium tasks. Use all seven for anything that crosses modules, changes data, or has a requirement like “never create duplicates”.</li></ul><p>I have not measured how much time this saves, and I am not going to invent a number. What I can say is where the cost moves: from reviewing and reworking a large diff to reading a few pages before any code exists.</p><h3>Priority Order: What to Set Up in One Hour</h3><ol><li><strong>Write the Level 1 rule</strong> in AGENTS.md or .github/copilot-instructions.md: documents first, then STOP. Ten minutes.</li><li><strong>Pick one real ticket</strong> and run it. Read the Task Analysis and Design carefully. This is where you learn whether it works for your codebase.</li><li><strong>Add the repo-level documents</strong> (Architecture, Code Style, Testing) once, and review them properly.</li><li><strong>Move the document templates into a skill,</strong> so the workflow is reusable across projects.</li><li><strong>Build the read-only planner and the implementer agents</strong> with a handoff, once you trust the documents.</li><li><strong>Decide your skip rule</strong> for small tasks, and write it down.</li></ol><p>If you do only one thing: step 2. A gate you have never tested is just a sentence in a file.</p><h3>Honest Summary</h3><p><strong>Backed by documents I opened:</strong> the file names and locations for Copilot instructions, AGENTS.md, prompt files, custom agents and skills; that instruction files are additive with no general precedence order; and that a loaded instruction is not proof the agent followed it (VS Code docs). That custom agents can restrict tools and use handoffs comes from a community guide dated February 2026, which is a secondary source.</p><p><strong>My opinion, from daily use:</strong> reviewing a plan before code is cheaper than reviewing a diff, and a structural lock (a read-only planner) is more reliable than a polite instruction. This is engineering judgment, not a measured result.</p><p><strong>What this article is not:</strong> a benchmark. I have no study showing planning-first agents produce better code, and the ORD-1423 ticket is invented to illustrate the workflow, not a real incident.</p><p>If you take one idea away: the most valuable thing an agent can write is not code. It is what it thinks you asked for.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=de89f1856aba" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>