Specifica

Specifica is a markdown format designed to bring clear structure and consistency to software specifications, technical migrations, API designs, and team workflows. It addresses the challenge of scattered, ambiguous documentation by organizing project information into human-readable, version-controlled markdown files within a Git repository. The format is compatible with GitHub-Flavored Markdown (GFM), allowing teams to work in any editor and maintain readability across platforms like GitHub, VS Code, or the terminal.

At the core of Specifica’s approach is a convention of three optional files per item—spec.md for requirements and edge cases, design.md for architectural decisions and reasoning, and tasks.md for implementation steps. This separation enforces clarity by distinguishing what needs to happen, how it should be accomplished, and the actionable steps required. Requirements are written as checkboxes for testable behaviors, and tasks.md provides a machine-readable checklist that tools and AI systems can parse, validate, and update programmatically. The format is tool-agnostic, with no proprietary syntax, build tools, or lock-in, and allows teams to include only the files relevant to their workflow or feature.

The directory structure is flexible: a configurable root directory (such as .specifica/) contains item folders named in kebab-case, each holding the relevant markdown files. A principles.md file at the root can capture project-wide values, constraints, or user preferences, while additional files can be added as needed. This structure supports both complex features requiring all three files and simpler tasks that may need only one, accommodating a range of use cases from feature specification to technical migration tracking.

Specifica is optimized for both human and AI collaboration. Its consistent, standard markdown structure provides clear context for large language models, enabling automation and integration with a broader tooling ecosystem. The format supports npm packages for parsing and serialization, storage adapters for different backends, CLI tools for validation and migration, and web editors with AI assistance. By focusing on clarity, machine-readability, and flexibility, Specifica aims to make software documentation actionable and accessible for both teams and automated systems.