Precepts Standards

Built for humans. Ready for agents.

The canonical source of multi-discipline standards for the Precepts platform. Standards are published as machine-readable Markdown with YAML frontmatter, consumable by both humans and AI agents.

Install

npm install @precepts/standards

Usage

Standards are plain Markdown files with structured YAML frontmatter. Consume them however you need:

import { readFileSync } from 'fs';
import matter from 'gray-matter';

// Read a standard
const raw = readFileSync(
  'node_modules/@precepts/standards/standards/integration/standards/api/resource-design.md',
  'utf-8'
);
const { data, content } = matter(raw);

console.log(data.identifier); // "INTG-STD-008"
console.log(data.status);     // "MANDATORY"
console.log(data.domain);     // "INTEGRATION"

Disciplines

| Discipline | Prefix | Directory | |---|---|---| | Integration | INTG | standards/integration/ | | Product Management | PRD | standards/product/ | | UX | UX | standards/ux/ | | Project Management | PRJ | standards/project-management/ |

Integration Standards (Batch 1)

| Identifier | Name | Status | |---|---|---| | INTG-STD-004 | Naming Conventions | MANDATORY | | INTG-STD-005 | Character Encoding | MANDATORY | | INTG-STD-006 | Backward and Forward Compatibility | MANDATORY | | INTG-STD-008 | API Resource Design | MANDATORY | | INTG-STD-009 | API Error Handling | MANDATORY | | INTG-STD-015 | Event Envelope (CloudEvents) | MANDATORY | | INTG-STD-029 | Observability | MANDATORY | | INTG-STD-033 | Resilience Patterns | MANDATORY | | INTG-STD-034 | Retry Policy | MANDATORY | | INTG-STD-035 | Timeout | MANDATORY |

Standards Schema

Each standard has YAML frontmatter validated against schema/standards.schema.json:

---
identifier: INTG-STD-008
name: API Resource Design
version: 1.0.0
status: MANDATORY
domain: INTEGRATION
documentType: standard
category: protocol
---

Required fields: identifier, name, version, status, domain, documentType

Identifier pattern: [INTG|PRD|PRJ|UX|SEC]-[STD|GDL|GOV|BP]-NNN

Status values: DRAFT, MANDATORY, RECOMMENDED, DEPRECATED

Content Conventions

• ## Rules for prescriptive instructions (not "Requirements")
• RFC 2119 keywords (MUST, SHOULD, MAY) bolded throughout
• Rule numbering: ### R-N: Title as H3 headings
• Concept-level examples (pseudocode), not technology-specific
• 200-300 lines per standard

Validation

npm run validate          # check frontmatter + required sections
npm run validate:strict   # warnings become errors

Ecosystem

This package is consumed by:

• precepts-dev/platform - Docusaurus site, MCP server, validator
• precepts-dev/engine - Commercial compliance scanning engine (private)
• Your tools - build anything on top of these standards

Consuming Standards via MCP (Model Context Protocol)

If you want AI agents (like Claude Desktop, Copilot, Cursor etc.) to interactively read, search, and validate your own implementation against these standards, check out the MCP server implementation in the platform repository.

Contributing

Standards proposals and revisions are welcome. Each standard follows the template in schema/document-standard-template.md.

1. Fork this repo
2. Create a new standard or modify an existing one
3. Run npm run validate to check your changes
4. Open a PR

License

CC BY-SA 4.0 - see LICENSE for details.

All standards are freely usable by individuals, companies, and AI tools, with attribution and share-alike.