git:20260905.a73d7ea to git:20260914.e06e21c

---

name: code-quality-and-validation

description: >-

Standards, tools, and commands for code formatting, linting, and static type checking

across Go, Python, and TypeScript.

---

# Code Quality & Validation Standards

This skill defines the multi-tier code quality, formatting, linting, and type checking standards across polyglot repositories.

---

## 1. Local Branch-First Development

> [!IMPORTANT]

> **CREATE A LOCAL BRANCH FIRST**: Always start by creating a dedicated local branch from `main`:

> ```bash

> git switch -c <developer-or-agent>/main/<feature-name>

> ```

> Never develop code or run refactors directly on `main`.

---

## 2. Tooling Matrix by Language

| Language | Subsystem | Formatter | Linter | Static Type Checker |

| :--- | :--- | :--- | :--- | :--- |

| **Go** | Backend & CLI | `gofmt` | `go vet ./...` | Go Compiler (`go build ./...`) |

| **Python** | AI & Services | Ruff / Black compatible | Ruff check / Pyright | Pyright (`uv run --with pyright pyright`) |

| **TypeScript** | Frontend & Web | Biome (`pnpm run format`) | Biome (`biome check`) | TypeScript Compiler (`tsc --noEmit`) |

---

## 3. Code Quality Rules

### 1. Go Guidelines

- Always format code using standard `gofmt` before committing.

- Zero compiler warnings or `go vet` issues allowed.

- Prefer structured logging via standard library `slog`.

- Clean up goroutines and database connection handles using `defer`.

### 2. Python Service Guidelines

- Python 3.12+ type annotations required on all function arguments, return types, and Pydantic models.

- Zero errors in Pyright type checking (`pyrightconfig.json`).

- Ensure all async functions and database sessions are properly awaited and closed.

### 3. Frontend TypeScript Guidelines

- Strict TypeScript checks with zero `any` types wherever possible.

- Use Biome for combined linting and code formatting (`package.json`).

- Ensure components render cleanly in production builds.

---

## 4. Developer CLI Runbook

```bash

# Auto-format all Go and TypeScript files

make format

# Run all linters across Go, Python, and Frontend

make lint

# Run static type checkers across Python and Frontend

make typecheck

# Full pre-commit validation pass

make pre-commit

```