What if we stopped trusting code and started trusting outcomes? A practical framework for software development where contracts define reality and implementation becomes irrelevant.

Contract Driven Development

Systems design for multi-agent coordination — evolving from single-agent PRD executor to a full team system with SOUL-based personalities, filesystem-native state, and observable dashboards.

AI Agent System Architecture


### I. The Problem

We've been staring at the wrong thing.

For decades, software development has been about **code**. Write it. Review it. Test it. Refactor it. Debate it in pull requests. Argue about tabs vs spaces.

Meanwhile, the actual question—*does this thing deliver value?*—gets answered months later. Maybe never.

We trust code. We should trust outcomes.

---

### II. The Inversion

Imagine Maslow's hierarchy, but upside down.

At the top: **Value**. Does it make money? Does it scale? Does it matter?

At the bottom: **Resources**. Servers. Databases. Pods. The metal.

In between: layers of abstraction. Each layer depends on the one below it. Each layer makes promises to the one above it.

These promises are **contracts**.

---

### III. The Hierarchy

**Layer 5: Value**
- Is it profitable?
- Is it scalable?
- Is it sustainable?
- Does it matter?

**Layer 4: Capability**
- Can users do the thing?
- Can they pay?
- Can they leave with their data?

**Layer 3: Behavior**
- When X happens, does Y follow?
- Is it fast enough?
- Does it break?

**Layer 2: Components**
- Are the services alive?
- Do they talk to each other?
- Do they keep their promises?

**Layer 1: Resources**
- Is the server running?
- Is the database reachable?
- Is DNS resolving?

---

### IV. The Contract

A contract is not a test.

A test asks: "Does this code work?"

A contract asks: "What does 'work' mean at this level of abstraction?"

Tests verify implementation. Contracts **define reality**.

---

### V. The Cascade

Trust flows upward.

If Layer 1 contracts pass → trust the infrastructure.
If Layer 2 contracts pass → trust the components.
If Layer 3 contracts pass → trust the behavior.
If Layer 4 contracts pass → trust the capabilities.
If Layer 5 contracts pass → trust the value.

If all layers pass, you've **proven** the system delivers value.

Without reading a single line of implementation code.

---

### VI. The Two Kinds of Truth

Some contracts are **facts**. Code can check them.

- `revenue > costs`
- `latency.p99 < 200ms`
- `healthCheck(endpoint) === true`

Some contracts are **vibes**. Only humans can judge them.

- "Is this intuitive?"
- "Does this feel trustworthy?"
- "Is this copy compelling?"

For decades, vibes couldn't be contracted. They stayed in the realm of opinions, design reviews, gut feelings.

Not anymore.

---

### VII. LLM-as-Judge

An LLM can judge vibes. And return a boolean.

"Is this UI intuitive?" → yes/no
"Does this copy build trust?" → yes/no
"Is this experience delightful?" → yes/no

The judge is probabilistic, not deterministic. It has confidence, not certainty.

But it can be calibrated.

50 labeled examples. Run the judge. Measure accuracy. Tweak until 90%+.

A calibrated judge is good enough to ship on.

---

### VIII. The Expanded Contract Space

Before LLMs: contracts could only encode what computers could measure.

After LLMs: contracts can encode what humans can judge.

Brand consistency. Emotional resonance. Ethical compliance. Accessibility. Tone.

All contractable now.

The space of "things you can formally verify" just exploded.

---

### IX. The Implication

If contracts define reality, and all contracts pass, then reality is correct.

By definition.

Implementation becomes **irrelevant**.

- Ralph writes it? Fine.
- A human writes it? Fine.
- GPT-7 writes it? Fine.

Same contracts. Different shadows on the cave wall.

You don't review implementation. You validate contracts.

---

### X. The Development Loop

Old way:
```
Idea → Code → Test → Deploy → Hope
```

CDD:
```
Value Contract → Capability Contract → Behavior Contract → Component Contract → Resource Contract
                                                                                        ↓
                                                                              Implementation
                                                                                   (whatever)
                                                                                        ↓
                                                                              Validate Cascade
                                                                                        ↓
                                                                                All pass? Ship.
```

You iterate on **contracts**, not code.

If value isn't being delivered, you don't debug implementation. You ask: which layer's contract is failing? Fix that contract. Regenerate implementation.

---

### XI. The Axioms

At the foundation, you need things you trust without proof.

- Network reachability implies existence.
- Arithmetic is valid.
- Money in the bank is real.
- Retention correlates with value.

CDD doesn't eliminate trust. It makes trust **explicit**.

Name your axioms. Derive everything else.

---

### XII. The Promise

If you adopt CDD:

1. **No more code review.** Contracts are the review.
2. **No more implementation debates.** If it passes, it's correct.
3. **No more "does it work?" anxiety.** The cascade answers that.
4. **No more hoping value gets delivered.** Value is contracted.

The implementation becomes disposable. Generate it. Throw it away. Generate again.

The contracts are the product.

---

### XIII. The Risk

LLM judges can be wrong.

Deterministic checks can have bugs.

Contracts can be poorly specified.

CDD doesn't guarantee correctness. It guarantees **explicitness**.

When something fails, you know exactly where. Which layer. Which contract. Which field.

That's worth everything.

---

### XIV. The Bet

We bet that:

1. Outcomes can be contracted.
2. Contracts can be validated.
3. Validation can be trusted.
4. Implementation can be ignored.

If true, we've just made 90% of software development—the implementation part—a commodity.

The remaining 10%? Defining what "value" means.

That's the hard part.

That's the human part.

That's the only part that matters.

---

*Contracts are the product. Implementation is a shadow.*


What if we stopped trusting code and started trusting outcomes? A philosophical framework for software development where contracts define reality and implementation becomes irrelevant.

Contract-Driven Development: An Armchair Manifesto


### tldr;

For some reason, I have a particular disdain for writing blog titles and meta descriptions. So I thought "maybe AI could do it for me..."

Turns out, it can. And it's pretty easy.

### Why Use AI for Blog Titles?

Because writing them feels like busy work. And they are usually words that I would struggle to come up with myself. And I hate it. ⛈

### The OG Blog Post Script

On this blog, all of my MDX files are stored in `/src/content/articles`. I have a simple script that let's
me run

```shell
$ yarn article:new some-article-slug-i-like
```

When I run that, it generates a numbered MDX file
in that directory with the appropriate slug. Here's what that script looked like originally:

```js:/scripts/add-article.js
const fs = require('fs')
const path = require('path')

// helper that gets the number of the file from a string like 0001-my-first-post.mdx
function getFileNameIndex(fileName) {
  if (!fileName) return 0
  const match = fileName.match(/^[0-9]+\-/)
  if (!match) return 0
  return parseInt(match[0].slice(0, -1), 10)
}

async function addArticle() {
  // grab the title from the command line arguments
  const title = process.argv[2]
  const directory = process.argv[3] || 'articles'
  const directoryPath = `src/content/${directory}`

  // read the src/content/articles directory and get the last numbered file (e.g. 0035-hello-world.mdx)
  const files = await fs.readdirSync(
    path.join(process.cwd(), directoryPath),
    {
      withFileTypes: true,
    }
  )

  // sort by index and grab the last file
  const lastFile = files
    .filter((file) => file.name.endsWith('.mdx'))
    .sort((a, b) => {
      const aIndex = getFileNameIndex(a?.name) || 0
      const bIndex = getFileNameIndex(b?.name) || 0
      return bIndex - aIndex
    })[0]

  // get the index of the last file
  const index = getFileNameIndex(lastFile?.name) || 0

  // ensure the new index is a string with 4 digits
  const indexString = `${index + 1}`.padStart(4, '0')

  // get the current date in the format YYYY-MM-DD
  const date = new Date().toISOString().split('T')[0];

  // create a new file name with the next index
  const newFileName = `${indexString}-${title.toLowerCase().replace(/ /g, '-')}.mdx`

  // create the new file
  await fs.writeFileSync(
    path.join(process.cwd(), directoryPath, newFileName),
    `---
author: Ty Barho
date: '${date}'
title: ${title}
description:
tags:
---

`
  );
}

async function run() {
  await addArticle()
}

run()
```

And the correspoding `package.json` entry:

```json:/package.json {8}
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "next lint",
    "postbuild": "next-sitemap",
    "article:new": "node ./scripts/add-article.js"
  },
}
```

This was a nice setup. If I ran the command
```shell
$ yarn article:new how-to-build-an-mdx-blog-in-next
```

the script would automatically generate a file named `/src/articles/0123-how-to-build-an-mdx-blog-in-next.mdx` with
frontmatter content like this:

```text
---
author: Ty Barho
date: '08/24/2023'
title: "how-to-build-an-mdx-blog-in-next"
description:
tags:
---


```

The bad part? I still have to go write those dang SEO `title`, and `description` attributes. What a pain. 😡

### Setting Up the AI Model

I've been messing with LLM's for the past couple of weeks, and I thought: "Man, I really hate writing blog titles
and meta descriptions. I wonder if ChatGPT could do that for me."

Turns out, it can.

Here's how I edited the script...

```js:/scripts/add-article.js {3-16,58-95}
const fs = require('fs')
const path = require('path')
const OpenAI = require('openai')

require('dotenv').config({
  path: path.join(process.cwd(), '.env.development.local'),
})

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const defaultModelOptions = {
  model: 'gpt-3.5-turbo',
  stream: false,
}

function getFileNameIndex(fileName) {
  if (!fileName) return 0
  const match = fileName.match(/^[0-9]+\-/)
  if (!match) return 0
  return parseInt(match[0].slice(0, -1), 10)
}

async function addArticle() {
  // grab the title from the command line arguments
  const title = process.argv[2]
  const directory = process.argv[3] || 'articles'
  const directoryPath = `src/content/${directory}`

  // read the src/content/articles directory and get the last numbered file (e.g. 0035-hello-world.mdx)
  const files = await fs.readdirSync(path.join(process.cwd(), directoryPath), {
    withFileTypes: true,
  })

  const lastFile = files
    .filter((file) => file.name.endsWith('.mdx'))
    .sort((a, b) => {
      const aIndex = getFileNameIndex(a?.name) || 0
      const bIndex = getFileNameIndex(b?.name) || 0
      return bIndex - aIndex
    })[0]

  // get the index of the last file
  const index = getFileNameIndex(lastFile?.name) || 0

  // ensure the index is a string with 4 digits
  const indexString = `${index + 1}`.padStart(4, '0')

  // get the current date in the format YYYY-MM-DD
  const date = new Date().toISOString().split('T')[0]

  // create a new file name with the next index
  const newFileName = `${indexString}-${title
    .toLowerCase()
    .replace(/ /g, '-')}.mdx`

  try {
    const training = [
      { role: 'system', content: '[your base training here]' },
      { role: 'user', content: '0001-sample-post-1' },
      { role: 'assistant', content: '[example response 1]' },
      { role: 'user', content: '0002-sample-post-1' },
      { role: 'assistant', content: '[example response 2]' },
    ]

    const response = await openai.chat.completions.create({
      ...defaultModelOptions,
      messages: [
        ...training
      ],
    })

    const res = response.choices[0].message.content
    const ai = JSON.parse(res)

    const content = `---
author: Ty Barho
date: '${date}'
title: "${ai.title}"
description: "${ai.description}"
tags: ${ai.tags}
---

  `

    // create the new file
    await fs.writeFileSync(
      path.join(process.cwd(), directoryPath, newFileName),
      content
    )
  } catch (e) {
    console.error(e)
    process.exit(1)
  }
}

async function run() {
  await addArticle()
}

run()
```

After a litle prompt engineering, it worked like a charm! For example, if I run it with this command:

```bash
$ yarn article:new writing-an-automated-keyword-finder-with-puppeteer-and-ai
```

Here's the frontmatter I get:

```text
---
author: Ty Barho
date: '2023-10-18'
title: "Automated Keyword Finder using Puppeteer and AI"
description: "Learn how to build an automated keyword finder using Puppeteer to scrape search engine results and AI algorithms for keyword analysis."
tags: automation,puppeteer,ai,keyword-analysis,web-scraping
---

```

Now, instead of writing all that from my already addled brain, I can do some quick edits, and I'm done.

Pretty neat, huh? 😎🤖

### Prompt Engineering Example

For simplicity, I didn't include my training data above, just so you could read the code more clearly. But, for those
who don't yet have a lot of experience with engineering these prompts, here they are for you to tweak to your
use case.

#### The System Prompt

We start with the system prompt, which gives the LLM some basic parameters to operate by.

> yellow:"Woe" I'm still working through getting System prompts to "obey" me well. Often, some of my instructions are ignored.
> I've found using language like "You may NEVER" or the Question/Answer format work most of the time, though I still get errors.

```js
{
  role: 'system',
  content: `
You are a bot that cleans blog post titles and generates tags and descriptions.
Titles must be grammatically correct.
Descriptions must be between 50 and 160 characters.
Here is an example:
<input>0014-adding-a-copy-button-mdx-code-snippets.mdx</input>
<output>
{
  "title": "Add a Copy Button to Your Rehype (NextJS / MDX) Code Snippets",
  "description": "In this article I'll show you how to add a convenient copy button to Rehype code snippets in your NextJS MDX blog.",
  "tags": "nextjs,mdx"
}
</output>

Please note that tags should be short abbreviations.
Example: artificial-intelligence = ai
Example: natural-language-processing = nlp
`,
}
```

#### The User / Assistant Prompts

These are where you give examples of expected output. This is called "multi-shot" prompt engineering,
and IMO, this is where the meat of completion goodness happens. Make sure these are solid.

```js
;[
  { role: 'user', content: `0016-nextjs-convertkit-blog-subscriber-form.mdx` },
  {
    role: 'assistant',
    content: `{
  "title": "Newsletter Subscriptions with NextJS & ConvertKit",
  "description": "In this article, I'll teach you how to create a newsletter subscription form in NextJS, and connect to ConvertKit using NextJS api routes.",
  "tags": "nextjs,convertkit,react-hook-form,yup,api"
}`,
  },
]
```

I'm only using one-shot prompting here.  You probably want to use 2 or 3 of these "shots".

> indigo:"JSON Output" Notice that in both my `system` and `assistant` prompts, I am responding in JSON. This has proven
> effective in ensuring that I only get responses in JSON that I can parse.

### Next Steps

So far, this has been a super useful time-saver. If I were looking at where to take this next, I might
extend this by chaining another trained model to revise the description for specific SEO keywords & density,
or possibly ensure that titles are more directly related to posts that I've already created, from a content
perspective.

In the meantime, I'm just really happy that I don't have to write blog titles or meta descriptions by hand
anymore 😅.

Hope this helps someone, and happy coding! 🦄


Learn how to use AI to generate catchy and engaging blog titles for your MDX blog, and attract more readers to your content.

Generating AI-Powered Blog Titles for Your MDX Blog


I've recently jumped into prompt engineering with both feet, but found myself rewriting a lot of the same
boilerplate code when engineering new prompts. If you take a look at 2 of the tools I've added to this site:

1. [TailwindCSS + React Hook Form Generator](/tools/tailwindcss-forms-ai-generator)
2. [AI Spec Generator](/tools/ai-spec-generator)

They are pretty close to the same UI, but the API code for them was almost identical. So? DRY.

# tldr;

Vercel AI + Open AI makes building new AI experiences fast. Adding a little abstraction makes it even faster. 💥

### The Original Vercel AI API Route

To get started with Vercel AI, I basically just ripped their code from the docs [here](https://sdk.vercel.ai/docs/concepts/caching). No biggie. I added a little
training data, and some code examples, so that my first attempt at a streaming AI API route looked like this:

```js:/api/ai/code/index.js
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'
import { kv } from '@vercel/kv'

const DEV = process.env.NODE_ENV === 'development'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const modelOptions = {
  model: 'gpt-3.5-turbo',
  stream: true,
}

const training = [
  { role: 'system', content: '...' },
  { role: 'user', content: '...' },
  { role: 'assistant', content: '...' },
  { role: 'user', content: '...' },
  { role: 'assistant', content: '...' },
];

export default async function handler(req) {
  const { messages } = await req.json()
  const key = `${prefix}-${JSON.stringify(messages)}`

  // Check if we have a cached response in production
  const cached = DEV ? null : await kv.get(key)

  if (cached) {
    const chunks = cached.split(' ')
    // Emulate the "stream" interface, even if we're cached
    const stream = new ReadableStream({
      async start(controller) {
        for (const chunk of chunks) {
          const bytes = new TextEncoder().encode(chunk + ' ')
          controller.enqueue(bytes)
          await new Promise((r) =>
            setTimeout(
              r,
              // get a random number between 10ms and 50ms to simulate a random delay
              Math.floor(Math.random() * 40) + 10
            )
          )
        }
        controller.close()
      },
    })
    return new StreamingTextResponse(stream)
  }

  const response = await openai.chat.completions.create({
    ...modelOptions,
    messages: [...training, ...messages],
  })

  const stream = OpenAIStream(response, {
    async onCompletion(completion) {
      // Cache the response. Note that this will also cache function calls.
      if (DEV) {
        return;
      }

      await kv.set(key, completion)
      await kv.expire(key, 60 * 60)
    },
  })

  return new StreamingTextResponse(stream)
}

```

Not bad, considering it even implements caching for cost savings on responses.  But then,
when I went to build the second AI API route (the one for my [spec tool](/tools/ai-spec-generator)), I realized I was
basically identically copying all the meat of this handler, with the exception of the training
data.

There are a couple of ways you could handle this:

1.  Add the training data in an api request to a single ChatGPT completion endpoint
2.  Abstract the creation of AI api handlers into a function that accepts additional training data

Ultimately, I opted for #2, simply because having all that training data in React components
seemed like a weird place for it to live, and I like the flexibility of different API endpoints per bot 🤖.

Maybe I want to extend them, or chain them... who knows.  This is all new to me.

Anyway, here's the simple abstraction, and a sample implementation, for your reusing pleasure.

```js:/lib/createAIHandler.js
import { OpenAIStream, StreamingTextResponse } from 'ai'
import OpenAI from 'openai'
import { kv } from '@vercel/kv'

const DEV = process.env.NODE_ENV === 'development'

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
})

const defaultModelOptions = {
  model: 'gpt-3.5-turbo',
  stream: true,
}

export default function createAIHandler({
  prefix,
  training = [],
  modelOptions = defaultModelOptions,
}) {
  // Return a function, that is the handler
  return async function (req) {
    const { messages } = await req.json()
    const key = `${prefix}-${JSON.stringify(messages)}`
    // Check if we have a cached response
    const cached = DEV ? null : await kv.get(key)

    if (cached) {
      const chunks = cached.split(' ')
      const stream = new ReadableStream({
        async start(controller) {
          for (const chunk of chunks) {
            const bytes = new TextEncoder().encode(chunk + ' ')
            controller.enqueue(bytes)
            await new Promise((r) =>
              setTimeout(
                r,
                // get a random number between 10ms and 50ms to simulate a random delay
                Math.floor(Math.random() * 40) + 10
              )
            )
          }
          controller.close()
        },
      })
      return new StreamingTextResponse(stream)
    }

    const response = await openai.chat.completions.create({
      ...modelOptions,
      messages: [...training, ...messages],
    })

    const stream = OpenAIStream(response, {
      async onCompletion(completion) {
        // Cache the response. Note that this will also cache function calls.
        if (DEV) {
          return;
        }
        
        await kv.set(key, completion)
        await kv.expire(key, 60 * 60)
      },
    })

    return new StreamingTextResponse(stream)
  }
}
```

Pretty simple wrapper, eh?

Now, here's how you use it in a sample AI route for generating animal names:

```js:/api/ai/animal-names/index.js
import createAIHandler from '@/lib/createAIHandler'

export const runtime = 'edge'

const training = [
  { role: 'system', content: `
You are a bot that can ONLY respond with made up animal names.
Include a person's name, an adjective, a color, and an animal name.

<example>
Bart, the Slippery Green Walrus.
</example>
` },
  { role: 'user', content: 'Give me an animal name'  },
  { role: 'assistant', content: 'Sue, the Hilarious Yellow Antelope.' },
  { role: 'user', content: 'How are you?'  },
  { role: 'assistant', content: 'Jeff, the Angry Red Hare.' },
]

export default createAIHandler({
  prefix: 'animal-bot',
  training,
})
```

Lastly, wire it up in your component:

```jsx:/pages/animal-name-generator.jsx
import { useChat } from 'ai/react'

export default function Page() {
  
  const { messages, handleSubmit, input, handleInputChange } = useChat({
    api: '/api/ai/animal-names',
  });

  return (
    <>
      // Your chat UX
    </>
  )
}
```

I'm not gonna go into building forms and chat UX here, but good starting places are:

- [TailwindUI Feeds](https://tailwindui.com/components/application-ui/lists/feeds)
- [How I build forms](/articles/react-fast-performant-forms)
- [My AI Tailwind Form Generator](/tools/tailwindcss-forms-ai-generator)

Hope this helps you ramp up on your AI skillz, and happy coding! 😎

Learn how to abstract a Vercel OpenAI handler to quickly build and deploy AI-powered tools and applications.

Abstracting a Vercel OpenAI Handler for Quick AI Tools

I often get asked how I build robust forms quickly.  In this article, I'll show how to quickly build a form with React Hook Form, TailwindCSS, and Yup

Stop reading about AI. Start using it.

Articles

Contract Driven Development

Resources