coding-standard

## Project Context

- 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"`
- personal config directory: !`bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"`
- project .han/config.md: !`cat .han/config.md 2>/dev/null || echo ""`

As your first action, use the Read tool on `.han/config.md` inside the `personal config directory` path above. A read
that returns no file is no personal configuration: continue silently. When that file or the `project .han/config.md`
probe supplies content, apply it per [config-rule.md](../../references/config-rule.md), which governs precedence
between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

## Step 1: Determine Mode

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

| Mode                | When                                                      | Initial Status | Then                                        |
| ------------------- | --------------------------------------------------------- | -------------- | ------------------------------------------- |
| Creating new        | Building a coding standard from scratch                   | `proposed`     | → Step 2                                    |
| Converting existing | User provides an existing document (ADR, etc.) to convert | `accepted`     | → Step 2                                    |
| Updating existing   | Modifying an existing coding standard                     | —              | Read the existing coding standard, → Step 3 |

## 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](../../references/yagni-rule.md) alongside the
companion evidence rule in [../../references/evidence-rule.md](../../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. **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](./references/template.md), ask the user whether to match the existing format or use this skill's
   template.

5. **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 prefixe