SPECial

1. Overview

SPECial is a lightweight specification standard. It provides a style guide, a file structure, and an operational pipeline that help human and LLM agents manage context, navigate documentation, and keep specifications consistent with code.

1.1. When to use SPECial

Use SPECial when you have non-trivial amount of interconnected domains that need documentation and are subject to modification over time. SPECial is specifically optimised towards projects that employ LLM agents as active contributors / maintainers, but it is perfectly suitable for human-only usage.

SPECial's main implementation uses Markdown files as a basis of its file structure. You can use other file formats provided you have some metadata storage solution (either built-in into the file format, or external).

2. Quickstart

2.1. Add your domain files

Create an L0 file for each major domain in your project. The file name prefix encodes its scope level.

docs/
  L0-auth.md        # context & motivation for the auth domain
  L0-payments.md    # context & motivation for payments

Each file requires frontmatter with at minimum scope, summary, modified, and reviewed.

---
scope: L0
summary: "Auth domain — purpose, constraints, and threat model"
modified: 2026-01-05
reviewed: 2026-01-05
---

Add deeper files as the domain grows: L1- for contracts and invariants, L2- for structure and flows, L3- for implementation details. See Scope for the full description.

2.2. Link files with depends and dependents

When changes to file X can make file Y stale, declare the relationship in Y's frontmatter.

# docs/L1-auth.md
---
scope: L1
summary: "Auth contracts and session invariants"
modified: 2026-01-05
reviewed: 2026-01-05
depends:
  - path: docs/L0-auth
---

Add the matching dependents entry in docs/L0-auth.md pointing back to docs/L1-auth. SPECial uses this graph to surface potentially stale files: if L0-auth is modified after L1-auth was last reviewed, L1-auth is flagged for verification. See File structure for the full staleness rules and shorthand syntax.

2.3. What next?

The full standard is covered across three L0 documents. File structure goes deeper on frontmatter, scope levels, and the staleness mechanism you saw in step 2.2. Project structure covers configuration and path resolution if you need to customise the layout. Documentation style covers writing conventions for the file bodies themselves.

To make specs testable, see Assertions — a mechanism for declaring verifiable claims in specs and linking them to tests. For AI agent integration, see Agent setup.

---

SPECial was designed by Theo Ryzhenkov and is distributed under MIT license. Documentation for SPECial follows SPECial standard.