/conventions-init

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

1. **Resolve repo root** (`git rev-parse --show-toplevel`); if not a repo, STOP and suggest `git init` / `/init-repo`. 2. **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. 3. **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. 4. **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. 5. **Seed the denylist** from the documented defaults (`data`, `result`, `tmp`, `handle`, `process`); the user can extend. 6. **Leave `consistency` as a commented template** — house rules are the user's to write (same "never invent" rule as `glossary-init`). 7. **Write `conventions.yml`** (bootstrap mode) with the `schema_version` "1.x" comment, block-style. In existing-file mode, print the draft instead. 8. **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. 9. **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.