conventions

conventions

The canonical home for the house conventions standard, plus the skills and hook that let Claude and Codex apply it to a project and keep it current over time.

This repo is three things at once:

• The source of truth — CONVENTIONS.md, version-stamped, the single canonical copy. Everything else references it; nothing duplicates it.
• The conventions plugin — three skills + a session-start hook (below).
• The repeatable upstream — projects pin this repo as their conventions-source and check it for newer versions.

The three skills

Skill	When	What it does
conventions:bootstrap	new repo	Scaffold the doc skeleton + a verbatim CONVENTIONS.md + templates/ stubs + vendored config defaults + _local/ + AGENTS.md/CLAUDE.md. One-time.
conventions:sync	existing repo	Reconcile drift and pull upstream upgrades for the tracked artifacts (CONVENTIONS.md + .conventions/*.base.*). Bidirectional, never silently overwrites.
conventions:orient	every session	Read-only: read ARCHITECTURE.md → CONVENTIONS.md, run the cheap version check, surface anything stale. Never touches files.

Session-start hook

hooks/session-start.sh runs when you open a repo. It does a cheap, offline, deterministic version compare (project's vendored conventions-version vs the installed standard) and:

• always emits a one-line status, and
• when the project is behind, injects ARCHITECTURE.md + CONVENTIONS.md so the session starts grounded, and points you at conventions:sync.

How a project tracks the standard

bootstrap writes a pin into the project's own CONVENTIONS.md frontmatter:

---
conventions-version: 1                                   # the version this copy is
conventions-source: [email protected]:platform/conventions.git   # or a local path
---

conventions-version is compared as an integer; conventions-source tells sync where upstream lives (a local clone for personal use, an internal git remote at work). The standard repo is tagged vN to match the stamp.

Install

Install the plugin from the repo-local marketplace (no raw symlinking):

• Claude Code — .claude-plugin/marketplace.json
• Codex — .codex-plugin/plugin.json / .agents/plugins/marketplace.json

Installing the plugin wires the skills (conventions:*) and the session-start hook on both tools. For a team, host this repo internally and register it as a shared marketplace.

Design rationale

The full design and the decisions behind it live in _local/PROPOSAL.md (gitignored kickoff scratch). The durable subset migrates into this README and CONVENTIONS.md.

Dependencies

Effectively none. The engine is git + the agent + a few lines of POSIX sh. Config defaults are vendored files, not packages. A scaffolded app will pull its own UI/runtime deps — that's app-level and separate from this plugin's (dependency-free) surface.