conventions/README.md

# @conventions

Single source of truth for workspace + coding conventions, shared by every project
under `~/Code` (and known to global agentic config, so any agent in any repo can
resolve them).

## Layout
```
@conventions/
├── convention.yaml.schema          # meta-schema every convention validates against
├── programming_general/<name>.yaml # language-agnostic conventions
├── programming_ts/<name>.yaml      # TypeScript
├── programming_swift/<name>.yaml   # Swift
├── programming_py/<name>.yaml      # Python
├── programming_rust/<name>.yaml    # Rust
└── programming_gd/<name>.yaml      # GDScript
```

## A convention
A `<name>.yaml` is metadata + `rules`, and may:
- **accept `params`** — referenced as `convention:<name>(<args>)`, e.g. `convention:recursive_code_workspace(~/Code)`;
- **define a manifest** via `providesFile` — a file (e.g. `.infra.yaml`) every conforming project must contain, with a nested JSON Schema for its contents.

Validate a convention file against `convention.yaml.schema`; validate a project's
manifest against the convention's `providesFile.schema`.

## How agents use it
Global config points agents here. An agent resolves `convention:<name>` by reading
`programming_<scope>/<name>.yaml`, applies its `rules`, and (for `providesFile`
conventions) reads/writes the project's manifest to that schema. Conventions are
data, not prose — tooling (a future `infra-apply`, linters, scaffolders) can consume
them directly.

## Seed conventions
- `programming_general/recursive_code_workspace.yaml` — the `~/Code` @org layout.
- `programming_general/infra_manifest.yaml` — per-project `.infra.yaml`.

## Lint
`./run lint:yaml` validates every convention against `convention.yaml.schema` (name==filename, scope==dir, semver). `run` is a symlink to `scripts/cli/run`.