verso.md
Get started

Your specs belong
in the repo.

Not in Linear. Not in Notion. Not in a Google Doc that goes stale the day after it's written.

0

AI tools that can read your Linear tickets.

1

Line prompt when the spec is in the repo.

∞

Context. Every .md file feeds every AI tool.

Cursor, Claude Code, Copilot, Codex.
They all read your repo.
None of them read your tickets.

Same AI. Different repo. The only difference is whether it finds specs.

Without specs

$ claude "Build a login flow"

Creating /pages/login.js...

Using localStorage for sessions...

No auth library detected.

Guessing route structure...

2 of 3 generated files won't compile.

With specs in repo

$ claude "Build what's in docs/auth-prd.md"

Reading auth-prd.md ✓

Reading CLAUDE.md ✓

Using Supabase Auth + GitHub OAuth

Route: /app/login/page.tsx

4 files created. All compile. All match spec.

The spec is the prompt.

No copy-pasting from Linear into a chat window. No describing the context. The AI reads the file directly.

Before

Build a login page. We use Supabase for auth with GitHub OAuth. The callback URL is /auth/callback. Sessions use cookies, not localStorage. Put it in src/app/login/page.tsx. Use the existing Button component from src/components/ui/button.tsx. Follow the same patterns as...

After

Build what's in docs/auth-prd.md

Pull Request #142

+src/app/login/page.tsx
+src/lib/auth/oauth.ts
~docs/auth-prd.mdupdated
+tests/auth.test.ts

Spec, code, tests.
One PR.

The reviewer sees the full picture. The spec updates with the code. Not in a separate tool, days later, if someone remembers.

Docs become
guardrails.

Your ADR says Redis over Kafka. Your conventions say never use localStorage for auth. AI reads both and respects them.

This only works when the docs are .md files in the repo.

# CLAUDE.md

## Conventions

- Use Supabase Auth, not NextAuth

- Sessions in httpOnly cookies

- Never localStorage for tokens

- API routes in src/app/api/

AI reads this before writing a single line.

Linear

AUTH-234 Closed

AUTH-189 Archived

AUTH-167 Done

Where's the spec?

Repo

auth-prd.md

updated 3d ago

47 commits

git blame works

Specs outlive
the sprint.

Tickets get archived. The spec that described whyyou built something disappears into the backlog. In the repo, it's there forever.

Write the spec once.
Every AI tool reads it.

Claude Code generates the code. Cursor uses it for autocomplete. Your CI agent validates against it. One file. Many readers.

Claude CodeCursorCopilotWindsurfCodexDevin

The winning setup

Linear for tracking.
.md in the repo for specs.

Linear says "build auth." The .md file says how, in enough detail that both humans and AI can execute.

$ claude "Build what's in docs/auth-prd.md"

Reading auth-prd.md ✓

Reading CLAUDE.md ✓

Reading adr-003-supabase.md ✓

Creating 4 files:

src/app/login/page.tsx

src/app/auth/callback/route.ts

src/lib/auth/oauth.ts

src/lib/auth/session.ts

All files match spec. All follow conventions.

Start writing specs
that actually work.

Get startedLearn about AI-ready repos