Working with AI

Writing Specs

The quality of what xpo drive produces depends almost entirely on the quality of the spec it receives. A vague spec produces vague output. A precise spec produces shippable code.

The good news: you don't have to write specs from scratch.

Let the agent draft it

Humans are better at editing than writing from a blank page. Use that. Start with a rough idea and let your agent do the heavy lifting:

You: I want to add email notifications when an issue is assigned.
     Can you draft a spec for that?

Agent: I've looked at the codebase. Here's a draft spec...

The agent explores your codebase, understands the existing patterns, and writes a spec that's grounded in your actual architecture. Your job is to review it, push back on assumptions, and add the details only you know — business rules, edge cases, constraints.

This is faster than writing from scratch and produces better specs, because the agent already knows what files exist, what patterns are established, and what dependencies are in play.

What makes a good spec

A spec that xpo drive can execute well has three qualities:

Clear acceptance criteria. What does "done" look like? Not "add notifications" but "when an issue is assigned via the board or CLI, the assignee receives an email within 60 seconds. The email includes the issue title, a link to the board, and who assigned it."

Enough context to be unambiguous. If there are decisions to make, make them in the spec. "Use the existing mailer package" is better than "send an email somehow." "Add a notification_preferences table" is better than "store preferences."

A way to verify. The strongest specs reference something testable — "the existing test suite passes and a new integration test covers the assignment notification path." xpo drive runs your test command as the hard gate, so specs that align with testable outcomes produce the best results.

What to avoid

Too vague. "Improve the auth flow" — improve how? The agent will guess, and it will guess wrong. If you can't describe what "better" looks like, the spec isn't ready.

Too prescriptive about implementation. "In file src/auth.ts, on line 47, add a call to validateToken()" — this is micromanagement. Give the agent the what and let it figure out the where and how. It has access to the full codebase.

Multiple unrelated changes. "Add notifications and also refactor the database layer" — these are two stories. Each spec should be one coherent piece of work. If you find yourself writing "also," split it.

The spec evaluation loop

When you run xpo drive, the supervisor agent evaluates the spec before any code is written. If it finds the spec too vague or ambiguous, it revises the spec and saves the revision back to the issue — up to three rounds. This catches the worst specs before they waste a coding cycle.

But don't rely on this as a safety net. A spec that the supervisor has to rewrite three times will produce worse results than one you refined yourself in two minutes.

A practical template

You don't need to follow a rigid format. But if you want a starting point:

## What
One paragraph describing the change and why it matters.

## Acceptance criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Constraints
- Must use existing X pattern
- Must not break Y
- Performance: must handle Z

## How to verify
Describe how to test this beyond the automated suite.