Skip to content

STD-GEN-001: Standards & Practices Framework

1. Context

To maintain a high-quality, scalable system, we must consolidate fragmented rules into a cohesive "Law Library". This Meta-Standard defines how to create, name, and manage Standards & Practices within the Singular Dream platform. it establishes the "Atomic Library" pattern.

2. The Standard (The Floor)

  • [MUST] Naming Convention: Files MUST follow the pattern STD-<CATEGORY>-<ID>_<TITLE_SLUG>.md.
  • [MUST] Human Readability: The TITLE_SLUG MUST be a descriptive identifier (e.g., the_warp_drive_principle) to enable visual scanning by humans. Random IDs or opaque slugs are prohibited.
  • [MUST] Primary Title: Every standard MUST contain a H1 title that exactly matches or describes the filename slug.
  • [MUST] Pedagogical Verbosity: Documentation MUST air on the side of being more verbose. It MUST explain not only What the standard is, but Why it exists (Rationale) and How it is to be implemented (Guidance). This serves the education of humans and the precise guidance of AI agents.

3. Best Practices (The Path)

  • [SHOULD] Use the Template: All new standards SHOULD follow the structure defined in Figure 1 (Context -> Standard -> Practices -> Exceptions).
  • [SHOULD] Colocate Archives: When deprecating, move the old file to 02_standards/archive/ and append the version/date to the filename.
  • [SHOULD] Differentiate Types: Explicitly label rules as [MUST] (Standard) or [SHOULD] (Practice).

4. The Taxonomy (Categories)

The following prefixes are reserved. New prefixes must be added to .categories.json.

Code Category Focus
ARC Architecture Structural patterns, blueprints.
COD Coding Syntax, linting, testing.
OPS Operations Infrastructure, security.
GOV Governance Decisions, policy, roles.
CMP Compliance Legal, audit.
TEC Technology Stack, tooling, choices.
PRD Product Requirements, personas.
DEV Development Workflow, Git, Commits.
DAT Data Schemas, seeding, ingestion.
GEN General Meta-standards.

5. The Template (Figure 1)

---
id: STD-CAT-000
title: Example Standard
category: Category Name
status: Active
tags: [tag1, tag2]
---

# STD-CAT-000: Example Standard

## 1. Context

Why does this exist?

## 2. The Standard (The Floor)

- **[MUST] rule_1**: Strict requirement.

## 3. Best Practices (The Path)

- **[SHOULD] practice_1**: Recommendation.

## 4. Exceptions

When to deviate?

## 5. Version History

| Version | Date       | Author | Change  |
| :------ | :--------- | :----- | :------ |
| 1.0     | 2026-01-01 | User   | Initial |

6. Exceptions

  • Proposals: Draft proposals may reside in documentation/04_development/proposals/ until ratified as Standards.
  • .cursorrules: System-prompt instructions for AI are "High-Cardinality" rules that may duplicate Standards for operational efficiency (Token Context). They should align with, but are distinct from, the Documentation Standards.

Appendix: Framework Analysis

Assessment of the Flat Library Approach

Strengths

  1. Refactor-Proof: Renaming categories doesn't break relative links (../../).
  2. AI Compatibility: Regex-friendly naming (STD-*) makes it easy for Agents to "Learn the Law".
  3. Single Source of Truth: Eliminates "drift" between Policies and Manuals.
  4. Extensible: Adding STD-AI is trivial (JSON entry + File), no folder restructure needed.

Drawbacks & Mitigations

  1. Visual Noise: 100+ files can be overwhelming.
    • Mitigation: Reliability on MkDocs and Metadata Tags to create "Virtual Folders" for human consumption.
  2. ID Management: Risk of ID collision.
    • Mitigation: Future implementation of a pnpm new:std script.
  3. Prefix Ambiguity: Overlap between categories (e.g., TEC vs SEC).
    • Mitigation: Use Tags for cross-cutting concerns.

Version History

Version Date Author Change
0.1.0 2026-01-26 Antigravity Initial Audit & Metadata Injection