/add-convention

name: add-convention
description: Assess and add a CONVENTION (a reusable rule, practice, or naming/process standard) to a documentation-led repo — decides FIRST whether it is worth codifying at all, then routes it to the right home (AGENTS.md hard rule, CONVENTIONS.md guidance, GLOSSARY term, or to /new-adr if it is really a one-off decision). Pushes back on premature or duplicate conventions. Use when the user says "add a convention", "make this a rule", "document this practice", "we should always X", or invokes /add-convention. NOT for recording a single architectural/product decision (use /new-adr) and NOT for queueing work (use /new-plan).

add-convention

Add a convention — but only after assessing whether it should exist and where it belongs. This skill is a gatekeeper and a router, not a stenographer.

Step 0 — Preconditions and context

1. Confirm the repo is bootstrapped. 2. Read `CONVENTIONS.md` and `AGENTS.md` in full so you can detect overlap with existing rules and judge fit.

Step 0.5 — Assessment (run first)

Run the shared assessment protocol; the triage (Step 1) and routing (Step 2) questions are asked under it:

• **Reuse supplied answers first.** Treat applicable choices already supplied

in the request or this session, including depth, as answered. Summarise them without asking again; defaults never replace explicit choices. If every material choice is supplied, proceed. Ask only about a material missing or conflicting choice. A repository preference alone is not a current answer or execution grant.

• **Depth selector for unresolved choices.** If depth is not supplied and

choices remain, ask how deep this assessment should go: **express** — every choice takes its recommended default; only questions with no derivable default (the free-text essentials) are still asked; **guided** — only the questions marked high-impact below, plus the free-text essentials; **full** — every question below. If the repo's `CONVENTIONS.md` records an `Assessment depth:`, pre-select it as the recommended option when asking; a recorded depth is never applied silently. Otherwise recommend **full** when the request arrived with little or no context and **express** when it is already fully specified. At any question the operator may answer "defaults from here" or "go deeper"; honour the switch immediately.

• Ask questions **one at a time**, each with a **recommended option** and

a one-line reason; wait for each answer.

• Use **structured selection** (single- or multiple-choice). If the host

exposes a structured single-/multi-select question tool, use it and mark the recommended option; otherwise list options A/B/C in plain text and name the recommended one. Use **free text only** where an enumerable set is impossible (e.g. the exact wording).

• **The operator decides.** Never proceed past a question without an

answer, and never guess scope when invoked with no context.

Questions (skip any the request already answers): 1. **Worth codifying?** — yes (recurring, stable, testable) or no (one-off, duplicate, churn-prone, vague). *Recommended: per the Step 1 triage; this question gates the rest.* *(High-impact — asked in guided.)* 2. **Home** — `AGENTS.md` hard rule / `CONVENTIONS.md` guidance / `GLOSSARY.md` term / actually a decision (hand off to the **new-adr** skill). *Recommended: per the rule's nature (see Step 2).* *(High-impact — asked in guided: the wrong home is churn to move.)* 3. **Enforce in the verify gate?** — yes / no. *Recommended: no, unless the rule is mechanically checkable.* 4. **Wording** — free text (the rule statement itself; asked at every depth).

Step 1 — Assess: is this worth codifying?

Apply triage. Recommend **against** adding when:

• It is already covered (explicitly or implicitly) by an existing

convention — point to it instead of duplicating.

• It is a one-off, not a recurring decision — codifying it adds noise.
• It is likely to churn — premature rules become stale cruft.
• It is too vague to be testable or actionable as written.

Recommend **for** adding when it is a recurring decision whose ambiguity causes rework, it is stable, and it can be stated so an agent can follow it without further interpretation. State your recommendation and the reason before doing anything.

Step 2 — Route: where does it belong?

Decide the home, and explain the choice:

• **Hard rule agents must obey** → a bullet in `AGENTS.md` §Hard rules,

with the substance in `CONVENTIONS.md`. Use for non-negotiable constraints.

• **Authoring / process guidance** → a section in `CONVENTIONS.md`.

Use for "how we do things" that informs but doesn't gate.

• **Shared term / definition** → `GLOSSARY.md` (create it if absent —

adding the first term enables the glossary layer; place it at the recorded artefact root). Read the repo's `CONVENTIONS.md` §Glossary and inspect the rule it actually declares; the canonical structure is an optional H1 heading and optional introductory prose, then exactly one two-column Markdown table whose header is `Term | Definition`. Every term is its own row. Never record a term as a heading, a bullet or a paragraph, and never add a second table or a different column shape. A §Glossary that states an older or unrelated glossary convention is not adoption of this table: use the canonical shape and offer the audit skill's separately consented rule-and-file migration rather than copying the old shape. An absent `GLOSSARY.md` remains a valid state; this skill creates one only because a term is actually being added.

• **It is actually a decision, not a convention** (an architectural,

product, or technology choice with alternatives and consequences) → this is an ADR. Stop and offer the **new-adr** skill; do not bury a decision in CONVENTIONS.

If a convention is a triage/process rule (e.g. how incoming work is triaged), prefer `CONVENTIONS.md` with a