Three files per item in your repo. Describe what needs to happen, how it works, and what to do next — as files in a directory. Software specs, API designs, technical migrations, or team workflows.
.specifica/ ├── principles.md ← project values, constraints │ ├── auth/ │ ├── spec.md ← requirements, edge cases │ ├── design.md ← architecture, decisions │ └── tasks.md ← implementation steps │ ├── connect-repo/ │ ├── spec.md │ ├── design.md │ └── tasks.md │ └── api-versioning/ ├── spec.md └── design.md
.specifica/ ├── principles.md ← contribution guidelines │ ├── plugin-system/ │ ├── spec.md ← plugin API requirements │ ├── design.md ← hooks, lifecycle, events │ └── tasks.md ← implementation checklist │ ├── typescript-migration/ │ ├── spec.md │ └── tasks.md ← file-by-file progress │ └── v2-breaking-changes/ ├── spec.md └── design.md
Software specs are scattered across docs, tickets, wikis, and Slack threads. Hard for humans to navigate. Impossible for AI to parse. Specifica gives both a structured home.
Plain markdown files in your Git repo. No proprietary formats, no build tools, no lock-in.
Consistent structure makes perfect context for LLMs. Machine-readable state enables automation.
spec.md for requirements contextdesign.md for architectural decisionstasks.md checkboxes programmaticallyThree files, three concerns. Constraints eliminate ambiguity and force intentional thinking.
Standard format unlocks a tooling ecosystem. Parsers, validators, editors, CI checks, sync tools.
Every item — a feature, a plan, a process — decomposes the same way. Three files, three concerns. All optional. Use what you need.
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.
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
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`
All three files are optional. A complex feature uses all three. A technical migration uses two. A simple bug fix uses one.
auth/ ├── spec.md ← OAuth flow, edge cases ├── design.md ← KV tokens, session cookie └── tasks.md ← 9 ordered steps
user-search-api/ ├── spec.md ← endpoints, params, responses ├── design.md ← indexing, pagination, filters └── tasks.md ← DB schema, handlers, tests
migrate-to-typescript/ ├── spec.md ← scope, goals, success criteria ├── design.md ← migration strategy, phases └── tasks.md ← file-by-file conversion list
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.mdContext for the whole project or user. Project-level: values and constraints. User-level: preferences and memory.
Kebab-case names that describe the item — auth, plan-saras-birthday, new-hire-onboarding.
Include only what the item needs. A simple list is one file. A complex feature is three.
Need an architecture.md at root? Add it. The convention is a guide, not a gate.
GitHub-Flavored Markdown. No preprocessors. If GitHub renders it, it's valid.
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
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
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.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
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.
parseTasks(md) → Task[] serializeTasks(tasks) → string parse(spec?, design?, tasks?) → Item serialize(item) → { spec, design, tasks } validate(files) → { valid, errors }
interface StorageAdapter createItem(title, type?) → Item getContent(itemId) → { spec, design, tasks } updateTaskStatus(id, order, done) addMemory(category, key, value) syncToGit(itemId)
mkdirCreate the directory, add your first item, commit. Three commands to get started.
$ 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