Specifica is a markdown format for writing software specifications. One directory, three file types per feature, zero configuration. Use any editor — or ours.
Specifica is a format, not a tool. It defines where specification files live in a repository, what files every feature includes, and how those files are structured. Standard markdown. Standard Git. No proprietary format, no lock-in, no build step.
Spec, design, tasks. What, how, work. Three audiences, three concerns, three files. Mixing them into one document is how specs become unreadable.
Requirements as checkboxes. Each one is a single, testable behavior. Edge cases at the end. Written for everyone — PM, designer, engineer.
Architecture, data model, API contracts, and key decisions. The reasoning behind choices, not just the choices. Written for engineers.
A flat checklist ordered by dependency. Each item is completable in a single PR. No nesting, no sub-items, no ambiguity about what's next.
Root-level files describe the project as a whole. Feature folders use kebab-case names and each contain the same three files. Extra files are fine — the convention is a guide, not a gate.
principles.md3–7 numbered constraints that guide every decision. These are rules, not aspirations. Each one should rule something out.
spec.md at rootThe project-level spec. Defines scope, success criteria, time appetite, and non-goals. The one document someone reads to understand the whole project.
feature/ foldersKebab-case names that describe the feature — auth, connect-repo, commit. Name the behavior, not the page or component.
Optional. Tag any H1 heading with [draft], [review], or [final] to signal where a spec is in its lifecycle.
Standard GitHub-Flavored Markdown. No custom syntax, no preprocessors. If GitHub renders it correctly, it's valid Specifica.
Each requirement is a GFM checkbox describing a single, testable behavior. If you can't verify it, it's not specific enough.
At the end of each section: bold label, then scenario → outcome pairs separated by periods. Not stories — failure modes.
Key Decisions sections carry the reasoning. "Token in KV, not cookie" isn't enough — say why. Future-you needs the context.
No nesting. Ordered by dependency — top items unblock bottom items. Each task is completable in a single PR or commit.
.md file in .specifica/. No external database, no SaaS platform, no proprietary format owns the content. Clone the repo and you have the specs.vim and git push.mkdirCreate the directory, add your first feature, commit. You're using Specifica. Or use the editor if you prefer a UI.