59656b5b93
Add document apiVersion (conventions/v1) + per-convention semver + updated date to the schema and all seed conventions; manifest files carry their own apiVersion (infra/v1). New ./run (symlink -> scripts/cli/run) with lint:yaml validating every programming_*/<name>.yaml against the schema (name==filename, scope==dir). Rename infra-manifest.yaml -> infra_manifest.yaml for name match. 4/4 valid. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
39 lines
1.8 KiB
Markdown
39 lines
1.8 KiB
Markdown
# @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`.
|