| name | conventions-init |
| description | USE WHEN setting up a repo for AI-first work (after /init-repo), or when the context-surface hook should start feeding repo conventions to agents before edits. Drafts `conventions.yml` at repo root: per-kind casing (inferred from the code), a vague-name denylist seed, directory roles, and a hand-filled house-rules block. Idempotent — never overwrites a populated file; re-running prints suggested additions for manual merge. Read-only on code; never invents house rules. After writing, run /refresh-context-map so the hook picks it up.
|
| allowed-tools | ["Read","Write","Glob","Grep","Bash(git rev-parse:*)","Bash(git ls-files:*)","Bash(python:*)","Bash(python3:*)","Bash(test:*)"] |
| argument-hint | [--noninteractive] |
/conventions-init
What it does
Bootstraps conventions.yml at the repo root — the profile the context-surface
hook surfaces to an agent before it edits a source file (casing rules, a
vague-name denylist, directory roles, and divergent house rules the model cannot
infer). Block-style YAML only, so the stdlib fallback parser stays reliable.
It infers the mechanical parts (casing, structure) and asks the user for
the house rules — it never invents a convention the repo does not actually hold.
When to invoke
- Setting up an AI-first repo, after
/init-repo.
- When you want the plugin to start steering on this repo (no
conventions.yml
yet means the whole steering loop is a no-op).
Do NOT invoke for: per-function docs (those are docstrings), or to auto-write
house rules the team has not agreed on.
Workflow
- Resolve repo root (
git rev-parse --show-toplevel); if not a repo, STOP
and suggest git init / /init-repo.
- Detect mode. If
conventions.yml is absent, bootstrap. If it exists, do
NOT rewrite it (stdlib YAML loses the human-written consistency comments);
instead print the suggested draft below and tell the user to merge by hand.
- Infer casing. Run
python scripts/score_adherence.py --repo . if the
plugin's scorer is available, and read metrics.casing_consistency.by_kind[*] .dominant for functions / types / constants. Python-first: if there are
no .py files (or the scorer is absent), leave casing values blank with a
comment for the user — never guess from an unsupported language.
- Seed structure roots. List top-level + recognized source dirs (
src/,
lib/, app/, scripts/, tests/, …) that exist; write each as a root key
with a blank role string for the user to fill.
- Seed the denylist from the documented defaults (
data, result, tmp,
handle, process); the user can extend.
- Leave
consistency as a commented template — house rules are the user's
to write (same "never invent" rule as glossary-init).
- Write
conventions.yml (bootstrap mode) with the schema_version "1.x"
comment, block-style. In existing-file mode, print the draft instead.
- Remind the user to run
/refresh-context-map so the manifest (and thus the
hook) picks up the new conventions, and offer a one-line AGENTS.md pointer.
- Report the path and which fields were inferred vs left for the user.
Hard rules
- Never invent house rules. The
consistency block is the user's; the skill
only scaffolds it.
- Never overwrite a populated
conventions.yml. Existing-file mode prints
suggestions for manual merge (preserves the user's comments).
- Never block. Discoverability skill; advisory if the user declines.
- Block-style YAML only (no inline braces or brackets) — keeps the stdlib
fallback parser reliable.
- Python-first casing. Do not infer casing from unsupported languages; leave
it blank for the user.
Tunables
--noninteractive — write the inferred skeleton with blank roles and a
commented consistency block, no prompts.
What this skill does NOT do
- Auto-write house rules or invent conventions the repo does not hold.
- Rebuild the context-map manifest — that is
/refresh-context-map.
- Score or lint code — that is
score_adherence.py / /repo-doctor.
Codex parity
Same SKILL.md ships in Codex via scripts/install-codex.sh. No tool-specific
divergence.
