Skip to content

Why SpecBase? The Spec Oracle for AI Agents and Developers

The Problem

You start a new project. Maybe it’s a backend service, a CLI tool, or a video game. You know you need documentation — but what documentation?

Every experienced engineer has learned this the hard way: three months in, you realize you never wrote an API versioning spec. Six months in, the team discovers there’s no incident response runbook. A year in, someone asks “where’s our architecture decision log?” and the answer is a Slack thread from April.

The knowledge of “what documents a project needs” lives in senior engineers’ heads. It’s tribal knowledge, passed down through code reviews and postmortems. It’s never been systematized — until now.

What SpecBase Does

SpecBase is a spec oracle: you tell it your project type and features, and it instantly returns:

  1. A prioritized list of required documents — what you need to write, with P0/P1/P2 priority levels.
  2. Rationale — why each document matters, tied to the specific project type.
  3. A system prompt — paste it into your AI coding agent to give it project awareness.
  4. A checklist — track progress as you write each spec.
  5. Starter templates — Markdown stubs so you’re never staring at a blank page.

For example, a “video game with multiplayer support” needs 30+ documents: Game Design Document, Networking Architecture, Anti-Cheat Design, Latency Budget, Matchmaking Spec, and more. SpecBase knows this because it encodes 11 software archetypes with feature-variant rules into an extensible knowledge base.

Agent-Native from Day One

SpecBase isn’t just a CLI tool or a website. It’s built for AI agents.

Through MCP (Model Context Protocol), your AI coding agent — Claude Code, GitHub Copilot, Cursor, or any MCP-compatible tool — can connect to SpecBase and call get_standard_docs() programmatically. The agent gets structured JSON back, which it can use to:

  • Bootstrap a new project with the right documentation structure.
  • Audit an existing project against the spec checklist.
  • Generate system prompts that give the agent deep project context.

No copy-paste. No context switching. The agent knows what docs are needed and can start writing them.

How It Works

SpecBase’s knowledge base is a YAML ontology of 11 software archetypes:

  • Web App · Backend Service · CLI Tool · Desktop App · Mobile App
  • Embedded/IoT · Data Pipeline · AI/ML System · Video Game
  • DevOps Platform · Library/Framework

Each archetype has base documents (always required) and features (optional modifiers like auth, multiplayer, gdpr, streaming). Features can add documents, imply other features, and even conflict with each other.

The composition algorithm resolves all of this deterministically: given an archetype and a set of features, the output is always the same. This algorithm runs identically in Go (for the CLI and MCP server) and JavaScript (for the web runner), verified by a parity test that checks 31 input combinations on every CI run.

Three Ways to Use It

  1. CLI — specbase query <type> --features f1,f2 --format table|json|prompt
  2. Web Runner — interactive browser UI at specbase.net/runner
  3. MCP — specbase mcp --transport stdio or connect to mcp.specbase.net

All three produce identical output from the same knowledge base.

Open Source, Free, No Telemetry

SpecBase is free and open source:

  • Code: Apache-2.0
  • Knowledge base: CC-BY-4.0
  • Templates: CC0-1.0 (public domain — use them however you want)

There is no telemetry. No analytics in the binary. No “phone home” logic. The CLI works fully offline. Your project details stay on your machine.

Get Started

# Install
go install github.com/aallbrig/specbase@latest

# Query
specbase query web_app --features auth,i18n --format table

# Or use with your AI agent via MCP
specbase mcp --transport stdio

Or try the interactive runner right now — no installation required.

Browse the Document Library to see all 214 specification documents across all archetypes.

What’s Next

SpecBase v1.0 ships with 11 archetypes and 214 documents. The knowledge base is designed to be extensible — community contributions of new archetypes and documents are welcome.

We’re also working on:

  • Remote MCP service at mcp.specbase.net for zero-install agent integration
  • Additional archetypes based on community feedback
  • Deeper agent integrations (auto-generation of full spec drafts)

Follow the project on GitHub and join the conversation.