A spec template for AI app builders

The short answer

A spec an AI app builder can follow has the problem in one sentence, what you are deliberately leaving out, the roles, a complete data model, numbered rules with worked examples, the screens, notifications, edge cases, seed data, and a build plan split into phases with acceptance checks. The template below has all of those sections. Copy it, fill it in, paste the whole file into your builder, then send the phase prompts one at a time.

It is the same structure as every blueprint on this site. If one of them is close to what you need, start from it instead of a blank page.

The template

Copy this into a file called spec.md and replace everything in angle brackets.

# <Tool name>

Department: <team> · Replaces: <product or spreadsheet it replaces>
For teams of <N> to <M> people.

> How to use this file: paste this whole document into your AI builder as context.
> Then send the build prompts in the Build plan section one at a time. Do not move
> to the next phase until the acceptance checks for the current phase pass.

## 1. The problem

"<One sentence, in the words of the person who has the problem.>"

<Two or three sentences on what goes wrong today and what success looks like.>

## 2. What the real product does

Research basis: <the product's pages you read, with the month you read them>.

1. <What it does, as facts you verified.>
2. <...>

### What this tool keeps
<The part your team actually uses.>

### What this tool deliberately leaves out
<Everything else, named. This stops the builder inventing features.>

## 3. Scope of v1

- <One team, one currency, one time zone, which channels, phone or desktop.>

## 4. Roles

| Role | Who | Can do |
|---|---|---|
| <Member> | <Everyone> | <...> |
| <Admin> | <...> | <...> |

## 5. Data model

All timestamps are UTC. Money is integer cents. IDs are strings.

**<Entity>**
- id
- <field> (<type>, required/optional, constraints, unique?)

<Repeat for every entity. Include an append-only Event table for history
and a Notification table (outbox) if anything sends email or messages.>

## 6. Rules

- **R1.** <One rule per line, testable, with the exact error message if it refuses.>
- **R2.** <...>

### Worked examples (with the seed data in section N)

| Input | Expected result |
|---|---|
| <...> | <...> |

## 7. Lifecycle

| Action | Who | From | To | Side effects |
|---|---|---|---|---|
| <Submit> | <Requester> | <draft> | <pending> | <events, notifications> |

## 8. Screens

1. **<Screen>**: <what it shows, what you can do, empty state.>

## 9. Notifications

<Who gets what, when, through which channel. Write to the outbox first;
if no email provider is configured, log instead of sending.>

## 10. Scheduled jobs and time

<What runs when, in which time zone, and how to test it with a
development-only way to move "now" forward.>

## 11. Edge cases

- <People leaving, roles changing, duplicates, empty states, limits.>

## 12. Seed data

<Named people with roles and reporting lines, and records that exercise
every rule. Dates relative to today.>

## 13. Build plan

### Phase 1: Foundation

    Using the <Tool name> spec above, build Phase 1 only.

    1. Set up the data model from section 5 with a real database.
    2. Add sign-in with the platform's built-in auth or Google sign-in limited to
       our company email domain. A signed-in email must match an active person;
       anyone else sees "Ask an admin to add you."
    3. Build the admin screens from section 8.
    4. Load the seed data from section 12.
    5. Add a "sign in as" switcher visible only in development.

    Do not build <later phases> yet. When you're done, list what you built and
    anything in the spec you had to interpret.

**Acceptance checks**
- [ ] <Person> can <do X> and sees <visible result>.
- [ ] <Person> cannot <do Y>; the button is hidden and a direct API call is refused.

### Phase 2: <Core flow>
<Prompt and checks, as above.>

### Phase 3: <Notifications and integrations>

### Phase 4: <Time, jobs and export>

## 14. Variations

- <Ideas for later, deliberately not in v1.>

What goes in each section, and why

The problem

One sentence in the words of the person who has it, not a product category. "Purchase requests get lost in Slack, and nobody knows who approved what" tells the builder what matters (nothing lost, every decision recorded) and what does not (dashboards, theming).

What the real product does, and what you leave out

Read the product you are replacing and write down what it does. Then name what you keep and what you leave out. The "leave out" list is as important as the "keep" list: it stops the builder from adding features nobody asked for, and it tells future readers when the paid product is the better choice.

Roles

A table of who can do what. Say explicitly that permissions are enforced on the server, not only by hiding buttons. Most security bugs in AI-built apps are a hidden button with an open API behind it.

Data model

Every entity, every field, its type and constraints. Three rules prevent most bugs: money as integer cents, dates and timestamps kept separate (with the time zone stated), and history that is append-only.

Rules with worked examples

Number the rules so prompts and checks can refer to them ("enforce R1 to R4 on the server"). For every calculation, routing decision or sort order, add a table of worked examples using the seed data. The examples show the builder exactly what the rule means and become your unit tests.

Lifecycle

A table of every status change: who can do it, from which status, to which status, and what else happens (events written, notifications sent). Anything not in the table is refused. This one table prevents a whole class of "how did it get into that state" bugs.

Seed data

Named people and records that exercise every rule: someone with no manager, an approver who is away, a value just over a threshold. Good seed data is what makes good acceptance checks possible.

Build plan and acceptance checks

Three to five phases: foundation, the core flow, notifications and integrations, then time-based jobs and export. Each prompt says what to build, which sections to follow, and what not to build yet, and ends by asking the builder to list what it had to interpret. Each phase ends with checks that name a person, an action and the visible result. Run them before moving on.

Common mistakes

• No "leave out" list. The builder fills the gaps with features you did not want.
• Rules in prose. "Managers approve big purchases" leaves "big", "managers" and "approve" to interpretation. "R3. Requests of $1,000 or more add a Finance step assigned to the Finance rule's approver" does not.
• Checks without names. "Users can approve requests" passes in every demo. "Signed in as Ana while Maya's step is active, there is no Approve button and a direct API call is refused" does not pass by accident.
• No people changes. Specs describe a stable team. Real teams have people on holiday, changing managers and leaving. Our approval workflow build test found that most spec gaps were here.
• Building everything in one prompt. Long single prompts produce code that is hard to check. Phases keep each step small enough to verify.

Questions people ask

Is this the same as a PRD?

It overlaps with a product requirements document, but it is written for a builder, not for stakeholders. A PRD explains why and for whom; this spec adds the exact data model, numbered rules, worked examples and acceptance checks a builder needs to produce working software without guessing.

How long should a spec be?

Long enough that the builder never has to guess a rule. The blueprints on this site run from about 250 to 450 lines of Markdown. A small tool with no money or permissions can be shorter.

Does this work with any AI builder?

Yes. The template is plain Markdown and builder-agnostic. Paste the whole file as context first, then send each phase prompt separately. The acceptance checks are how you find out whether your builder read the spec the way you meant it.