DEV Community: Alex Shev

How to Build a Local-Service Site That Can Answer ‘Can You Fix My RV Today?’

Alex Shev — Sat, 22 Aug 2026 15:16:54 +0000

An RV repair business does not lose a service call because a visitor failed to read a clever headline.

It loses the call when a person with a broken slide-out, roof leak, or electrical issue cannot answer four basic questions quickly:

Do you handle this exact problem?
Do you serve where I am?
Are you available and credible?
What do I do next?

That sounds like marketing. It is mostly a systems-design problem.

The implementation goal is not “make more city pages.” It is to make the business's real-world facts available, consistent, crawlable, and usable across the website, Google Business Profile, analytics, and the conversion flow.

This post turns SEOG’s RV repair checklist into an implementation pattern a developer can apply to any local-service site.

The model: one source of truth, many decision surfaces

Local customers do not encounter a business in one place. They may see a Google result, a Maps profile, a service page, a review, or a call button before they ever submit a form.

Treat the site as one consumer of a small, canonical business data model rather than a collection of independently written pages.

business facts ─┬─> server-rendered service pages
                ├─> JSON-LD
                ├─> XML sitemap + canonical URLs
                ├─> GBP sync/review queue (with human approval)
                ├─> call/form events
                └─> audit and change history

The important part is the left side. If a mobile RV technician's phone number, service coverage, repair categories, and hours live in five unrelated CMS fields, a mismatch is inevitable.

Start with an explicit domain object.

type BusinessLocation = {
  id: string;
  legalName: string;
  publicName: string;
  phoneE164: string;
  website: string;
  address?: {
    streetAddress: string;
    addressLocality: string;
    addressRegion: string;
    postalCode: string;
    addressCountry: "US";
  };
  geo?: { latitude: number; longitude: number };
  serviceAreas: Array<{ name: string; state: string; proof: string[] }>;
  hours: Array<{ dayOfWeek: string[]; opens: string; closes: string }>;
  services: Array<{
    slug: string;
    name: string;
    customerProblem: string;
    evidence: string[];
    emergency: boolean;
  }>;
};

proof and evidence are deliberate fields. They prevent the familiar anti-pattern where a generator creates a page merely because a city name and a service name exist in a spreadsheet. A service-area claim should be backed by something real: a dispatch region, technician coverage, case work, a physical facility, or a documented operating policy.

Build pages from real combinations, not every possible combination

A useful URL is not a matrix cell.

/rv-roof-repair/mesa-az should exist only if the business actually serves Mesa for roof repair and the page can provide information a customer cannot get from a generic page.

For a Next.js application, make the eligibility rule executable instead of leaving it to editorial memory:

function canPublishServiceAreaPage(
  service: BusinessLocation["services"][number],
  area: BusinessLocation["serviceAreas"][number],
) {
  return service.evidence.length > 0 && area.proof.length > 0;
}

export async function generateStaticParams() {
  const business = await getBusinessLocation();

  return business.services.flatMap((service) =>
    business.serviceAreas
      .filter((area) => canPublishServiceAreaPage(service, area))
      .map((area) => ({ service: service.slug, area: slugify(area.name) })),
  );
}

This is a product guardrail, not an SEO trick. Google’s spam policies explicitly call out substantially similar regional pages that funnel users toward one destination as doorway abuse. A page needs its own user value, not just a different token in the title. Google’s policy is worth reading before automating local landing pages.

Render the decision-critical facts in the initial HTML

Do not make a potential customer — or a crawler — wait for a client-side API call to learn whether you repair RV electrical systems or whether emergency dispatch is available.

Use server rendering or static generation for the core page content:

// app/[service]/[area]/page.tsx
export default async function ServiceAreaPage({ params }: Props) {
  const { business, service, area } = await resolveServiceArea(params);

  return (
    <main>
      <h1>{service.name} in {area.name}</h1>
      <p>{service.customerProblem}</p>

      <section aria-labelledby="coverage">
        <h2 id="coverage">Coverage and dispatch</h2>
        <p>{area.proof.join(" ")}</p>
      </section>

      <section aria-labelledby="proof">
        <h2 id="proof">What we repair</h2>
        <ul>{service.evidence.map((item) => <li key={item}>{item}</li>)}</ul>
      </section>

      <a href={`tel:${business.phoneE164}`} data-event="service_call_click">
        Call for {service.name}
      </a>
      <RequestServiceForm serviceId={service.slug} areaId={area.name} />
    </main>
  );
}

Google can render JavaScript, but it processes JavaScript in crawling, rendering, and indexing stages. Server-rendering the essential content improves the experience for people and for crawlers, and helps other bots that do not execute the full application. See Google’s JavaScript SEO guidance.

The page should answer the real query, not manufacture confidence. If dispatch availability is unknown, say how the customer gets an answer. Never render “same-day service” because a marketing field was left enabled.

Generate structured data from the same object

Schema should be a projection of visible, maintained facts — never a second source of truth.

For a fixed physical location, use the most specific appropriate LocalBusiness subtype. For a mobile-only service, do not invent a customer-facing address. Keep the markup aligned with the content a person can see on the page.

function localBusinessJsonLd(business: BusinessLocation) {
  return {
    "@context": "https://schema.org",
    "@type": ["AutoRepair", "LocalBusiness"],
    "@id": `${business.website}/#location-${business.id}`,
    name: business.publicName,
    url: business.website,
    telephone: business.phoneE164,
    ...(business.address && { address: { "@type": "PostalAddress", ...business.address } }),
    ...(business.geo && { geo: { "@type": "GeoCoordinates", ...business.geo } }),
    openingHoursSpecification: business.hours.map((hours) => ({
      "@type": "OpeningHoursSpecification",
      ...hours,
    })),
    areaServed: business.serviceAreas.map((area) => ({
      "@type": "AdministrativeArea",
      name: `${area.name}, ${area.state}`,
    })),
    hasOfferCatalog: {
      "@type": "OfferCatalog",
      name: "RV repair services",
      itemListElement: business.services.map((service) => ({
        "@type": "Offer",
        itemOffered: { "@type": "Service", name: service.name },
      })),
    },
  };
}

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{ __html: JSON.stringify(localBusinessJsonLd(business)) }}
/>

Validate the final URL with Google’s Rich Results Test and URL Inspection — not only the JSON object in a unit test. Google recommends JSON-LD, but valid markup is an eligibility signal, not a promise of a rich result. Its LocalBusiness documentation is precise about both the implementation and that distinction.

Make canonicalization and discovery part of the build

The system should publish only the URLs it wants search engines to treat as canonical.

// app/sitemap.ts
export default async function sitemap() {
  const pages = await getPublishedServiceAreaPages();

  return pages.map((page) => ({
    url: `https://example.com/${page.service}/${page.area}`,
    lastModified: page.updatedAt,
  }));
}

Each route also needs a self-referencing canonical in its metadata. Do not put filtered, preview, parameterized, or unpublished pages in the sitemap.

Google recommends listing the canonical URLs you prefer in a sitemap; for larger sites, generate that sitemap from the same data store that controls publishing. See its sitemap guide and canonicalization guide.

Instrument the conversion path, not only page views

If the business says calls are down, “organic sessions are flat” is not enough diagnosis.

Record the transition from discovery to action without collecting more personal data than the business needs:

type LocalIntentEvent = {
  name: "service_call_click" | "quote_form_started" | "quote_form_submitted";
  service: string;
  area: string;
  pageType: "service" | "service_area";
  referrerClass: "organic" | "maps" | "paid" | "direct" | "other";
};

export function trackLocalIntent(event: LocalIntentEvent) {
  analytics.track(event.name, event);
}

Track the call click, form start, form submission, and any booking completion that the business can measure. Send only the fields needed for analysis; do not put phone numbers, issue descriptions, or other sensitive request content into generic analytics events.

Then join those events with a small operational audit:

service + area + page version
  -> rendered page checks
  -> profile/review freshness check
  -> call/form events
  -> prioritized human-approved change
  -> re-check window

This makes it possible to distinguish “we need more demand” from “people are reaching us but the service, coverage, trust, or contact path is unclear.”

Add tests where local sites usually drift

The highest-value tests are boring:

it("does not publish a service-area route without service and coverage proof", () => {
  expect(canPublishServiceAreaPage(noEvidenceService, coveredArea)).toBe(false);
  expect(canPublishServiceAreaPage(realService, noProofArea)).toBe(false);
});

it("keeps the phone number consistent across page and JSON-LD", async () => {
  const html = await renderPage("rv-electrical-repair", "mesa-az");
  expect(html).toContain("+14805550199");
  expect(extractJsonLd(html).telephone).toBe("+14805550199");
});

Also run an integration check in CI for:

200 responses for published pages and 404 for ineligible combinations;
canonical URL matches the route;
sitemap contains only published canonical URLs;
no noindex leaks from preview/staging configuration;
JSON-LD reflects visible service, hours, phone, and location data;
call/form controls exist and are keyboard accessible;
content changes have a reviewed audit record.

The operating rule: suggest changes, do not silently mutate trust surfaces

A developer can automate discovery, validation, and draft generation. That does not mean an integration should silently rewrite a Google Business Profile, alter service areas, or publish review responses.

Use an approval queue:

observed fact -> proposed correction -> evidence -> risk -> human approval -> apply -> verify

This keeps automation useful without treating a business identity as an unattended configuration file.

Closing thought

The durable local-service implementation is not a pile of keywords and location templates.

It is a small, tested facts system that makes the same answer available everywhere a customer needs it:

We fix this problem. We serve this area. Here is the proof. Here is what to do next.

That is a better foundation for search visibility, Maps presence, AI-assisted discovery, and — most importantly — a service call that actually reaches the business.

Original business-facing guide: RV Repair SEO Checklist: What to Fix When Service Calls Slow Down

Build the audit, or start with the evidence

If you are building this workflow for a local-service team, SEOG turns the same inputs — Google Business Profile completeness, map visibility, competitor context, reviews, local pages, and conversion gaps — into a prioritized, human-approved action plan.

Explore the platform: seog.ai

Stop Treating Local SEO Expansion Like a City-Page Generator

Alex Shev — Mon, 10 Aug 2026 20:00:18 +0000

Most local SEO expansion plans start too late in the workflow.

The client says:

We want more jobs in this suburb.

The team answers:

Create a city page.
Add the city to the service area.
Track a few keywords.
Maybe buy more leads.

That can work sometimes.

But it is also how teams create doorway pages, make risky Google Business Profile changes, and spend money in markets where the actual blocker was not content.

The better question is not:

Can we target this city?

The better question is:

What local signals say this market is worth pursuing, and what should be fixed before we expand?

That is where location intelligence becomes useful for local SEO.

Not as a fancy map demo.

As a decision system.

The problem with city-level thinking

Local search is geographic, but many local SEO workflows still behave as if geography is just a keyword modifier.

They treat:

plumber dallas
plumber plano
plumber frisco

as three content tasks.

But a local market is not only a keyword.

It has:

competitor density
review expectations
map visibility patterns
category fit
service-area reality
local proof
customer trust signals
citation and entity consistency
website support for the actual service and area

A business can be strong near its office and invisible ten miles away.

A service-area business can have a wide radius on paper and still look weak in a specific neighborhood.

A website can mention a suburb and still fail to prove that the business actually serves it.

That is why a single rank check from the office is not enough.

It tells you one viewpoint.

It does not tell you the market.

Location intelligence, in practical terms

For local SEO, I would define location intelligence like this:

Turning geographic signals into a prioritized action plan.

That sounds simple, but it changes the order of work.

Instead of starting with:

What page should we create?

you start with:

Where is the business already credible?
Where is it visible but not trusted?
Where is it trusted but not visible?
Where are competitors stronger?
Where does the website fail to support the local promise?
Which fix is likely to matter first?

That is a much better operating loop.

It also makes the final recommendation safer.

Sometimes the answer is still a new local page.

Sometimes the first fix is review velocity.

Sometimes it is a Google Business Profile category or service mismatch.

Sometimes it is citation cleanup.

Sometimes it is simply: do not expand here yet.

A market-area scorecard beats an unordered audit

The most useful version of this workflow is not a giant report.

It is a market-area scorecard.

For each target area, compare a small set of signals:

Market area: North suburb
Primary service: emergency HVAC repair

Profile readiness:
- GBP categories match the service?
- services listed clearly?
- photos and hours current?
- call / booking path visible?

Map visibility:
- visible near the office?
- visible near the target suburb?
- missing for money terms?

Trust:
- review count vs competitors?
- review recency?
- negative reviews unanswered?
- service-specific proof?

Competitors:
- who dominates the local pack?
- are they stronger because of reviews, proximity, category fit, website support, or all of it?

Website support:
- useful service page?
- useful location / area proof?
- internal links?
- conversion path?

Entity consistency:
- name, phone, site, address or service-area signals aligned?
- important directories clean enough?

Recommendation:
- first three fixes
- what not to do yet
- re-check date

This is not complicated.

That is the point.

A client can understand it.

An agency can repeat it.

An operator can re-check it after the fixes.

And an AI agent can run parts of it if the inputs are structured enough.

The dangerous fixes are usually the premature ones

The biggest value of this approach is not that it finds more tasks.

It stops bad tasks.

For example, do not start with:

changing a Google Business Profile address or service area without risk review
creating dozens of thin city pages because competitors have them
adding keywords to the business name
buying citations before core entity data is clean
increasing ad spend before fixing profile, review, and conversion gaps
assuming one office-location rank check represents the whole market

That last one is especially common.

The map is not one result.

The map is a local surface that changes with the searcher, query, proximity, category fit, competitor strength, and trust signals.

If you are making expansion decisions, you need area-level evidence.

Not vibes.

A simple priority order

When a client asks, "Should we expand into this area?", I like this order:

1. Entity mismatch

If the business name, phone, website, address, or service-area signals are inconsistent, fix that before scaling.

Messy entity data makes everything else less trustworthy.

2. Profile mismatch

If the Google Business Profile does not clearly support the target service, fix categories, services, hours, photos, and conversion links before writing more pages.

3. Trust gap

If local competitors have fresher reviews, better photos, clearer services, or stronger ratings, the first fix may be trust, not content.

Customers often choose from a small local set.

Small trust differences compound fast.

4. Coverage gap

If the site does not support the service-area promise, build or improve the relevant page.

But make it useful.

A local page should help a customer choose you, not just repeat a city name.

5. Competitor gap

If competitors dominate because their profile, reviews, categories, and pages are aligned, you need a market-specific improvement plan.

Not a generic "local SEO package."

6. Measurement gap

If you cannot re-check the same area after changes, the report becomes opinion.

Track the target area, the first fixes, and the re-check window.

Where software should help

This is where I like the SEOG framing.

The product is not interesting because it promises a magic ranking button.

That would be the wrong promise.

The useful promise is more operational:

Run a local visibility preview.
Compare the market-area signals.
Turn the gaps into a prioritized action plan.

That is the job most local SEO teams actually need help with.

Not another dashboard full of disconnected metrics.

Not another spreadsheet where every row has the same urgency.

A workflow that says:

This market is worth pursuing.
These competitors are the pressure.
These signals are weak.
Fix these three things first.
Do not touch these risky things yet.
Re-check this area after the changes.

That is a stronger client conversation.

It is also a better internal workflow for agencies.

Why this matters for developers and automation teams

If you are building internal tools for marketing teams, this is a good example of a broader product lesson:

Do not only expose data.
Expose decisions.

A local SEO tool can show:

rankings
reviews
competitors
profile fields
citations
pages
traffic
calls

But the operator still needs to know what to do first.

The more useful system connects those signals into a decision model:

input signals -> market comparison -> risk checks -> priority order -> action plan -> re-check

That is the difference between a dashboard and an operating workflow.

Dashboards are good for visibility.

Workflows are good for action.

Local SEO expansion needs both, but the workflow is usually the missing piece.

A practical template

Here is the template I would use before recommending expansion into a new local market:

Target area:
Primary service:
Current local visibility:
Strongest three competitors:
Profile gaps:
Review / trust gaps:
Website support gaps:
Citation / entity gaps:
Conversion path gaps:
Risky changes to avoid:
First three fixes:
Re-check date:
Decision:
  - expand now
  - fix first, then expand
  - hold / not worth the effort yet

That last line matters.

Not every market deserves action right now.

Sometimes the best SEO recommendation is sequencing.

Final thought

Local SEO expansion should not begin as a city-page generator.

It should begin as a market decision.

If the evidence says the business is visible, trusted, and supported by the site, then expansion work can make sense.

If the evidence says the profile is mismatched, reviews are stale, competitors are stronger, and the website does not support the area, more pages may only create noise.

The better workflow is:

compare the market -> find the gap -> fix the blocker -> re-check -> expand with evidence

That is the angle I like in SEOG's location-intelligence checklist.

It turns local SEO from an unordered pile of tasks into a decision system.

Original SEOG guide:

https://seog.ai/blog/location-intelligence-local-seo-checklist-market-expansion

Midnight Borscht: CSS Comfort Food Art

Alex Shev — Tue, 04 Aug 2026 05:09:56 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art.

Inspiration

Midnight Borscht is inspired by the kind of comfort food that feels quiet instead of flashy: a deep beet soup, a spoon on the side, rye bread nearby, sour cream melting into the surface, dill scattered on top, and an embroidered tablecloth underneath.

I wanted the art to feel like a small kitchen after dark. The bowl is warm, the wall tiles are dim, and the tablecloth pattern gives the scene a handmade feeling.

Demo

Live demo: https://desciple88.github.io/midnight-borscht-css-art-devchallenge-2026/

Source code: https://github.com/desciple88/midnight-borscht-css-art-devchallenge-2026

Journey

The constraint for this piece was simple: no images, no SVG, and no JavaScript. Everything is HTML and CSS.

The bowl, soup surface, sour cream, dill, beet pieces, potato, spoon, bread, wall tiles, and woven tablecloth are all built from layered div and span elements with gradients, border radii, shadows, repeated backgrounds, transforms, and pseudo-depth.

The hardest part was making it read as food at both desktop and mobile sizes. The desktop version has a composed poster feel, while the mobile version keeps the bowl large enough to show the toppings without letting the scene become a random crop.

CSS details I cared about:

The borscht surface uses stacked radial gradients to keep the soup from looking flat.
The sour cream and dill sit above the beet base to create a clear focal point.
The tablecloth is made with repeating linear gradients and stitched bands instead of an image.
The wall tiles use rotated CSS squares so the background still feels handcrafted.
Steam is animated, but prefers-reduced-motion disables the motion for users who request it.

I self-checked the final piece with local desktop and mobile screenshots, verified that the page contains no image, SVG, or script tags, and deployed it as a public GitHub Pages demo.

License: MIT.

Leftover Ladle: Comfort Food from What You Already Have

Alex Shev — Tue, 04 Aug 2026 04:42:21 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, Perfect Landing

What I Built

Leftover Ladle is a landing page for a fictional comfort-food service that turns fridge leftovers into a warm dinner plan.

The theme is built around one very human comfort-food moment: it is late, it is raining, you do not want another delivery app, and the best meal is probably already hiding in your kitchen.

I focused the page around a complete landing experience:

A first-viewport hero with a CSS kitchen scene, simmering pot, window, rain, jars, and steam.
A clear “how it works” section that explains the product without a wall of copy.
An interactive bowl builder where users choose a base, comfort mood, heat level, and allergy adjustments.
A concise menu section with three comfort-food directions.
A reservation form with accessible status feedback.

Demo

Live demo: https://desciple88.github.io/leftover-ladle-devchallenge-2026/

Source code: https://github.com/desciple88/leftover-ladle-devchallenge-2026

Journey

I chose the Perfect Landing prompt because it rewards more than decoration. A good food landing page has to make the visitor hungry, but it also has to feel easy to use.

The main design choice was to avoid a generic restaurant page. Instead of selling one dish, Leftover Ladle sells a useful comfort-food ritual: pick what is already in your pantry, choose the mood, and get a bowl plan.

Accessibility and resilience were part of the build from the beginning:

Semantic header, nav, main, section, form, fieldset, and footer structure.
A skip link for keyboard users.
Real labels for controls and inputs.
An aria-live bowl preview so updates are announced.
High-contrast buttons and focus states.
prefers-reduced-motion handling for the rain and steam animation.
No runtime dependencies, so the page stays fast and easy to inspect.

The part I am happiest with is the CSS kitchen scene. It gives the page its own visual identity without relying on a stock food photo, and it still supports the landing page rather than becoming a separate art experiment.

I also self-checked the project with desktop and mobile screenshots, static HTML checks for duplicate IDs and label targets, and a JavaScript syntax check before submitting.

License: MIT.

How I Debugged a Broken Vertex AI Image Pipeline and Finally Made It Reliable

Alex Shev — Mon, 03 Aug 2026 16:47:18 +0000

Last week, I lost more time to AI infrastructure than to the actual creative work.

The task sounded simple: generate images through Vertex AI for a content pipeline.

What actually happened:

one key worked yesterday and failed today
one project returned invalid_grant
another returned permission denied
free tier worked sometimes, then hit quota walls
the code looked fine, but the system still didn’t produce images

This is the part nobody tells you about AI workflows:
most failures are not model failures. They’re credential, project, and policy failures.

Here’s how I finally debugged the whole thing and got the image route working again.

The symptoms

At first, the failures looked unrelated.

I saw three different classes of errors:

invalid_grant: account not found

403 Permission denied

429 RESOURCE_EXHAUSTED

That usually means one of two things:

your system is broken in multiple places
your system is pointing at multiple environments and you don’t know which one is real

In my case, it was the second one.

Step 1: Stop guessing which path is canonical

The first useful move was brutally simple:
find the one script that the team actually trusts.

For us, that was:

~/clawd/ops/production/scripts/generate_panels.py

That became the source of truth.

Not old snippets.
Not half-working notebooks.
Not memory.

Once I checked the actual script, I immediately found one hidden problem:

PROJECT = "old-project-id"

The pipeline was still hardcoded to an old project.

So even when I updated the credentials, the requests were still going to the wrong place.

That alone explained a lot.

Step 2: Separate free-tier failure from paid-route failure

We had two different routes mixed together:

Gemini API / AI Studio free tier
Vertex AI paid route

That sounds harmless, but it creates terrible debugging conditions.

Because the failure modes are different:

free tier dies with quota errors
Vertex dies with IAM / service account / project errors

If you mix them, you start solving the wrong problem.

For example, this looked like a model problem at first:

429 RESOURCE_EXHAUSTED

But it turned out to be just a burned free-tier key.

Meanwhile the paid route was failing for a completely different reason.

Lesson: treat free and paid as separate systems, even if they use the same model.

Step 3: Verify the service account before touching the code

Once I had the new Vertex JSON, I didn’t start by generating an image.
I started by checking whether the credential could even mint a token.

That kind of test saves time because it tells you whether the problem is:

auth
project permissions
or model invocation

In Python, the logic is basically:

from google.oauth2 import service_account
from google.auth.transport.requests import Request

creds = service_account.Credentials.from_service_account_file(
    "vertex_ai_key.json",
    scopes=["https://www.googleapis.com/auth/cloud-platform"],
)

creds.refresh(Request())
print(creds.token[:40])

If this step fails, don’t touch your prompts.
Don’t touch the model.
Don’t touch the rendering code.

You don’t have an image problem yet.
You have an auth problem.

Step 4: Watch for organization policies

This one burned the most time.

I created a new service account, everything looked correct, and then Google Cloud refused to create a JSON key.

The error turned out to be caused by this policy:

iam.disableServiceAccountKeyCreation

That wasn’t obvious from the first screen.
The UI showed one policy as “not enforced,” while a legacy constraint was still active somewhere above it.

That kind of mismatch is why cloud debugging feels cursed.

The practical fix was not to keep fighting the same project.
The practical fix was to create a clean personal project without inherited org-policy baggage.

That ended up being faster than trying to untangle admin policy state.

Step 5: Create one clean project and move on

The final working setup looked like this:

a new clean Vertex project
a new service account
a fresh JSON key
the canonical script updated to the new project id
one successful test generation to prove the whole path worked

Only after that did I consider the route fixed.

Not when the key existed.
Not when the policy screen looked green.
Not when the script stopped crashing.

Only when this produced an actual file:

outputs/nanobanana_vertex_test.png

That was the only result that mattered.

The working mental model

When an AI image pipeline breaks, I now check things in this order:

Which script is canonical?
Which project is the request actually hitting?
Can the credential mint a token?
Is this free-tier quota or Vertex IAM?
Are org policies blocking service-account keys?
Did I generate one real image successfully?

That order is much faster than randomly changing keys and re-running prompts.

What actually fixed it

For us, the final fix was not “better prompting.”
It was:

stopping reliance on stale project ids
replacing broken credentials
separating free-tier and paid routes
avoiding inherited org-policy traps
testing the pipeline end-to-end with a real output file

That’s not glamorous.
But it’s the difference between a pipeline you trust and a pipeline that only works when you’re lucky.

Final thought

A lot of AI tooling discourse is still obsessed with models.

But once you work with these systems in production, the real bottleneck is often much more boring:
identity, permissions, quotas, and project hygiene.

The model can be state of the art.
If your project graph is a mess, you still won’t ship.

Where Terminal Skills fits

This is also exactly the kind of workflow I want to turn into a Terminal Skill.

Not because a skill should hide the cloud setup behind magic, but because the debug order should not live only in someone’s memory.

A useful vertex-ai-image-pipeline skill would give an agent a repeatable checklist:

identify the canonical script
verify the configured project id
test whether the service account can mint a token
separate free-tier quota failures from Vertex IAM failures
check for organization-policy blockers
run one minimal generation test before touching prompts
report the exact failing layer instead of guessing

That is the broader idea behind Terminal Skills: turn messy, real operational workflows into reusable agent skills.

I will probably translate this article into a proper Terminal Skills use case next, because this is the kind of boring production workflow agents need more than another prompt template.

If you’ve had to debug a broken AI pipeline recently, I’d genuinely love to hear what failed first for you.

Stop Testing APIs by Hand. Give Your AI Agent a Bruno Workflow.

Alex Shev — Wed, 29 Jul 2026 23:25:57 +0000

Most API testing workflows break in a boring way.

Not because the team does not care about testing.

Not because nobody knows how to send a request.

Because the API workflow lives in too many places at once.

One developer has a Postman collection.
Another has a few curl commands in shell history.
The backend repo has environment variables in .env.example.
CI has a smoke test that only checks one endpoint.
The docs say one thing.
The staging API behaves slightly differently.

Then an AI coding agent enters the repo and gets asked:

Can you check this API flow?

The agent can read code.
It can write tests.
It can generate curl commands.
It can explain HTTP status codes.

But it still has the same problem a new human has.

Where is the API workflow?

If the answer is "somewhere in a GUI tool, someone's local history, and a few scattered docs," the agent has to reconstruct the whole thing from scratch.

That is not a tool problem.

That is a workflow packaging problem.

API collections should live near the code

This is why I like Bruno.

Bruno is an open-source API client that stores collections as plain text files in your Git repository.

That detail matters more than the UI.

If your API collection lives next to the application code, it becomes part of the engineering system:

request changes show up in pull requests
environment files can be reviewed
auth flows can be documented as runnable requests
test assertions can live with the request that needs them
CI can run the same collection humans use locally
new team members can learn the API by running the collection

The collection is not a private artifact hidden in a synced workspace.

It is a repo artifact.

That changes what an AI agent can do with it.

The real unit is not a request

A single API request is easy.

The useful workflow is usually a sequence:

Login.
Save the token.
Create a resource.
Read it back.
Update it.
Verify the response shape.
Clean up or test the failure path.

When developers test this manually, they often remember the sequence in their head.

That works until the API changes.

It works until staging has different data.

It works until someone else needs to debug the same flow.

It works until an agent has to run it and cannot rely on tribal memory.

The important thing to encode is not:

Send a POST request.

It is:

This is the auth flow.
These variables move from one request to the next.
These assertions prove the contract still works.
This command runs the flow in CI.

That is where Bruno's file-based model becomes useful.

A .bru request can contain the request metadata, headers, body, scripts, and tests in a human-readable format.

An environment file can define baseUrl, test users, and secret placeholders.

Post-response scripts can save values for later requests.

The CLI can run the collection:

bru run --env staging

or a folder:

bru run auth/ --env dev

or output CI-friendly results:

bru run --env dev --output results.xml --format junit

That is a much better artifact for an agent than a vague instruction like:

Test the API.

What an AI agent should not improvise

I do not want an agent inventing an API testing workflow every time.

That is how you get impressive-looking activity and weak verification.

The agent might:

hit the happy path only
test against the wrong environment
forget auth state
use fake data that bypasses the real bug
skip assertions and only report that the request returned something
paste a curl command that nobody ever runs again

None of those failures look dramatic.

They look like work.

The agent says:

I tested the endpoint.

But the team has no durable artifact, no diff, no reusable flow, and no CI hook.

That is the wrong end state.

For API work, I want the agent to leave behind something the repo can keep.

A better Bruno workflow for agents

The workflow I would want from an AI coding agent looks like this.

1. Discover the API surface

The agent should inspect routes, controllers, OpenAPI specs if they exist, existing tests, and any current API docs.

The output should be a short map:

auth endpoints
core resources
destructive actions
environment assumptions
test data requirements
flows that need chained state

No collection changes yet.

First understand the shape.

2. Create a Git-friendly collection structure

The collection should mirror the API, not the agent's thought process.

For example:

api-collection/
  bruno.json
  environments/
    dev.bru
    staging.bru
  auth/
    login.bru
    refresh-token.bru
  users/
    list-users.bru
    get-user.bru
    create-user.bru
  orders/
    create-order.bru
    process-refund.bru

That structure is boring on purpose.

People can navigate it.

Agents can navigate it.

Reviewers can diff it.

3. Encode variables and secrets correctly

Environment files should carry normal config like:

baseUrl: http://localhost:3000
testEmail: test@example.com

Secrets should be marked as secrets and not committed as plain values.

This is one of the places where an agent needs a rule, not vibes.

If a tool can run requests, it can also leak credentials by accident.

So the workflow has to define where config lives, which values can be committed, and what must stay local or injected by CI.

4. Chain requests deliberately

Many real API tests are stateful.

Create user returns an ID.

Create order depends on the user.

Refund depends on the order.

The agent should not fake those IDs when it can capture them from the real response.

That is where post-response scripts are useful.

The point is not clever scripting.

The point is making the API flow executable instead of explanatory.

5. Put assertions next to the request

A request without assertions is only a smoke signal.

The agent should add tests for the contract that matters:

status code
required fields
expected types
auth behavior
error shape
permission boundaries
idempotency or retry behavior when relevant

The test should answer:

What would make this endpoint unsafe to ship?

Not:

Did the server return any JSON?

6. Add a CI command

The workflow is not done until there is a command the team can run again.

For example:

bru run --env staging

or:

bru run auth/ users/ --env ci --output results.xml --format junit

The exact command depends on the project.

But the artifact should be clear enough that a developer, CI job, or future agent can repeat the same check.

Where Terminal Skills fits

This is exactly the kind of workflow that belongs in a skill.

The Terminal Skills catalog has a bruno skill for AI agents:

Bruno on Terminal Skills

The useful part is not "the agent has heard of Bruno."

That is not enough.

The useful part is giving the agent an operating procedure:

use Bruno as a Git-first API testing tool
store collections as reviewable repo files
organize requests by API structure
use environment files for config
keep secrets out of committed values
write assertions in requests
chain state between calls intentionally
run collections through the Bruno CLI
treat the collection as living API documentation

Install for Codex:

npx terminal-skills install bruno --agent codex

Install for Gemini CLI:

npx terminal-skills install bruno --agent gemini

Install for Claude Code:

npx terminal-skills install bruno

The broader point is simple:

If an agent is going to touch your API workflow, do not ask it to improvise testing.

Give it a repeatable workflow it can follow, edit, run, and leave behind.

Why this matters for API teams

API testing is one of those areas where AI can create false confidence quickly.

An agent can generate a convincing explanation of an endpoint.

It can generate sample requests.

It can say the test passed.

But unless the workflow leaves a durable artifact, the value disappears after the chat.

The better outcome is:

the Bruno collection was updated
the change is visible in Git
the request has assertions
the environment is explicit
the command can run locally
CI can run it later
the next agent does not need to rediscover the flow

That is the difference between assistance and operational memory.

The agent did not just test the API.

It improved how the team tests the API.

My practical checklist

If I were reviewing an agent-generated Bruno workflow, I would ask:

Does the collection live in the repo?
Does the folder structure match the API shape?
Are environments separated cleanly?
Are secrets marked and excluded from committed values?
Do important requests include assertions?
Are auth tokens and IDs passed through real response state?
Can the collection run from the CLI?
Is there a CI-ready command?
Would a new teammate understand the API faster after reading and running it?

If the answer is yes, the agent left behind something useful.

If the answer is no, it probably just tested by hand with extra steps.

The broader lesson

AI agents are good at producing one-off work.

Engineering teams need repeatable work.

That is the gap skills are meant to close.

For API testing, the difference is especially visible.

Do you want the agent to send a request once?

Or do you want it to build the API workflow your team can keep using?

That is why Bruno is a good fit for Terminal Skills.

It turns API testing into files, diffs, commands, and checks.

And those are exactly the kinds of artifacts agents can use without asking everyone to trust a chat transcript.

Disclosure: AI assistance was used to draft and edit this article.

I fixed an unbounded audio queue in a live translation server before it could take the process down

Alex Shev — Wed, 15 Jul 2026 01:51:04 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

The project is a live speech translation app.

A browser client captures microphone audio, converts it to 16 kHz PCM, and streams it to a NestJS server over Socket.IO. The server opens one WebSocket session to a local ML service, forwards the audio frames, and relays translated segments back to listeners.

The important part for this bug: audio starts arriving from the browser before the ML WebSocket is guaranteed to be open.

That is normal for realtime systems. The dangerous part was what happened when the ML service was unavailable, slow to handshake, or stuck behind a bad connection.

Bug Fix or Performance Improvement

The MlSession class buffered audio frames while waiting for the ML WebSocket to open:

sendAudio(pcm: Buffer) {
  if (this.closed) return;
  if (this.open) this.ws.send(pcm);
  else this.queue.push(pcm);
}

That looks harmless until you remember what the data is: raw PCM audio.

At 16 kHz, mono, 16-bit PCM, the stream is roughly 32 KB per second per active speaker. If the ML WebSocket never opens, every audio event keeps appending another Buffer to queue. A stalled ML service could quietly turn one active audio source into an unbounded memory growth path.

The server did not have to be under heavy traffic for this to matter. One broadcaster with a stuck ML backend was enough to create an ever-growing in-memory queue.

Code

I added an explicit cap for queued audio before the ML connection opens, tracked queued bytes, reset the counter once the connection opens, and released queued buffers on close/error.

const MAX_QUEUED_AUDIO_BYTES = Number(
  process.env.ML_MAX_QUEUED_AUDIO_BYTES || 512 * 1024,
);

The send path now fails fast instead of buffering forever:

sendAudio(pcm: Buffer) {
  if (this.closed) return;
  if (this.open) this.ws.send(pcm);
  else {
    if (this.queuedBytes + pcm.byteLength > MAX_QUEUED_AUDIO_BYTES) {
      this.finish(new Error("ML websocket audio queue overflow before connection opened"));
      try {
        this.ws.close();
      } catch {}
      return;
    }
    this.queue.push(pcm);
    this.queuedBytes += pcm.byteLength;
  }
}

When the socket opens, queued audio is flushed and the byte counter goes back to zero:

this.ws.on("open", () => {
  this.ws.send(JSON.stringify({ type: "config", ...config }));
  this.open = true;
  for (const buf of this.queue) this.ws.send(buf);
  this.queue = [];
  this.queuedBytes = 0;
});

Close/error paths also clear the queue:

close() {
  this.closed = true;
  this.queue = [];
  this.queuedBytes = 0;
  try {
    this.ws.close();
  } catch {}
}

private finish(err?: Error) {
  if (this.closed) return;
  this.closed = true;
  this.queue = [];
  this.queuedBytes = 0;
  this.onClose(err);
}

My Improvements

The fix changes the failure mode.

Before:

ML service unavailable or stuck
browser keeps streaming audio
server queues every PCM frame
memory grows until the process is restarted or killed

After:

ML service unavailable or stuck
server accepts only a bounded amount of pending audio
session closes with a specific overflow error
existing gateway cleanup runs and listeners get the normal ended signal
memory is released immediately

I kept the default cap at 512 KB, which is around 16 seconds of 16 kHz mono PCM audio. That is enough for normal connection delay but small enough to prevent a single stalled session from becoming a memory leak.

The value is configurable:

ML_MAX_QUEUED_AUDIO_BYTES=1048576

That lets production tune the buffer based on expected network conditions without changing code.

Verification

The normal server build still passes:

npm run build

Output:

> live-translation-server@0.1.0 build
> tsc -p tsconfig.json

I also ran a smoke test that accepts the TCP connection but intentionally never completes the WebSocket handshake. Then I sent audio chunks into MlSession with a small queue limit.

Expected result: the session should close with the overflow error instead of keeping the buffers forever.

Observed result:

{"closed":true,"errMessage":"ML websocket audio queue overflow before connection opened"}

That is the behavior I wanted: when the ML backend is not actually ready to receive audio, the realtime server fails the session explicitly instead of becoming a quiet memory sink.

What I learned

Realtime systems make small buffers feel safe.

This was not a dramatic bug in the happy path. The app worked when the ML WebSocket opened quickly. The bug lived in the waiting room between "the browser is already sending audio" and "the ML service is ready."

That is exactly where production bugs like to hide: not in the main algorithm, but in the glue code that assumes the next component will be ready soon.

The fix was not a bigger abstraction. It was a boundary:

audio may wait briefly, but it may not wait forever.

That one rule turns an unbounded failure into a controlled one.

Your AI App Does Not Need Ten Model Clients. It Needs a Gateway Workflow.

Alex Shev — Tue, 14 Jul 2026 23:44:12 +0000

Most AI apps start with one provider.

That is usually fine.

You add an OpenAI SDK call, pick a model, ship the feature, and move on.

Then the product grows.

One workflow needs a cheaper model. Another needs a stronger reasoning model. Another needs image or video generation. A customer wants data routed through a specific provider. A fallback model becomes necessary because the primary one is rate-limited during a launch.

Suddenly, "just call the model" is not really the architecture anymore.

The real problem is routing.

The trap: provider logic spread across the app

The messy version looks like this:

if (task.type === "support_summary") {
  return openai.chat.completions.create(...)
}

if (task.type === "deep_research") {
  return anthropic.messages.create(...)
}

if (task.type === "image") {
  return imageProvider.generate(...)
}

That works for a while.

But as soon as the team needs fallbacks, model swaps, cost controls, or media endpoints, provider decisions start leaking into product code.

Now the app has two problems:

product logic
model routing logic

Those should not be the same layer.

A gateway is boring in the best way

This is why I like the routerbase-gateway pattern on Terminal Skills.

The useful idea is not "one more AI provider."

The useful idea is putting OpenAI-compatible calls, model IDs, fallback choices, streaming behavior, tool calling, JSON mode, and media generation behind one gateway layer.

Instead of teaching every part of the app how to talk to every model provider, the application talks to one interface.

The routing layer decides what happens behind it.

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ROUTERBASE_API_KEY,
  baseURL: "https://api.routerbase.com/v1",
});

const result = await client.chat.completions.create({
  model: "fast-support-summary",
  messages: [
    { role: "system", content: "Summarize the customer issue clearly." },
    { role: "user", content: transcript },
  ],
});

The application code stays boring.

The routing policy can change without rewriting every feature.

Why this matters for agents

An AI coding agent can wire up raw API calls.

That is not the hard part.

The hard part is getting the agent to make the same architectural decision the team would make:

keep provider-specific logic out of product code
use environment variables consistently
keep model names configurable
support fallbacks without scattering conditionals everywhere
preserve streaming and JSON-mode behavior where the feature needs it
avoid logging sensitive prompts or keys

That is exactly the kind of workflow that belongs in a skill.

Not because the commands are complicated.

Because the judgment should be repeatable.

The skill version of the task

Without a skill, the prompt tends to be vague:

Migrate this app to use RouterBase.

That leaves too many decisions open.

With a workflow-oriented skill, the agent has a narrower job:

npx terminal-skills install routerbase-gateway --agent codex

Then the agent can follow a safer pattern:

Find existing OpenAI-compatible client calls.
Move provider configuration into environment variables.
Replace direct provider clients with the gateway base URL.
Keep model IDs outside hard-coded feature logic where possible.
Preserve streaming, tool calling, and structured-output behavior.
Add a small verification path before claiming the migration worked.

That is much closer to production work than "switch the API key."

The real win is change management

Model routing is not just an infra preference.

It changes how product teams can operate.

When the routing layer is explicit, the team can:

test cheaper models on low-risk tasks
keep stronger models for high-value workflows
add a fallback route for outages
move media generation behind the same operational pattern
compare providers without rewriting the feature
keep provider churn away from product code

The application becomes less attached to one vendor.

The team becomes more explicit about which model is used for which job.

This is where skills are useful

Most teams do not need an agent that merely knows a gateway exists.

They need an agent that knows how to migrate safely:

inspect the codebase first
identify provider-specific assumptions
make the smallest useful change
avoid leaking secrets
preserve existing behavior
verify the path after the edit

That is the difference between a tool and a workflow.

The tool is the gateway.

The workflow is how you introduce it without making the codebase harder to reason about.

Source workflow:

https://terminalskills.io/use-cases/route-ai-model-requests-through-routerbase

The short version:

If your AI app is starting to juggle providers, models, fallbacks, and media endpoints, do not scatter that logic through the product.

Put it behind a gateway.

Then teach the agent the migration workflow.

Your AI Coding Agent Does Not Need a Refactor Prompt. It Needs an Architecture Workflow.

Alex Shev — Sat, 11 Jul 2026 17:30:59 +0000

Most AI refactoring advice starts in the wrong place.

It assumes the hard part is telling the model what to change.

So the prompt gets longer:

Act as a senior architect.
Review this codebase.
Find refactoring opportunities.
Improve maintainability.
Make it more testable.

That sounds reasonable.

But in a real repo, that prompt is too vague to be useful.

The hard part is not asking for better architecture.

The hard part is finding the parts of the codebase where architecture is actually hurting the work.

Not every ugly file needs a refactor.
Not every repeated function needs extraction.
Not every small module is a good module.
Not every "clean" interface hides useful complexity.

Sometimes the code that looks messy is doing the real work.
Sometimes the code that looks clean is only clean because the complexity was pushed into every caller.

That is the part an AI coding agent needs help with.

It needs an architecture workflow.

The problem with generic refactoring agents

When I let an agent inspect a codebase with only a broad refactor instruction, it tends to do one of three things.

First, it finds obvious style issues.

Naming.
Duplication.
Large files.
Missing comments.
Inconsistent patterns.

Those can matter, but they are rarely the architectural bottleneck.

Second, it proposes interface extraction too early.

The agent sees coupling, so it creates a service.
It sees repeated logic, so it creates a helper.
It sees conditionals, so it creates strategies.

The code looks more "designed" afterward, but the system may become harder to understand because the same concept is now split across more files.

Third, it treats testability as an extraction problem.

If something is hard to test, the agent may pull small pure functions out of the flow until the tests become easy.

That can make unit tests pleasant while hiding the real bugs in orchestration, boundaries, state, and integration behavior.

The result is a codebase with more files, more seams, more mock points, and not necessarily better architecture.

I do not want an agent to refactor like that.

I want the agent to slow down and ask a better question:

Where did understanding this system become expensive?

Architectural friction is a better signal than file size

A useful architecture pass should start by exploring the codebase the way a new senior engineer would.

Not by counting lines.
Not by ranking files by complexity score.
Not by searching for "TODO".

By following concepts.

For example:

Where does one business concept require bouncing through five shallow modules?
Where is the public interface almost as complicated as the implementation?
Where do callers need to know too much about internal sequencing?
Where are tests mostly checking implementation details?
Where do changes require touching several files that should probably move together?
Where does the agent keep losing the thread while trying to understand one behavior?

That last one is underrated.

If an agent gets lost while navigating the repo, that is not only a model limitation.

It may be an architecture signal.

Humans feel this too. We just describe it differently:

Every change here takes longer than it should.

or:

You have to know too much context before touching this module.

or:

The tests pass, but I do not trust this area.

That is the layer worth investigating.

The deep module idea maps surprisingly well to agents

John Ousterhout's deep module idea is still one of the best ways to think about this.

A deep module has a small interface that hides meaningful complexity.

That matters for humans because a good interface reduces the amount of system knowledge a developer needs to hold in their head.

It matters for AI agents for the same reason.

Agents are good at following local instructions.

They are worse when every small change requires reconstructing a hidden social map of the repo:

This helper is called here.
But only after this validation.
Unless this flag is set.
And this type is technically shared.
But this caller mutates it.
And the test mock does not match production behavior.

When the implementation is scattered but the concept is unified, the agent has to infer the module boundary every time.

That is waste.

Good architecture gives both humans and agents a smaller surface to reason about.

The goal is not fewer files.

The goal is better boundaries.

A better workflow for agent-assisted architecture review

The workflow I prefer has seven stages.

1. Explore before proposing

The agent should walk the codebase and record friction.

No refactor proposals yet.
No new interfaces yet.
No patches yet.

Just exploration.

The output should be a list of architectural friction points, not a list of code smells.

For each candidate, I want:

the module or concept cluster involved
why those files are coupled
what state or behavior is spread across them
what tests are hard to write or trust
what kind of change becomes expensive there

This is the step most refactor prompts skip.

2. Present candidates, not solutions

The agent should show the candidates and ask which one to explore.

That sounds small, but it prevents a common failure mode:

The agent picks an area that looks bad but is not important.

Architecture work should follow business and maintenance pressure.

If an area is ugly but stable, it may not be the next refactor.

If an area changes every week and every change creates review anxiety, that is a better target.

3. Frame the problem space

Before designing anything, the agent should describe the constraints.

For example:

This cluster handles customer eligibility.
It currently depends on plan state, billing status, account flags, and region rules.
The callers mostly need one decision: can this customer use this feature?
The current implementation exposes too many intermediate checks.

This framing is useful because it separates the problem from the proposed interface.

The team can disagree with the framing before arguing about code.

4. Generate multiple interface designs

One proposal is not enough.

Architecture design benefits from contrast.

I like asking separate agents, or separate passes, to design different interfaces:

one minimal interface
one flexible interface
one optimized for the most common caller
one ports-and-adapters version if external dependencies are involved

The point is not to blindly choose the most elegant design.

The point is to expose trade-offs.

5. Compare the designs in prose

This is where the main agent should be opinionated.

Not:

Here are three options. Which do you prefer?

Better:

Option A is easiest to adopt but leaks dependency order.
Option B hides the right complexity but may be too abstract for current callers.
Option C is the strongest default because most callers only need one decision.
I would use C, with the error reporting shape from B.

That is the kind of help I actually want from an agent.

6. Turn the decision into an RFC

Once the direction is chosen, do not jump straight to a giant PR.

Create a refactor RFC issue.

It should include:

the current friction
the chosen boundary
the interface sketch
migration plan
test strategy
risks
what not to change yet

This gives the team a reviewable architecture artifact before implementation begins.

7. Only then edit code

The implementation should be the last step, not the first.

If the agent starts by editing, it will often optimize the local patch instead of the architecture.

The workflow has to force the design conversation first.

Where Terminal Skills fits

This is the kind of workflow that belongs in a skill, not in a one-off prompt.

The Terminal Skills catalog has an improve-codebase-architecture skill that packages this exact style of process:

Improve Codebase Architecture on Terminal Skills

It is not a magic refactoring button.

That is the point.

It teaches the agent to:

explore the codebase organically
treat navigation friction as a signal
identify shallow modules and coupling clusters
present candidates before proposing interfaces
design multiple alternative boundaries
compare trade-offs
create a GitHub issue RFC instead of silently rewriting the system

Install command for Codex:

npx terminal-skills install improve-codebase-architecture --agent codex

For Claude Code:

npx terminal-skills install improve-codebase-architecture

The native ad here is simple:

If your agent keeps making refactors that look clean but do not make the codebase easier to change, do not give it a bigger prompt.

Give it a repeatable architecture workflow.

Why this matters more now

Agent skills are becoming a serious part of terminal-agent work.

The ecosystem is moving in the same direction: reusable procedures are becoming a way to encode what to accomplish, when to apply it, and how to execute terminal tasks. The uncomfortable side is that skill retrieval, skill quality, and reusable automation can become fragile if the procedure is vague or unsafe.

That matches what I see in practice.

Skills are powerful when they are specific, procedural, and verifiable.

They are weak when they are just long advice files.

An architecture skill is a good test case because it cannot succeed by memorizing commands.

It has to guide judgment.

It has to slow the agent down.

It has to preserve human decision points.

It has to make the final artifact reviewable.

That is what separates an agent workflow from an agent vibe.

My practical checklist

If I were evaluating an architecture skill for a coding agent, I would ask:

Does it force exploration before edits?
Does it identify concept clusters, not just files?
Does it distinguish coupling from duplication?
Does it ask for human selection before deep design?
Does it generate multiple interface options?
Does it compare trade-offs in plain language?
Does it produce an RFC before implementation?
Does it define what should not be changed?
Does it improve test boundaries instead of just adding mocks?

If the answer is no, it is probably not an architecture workflow.

It is just a refactor prompt wearing a better title.

The broader lesson

AI agents are getting better at writing code.

That makes architecture more important, not less.

When the agent can produce a thousand-line refactor in minutes, the bottleneck shifts from typing to judgment:

Was this the right boundary?
Did we hide the right complexity?
Did we make future changes easier?
Can the team review the decision?
Can the agent explain why it chose this shape?

Those questions do not belong at the end of the PR.

They belong in the workflow.

That is why I think the next useful layer for AI coding agents is not more autonomous editing.

It is better operating procedures.

Skills are one way to package those procedures.

And architecture review is one of the places where that packaging starts to matter.

Disclosure: AI assistance was used to draft and edit this article.

The Local SEO Report Should Be an Agent Run, Not a Dashboard Screenshot

Alex Shev — Fri, 03 Jul 2026 16:21:25 +0000

Every local SEO agency has some version of the Monday reporting ritual.

Someone opens a spreadsheet.

Someone opens Google Business Profiles.

Someone checks rankings for a few money keywords.

Someone looks at reviews.

Someone peeks at competitors.

Then the team turns all of that into a client-friendly update that says what changed, what matters, and what needs approval.

The work is valuable.

The ritual is awful.

It is repetitive, stateful, and full of tiny judgment calls:

did the business drop out of the map pack?
did a negative review arrive over the weekend?
does the reply need owner approval?
did a nearby competitor suddenly gain reviews?
is this a real issue, or just noise?
should the client act this week, or just keep watching?

That is exactly the kind of workflow where I do not want an AI agent to "write an SEO report" from scratch.

I want the agent to run the operating loop.

The dashboard is not the workflow

Dashboards are useful for humans.

They are less useful as the primary interface for agents.

A dashboard usually answers:

What can I see if I click around?

An agent workflow needs a different interface:

What state exists?
What changed?
What should be checked next?
What requires approval?
What should never be done automatically?

That difference matters.

Local SEO reporting is not just data extraction. It is a recurring workflow with memory:

businesses already onboarded
keywords already tracked
ranking history over time
reviews already answered or still pending
competitors already on a watchlist
locations that need neighborhood-specific checks
client-specific rules around tone, compliance, and approval

If the agent only gets a screenshot or CSV export, it has to infer too much.

If the agent gets a structured tool layer, it can operate much closer to the real job.

That is why the SEOG skill on Terminal Skills is interesting to me.

It turns local SEO monitoring into a terminal-native MCP workflow instead of another browser tab to babysit.

Source skill: SEOG on Terminal Skills

Use case: Automate Local SEO Monitoring for Client Businesses

What the skill actually gives the agent

The SEOG skill connects an AI coding agent to the SEOG MCP server.

The platform is built around local businesses that live or die on Google Maps visibility: Google Business Profile data, map-pack rankings, reviews, and nearby competitors.

The MCP server exposes those operations as tools.

That is the important part.

Instead of asking the agent to scrape pages or reason from a dashboard screenshot, the agent can call tools for the core entities in the workflow:

businesses
keywords and rankings
Google reviews
competitors

The skill describes a streamable HTTP MCP endpoint:

claude mcp add --transport http seog https://api.seog.ai/mcp \
  --header "Authorization: Bearer <your-seog-mcp-token>"

After that, the agent can work through a structured local SEO loop:

list_businesses
check_keyword
keyword_history
sync_reviews
list_reviews
draft_review_response
discover_competitors
snapshot_competitor

That is a much better contract than:

Open my dashboard and tell me how things look.

The useful report is an impact queue

A weak AI-generated SEO report sounds like this:

Your local visibility is important. Reviews matter. Keep optimizing your profile.

Technically true.

Completely useless.

A useful local SEO report is closer to an impact queue:

1. You dropped from #2 to #5 for "emergency dentist near me" in Hyde Park.
2. Two new negative reviews need owner-approved replies.
3. A competitor within 1km added 43 reviews this month.
4. Your service page still does not match the GBP category you are trying to rank for.

That is the reporting shape agencies actually need.

The agent should not just summarize.

It should triage.

The Terminal Skills use case frames this well: the agent checks rankings, syncs reviews, snapshots watched competitors, and writes a weekly digest with movement, unanswered negative reviews, drafted replies, and competitor alerts.

The detail I like most is prioritization.

A client dropping out of the 3-pack for a money keyword matters more than a 4-star review that has not been answered yet.

That sounds obvious to an operator.

It is not obvious to a generic writing model unless the workflow teaches it.

Location context is not optional

One trap in local SEO reporting is pretending that rankings are a single global number.

They are not.

For local businesses, the search location changes the answer.

Checking from the agency office is often the wrong measurement.

A coffee shop, dentist, med spa, or plumber may care about one neighborhood more than another. The useful question is not only:

Where do we rank?

It is:

Where do we rank from the places customers actually search?

That is why I like seeing locationLabel and coordinates as part of the keyword tracking flow.

The agent can track a keyword from "Hyde Park" and "South Congress" instead of flattening the whole city into one report.

That makes the weekly digest more honest.

It also changes the recommendations.

A business might be fine near its physical address but weak in the service area it wants to expand into. That is a different action item than "rankings are down."

Review replies should be draft-first

This is the line I would not cross with automation:

An agent can draft review replies.

It should not silently publish them.

The SEOG skill makes that boundary explicit: draft_review_response saves a draft, but the owner approves in-app.

That is the right design.

Review replies are public. They touch customer trust. In medical, legal, home services, and other sensitive categories, a careless reply can create real problems.

For regulated businesses, even a friendly response can go wrong if it confirms that someone was a customer or patient.

So the automation boundary should look like this:

Agent:
- finds reviews that need attention
- groups negative or risky reviews first
- drafts safe replies
- explains why each reply needs review

Human:
- approves
- edits
- publishes

That is not a limitation.

That is the workflow becoming safer.

Good agent systems are not the ones that automate every click.

They are the ones that know which clicks require approval.

Competitor monitoring is where the report gets interesting

Most agencies already track their own client.

The better reports also watch the local battlefield.

If a nearby competitor suddenly gains review velocity, changes categories, adds services, or starts outranking the client for a money keyword, the client should hear about it before they notice it themselves.

The SEOG workflow includes competitor discovery and snapshots:

discover_competitors
add_competitor
set_competitor_watchlist
snapshot_competitor

That gives the agent a useful job:

Do not tell me everything.
Tell me what changed around this business.

That is the difference between reporting and monitoring.

Reporting describes what happened.

Monitoring notices what is starting to happen.

For local SEO, that can be the difference between:

Your rankings dropped last month.

and:

The competitor two blocks away is about to pass your review count. Start a compliant review request push now.

The second one is much more valuable.

The agent still needs guardrails

This kind of workflow is also a good reminder that MCP tools are not enough by themselves.

The skill has to teach operational boundaries.

For example:

deleting a business is irreversible and should require confirmation
live rank checks consume quota and should not run in tight loops
review replies are drafts, not published responses
API tokens are credentials and should never be logged or committed
a 401 probably means the token was revoked and needs reissue

Those details are not decoration.

They are the difference between a useful agent and a risky one.

A generic model can understand "local SEO reporting."

A skill can tell it:

Do not delete this portfolio by accident.
Do not burn quota in a loop.
Do not claim a review reply was published.
Do not leak the token.

That is exactly why I keep coming back to skills as the right abstraction for agent work.

Prompts describe intent.

Skills describe operating procedure.

A weekly agency run should look boring

The best version of this workflow is not flashy.

It is a scheduled run.

Every Monday morning:

For each client:
1. sync the business state
2. check active keywords by tracked location
3. compare rank movement against the last 7 days
4. sync reviews
5. draft replies for negative or unanswered reviews
6. snapshot watchlisted competitors
7. produce an impact-ranked digest
8. stop before anything public is published

That is boring in the best way.

It gives the agency leverage without turning the account into an autopilot risk.

The human still owns strategy, client communication, and approvals.

The agent owns the repetitive monitoring loop.

That is the split I trust.

The bigger lesson

I do not think the future of local SEO work is "AI writes reports."

That is too shallow.

The more useful shift is:

AI agents run recurring evidence-gathering workflows,
then hand humans a prioritized approval queue.

For a local SEO agency, that queue might be:

rankings that moved
reviews that need attention
competitors that changed
pages that need technical cleanup
schema gaps
business facts that no longer match across the web

The report becomes a byproduct of the operating loop.

That is the part worth building.

If an agent can run the same checks every week, preserve state, respect approval boundaries, and explain what changed, it is no longer just generating content.

It is doing operational work.

And that is where agent skills start to feel less like prompt engineering and more like actual software.

The Blender Skill That Makes AI Agents Prove the Render Exists

Alex Shev — Tue, 30 Jun 2026 21:36:15 +0000

Most AI + Blender demos stop one step too early.

The agent writes a script.

The script looks plausible.

The explanation sounds confident.

But the real question is much simpler:

Did Blender actually render the thing?

That is the line between a demo and a workflow.

If an AI agent is helping with 3D production, the output cannot just be a paragraph of advice or a Python snippet that might work. At some point, the agent has to cross into the production layer:

configure the render engine
set resolution and file format
create or aim the camera
set up lights
apply materials
render a frame or sequence
verify that the output file exists
return something the human can inspect

That is why I like the idea behind the blender-render-automation skill on Terminal Skills.

It is not trying to make Blender “magic.”

It is trying to make Blender boring enough for an agent to operate.

And boring is where real automation starts.

The problem with AI-generated Blender scripts

Blender has a powerful Python API.

That makes it tempting to treat Blender automation as a code-generation problem:

Ask the agent for a bpy script.
Paste it into Blender.
Hope it works.

Sometimes it does.

Sometimes the script uses the wrong render engine name.

Sometimes the camera points nowhere useful.

Sometimes the material code assumes a node that is not there.

Sometimes the render settings are incomplete.

Sometimes the agent says “done” even though no image was written to disk.

The annoying part is that these failures are not always dramatic. They are small production misses. The script almost works. The scene almost renders. The output almost matches what you asked for.

But “almost” is expensive in 3D work.

If you are creating product shots, thumbnails, animation previews, turntables, or review renders, the workflow needs a stronger contract than:

Here is some code you can try.

It needs:

Here is the render output. Here is the path. Here is what was configured. Here is what still needs review.

A render skill is a definition of done

The useful thing about a Blender render skill is not only that it knows bpy.

The useful thing is that it teaches the agent what “done” means.

For a render workflow, “done” should not mean:

the agent wrote a plausible answer
the agent described Cycles vs EEVEE
the agent generated a script and stopped

It should mean:

Blender was run headlessly or through a known script path
the render engine was explicitly configured
output resolution and format were set
cameras and lights were created or selected
materials were applied with clear names
a still frame or animation sequence was rendered
the expected file appeared at the expected path

That is a much better interface for AI agents.

It turns the task from “make a nice Blender thing” into a workflow with observable artifacts.

Why headless Blender matters

Blender is a visual tool, but it can also run from the command line.

That changes what an agent can do.

Instead of manually clicking through the UI, the agent can operate through a repeatable loop:

blender scene.blend --background --render-output /tmp/frame_ --render-frame 1

or:

blender scene.blend --background --frame-start 1 --frame-end 100 --render-anim

That loop is important because agents are much better when they can run something, inspect the result, and continue.

A GUI-only workflow often leaves the agent guessing.

A terminal workflow gives it evidence.

The agent can check:

did the command exit successfully?
did the PNG sequence appear?
did the MP4 get created?
did the output directory contain the expected frames?
did the render crash halfway through?

Those checks are not glamorous.

They are exactly what make automation useful.

Cycles, EEVEE, and choosing the right failure mode

The blender-render-automation skill also points at an important production distinction: not every render needs the same engine.

Cycles is physically accurate and better for final quality.

EEVEE is fast and better for previews.

That sounds obvious, but it matters for agents.

If an agent always chooses the slowest path, it wastes time.

If it always chooses the fastest path, it may return a preview that is not good enough for review.

A good render workflow should make that choice explicit:

use EEVEE for fast preview and layout checks
use Cycles for final stills or higher-quality review frames
enable denoising when samples are low
use GPU rendering when the environment supports it
avoid pretending a preview render is a final render

That kind of operational judgment is exactly what belongs in a skill.

The model can still reason about the task.

But the workflow gives it defaults that are safer than fresh improvisation every time.

Cameras and lights are not decoration

A lot of failed AI-Blender attempts are not really modeling failures.

They are camera and lighting failures.

The object exists.

The scene exists.

But the camera misses the subject, the focal length is wrong, the light is too weak, or the result is technically rendered but useless.

A render automation skill can push the agent to treat cameras and lights as part of the deliverable:

create a camera at a known location
aim it at the subject
use a reasonable focal length
add area lights or environment lighting
name cameras clearly
batch render multiple camera views when needed

This is especially useful for product work.

One render is rarely enough.

A human reviewer may need a hero angle, front view, side view, top view, and a transparent-background version.

That should not require five separate improvisations.

It should be a repeatable operation.

Render animations as image sequences first

One of the best small rules in render automation is:

Render animations as image sequences before assembling video.

That sounds like old-school pipeline advice because it is.

It is also exactly the kind of rule AI agents need.

If a direct video render fails at frame 87, you may lose the whole output or have a painful recovery path.

If an image sequence fails at frame 87, frames 1-86 still exist.

The agent can inspect what completed, rerun the missing range, and then assemble the sequence with FFmpeg.

That is a production workflow.

It is not just a Blender trick.

It is a reliability pattern:

Prefer recoverable intermediate artifacts over one fragile final artifact.

That pattern applies far beyond Blender.

But Blender makes it very visible.

Materials need conventions, not vibes

When a human says “make it premium,” an agent can generate endless material ideas.

That is not always helpful.

Production scenes need conventions:

named materials
predictable PBR settings
sane roughness and metallic values
glass separated from plastic and metal
transparent-background settings when needed
output formats chosen for the downstream use case

A render skill does not remove taste from the process.

It keeps the mechanical layer consistent so the human can spend attention on the creative layer.

That is the right division of labor.

The agent handles setup, naming, rendering, and verification.

The human judges whether the result is good.

The real product is the workflow boundary

When people talk about AI agents and creative tools, the conversation often jumps to autonomy.

Can the agent make a complete scene by itself?

Can it replace a 3D artist?

Can it generate a finished animation from one sentence?

I think that is the wrong starting point.

The more useful question is:

Can the agent own a narrow, repeatable production step?

For Blender rendering, that step might be:

set up a studio render scene
render a transparent PNG
create a 36-frame turntable
generate a contact sheet from multiple cameras
render an animation sequence
produce preview and final variants

That is a realistic agent workflow.

It does not need to replace the artist.

It needs to remove the repetitive setup work around the artist.

Why this matters for agent skills

The bigger lesson is not only about Blender.

It is about how we package work for AI agents.

A model can know a lot and still fail at the last mile.

Skills help close that gap by giving the agent:

a trigger for when the workflow applies
operational steps
command patterns
quality checks
failure modes
a definition of done

That is why I keep coming back to Terminal Skills as a useful layer.

It treats skills less like prompt decorations and more like small workflow contracts.

For Blender, that contract is easy to understand:

Do not just describe the render. Produce it, verify it, and tell me where it is.

That is the part agents need.

Not more confidence.

More proof.

The skill I am talking about is blender-render-automation on Terminal Skills:

https://terminalskills.io/skills/blender-render-automation

If you are experimenting with AI agents and Blender, I would start with one narrow workflow:

Create a clean product scene, render one preview, verify the image exists, and return the output path.

That is not flashy.

But it is the right kind of boring.

And once that works, you can build a real pipeline on top of it.

ComfyUI Is Becoming the Workflow Layer for AI Image Agents

Alex Shev — Sat, 27 Jun 2026 17:46:10 +0000

Most image generation tutorials still treat ComfyUI like a visual playground.

Open the UI.
Drag a few nodes together.
Load a checkpoint.
Generate an image.

That is useful, but it undersells why ComfyUI keeps mattering.

The more interesting shift is this:

ComfyUI is not just a UI for image generation anymore. It is becoming a workflow layer.

That matters a lot for AI agents.

An agent does not only need to write a prompt. It needs to run a repeatable process:

choose the right model
place files in the right folders
load the workflow
queue the job
wait for completion
retrieve the output
verify that the output exists
adapt the graph for the next run

A plain prompt does not give you that.

A graph does.

Why the graph matters

The big advantage of ComfyUI is that the workflow is explicit.

Instead of hiding the image pipeline behind one text box, ComfyUI exposes the steps:

checkpoint loading
prompt encoding
latent image creation
sampling
VAE decoding
image saving
ControlNet inputs
LoRA loading
upscaling
custom nodes

That can look intimidating at first, but it is exactly what makes ComfyUI useful for serious automation.

If an image workflow is just a prompt, an agent has to guess what happened.

If an image workflow is a graph, an agent can inspect the moving parts.

It can reason about the graph. It can reuse it. It can change one piece without rewriting the whole pipeline.

That is the difference between "generate something like this" and "run this visual production workflow again with different inputs."

Agents need workflows, not vibes

For casual generation, a prompt box is fine.

For production work, the weak point is rarely the first image.

The weak point is consistency.

Can you run the same style again?
Can you swap the input image?
Can you keep the ControlNet guide but change the subject?
Can you send the result into an upscale pass?
Can you use the same workflow from a script instead of clicking through the UI?

That is where ComfyUI starts to feel less like an art tool and more like infrastructure.

The workflow JSON becomes the contract.

The agent does not need to remember every step from scratch. It can submit the workflow, poll for the result, download the output, then report what happened.

The API is the underrated part

The visual graph is what people notice first.

The API is what makes it automation-friendly.

A normal agent path looks like this:

Start ComfyUI locally or on a GPU box.
Load or generate a workflow JSON.
Submit that workflow to the /prompt endpoint.
Poll /history/{prompt_id} until the job completes.
Fetch the generated image through /view.
Save the output into a known folder.

That is a much better fit for agents than browser-only image generation.

The agent can run the same workflow from code. It can log prompt IDs. It can keep output paths stable. It can fail cleanly when the server is down or a model file is missing.

That is not glamorous, but it is what makes the workflow usable.

The setup details are the real trap

The hard part is not only "how do I use ComfyUI?"

The hard part is all the small operational details around it:

which Python version is expected
which CUDA or ROCm path is being used
where checkpoint files belong
where LoRAs belong
where ControlNet models belong
how custom nodes are installed
how to run ComfyUI in Docker with GPU access
how to avoid losing outputs in random folders

These details are boring, but agents break on boring details.

That is why I like packaging this kind of workflow as a skill instead of leaving it as a loose note.

For example, I keep a ComfyUI Terminal Skill here:

https://terminalskills.io/skills/comfyui

The point is not "here is another page to read."

The point is that an agent needs a repeatable operating path. The skill gives it the ComfyUI install shape, model folder conventions, API queue example, result polling, custom node setup, ControlNet pattern, and Docker deployment notes in one place.

So when the task is "use ComfyUI for this workflow," the agent is not starting from search results. It has a known path through the tool.

You can also install it directly for an agent:

npx terminal-skills install comfyui --agent codex

That is the useful version of documentation for agent work: not a brochure, not a generic tutorial, but a compact workflow the agent can act on.

A practical ComfyUI agent workflow

If I were building an agent-controlled ComfyUI flow, I would keep it simple at first.

Start with one known working workflow.

Do not begin with ten custom node packs and a giant experimental graph.

Use a small txt2img or img2img workflow and make the agent prove it can:

start or reach the ComfyUI server
submit one workflow
capture the prompt ID
wait for completion
download the generated file
verify the file exists
report the exact output path

Only after that would I add more complexity:

ControlNet
LoRA variants
upscale passes
image prompt adapters
animation nodes
batch generation
remote GPU deployment

The first milestone is not a beautiful image.

The first milestone is a reliable loop.

Why this matters for creative automation

ComfyUI is one of the places where AI image work becomes more like software engineering.

You do not just write a prompt.

You build a pipeline.

That pipeline can be versioned, reused, inspected, debugged, and called from code.

For human artists, that gives more control.

For AI agents, it gives something even more important: structure.

Agents are much more useful when the workflow has shape.

ComfyUI gives image generation that shape.

And once the workflow is explicit, the agent can stop guessing and start operating.