Standards Framework

This is not a field notebook. These are normative governance documents. Standards are prescriptive, enforceable, and undated — they represent current truth, not historical entries. Every standard defines compliance criteria that a reader (human or AI agent) can evaluate as pass/fail.

Standards vs Patterns vs Codex

Three systems, three purposes. Confusing them weakens all three.

Attribute Standard Pattern Codex

Voice

Prescriptive ("MUST")

Descriptive ("when I hit X…​")

Referential ("syntax is…​")

Temporality

Undated — current truth

Dated entries with context

Rarely changes

Scope

Cross-domain, enforceable

Single domain, experiential

Single tool, lookup

Audience

Humans AND AI agents

Humans reviewing experience

Humans needing syntax

Change process

Versioned, lifecycle-managed

Append new entries

Update when tool changes

Location

standards/

patterns/

codex/

Question answered

"What MUST I do?"

"What has worked before?"

"How does this tool work?"

What Makes a Standard

A document is a standard if ALL of these are true:

  1. It uses normative language — MUST, MUST NOT, SHALL, SHOULD, MAY per RFC 2119

  2. It defines compliance criteria — a reader can determine pass/fail

  3. It applies across projects and contexts — not specific to one deployment

  4. It has an owner responsible for maintenance

  5. It is referenced as authority — by humans, CLAUDE.md files, or AI agents

If a document describes what worked but doesn’t prescribe what must be done, it is a pattern, not a standard.

RFC 2119 Keywords

Standards use precise normative language. These keywords have specific meanings:

Keyword Meaning

MUST / SHALL

Absolute requirement. No exceptions without a documented, approved deviation.

MUST NOT / SHALL NOT

Absolute prohibition.

SHOULD / RECOMMENDED

There may exist valid reasons to ignore this requirement, but the full implications must be understood and carefully weighed.

SHOULD NOT / NOT RECOMMENDED

There may exist valid reasons when the behavior is acceptable, but the implications should be understood.

MAY / OPTIONAL

Truly optional. Implementations that include this and those that omit it are both compliant.

Standard Lifecycle

Every standard has a lifecycle status tracked via the :std-status: attribute:

Status Meaning Action Required

Draft

Proposed, under review. Not yet enforceable.

Review, refine, test compliance criteria.

Active

Current, enforceable. CLAUDE.md files and agents reference it.

Follow it. Violations require documented exceptions.

Superseded

Replaced by a newer version. Retained for audit trail.

Follow the replacement. Reference old version only for history.

Retired

No longer applicable. Retained for historical record.

None. Do not enforce.

Transitions: Draft → Active (upon first enforcement). Active → Superseded (when replaced). Active → Retired (when no longer applicable).

Machine-Parseable Attributes

Every standard document includes these attributes for AI agent and script consumption:

:std-id: STD-NNN
:std-status: Draft | Active | Superseded | Retired
:std-domain: operations | documentation | security | ai-interaction | infrastructure | workflow
:std-owner: {author}

Enumeration: grep -r ':std-status: Active' pages/standards/ returns all enforceable standards.

Stable reference: CLAUDE.md files reference STD-001, not file paths. The Registry maps IDs to current locations.

How to Write a Standard

  1. Start from TEMPLATE-standard.adoc

  2. Assign the next sequential STD-NNN ID (check the Registry for the current maximum)

  3. Write requirements using RFC 2119 keywords — every requirement MUST be independently testable

  4. Define compliance criteria — a reader MUST be able to determine pass/fail from the Compliance section alone

  5. Set :std-status: Draft initially

  6. Add to the Registry

  7. Add to the appropriate domain index.adoc and partials/nav/standards.adoc

  8. Promote to Active when first enforced

Domains

Standards are organized by domain. New domains are added when their first standard is written.

Domain Scope

Operations

Deployment validation (STD-002), change control (STD-005), RCA (STD-010), incident response (STD-011), runbook structure (STD-012), case studies taxonomy (STD-013)

Documentation

Project structure (STD-001), file naming (STD-003), AsciiDoc conventions (STD-004), repository architecture (STD-009), worklog system (STD-014), Antora attributes (STD-015), codex format (STD-016), portfolio format (STD-017), training curriculum (STD-018), discoveries lifecycle (STD-019), diagram catalog (STD-020)

Security

Secrets handling (STD-006)

AI Interaction

Delegation boundary (STD-007)

Workflow

CLI quality (STD-008)

Infrastructure

Deployment checklists, system baselines (seeded when first standard written)

Communication

Rhetoric, professional writing (seeded when first standard written)

Relationship to CLAUDE.md

Standards are the source of truth. CLAUDE.md files are enforcement mechanisms.

Standards CLAUDE.md

Define the rule, rationale, and compliance criteria

Apply rules to a specific repository context

Live in pages/standards/

Live in .claude/CLAUDE.md (repo) or ~/.claude/CLAUDE.md (global)

Audience: anyone (human, AI, audit)

Audience: AI agents operating in the repo

Change via lifecycle (Draft → Active)

Updated to reference standards by ID

When a CLAUDE.md rule and a standard conflict, the standard wins. The CLAUDE.md is updated to match.

Registry

Full Standards Registry — the single lookup point for all standards, including those not yet migrated to this section.

Related