---
description: Rules for coding agents to follow
globs: **/*
alwaysApply: true
---

# Coding Styleguide

## Universal Principles

- Write idiomatic, self-documenting code with clear, descriptive names
- Optimize for readability
- Use names consistently
- Prefer explicit over implicit
- Keep code close together that belongs together

## Complexity and module design

- Treat complexity as the primary enemy. Prefer designs that reduce mental load, special cases, and cross-module coupling.
- Prefer deep modules with shallow interfaces: expose minimal API surface and hide implementation details by default.
- Avoid pass-through abstractions that add layers but do not hide meaningful complexity.

## JavaScript & TypeScript

See [Coding Styleguide JavaScript & TypeScript](./coding-styleguide-js-ts.mdc)

## HTML & CSS

See [Coding Styleguide HTML & CSS](./coding-styleguide-html-css.mdc)

## React

See [Coding Styleguide React](./coding-styleguide-react.mdc)

## Shell scripts

See [Coding Styleguide Shell Scripts](./coding-styleguide-sh.mdc)

## Development Practices

- Breakdown complex tasks into smaller, manageable todos and write them down to a dedicated TODO file
- Aim for small, reviewable pull-requests. Split work into logical units, and use stacked PRs when scope or risk justifies incremental review.
- Write unit tests for simple, pure functions
- Unit test files are colocated with source files (\*.test.ts)
- Write integration or e2e tests for more complex functions/classes/components
- Prefer staged validation for non-trivial tasks: run focused checks after meaningful changes, then run broader lint/type/test checks before handoff. For trivial tasks, a single final validation is acceptable.
- Adjust documentation both in comments and markdown files once you're done

## Consumer-repo uncertainty protocol

Some guidance depends on the consuming repository's runtime and toolchain (module resolution, transpilation, bundler, test runner).

- First infer conventions from local evidence:
  - nearby files and existing import style
  - tsconfig compiler options
  - eslint and import rules
  - package scripts and build tooling
- If evidence is insufficient or conflicting, ask one concise question before changing conventions.
- Do not silently introduce a new convention in a mixed or unknown setup.
- If no answer is possible, follow the closest existing local convention and explicitly document the assumption.

## Repo-level routing system

To reduce exploration cost in large repositories, use a repo-level routing document.

- Preferred path in consuming repositories: `docs/agent-routing.md` (or the nearest existing equivalent).
- Use `@peerigon/configs/ai/agent-routing.example.md` as a starting structure and adapt it to the consuming repository.
- At task start, check whether routing exists.
- If routing is missing and the task is non-trivial, create an initial routing file before implementation. If local policy may restrict docs changes, ask one concise question first.
- Use routing-first navigation: read the relevant routing section before broad codebase exploration.
- Keep routing concise and practical. Update it when better entrypoints, caveats, or validation commands are discovered.
- Do not duplicate full architecture docs. Routing should be an index for fast task orientation.