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.
.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
.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
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 weekly standup prep uses two. A grocery run is one file.
auth/ ├── spec.md ← OAuth flow, edge cases ├── design.md ← KV tokens, session cookie └── tasks.md ← 9 ordered steps
new-hire-onboarding/ ├── spec.md ← goals, timeline, who's involved └── tasks.md ← accounts, access, meetings…
plan-saras-birthday/ ├── spec.md ← 12 people, surprise, budget ├── design.md ← Rosewood, don't invite Mike └── tasks.md ← venue, guests, cake
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. 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