Contributing

Use this section when you are changing OAT itself rather than consuming it as a user. It routes you to the right contributor contract for code changes, docs updates, markdown authoring patterns, and skill development.

Contents

• Contributing Code - Repo setup, monorepo structure, quality gates, and PR expectations.
• Contributing to OAT Docs - Docs contract, local docs workflow, and docs-specific authoring guidance.
• Markdown Features - Supported docs syntax for callouts, tabs, Mermaid, and code blocks.
• Writing Skills - Skill authoring guidance, runtime contracts, and governance.
• CLI Design Principles - Cross-cutting CLI architecture and UX principles.
• Commit Conventions - Traceable commit patterns for project and docs work.
• Hooks and Safety - Safety and mutation contracts for provider-sync behavior.
• Smoke Testing - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
• Updating Model Guidance - Source map and verification checklist for provider model refreshes.
• Verifying Cursor Pins - Runbook for probe-verifying a Cursor model pin before shipping it.

Source-of-truth hierarchy

When you document OAT behavior, check it against these sources, highest first:

1. Runtime behavior: packages/cli/src/**
2. Skill behavior contracts: .agents/skills/*/SKILL.md
3. OAT templates and runtime state: .oat/templates/**, .oat/sync/**, .oat/config.json, .oat/config.local.json
4. Repo reference records: .oat/repo/**

New pages belong in one of the top-level sections listed on the docs home page; the older guide/ section no longer exists.