Before Desktop and CLI Drift Apart: Put Agent Steps in One Versioned File

As Antigravity 2.0 multiplies entry points across desktop, CLI, and SDK, the instructions for the same task slowly diverge per surface. As an indie developer running several sites on autopilot, I lay out a design that consolidates the steps into a single versioned file each surface merely reads.

Antigravity³⁷⁷ workflow design³version controlautomation⁹⁵

✦ Premium Article

There was a stretch where I noticed the same article-generation steps produced subtly different results from the desktop than from the CLI. Tracing it, I found I had fixed the order of the quality gates on the desktop side one day, while the CLI side still held the old order. Both ran believing they had the "correct steps," yet the content of correctness disagreed.

Now that Antigravity 2.0 has multiplied entry points across a desktop app, a CLI, and an SDK, this divergence will only spread if left alone. The more surfaces there are, the more places hold instructions for the same task, and the easier it is to fix one and forget the other. Here I want to describe a design that gives no surface its own steps and instead consolidates them into one versioned file.

Suspect a "scattered" state of your steps

The first thing to review is whether the same task's steps are written in more than one place. If similar steps are embedded in your desktop settings, your CLI script, and your SDK call code, they are already scattered.

Scattered steps start identical. The problem is time. In operation, steps always change. The assumption that you can edit every place identically each time eventually breaks as long as a human does it. The moment it breaks, different work begins running quietly per surface.

Pull the steps out into a single file

The direction of the fix is simple. Peel the steps themselves away from each surface, write them in one file, and let each surface merely read it. The idea is to manage the instructions and the gate order in one place, just like code.

# pipeline.yaml — the single source of truth for the steps
version: 7
steps:
  - id: draft        # generate the draft
    prompt_ref: prompts/draft.md
  - id: gate-quality # quality gates (order fixed here)
    run: [article_gate, templating_gate, frontmatter_integrity]
  - id: bilingual    # keep JA and EN in sync
    require: { ja: true, en: true }
  - id: publish
    when: all_gates_passed

Desktop, CLI, and SDK hold no steps of their own; they merely load and run this pipeline.yaml. That way, when you want to change the steps, the place to edit is fixed to one. To reorder, edit steps, and the change takes effect on every surface at once.

✦

Thank you for reading this far.

Continue Reading

What follows includes implementation code, benchmarks, and practical content we hope you'll find useful. This site runs without ads — server and development costs are supported entirely by members like you. If it's been helpful, we'd be truly grateful for your support.

WHAT YOU'LL LEARN

✦A layout where each surface holds no copy of the steps and instead reads one versioned source file

✦The three paths by which steps quietly drift (in-place edits, copy proliferation, surface-specific exceptions) and how git stops them

✦How consolidating my four sites' auto-publish steps into one file nearly eliminated missed fix propagation

Secure payment via Stripe · Cancel anytime

✦

Unlock This Article

Get full access to the rest of this article. Buy once, read anytime. This site is ad-free — your support goes directly toward keeping it running.

Unlock all articles with Membership →

Pin "which version of the steps" with a number and git

The second pillar is giving the file a version and keeping history in git. With it, you can later identify which version of the steps a nightly job ran on.

What you carry	Its role
version number	Recorded in the run log so you can trace which steps ran
git history	Return to the correct steps from before it broke
validation on change	Stop invalid steps from flowing to production

I always write the steps' version number at the top of the run log. When a result feels off, looking first at "which version it ran on" lets me separate whether the cause lies in a change to the steps or somewhere else. Without the version number, I used to melt 30 minutes or more on this separation every time.

Three paths by which steps quietly drift

Even consolidated into one place, they drift again if you relax. I have hit three "recurrence paths" for drift.

First, in-place edits. You tweak the steps slightly while working on the desktop and forget to fold it back into the source file. You think you fixed it, but the next CLI run uses the original. I made it a rule to always reflect any in-place change into the source, and I closed off the path of editing directly on the desktop side.

Second, copy proliferation. When adding a new surface, you copy the existing steps into it. Identical at the moment of copying, they grow apart afterward. The ironclad rule is to make new surfaces reference the source, not a copy.

Third, surface-specific exceptions. The request "only on the CLI, add this one extra step" always appears. Writing it into the body of the steps makes the source depend on a specific surface and muddies it. I keep exceptions out of the body, push them outside as a thin per-surface config, and keep the source surface-independent.

Validate by machine on change

The biggest benefit of putting the steps in a file is that you can validate changes by machine. When I change the source, I automatically confirm its format is correct and that every surface can read it without trouble.

# validate-pipeline.sh — validate the source before it flows to production
set -euo pipefail
python3 -c "import yaml,sys; yaml.safe_load(open('pipeline.yaml'))" || { echo "❌ YAML syntax error"; exit 1; }
agy pipeline lint pipeline.yaml          # detect undefined steps or missing prompt_ref
agy pipeline dry-run pipeline.yaml --surface cli --surface sdk
echo "✅ source v$(grep '^version:' pipeline.yaml | awk '{print $2}') validated"

The key point is checking, together, that multiple surfaces can read the same steps, as with --surface cli --surface sdk. If just one surface fails here, you catch the divergence before it reaches production. Simply placing validation ahead of the change prevents the "per-surface correctness" from the opening from ever running.

Decide the order: which surface to fold in first

Trying to fold every surface into the source at once makes the migration itself a large task and tends to stall midway. I recommend folding gradually, in this order.

Switch the most frequently run surface to source-reference first. You feel the effect immediately, and it doubles as your first validation
Next, fold in surfaces where a stoppage hits revenue directly. In my case the steps tied to AdMob and App Store delivery fall here
Last, fold in surfaces you use only occasionally. This is a low-harm pitfall to leave for later

There is a reason for this order. The more frequent a surface, the faster and wider its drift shows. Securing it first keeps production damage small even if an incident happens mid-migration. Conversely, starting from a rarely used surface yields thin reassurance for the effort, and the migration does not continue.

A caveat: during the migration, "source-referencing surfaces" and "old inline surfaces" coexist. Because this mixed period is exactly where divergence arises, I track which surfaces are migrated in a list and avoid important changes on the not-yet-migrated ones. Changing the steps heavily mid-migration lets the propagation be avoided on the old surfaces and breeds quiet drift. The more gradually you fold them in, the safer it is, in my own experience.

Why bother this much as an indie developer

Honestly, even with steps scattered across two or three surfaces, it works for a while. I too wrote the steps inline in each surface when I started auto-publishing four sites. But as surfaces grew and I changed steps more often, small divergences from forgotten edits began appearing almost weekly.

After consolidating into one file, missed fix propagation nearly vanished, because the place to edit is one. Indie development, precisely because the only pair of hands is your own, benefits from a design that does not rely on the assumption of editing every place without omission. I try to choose a design that frees me from remembering, not one that adds work.

Your next step

First, count how many places the steps of your running automation are written in. If there are two or more, that is a candidate to drift in the future. Then write those steps out into one file and switch only the surface you use most to reference that file. Once you have the feel of "fix one place and it takes effect everywhere," you will naturally fold the remaining surfaces in too.

Thank You for Reading

Antigravity Lab is ad-free, supported entirely by members like you. We publish practical guides daily with implementation code, benchmarks, and production-ready patterns. If you've found it useful, we'd love to have you on board.