coding-standard

Project Context

• Git user: !git config user.name (!git config user.email)
• OS username: !whoami
• CLAUDE.md: !find . -maxdepth 1 -name "CLAUDE.md" -type f
• AGENTS.md: !find . -maxdepth 1 -name "AGENTS.md" -type f
• project-discovery.md: !find . -maxdepth 3 -name "project-discovery.md" -type f
• Rules directory: !find . -maxdepth 4 -type d -path "*/.claude/rules/coding-standards"

Step 1: Determine Mode

Determine which mode to operate in based on the user's request:

Step 2: Evaluate Appropriateness

Coding standard documents are not a replacement for automated tooling. Before proceeding, evaluate whether the proposed coding standard falls into one of these categories:

• Conventions that should be enforced by linters or formatters (variable naming, indentation, whitespace, import ordering, bracket placement, line length, semicolons)
• Common language conventions that are well-known or easily discoverable from the language's own documentation and community norms (type declaration style, etc.)

If the proposed coding standard falls into one of these categories:

1. Warn the user that this is typically handled by automated tooling or is a well-known language convention, and that documenting it adds maintenance burden without value. Recommend configuring tooling instead.
2. Ask the user whether they still want to proceed
3. If the user declines, stop — the skill is done

If the proposed coding standard does not fall into these categories, proceed to the YAGNI check below.

YAGNI check

Apply the evidence-based YAGNI rule from ../../references/yagni-rule.md alongside the companion evidence rule in ../../references/evidence-rule.md. A coding standard is worth writing only when the project actually does the thing the standard governs today and the standard solves a real, concrete problem the team is currently hitting. Standards about patterns the project doesn't use yet, "for future flexibility", "best practice says we should…", or symmetry with other standards ("we have one for backend, so we should have one for frontend" when the frontend codebase is a single file) are YAGNI candidates. Acceptable evidence the standard is needed now:

• The pattern the standard governs is actively used in the codebase today (cite at least three examples), and inconsistency between examples is causing real friction (review churn, bugs, onboarding cost).
• A documented incident or recurring code-review finding the standard would prevent.
• A regulatory or compliance rule the project actually falls under that requires the convention.
• A user-described need ("I keep having to remind people about X").

If no accepted evidence applies, recommend deferring the standard with the trigger that would justify writing it (a third instance of the pattern lands, a real incident occurs, a recurring review finding accumulates). Surface the recommendation to the user with the override option.

Step 3: Discover Project Structure

1. Retrieve project config: Resolve project config: read CLAUDE.md's ## Project Discovery section for docs and coding-standards directories; fall back to project-discovery.md; fall back to Glob defaults (docs/, docs/coding-standards/). Continue without any keys that remain unfound.

2. Determine the coding standards directory:

   • If a coding standards directory was found, use it
   • If only a docs directory was found, create {docs-dir}/coding-standards/
   • If neither was found, create docs/coding-standards/

3. Enumerate existing coding standards: If a coding standards directory was found, use Glob to enumerate existing .md files in that directory.

4. Resolve author information: If git user or email is empty in the project context above, ask the user for their name and email.

5. Check existing coding standard format: If existing coding standards were found via Glob, read one to understand the project's existing format. If it uses a different format than the template at template.md, ask the user whether to match the existing format or use this skill's template.

6. Discover the filename hierarchy taxonomy: Coding standards are organized by a one- or two-level hierarchy encoded in the filename so related standards sort together in a directory listing. Discover the taxonomy that applies to this project — never hardcode it.

   • From existing filenames: If existing standards were enumerated, parse their filenames to extract the leading hierarchy segments already in use (e.g., svelte-component-naming.md → top-level svelte; svelte-stores-state-shape.md → top-level svelte, second-level stores). Build a list of top-level prefixes and known second-level prefixes per top-level.
   • From project context: Read CLAUDE.md and project-discovery.md (paths from project context above) to identify the project's languages, frameworks, runtimes, and major subsystems. Each of these is a candidate top-level hierarchy (e.g., svelte, rails, postgres, terraform, api, worker).
   • Carry forward to Step 6: the discovered top-level prefixes (existing + candidate) and any second-level prefixes already in use under each.

7. Discover the project's primary file-type globs and group them into index-file buckets. The paths: frontmatter in Step 6 needs file globs scoped to the languages and directories the new standard governs. The Step 7 integration then routes the new standard into one or more per-file-type index files under .claude/rules/coding-standards/, where each index file owns a single file-type bucket (for example, svelte.md owns **/*.svelte; typescript.md owns **/*.ts and **/*.tsx; ruby.md owns **/*.rb and app/**/*.rb). Build the candidate glob set and its bucket grouping now so Steps 6 and 7 have them on hand.

   • From CLAUDE.md and project-discovery.md: extract every language, file extension, and major source directory the project actually uses (e.g., **/*.go, **/*.ts, **/*.tsx, **/*.py, **/*.rb, app/**/*.rb, services/**/*.go).
   • From existing standards' paths: frontmatter: if any existing standard already carries paths:, collect its globs as candidate glob prefixes — they reflect the project's accepted scoping vocabulary.
   • From existing index files under .claude/rules/coding-standards/: if the rules directory was found in the project context, enumerate the index files already present and read each one's paths: frontmatter. Each existing file defines an established bucket; reuse it rather than introducing a parallel bucket for the same file type.
   • Fallback: if no source yields globs, glob the project root for the dominant file extensions (**/*.{ext} for each extension seen in more than a handful of files) and surface what you found.
   • Group into buckets: organize the resolved candidate glob set into file-type buckets, one per index file. Reuse an existing bucket whenever one fits; introduce a new bucket only when no existing index file's paths: covers the new glob. Name new buckets after the language, framework, or subsystem they cover (e.g., svelte, typescript, ruby, sql) — the bucket name becomes the index file's filename in Step 7.
   • Carry forward to Steps 6 and 7: the candidate glob set grouped by bucket, plus the list of existing index files and the globs each one owns.

Step 4: Gather Context

1. From the arguments and conversation, determine:
   • Topic: what the coding stan