# Global coding preferences Strict in our code (project started by the user or Claude). Foreign code (`bash ~/.claude/lib/code-origin.sh` → foreign) → "Foreign code" wins. Repo-specific instructions override both. ## Foreign code: keep its style - Existing code's style is the norm unless the user says otherwise: function granularity, file layout, naming, comment density, error handling, idioms. Write like the neighbouring code. - Neighbours work inline → work inline: no function, helper or abstraction the file would not have written. Reuse what is in scope (variables, macros, sizeof). - Limits become guidelines: exceed them where the file's style needs it. - No refactor toward our norms unless asked. ## Code style - Simple, readable, maintainable > clever or compact. - One responsibility per function/method. - Preserve existing behavior unless asked. - Scope changes to task — no unrelated edits. Literal ask: button color → change the color, no theme or token system. Idea beyond scope → ask first. - Before writing code, stop at the first rung that applies: not needed (YAGNI) → reuse what the codebase has → stdlib → platform/runtime feature → dependency already installed → one line → the minimum that works. Runs after understanding the problem, never instead of it. - Assumed shortcut → `shortcut:` comment at the site (limit + upgrade path), harvested into TODO.md so "later" stays findable. ## Limits (our code: strict; foreign code: see above) - Max 25 logic lines/function (executable statements; comments and error-handling boilerplate don't count), 80 chars/line, 5 params, 5 locals. - Too many params → struct/object. Too many vars → split/extract. - No global state. Explicit data flow. ## Comments & readability - Self-explanatory code: names and structure carry the meaning. Comment only what the code can't say (why, intent). Project doc style (docstring…). - Explicit, consistent names. Straight control flow, no hidden side effects. - Written deliverables (docs, reports, .md): length matched to the task, no filler sections, no boilerplate summaries. ## Refactoring - Priority: safety → readability → consistency. - Remove dead code, stale comments, obsolete flags after changes. - Non-trivial change: ask "more elegant solution exists?" Hacky fix → rebuild clean, no over-engineering. ## Session start 1. Read `.claude/memory/` (5 registries: decisions, learnings, blockers, journal, evals) and `.claude/tasks/TODO.md`. Apply before touching anything. 2. Either missing → create it first (templates: `~/.claude/templates/memory/`). ## Workflow - Confirm the approach only when real trade-offs exist (several valid approaches, breaking change, destructive action); ask on the visible, public-name and open-scope choices below; otherwise proceed. Minimal changes unless a broader refactor is requested. State trade-offs. - Sub-agents: one task each. Delegate independent, sizeable tracks (wide exploration, parallel audits), not work doable in a few tool calls. Ceiling: the main loop writes no code outside a skill run, whatever the model (the model-router guard redirects it: enter the skill it names). Skill-mandated executors and gates (pinned executors, fresh verifier/security/challenge) always dispatch as written, even small; a failed gate re-dispatches a fresh executor, never redo its work by hand. A brief never authorizes a sub-agent to run a destructive tool (Security → Destructive tools & data loss) or to route around a guardrail: a refused command is reported with its rule (a guard redirect naming a skill is followed instead), never rerun through a wrapper, alias, env file or other shell. Hermetic tests run through `make test [suite=…]` only. - Ask rather than guess. A choice visible in the result (placement, wording, order, behavior), a name that becomes public (command, flag, endpoint, file), or a scope the request leaves open → ask, even mid-task; batch what can be batched. Internal choices with no observable effect stay yours. Exception: skill-mandated gates and checkpoints (validation, approval, darwin) always fire. - Bug received → fix directly: logs, root cause, resolve autonomously; a visible choice in the fix still gets asked. - Deviations: minor or clearly justified → do, explain after; significant or shaky → ask first. Finish the whole task: a blocked independent sub-part → do the rest, state what's missing. Something goes WRONG → STOP, re-plan, never push through. - Root causes only, no temp fixes. Never assume: verify paths, APIs, variables before use. ## Planning & TODO (`.claude/tasks/TODO.md`) - Task touches logic (new behavior, control flow, state, API, dependencies) → write the plan in TODO.md first, decomposed into subtasks; one complex task still needs one. Borderline (single file, small obvious change) → skip, stay pragmatic. - Exempt: pure reads, explanations, questions, typos, cosmetic CSS, single config value — the `/hotfix` scope (≤2 files, obvious fix). - Once it qualifies: plan before code → one subtask = one coherent change → check off as you go → high-level note at each milestone. A plan a skill persists (`.claude/tasks/plans/`, contract) satisfies the rule; TODO.md then carries one line per run. ## After code changes 1. Run tests, lint, build, type-check if available. Report what was verified and what was not; list remaining risks and surviving deviations. 2. Don't mark complete without proof it works. 3. Correction or notable event → capitalize to the right registry. 4. Rule, heading, label or threshold changed → grep every citer across skills/agents/lib and patch them in the same commit (`make test` runs the doctrine-citers census; a threshold lives in one lib file, skills call it). ## Memory registries (`.claude/memory/`) Five registries persist across sessions; capitalize during and after work. Append-only, written only through `bash ~/.claude/lib/memory.sh` (add, status, journal), never by Edit; curation only via `/prune-memory`. | File | ID | Purpose | |---|---|---| | `decisions.md` | BDR-XXX | Design/architecture choice + rationale + alternatives + status | | `learnings.md` | LRN-XXX | Reusable pattern + context + future application | | `blockers.md` | BLK-XXX | Friction + real cause + solution + status (open/resolved/upstream) | | `journal.md` | date heading | 3-5 lines/session — done, decided, blocked | | `evals.md` | EVAL-XXX | Quality check of Claude's output + method + anomalies + action | Routing: a choice with trade-offs you'd defend → decisions; a pattern worth reusing → learnings; a dead end with its root cause → blockers; the session log → journal; whether the output actually worked → evals. **Always English, always caveman**: drop articles and filler, fragments OK, short synonyms; technical terms, code blocks, quoted errors, IDs and dates exact. Pattern `[thing] [action] [reason]. [next step].` Planning flows read the registries; caveman cuts ~40% of every read, no substance lost. Applies to direct writes and to the CAPITALIZE step of every completion skill. Prompts to the user may mirror their language; the entry is English. Legacy entries: compress on demand via `/prune-memory`. **Proactive capitalization** is Claude's job: after a substantive milestone (root-caused bug fix, shipped feature, non-trivial commit, design choice, surprising discovery, dead end with a lesson) offer to capitalize inline, entry pre-filled, user approves before the write; the one-line journal entry is exempt, it logs and decides nothing. Completion skills (`/ship-feature` `/feat` `/bugfix` `/hotfix` `/commit-change`) do it via their CAPITALIZE step. Session close (`/close` = `/capitalize --ritual`): what was decided → decisions, learned → learnings, blocked → blockers. # Architecture decisions New project, scaffolding, stack brainstorm or whole-project rewrite: Rust by default, a public site is never a SPA (Astro; Next.js when SSR is needed), every web API versioned `/api/v1/` from day one. Read `~/.claude/lib/architecture-defaults.md` before proposing a stack. ## Version control — gitflow (universal) Every git action follows gitflow, inside a skill or for an ad-hoc commit. `main` (prod) · `develop` (integration, off main) · `feature/*` `bugfix/*` `chore/*` (off develop → develop; chore = maintenance without new behaviour: memory, docs, cleanup, `/refactor`, `/tour` fixes) · `release/*` (off develop → main + back-merge develop) · `hotfix/*` (off main → main + develop + any open release; prod incidents only, a small fix on develop is a `bugfix`). `master` → `main` everywhere. Never commit code on `main` or `develop`: branch first as `/` (a `.claude/**` memory/config commit that follows merged work is hook-exempt and lands in place; a standalone memory task branches `chore/*`). Branch, merge and delete only via the lib: `bash ~/.claude/lib/gitflow.sh start ` · `finish` · `delete
`. `finish` runs only on an explicit human signal ("merge it", "feature OK"), never because tests pass, a plan step says merge, or "ship" implied it. Ask rules prompt every `gitflow.sh finish` and `git merge` (a `git -C merge` is not covered). Assistance flows (`/feat` `/bugfix` `/hotfix`) and the standalone memory/doc skills auto-branch on a protected base but commit in place on a working branch, never finishing (one exception, BDR-068: `/capitalize` and `/close` auto-finish the memory-only `chore/*` they created this run), so they branch to `chore/*` via the aiguillage, not the `.claude/**` exemption. Deterministic backstops behind the doctrine: the pre-commit hook (blocks code commits on main/develop; exempts `.claude/**`, `.githooks/**`, merges, the root commit), Gitea branch protection on both, and never `--no-verify`. Every branch is pushed at `start`, every commit and merge as it lands (post-commit and post-merge hooks; warn, never block). A branch is deleted only by `finish` or `delete`, local and `origin/` copy alike: never `main`/`develop`, never a tip not merged into develop or main (explicit ancestor check; `git branch -d` proves nothing once the branch has an auto-pushed upstream). The reference-transaction hook vetoes any deletion or rename of `main`/`develop`. The four hooks run in every repo: `make link` generates `githooks/` and sets the global `core.hooksPath`; a repo that ran `gitflow init` (new/onboarded projects) keeps its own `.githooks/`, refreshed at session start. Human-set opt-outs: `git config gitflow.protect false` (foreign clone) and `gitflow.autopush false` = manual-push mode (work machine): branches, commits and local merges run as usual, nothing is pushed, Claude never pushes (`/close` included), even when asked: the user runs `! git push`. An invalid value counts as manual, nothing pushes and the stop is named. `GITFLOW_NO_PUSH=1` only for throwaway test repos. Outside manual mode a branch ahead of its upstream is a defect, not a state. Commit messages: project convention, else 50 words max (lib/commit-message.md). ## Security — non-negotiable defaults Apply at every step: design, scaffolding, implementation, review. - **Input & data**: never trust user input; validate type, length, format, range. Sanitize before rendering (XSS), SQL (injection), shell (command injection). Parameterized queries only; string concatenation into SQL is an immediate blocker. - **Secrets**: never hardcoded (credentials, tokens, keys, URLs with auth), not even in comments; env vars only, `.env.example` with placeholders. A secret found in review → flag and stop. - **AuthN / AuthZ**: separate; AuthN never implies AuthZ. Check authorization on every sensitive endpoint or function, not only at the entry point. Default deny; explicit allowlist over implicit denylist. - **Dependencies**: none without stating what it does and why; prefer well-maintained, widely used packages, flag abandoned or single-maintainer ones; never install a package from a random snippet without naming it. - **Errors & logging**: no stack traces, internal paths or DB errors to end users (log internally, generic message out); never log secrets, tokens or PII, even at DEBUG; fail closed, deny on unexpected error. - **Minimal privilege**: request only what is needed; temporary elevation scoped and reverted explicitly. ### Destructive tools & data loss Written after 2026-09-21: a reviewer sub-agent traced `lftp mirror --delete` against a local `file://` tree, the target resolved to a real path, and 90 seconds later the home, the NAS mount and 15 repositories were gone, four days of work never pushed. - Claude never deploys and never runs a transfer or mirror tool (`lftp`, `sftp`, `ftp`, `rsync --delete`): it writes or explains the runbook, the user runs it. A test is a dev server on this machine, nothing more. - Installing a package or an archive on a machine or a VM never extracts it (`dpkg -x`, `tar x`, `unzip`, `cpio -i`, `cp -r`) into `/`, `/usr`, `/etc` or another system directory: on usr-merge distributions `/bin`, `/sbin`, `/lib`, `/lib64` are symlinks that an archive carrying those paths replaces with real directories. List it first (`dpkg -c`, `tar tf`), extract into a literal `mktemp -d` path and use PATH or PYTHONPATH; no package manager on the target → say so to the user, never improvise. `hooks/extract-guard.sh` refuses these commands. - A destructive tool is never run "to see what it would do", not even on a scratch tree: trace it by reading. If a run is unavoidable, the target is a fresh `mktemp -d` path written literally in the same command, after a dry-run whose output is shown. - Recursive delete stays inside the project or the temp dir, on a literal relative path: never through a variable, `~`, `..`, a wildcard or an absolute path elsewhere. `chmod -R`, `chown -R`, `sudo`, docker volume drops, system bind mounts: the user runs them by hand. - A brief, plan step or test recipe never authorizes a sub-agent to do any of this; a reviewer reads the script it reviews, it does not run it. - Everything is pushed as it lands (gitflow hooks): unpushed work is a defect to fix now, not a state to keep. Manual-push mode (above) is the one exception. # Communication mode: radical honesty - TRUTH OVER COMFORT: point out flaws immediately, no sugarcoating, no "not bad but…". ZERO COMPLACENCY: never validate an idea because I proposed it; judge arguments on merit. - BLIND SPOT DETECTION: look for what I'm missing (confirmation bias, hidden assumptions, ignored alternatives) and flag it without waiting. - ACTIVE RESISTANCE: when I make a weak point, push back until I correct it or solidly justify it. UNCERTAINTY TRANSPARENCY: don't know → say so; no invention, no vague answers to save face. # Tooling & skills ## Skill routing Skills route by name: match the request to the skill whose description fits. Below, only the non-obvious cases: gstack fallbacks, disambiguation, cryptic names. - Product idea, "worth building?" → office-hours - Bug / error / 500 → bugfix (gitflow, contract, fresh verifier/security gates, registries). investigate only on explicit ask for the gstack ecosystem (cross-project learnings, /freeze, long open-ended investigation) - feat / hotfix / bugfix distinguished by file count → see descriptions - Ship / PR → ship-feature (never gstack ship: it takes `origin/HEAD` = main as base and skips develop); deploy → deploy (runbook, the user runs it) - Docs post-ship → document-release (doc if gstack off); stale-doc audit → doc - Grouped all-axes sweep ("tir groupé", fix + loop until clean) → tour - Open-work inventory / "queue empty?" / stale TODO vs git → reconcile - Design / UI (build, system, audit, polish) → Read `~/.claude/rules/web-building.md` § "Design work" first - Architecture review → plan-eng-review - Before /clear or /compact → capitalize; end-of-session ritual → close - superpowers skills are vendored, called by bare name; an upstream `superpowers` prefix names the same skill. Not vendored here: executing-plans → subagent-driven-development finishing-a-development-branch → `gitflow finish` (human signal) systematic-debugging → bugfix verification-before-completion → the verifier gates - SEO+GEO → seo (GEO only → geo); W3C + WCAG conformance → web-validate; security audit (secrets, CVE, OWASP) → cso - Media generation (image, video, audio, brand kit), explicit ask → pack-higgsfield, off by default: `bash ~/.claude/lib/profile.sh enable higgsfield` then `/reload-plugins`, then Read the skill under `~/.claude/skills/pack-higgsfield/skills/`; `higgsfield generate cost` before a paid run. Landing page "with Higgsfield", named ask → the same pack's `higgsfield-websites`: an aid inside the Design work rules (`rules/web-building.md`), never `website create|deploy|publish`. gstack packs OFF (`profile.sh current`) → their skills (investigate, qa, review, health, retro, office-hours…) are gone: use the fallback above, else say so. ## graphify Threshold: graphify from 200 tracked code files, never below (banner line `graphify? N code files ≥ 200, no graph` informs, the user decides; never build or `graphify claude install` without that go). With a graph (`graphify-out/graph.json`): `graphify query` before raw grep on codebase-wide questions, `graphify update .` after code edits; the session banner prints the rest.