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>
81 lines
3 KiB
Text
81 lines
3 KiB
Text
# JSON Schema (draft 2020-12, written in YAML) for a single workspace convention.
|
|
# Every file at @conventions/programming_<scope>/<name>.yaml validates against this.
|
|
# Agents reference a convention as convention:<name> or convention:<name>(<args>).
|
|
$schema: "https://json-schema.org/draft/2020-12/schema"
|
|
$id: "conventions/convention.yaml.schema"
|
|
title: Convention
|
|
description: One workspace convention — metadata + rules, optionally defining a project manifest file and/or accepting parameters.
|
|
type: object
|
|
additionalProperties: false
|
|
required: [apiVersion, name, title, scope, status, summary]
|
|
properties:
|
|
apiVersion:
|
|
type: string
|
|
const: "conventions/v1"
|
|
description: Schema-contract version for the convention DOCUMENT itself. Bumped only on breaking schema changes; consumers branch on it. (The JSON Schema draft is separate — see $schema.)
|
|
version:
|
|
type: string
|
|
pattern: "^\\d+\\.\\d+\\.\\d+$"
|
|
description: SemVer of THIS convention's CONTENT (its rules/manifest). Bump on changes so projects can pin/migrate, e.g. "requires convention:infra_manifest >= 1.2.0".
|
|
updated:
|
|
type: string
|
|
format: date
|
|
description: ISO date (YYYY-MM-DD) this convention was last changed.
|
|
name:
|
|
type: string
|
|
pattern: "^[a-z0-9][a-z0-9_]*$"
|
|
description: snake_case id; MUST match the filename (without .yaml).
|
|
title:
|
|
type: string
|
|
scope:
|
|
type: string
|
|
enum: [general, ts, swift, py, rust, gd]
|
|
description: Matches the programming_<scope>/ directory the file lives in.
|
|
status:
|
|
type: string
|
|
enum: [draft, active, deprecated]
|
|
summary:
|
|
type: string
|
|
description: One line; shown when an agent lists available conventions.
|
|
params:
|
|
type: array
|
|
description: Named arguments the convention accepts, e.g. recursive_code_workspace(root).
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [name]
|
|
properties:
|
|
name: { type: string }
|
|
description: { type: string }
|
|
default: {}
|
|
appliesTo:
|
|
type: array
|
|
description: Globs or project kinds this convention governs.
|
|
items: { type: string }
|
|
supersedes:
|
|
type: array
|
|
items: { type: string }
|
|
rules:
|
|
type: array
|
|
items:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [id, level, text]
|
|
properties:
|
|
id: { type: string }
|
|
level: { type: string, enum: [must, should, may] }
|
|
text: { type: string }
|
|
rationale: { type: string }
|
|
# When set, the convention defines a manifest file every conforming project must
|
|
# provide (e.g. .infra.yaml), with a nested JSON Schema for that file's contents.
|
|
providesFile:
|
|
type: object
|
|
additionalProperties: false
|
|
required: [path, schema]
|
|
properties:
|
|
path:
|
|
type: string
|
|
description: Repo-relative path each conforming project must contain (e.g. ".infra.yaml").
|
|
schema:
|
|
type: object
|
|
description: JSON Schema (draft 2020-12) the manifest file validates against.
|