Three files. Any item. Your repo.

A structured markdown format for Git. Describe what needs to happen, how it works, and what to do next — as files in a directory. Software specs, personal plans, or team workflows.

v1.0-rc · GFM compatible · Tool-agnostic · @specifica/format
Software development
.specifica/
├── principles.md

├── auth/
│   ├── spec.md    ← requirements, edge cases
│   ├── design.md  ← architecture, decisions
│   └── tasks.md   ← implementation steps

├── connect-repo/
│   ├── spec.md
│   ├── design.md
│   └── tasks.md

└── commit-flow/
    ├── spec.md
    └── tasks.md
Personal planning
.clove/
├── principles.md  ← preferences, context

├── plan-saras-birthday/
│   ├── spec.md    ← 12 people, surprise, budget
│   ├── design.md  ← Rosewood, don't invite Mike
│   └── tasks.md   ← venue, guests, invitations

├── weekly-groceries/
│   └── tasks.md   ← just a list

└── morning-routine/
    ├── spec.md
    └── tasks.md
The format

What, how, work.

Every item — a feature, a plan, a process — decomposes the same way. Three files, three concerns. All optional. Use what you need.

spec.md

The What

Intent, constraints, scope

What needs to happen and why. Requirements as checkboxes. Edge cases at the end.

# GitHub Auth

Users sign in with GitHub OAuth.

- [ ] "Sign in with GitHub" button
- [ ] OAuth requests `repo` scope
- [ ] Redirect to `/dashboard`
- [ ] Expired token → re-auth prompt

**Edge cases:** User revokes
OAuth app → re-auth prompt.
design.md

The How

Decisions and reasoning

How it works and why. Architecture, data model, key decisions with context.

# Auth — Design

## Flow
Browser → /auth/github → 302
GitHub → /callback?code=xxx
Worker → encrypt → KV → cookie

## Key Decisions
1. Token in KV, not cookie
2. 8h TTL — security vs friction
3. `repo` scope — private access
tasks.md

The Work

Ordered, flat, checkable

A checklist ordered by dependency. The only file with machine-readable state.

# Auth — Tasks

- [ ] Create GitHub OAuth App
- [ ] Implement `/auth/github`
- [x] Implement `/auth/callback`
- [x] Upsert user in D1
- [ ] Implement `/auth/logout`
- [ ] Auth middleware
- [ ] Handle expired token
- [ ] D1 migration: `users`
Use cases

Same structure, different domains.

All three files are optional. A complex feature uses all three. A weekly standup prep uses two. A grocery run is one file.

Software development

Feature specification

Requirements, architecture, and implementation steps for a software feature.
spec.mddesign.mdtasks.md
auth/
├── spec.md    ← OAuth flow, edge cases
├── design.md  ← KV tokens, session cookie
└── tasks.md   ← 9 ordered steps
Work at office

Team process

A repeating workflow with context and a checklist. Onboarding, standup prep, release process.
spec.mddesign.mdtasks.md
new-hire-onboarding/
├── spec.md    ← goals, timeline, who's involved
└── tasks.md   ← accounts, access, meetings…
Personal

Life planning

A project with intent, key decisions, and steps. Or just a checklist — your call.
spec.mddesign.mdtasks.md
plan-saras-birthday/
├── spec.md    ← 12 people, surprise, budget
├── design.md  ← Rosewood, don't invite Mike
└── tasks.md   ← venue, guests, cake
Directory structure

One root. Item folders inside.

Root directory is configurable — .specifica/ for software, .clove/ for personal, or anything else. A principles.md at the root provides context. One folder per item.

.specifica/  ← configurable

├── principles.md

├── auth/
│   ├── spec.md
│   ├── design.md
│   └── tasks.md

├── connect-repo/
│   ├── spec.md
│   └── tasks.md

└── weekly-groceries/
    └── tasks.md

principles.md

Context for the whole project or user. Project-level: values and constraints. User-level: preferences and memory.

Item folders

Kebab-case names that describe the item — auth, plan-saras-birthday, new-hire-onboarding.

Files are optional

Include only what the item needs. A simple list is one file. A complex feature is three.

Extra files are fine

Need an architecture.md at root? Add it. The convention is a guide, not a gate.

Conventions

Standard GFM. No custom syntax.

GitHub-Flavored Markdown. No preprocessors. If GitHub renders it, it's valid.

Requirements are checkboxes

Each one is a single, testable behavior.

- [ ] Expired token → show "Re-authenticate"
- [ ] Commit button shows pending changes badge
────
- [ ] Good error handling  ← too vague
- [ ] Use Zustand for state  ← implementation

tasks.md is machine-readable

Checkboxes parse to structured data. The one file tools can read and write programmatically.

- [x] Pick venue          ← done: true
- [x] Build guest list    ← done: true
- [ ] Send invitations    ← done: false
- [ ] Order cake          ← done: false

Edge cases are compact

Scenario → outcome pairs. Failure modes, not stories.

**Edge cases:** User revokes OAuth
app → re-auth prompt. User has no
repos → empty state. Token expires
mid-edit → preserve draft.

Design docs explain why

Key Decisions carry reasoning, not just choices.

## Key Decisions

1. Token in KV, not cookie
   — never expose token client-side
2. Surprise party
   — Sara checks her email constantly
Packages

Parse it. Store it. Build on it.

Two open-source npm packages. The parser reads and writes the format. The store defines a standard interface for any backend — implement it with SQLite, filesystem, PostgreSQL, or anything else.

Open source
Pure TypeScript parser and serializer. No dependencies. Reads and writes the three-file format.
parseTasks(md) → Task[]
serializeTasks(tasks) → string
parse(spec?, design?, tasks?) → Item
serialize(item) → { spec, design, tasks }
validate(files) → { valid, errors }
Open source
StorageAdapter interface. Items, content, tasks, memory, chat, git sync. Implement it with any backend.
interface StorageAdapter
createItem(title, type?) → Item
getContent(itemId) → { spec, design, tasks }
updateTaskStatus(id, order, done)
addMemory(category, key, value)
syncToGit(itemId)
Principles

Five rules.

01
Repo is source of truth
Every item is markdown files in a directory. No database owns the content. Clone the repo and you have everything.
02
Standard markdown
GitHub-Flavored Markdown. No custom syntax, no preprocessor, no build step.
03
Three files, all optional
Spec (what), design (how), tasks (work). Use all three or just one. The format adapts to the item.
04
Opinionated structure
One directory layout. Kebab-case folders. Constraints eliminate decisions that don't matter.
05
Tool-agnostic
Works with any editor, any Git workflow, any CI pipeline. Tooling enhances the format — it doesn't own it.

Start with mkdir

Create the directory, add your first item, commit. Or use the editor for a web UI.

$ mkdir -p .specifica/auth
$ touch .specifica/auth/{spec,design,tasks}.md
$ git add .specifica/ && git commit -m "docs: init specifica"

# or install the packages
$ npm install @specifica/format @specifica/store