v1.1.0 — Open Standard · MIT License

Stop Prompting. Start Specifying.

Write the contract once. Ship the same code every time.
MAP Spec eliminates AI drift through structured, machine-readable specifications.

Read the Standard Join the waitlist
Star on GitHub — help us grow
MIT Licensed · fork freely
v1.1.0 · Atomic Specs
Phase 3 code gen · coming soon
rules.spec.yaml
api.spec.yaml
data.spec.yaml
// describe your project
// click "Generate spec" to see MAP Spec output
The Problem

AI guesses.
MAP Spec doesn't.

Give AI a vague prompt and it makes hundreds of silent decisions — wrong database, wrong security, invented tables. Every run differs.

Without MAP Spec
"Build me a todo app with user auth and offline support"
AI picks MySQL — you wanted PostgreSQL
AI uses MD5 for passwords — critical security bug
AI hard-deletes user data — compliance violation
AI invents 3 tables you never asked for
Every run produces different, inconsistent output
With MAP Spec
RULE-001: bcrypt cost=12, never log passwords [critical] RULE-004: Soft delete only, deleted_at [critical] data.spec.yaml: 3 exact tables, typed columns api.spec.yaml: 8 endpoints, exact contracts
AI uses exactly what you specified
Security rules enforced — bcrypt, soft delete, JWT
Zero invented tables, endpoints, or components
Reproducible output across every model, every run
Even the weakest model follows the spec correctly
The Standard

7 layers.
Zero ambiguity.

A complete, unambiguous contract that any AI model consumes to produce accurate, predictable output. Click any row to see real YAML.

click any row to expand
01
Meta
meta.spec.yaml
Project identity, technology stack declaration, constraints and boundaries.
// meta.spec.yaml map-spec: "1.1.0" layer: "meta" project: name: "Task Manager" type: "web-app" stack: frontend: "Next.js 14" backend: "Node.js + Express" database: "PostgreSQL 15" auth: "JWT + refresh tokens" constraints: - { type: "performance", value: "API p95 < 200ms" } - { type: "compliance", value: "GDPR — no hard deletes" }
02
Functional
functional.spec.yaml
Features, user stories, Given/When/Then acceptance criteria with AI implementation notes.
unit: id: "FEAT-001-user-registration" priority: "must-have" acceptanceCriteria: - id: "AC-001-1" given: "I am on /register" when: "I submit valid email + password" then: "redirect /dashboard, session active" aiNote: "JWT in httpOnly cookie. bcrypt.hash(pw,12) before INSERT." - id: "AC-001-2" given: "email already exists" when: "form submitted" then: "400 — EMAIL_ALREADY_EXISTS inline error" aiNote: "Show error below field. Not a toast."
03
API
api.spec.yaml
Every endpoint with exact request/response contracts, auth, rate limits and side effects.
endpoint: method: "POST" path: "/api/v1/auth/register" auth: false rateLimit: "10 req/min per IP" responses: 201: { userId: "uuid", token: "JWT" } 400: { error: "EMAIL_ALREADY_EXISTS" } 429: { error: "RATE_LIMIT_EXCEEDED" } aiNotes: - "bcrypt.hash(pw, 12) BEFORE INSERT — never after" - "Never return password hash in any response"
04
Data
data.spec.yaml
Exact database schema — every table, column type, index and relation with implementation notes.
tables: - name: "users" columns: - { name: "id", type: "UUID", primary: true } - { name: "email", type: "VARCHAR(255)", unique: true } - { name: "password", type: "VARCHAR(255)", note: "bcrypt hashed — never store plain" } - { name: "deleted_at", type: "TIMESTAMPTZ", note: "soft delete only — never DELETE FROM" } indexes: ["email", "deleted_at"]
05
UI
ui.spec.yaml
Every component — props, state, interactions, routing. AI must not invent components not listed here.
components: - id: "COMP-001-RegisterForm" route: "/register" state: ["loading", "error", "success"] interactions: - trigger: "form submit" action: "POST /api/v1/auth/register" onSuccess: "redirect /dashboard" onError: "show inline field error" aiNotes: - "Validate client-side with Zod before API call"
06
Rules
rules.spec.yaml
Business logic guardrails AI must never violate. Every critical rule has a mandatory aiInstruction field.
rules: - id: "RULE-001" domain: "security" rule: "Passwords must be hashed before storage" severity: "critical" aiInstruction: "bcrypt.hash(pw, 12) before INSERT. Never log. Never return." - id: "RULE-004" domain: "data" rule: "User records must never be hard deleted" severity: "critical" aiInstruction: "Never generate DELETE FROM users. SET deleted_at = NOW()."
07
Quality
quality.spec.yaml
Test suites, coverage requirements, performance targets. Every acceptance criterion has a test.
coverage: unit: ">= 80%" integration: ">= 60%" performance: - { endpoint: "API-001", p95: "< 200ms", tool: "k6" } testSuites: - id: "SUITE-001" type: "integration" name: "Auth Integration Tests" priority: "critical" covers: ["AC-001-1", "AC-001-2"]
How It Works

Brief to spec
in minutes.

MyAgenticPlatform generates complete MAP Spec packages automatically. Local setup today — hosted platform coming soon.

STEP 01

Describe your product

Write a brief in plain English. What you're building, who it's for, what it must do. No technical knowledge required.

Phase 0 — Clarification + Mandate
STEP 02

Generate MAP Specs

6 specialised agents generate Phase 1 artifacts, then 7 spec-writers produce atomic YAML files across all 7 layers.

Phase 2 — Atomic MAP Specs
STEP 03

Build with any AI

Copy any spec card and paste into Claude, GPT, Cursor, or Copilot. The spec binds the model. No drift. Same output every time.

Phase 3 — Code Generation (coming soon)
Live simulation

Watch MAP Spec generate in real time.

A real brief. Real agents. Real atomic specs. Click run to watch the full pipeline.

01
Product Brief
Build a task management app with team collaboration, due dates, and priority levels.
02
Phase 0 — Clarification
—
03
Phase 1 — AI Agents
—
04
Phase 2 — Atomic Specs
—
— select a spec — 
# Click any spec file on the left
# to view its YAML content here

Simulated · based on real platform output

Why Open

The standard is free.
The generator is best.

MIT licensed. Anyone can read it, implement it, build tools around it. We make money by being the best at generating it.

01

Open Standard

MIT licensed. Fork it, extend it, build tools around it. No vendor lock-in. The spec belongs to everyone.

02

AI-Optimised

Every field serves a machine-readable purpose. The aiInstruction field is mandatory on every critical rule.

03

Versioned

Every file declares map-spec: "1.1.0". Breaking changes are major versions. Full history on GitHub.

04

Human-Readable

YAML format. Any developer reads and writes MAP Spec without tooling. Stakeholders review and approve specs before code runs.

The Platform

See it working.

MyAgenticPlatform is the reference implementation. Here's what the pipeline, board, and spec viewer look like in practice.

Phase 0 approved — 6 agents complete
proj-1778750057288
Build a personal finance app with AI-powered spending insights
Completed
Phase 0 — Mandate Approved Platform Owner · 14 May 2026
Business Analyst
Product Manager
UI/UX Designer
Frontend Dev
Backend Dev
QA / Tester
Implementation Board — Kanban view · 0 / 77 done
Board
Backlog
Epic — Story — Task
To do74
TABLE-audit-logs
Audit logs table
data
API-004-POST-todos
POST /todos
api
In progress3
TABLE-users
Users table
datacritical
drag cards here
In review0
drag cards here
Done0
drag cards here
Spec viewer — click any task card to view and copy as AI prompt
AI Insights Table TABLE-ai-insights.yaml · Step 2
map-spec: "1.1.0" layer: "data" unitId: "TABLE-ai-insights" engine: "PostgreSQL" migrations: true tables: - name: "ai_insights" description: "Cached AI-generated spending analysis" columns: - { name: "id", type: "UUID", primary: true, default: "gen_random_uuid()" } - { name: "user_id", type: "UUID", foreignKey: "users.id" } - { name: "deleted_at", type: "TIMESTAMPTZ", note: "soft delete — never hard delete" }
Roadmap

What's shipped.
What's next.

Honest status on everything. No vaporware.

LIVE

Phase 1 — Artifacts

Brief to requirements, wireframes, architecture, and test cases via 6 AI agents. Mandate and clarification gating. Local setup via GitHub.

LIVE

Phase 2 — Atomic MAP Specs

Artifacts to 121 atomic YAML spec files. One file per endpoint, table, rule, component. Zero ambiguity for any AI model.

LIVE

Implementation Board

Jira-style Epic to Story to Task board. Every spec is a task card. Copy as AI prompt with one click. Drag to update status.

SOON

Phase 3 — Code Generation

Atomic specs to working code. Each spec generates one file. AI bound by the spec — no drift, no assumptions, no invented logic.

SOON

Hosted Platform

MyAgenticPlatform as a web product. No local setup required. Brief in, specs out. Join the waitlist below for early access.

PLANNED

MAP Spec Validator CLI

Free open-source CLI. Run map-spec validate on any project. Check completeness and consistency before a line of code runs.

FAQ

Common questions.
Straight answers.

What is MAP Spec?

+
MAP Spec is an open YAML-based standard for writing software specifications that AI models consume without making assumptions. It defines 7 layers — meta, functional, api, data, ui, rules, and quality — forming a complete, unambiguous contract. Any AI model that reads a MAP Spec file knows exactly what to build and what constraints to follow.

How is MAP Spec different from OpenAPI or Swagger?

+
OpenAPI only covers API endpoints. MAP Spec covers the entire software contract — database schema, UI components, business rules, acceptance criteria, and test cases. It's designed specifically for AI consumption with mandatory aiInstruction fields on critical rules. OpenAPI tells you what an API does. MAP Spec tells an AI how to build the whole system.

What is AI drift and why does it matter?

+
AI drift happens when a language model makes micro-decisions you didn't specify — choosing MySQL when you wanted PostgreSQL, using MD5 instead of bcrypt, hard-deleting user records, or inventing tables you never asked for. MAP Spec eliminates drift by giving AI a complete contract with zero ambiguity. If it's not in the spec, AI doesn't build it.

What are Atomic Specs?

+
Atomic Specs (MAP Spec v1.1.0) break each layer into the smallest possible files — one file per endpoint, one per database table, one per UI component. When an AI generates code from a single atomic spec, it has no context about anything else. No cross-contamination. No drift. Even the weakest model follows it correctly.

Is MAP Spec free to use?

+
Yes. The MAP Spec standard is MIT licensed — free to read, implement, and build tools around forever. MyAgenticPlatform currently requires local GitHub setup. A hosted platform with free and paid tiers is coming — join the waitlist below.

Do I need to know YAML or code?

+
No. MyAgenticPlatform generates all MAP Spec files automatically from a plain English brief. You describe your product, 6 agents generate the artifacts, and 7 spec-writers produce the YAML. You can read and review the specs but never need to write YAML yourself.

Can I try MyAgenticPlatform right now?

+
Yes, but it requires local setup. Clone the repo from GitHub, add your Anthropic API key, and run it locally. A hosted web platform with no setup required is in development — join the waitlist to be first when it launches.

Can I contribute to MAP Spec?

+
Absolutely. MAP Spec is open source on GitHub. You can propose changes to the standard, submit example projects, build validators, or create tools that consume MAP Spec. See the Contributing guide in the repo.
Articles

Read the standard.

View on GitHub
STANDARD · docs/STANDARD.md · 15 min read

The MAP Spec v1.0.0 Standard

All 7 layers defined. Every field explained. AI consumption rules and validation requirements for spec-driven development.

Read the standard
GUIDE · docs/ATOMIC.md · 12 min read

Atomic Specs — MAP Spec v1.1.0

One file. One concern. Zero ambiguity. How Atomic Specs eliminate AI drift through minimal-context specification files.

Read the guide
COMING SOON · dev.to

Why AI-Generated Code Drifts

The root cause of AI drift, why vague prompts fail, and how specification-driven development fixes it permanently.

Coming soon
EARLY ACCESS

Get early access to the hosted platform

MyAgenticPlatform is currently local-setup only. Join the waitlist for the hosted version — brief in, specs out, no terminal required.

You're on the list. We'll be in touch when early access opens.

No spam. Unsubscribe any time. contact@mapspec.io