Format reference

The Specifica format

An open format for writing specs in a Git repository, as plain GitHub-flavored markdown that people review and AI coding agents build from. MIT-licensed, maintained by Cognium Labs. Status: release candidate (v1.0-rc).

Directory structure

.specifica/              ← the root (configurable)
├── principles.md        ← rules for the whole project
├── mvp/                 ← one folder per item
│   ├── spec.md          ← what
│   ├── design.md        ← how
│   └── tasks.md         ← the work
└── connect-repo/
    ├── spec.md
    └── tasks.md

Root: .specifica/ by convention; any directory name works.
principles.md at the root holds context for the whole project: values, constraints, style, things to always or never do.
Item folders are kebab-case and name the item: a release (mvp, 0.1), a feature (auth), a migration (typescript-migration), or anything else.
Files are optional. Include only what an item needs: a simple list is one tasks.md; a feature is all three.
Extra files are fine. Tools preserve files they do not know.

The files

spec.md What

What the item must do: requirements and edge cases. Each requirement is one testable behaviour, written as a checkbox.

## Requirements

- [ ] A user adds a contact with a name, email and company.
- [ ] Expired token → show "Re-authenticate".

## Edge Cases

- Two contacts with the same email → the second is refused.

design.md How

How it is put together: data, flows, components and the key decisions, with the reason for each. Diagrams can be Mermaid code blocks.

## Key Decisions

1. Token in KV, not a cookie: never expose the token client-side.

tasks.md The work

The build order as a checklist. This is the one file tools read and write programmatically: - [ ] and - [x] lines parse to structured tasks.

- [x] Data model: contacts and deals
- [ ] Contacts: add, edit, search

Conventions

Standard GFM, no custom syntax

If GitHub renders it, it is valid. No preprocessor, no build step.

Requirements are checkboxes

Each one a single testable behaviour. "Good error handling" is too vague; "Use Zustand" is implementation and belongs in design.md.

Edge cases are compact

Scenario → outcome pairs. Failure modes, not stories.

Design docs explain why

Decisions carry their reasoning. Keep every file short enough to read whole.

Packages

Two open-source TypeScript packages on npm.

`@specifica/format`

Parse and serialize the format; no dependencies. parse, serialize, parseTasks, serializeTasks, validate.

`@specifica/store`

A StorageAdapter interface (items, content, tasks, memory, chat, git sync) to implement on any backend.

npm install @specifica/format @specifica/store

Five rules

The repo is the source of truth. Every item is markdown files in a directory; clone the repo and you have everything.
Standard markdown. GitHub-flavored, no custom syntax.
Three files, all optional. Spec (what), design (how), tasks (work).
Opinionated structure. One layout, kebab-case folders: constraints remove decisions that do not matter.
Tool-agnostic. Any editor, any Git workflow, any CI. Tools enhance the format; they do not own it.

Get started

$ mkdir -p .specifica/mvp
$ touch .specifica/principles.md .specifica/mvp/{spec,design,tasks}.md
$ git add .specifica && git commit -m "docs: start a specifica spec"

Or draft one by chatting in the playground, then download it or copy it for your coding agent.

Try the playground →