DEV Community: Monarch Wadia

Convention as Code: Enforcing Architecture with Scripts, CI, and AI Agents

Monarch Wadia — Sat, 14 Feb 2026 23:30:20 +0000

Conventions Drift

Vibe coding gets it 80% right, but the remaining 20% needs enforcement via some mechanical method.

Every codebase has unwritten rules. "Schemas go in their own files." "Always be explicit about strictness." They live in someone's head, or on a wiki page nobody reads. New code breaks them.

Agents break such conventions very quickly — because agents don't attend standups, don't read wikis, and don't absorb tribal knowledge through osmosis.

We hit this on a real project — an Atlassian Cloud integration with 19 tools across Jira, Confluence, and Bitbucket. We asked a simple question: are any of our validation schemas too loose?

The answer was yes. Everywhere.

Our validation library, Zod, silently strips unknown keys by default. Pass { name: "Alice", role: "admin" } to a schema that only knows about name, and role vanishes. No error, no warning, just gone.

We found 233 problems across 20 files:

No explicit strictness. 119 schemas silently stripping unknown keys because nobody told them not to.
No separation. 114 schemas buried inline inside handler functions — unnamed, unsearchable, invisible.

ESLint can't catch either of these. We needed something stronger.

Development Time: 28 Minutes. Enforcement Period: Forever.

We fixed all 233 violations in 28 minutes of wall-clock time — two custom rules, seven AI agents running in parallel. That's the fast part.

The lasting part: those same rules now run on every commit. Any future code that breaks the convention breaks the build. No code review needed. No tribal knowledge. The convention went from "something we try to remember" to something the machine enforces — permanently.

That's the pattern: encode a convention as a script, use agents to fix existing violations, then let CI enforce the rule forever.

Writing the Rules

We wrote custom rules using ts-morph, which gives you access to TypeScript's full compiler API. Unlike ESLint, it can follow method chains, track imports across files, and understand types. That's what we needed.

A rule receives the full project and returns violations. Simple. We called the rule runner topology — a small directory of scripts, each taking a ts-morph project and returning a list of violations.

The first rule: every z.object() must be followed by .strict() (reject unknown keys) or .loose() (allow them) — no silent defaults. The point isn't which one you pick; it's that the choice is explicit. We ran it:

$ tsx topology/run.ts

topology: 119 violation(s) found

  src/ipc/routes.ts:45 — z.object() must be followed by .strict() or .loose()
  src/ipc/routes.ts:52 — z.object() must be followed by .strict() or .loose()
  src/ipc/routes.ts:78 — z.object() must be followed by .strict() or .loose()
  ...
  src/web/chat/tools/workspace/readFile.ts:10 — z.object() must be followed by .strict() or .loose()
  src/web/chat/tools/workspace/writeFile.ts:11 — z.object() must be followed by .strict() or .loose()
  src/web/chat/tools/workspace/deleteFile.ts:10 — z.object() must be followed by .strict() or .loose()

119 hits. Each one a file, a line number, and a message. Exit code 1.

The second rule — every schema must live in a .schema.ts file — caught 114 more. 233 total: a precise, machine-readable list of everything that needed fixing.

Dispatching Agents — In Parallel

This is where agents earn their keep. Not one agent doing everything, but multiple agents working simultaneously on partitioned work — the same way you'd split tasks across a team, except the team spins up in seconds and doesn't need onboarding.

We used Claude Sonnet 4.5 in parallel sessions to do the refactoring.

Strictness fixes: One agent added .strict() (or .loose() where appropriate) to all 119 schemas. Each change was a single method call — one agent handled it easily.

Schema extraction: This was bigger — creating new files, naming schemas, rewriting imports. We split the 20 violating files into 6 non-overlapping groups (by directory, so no shared imports crossed boundaries) and gave each group to a separate agent. No two agents touched the same file, so there were zero merge conflicts. Seven agents total, running in parallel, done in under half an hour.

Here's what a single file looked like before and after:

Before — inline, no strictness:

// readFile.ts
import { z } from "zod";

export function createReadFileTool(rootPath: string) {
  return buildTool({
    inputSchema: z.object({
      path: z.string().describe("Path to the file"),
      startLine: z.number().int().min(1).optional(),
      endLine: z.number().int().min(1).optional(),
    }),
    execute: async ({ path, startLine, endLine }) => {
      /* ... */
    },
  });
}

After — extracted, strict, named:

// readFile.schema.ts (new)
export const ReadFileInputSchema = z
  .object({
    path: z.string().describe("Path to the file"),
    startLine: z.number().int().min(1).optional(),
    endLine: z.number().int().min(1).optional(),
  })
  .strict();

// readFile.ts
import { ReadFileInputSchema } from "./readFile.schema";

export function createReadFileTool(rootPath: string) {
  return buildTool({
    inputSchema: ReadFileInputSchema,
    execute: async ({ path, startLine, endLine }) => {
      /* ... */
    },
  });
}

The schema gets a name, explicit tightness, and a dedicated home.

Agents Verify Their Own Work

This is the key insight for anyone building agent workflows: agents don't need to understand why a convention exists. They just need a pass/fail signal — exactly like a test suite.

Each agent was told to run the rules as a final step:

After completing all changes, run tsx topology/run.ts and confirm the output is topology: 2 rule(s) passed. If any violations remain, fix them before reporting completion.

We also ran 6 verification agents that compared each git diff against the original file, confirming schemas were extracted verbatim and no behavior changed. All 6 passed.

Merge and Enforce

The rules go into the lint script:

{
  "lint": "tsc --noEmit && prettier --check . && eslint . && tsx topology/run.ts"
}

During the refactoring, this script found problems. After the merge, the same script prevents them. CI runs it on every commit — no agents involved, just a pass/fail check. Either topology: 2 rule(s) passed or the build breaks with exact file and line numbers.

A Few Things We Learned

.strict() on subset schemas crashes at runtime. If a schema validates a slice of a larger object, use .loose() instead. The rule accepts both — it just requires the choice to be explicit.
ts-morph is slow to start (~3-5 sec). Fine for CI. Noticeable in local dev loops. Scope it to specific file globs if it bothers you.
Rules need upkeep. When Zod 4 deprecated .passthrough() in favor of .loose(), we updated the rule and dispatched another agent batch. The rule was a one-line fix; the codebase was another 28-minute session.

The Pattern

This was a small project — two rules, 233 violations, 28 minutes. But the pattern is general and repeatable:

Identify a convention that lives in someone's head.
Encode it as a script that returns violations with file and line numbers.
Dispatch agents to fix the violations, using the script as their success criterion.
Enforce the script in CI so the convention can never drift again.

Every architectural convention that lives only in someone's head is a convention that agents will violate and humans will forget to enforce. Making it executable changes both problems at once. And it gives agents the same pass/fail signal they get from tests — they don't need to understand the reasoning, they just need to make the check pass.

Scripts solve the knowing. Agents solve the doing. CI solves the forgetting.

Use OpenAI in your JavaScript project the easy way with Ragged

Monarch Wadia — Mon, 10 Jun 2024 05:28:27 +0000

Introduction

Welcome to this simple tutorial on how to use OpenAI’s API in JavaScript. In this tutorial, we will be taking the help of Ragged, which is a library that makes working with OpenAI very easy and uncomplicated.

In this tutorial, we’ll walk you through the steps to set up Ragged and create a basic application. By the end of this article, you’ll have a solid understanding of how to interact with OpenAI’s models using JavaScript.

What is Ragged?

Ragged is a universal LLM client for JavaScript and TypeScript. It offers an easy-to-understand API to access various language models, including those from OpenAI. With Ragged, you can seamlessly integrate LLM capabilities into your frontend as well as backend projects.

Prerequisites

Before we begin, ensure you have the following installed on your machine:

Node.js is installed on your machine
You have an OpenAI API key

Setting Up Ragged

First, let’s create a new JavaScript project. Open your terminal and run the following commands:

mkdir openai-ragged-tutorial
cd openai-ragged-tutorial
npm init -y
npm pkg set type="module"

Next, install Ragged:

npm install ragged

Writing the Hello World Application

Now, let’s write our “Hello World” application using Ragged. Create a new file named index.js and add the following code:

import { Chat } from "ragged/chat";

// Create a new Chat instance with the OpenAI provider
const c = Chat.with('openai', { apiKey: process.env.OPENAI_API_KEY });

// Async function to handle the chat interaction
async function main() {

  // Chat with the model
  await c.chat('What is the meaning of life?');
  console.log(c.history.at(-1)?.text); // Output: "The meaning of life is to be happy."

  await c.chat('Repeat what you just said, but in hindi.');
  console.log(c.history.at(-1)?.text); // Output: "जीवन का अर्थ खुश रहना है।"

}

// Run the main function
main();

In this code:

We import the Chat class from Ragged.
We create a new instance of Chat with the OpenAI provider.
We define an asynchronous main function to handle the chat interaction.
We chat with the OpenAI model and translate its response to Hindi.

Next, you need to run this application using your OpenAI API key as an environment variable.

OPENAI_API_KEY=your_api_key node index.js

Make sure you replaced your_api_key with the actual key from OpenAI.

You should see a response from the OpenAI model printed in your terminal.

401 Problems?

If you got a “non-200 response” or an indicator that the “Status was 401”, this means you may have provided the incorrect API key. Check that the OPENAI_API_KEY variable was set correctly and try again.

Exploring More Features

Ragged offers more than just basic chat capabilities. You can access and manipulate the message history, use tools, and create autonomous agents. To learn more, you can read Ragged’s documentation.

Conclusion

In this tutorial, we covered the basics of setting up Ragged and creating a simple “Hello World” application using OpenAI’s API. Ragged makes it easy to integrate LLM capabilities into your JavaScript projects with minimal setup and effort.

Feel free to explore the Ragged documentation for more advanced features and use cases. Happy coding!