Specs

Specs are the technical and design contracts a project promises to honor. They live in docs/specs/ and are read by reviewers, audits, and humans alike. Unlike the plan, specs change rarely — they're the rules the plan must respect.

#What a spec is

A spec captures how something must be done — design tokens, SLO targets, security boundaries, naming conventions — at a level of detail that lets a reviewer say "this code violates section 4.2." Specs are reference material, not narrative documents.

A good spec is:

• Stable — it changes infrequently. If a rule needs to bend per-task, it shouldn't be in a spec.
• Inspectable — every claim is anchored. "Color tokens are listed in Table 3" not "use brand colors."
• Testable — wherever possible, an audit script or reviewer can mechanically check compliance.

Specs that fail one of these qualities tend to drift into stale lore. The remedy is usually to delete the rule rather than to keep documenting it.

#Common specs

#Design system spec

design_system.spec_path (default: docs/specs/design-system.md) is the canonical reference for tokens, components, and patterns. The Design System Agent reads it during /synthex:design-system-audit/synthex:design-system-audit to flag drift; the code reviewer cross-references it during /synthex:review-code/synthex:review-code for any UI-touching diff.

A design-system spec typically contains:

• Tokens — colors, typography, spacing, radius, motion. Each with hex/px values and intended use.
• Components — primitives the codebase ships, with API shape and composition rules.
• Forbidden combinations — pairs that fail accessibility (contrast below threshold), or patterns that cause regressions.

#SLO / reliability spec

reliability.slo_document (default: docs/specs/slos.md) declares the service-level objectives a project commits to: availability, latency, error rates, with measurement windows. The SRE Agent reads it during /synthex:reliability-review/synthex:reliability-review to assess whether proposed changes risk exceeding the error budget.

#Domain-specific specs

Projects often ship additional specs as constraints emerge:

• docs/specs/security.md — threat model, secret-handling rules, dependency policy.
• docs/specs/compliance.md — regulatory requirements (GDPR, SOC 2, HIPAA scope).
• docs/specs/performance.md — bundle-size budgets, runtime budgets, benchmark thresholds.

code_review.spec_paths in .synthex/config.yaml lists the directories the code reviewer scans for compliance checks. Adding a new spec to that list automatically subjects future code reviews to its constraints.

#Specs vs. ADRs vs. RFCs

The three artifact types are easy to confuse:

A simple flow: an idea ships as an RFC → it gets accepted and the decision is recorded as an ADR → the rule it establishes lands in the relevant spec → reviewers enforce it from then on.

#Where specs live

The default paths in .synthex/config.yaml:

documents:
  specs: docs/specs

design_system:
  spec_path: docs/specs/design-system.md

reliability:
  slo_document: docs/specs/slos.md

code_review:
  spec_paths:
    - docs/specs

Override these per project as needed. The conventions are deliberately conservative — most projects keep everything under docs/specs/ and customize only the file names.

#Next

• ADRs — record the decisions that established your specs
• RFCs — propose changes to specs when they're material
• Plugin architecture — Synthex's own plugin spec