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

Confirm the repo is bootstrapped.
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):

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.)
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.)
Enforce in the verify gate? — yes / no. Recommended: no, unless the rule is mechanically checkable.
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 hard-rule bullet in AGENTS.md only for the parts that are non-negotiable.

Step 3 — Draft and confirm

Draft the exact wording for its home file. Keep it tight, testable, and in the repo's language. Show the diff. Confirm before writing.

Step 4 — Write and commit

Apply the edit(s). If a convention rises to a hard rule, ensure AGENTS.md and CONVENTIONS.md stay consistent. Conventional Commit (docs: ...); no ADR touched means no Rationale: footer is required, but add one if the repo's contract asks for it on convention changes.

Adding or extending a glossary. Use the canonical structure defined below and the declared-rule checks; the shape must not drift between runs.

Where the rule comes from. If CONVENTIONS.md has no §Glossary section (a legacy repo that predates it, or a layer enabled before the rule was recorded), fall back to the product default canonical shape above: optional # Glossary heading and intro prose, then one Term | Definition table. Do not invent a different shape for that repo, and do not silently edit unrelated conventions.
Reading the declared rule. When a §Glossary exists, read what it actually declares. If it describes the canonical two-column Term | Definition table, follow it and change it only on an explicit request. If it states a different or older glossary convention (bullets, prose, another column shape), the repo has not adopted this table: do not copy the old shape, and do not silently rewrite the rule. Use the canonical shape for the term and offer the audit skill's migration, which covers the rule and the file together as one separately consented diff.
Recording the convention. When a §Glossary is absent, offer — as its own confirmed edit, separate from the term being added — to record a ## Glossary section in CONVENTIONS.md stating the shape actually used. Show that diff and write it only if the user accepts; never rewrite or reorder other CONVENTIONS.md sections to make room, and if the user declines, keep the glossary canonical but leave CONVENTIONS.md unchanged.
Creating the file. Write the optional # Glossary heading and any short introductory prose the repo needs, then the single two-column table with header Term | Definition and the new term as its first row. Do not invent placeholder terms.
Extending an existing file. Preserve the heading, introductory prose, entry order and every existing row byte for byte. Append the new term as one new row; never rebuild, re-sort or reformat the file, and never introduce a second table.
Anchors. If the new term's row is reachable from a heading anchor an incoming link already uses, keep that anchor on the row rather than dropping the target; if the anchor cannot be preserved, stop and flag it instead of guessing.
Preserve meaning. Keep the term's spelling, aliases, links and inline code exactly as supplied. Escape a literal pipe as \|. If a definition is genuinely multiline, keep it in one cell with <br> for the hard break rather than spilling into extra rows.
Duplicates and ambiguity. If the term already exists, show the existing and proposed definitions and ask whether to update or leave the existing row. Never silently merge, replace or add a second row for the same term, and never guess a definition.
Non-canonical file. If the existing GLOSSARY.md is bullets, prose, headings or a mixed shape, do not append a competing row and do not rewrite the file as a side effect of adding a term. Surface the non-canonical structure and offer the audit skill's consented migration; apply it only if the user accepts the concrete diff. A declined migration leaves the file as the user keeps it.

Name the rule and propagation performed; list repositories not updated.

Closing report

End every run, including blocked, failed and stopped runs, with a section headed exactly Status at a glance, containing these three labels:

This run: only actions actually attempted and their outcomes; quote each verify gate's exact output and exit code, including timeouts or interruptions.
Overall: implemented, partially verified, verified, blocked, failed or unknown. A passing sub-step is not an overall pass; incomplete or missing evidence never becomes success.
Yet to do: every remaining action, unresolved finding, verification, cleanup or required input. Write None only when the whole task is verifiably complete; never omit work because a budget ended.

Routine progress messages need no block. Keep final results brief and distinguish work prepared on a PR from work confirmed shipped.

EvolveHQ/docflow

What is docflow?

Ask in your favorite AI

Documentation