<?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 Vitek Tajzich on Medium]]></title>
        <description><![CDATA[Stories by Vitek Tajzich on Medium]]></description>
        <link>https://medium.com/@v.tajzich?source=rss-4726de7c7d9e------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*IVxhev5M3b9xbuty.jpg</url>
            <title>Stories by Vitek Tajzich on Medium</title>
            <link>https://medium.com/@v.tajzich?source=rss-4726de7c7d9e------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 06:58:10 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@v.tajzich/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[You Can Have a Self-Correcting AI Pipeline. You’re Just Afraid to Start.]]></title>
            <link>https://medium.com/@v.tajzich/you-can-have-a-self-correcting-ai-pipeline-youre-just-afraid-to-start-4a90475362e9?source=rss-4726de7c7d9e------2</link>
            <guid isPermaLink="false">https://medium.com/p/4a90475362e9</guid>
            <category><![CDATA[ai-agents-in-action]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[claude-code]]></category>
            <dc:creator><![CDATA[Vitek Tajzich]]></dc:creator>
            <pubDate>Sat, 22 Aug 2026 13:42:44 GMT</pubDate>
            <atom:updated>2026-08-22T13:42:44.841Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bzbmafmOZKOwxzH2zKOzXA.png" /></figure><p>Almost every developer I talk to uses Claude at work, and most of them use it agentically — Claude Code, real tasks, real code getting shipped. What almost none of them have is a setup that corrects itself without them sitting there.</p><p>They’re not using it wrong. Nobody is approving every step — it runs in auto mode, and it does real work. But they stay in the session, watch it, and check the result themselves at the end. The human is the verification step. And the distance from there to a pipeline that verifies itself is much shorter than it looks — most of it is reading and arguing, not writing code.</p><p>But when I ask why they haven’t closed that distance, I get the same three answers. None of them are about difficulty.</p><p><strong>“I don’t know where to begin.”</strong> The most common one. Not because they’re new to agents — they’re not — but because supervised work and autonomous work look like the same thing from the inside. There’s no obvious move that converts one into the other, so the move never gets made.</p><p><strong>“I’m afraid it will go sideways.”</strong> Fair, and the fear is earned. But the conclusion most people draw from it — <em>therefore stay in every session forever</em> — is the wrong one. It goes sideways for two reasons: the agent doesn’t know your project, and it can’t verify its own work end to end. Running the tests is not verification — not when the change touches UI, or a contract, or anything a green build doesn’t see. Both are fixable, and fixing them is most of the work.</p><p><strong>“It will take too much time.”</strong> True and false at once. Yes, it takes time. Not weeks. And it’s the same time you’d spend onboarding a new colleague — except you do it once and it stays done.</p><p>All three have the same answer.</p><p>The rest of this is what I actually do. I’ll describe it with Claude because that’s what I use, but nothing here is Claude-specific. Any agent that can read a file, run a command, and be given a role works the same way.</p><h3>Step 1: Make the project explain itself</h3><p>It doesn’t matter what kind of project it is. Web app, native app, backend service — the principle is identical.</p><p>Start by asking Claude to walk the project and generate a CLAUDE.md in the root. Then <strong>read it</strong>. Carefully.</p><p>This is the most important part of the whole thing, and it’s the part everyone skips. You are not generating a config file. You are checking whether the agent’s mental model of your project matches yours. If it doesn’t, everything after this point is guesswork.</p><p>So don’t just accept what comes out. Question it. Argue with it. Anywhere the description doesn’t match what you know to be true, say so — including the small things. Especially the small things.</p><p>Don’t compromise here. Not once. Every ambiguity you let slide is a decision the agent will make for you later, at the worst possible moment.</p><p>Once CLAUDE.md is in place, ask Claude to run a full build. Not just compile — tests, coverage report, vulnerability scan, linters, everything your CI does.</p><p>Then let it iterate. It will hit walls. Watch the session. The moment you see it doing something silly, interrupt. Ask why it did that, and tell it how it should be done instead.</p><p>Yes, this step requires you to sit in the session. You’re doing that anyway. The difference is that here it has an end — you’re spending the attention to buy it back later.</p><p>You’ll find non-standard things in your project. Every project has them. Your first attempt should always be to convert them into the standard solution. That’s the real fix, and it pays off for every developer on the project, not just the agent. Only when that isn’t possible — and sometimes it isn’t — document them explicitly: in CLAUDE.md, or as a dedicated skill or tool. What you cannot do is leave them undocumented and hope.</p><p>When you think the agent understands the project and the rules, skills, and CLAUDE.md are in place: <strong>open a fresh session and try again from scratch.</strong> A fresh session has no memory of your corrections, only what&#39;s written down. That&#39;s the real test. Iterate until it&#39;s flawless.</p><h3>Step 2: Give it the tools to check its own work</h3><p>Now think about how development actually happens on this project. Split it into the smallest logical chunks you can.</p><p>After step 1, the agent knows how to compile, test, and check coverage. That’s not enough. It needs to be able to <strong>verify its own work</strong> — otherwise you are the verification step, and you’ve built nothing autonomous.</p><p>The question to ask yourself is simple:</p><blockquote><em>What would </em>I<em> do to verify this feature or bug fix? What tools do I open? How do I use them?</em></blockquote><p>The agent needs the same tools. Not similar ones. The same ones.</p><p>If you have a UI app, use AI to generate tooling that screenshots the running app and compares it against the design. If you have a backend, give it tools to verify the contract. Whatever you open to convince yourself the work is correct, the agent needs it too.</p><p>This is usually where people underinvest, and it’s exactly the investment that kills fear number two. An agent that can check its own work doesn’t go sideways for long. It notices, and it corrects. There is nothing more sophisticated behind the phrase “self-correcting pipeline” than that.</p><h3>Step 3: Define your sub-agents</h3><p>A sub-agent is just a specification of work that happens regularly — usually nothing more than a markdown file describing a process and its constraints.</p><p>Why bother? Because if you don’t define them, the main agent has to invent the work specification from scratch every single time. That burns tokens and, worse, makes the outcome unpredictable. Two runs of the same task produce two different processes.</p><p>A few are usually enough to start:</p><ul><li><strong>Implementor</strong> — implements a feature. Knows how to run tests, follows TDD, updates the API docs, whatever your project requires.</li><li><strong>Reviewer</strong> — understands how to check someone else’s work and produce a report on what’s wrong and <em>why</em>.</li><li><strong>UI reviewer</strong> — checks the built UI against the specification and the design.</li></ul><p>Start with these. Add more when you notice yourself explaining the same process twice.</p><h3>Step 4: Write the skill</h3><p>Now create a skill: <em>“implement a feature.”</em> And another: <em>“fix a bug.”</em> It could be one skill, but the workflows usually differ enough to justify two.</p><p><strong>Don’t write them by hand.</strong> Tell Claude you want to create a skill and describe the steps you take. Something like:</p><ul><li>read the Jira description</li><li>look up the documentation (tell it where — markdown files in docs/? a Confluence page? an MCP server?)</li><li>get the design, if there is UI</li><li>write a technical spec based on the ticket</li><li>review that spec with the reviewer agent, and iterate until no issues are found</li><li>write an implementation plan</li><li>implement it using TDD</li><li>open a PR</li><li>run the PR review agent</li><li>notify when the work is done</li></ul><p>If you’re not sure you’ve covered everything, just ask Claude to interview you. It will ask the questions you forgot to answer.</p><p>That’s the whole thing. You have a skill describing how a feature gets implemented. You’ve given the agent the tools to build, test, and verify. You’ve defined sub-agents for the repeating work, which makes it cheaper and more predictable.</p><p>Four steps. None of them require anything you don’t already know about your own project.</p><h3>Step 5: Run it, then fix what you learn</h3><p>Run it on something simple. Watch the session live, or at minimum review it afterwards.</p><p>Then ask the agent directly: what was unclear? Where did it go sideways? What workarounds did it have to take?</p><p>That feedback is the actual product of the first run — not the code. Use it to update the skills, the rules, the agent definitions. Add tools that were missing. Fix tools that didn’t work.</p><p>The strongest move at this point is to <strong>throw the branch away and run the same task again</strong> with the updated setup. Same input, better harness, and you get a clean read on whether your fix worked. If that’s too expensive, just check it on the next task instead.</p><p>It takes a few sessions to polish. Not weeks.</p><p>Two things compound from here. Let the agent open GitHub or Jira issues against <strong>its own harness</strong> — so when a tool is broken or a rule contradicts itself, it tells you instead of silently working around it. And let it store learnings and workarounds in a markdown file inside the project, so the next session starts from what the last one figured out.</p><h3>It’s never done, and that’s fine</h3><p>This isn’t a setup you complete. It’s a living thing. It needs maintenance, and it gets better every time you feed it back.</p><p>But once it’s running, the shape of the work changes. The project becomes genuinely autonomous: the agent can develop and maintain it, and you move from writing the code to designing the system that writes it.</p><p>And it doesn’t stop at one repo. Once the skills, agents, and scripts have proven themselves, you can lift them into a plugin and hand the whole thing to your team — or your whole company.</p><p>So: not hard, not risky, not slow. You’re already in the session — the whole thing is just writing down what you would have said out loud. Start by making the project explain itself, and everything else follows from that.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4a90475362e9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[A Self-Correcting Pipeline for Building Apps]]></title>
            <link>https://medium.com/@v.tajzich/a-self-correcting-pipeline-for-building-apps-3f15fbd43bd8?source=rss-4726de7c7d9e------2</link>
            <guid isPermaLink="false">https://medium.com/p/3f15fbd43bd8</guid>
            <category><![CDATA[mobile-app-development]]></category>
            <category><![CDATA[ai-agents-in-action]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[software-testing]]></category>
            <category><![CDATA[design-systems]]></category>
            <dc:creator><![CDATA[Vitek Tajzich]]></dc:creator>
            <pubDate>Sat, 22 Aug 2026 12:14:21 GMT</pubDate>
            <atom:updated>2026-08-22T12:14:21.325Z</atom:updated>
            <content:encoded><![CDATA[<p>I’m going to show you a real build pipeline — the one that ships our app. What we build and why it is built that way, and then how a pipeline like this is put together.</p><p>We run a delivery pipeline that takes a business spec and a design, and produces two native apps — iOS in Swift, Android in Kotlin — that match both. It is self-correcting: when a screen does not match its design, the build goes red. And it is self-learning: every divergence a human catches once becomes a check the pipeline runs forever.</p><p>This article covers how it is wired: the two phases, the agents that run in each, how the visual gate turns “does this look right” into red or green, how a single human catch is converted into a permanent rule, and how we decide when a class of review is trustworthy enough to run without a person signing it off.</p><h3>What we build</h3><p>An archery scoring app, shipped as two native apps.</p><p>Business logic lives once, in a shared Kotlin core: scoring, statistics, validation, the state machines behind each screen. Anything that <em>decides a value</em> goes there. Each native app is a thin wrapper around it and owns only what genuinely cannot be shared — the UI layer (SwiftUI on one side, Jetpack Compose on the other), navigation, platform APIs, haptics.</p><p>The same principle applies to appearance. Every color is a named token in the shared core, and both apps read it. A raw hex value written in Swift or Kotlin is a rule violation, not a preference — because a color hardcoded on one platform silently stops the other from ever changing.</p><p>That matters for what follows: if the two apps share their logic and their palette, then “do they match the design” becomes a question about each platform’s view layer alone — which is exactly the question the visual gate answers.</p><h3>The pipeline</h3><p>Two phases: one human, one automated.</p><p><strong>Phase A — the source of truth.</strong> The designer/product owner in one person writes the spec and builds the design, and iterates until the two agree. The spec is business only: what problem, for whom, what success looks like, and explicitly what this is <em>not</em>. No data model, no screen structure, no framework names. The design covers every screen <em>and every state</em> of it — empty, populated, mid-flow, error — each with a stable ID that everything downstream refers to.</p><p>The iteration inside Phase A is the point. A spec that describes a flow the design doesn’t draw, or a design with a state the spec never mentions, is a defect caught here for the price of a conversation. Downstream it costs an implementation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1KiixhmE-VwR90S0BdmJcQ.jpeg" /><figcaption>ONE FEATURE, ONE PAGE OF THE DESIGN — NINE STATES, EACH WITH ITS OWN ID.</figcaption></figure><p><strong>Phase B — the pipeline.</strong> Once spec and design agree, agents take over: plan, implement, verify the logic, capture both apps, compare each screen against its design. It loops until both apps look like the design and the logic does what the spec says.</p><p>Inside Phase B nothing is exotic. It is ordinary engineering discipline — a task-by-task plan with acceptance criteria, test-driven development, code review, static analysis, coverage floors. The unusual part is not how the code gets written. It is that appearance has its own gate, and that the gate gets smarter every time it misses something.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*47nokbE7Cy_HDZhs8hPnkQ.png" /></figure><h3>The agents</h3><p>One agent per job, each with a narrow task and a fresh context. Reviewers never edit code; implementers never review their own work. That separation is not bureaucracy — an agent that just wrote something is the worst possible judge of whether it matches the design.</p><h4>PLAN</h4><ul><li><strong>Planner</strong> — Turns spec + design into a task-by-task plan: files, interfaces, the test to write first, and the command that verifies each step</li></ul><h4>BUILD</h4><ul><li><strong>Implementer</strong> — Builds one task, or fixes one returned divergence. Verifies with the covering tests before reporting</li></ul><h4>VERIFY</h4><ul><li><strong>Code reviewer</strong> — Checks the change against the architecture rules — layering, dependency injection, what belongs in the shared core</li><li><strong>Test debugger</strong> — Diagnoses a failing test, traces the root cause through the layers, proposes the minimal fix</li></ul><h4>CAPTURE</h4><ul><li><strong>Design inventory</strong> — Produces the canonical list of design screens and components, and diffs it against the last run. The diff is the work order</li><li><strong>Coverage auditor</strong> — Cross-references every design screen against the ones we actually capture, and reports the gaps</li><li><strong>Design capturer</strong> — Renders the design prototypes headlessly and crops each to one screen variant</li><li><strong>Capture-test author</strong> — Writes the UI test that drives the app into that exact state, so the screenshot is comparable</li><li><strong>Capture runner</strong> — Runs the whole capture end to end on both platforms and reports what changed</li></ul><h4>REVIEW</h4><ul><li><strong>Pair reviewer</strong> — Compares one design ↔ app pair, element by element, in fresh context. Emits a structured verdict</li><li><strong>Source auditor</strong> — Reads the view source for divergences a screenshot cannot show</li><li><strong>Consistency reviewer</strong> — Looks at all screens as a set — twin screens that drifted apart, one control rendered two different ways</li></ul><h4>LEARN</h4><ul><li><strong>Principle critic</strong> — Scores a candidate review principle in clean context, deciding whether it is worth arming</li></ul><p>The capture agents look like overhead until you consider what they replace: a person opening the app, navigating to a screen, putting it in the right state, and taking a screenshot — for every screen, every time anything changes.</p><h3>Why appearance needs its own gate</h3><p>Tests prove behaviour. They say nothing about whether the screen looks like the design.</p><p>This is where agent-written UI fails in a specific way: it is <em>plausible</em>. The spacing is reasonable, the components exist, the screen works. It is simply not the design — a row that should be highlighted isn’t, a control the design places bare on a card is wrapped in an extra box, a badge is outlined where the design fills it. Every one of those passes every test.</p><p>A divergence is not a crash. It is a screen that feels slightly different from the rest of the app — and that feel <em>is</em> the product. We ship an experience, so the design is a requirement, not a reference.</p><p>Users do not file bugs about wrong design. They just get a worse app, and we never hear about it. That leaves no incoming signal to react to, and re-checking 83 screens by eye on every change is not a substitute for one.</p><blockquote>So the whole design of the gate follows from one rule: every judgment a human would make becomes an artifact a script can turn red.</blockquote><h3>How the visual gate works</h3><p><strong>Capture both sides.</strong> The design prototypes are rendered and cropped per screen variant — the empty state and the populated state are separate captures, not one page you eyeball twice. On the app side, a UI test drives the real app into that exact state and screenshots it, on both platforms. Long screens are captured as a series of frames, because reviewing only the top of a screen is precisely how divergences survive.</p><p>Two capture rules, both learned by getting them wrong:</p><ul><li><strong>Seed the richest data and match the state.</strong> If the design shows a populated, expanded, mid-flow screen, capturing an empty list and calling it a match proves nothing.</li><li><strong>Put the active item where the design puts it.</strong> If the design highlights the third row, the seed must make the third row active — otherwise the comparison is invalid before the reviewer even looks.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Q6tTd9ptIhh-D1PC-KmrfQ.png" /><figcaption>FOC CALCULATOR — ONE ARTBOARD, BOTH APPS, WHAT A REVIEWER IS HANDED.</figcaption></figure><blockquote>Judging this triple is the reviewer’s actual job. Some differences are expected and must not be reported: the design is drawn in one locale and the apps run in another, and Android’s top bar follows its own platform convention. Others are exactly what the element-by-element diff exists to record — the empty result pill reads — % on one platform and % on the other. A human rules on which is which; every ruling that generalizes becomes a permanent check.</blockquote><p><strong>Review one pair at a time.</strong> The reviewer opens one design image and every app frame for that screen, and walks it element by element. One pair per invocation, always in fresh context, never batched. That is not a stylistic preference — batching turns a review into a glance, and moving to per-pair review took a backtest of known divergences from 4 out of 5 to 5 out of 5.</p><p>The reviewer also reads the expected value from the <em>design source</em>, not from the design screenshot. Screenshots are unreliable for shade and weight; the source that produced them is not.</p><p>Each review produces a structured record: a hash of the frames it looked at, the list of frames it reviewed, and an element-by-element diff where every entry carries what was expected, what was observed, a verdict and a severity.</p><p><strong>Five invariants decide the commit.</strong></p><ul><li><strong>Freshness</strong> — a screen re-rendered but not re-reviewed. The record is bound to the exact frames it judged</li><li><strong>Completeness</strong> — reviewing the top of a long screen and calling it done</li><li><strong>Open defect</strong> — any divergence judged real and significant</li><li><strong>Memory replay</strong> — skipping a check the pipeline has already been taught</li><li><strong>No contradiction</strong> — a verdict of “matches” while the diff below it says otherwise</li></ul><p>Only real, visible divergences block. Small and cosmetic ones are recorded and ignored by the gate. Once findings gate a commit, the failure mode flips from missing defects to alert fatigue — and a reviewer that marks everything critical is as useless as one that marks nothing.</p><p>Then the loop: fix, re-capture, re-review. Re-capturing changes the frames, which invalidates the old verdict, which forces a fresh review. You cannot fix a screen and quietly keep the green check that was issued for the broken version.</p><p><strong>Two passes a screenshot can’t do.</strong> A source auditor reads the view code for divergences invisible in an image — layout expressed as a fraction of the screen, which looks right on the capture device and breaks on another; two definitions of a component that should exist once; a bar that floats where the design pins it. A consistency reviewer looks at all screens together, catching twin screens that drifted apart — something no single-pair review can see by construction.</p><h3>How it learns</h3><p>Everything above catches known kinds of mistakes. The interesting question is what happens the first time something slips through.</p><p><strong>A human catch becomes a permanent check.</strong> When a person spots a divergence the pipeline passed, it is recorded against the screens it applies to. From then on, every review of those screens must record an explicit verdict for it — not “the reviewer will probably remember”, but a gate that fails if the verdict line is missing. That is the deterministic floor: <strong>the same kind of mistake is never missed twice.</strong> Eight such checks are active today.</p><p><strong>A check can be generalized into a principle.</strong> A screen-scoped guard is narrow. “An item in an active state must render the design’s active treatment, never the idle one” applies to every screen in the app.</p><p>Promotion is not automatic, because a model grading its own generalization is worthless. The candidate goes to a critic run three times in clean context — it sees the candidate, the existing principles and the standard, never the conversation that produced it. Each run scores it independently, and the median decides. Clear the bar and the principle is armed immediately: the reviewer applies it on the next run. Seven are armed today, each carrying its scores, what it was distilled from, and a flag that it has not yet been audited by a person. Humans audit asynchronously; nothing waits for them; retiring a principle disarms it.</p><p>The failure mode here is deliberately asymmetric. Principles are a <em>soft</em> rubric — they bias the reviewer toward more scrutiny, they never authorize passing something. A bad principle produces noise, which is annoying and measurable. It cannot produce a missed defect.</p><h3>How we know it works</h3><p>A self-learning loop that grades its own homework is a story, not a system. So the loop is measured against fixed ground truth.</p><p><strong>A golden set.</strong> Ten committed cases, each a design and an app screenshot captured at a <em>known defective</em> state, together with the divergences the agent is required to find. A deterministic scorer grades the agent’s output against them. The cases came from real misses — the ones humans caught while the pipeline said green.</p><p><strong>A canary, against Goodhart.</strong> One of those cases is planted in live runs. If the reviewer fails to flag its known defect, the run is void. That is the difference between proving a review happened and hoping an output was plausible.</p><p><strong>A bar for autonomy, and it is revocable.</strong> A class of review is allowed to run without a human signature only when four things hold at once: recall against the golden set clears its threshold overall and per class; precision clears its threshold, so we are not drowning in false alarms; the canary is caught every run; and there have been zero human-caught misses across three consecutive real passes. That last one is the real gate — it is the exact test that failed twice while a human was still the oracle.</p><p><strong>A ceiling we state out loud.</strong> The memory plus the gate guarantee the same class of defect is never missed twice. A genuinely novel one, on first sighting, still depends on the reviewer being diligent. “Autonomous” here means autonomous <em>on regression</em>, not omniscient on first contact. New screens and new patterns stay human-signed until they have a golden case and clear the bar.</p><h3>What it buys, and what it costs</h3><h4>What it buys</h4><ul><li><strong>Ambiguity is paid for up front</strong>, in a business spec and a design that must agree before anyone writes code — where it costs a conversation instead of an implementation.</li><li><strong>Correctness and appearance are separate gates.</strong> Green tests on a wrong-looking screen no longer count as done.</li><li><strong>Human review got cheap, not optional.</strong> The design and both apps arrive side by side, already driven into the same state — nobody installs a build and clicks their way to the screen in question. Checking a result takes seconds, and that is precisely what makes the feedback happen at all. A principle exists because looking was easy enough to bother.</li><li><strong>Nothing regresses quietly.</strong> Every catch becomes a check that runs forever, at the cost of writing it down once.</li></ul><h4>What it costs</h4><ul><li>The spec and the design have to actually agree before implementation starts. That is real work, and it is front-loaded.</li><li>A capture harness must exist and be maintained on both platforms — driving an app into a specific state repeatedly is not free.</li><li>Review passes consume real time and real tokens. Per-pair, fresh-context review is the expensive option; it is also the one that works.</li><li>The learned memory needs auditing. Rules that accumulate without review eventually become rules nobody understands.</li></ul><p>It pays off at the point where a person can no longer personally inspect everything that gets produced. With agents doing the writing, that point arrives much earlier than it used to.</p><h3>Is it perfect?</h3><p>No. Some divergences the reviewer does not see at all, and some it sees and does not judge to be a problem. That failure mode never disappears — it only gets rarer.</p><p>Which is exactly what the screenshots are for. A person scans them quickly — quickly, because the design and both apps are already captured in the same state, side by side — hands the wrong one back to the agent, and says what is wrong with it. What comes out of that is a candidate rule, and the person confirms it.</p><p>The iteration is on the feedback, not on the screen. You go back and forth with the agent until the rule names the actual problem rather than the single instance of it. Once it lands, the screen is fixed under the new rule — and the rule rides along on every review after it.</p><p>That loop is why the Android app came together in an implausibly short time. It is still not perfect. It gets less imperfect every time someone spends thirty seconds looking at a screenshot.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3f15fbd43bd8" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[My Notes Are Always Current. Not Because I’m Organized.]]></title>
            <link>https://medium.com/@v.tajzich/my-notes-are-always-current-not-because-im-organized-3f2be972cff6?source=rss-4726de7c7d9e------2</link>
            <guid isPermaLink="false">https://medium.com/p/3f2be972cff6</guid>
            <category><![CDATA[notes]]></category>
            <category><![CDATA[sw-engineering]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[markdown]]></category>
            <category><![CDATA[management]]></category>
            <dc:creator><![CDATA[Vitek Tajzich]]></dc:creator>
            <pubDate>Mon, 23 Mar 2026 11:29:58 GMT</pubDate>
            <atom:updated>2026-03-23T11:29:58.017Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*eaxRTmItOuUlgqYpkXc_JQ.png" /></figure><p>My notes are always current. Not because I’m organized - because an AI agent rebuilds the picture on command.</p><p>I started where most people start - Apple Notes, Notion, Bear, then Obsidian. Each one organized things its own way. Each one broke when my requirements changed. So I stopped using apps to manage my notes and started using an AI agent that reads and writes plain text files. When something isn’t working, I edit a rule. The next time the agent runs, the system works differently. No migrations. No plugins. No waiting.</p><p>Every productivity app promises to organize your work. None of them let you rewrite the rules.</p><p>This article walks through how the system evolved - not as a grand design, but as an organic response to real frustrations. You’ll see the structure, the automation, and the single insight that makes it all work.</p><h3>The Problem</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*pz7WTesqprTOyElnXw3LEw.png" /></figure><p>Information goes stale the moment you write it down.</p><p>You sit down Monday morning. Somewhere in your notes are action items from last week’s meetings. Some are done. Some were superseded. Some you forgot existed. You’d have to open five different notes and mentally reconstruct the state of the world. So you don’t. You wing it.</p><p>You join a cross-team sync. Someone raises a topic. It sounds familiar. Was there a decision last time? Who was supposed to follow up? The notes exist somewhere, but finding the thread across three weeks of meetings would take longer than just discussing it again. So the same conversation happens for the third time.</p><p>You’re about to meet with a direct report. What did you agree to last time? What topics have been simmering across multiple conversations? You scroll through past notes but they’re just raw transcripts. No thread. No summary. No sense of what’s still open.</p><p>These aren’t organization problems. They’re <strong>freshness</strong> problems. The information exists - it’s just never synthesized, never rolled up, never kept current. And the tools you use can’t help because they only store what you type. They don’t process it. They don’t summarize it. They don’t track what changed since last time.</p><p>You could build templates, tag systems, database views. Obsidian and Notion both offer that. But the moment your needs change - a new meeting cadence, a different team structure, a realization that your action item format needs a source link - you’re rebuilding templates and migrating data. Your requirements evolve weekly. Your tools update quarterly, if ever.</p><p>Every tool comes with opinions. Notion thinks in databases. Obsidian thinks in links and plugins. Apple Notes thinks in folders. When you adopt a tool, you adopt the author’s mental model. You learn their vocabulary, their workflows, their limits. You become a prisoner of someone else’s idea of how notes should work. And when that model doesn’t fit your reality -you can file a feature request and wait.</p><p>If you don’t need a mobile app - and for a work knowledge system, I don’t - there’s another path. Tools like Cursor work directly with plain markdown files. No proprietary format. No database schema. No plugin API to learn. Just text files in a folder, versioned with git, readable by any editor, and - critically - readable and writable by AI.</p><p>I needed a system where the information stayed fresh and the rules could change as fast as my thinking.</p><h3>The Moment It Clicked</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wn3EJ5v2nvArNlWZ0rPlAw.png" /></figure><p>I was already using Cursor as my AI agent environment. Not for writing code - I use JetBrains for that. Cursor is where I work <em>with</em> an AI agent: give it context, give it instructions, let it do the work. I’d been using it for code-adjacent tasks - generating configs, refactoring scripts, analyzing repos.</p><p>One day I opened my notes folder in Cursor instead of Obsidian. Not with a grand plan - I just wanted to quickly edit a meeting note. But Cursor didn’t see “notes.” It saw what it always sees: a directory of text files. And it did what it always does: offered to help.</p><p>I asked it to summarize last week’s meetings. It read the files, found the meeting notes by date, and produced a coherent summary. Then I asked for open action items across all recent notes. It found them. Things I’d forgotten. Things buried in notes I hadn’t reopened since writing them.</p><p>This wasn’t a notes app with AI bolted on. This was an AI agent with direct access to my files - the same way it has direct access to source code. No API. No plugin. No intermediary. It could read everything, cross-reference anything, and write new files following whatever conventions I described.</p><p>That’s when I made a deliberate choice: markdown files in a git repo. Not because markdown is trendy, but because it’s the format AI agents work with best. Plain text. No binary blobs. No proprietary encoding. Version-controlled so nothing is ever lost. And cheap - every AI model reads text natively. No parsing, no conversion, no context window wasted on format overhead.</p><p>I didn’t design a note-taking system. I gave an AI agent a folder and taught it how I think.</p><h3>The Folder</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ReiczsTRH79KpygOOIyaeA.png" /></figure><p>The first thing you need isn’t AI - it’s a structure the AI can navigate. But the structure has to be flexible enough to grow organically.</p><p>An AI agent reading your files is only as useful as the organization of those files. If everything lives in one flat folder, the agent wastes context window figuring out what’s what. If the structure is too rigid, you spend more time filing notes than writing them. The sweet spot: <strong>conventions, not constraints.</strong></p><p>I settled on a simple hierarchy. At the top: areas of work. Under each area: products, reference docs, and meetings. Meetings can live anywhere - under a product, under a team, at the root. The only rule: meeting notes go inside a meetings/ folder, wherever that folder lives.</p><pre>vault/<br>├── team-a/<br>│   ├── team.md<br>│   ├── product-x/<br>│   │   ├── product.md<br>│   │   └── meetings/<br>│   ├── product-y/<br>│   │   ├── product.md<br>│   │   └── meetings/<br>│   └── meetings/<br>│       ├── 1-on-1-alice/<br>│       ├── 1-on-1-bob/<br>│       └── weekly-sync/<br>├── initiatives/<br>├── people/<br>└── wraps/</pre><p>The agent doesn’t need a database. It uses **/meetings/**/*.md to find all meeting notes. It uses */product.md to find all product areas. It reads team.md to understand the team structure. The folder tree <em>is</em> the schema - human-readable and machine-navigable.</p><p>Meeting notes are named YYYY-MM-DD.md for recurring meetings, YYYY-MM-DD - Topic.md for one-offs. That&#39;s it. No tags required to find them. No frontmatter. The date is in the filename, the context is in the folder path. The agent can glob for files by date range and know which meeting series they belong to from the directory name alone.</p><p>This structure isn’t clever. It’s deliberately boring. Boring is good - it means any AI model can understand it without elaborate instructions. The more predictable your file layout, the less you have to explain to the agent, and the less context window you burn on orientation.</p><p><em>I want to be clear: this is my structure. It doesn’t have to be yours. That’s the whole point. You don’t need to adopt my mental model - you need to discover your own.</em></p><p>And here’s the thing: describing your own structure is hard. It was hard for me. I knew how I wanted things organized - I could feel when a file was in the wrong place - but I couldn’t write down the rules. So I asked the AI to help. I told it to look at my existing notes and describe the patterns it saw. Then I asked it to suggest improvements. It reflected my thinking back to me, cleaner than I could have articulated it myself.</p><p>The result is still how <em>I</em> think - the AI didn’t impose a foreign structure. It helped me see my own structure clearly enough to write it down. And once it’s written down, the AI can follow it, and I can change it anytime.</p><p>Start with whatever layout makes sense to you. The AI doesn’t care. Describe your conventions in a rule, and the agent follows them. And when your conventions stop making sense - change the rule. No migration scripts. No restructuring by hand. The AI does the heavy lifting. The cost of being wrong is a text edit, not a weekend of moving files.</p><h3>The Rollup Machine</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-Me2slW2l8OLbIEzZO-Zmg.png" /></figure><p>I had meeting notes. Dozens of them. Each one captured what happened on that day. But nobody reads old meeting notes. They sit there, decaying into irrelevance, while the same topics get re-discussed and the same action items get re-assigned because nobody remembers they already exist.</p><p>The system has two rollup mechanisms that solve this.</p><h3>Summary.md: The Living Thread</h3><p>Every recurring meeting series gets a Summary.md file. Not a transcript. Not a log. A living document that the AI maintains by reading all the individual meeting notes in that folder and synthesizing them into one current picture.</p><p>A 1-on-1 Summary.md contains: the relationship context, hot topics that are currently active, open action items with source links back to the meeting where they were created, a topic history showing when things were first raised and how they evolved, and a ledger of which meetings have been summarized.</p><p>A weekly team sync Summary.md does the same for the group: recurring themes, decisions made, who owns what, what keeps coming back unresolved.</p><pre># 1-on-1: Alice - Summary</pre><pre>## Hot Topics<br>- Cloud migration ownership -first raised 2026-01-15, still open<br>- On-call rotation concerns - resolved 2026-02-20</pre><pre>## Open Action Items<br>- [ ] Draft migration timeline @Alice ðŸ“… 2026-03-25<br>      ([2026-03-10](meetings/1-on-1-alice/2026-03-10.md))</pre><pre>## Summarized Meetings<br>- 2026-03-10 âœ“<br>- 2026-03-03 âœ“<br>- 2026-02-24 âœ“</pre><p>The Summary.md is the <strong>canonical</strong> location for open tasks in that meeting series. Not the individual notes. When the AI summarizes a new meeting, it merges - updates existing items, marks completed ones, adds new ones. One source of truth per meeting series. No duplication.</p><h3>Wraps: The Time Lens</h3><p>The second mechanism operates on a different axis: time. Daily wraps pull from all meetings that day. Weekly wraps synthesize the dailies. Monthly wraps synthesize the weeklies. Quarterly wraps synthesize the monthlies.</p><pre>wraps/<br>└── 2026/<br>    ├── Q1.md<br>    └── 03/<br>        ├── month.md<br>        └── W12/<br>            ├── week.md<br>            ├── 2026-03-16.md<br>            ├── 2026-03-17.md<br>            └── ...</pre><p>Each level answers a different question. The daily wrap: “What needs my attention today?” The weekly: “What moved this week, and what’s stuck?” The monthly: “What are the themes and trends?” The quarterly: “Where are we relative to goals?”</p><p>I don’t write any of this. I run a command and the AI reads the source notes, follows the rules for what belongs in each wrap level, and generates the document. If I haven’t run it in a few days, I run it and I’m caught up in seconds.</p><h3>The Rules</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LC58KVGQt_hkbonRsuKP9A.png" /></figure><p>In Cursor, a rule is a markdown file that the AI reads before doing anything. It’s not code. It’s not config syntax. It’s natural language describing how something should work. The AI reads it, understands it, and follows it every time it generates or modifies a file in your vault.</p><p>I write mine in English - not because I have to, but because as a developer I’m used to it. I’m not a native English speaker. You could write rules in Czech, Spanish, Japanese - the AI doesn’t care. It understands intent in whatever language you think in. That alone makes this more accessible than any app with a fixed English UI and English documentation.</p><p>Here’s a simplified version of a rule that defines how meeting notes should look:</p><pre># Meeting Notes Format</pre><pre>## File Naming<br>- Recurring meetings: YYYY-MM-DD.md<br>- One-off meetings: YYYY-MM-DD - Topic.md<br>- All meeting notes live under **/meetings/ folders</pre><pre>## Note Structure<br>- H1: the date<br>- Meeting Summary: 3-5 key bullets<br>- Key Discussion Points: detailed topics as H3 subsections<br>- Action Items: checkbox format with owner and due date<br>- Follow-Up: items needing future attention</pre><pre>## Action Items<br>Use this format:<br>- [ ] Task description @Owner - … YYYY-MM-DD</pre><p>That’s it. The AI reads this and every meeting note it generates follows this structure. Every summary it builds knows to look for these headings. Every wrap knows where to find action items.</p><h3>The Power of Editing a Rule</h3><p>Six months in, I realized my action items were missing something: I couldn’t trace <em>where</em> an action item came from. Which meeting? What context? So I edited the rule. Added one line to the action item format:</p><pre>- [ ] Task description @Owner - … YYYY-MM-DD ([source](path/to/meeting.md))</pre><p>That was a Tuesday afternoon. From that moment, every new meeting note, every summary, every wrap the AI generated included source links. No migration of old data. No plugin to install. No database column to add. I edited a text file and the system’s behavior changed.</p><h3>Rules Compound</h3><p>I started with one rule for meeting notes. Then I added one for the vault structure - so the AI knew where to put files. Then one for writing style - so generated content was concise, factual, and used consistent date formats. Then one for how action items should be reconciled across meetings.</p><p>Each rule is a small, focused file. They compose naturally. The AI reads all applicable rules before doing work, and the result is consistent output that follows all of your conventions simultaneously. It’s like having a style guide that actually enforces itself.</p><p>In Notion, if you want to change how your meeting template works, you edit the template and then every <em>new</em> page follows it - but the old ones don’t. In this system, the rule applies to everything the AI touches from now on, and if you ask it to regenerate old summaries, those update too. The rule is retroactive by nature.</p><h3>The Commands</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*O-ByijwDbOz2Qsia-ACzew.png" /></figure><p>Rules define <em>how</em> things should work. Commands define <em>what</em> to do. They’re repeatable workflows you trigger on demand - the buttons of the system, except you can rewrite what any button does.</p><p>A command is a markdown file that describes a task for the AI to perform. “Read all meeting notes from this week. Extract action items. Generate a daily wrap at this path following the wrap rules.” You run it, the AI executes it, and the output appears as a new file in your vault.</p><p>My system has a handful of commands that I run regularly:</p><ul><li><strong>wrap-day</strong> - reads today’s meeting notes, generates a daily wrap with summary, action items, and key points</li><li><strong>wrap-week</strong> - reads the daily wraps for the week, synthesizes them into a weekly view with themes, decisions, and carried-over tasks</li><li><strong>wrap-month</strong>, <strong>wrap-quarter</strong> - same pattern, higher altitude</li><li><strong>summarize-1on1</strong> - reads all unsummarized meeting notes in a 1-on-1 folder, updates the Summary.md with new topics, actions, and the summarized-meetings ledger</li><li><strong>triage-tasks</strong> - scans all Summary.md files for open action items and rebuilds a prioritized task list</li></ul><p>A typical Monday morning: I run wrap-day for Friday if I didn&#39;t already. Run wrap-week for last week. Glance at the weekly wrap - thirty seconds and I know what moved, what&#39;s stuck, what I owe people. Before a 1-on-1, I run summarize-1on1 for that person. The Summary.md updates. I read it. I know the open threads, the follow-ups, the history. Two minutes of preparation that would have taken fifteen minutes of scrolling through old notes.</p><p>Just like rules, commands are text files. When I realized my daily wraps were too verbose, I didn’t open the command file and edit it manually. I told the AI: “Wraps are too long. Emphasize brevity, cut the filler, keep action items and key decisions only.” The AI updated the command itself. When I wanted wraps to include a deadlines table, I described what I needed and the AI added it to the command.</p><p>I rarely edit rules or commands by hand. I describe what I want differently, and the AI modifies its own instructions. The system rewrites itself through conversation. The only thing I do manually is decide that something needs to change.</p><h3>The Bridge</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*b48cbACBEWCbukMsy38qXg.png" /></figure><p>One piece was still missing. Action items in my notes referenced Jira tickets, but Jira lived in a browser tab. I couldn’t ask the AI “what’s the status of this initiative?” because half the truth was in my vault and half was behind an API.</p><p>So I built a bash script that pulls Jira issues into markdown files - one file per issue, organized by status. But it doesn’t just grab the title and status. It downloads the comments on the issue and fetches the related commits from GitHub. Each Jira issue becomes a self-contained story: what was requested, what was discussed, and what was actually built. All in one markdown file, sitting in the vault alongside meeting notes that reference the same work.</p><p>Now when the AI generates a wrap or triages tasks, it has the full picture. A meeting note mentions a Jira ticket - the AI can read the ticket’s story, see the latest comments, check whether code was committed. It connects dots that would take a human twenty minutes of tab-switching to assemble. The vault becomes the single place where everything converges: meeting notes, summaries, tasks, Jira stories with their comments and commits. All in text. All readable by the agent.</p><p>This isn’t limited to Jira. Any external system that can export data - calendars, emails, CRM records - can be mirrored the same way. Markdown is the universal adapter.</p><h3>The Pattern</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gkoZ5nKa4iHNcE7YhFSV2A.png" /></figure><p>Looking back, every piece of this system follows the same principle. The vault structure is described in a rule. The meeting format is described in a rule. The wrap generation is described in a command. The Jira sync is a script. Everything that defines how the system works is a text file I can read, edit, or ask the AI to rewrite.</p><p>In a traditional app, your requirements are embedded in the product’s features. You can configure what the developer exposed. You can request what the product team prioritizes. You live within someone else’s vision of how knowledge work should function. When your needs diverge from their roadmap, you build workarounds - or you switch tools and start over.</p><p>This system inverts that. The AI has no opinions about how your notes should work. It has no roadmap, no feature backlog, no design philosophy. It does what the rules say. You <em>are</em> the product team. Your rules <em>are</em> the product. And deploying a new version takes seconds - you edit a file and the next command run reflects the change.</p><p>None of this is novel if you’re a developer. Plain text files. Git for version control. Rules as specifications. Commands as scripts. I applied the same principles I use for code to my knowledge base. Every note is versioned. Every change to a rule is a commit. Sensitive notes - like 1-on-1 meeting records - are encrypted before they’re committed. If something breaks - if an AI-generated summary goes wrong or a rule change produces bad output - I git diff to see what changed, git revert to undo it. The same safety net that protects my code protects my thinking. There&#39;s no &quot;undo&quot; button that only goes back one step. There&#39;s full history, forever.</p><h3>Build Yours</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Ko65IcF3Dk1rmNFfyjpMow.png" /></figure><p>You don’t need to copy this system. You need to start one. The barrier is low: a folder, a few markdown files, an AI agent that can read them. Write your first rule - how your meeting notes should look. Write your first command - summarize this week’s notes. See what comes out. Adjust. Iterate. The system will emerge from your own friction, just like mine did.</p><p>I’ve published a template repository with the folder scaffold, starter rules, and example commands. It’s not my vault - it’s a blank canvas with the machinery already wired. Fork it, delete what doesn’t fit, add what does. Make it yours.</p><p>Your notes should work as hard as you do. Make the AI do the work.</p><p><strong>Template Repository </strong><a href="https://github.com/vtajzich/notes-skeleton">https://github.com/vtajzich/notes-skeleton</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3f2be972cff6" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Write and Test Cursor Plugins Locally (The Part the Docs Don’t Tell You)]]></title>
            <link>https://medium.com/@v.tajzich/how-to-write-and-test-cursor-plugins-locally-the-part-the-docs-dont-tell-you-4eee705d7f76?source=rss-4726de7c7d9e------2</link>
            <guid isPermaLink="false">https://medium.com/p/4eee705d7f76</guid>
            <category><![CDATA[cursor]]></category>
            <category><![CDATA[plugins]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Vitek Tajzich]]></dc:creator>
            <pubDate>Mon, 02 Mar 2026 14:04:28 GMT</pubDate>
            <atom:updated>2026-03-02T14:04:28.625Z</atom:updated>
            <content:encoded><![CDATA[<p>Cursor has a plugin system. The <a href="https://cursor.com/docs/plugins/building">official docs</a> cover the structure well — manifest, commands, skills, rules. What they don’t cover is how to test your plugin locally during development without publishing to the marketplace.</p><p>I built a few plugins over the past months and had to figure out the local dev loop myself. The answer lives in how Cursor integrates with Claude Code’s config directories. The integration itself is a supported path, but the local plugin development workflow around it is barely documented. This article covers that gap.</p><p><em>Note: everything here was tested on macOS (Cursor 2.5.x). The config paths and sqlite commands are macOS-specific. The general approach should transfer to Linux/Windows with adjusted paths, but I haven’t verified that.</em></p><h3>What’s a Plugin, Briefly</h3><p>A plugin is a container. It can bundle primitives such as <strong>rules</strong> (persistent AI guidance in .mdc files), <strong>skills</strong> (specialized agent capabilities in SKILL.md files), <strong>commands</strong> (markdown-defined actions), <strong>hooks</strong>, <strong>agents</strong>, and <strong>MCP servers</strong> into one distributable package.</p><p>The only required file is .cursor-plugin/plugin.json:</p><pre>{<br>  &quot;name&quot;: &quot;my-plugin&quot;,<br>  &quot;version&quot;: &quot;1.0.0&quot;,<br>  &quot;description&quot;: &quot;What it does in one sentence&quot;,<br>  &quot;author&quot;: { &quot;name&quot;: &quot;Your Name&quot; },<br>  &quot;commands&quot;: &quot;./commands/&quot;,<br>  &quot;skills&quot;: &quot;./skills/&quot;,<br>  &quot;rules&quot;: &quot;./rules/&quot;<br>}</pre><p>One thing worth knowing early: <strong>Cursor plugins</strong> use .cursor-plugin/ for the manifest directory. <strong>Claude Code plugins</strong> use .claude-plugin/. Cursor integrates with parts of Claude Code&#39;s config surface — which is exactly what makes local testing possible. More on that below.</p><h3>The Minimal Plugin Structure</h3><p>Here’s a real directory tree from one of my plugins:</p><pre>my-plugin/<br>├── .cursor-plugin/<br>│   └── plugin.json<br>├── commands/<br>│   ├── do-something.md<br>│   ├── do-another-thing.md<br>│   └── install-plugin.md<br>├── rules/<br>│   └── safety.mdc<br>├── skills/<br>│   └── my-skill/<br>│       └── SKILL.md<br>└── scripts/<br>    ├── install-plugin.sh<br>    └── lib.sh</pre><p>Commands are markdown files with YAML frontmatter. The agent reads them and follows the steps:</p><pre>---<br>name: my-command<br>description: What the command does<br>---</pre><pre># My Command</pre><pre>## Steps</pre><pre>1. Ask the user for the thing.<br>2. Run `bash &lt;plugin_root&gt;/scripts/do-the-thing.sh --name &lt;name&gt;`.<br>3. Report the result.</pre><p>Rules are .mdc files with frontmatter controlling when they apply (alwaysApply: true, or scoped via globs). Skills are SKILL.md files in named subdirectories — the agent invokes them based on task context.</p><p>If you don’t specify paths in plugin.json, Cursor auto-discovers components from the default directory names. Explicit paths override auto-discovery.</p><h3>The Local Testing Problem</h3><p>The docs have a submission checklist that says “Plugin has been tested locally.” Great advice. How?</p><p>Claude Code CLI has --plugin-dir ./my-plugin for this. You point it at your plugin directory and it loads everything. Clean.</p><p>Cursor IDE doesn’t have that flag. The Marketplace is the intended distribution channel, and there’s no built-in “load from local directory” option in the IDE. So if you’re developing a Cursor plugin and want to see your commands show up in the agent’s palette, you need to register it manually.</p><h3>The .claude Directory</h3><p>Here’s what I found: Cursor’s agent reads plugin registration from ~/.claude/ — it shares Claude Code&#39;s config surface. The integration is a known supported path (Cursor&#39;s <a href="https://cursor.com/docs/agent/third-party-hooks">third-party hooks docs</a>reference it), but the local plugin dev workflow built on top of it isn&#39;t spelled out anywhere.</p><p>You need three things, plus possibly a fourth depending on your Cursor version.</p><h3>Step 1: Copy your plugin files</h3><p>What worked for me: put your plugin into ~/.cursor/plugins/&lt;name&gt;/:</p><pre>PLUGIN_NAME=&quot;my-plugin&quot;<br>TARGET=&quot;$HOME/.cursor/plugins/$PLUGIN_NAME&quot;<br>rm -rf &quot;$TARGET&quot;<br>mkdir -p &quot;$TARGET&quot;<br>for dir in .cursor-plugin commands rules skills scripts; do<br>  [ -d &quot;$dir&quot; ] &amp;&amp; cp -R &quot;$dir&quot; &quot;$TARGET/&quot;<br>done</pre><h3>Step 2: Register in ~/.claude/plugins/installed_plugins.json</h3><p>In my testing, this is the file Cursor picks up to discover locally-installed plugins. Create it (or merge into it) with your plugin entry:</p><pre>{<br>  &quot;plugins&quot;: {<br>    &quot;my-plugin@local&quot;: [<br>      {<br>        &quot;scope&quot;: &quot;user&quot;,<br>        &quot;installPath&quot;: &quot;/Users/you/.cursor/plugins/my-plugin&quot;<br>      }<br>    ]<br>  }<br>}</pre><p>The @local suffix appears to signal a locally-installed plugin, as opposed to one pulled from the marketplace. Use an absolute path for installPath — relative paths didn&#39;t work reliably in my testing.</p><h3>Step 3: Enable in ~/.claude/settings.json</h3><p>Registration alone doesn’t activate the plugin. You also need to flip the enable flag:</p><pre>{<br>  &quot;enabledPlugins&quot;: {<br>    &quot;my-plugin@local&quot;: true<br>  }<br>}</pre><h3>Step 4 (if needed): Enable third-party content import</h3><p>Depending on your Cursor version, third-party plugin loading may be gated behind a setting. Look for “Include third-party Plugins, Skills, and other configs” under Settings &gt; Features (older builds may call it “Third-party skills”). If it’s off, flip it on.</p><p>If the UI toggle doesn’t exist in your build, the sqlite fallback worked for me on macOS with Cursor 2.5.x. Close Cursor first, then:</p><pre>DB=&quot;$HOME/Library/Application Support/Cursor/User/globalStorage/state.vscdb&quot;<br>[ -f &quot;$DB&quot; ] &amp;&amp; sqlite3 &quot;$DB&quot; \<br>  &quot;INSERT OR REPLACE INTO ItemTable (key, value)<br>   VALUES (&#39;cursor/thirdPartyExtensibilityEnabled&#39;, &#39;true&#39;);&quot;</pre><p>This key may change in future builds. If the DB doesn’t exist or the write fails, skip this step and check the UI settings instead.</p><p>After these steps: restart Cursor. Your commands should appear in the agent’s command palette.</p><h3>Automate It</h3><p>Doing this manually on every change is tedious. I wrap it in a single install-plugin.sh that lives in the plugin&#39;s scripts/ directory.</p><p>The tricky part is steps 2 and 3 — you need to upsert into JSON files that may already contain entries from other plugins. Don’t just overwrite them. I use inline Python for this because jq is not always available and Python ships with most macOS setups (verify with python3 --version):</p><pre>#!/usr/bin/env bash<br>set -euo pipefail<br>command -v python3 &gt;/dev/null || { echo &quot;python3 required&quot;; exit 1; }</pre><pre>SCRIPT_DIR=&quot;$(cd &quot;$(dirname &quot;$0&quot;)&quot; &amp;&amp; pwd)&quot;<br>REPO_ROOT=&quot;$(cd &quot;$SCRIPT_DIR/..&quot; &amp;&amp; pwd)&quot;<br>PLUGIN_NAME=&quot;my-plugin&quot;<br>PLUGIN_ID=&quot;${PLUGIN_NAME}@local&quot;<br>TARGET=&quot;$HOME/.cursor/plugins/$PLUGIN_NAME&quot;</pre><pre>CLAUDE_PLUGINS=&quot;$HOME/.claude/plugins/installed_plugins.json&quot;<br>CLAUDE_SETTINGS=&quot;$HOME/.claude/settings.json&quot;</pre><pre># 1. Copy plugin files<br>rm -rf &quot;$TARGET&quot;<br>mkdir -p &quot;$TARGET&quot; &quot;$HOME/.claude/plugins&quot;<br>for dir in .cursor-plugin commands rules skills scripts; do<br>  [[ -d &quot;$REPO_ROOT/$dir&quot; ]] &amp;&amp; cp -R &quot;$REPO_ROOT/$dir&quot; &quot;$TARGET/&quot;<br>done</pre><pre># 2. Register in installed_plugins.json (upsert, don&#39;t clobber)<br>python3 - &quot;$CLAUDE_PLUGINS&quot; &quot;$PLUGIN_ID&quot; &quot;$TARGET&quot; &lt;&lt;&#39;PY&#39;<br>import json, os, sys<br>path, pid, ipath = sys.argv[1], sys.argv[2], sys.argv[3]<br>data = {}<br>if os.path.exists(path):<br>    try: data = json.load(open(path))<br>    except: data = {}<br>plugins = data.get(&quot;plugins&quot;, {})<br>entries = [e for e in plugins.get(pid, [])<br>           if not (isinstance(e, dict) and e.get(&quot;scope&quot;) == &quot;user&quot;)]<br>entries.insert(0, {&quot;scope&quot;: &quot;user&quot;, &quot;installPath&quot;: ipath})<br>plugins[pid] = entries<br>data[&quot;plugins&quot;] = plugins<br>os.makedirs(os.path.dirname(path), exist_ok=True)<br>json.dump(data, open(path, &quot;w&quot;), indent=2)<br>PY</pre><pre># 3. Enable in settings.json (upsert, don&#39;t clobber)<br>python3 - &quot;$CLAUDE_SETTINGS&quot; &quot;$PLUGIN_ID&quot; &lt;&lt;&#39;PY&#39;<br>import json, os, sys<br>path, pid = sys.argv[1], sys.argv[2]<br>data = {}<br>if os.path.exists(path):<br>    try: data = json.load(open(path))<br>    except: data = {}<br>data.setdefault(&quot;enabledPlugins&quot;, {})[pid] = True<br>os.makedirs(os.path.dirname(path), exist_ok=True)<br>json.dump(data, open(path, &quot;w&quot;), indent=2)<br>PY</pre><pre>echo &quot;Installed. Restart Cursor.&quot;</pre><p>The install script itself can be exposed as a plugin command. I have an install-plugin.md command that tells the agent to run bash &lt;plugin_root&gt;/scripts/install-plugin.sh. First install is manual, every install after that is a command.</p><h3>The Dev Loop</h3><p>It’s simple and it’s not pretty:</p><ol><li>Edit your plugin sources in your repo.</li><li>Run bash scripts/install-plugin.sh.</li><li>Restart Cursor (Cmd+Shift+P → “Reload Window” sometimes works, full restart is safer).</li><li>Test your commands, skills, and rules in the agent.</li><li>Repeat.</li></ol><p>There’s no hot-reload. No watch mode. No incremental updates. You copy files, you restart, you test. It’s the kind of workflow that makes you appreciate how spoiled we are with frontend dev servers.</p><p>But it works. And right now, it’s the only way I’ve found to iterate on Cursor plugins without publishing to the marketplace.</p><h3>What I Wish I Knew Sooner</h3><p>A few things that cost me time:</p><p><strong>.cursor-plugin/ vs </strong><strong>.claude-plugin/</strong> — Cursor uses the former. Claude Code uses the latter. If you&#39;re looking at Claude Code plugin docs and copying the structure, you&#39;ll create .claude-plugin/ and wonder why Cursor doesn&#39;t pick it up.</p><p><strong>Don’t install under </strong><strong>~/.cursor/skills/ only.</strong> I tried this first. Skills get loaded, but commands don&#39;t register. You need the full ~/.cursor/plugins/&lt;name&gt;/ path plus the .claude/ registration.</p><p><strong>Check both JSON files.</strong> I’ve hit a case where a plugin showed as installed but didn’t load — installed_plugins.json had the entry but enabledPlugins in settings.json didn&#39;t. Always verify both files after install. This may be version-specific, but it cost me an hour the first time.</p><p><strong>Restart means restart.</strong> Reload Window works sometimes. When it doesn’t and you’re staring at a command palette that doesn’t show your new commands, just quit and reopen Cursor. Save yourself the debugging.</p><p>The plugin system is young. This hack will probably become unnecessary once Cursor adds proper local dev tooling — something like --plugin-dir but for the IDE, not just the CLI. Until then, the ~/.claude/ directory is your friend.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4eee705d7f76" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>