OpenSpec Project Conventions and Architectural Guidelines

Status: draft Owners: Program Lead, Architecture, Compliance Last updated: 2025-11-17

Purpose

Define repository‑wide conventions for OpenSpec usage, spec authoring, compliance and accessibility gates, and architectural boundaries.

OpenSpec conventions

Filenames: use kebab‑case; prefix with domain (e.g., feature-forum.md).
Status labels: draft, in-review, approved, implemented, archived.
Each proposal follows the template in openspec/templates/proposal-template.md and lives under openspec/changes/.
Accepted specs move to openspec/specs/ with clear versioning.
One change = one lifecycle: propose → review → apply → archive.

Slash command conventions

/propose <title> [scope=spec|infra|policy] [labels=...] [assignees=...] [model=claude|gpt|copilot]
/review <areas=accessibility,compliance,security,mobile,web,backend>
/apply <spec=<file>> [pr=link] moves normative text to openspec/specs/
/archive <reason> [link=PR] marks closure with traceability
/assign @user1 @user2 sets proposal owners

Decision records

Record important decisions inline in proposals under “Alternatives considered” and “Decision & rationale”.
For cross‑cutting decisions, add a short entry in openspec/specs/architecture.md#decisions.

Architecture (guardrails)

API standards

OpenAPI-first for HTTP; JSON over HTTPS; WebSocket for realtime.
OAuth2/OIDC for auth; short‑lived access tokens; rotate refresh tokens.
Resource versioning via URI (/v1) and schema versioning in payloads as needed.
Pagination, idempotency keys for writes, and explicit rate limits.

Data protection & compliance

Data classes: Public, PII, PHI. Keep PHI minimized and isolated.
Encryption: TLS 1.3 in transit, AES‑256 at rest; per‑table/field encryption for PHI/PII where applicable.
Access controls: role‑based (RBAC) and attribute‑based (ABAC) where necessary; audited access to sensitive data.
Data retention & deletion: GDPR erase requests and well‑defined retention policies per data class.
Logging: no PHI/PII in logs; use structured logs with redaction.

Accessibility baseline

Target WCAG 2.2 AA+; support reduced motion, dynamic type/large fonts, high contrast, screen readers, and keyboard/assistive navigation.
Mobile: iOS VoiceOver / Android TalkBack parity for all screens.
Web: semantic landmarks, focus order, ARIA where necessary; test via automated and manual checks per spec.

Observability & quality

Tracing for backend APIs; structured logs; SLOs for critical user journeys.
Test pyramid per component: unit, integration, e2e. Accessibility checks included in CI for UI changes.

Release management

Contribution