# Coding Guidelines

These rules apply to **all** work in this repo. Follow them strictly.

## 1. Folder-per-extension, small & modular

- Every extension lives in its **own folder** under `extensions/` (e.g. `extensions/my-ext/`).
  Single-file extensions (`extensions/foo.ts`) must be migrated to `extensions/foo/index.ts`.
- Keep files **small and focused** — one concern per file, ≤ 300 lines as a guideline.
  If a file grows beyond that, split it into submodules within the extension folder.
- Each extension folder may contain: `index.ts` (entry point), private helpers,
  types, and tests. Only `index.ts` is the public surface.

## 2. Use shared helpers

- Reusable utilities belong in `extensions/shared/` — never duplicate logic
  across extensions.
- Before writing a new helper, check `extensions/shared/` for an existing one.
- When extracting a helper, add it to the [Shared Modules table](extensions.md)
  in `docs/extensions.md`.

## 3. DRY — Don't Repeat Yourself

- If the same logic appears in two or more places, extract it into a shared
  module or a local helper within the extension folder.
- Config values, magic strings, and constants go in one place — never scattered
  across files.

## 4. No `any` types

- **Never** use `any` in TypeScript. Use `unknown`, generics, proper interfaces,
  or type narrowing instead.
- Existing `any` types should be fixed when touching that code.

## 5. Write tests for extensions

- Every extension folder must include tests (e.g. `extensions/my-ext/my-ext.test.ts`).
- Tests cover: tool registration, core logic, edge cases.
- Run the full test suite before committing.

## 6. Update docs on every change

- **Any** code change must include corresponding updates to all affected docs:
  `AGENTS.md`, `docs/extensions.md`, `docs/agents.md`, `docs/commands.md`,
  `docs/configuration.md`, skill files, and ADRs.
- A PR/commit that changes behavior without updating docs is incomplete.
- When adding or renaming an extension, update the Extension List table in
  `docs/extensions.md` and the Key extensions line in `AGENTS.md`.
