◇ Open Standard · v1.0

OpenSpec

The open specification format for AI agent orchestration. A versioned, tool-agnostic format describing software projects as hierarchical specs that any compliant agent can execute.

Think OpenAPI, but for agent orchestration instead of REST APIs.

Quick Install

$ npm install -g @blacksmithers/openspec

Data Hierarchy

Project→ root container

├─Specification→ feature or module

├─Epic→ work group

└─Ticket→ atomic unit of work

The Core Insight

Traditional tickets say what. OpenSpec tickets say what, where, how, and how to verify. Every field exists because its absence caused a real failure in production AI agent orchestration.

Human Ticket vs. Agent Ticket

Traditional Ticket

Title Add user authentication

Desc Implement JWT-based auth with login/register endpoints

Points 5

OpenSpec Ticket

{
  "implementation": {
    "filesToCreate": ["src/middleware/auth.ts"],
    "filesToModify": ["src/routes/index.ts"]
  },
  "codeReferences": [{ "name": "JwtConfig", ... }],
  "typeReferences": [{ "name": "UserDocument", ... }],
  "dependencies": [{ "type": "requires", ... }]
}

See the full comparison and 8 lessons →

◆

Why This Format

Eight lessons from 400+ builds. Every field exists because its absence caused a real failure.

▷

Getting Started

Write, validate, and use an OpenSpec in five minutes. No account required.

⬡

Schema Explorer

Browse every entity and field in the format with types, requirements, and descriptions.

⌘

Live Editor

Paste or write a spec file and validate it in real-time against the v1.0 schema.

◈

Three Formats

JSON for machines, YAML for humans, TOON for LLMs. All lossless representations of one schema.

▸

Offline Validator

npm package that validates specs locally. Zero auth, zero SaaS dependency.

◇

Schema URL (permanent)

https://openspec.tech/schema/v1.0/openspec-schema.json

OpenSpec is an open specification. Any tool can generate, validate, and consume .oschema.json files. The format belongs to the ecosystem.