diff --git a/.prettierrc b/.prettierrc index 0a02bce..8af31cd 100644 --- a/.prettierrc +++ b/.prettierrc @@ -1,3 +1,4 @@ { - "tabWidth": 4 + "tabWidth": 4, + "proseWrap": "always" } diff --git a/Makefile b/Makefile index 8ea462e..975aa15 100644 --- a/Makefile +++ b/Makefile @@ -7,13 +7,13 @@ test: lint: @echo "Linting markdown files..." - @$(PRETTIER) --check '**/*.md' --tab-width 4 + @$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always fmt: - @$(PRETTIER) --write '**/*.md' --tab-width 4 + @$(PRETTIER) --write '**/*.md' --tab-width 4 --prose-wrap always fmt-check: - @$(PRETTIER) --check '**/*.md' --tab-width 4 + @$(PRETTIER) --check '**/*.md' --tab-width 4 --prose-wrap always check: test lint fmt-check diff --git a/README.md b/README.md index 9bb2810..32e2ac8 100644 --- a/README.md +++ b/README.md @@ -11,21 +11,21 @@ git clone https://github.com/sneak/prompts.git cd prompts ``` -Prompts are stored as Markdown files in the repository root. Copy or -reference them as needed in your projects. +Prompts are stored as Markdown files in the repository root. Copy or reference +them as needed in your projects. ## Rationale -LLM prompts, especially development policies, benefit from version control -and a single authoritative source. This repo provides a central place to -maintain, share, and evolve prompts across projects. +LLM prompts, especially development policies, benefit from version control and a +single authoritative source. This repo provides a central place to maintain, +share, and evolve prompts across projects. ## Design -The repository is a flat collection of Markdown files. Each file contains -one or more related prompts or policy documents. There is no build step or -runtime component; the prompts are consumed by copying them into other -projects or referencing them directly. +The repository is a flat collection of Markdown files. Each file contains one or +more related prompts or policy documents. There is no build step or runtime +component; the prompts are consumed by copying them into other projects or +referencing them directly. ## TODO diff --git a/REPO_POLICIES.md b/REPO_POLICIES.md index 4643607..df18a7c 100644 --- a/REPO_POLICIES.md +++ b/REPO_POLICIES.md @@ -3,71 +3,68 @@ Version: 2026-02-22 - Cross-project documentation (such as this file) must include a - `Version: YYYY-MM-DD` line near the top so it can be kept in sync - with the authoritative source as policies evolve. + `Version: YYYY-MM-DD` line near the top so it can be kept in sync with the + authoritative source as policies evolve. - All references to Docker images, Go modules, and packages must use - cryptographic hashes. Mutable references (tags, `@latest`, etc.) are - remote code execution vulnerabilities. + cryptographic hashes. Mutable references (tags, `@latest`, etc.) are remote + code execution vulnerabilities. - Every repo with software must have a root `Makefile` with these targets: - `make test`, `make lint`, `make fmt` (writes), `make fmt-check` - (read-only), `make check` (prereqs: `test`, `lint`, `fmt-check`), - `make docker`, and `make hooks` (installs pre-commit hook). A model - Makefile is at + `make test`, `make lint`, `make fmt` (writes), `make fmt-check` (read-only), + `make check` (prereqs: `test`, `lint`, `fmt-check`), `make docker`, and + `make hooks` (installs pre-commit hook). A model Makefile is at `https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile`. - Always use Makefile targets (`make fmt`, `make test`, `make lint`, etc.) - instead of invoking the underlying tools directly. The Makefile is the - single source of truth for how these operations are run. + instead of invoking the underlying tools directly. The Makefile is the single + source of truth for how these operations are run. -- Every repo should have a `Dockerfile`. For non-server repos, the - Dockerfile should bring up a development environment and run - `make check` (the build should fail if the branch is not green). +- Every repo should have a `Dockerfile`. For non-server repos, the Dockerfile + should bring up a development environment and run `make check` (the build + should fail if the branch is not green). - Use platform-standard formatters: `black` for Python, `prettier` for - JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration - with one exception: set four-space indents for everything except Go. - Documentation and writing repos (Markdown, HTML, CSS) should also have - `.prettierrc` and `.prettierignore`. + JS/CSS/Markdown/HTML, `go fmt` for Go. Always use default configuration with + two exceptions: four-space indents (except Go), and `proseWrap: always` for + Markdown (hard-wrap at 80 columns). Documentation and writing repos (Markdown, + HTML, CSS) should also have `.prettierrc` and `.prettierignore`. - Pre-commit hook: `make check` if local testing is possible, otherwise - `make lint && make fmt-check`. The Makefile should provide a - `make hooks` target to install the pre-commit hook. + `make lint && make fmt-check`. The Makefile should provide a `make hooks` + target to install the pre-commit hook. -- `make test` must complete in under 20 seconds. Add a 30-second timeout - in the Makefile. +- `make test` must complete in under 20 seconds. Add a 30-second timeout in the + Makefile. - Docker builds must complete in under 5 minutes. -- `make check` must not modify any files in the repo. Tests may use - temporary directories. +- `make check` must not modify any files in the repo. Tests may use temporary + directories. - `main` must always pass `make check`, no exceptions. -- Never commit secrets. `.env` files, credentials, API keys, and - private keys must be in `.gitignore`. No exceptions. +- Never commit secrets. `.env` files, credentials, API keys, and private keys + must be in `.gitignore`. No exceptions. -- `.gitignore` should be comprehensive from the start: OS files - (`.DS_Store`), editor files (`.swp`, `*~`), language build artifacts, - and `node_modules/`. Fetch the standard `.gitignore` from - `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` - when setting up a new repo. +- `.gitignore` should be comprehensive from the start: OS files (`.DS_Store`), + editor files (`.swp`, `*~`), language build artifacts, and `node_modules/`. + Fetch the standard `.gitignore` from + `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` when setting up + a new repo. -- Never use `git add -A` or `git add .`. Always stage files explicitly - by name. +- Never use `git add -A` or `git add .`. Always stage files explicitly by name. - Never force-push to `main`. -- Make all changes on a feature branch. You can do whatever you want on - a feature branch. +- Make all changes on a feature branch. You can do whatever you want on a + feature branch. -- `.golangci.yml` is standardized and must _NEVER_ be modified by an - agent, only manually by the user. Copy from - `~/dev/upaas/.golangci.yml` if available. +- `.golangci.yml` is standardized and must _NEVER_ be modified by an agent, only + manually by the user. Copy from `~/dev/upaas/.golangci.yml` if available. -- When pinning images or packages by hash, add a comment above the - reference with the version and date (YYYY-MM-DD). +- When pinning images or packages by hash, add a comment above the reference + with the version and date (YYYY-MM-DD). - Use `yarn`, not `npm`. @@ -75,45 +72,43 @@ Version: 2026-02-22 - Simple projects should be configured with environment variables. -- Dockerized web services listen on port 8080 by default, overridable - with `PORT`. +- Dockerized web services listen on port 8080 by default, overridable with + `PORT`. - `README.md` is the primary documentation. Required sections: - **Description**: First line must include the project name, purpose, - category (web server, SPA, CLI tool, etc.), license, and author. - Example: "µPaaS is an MIT-licensed Go web application by @sneak - that receives git-frontend webhooks and deploys applications via - Docker in realtime." + category (web server, SPA, CLI tool, etc.), license, and author. Example: + "µPaaS is an MIT-licensed Go web application by @sneak that receives + git-frontend webhooks and deploys applications via Docker in realtime." - **Getting Started**: Copy-pasteable install/usage code block. - **Rationale**: Why does this exist? - **Design**: How is the program structured? - - **TODO**: Update meticulously, even between commits. When - planning, put the todo list in the README so a new agent can pick - up where the last one left off. - - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. - Include a `LICENSE` file in the repo root and a License section in - the README. + - **TODO**: Update meticulously, even between commits. When planning, put + the todo list in the README so a new agent can pick up where the last one + left off. + - **License**: MIT, GPL, or WTFPL. Ask the user for new projects. Include a + `LICENSE` file in the repo root and a License section in the README. - **Author**: [@sneak](https://sneak.berlin). - First commit of a new repo should contain only `README.md`. -- Go module root: `sneak.berlin/go/`. Always run `go mod tidy` - before committing. +- Go module root: `sneak.berlin/go/`. Always run `go mod tidy` before + committing. - Use SemVer. -- Database migrations live in `internal/db/migrations/` and must be - embedded in the binary. Pre-1.0.0: modify existing migrations (no - installed base assumed). Post-1.0.0: add new migration files. +- Database migrations live in `internal/db/migrations/` and must be embedded in + the binary. Pre-1.0.0: modify existing migrations (no installed base assumed). + Post-1.0.0: add new migration files. -- All repos should have an `.editorconfig` enforcing the project's - indentation settings. +- All repos should have an `.editorconfig` enforcing the project's indentation + settings. -- Avoid putting files in the repo root unless necessary. Root should - contain only project-level config files (`README.md`, `Makefile`, - `Dockerfile`, `LICENSE`, `.gitignore`, `.editorconfig`, - `REPO_POLICIES.md`, and language-specific config). Everything else - goes in a subdirectory. Canonical subdirectory names: +- Avoid putting files in the repo root unless necessary. Root should contain + only project-level config files (`README.md`, `Makefile`, `Dockerfile`, + `LICENSE`, `.gitignore`, `.editorconfig`, `REPO_POLICIES.md`, and + language-specific config). Everything else goes in a subdirectory. Canonical + subdirectory names: - `bin/` — executable scripts and tools - `cmd/` — Go command entrypoints - `configs/` — configuration templates and examples @@ -126,8 +121,8 @@ Version: 2026-02-22 - `static/` — static assets (images, fonts, etc.) - `web/` — web frontend source -- When setting up a new repo, files from the `prompts` repo may be used - as templates. Fetch them from +- When setting up a new repo, files from the `prompts` repo may be used as + templates. Fetch them from `https://git.eeqj.de/sneak/prompts/raw/branch/main/`. - New repos must contain at minimum: diff --git a/docs/EXISTING_REPO_CHECKLIST.md b/docs/EXISTING_REPO_CHECKLIST.md index 812b43e..856ec12 100644 --- a/docs/EXISTING_REPO_CHECKLIST.md +++ b/docs/EXISTING_REPO_CHECKLIST.md @@ -1,29 +1,26 @@ # Existing Repo Checklist -Use this checklist when beginning work in a repo that may not yet -conform to our +Use this checklist when beginning work in a repo that may not yet conform to our [development policies](https://git.eeqj.de/sneak/prompts/raw/branch/main/REPO_POLICIES.md). -Work on a feature branch. Check each item and fix any gaps before -proceeding with your task. +Work on a feature branch. Check each item and fix any gaps before proceeding +with your task. ## Required Files -- [ ] `README.md` exists with all required sections (Description, - Getting Started, Rationale, Design, TODO, License, Author) +- [ ] `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 with the [authoritative source](https://git.eeqj.de/sneak/prompts/raw/branch/main/REPO_POLICIES.md) -- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, - secrets) — fetch from - `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` +- [ ] `.gitignore` is comprehensive (OS, editor, language artifacts, secrets) — + fetch from `https://git.eeqj.de/sneak/prompts/raw/branch/main/.gitignore` if missing - [ ] `.editorconfig` exists - [ ] `Dockerfile` and `.dockerignore` exist - [ ] Language-specific config: - [ ] Go: `go.mod`, `go.sum`, `.golangci.yml` - - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, - `.prettierignore` + - [ ] JS: `package.json`, `yarn.lock`, `.prettierrc`, `.prettierignore` - [ ] Python: `pyproject.toml` - [ ] Docs/writing: `.prettierrc`, `.prettierignore` @@ -31,36 +28,32 @@ proceeding with your task. - [ ] `Makefile` exists in root — reference the [model Makefile](https://git.eeqj.de/sneak/prompts/raw/branch/main/Makefile) -- [ ] Has targets: `test`, `lint`, `fmt`, `fmt-check`, `check`, - `docker`, `hooks` +- [ ] 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 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) +- [ ] 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 +- [ ] 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 +- [ ] Files organized into canonical subdirectories (`bin/`, `cmd/`, `docs/`, + `internal/`, `static/`, etc.) +- [ ] Go migrations in `internal/db/migrations/` and embedded in binary ## Final diff --git a/docs/NEW_REPO_CHECKLIST.md b/docs/NEW_REPO_CHECKLIST.md index 2f48220..06ec72a 100644 --- a/docs/NEW_REPO_CHECKLIST.md +++ b/docs/NEW_REPO_CHECKLIST.md @@ -1,7 +1,7 @@ # New Repo Checklist -Use this checklist when creating a new repository from scratch. Follow -the steps in order. Full policies are at: +Use this checklist when creating a new repository from scratch. Follow the steps +in order. Full policies are at: `https://git.eeqj.de/sneak/prompts/raw/branch/main/REPO_POLICIES.md` Template files can be fetched from: @@ -30,11 +30,11 @@ Template files can be fetched from: ### Fetch Template Files -- [ ] `.gitignore` — fetch from prompts repo, extend for - language-specific artifacts +- [ ] `.gitignore` — fetch from prompts repo, extend for language-specific + artifacts - [ ] `.editorconfig` — fetch from prompts repo -- [ ] `Makefile` — fetch from prompts repo, adapt targets for the - project's language and tools +- [ ] `Makefile` — fetch from prompts repo, adapt targets for the project's + language and tools - [ ] For JS/docs repos: `.prettierrc`, `.prettierignore` ### Create Project Files @@ -46,8 +46,8 @@ Template files can be fetched from: - Non-server: brings up dev environment and runs `make check` - Image pinned by sha256 hash with version/date comment - [ ] Language-specific: - - [ ] Go: `go mod init sneak.berlin/go/`, `.golangci.yml` - (copy from `~/dev/upaas/.golangci.yml`) + - [ ] Go: `go mod init sneak.berlin/go/`, `.golangci.yml` (copy from + `~/dev/upaas/.golangci.yml`) - [ ] JS: `yarn init`, `yarn add --dev prettier` - [ ] Python: `pyproject.toml` @@ -57,8 +57,7 @@ Template files can be fetched from: - [ ] `make lint` — runs linter - [ ] `make fmt` — formats code (writes) - [ ] `make fmt-check` — checks formatting (read-only) -- [ ] `make check` — prereqs: `test`, `lint`, `fmt-check`; must not - modify files +- [ ] `make check` — prereqs: `test`, `lint`, `fmt-check`; must not modify files - [ ] `make docker` — builds Docker image - [ ] `make hooks` — installs pre-commit hook