convention-writing

First search the codebase for existing instances of the pattern using glob and grep, count conforming versus deviating files, and identify the best examples. Then write a spec with a one-sentence pattern statement, scope globs, real code examples, anti-patterns with consequences, and an exceptions section.

A pattern is worth standardizing when it meets at least two of four criteria: it appears in 5+ files, the codebase shows 2+ inconsistent approaches, getting it wrong has real consequences, or new contributors consistently get it wrong. Skip patterns already enforced by linting or self-evident from the framework.

Scope globs are an array of patterns in the spec frontmatter that determine which files the convention applies to, so tools like hero relevant can inject it into agent context. Start narrow with patterns like src/api/**/*.ts rather than broad ones like src/**.

Write one convention per concern so each spec is independently understandable and scoped. Merge only when two drafts share the same scope, audience, and would always be read together.

A convention is ready when the pattern is a single clear statement, scope globs are tested against intended files, examples reference real code, anti-patterns explain consequences, and it has been checked against existing conventions for overlap.