Spec-Driven Development

Your agents are only as good as your spec.

Stop guessing what your agents will do. Write a spec.

What would you like to build?

Add context

Download for Mac

THE PROBLEM

You typed a prompt. Your agent got creative.

Without structure, agents fill gaps with guesses. Here's what “Add authentication to my desktop app” actually produces:

claude code

>Add authentication to my desktop app

I'll add authentication to the desktop app. Let me search for the existing auth setup...

Codebase search - context engine"authentication config"

Found 2 files

├─src/main/ipc-handlers.ts94%

├─package.json71%

No existing auth found. I'll set up NextAuth with a session provider and database schema...

Writesrc/auth/provider.tsx+48 lines

Installed NextAuth instead of ClerkWRONG FRAMEWORK

Writeprisma/schema.prisma+82 lines (modified)

Refactored database schema (not requested)SCOPE CREEP

Writesrc/api/auth/[...rest].ts+36 lines

Added REST endpoints for mobile authWRONG PLATFORM

Skipped IPC bridge between renderer and mainMISSING REQUIREMENT

No rollback plan, no feature flagNO SAFETY NET

5 issues. 0 were in your prompt. All were in the gaps.

MCP connected

Claude Sonnet 4~/project

Stop hoping your agent gets it right.

Download for Mac

THE FIX

Same prompt. Now with a spec.

A spec turns your one-liner into structured intent.

01Outcome

A spec is a contract. Start with one sentence that defines the end state.

Goal

Add Clerk-based user authentication to the desktop app. Authenticated users get access to DotAgents-hosted model providers (no personal API keys needed). This requires both client-side Clerk integration and a backend LLM proxy service.

Success metric: a new user can sign up, authenticate, and make their first LLM call within 60 seconds of launching the app — without entering any API keys.

02Scope

Agents are eager. Without non-goals, they expand into features you never asked for.

Non-goals

•Mobile app authentication (desktop only for now)

•User-facing billing/usage limits (future work)

•Rate limiting on the proxy (future work)

•Self-hosted proxy deployment docs (future work)

•OAuth social login providers beyond Clerk defaults

•Multi-tenant organization/team support

03Constraints

Every spec has assumptions. The dangerous ones are the ones you don't notice.

Assumptions

•Clerk publishable key will be provided as a build-time env var (VITE_CLERK_PUBLISHABLE_KEY)

•The LLM proxy will be deployed separately (not bundled in the Electron app), for dev it runs on localhost

•Clerk free tier is sufficient for initial launch, confirmed

•Provider API keys (OpenAI, Groq, Gemini) are stored as env vars on the proxy server

•Electron's default session partition handles cookie storage for Clerk tokens

04Decisions

Agents don't do hallway conversations. If it's not explicit, they'll re-litigate it.

Decisions

•Use Clerk (not NextAuth) for authentication — Clerk has native Electron support

•Proxy runs as a separate service, not bundled in Electron

•Feature-flagged via env var: no key = no Clerk, app works as before

•Streaming responses via SSE, not WebSockets — simpler, works through CDNs

•JWT validation on every proxy request, no session caching (security-first)

05Tasks

The biggest AI failure mode is asking for too much in one shot. Break it down.

Tasks

Add Clerk auth to the Electron renderer

Auth state IPC bridge (renderer → main)

Backend LLM proxy service with JWT validation

Connect desktop app to use proxy when authenticated

Auth-aware UI in settings (sign in/out, status)

Error handling: expired tokens, network failures, key rotation

06Checks

If you can't test it, you can't spec it. No ambiguity, no 'it should feel right.'

Acceptance Criteria

Users can sign in / sign up via Clerk in the desktop app

Authenticated users can use LLM features without providing their own API keys

A backend proxy validates Clerk JWTs and proxies LLM requests with server-side API keys

Unauthenticated users can still use the app with their own API keys (no regression)

Auth tokens are never persisted to disk in plaintext

The proxy supports streaming (SSE) responses end-to-end

Expired JWT returns 401; client auto-refreshes and retries once

Download for Mac

THE FIX

Same prompt. Now with a spec.

A spec turns your one-liner into structured intent. Scroll to see it build, section by section.

Coordinator

auth-middlew...

a3f7b2c: Add...

Add authentication to my desktop app

1h ago

Describing outcome

Goal

Success metric: a new user can sign up, authenticate, and make their first LLM call within 60 seconds of launching the app — without entering any API keys.

Type a message...

Claude Opus 4.6@

Download for Mac

THE RESULT

Now watch it actually run.

The spec becomes the system's source of truth. A coordinator delegates tasks, agents execute in parallel, and everything stays in sync. You review the plan, not the diff.

Intent — spec-driven workflow

Add authentication to my desktop app — dotagents/desktop⌘K

Coordinator×

clerk-auth.tsx×

e4a1b3d: Add...×

AGENTS / Coordinator / Coordinator agent

We need to add user authentication to the desktop app. Users should be able to sign in and use hosted LLM providers without managing their own API keys.

I'll implement Clerk-based auth for the Electron app with a backend proxy. Let me analyze the current codebase.

2h ago

Make sure unauthenticated users can still use the app with their own API keys. Also handle token expiry gracefully.

Good call. I'll feature-flag the auth and add automatic token refresh. Let me break this into parallel tasks.

1h ago

Go ahead. Start with the Clerk integration in the renderer, then the LLM proxy service.

I'll coordinate agents across the desktop app and proxy service. Spawning specialists now:

Clerk Auth AgentRunning...

Integrating Clerk authentication into Electron renderer

// clerk-auth.tsx

import { ClerkProvider } from "@clerk/clerk-react"

export function AuthProvider({ children }) {

return <ClerkProvider publishableKey=...

LLM Proxy AgentRunning...

Building JWT-validated LLM proxy service

// llm-proxy.ts

export async function validateAndProxy(

req: Request, res: Response,

Both agents are working in parallel across the desktop app and proxy service. Current progress:

• Clerk Auth Agent: Setting up ClerkProvider, sign-in flows, and auth state IPC bridge
• LLM Proxy Agent: Adding JWT validation middleware and SSE streaming for LLM responses

Just now

Claude Opus 4.6@

Spec×

NOTES / Spec

Desktop App Authentication — Clerk + LLM Proxy

Overview

Add Clerk-based user authentication to the desktop app. Authenticated users get access to hosted model providers without personal API keys. Requires client-side Clerk integration in Electron and a backend LLM proxy service with JWT validation.

Architecture

• Electron renderer: Clerk auth UI, sign in/up flows
• Main process: IPC bridge for auth state
• LLM Proxy: JWT validation, API key management
• Streaming: SSE for LLM responses
• Feature flag: env var toggles auth on/off

Integration Points

• ClerkProvider wraps app root in renderer
• IPC channel: auth:getToken / auth:onStateChange
• POST /proxy/chat — validated LLM proxy endpoint
• GET /proxy/models — list available providers

Tasks

✓Add Clerk auth to Electron renderer

✓Auth state IPC bridge (renderer → main)

✓Backend LLM proxy with JWT validation

/Connect desktop app to proxyin progress

Auth-aware UI in settings

Error handling: expired tokens, network failures

End-to-end integration tests

Add authentication to desktop app

dotagents/desktop

Agent orchestration

A coordinator agent breaks down your task into a spec, then delegates work to specialist agents that run in parallel.

Coordinator

30m

I'll coordinate the auth implementation across renderer and proxy...

2 delegated agents

Clerk Auth Agent

running

LLM Proxy Agent

running

Background agents3

Test Suite Agent

Lint & Type Check

Docs Generator

Context

Context about the task, shared with all agents in this space.

Spec

Changes5

Changes made to files by agents working in this space.

feat/clerk-auth → main

■clerk-auth.tsxsrc/auth+112 -0

■llm-proxy.tssrc/services+89 -3

■auth.tssrc/config+15 -2

■clerk-auth.test.tstests/integration+74 -0

■settings.tsxsrc/components+22 -8

Files

The agents in this space are working off a copy of your files.

src

tests

config

docs

p 3000Terminallsnpm run test:watch --...

Get Started

Build with Intent

Orchestrate your agents like a system, not a swarm. Define what gets built, delegate to agents that stay aligned, and maintain full visibility from first commit to merge.

Download for Mac

Read our manifesto

Download for Mac