---
title: Existing Repo Checklist
last_modified: 2026-03-10
---

Use this checklist when beginning work in a repo that may not yet conform to our
repository policies
(`https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`).

Work on a feature branch. Check each item and fix any gaps before proceeding
with your task.

# Formatting (do this first)

- [ ] If the repo has never been formatted to our standards, run `make fmt` and
      commit the result as a standalone branch/commit/PR before any other
      changes. Formatting diffs can be large and should not be mixed with
      functional changes.

# Required Files

- [ ] `README.md` exists with all required sections (Description, Getting
      Started, Rationale, Design, TODO, License, Author)
- [ ] `LICENSE` file exists and matches the README
- [ ] `REPO_POLICIES.md` exists and version date is current — fetch from
      `https://git.eeqj.de/sneak/prompts/raw/branch/main/prompts/REPO_POLICIES.md`
- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, secrets) —
      fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore`
      if missing
- [ ] `.editorconfig` exists — fetch from
      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.editorconfig`
- [ ] `Dockerfile` and `.dockerignore` exist; Dockerfile runs `make check` as a
      build step — fetch `.dockerignore` from
      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.dockerignore`
- [ ] Gitea Actions workflow in `.gitea/workflows/` runs `docker build .` on
      push — reference
      `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitea/workflows/check.yml`
- [ ] Language-specific config:
    - [ ] Go: `go.mod`, `go.sum`, `.golangci.yml` (fetch from
          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.golangci.yml`)
    - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore`
          (fetch from
          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierrc` and
          `https://git.eeqj.de/sneak/prompts/raw/branch/main/.prettierignore`)
    - [ ] Python: `pyproject.toml`
    - [ ] Docs/writing: `.prettierrc`, `.prettierignore` (same URLs as above)

# Makefile

- [ ] `Makefile` exists in root — reference
      `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`
- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, `docker`,
      `hooks`
- [ ] `make check` does not modify any files in the repo
- [ ] `make test` has a 30-second timeout
- [ ] `make test` runs real tests, not a no-op (at minimum, import/compile
      check)
- [ ] `make check` passes on current branch

# Formatting

- [ ] Platform-standard formatter is configured (`black`, `prettier`, `go fmt`)
- [ ] Default formatter config, only exception: four-space indents (except Go)
- [ ] All files pass `make fmt-check`

# Git Hygiene

- [ ] Pre-commit hook is installed (`make hooks`)
- [ ] No secrets in the repo (`.env`, keys, credentials)
- [ ] No mutable references in Dockerfiles or scripts (tags, `@latest`) — all
      pinned by cryptographic hash with version/date comment
- [ ] Using `yarn`, not `npm` (JS projects)

# Directory Structure

- [ ] No unnecessary files in repo root
- [ ] Files organized into canonical subdirectories (`bin/`, `cmd/`, `docs/`,
      `internal/`, `static/`, etc.)
- [ ] Go migrations in `internal/db/migrations/` and embedded in binary

# HTTP Service Hardening (if targeting 1.0 and the repo is an HTTP/web service)

- [ ] Security headers set on all responses (HSTS, CSP, X-Frame-Options,
      X-Content-Type-Options, Referrer-Policy, Permissions-Policy)
- [ ] Request body size limits enforced on all endpoints
- [ ] Read/write/idle timeouts configured on the HTTP server (slowloris defense)
- [ ] Per-handler execution time limits in place
- [ ] Password-based auth endpoints are rate-limited
- [ ] CSRF tokens on all state-mutating HTML forms
- [ ] Passwords hashed with bcrypt, scrypt, or argon2
- [ ] Session cookies use HttpOnly, Secure, and SameSite attributes
- [ ] True client IP correctly detected behind reverse proxy (trusted proxy
      allowlist configured)
- [ ] CORS restricted to explicit origin allowlist for authenticated endpoints
- [ ] Error responses do not leak stack traces, SQL queries, or internal paths

# Final

- [ ] `make check` passes
- [ ] `docker build` succeeds
- [ ] Commit and merge fixes before starting your actual task