# The Specifica format

Specifica is an open format for writing specs in a Git repository, as plain GitHub-flavored markdown that people review and AI coding agents build from. It is MIT-licensed and 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.

```markdown
## 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.

```markdown
## 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.

```markdown
- [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 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.
- **Design docs explain why:** decisions carry their reasoning.
- **Keep files short** so a person and an agent can read each one whole (the playground warns past 100 lines).

## Packages

Two open-source TypeScript packages on npm:

- **`@specifica/format`**: parse and serialize the format; no dependencies. `parse(spec?, design?, tasks?) → Item`, `serialize(item)`, `parseTasks(md) → Task[]`, `serializeTasks(tasks)`, `validate(files)`.
- **`@specifica/store`**: a `StorageAdapter` interface (items, content, tasks, memory, chat, git sync) to implement on any backend.

```bash
npm install @specifica/format @specifica/store
```

## Five rules

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

## Get started

```bash
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 (https://specifica-playground.pages.dev/), then download it or copy it for your coding agent.

Source: https://github.com/cogniumhq/specifica · Site: https://specifica.org