# Precepts

> Multi-discipline standards platform. Machine-readable standards for humans and AI agents.
> Standards are published as Markdown with YAML frontmatter, consumable by agents via MCP, llms.txt, and CLAUDE.md.

## Schema

Identifier pattern: [INTG|PRD|PRJ|UX|SEC]-[STD|GDL|GOV|BP]-NNN
Status values: DRAFT, MANDATORY, RECOMMENDED, DEPRECATED
Document types: standard, guideline, governance, best-practice
Domains: INTEGRATION, PRODUCT-MANAGEMENT, PROJECT-MANAGEMENT, UX, SECURITY
Version: semver (patch = typo fix, minor = new fields/status change, major = breaking)

## Disciplines

- [Integration Standards](https://docs.precepts.dev/integration/): API design, events, resilience, observability, data formats, naming, encoding, versioning
- [Product Management](https://docs.precepts.dev/product/): Requirements, roadmapping, prioritization guidelines
- [UX Standards](https://docs.precepts.dev/ux/): Accessibility, design systems, interaction patterns
- [Project Management](https://docs.precepts.dev/project-management/): Ceremonies, estimation, delivery practices

## Integration

- [INTG-BP-001 Webhook Design](https://docs.precepts.dev/integration/best-practices/webhook-design/) [DRAFT]: Webhooks are listed in appliesTo across nearly every integration standard — error handling, observability, resilience, retries — yet no document addresses webhook-specific design patterns.
- [INTG-BP-002 Rate Limiting and Throttling](https://docs.precepts.dev/integration/best-practices/rate-limiting/) [DRAFT]: Rate limiting is mentioned in INTG-STD-009 (HTTP 429 status code), INTG-STD-015 (429 triggers backoff for event delivery), and INTG-STD-016 (rate-limit response headers), but no document addresses rate-limiting strategy, quota design, or throttling patterns holistically.
- [INTG-GDL-001 Idempotency Design](https://docs.precepts.dev/integration/guidelines/idempotency/) [DRAFT]: Idempotency is referenced across multiple integration standards — INTG-STD-034 rejects "retry without idempotency guarantee on non-idempotent operations," and INTG-STD-015 permits event ID reuse for re-delivery — but no document defines how to implement idempotency.
- [INTG-GDL-002 API Versioning](https://docs.precepts.dev/integration/guidelines/api-versioning/) [DRAFT]: INTG-STD-006 establishes backward and forward compatibility rules — what constitutes a breaking change and how to evolve schemas without breaking consumers.
- [INTG-GOV-001 Integration Styles](https://docs.precepts.dev/integration/governance/integration-styles/) [MANDATORY]: Every service boundary is an integration contract.
- [INTG-STD-001 Date Format](https://docs.precepts.dev/integration/standards/data-formats/date-format/) [MANDATORY]: All date values transmitted across any interface MUST follow the ISO-8601 format.
- [INTG-STD-002 Date and Time](https://docs.precepts.dev/integration/standards/data-formats/datetime-formats/) [MANDATORY]: This standard defines the REQUIRED representation of date and time values exchanged across all integration boundaries.
- [INTG-STD-003 Money and Currency](https://docs.precepts.dev/integration/standards/data-formats/monetary-format/) [MANDATORY]: Monetary values represented as IEEE 754 floating-point numbers suffer from precision loss: 0.1 + 0.2 ≠ 0.3 in binary floating-point arithmetic.
- [INTG-STD-004 Integration Naming Conventions](https://docs.precepts.dev/integration/standards/foundational/naming-conventions/) [MANDATORY]: This standard defines MANDATORY naming conventions for all artifacts exchanged across integration boundaries - JSON fields, REST API paths, event types, queue topics, HTTP headers, enum values, query parameters, and file names.
- [INTG-STD-005 Character Encoding](https://docs.precepts.dev/integration/standards/data-formats/character-encoding/) [MANDATORY]: This standard defines the REQUIRED character encoding for all text data exchanged across integration boundaries.
- [INTG-STD-006 Backward and Forward Compatibility](https://docs.precepts.dev/integration/standards/versioning/backward-forward-compatibility/) [MANDATORY]: Integration contracts are long-lived shared agreements.
- [INTG-STD-008 API Resource Design and Naming](https://docs.precepts.dev/integration/standards/api/resource-design/) [MANDATORY]: This standard defines the required structure for RESTful API resources, URL paths, HTTP method usage, collection patterns, and operation semantics across all integration boundaries.
- [INTG-STD-009 API Error Handling](https://docs.precepts.dev/integration/standards/api/error-handling/) [MANDATORY]: All HTTP API error responses MUST use the RFC 9457 Problem Details format (application/problem+json).
- [INTG-STD-015 Event Envelope Standard](https://docs.precepts.dev/integration/standards/events/event-envelope/) [MANDATORY]: This standard mandates CloudEvents v1.0.2 as the universal event envelope for all events produced, consumed, or relayed across integration boundaries.
- [INTG-STD-016 HTTP Header Standards](https://docs.precepts.dev/integration/standards/api/http-headers/) [DRAFT]: HTTP headers carry essential metadata — correlation identifiers, content negotiation, caching directives, security controls, and rate-limit signals — yet no existing integration standard governs them holistically.
- [INTG-STD-018 Partial and Multi-Status Responses](https://docs.precepts.dev/integration/standards/api/partial-responses/) [DRAFT]: Many integration scenarios involve operations on multiple resources in a single request — batch imports, bulk updates, multi-entity deletions, or composite transactions.
- [INTG-STD-019 Pagination Standard](https://docs.precepts.dev/integration/standards/api/pagination/) [DRAFT]: INTG-STD-008 mandates that collection endpoints MUST support pagination (rejection criteria: "Missing pagination on collection endpoints") but prescribes no implementation rules.
- [INTG-STD-029 Integration Observability](https://docs.precepts.dev/integration/standards/observability/integration-observability/) [MANDATORY]: Every integration action - API call, event, file transfer, or agent handshake - MUST be traceable from origin to destination.
- [INTG-STD-033 Integration Resilience Patterns](https://docs.precepts.dev/integration/standards/resilience/integration-resilience-patterns/) [MANDATORY]: This standard defines MANDATORY resilience patterns for all integration points to ensure graceful degradation, automatic recovery, and full observability under failure.
- [INTG-STD-034 Retry Policy](https://docs.precepts.dev/integration/standards/resilience/retry-policy/) [MANDATORY]: Uncontrolled retries are a leading cause of cascading failures.
- [INTG-STD-035 Timeout Standard](https://docs.precepts.dev/integration/standards/resilience/timeout/) [MANDATORY]: Every external call - whether to an API, database, message broker, or file system - MUST have an explicit timeout.

## Product Management

- [PRD-GDL-001 Requirement Document](https://docs.precepts.dev/product/guidelines/requirement-document/) [DRAFT]

## UX

- [UX-BP-001 Dark Mode and Color Palette Design](https://docs.precepts.dev/ux/best-practices/design-tokens/) [RECOMMENDED]: This best practice document outlines RECOMMENDED practices for designing dark mode themes and constructing tokenized color systems.
- [UX-GDL-001 Mobile and Web Interaction Design](https://docs.precepts.dev/ux/guidelines/interaction/) [RECOMMENDED]: This guideline outlines RECOMMENDED interaction standards for mobile and web systems.
- [UX-STD-001 Accessibility and Assistive Technology](https://docs.precepts.dev/ux/standards/accessibility/) [MANDATORY]: This standard defines MANDATORY accessibility and assistive technology requirements across all user interfaces.

## Security

- [SEC-BP-001 Passkeys and Phishing-Resistant Authentication](https://docs.precepts.dev/security/best-practices/passkeys/) [RECOMMENDED]: This best practice document provides implementation guidance for passkeys (FIDO2/WebAuthn-based authentication) as the preferred phishing-resistant authentication method referenced in SEC-STD-001 R-1.
- [SEC-BP-002 Post-Quantum Cryptography Migration](https://docs.precepts.dev/security/best-practices/post-quantum-migration/) [RECOMMENDED]: This best practice document provides implementation guidance for migrating to post-quantum cryptography (PQC) algorithms.
- [SEC-GDL-001 Data Classification and Handling](https://docs.precepts.dev/security/guidelines/data-classification/) [MANDATORY]: This guideline defines a four-tier data classification framework for all data processed, stored, or transmitted by organization systems.
- [SEC-GDL-002 Security Configuration Hardening](https://docs.precepts.dev/security/guidelines/security-configuration/) [RECOMMENDED]: This guideline defines RECOMMENDED configuration hardening practices for HTTP services, containers, and infrastructure.
- [SEC-GDL-003 AI and LLM Application Security](https://docs.precepts.dev/security/guidelines/ai-llm-security/) [RECOMMENDED]: This guideline defines RECOMMENDED security practices for applications that integrate Large Language Models (LLMs) and AI systems.
- [SEC-GOV-000 Security Governance Framework](https://docs.precepts.dev/security/governance/governance-framework/) [MANDATORY]: This document establishes the governance meta-layer for the Precepts Security (SEC) domain.
- [SEC-GOV-001 Secure Software Development Lifecycle](https://docs.precepts.dev/security/governance/secure-sdlc/) [MANDATORY]: This document defines the mandatory security activities that MUST occur at each phase of the software development lifecycle (SDLC).
- [SEC-GOV-002 Zero Trust Architecture](https://docs.precepts.dev/security/governance/zero-trust/) [RECOMMENDED]: This governance document provides RECOMMENDED guidance for adopting Zero Trust Architecture (ZTA) principles.
- [SEC-GOV-003 Security Incident Response](https://docs.precepts.dev/security/governance/incident-response/) [MANDATORY]: This governance document defines MANDATORY requirements for the technical layer of security incident response: detection-to-escalation chains, incident classification, evidence preservation, regulatory notification timelines, and post-incident review.
- [SEC-GOV-004 Security Risk Assessment Framework](https://docs.precepts.dev/security/governance/risk-assessment/) [MANDATORY]: This governance document defines a MANDATORY methodology for conducting security risk assessments.
- [SEC-STD-001 Identity and Access Management](https://docs.precepts.dev/security/standards/identity/iam/) [MANDATORY]: This standard defines MANDATORY requirements for authentication, authorization, session management, and de-provisioning across all systems.
- [SEC-STD-002 Secrets Management](https://docs.precepts.dev/security/standards/identity/secrets-management/) [MANDATORY]: This standard defines MANDATORY requirements for the storage, access, rotation, and revocation of secrets: API keys, passwords, database credentials, private keys, certificates, and other sensitive credentials used by software systems.
- [SEC-STD-003 Cryptography and Transport Security](https://docs.precepts.dev/security/standards/cryptography/cryptography-tls/) [MANDATORY]: This standard defines MANDATORY requirements for cryptographic algorithm selection, key lengths, transport security (TLS), and certificate management across all systems.
- [SEC-STD-004 Security Logging and Monitoring](https://docs.precepts.dev/security/standards/observability/security-logging/) [MANDATORY]: This standard defines MANDATORY requirements for security event logging, log integrity, retention, and alerting.
- [SEC-STD-005 Input Validation and Injection Prevention](https://docs.precepts.dev/security/standards/application/input-validation/) [MANDATORY]: This standard defines MANDATORY requirements for validating all inbound data and preventing injection attacks across all system boundaries.
- [SEC-STD-006 Software Supply Chain Security](https://docs.precepts.dev/security/standards/application/supply-chain/) [MANDATORY]: This standard defines MANDATORY requirements for securing the software supply chain: dependency integrity, Software Bill of Materials (SBOM), vulnerability scanning, build pipeline security, and protection against dependency confusion attacks.
- [SEC-STD-007 Vulnerability Management](https://docs.precepts.dev/security/standards/application/vulnerability-management/) [MANDATORY]: This standard defines MANDATORY requirements for identifying, tracking, prioritising, and remediating security vulnerabilities across all systems and software components.
- [SEC-STD-008 Workload Identity](https://docs.precepts.dev/security/standards/identity/workload-identity/) [MANDATORY]: This standard defines MANDATORY requirements for machine-to-machine (service-to-service) authentication using workload identity.

## AI Distribution

Standards are delivered to AI agents via:
1. This file — AI crawler index at https://docs.precepts.dev/llms.txt
2. MCP Server — active querying via Model Context Protocol (see platform repo)
3. CLAUDE.md — auto-loaded context for Claude Code sessions in this repository

## Source

- Standards (CC BY-SA 4.0): https://github.com/precepts-dev/standards
- Platform (AGPL 3.0): https://github.com/precepts-dev/platform
- Site: https://docs.precepts.dev