Profiles, Catalogs, and ODS Packs

Profiles answer what kind of document a file is. They define expected H2 section headings checked during validation.

ODS uses a two-tiered Standard (Built-in) vs. Workspace (Custom) layering model for profiles and tags:

Prefer Standard Profiles first (feature, guide, api, architecture, decision, sop, policy, meeting, faq, checklist, index, note). Introduce a Custom Profile or ODS Pack only when a repeated document class is worth standardizing across teams.

Resolution Precedence

When resolving profile definitions:

1. Standard Profiles (built-in 12 core profiles)           // always loaded first
2. Catalog roots from root profiles:                       // workspace-local
3. Imported ODS Packs from root packs:                      // vendor / linked packs
4. Fallback ods-profiles/ if present                       // workspace-local fallback

• First definition of a name wins.
• Later duplicate definitions trigger a conflict warning (Level 3 CI should fail).
• Custom profiles are additive; they cannot overwrite or replace a Standard Profile name.

ODS Packs (ods pack)

A Profile defines a single document structural schema (profile: decision). A Pack is a reusable ODS workspace bundling Custom Profiles, AI Agent Skills, SOPs, Templates, and Governance Rules across repositories and machines.

Workspaces declare imported ODS Packs in their root index.md:

---
profile: index
ods: 0.1
ods-cli: ">=0.1.18"
ignore:
  - src
profiles:
  - ods-profiles
packs:
  - vendor/engineering-pack
  - ../shared-company-pack
---

Multi-Transport ods pack add

ods pack add <source> [--auto-update frequency] supports Git-native transport across five sources:

1. GitHub Shorthand: ods pack add owner/repo (Git clone into vendor/repo).
2. HTTPS Git URL: ods pack add https://github.com/acme/pack.git (Remote HTTPS clone).
3. SSH Git URL: ods pack add git@github.com:acme/pack.git (Remote SSH clone).
4. Local Path / Link: ods pack add ../shared-company-pack (Monorepo & local pack links/symlinks).
5. File URL: ods pack add file:///opt/packs/security (Air-gapped enterprise CI volume mounts).

Profile Mapping Matrix (“Which Profile Should I Use?”)